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.
| Name | In | Type | Description |
|---|---|---|---|
pageToken | query | string | A |
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. |
| 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.
| 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
| 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.
| 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. |
| 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.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
| 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.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
pageToken | query | string | A |
pageSize | query | integer (int64) | Revisions per page: 100 when absent, at most 500. More is coerced to it. |
| 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.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
Request body, application/json: RevisionCreate
| 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.
| 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. |
| 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.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
Request body, application/json: CompactRequest
| 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.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
Request body, application/json: AppendUpdates
| 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 |