Skip to content

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.

Responses
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.

Parameters
Name In Type Description
If-None-Match (required) header string

Must be *: the key is written once.

Request body, application/json: KeypairUpload

Responses
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 If-None-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

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.

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

Note id.

Request body, application/json: NoteKey

Responses
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.

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

Note id.

Responses
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.

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

Note id.

Responses
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.

Parameters
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

Responses
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.

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

Note id.

Responses
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.

Parameters
Name In Type Description
identifier (required) path string

Recipient handle or email.

Responses
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