RESTful Open Annotation API specification

View the Project on GitHub


Data model
OA context
Core API

API Extensions

The following features may optionally be supported by implementations of the API.


For large collections, the server may respond with only part of the collection in response to a GET collection request. If it does so, the server must provide URLs for other parts as part of the collection, using standard link relations in the top level of the response.

Example request:

curl -i

Example response:

HTTP/1.0 200 OK
Content-Type: application/ld+json

  "@context": ...
  "@id": "/annotations/",
  "generatedAt": "2012-04-09",
  "start": "/annotations",
  "next":  "/annotations?page=2"
  "last":  "/annotations?page=49402",

Content negotiation

All conformant implementations must support JSON-LD with the MIME type application/ld+json. RESTful Open Annotation stores may also support other formats through standard content negotiation. Namely, if the client specifies preference for one of the following in an Accept header, the store may respond with:

(Conversion from JSON-LD to other RDF serializations is supported by the many libraries available e.g. from

Suggested extensions

The following extensions have been suggested but no specification has yet been provided.