API reference: sharing
Sharing notes between accounts. Each account stores one sharing keypair. The owner resolves a recipient’s public key, wraps the note’s content key to it, and sets the members. A live ticket admits a WebSocket to a note’s relay for editing together.
GET /v1/account/sharing-key
Returns the caller's own keypair, which a device that lost the create race adopts. Needs a session.
| Status | Description | Body |
|---|---|---|
| 200 | Keypair material. | AccountKeys 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 |
PUT /v1/account/sharing-key
Stores the account's sharing and signing keypairs, once: a new sharing key would strand keys wrapped to it, and a new signing key would disown every note key signed with the old one. Needs a session.
| Name | In | Type | Description |
|---|---|---|---|
If-None-Match (required) | header | string | Must be |
Request body, application/json: KeypairUpload
| Status | Description | Body |
|---|---|---|
| 201 | Keypair stored | |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 412 | A keypair already exists | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 428 | Sent without | 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}/key
Commits a rotated key ahead of its reseal: from then every write naming another key is refused, so the reseal `PUT /v1/notes/{id}/members` carries next covers the whole note. Needs a session.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
Request body, application/json: NoteKey
| Status | Description | Body |
|---|---|---|
| 204 | Key committed: writes naming any other are refused. | |
| 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 |
| 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 |
POST /v1/notes/{id}/live-tickets
Creates a single-use ticket admitting one WebSocket to the note's live room. Needs a session.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
| Status | Description | Body |
|---|---|---|
| 201 | Admission ticket. | LiveTicket 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 |
GET /v1/notes/{id}/members
Lists a note's active members, owner first. Needs a session.
Any member may view the roster.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
| Status | Description | Body |
|---|---|---|
| 200 | Members. | MemberList 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 |
PUT /v1/notes/{id}/members
Replaces a note's membership set against the roster as last read (owner only). Needs a session.
Dropped members receive a revocation tombstone. Answers the new roster, tagged.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
If-Match (required) | header | string | The ETag of the members as last read. |
Request body, application/json: MembersUpdate
| Status | Description | Body |
|---|---|---|
| 200 | Membership updated: the members as they now stand. | MemberList application/json |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 402 | Sharing with anyone new, or more, needs Orbit | Problem application/problem+json |
| 403 | Not the owner | Problem application/problem+json |
| 404 | Note not found | Problem application/problem+json |
| 409 | The reseal misses the note’s current version or committed key, the key statement doesn’t follow the note’s last, or account storage full | Problem application/problem+json |
| 412 | The resource changed since the ETag in If-Match was read | Problem application/problem+json |
| 413 | Note too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 428 | The write must state If-Match | 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}/members:leave
Leaves a note shared with the caller, on any plan. Needs a session.
The caller’s membership ends as an owner’s removal ends it: their feeds take the note’s
tombstone, their sockets on it close, and they read and write it no more. The note then owes
its owner a rotation, resealOwed on the owner’s changes, so the key the caller held seals
nothing written after it.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Note id. |
| Status | Description | Body |
|---|---|---|
| 204 | Left. The caller reads and writes the note no more. | |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 403 | The owner, who stays | 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/users/{identifier}/sharing-key
Resolves a handle, or a verified and opted-in email, to its sharing public key. Needs a session.
| Name | In | Type | Description |
|---|---|---|---|
identifier (required) | path | string | Recipient handle or email. |
| Status | Description | Body |
|---|---|---|
| 200 | Public key. | PublicKeyInfo application/json |
| 400 | Not a handle or email | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 404 | No such shareable user | 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 |