Events
GET /v1/events with an account token returns a stream of server-sent events (text/event-stream). The app uses it to show each change at once.
Connect#
GET /v1/events HTTP/1.1
Host: relaydeck.onrender.com
Authorization: Bearer mca_...
Accept: text/event-streamEach event has a name and one line of JSON data.
event: task.updated
data: {"task":{"id":"tsk_01jb2m9x4e7q","key_id":"key_01jb2k3v9d","title":"Add dark mode support","description":"","status":"in_progress","priority":"high","notify":true,"progress":40,"status_note":"Updating the color tokens","source":"agent","created_at":1760112000.412,"updated_at":1760112300.9,"completed_at":null,"seen_at":1760112010.2,"host":"studio-mac"}}The server sends a comment line (: ping) after 20 seconds with no event, so that a proxy does not close the connection.
Event types#
| Event | Data | Sent when |
|---|---|---|
ready |
{"account_id": "acc_..."} |
One time, when the stream opens |
task.created |
{"task": Task} |
A task is made |
task.updated |
{"task": Task} |
A field of a task changes, also seen_at |
task.deleted |
{"task_id": "tsk_...", "key_id": "key_..."} |
A task is deleted, or it expires |
key.created |
{"key": Key} |
A key is made |
key.updated |
{"key": Key} |
The label changes, last_client changes, or last_host changes |
key.deleted |
{"key_id": "key_..."} |
A key is deleted. No event comes for its tasks and its questions. |
question.created |
{"question": Question} |
An agent asks a question |
question.updated |
{"question": Question} |
The status of a question changes |
inbox.updated |
{"key_id": "key_...", "unread": 2} |
The server adds an item to the inbox of a key, or the agent reads items |
account.deleted |
{} |
The account is deleted |
The objects are those of the REST API.
key.updated is not sent for each change of last_used_at or counts. Get the keys again when you need current counts.
Reconnect#
The stream does not replay old events. After each connect, wait for ready, then get the full lists again with GET /v1/keys, GET /v1/tasks, and GET /v1/questions. An event that arrives after ready is newer than those lists.
The server closes the stream in these cases. Connect again after each of them, except the first.
| Case | What the client sees |
|---|---|
| The account is deleted | account.deleted, then the end of the stream |
| The client reads too slowly | The end of the stream |
| The server loses its connection to the store | The end of the stream |
| The server starts again | The end of the stream |
| The account has 16 streams on one server process, and opens one more | The end of the oldest stream |
If the store is not available at the time of the connect, the response is 503. Wait for the seconds in Retry-After, then connect again.