Skip to content

API reference: notes

Encrypted notes and delta sync. Create a note, append updates, compact its snapshot, pull every change since a sync token, read one note whole, keep revisions on Orbit, and delete. Also the ticket that admits the change feed’s WebSocket.

GET /v1/changes

Every accessible note changed after the cursor, with snapshots when asked. Needs a session.

Parameters
Name In Type Description
pageToken query string

A nextPageToken or nextSyncToken from an earlier call. Absent is a full sync.

pageSize query integer (int64)

Notes per page: 100 when absent, at most 500, and at most 4 MiB past the first.

snapshots query boolean

Include snapshots on this page. Defaults to true on a full sync.

Responses
Status Description Body
200

Changed notes.

ChangesResponse application/json
400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
410

Token older than the deleted notes kept

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/changes/tickets

Creates a single-use ticket for one WebSocket on the caller's own change feed. Needs a session.

Responses
Status Description Body
201

Admission ticket.

FeedTicket application/json
401

No valid session token

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/notes

Creates a note from a client-encrypted snapshot, its owner the sole member. Needs a session.

Request body, application/json: NoteCreate

Responses
Status Description Body
201

Note created.

NoteRef application/json
400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
402

Free storage full

Problem application/problem+json
409

Note id already exists or account storage full

Problem application/problem+json
413

Note too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

GET /v1/notes/{id}

One note's full state, for a client that cannot bridge a compaction gap. Needs a session.

Parameters
Name In Type Description
id (required) path string (uuid)

Note id.

If-None-Match header string

Return 304 when the note’s ETag is unchanged.

Responses
Status Description Body
200

Full note state.

NoteChange application/json
304

Note unchanged since the supplied ETag

400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
404

Note not found

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

DELETE /v1/notes/{id}

Deletes a note (owner only, idempotently), tombstoning it for every member. Needs a session.

Parameters
Name In Type Description
id (required) path string (uuid)

Note id.

Responses
Status Description Body
204

Note deleted.

400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
403

Not the owner

Problem application/problem+json
404

Note not found

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

GET /v1/notes/{id}/revisions

Lists revision descriptors within the owner's plan's reach, newest first, a page at a time. Needs a session.

Parameters
Name In Type Description
id (required) path string (uuid)

Note id.

pageToken query string

A nextPageToken from an earlier page. Absent starts at the newest.

pageSize query integer (int64)

Revisions per page: 100 when absent, at most 500. More is coerced to it.

Responses
Status Description Body
200

Revisions, newest first.

RevisionList application/json
400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
404

Note not found

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/notes/{id}/revisions

Stores an encrypted revision snapshot: Orbit keeps every one while the account has room, a free account those of the last `free_history_days` days. Needs a session.

Parameters
Name In Type Description
id (required) path string (uuid)

Note id.

Request body, application/json: RevisionCreate

Responses
Status Description Body
201

Revision stored.

RevisionInfo application/json
400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
403

View-only access

Problem application/problem+json
404

Note not found

Problem application/problem+json
409

Note deleted, sealed under a retired key, revision anchor gone, or account storage full

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

GET /v1/notes/{id}/revisions/{revision}

Returns one revision's encrypted snapshot, within the owner's plan's reach: on a free account one of its window, or the anchor such a revision builds on. Needs a session.

Parameters
Name In Type Description
id (required) path string (uuid)

Note id.

revision (required) path integer (int64)

Revision number.

If-None-Match header string

Return 304 when the revision’s ETag is unchanged.

Responses
Status Description Body
200

Revision payload.

RevisionPayload application/json
304

Revision unchanged (immutable)

400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
404

Note or revision not found

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

PUT /v1/notes/{id}/snapshot

Replaces the snapshot with a compacted or re-encrypted one, pruning covered updates. Needs a session.

Parameters
Name In Type Description
id (required) path string (uuid)

Note id.

Request body, application/json: CompactRequest

Responses
Status Description Body
200

Snapshot compacted.

NoteRef application/json
400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
402

Free storage full

Problem application/problem+json
403

View-only access

Problem application/problem+json
404

Note not found

Problem application/problem+json
409

snapshotVersion out of range, sealed under a retired key, or account storage full

Problem application/problem+json
413

Note too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/notes/{id}/updates

Appends encrypted Yjs updates. Needs a session.

A requestId repeated by the session that sent it answers as the first did.

Parameters
Name In Type Description
id (required) path string (uuid)

Note id.

Request body, application/json: AppendUpdates

Responses
Status Description Body
200

Updates appended.

NoteRef application/json
400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
402

Free storage full

Problem application/problem+json
403

View-only access

Problem application/problem+json
404

Note not found

Problem application/problem+json
409

Note deleted, sealed under a retired key, or account storage full

Problem application/problem+json
413

Note too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json