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:
- Generate yourself an API token on your Hypothesis developer page (you must be logged in to Hypothesis to get to this page).
- 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: - Content-Type – response content type
Status Codes: - 200 OK – no error
search¶
-
GET
/api/search
¶ Search for annotations.
Example request:
GET /api/search?limit=1000&user=gluejar@hypothes.is Host: hypothes.is Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "rows": [ { "consumer": "00000000-0000-0000-0000-000000000000", "created": "2014-01-12T18:36:15.697572+00:00", "id": "LGVKq4E4SKKro1dBBEMwsA", "permissions": { ... }, "references": ["6lkzoOubSOOymDNDIgazqw"], "target": [], "text": "Peut-etre", "updated": "2014-01-12T18:36:15.697588+00:00", "uri": "http://epubjs-reader.appspot.com//moby-dick/OPS/chapter_003.xhtml", "user": "acct:gluejar@hypothes.is" } ], "total": 1 }
Query Parameters: - limit – The maximum number of annotations to return, for example:
/api/search?limit=30
. (Default: 20) - offset – The minimum number of initial annotations to skip. This is
used for pagination. For example if there are 65 annotations matching
our search query and we’re retrieving up to 30 annotations at a time,
then to retrieve the last 5 do:
/api/search?limit=30&offset=60
. (Default: 0) - sort – Specify which field the annotations should be sorted by. For
example to sort annotations by the name of the user that created them,
do:
/api/search?sort=user
(default: updated) - order – Specify which order (ascending or descending) the annotations
should be sorted in. For example to sort annotations in ascending
order of created time (i.e. oldest annotations first) do:
/api/search?sort=created&order=asc
. (Default: desc) - uri – Search for annotations of a particular URI, for example
/api/search?uri=www.example.com
. URI searches will also find annotations of equivalent URIs. For example if the HTML document athttp://www.example.com/document.html
includes a<link rel="canonical" href="http://www.example.com/canonical_document.html">
then annotations ofhttp://www.example.com/canonical_document.html
will also be included in the search results. Other forms of document equivalence that are supported include rel=”alternate” links, DOIs, PDF file IDs, and more. - user – Search for annotations by a particular user. For example
/api/search?user=tim
will find all annotations by users namedtim
at any provider,/api/search?user=tim@hypothes.is
will only find annotations bytim@hypothes.is
. - text – Search for annotations whose body text contains some text,
for example:
/api/search?text=foobar
- any – Search for annotations whose
quote
,tags
,text
,uri.parts
oruser
fields match some query text. For example:/api/search?any=foobar
.
Todo
Document the
document
query parameter.This parameter is treated specially. We’re holding off documenting it for now because upcoming work on document equivalence is likely to change it.
You can also search for any other field that you see in annotations returned by the h API. Visit
/api/search
with no parameters to see some annotations and their fields. For example to search for all annotations with the tag “climatefeedback” do:/api/search?tags=climatefeedback
tag
also works the same as tags.To search for all annotations that user
seanh@hypothes.is
has permission to delete do:/api/search?permissions.delete=acct:seanh@hypothes.is
You can give any query parameter multiple times. For example
/api/search?tags=climate&tags=feedback
will find all annotations that have either tag “climate” or “feedback”.Warning
The
id
field isn’t usable in searches.Searching for an individual annotation by ID:
/api/search?id=AVAqBdTCiSJM1mYBTinl
won’t return any results. To retrieve a single annotation by ID use the read API instead.
Request Headers: - Accept – desired response content type
Response Headers: - Content-Type – response content type
Status Codes: - 200 OK – no error
- 400 Bad Request – errors parsing your query
- limit – The maximum number of annotations to return, for example:
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: - Content-Type – response content type
Status Codes: - 200 OK – no error
- 404 Not Found – annotation with the specified id not found
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: - Accept – desired response content type
- Content-Type – request body content type
- Authorization – the API token
Response Headers: - Content-Type – response content type
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: - 200 OK – no error
- 400 Bad Request – could not create annotation from your request (bad payload)
- 401 Unauthorized – no API token was provided
- 403 Forbidden – API token provided does not convey “create” permissions
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: - Accept – desired response content type
- Content-Type – request body content type
- Authorization – the API token
Response Headers: - Content-Type – response content type
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: - Accept – desired response content type
- Authorization – the API token
Response Headers: - Content-Type – response content type
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