How to use Hypothesis API from R?



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.


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:

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()


By default the package is using, you can modify the host to point to custom Hypothesis instance by specify HYPOTHESIS_API_PATH environment variable.

Sys.setenv(HYPOTHESIS_API_PATH = "")

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


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


# 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")


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.