# How to use Hypothesis API from R?

    library(hypothesis)

## Introduction

This vignette provides an overview and usage examples of the `{hypothesis}` R package, which is a wrapper for the Hypothesis API. The package allows you to interact with the Hypothesis annotation platform programmatically.

## Authentication

Before using the `{hypothesis}` package, you need to obtain an API key from the Hypothesis platform. You can generate an API key by following the instructions:

- Visit the Hypothesis website at https://hypothes.is/ or self-hosted instance.
- Sign in to your account or create a new account if you don’t have one.
- Once you are signed in, click on your account avatar in the top right corner of the page and select “Account details” from the dropdown menu.
- In the account settings page, click on the “Developer” tab.
- Click `Generete your API token`

To set your API key as an environment variable, you can use the Sys.setenv() function:

    Sys.setenv(HYPOTHESIS_API_KEY = "your_api_key")

or set the it in the `.Renviron` file. e.g. `usethis::edit_r_environ()`

## Usage

By default the package is using `https://hypothes.is/api/`, you can modify the host to point to custom Hypothesis instance by specify `HYPOTHESIS_API_PATH` environment variable.

    Sys.setenv(HYPOTHESIS_API_PATH = "https://hypothesis.company.com/api/")

The `{hypothesis}` package provides several functions for interacting with the Hypothesis API. Here, we will demonstrate the usage of some key functions:

    search_annotations()

This function allows you to search for annotations based on various criteria. Here’s an example of how to use it:

    library(hypothesis)

    # Search for annotations with the keyword "R programming"
    # Check default parameters in function docs
    results <- search_annotations(any = "R programming")

    # Print the first 10 annotations
    head(results, 10)

The `annotation()` function allows you to perform actions on individual annotations. Here are some examples:

    # To interact with annotation you need to specify correct annotation id.
    # Fetch annotation details
    annotation_details <- annotation("annotation_id")

    # Update an annotation's text
    updated_annotation <- annotation("annotation_id", action = "update", text = "Updated text")

    # Flag an annotation
    flagged_annotation <- annotation("annotation_id", action = "flag")

The `get_groups()` function retrieves a list of groups from the Hypothesis platform. Here’s an example:

    # Retrieve all groups
    groups <- get_groups(authority = "localhost")

The `group()` function allows you to fetch group details or update group information. Here are some examples:

    # Fetch group details
    group_details <- group("group_id")

    # Update group information
    updated_group <- group("group_id", action = "update", name = "Updated Group Name")

The `get_profile()` function fetches the profile information of the currently-authenticated user. Here’s an example:

    # Fetch profile information
    profile <- get_profile()

    # Print the user's display name
    cat("Display Name:", profile$user_info$display_name, "\n")

## Conclusion

This vignette provided an introduction to the hypothesis R package and demonstrated its usage with the Hypothesis API. You can explore the package further by referring to the package documentation and the official Hypothesis API documentation.