Real Time API¶

Warning

This document describes an API that is in the early stages of being documented and refined for public use. Details may change, and your systems may break in the future.

In addition to the HTTP API Hypothesis has a WebSocket-based API that allows developers to receive near real-time notifications of annotation events.

Overview¶

To use the Real Time API, you should open a WebSocket connection to the following endpoint:

wss://hypothes.is/ws

Communication with this endpoint consists of JSON-encoded messages sent from client to server and vice versa.

Authorization¶

Clients that are only interested in receiving notifications about public annotations on a page do not need to authenticate. Clients that want to receive notifications about all updates relevant to a particular user must authenticate.

Server-side clients can authenticate to the Real Time API by providing an access token in an Authorization header:

Authorization: Bearer <token>

Browser-based clients are not able to set this header due to limitations of the the browser’s WebSocket API. Instead they can authenticate by setting an access_token query parameter in the URL when connecting:

var socket = new WebSocket(`wss://hypothes.is/ws?access_token=${token}`)

Server messages¶

Each messages from the server will be either an event or a reply:

event¶: An event is sent to clients as a result of an action taken elsewhere in the system. For example: if an annotation is made which matches one of the client’s subscriptions, the client will receive an event message. All event messages have a type field.
reply¶: A reply is sent in response to a message sent by the client. All replies have an ok field which indicates whether the server successfully processed the client’s message, and a reply_to field which indicates which client message the server is responding to.

Clients should ignore events with types that they do not recognise, as this will allow us to add new events in future without breaking your client.

Note

We will add documentation for specific event types as we upgrade the protocol.

Sending messages¶

All messages sent to the server must have a numeric ID which is unique for the connection. The ID should be sent with the message in the id field. In addition, every message sent to the server must have a valid type field. See below for the different types of message you can send.

`ping`¶

To verify that the connection is still open, clients can (and are encouraged to) send a “ping” message:

{
   "id": 123,
   "type": "ping"
}

The server replies with a pong message:

{
   "ok": true,
   "reply_to": 123,
   "type": "pong"
}

`whoami`¶

Primarily for debugging purposes, you can send the server a “who am I?” message to check whether you have authenticated correctly to the WebSocket.

{
   "id": 123,
   "type": "whoami"
}

The server will respond with a whoyouare message:

{
   "ok": true,
   "reply_to": 123,
   "type": "whoyouare",
   "userid": "acct:joe.bloggs@hypothes.is"
}