The Hypothesis API

This document details the h application’s public HTTP API. It is targeted at developers interested in integrating functionality from Hypothesis into their own applications.

Authorization

Some of the API URLs documented below require a valid API token. To use these API URLs you should:

  1. Generate yourself an API token on your Hypothesis developer page (you must be logged in to Hypothesis to get to this page).
  2. Put the API token in the Authorization header in your requests to the API.

Example request:

GET /api
Host: hypothes.is
Accept: application/json
Authorization: Bearer 6879-31d62c13b0099456de5379de90f90395

(Replace 6879-31d62c13b0099456de5379de90f90395 with your own API token.)

root

GET /api

API root. Returns hypermedia links to the rest of the API.

Example request:

GET /api
Host: hypothes.is
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "links": {
        "annotation": {
            "create": {
                "desc": "Create a new annotation",
                "method": "POST",
                "url": "https://hypothes.is/api/annotations"
            },
            "delete": {
                "desc": "Delete an annotation",
                "method": "DELETE",
                "url": "https://hypothes.is/api/annotations/:id"
            },
            "read": {
                "desc": "Get an existing annotation",
                "method": "GET",
                "url": "https://hypothes.is/api/annotations/:id"
            },
            "update": {
                "desc": "Update an existing annotation",
                "method": "PUT",
                "url": "https://hypothes.is/api/annotations/:id"
            }
        },
        "search": {
            "desc": "Basic search API",
            "method": "GET",
            "url": "https://hypothes.is/api/search"
        }
    },
    "message": "Annotator Store API"
}
Request Headers:
 
  • Accept – desired response content type
Response Headers:
 
Status Codes:

read

GET /api/annotations/(string: id)

Retrieve a single annotation.

Example request:

GET /api/annotations/utalbWjUaZK5ifydnohjmA
Host: hypothes.is
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "consumer": "00000000-0000-0000-0000-000000000000",
    "created": "2013-08-26T13:31:49.339078+00:00",
    "document": { ... },
    "id": "utalbWjUQZK5ifydnohjmA",
    "permissions": { ... },
    "references": [
        "ZkDZ8ZRXQkiEeG_3r7s1IA",
        "4uUTPORmTN-0y-puAXe_sw"
    ],
    "target": [],
    "text": "Dan, thanks for your team's work ...",
    "updated": "2013-08-26T14:09:14.121339+00:00",
    "uri": "http://example.com/foo",
    "user": "acct:johndoe@example.org"
}
Request Headers:
 
  • Accept – desired response content type
Response Headers:
 
Status Codes:

create

POST /api/annotations

Create a new annotation. Requires a valid API token.

Example request:

POST /api/annotations
Host: hypothes.is
Accept: application/json
Content-Type: application/json;charset=UTF-8
Authorization: Bearer 6879-31d62c1[...]0f90395

{
    "uri": "http://example.com/",
    "user": "acct:joebloggs@example.org",
    "permissions": {
        "read": ["group:__world__"],
        "update": ["acct:joebloggs@example.org"],
        "delete": ["acct:joebloggs@example.org"],
        "admin": ["acct:joebloggs@example.org"]
    },
    "document": { ... },
    "target": [ ... ],
    "tags": [],
    "text": "This is an annotation I made."
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "id": "AUxWM-HasREW1YKAwhil",
    "uri": "http://example.com/",
    "user": "acct:joebloggs@example.org",
    ...
}
Parameters:
  • id – annotation’s unique id
Request Headers:
 
Response Headers:
 
Response JSON Object:
 
  • id (string) – unique id of new annotation
  • created (datetime) – created date of new annotation
  • updated (datetime) – updated date of new annotation (same as created)
Status Codes:

update

PUT /api/annotations/(string: id)

Update the annotation with the given id. Requires a valid API token.

Example request:

PUT /api/annotations/AUxWM-HasREW1YKAwhil
Host: hypothes.is
Accept: application/json
Content-Type: application/json;charset=UTF-8
Authorization: Bearer 6879-31d62c1[...]0f90395

{
    "uri": "http://example.com/foo",
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "id": "AUxWM-HasREW1YKAwhil",
    "updated": "2015-03-26T13:09:42.646509+00:00"
    "uri": "http://example.com/",
    "user": "acct:joebloggs@example.org",
    ...
}
Parameters:
  • id – annotation’s unique id
Request Headers:
 
Response Headers:
 
Response JSON Object:
 
  • updated (datetime) – updated date of annotation
Status Codes:
  • 200 OK – no error
  • 400 Bad Request – could not update annotation from your request (bad payload)
  • 401 Unauthorized – no API token was provided
  • 403 Forbidden – API token provided does not convey “update” permissions for the annotation with the given id
  • 404 Not Found – annotation with the given id was not found

delete

DELETE /api/annotations/(string: id)

Delete the annotation with the given id. Requires a valid API token.

Example request:

DELETE /api/annotations/AUxWM-HasREW1YKAwhil
Host: hypothes.is
Accept: application/json
Authorization: Bearer 6879-31d62c1[...]0f90395

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "deleted": true,
    "id": "AUxWM-HasREW1YKAwhil"
}
Parameters:
  • id – annotation’s unique id
Request Headers:
 
Response Headers:
 
Response JSON Object:
 
  • deleted (boolean) – whether the annotation was deleted
  • id (string) – the unique id of the deleted annotation
Status Codes:
  • 200 OK – no error
  • 401 Unauthorized – no API token was provided
  • 403 Forbidden – API token provided does not convey “update” permissions for the annotation with the given id
  • 404 Not Found – annotation with the given id was not found