API reference: schemas
Account
| Name | Type | Description |
|---|---|---|
discoverableByEmail (required) | boolean | Whether the verified email may resolve this user for sharing. |
email | string | |
emailVerified (required) | boolean | |
handle | string | |
id (required) | string (uuid) | |
passkeys (required) | PasskeyState | |
pendingEmail | string | An address waiting for verification. It replaces |
subscription (required) | SubscriptionInfo | |
tier (required) | Tier | Server-computed. Clients must not re-derive it from |
tipsByEmail (required) | boolean | Whether a consent to tips by email is in force. |
usage (required) | Usage | |
version | integer (int64) | Rises with every change this read shows, so of two reads a client keeps the higher, whichever reached it last. Equal on two reads the clock alone sets apart, as a tier or a storage grace running out. Absent from a server that keeps none. |
AccountDelete
Account deletion request.
The credential is re-verified first.
| Name | Type | Description |
|---|---|---|
currentAuthKey (required) | string | Base64 current auth key (password- or recovery-derived). |
AccountKeys
The account’s own key material, for a device that lacks it.
| Name | Type | Description |
|---|---|---|
publicKey | string | |
signingKey | string | Base64 public signing key (Ed25519, 32 bytes). |
wrappedMasterKey | string | Base64 master key wrapped by the password-derived wrap key. Absent on old accounts. |
wrappedPrivateKey | string | |
wrappedSigningKey | string | Base64 signing seed wrapped by the master key. |
AccountSettings
The account’s settings as its devices sealed them, which the server keeps and never opens.
| Name | Type | Description |
|---|---|---|
sealed | string | Base64 ciphertext sealed under the account key. Absent while the account has written none. |
version (required) | integer (int64) | Rises by one with each write, from 0 before the first. |
AccountSettingsUpdate
The account’s settings sealed anew, replacing those last read.
| Name | Type | Description |
|---|---|---|
sealed (required) | string | Base64 ciphertext sealed under the account key. |
AccountUpdate
A merge patch of the account.
At least one identifier must remain. Unknown members are refused.
| Name | Type | Description |
|---|---|---|
discoverableByEmail | boolean | Opt into email discovery for sharing. It cannot be removed. |
email | string or null | A new address waits in The current one, resubmitted,
withdraws it, and |
handle | string or null |
|
tipsByEmail | boolean | Consent to tips by email, given once the address is verified, or withdrawn. It cannot be removed. |
AnotherYear
Who has chosen another year together, once day 365 is reached.
| Name | Type | Description |
|---|---|---|
mine (required) | boolean | |
theirs (required) | boolean |
AppStoreNotification
An App Store Server Notification, version 2, as Apple posts it.
| Name | Type | Description |
|---|---|---|
signedPayload (required) | string | The notification’s JWS, signed by the App Store. |
AppStoreTransaction
The transaction StoreKit verified, as the app received it.
| Name | Type | Description |
|---|---|---|
signedTransaction (required) | string | The transaction’s JWS ( |
AppendUpdates
Appends encrypted Yjs updates to a note.
| Name | Type | Description |
|---|---|---|
epochId (required) | string | Base64 fingerprint of the key the updates are sealed under. Any key other than
the note’s is refused as |
metadata | string or null | Base64 encrypted metadata digest. Replaces the stored digest. |
requestId | string (uuid) or null | A UUID naming this batch: a repeat from the same session appends nothing and answers as the first did. |
updates (required) | array of string | Base64 encrypted incremental Yjs updates, in application order. |
AuthParams
Identifier lookup request for the combined sign-in/sign-up flow.
| Name | Type | Description |
|---|---|---|
identifier (required) | string | Handle or email address. |
BackRequest
Backing an idea already on the board.
| Name | Type | Description |
|---|---|---|
emailUpdates (required) | boolean | As for a new idea: the address goes with the account’s first idea only. |
BlockedPeople
| Name | Type | Description |
|---|---|---|
people (required) | array of BlockedPerson | Newest first. |
BlockedPerson
Someone the account blocked.
| Name | Type | Description |
|---|---|---|
blockedAt (required) | string (date-time) | |
id (required) | integer (int64) | Their user on the board. |
name (required) | string | Their name, as the board showed it. |
BookFound
A book as the first catalogue that knows it describes it, never a mix of two.
| Name | Type | Description |
|---|---|---|
authors (required) | array of string | As the catalogue names them, in its order. |
isbn13 (required) | string | The ISBN-13, digits only. |
language | string | The book’s language, as the catalogue codes it. |
pageCount | integer (int32) | |
publisher | string | |
source (required) | BookSource | |
subtitle | string | |
title (required) | string | |
year | integer (int32) | The year of this edition. |
BookSource
Where a book’s details came from.
| Name | Type | Description |
|---|---|---|
link (required) | string | The book’s page in the catalogue, which the bookshelf links to with its details. |
provider (required) | Provider | |
updated | string (date) | The day the catalogue last updated its record, where its licence asks the credit to say it: the French National Library’s and Sudoc’s, under the Licence Ouverte. |
volumeId | string | The catalogue’s own id for the book. |
BridgeHistory
One page of bridge history, newest first.
| Name | Type | Description |
|---|---|---|
currentEpoch | string | Fingerprint of the key to speak under: the one most members hold. |
messages (required) | array of BridgeMessage | |
nextPageToken (required) | string | Pass as Empty when none remain. |
BridgeKey
The bridge key as one member holds it, named by its own fingerprint.
| Name | Type | Description |
|---|---|---|
epochId (required) | string | |
wrappedKey (required) | string | Base64 key wrapped to the holder’s sharing public key. |
BridgeKeyList
Every wrap of the bridge key addressed to the caller, newest first.
| Name | Type | Description |
|---|---|---|
keys (required) | array of BridgeKey | |
nextPageToken (required) | string |
BridgeMessage
One transmission on the Orbit command bridge.
body is opaque here and everywhere.
| Name | Type | Description |
|---|---|---|
authorHandle | string | The author’s handle as the server holds it now, absent without one. A client names the author by it, never by what the sealed body says. |
authorId | string (uuid) | Who transmitted, absent once that account is deleted. |
body (required) | string | Base64 sealed body, padded to one fixed width before sealing. |
createdAt (required) | string (date-time) | |
epochId (required) | string | Base64 fingerprint of the key this was sealed under. |
seq (required) | integer (int64) | The bridge’s total order: also the page cursor and the last-seen marker. |
BridgeSeal
Seals the bridge key to one member: the first mint, or letting a newcomer in.
| Name | Type | Description |
|---|---|---|
epochId (required) | string | |
userId (required) | string (uuid) | Who the key is sealed for. The caller, when minting. |
wrappedKey (required) | string |
BridgeSealed
A key now held by a member, as a batch sealed it.
| Name | Type | Description |
|---|---|---|
epochId (required) | string | |
userId (required) | string (uuid) |
BridgeSeals
Seals one key the caller holds to several members at once (AIP-231): all or none.
| Name | Type | Description |
|---|---|---|
requests (required) | array of BridgeSeal | One seal per member, each to someone other than the caller, each under the same key. |
BridgeSealsResult
What a batch sealed, in the order it was asked.
| Name | Type | Description |
|---|---|---|
bridgeKeys (required) | array of BridgeSealed |
BridgeSend
| Name | Type | Description |
|---|---|---|
body (required) | string | Base64 sealed body, exactly the width the character limit implies. |
epochId (required) | string | Base64 fingerprint of the key it was sealed under, one the sender holds. |
ChangesResponse
| Name | Type | Description |
|---|---|---|
changes (required) | array of NoteChange | |
nextPageToken (required) | string | Pass as Empty on the last page of this listing. |
nextSyncToken | string | On the last page only: the non-expiring sync watermark, to pass as |
CheckoutRequest
Starts a Stripe Checkout session, which the page completes with Stripe.js.
Stripe picks the currency from the buyer’s location.
| Name | Type | Description |
|---|---|---|
plan (required) | Plan |
CheckoutSession
A Checkout session for the page’s payment dialog to complete with Stripe.js.
| Name | Type | Description |
|---|---|---|
clientSecret (required) | string | Initialises Stripe.js’s Checkout for this session. |
publishableKey (required) | string | The key Stripe.js is loaded with. |
CompactRequest
Replaces the stored snapshot with a client-compacted one.
| Name | Type | Description |
|---|---|---|
epochId (required) | string | Base64 fingerprint of the key the snapshot is sealed under. Any key other than
the note’s is refused as |
metadata | string | Base64 metadata digest replacing the stored one, sent when the key rotated. |
snapshot (required) | string | Base64 encrypted Yjs full-state update. |
snapshotVersion (required) | integer (int64) | Highest change version incorporated into the snapshot: from the stored snapshot’s version (at least 1) to the note’s current version. |
Companion
The caller’s companionship, seen from the caller’s side.
| Name | Type | Description |
|---|---|---|
anotherYear (required) | AnotherYear | |
handle | string | The other’s handle, absent for an account that has none. |
journey | Journey | The other’s journey, its days written as dates alone, absent until they start one. |
name | string | What to show. The other’s handle, or for an account that has none, its email address. |
nudgedAt | string (date-time) | When the other last nudged the caller, absent if never. |
orbitEndsAt | string (date-time) | When the inviter’s paid Orbit is set to end, ending the companionship with it. Absent while it renews. |
role (required) | CompanionRole | |
since (required) | string (date-time) | When the invitation was accepted. |
until (required) | string (date) | The last day of the companion’s current year. The companionship ends after it, unless both choose another year. |
CompanionRole
The caller’s side of a companionship.
one of "inviter", "companion"
CompanionshipEnd
Why a companionship ended: one of the two ended it, the inviter’s Orbit lapsed at the end
of its paid period, or the year was completed without another.
one of "ended", "lapsed", "completed"
DeviceLinkOffer
The claiming device’s ephemeral key.
The sealing device, not the server, checks the proof.
| Name | Type | Description |
|---|---|---|
claimerPubKey (required) | string | Base64 ephemeral ECDH public key (SPKI). |
proof (required) | string | Base64 HMAC over the offer, keyed by the channel secret from the QR. |
DeviceLinkSeal
The sealing device’s ephemeral public key and the payload sealed to the claimer.
| Name | Type | Description |
|---|---|---|
sealed (required) | string | Base64 sealed transfer payload (nonce || AES-GCM ciphertext). |
sealerPubKey (required) | string | Base64 ephemeral ECDH public key (SPKI). |
DeviceLinkStart
A new device-link handshake and the linked device’s session token.
| Name | Type | Description |
|---|---|---|
expiresAt (required) | string (date-time) | |
id (required) | string (uuid) | |
token (required) | string | Opaque bearer token for the device being linked. |
DeviceLinkStatus
The handshake’s progress, as its owning device reads it.
| Name | Type | Description |
|---|---|---|
claimerProof | string | The claimer’s QR proof, verified by the sealer, present from |
claimerPubKey | string | The claimer’s ephemeral public key, present from |
status (required) | string | pending, offered, sealed, or claimed. |
EmailUpdates
How the account would hear of an idea’s changes by email.
one of "on", "offered", "unavailable"
EmailVerify
| Name | Type | Description |
|---|---|---|
token (required) | string |
EndedCompanionship
The caller’s last companionship, ended in the last 14 days, so each app tells of it.
| Name | Type | Description |
|---|---|---|
endedAt (required) | string (date-time) | |
handle | string | The other’s handle, absent for an account that has none. |
name | string | What to show. The other’s handle, or for an account that has none, its email address. |
reason (required) | CompanionshipEnd |
EnrolChallenge
A challenge and the handle naming its state.
options goes to navigator.credentials.
| Name | Type | Description |
|---|---|---|
handle (required) | string | |
options (required) | object |
Enrolment
| Name | Type | Description |
|---|---|---|
credential (required) | object | |
handle (required) | string | |
label (required) | string | |
wrappedMasterKey (required) | string | Base64 master key wrapped by the secret this credential derives. |
EnrolmentStart
The start of a passkey’s enrolment.
A passkey outlives a password change, so the credential is re-verified first.
| Name | Type | Description |
|---|---|---|
currentAuthKey (required) | string | Base64 current auth key (password- or recovery-derived). |
FeedTicket
A single-use ticket admitting one WebSocket connection to the caller’s change feed.
| Name | Type | Description |
|---|---|---|
ticket (required) | string |
FeedbackQuota
Feedback usage against the rolling-year allowance.
| Name | Type | Description |
|---|---|---|
limit (required) | integer (int64) | Messages allowed per rolling year on the current plan. |
used (required) | integer (int64) | Messages sent within the last 365 days. |
FeedbackReport
A bridge transmission a member reports, by its seq: the server reads its sender and time.
| Name | Type | Description |
|---|---|---|
seq (required) | integer (int64) | The transmission’s |
FeedbackRequest
A feedback message for Mission Control, or a report of a bridge transmission.
| Name | Type | Description |
|---|---|---|
message (required) | string | |
report | FeedbackReport | The transmission the message reports. A report doesn’t count against the yearly allowance, and has a daily cap of its own. |
GrantRole
An access level a note may be shared at: ownership is not transferable.
one of "editor", "viewer"
Idea
One idea the account posted or backed.
| Name | Type | Description |
|---|---|---|
author | Person | Who posted it, absent when the account did. |
mine (required) | boolean | Whether the account posted it, rather than backed it. |
number (required) | integer (int64) | The idea’s number on the board. |
shipped (required) | boolean | Whether it shipped since the account was last told. |
status (required) | string |
|
title (required) | string | |
url (required) | string | The idea’s page on the board. |
IdeaAllowance
Ideas posted in the last 7 days against the weekly allowance.
| Name | Type | Description |
|---|---|---|
limit (required) | integer (int64) | |
used (required) | integer (int64) |
IdeaRequest
A new idea for the board.
| Name | Type | Description |
|---|---|---|
description | string | What it would change, in a few lines. |
emailUpdates (required) | boolean | Sends the account’s verified address with its first idea, so the board emails updates. |
title (required) | string | 10 to 100 characters. |
IdeasView
The account’s ideas and how a new one would be shared.
| Name | Type | Description |
|---|---|---|
allowance (required) | IdeaAllowance | |
boardUrl (required) | string | |
emailUpdates (required) | EmailUpdates | |
enabled (required) | boolean | Whether this server offers ideas. When not, |
ideas (required) | array of Idea | Newest first. |
postedAs (required) | string | The name the board shows on the account’s ideas. |
InvalidMember
One invalid member of a request, located by a JSON Pointer (RFC 6901).
| Name | Type | Description |
|---|---|---|
detail (required) | string | What is wrong with it. |
pointer (required) | string | JSON Pointer to the member within the request body, empty for the whole body; a header or a
query parameter is named instead, as |
Invitation
A pending invitation, sent by the caller or to them.
| Name | Type | Description |
|---|---|---|
expiresAt (required) | string (date-time) | 14 days after it was sent. |
handle | string | The other’s handle, absent for an address or an account that has none. |
id (required) | string (uuid) | |
name (required) | string | What to show. For one sent, the handle or the address it was sent to. For one received, the sender’s handle, or for an account that has none, its email address. |
InvitationRequest
Whom to invite as a companion, by exactly one of a handle or an email address.
| Name | Type | Description |
|---|---|---|
email | string or null | An email address, which may or may not have an account. |
handle | string or null | An account’s handle. |
JournalEvent
One finished journal session, as its device worked it out: its mode and its length’s bucket, and nothing else, so a field more is refused rather than dropped.
| Name | Type | Description |
|---|---|---|
length (required) | JournalLength | |
mode (required) | JournalMode |
JournalLength
How long a finished session ran, by journey.length_minutes: each bucket named by the bound it
starts from, under 2 first.
one of "under-2", "from-2", "from-5", "from-10", "from-20"
JournalMilestone
One milestone a journal reached, the milestone alone, so a field more is refused.
| Name | Type | Description |
|---|---|---|
milestone (required) | JournalMilestoneId |
JournalMilestoneId
A step in a journal’s habit that its device saw reached (spec/journey, The counters): sessions on 2 days of the journal’s 8th week, or writing again within 14 days of 7 quiet days.
one of "week-8-habit", "comeback"
JournalMode
A journal writing mode, by the id spec/journey/modes gives it; a variant counts as its mode.
one of "just-write", "today", "check-in", "good-things", "self-compassion", "reflect", "expressive", "best-self", "bedtime"
Journey
One person’s journey: a year of daily prompts, fixed to the calendar from its first day.
Day n of a year is firstDay plus n - 1 days, its prompt the one for that calendar day.
| Name | Type | Description |
|---|---|---|
firstDay (required) | string (date) | The first day of the current year, on the calendar of the one who started it. |
written (required) | array of string (date) | The days of the current year written, ascending. Progress is their count out of the days so far, and “wrote today” whether today is among them: there are no streaks. |
year (required) | integer (int32) | The year, from 1. |
JourneyEvent
One anonymous journey funnel event, aggregated into a counter.
| Name | Type | Description |
|---|---|---|
journey (required) | JourneyId | |
step (required) | JourneyStep |
JourneyId
One of the eight canonical journeys the platform is measured against.
one of "onboard", "sync", "collaborate", "organise", "export", "upgrade", "link-device", "recover"
JourneyReminder
The daily reminder email, which the web app offers.
| Name | Type | Description |
|---|---|---|
email (required) | boolean | Whether it is sent, off unless turned on, and to a verified address alone. |
time (required) | string | The local time it goes out, |
timeZone (required) | string | An IANA time zone, as |
JourneyStart
The day a journey starts, on the calendar of the one starting it.
| Name | Type | Description |
|---|---|---|
firstDay (required) | string (date) | Today, where the caller is: no more than a day from today on the server’s clock. |
JourneyStep
A moment in a journey funnel: opened it, or carried it through.
one of "start", "complete"
JourneyView
The caller’s journey, their companion and invitations, and the reminder.
| Name | Type | Description |
|---|---|---|
companion | Companion | The companionship, absent while there’s none. |
invitationSent | Invitation | The caller’s pending invitation, absent while there’s none. |
invitationsReceived (required) | array of Invitation | Pending invitations to the caller, oldest first. |
journey | Journey | The caller’s journey, absent until one starts. |
lastEnded | EndedCompanionship | The caller’s last companionship, when it ended in the last 14 days. |
reminder (required) | JourneyReminder | |
remindersPaused (required) | boolean | Whether the reminder emails paused, as the last allowed went unanswered: the app asks once whether to keep them, and setting the reminder ends the pause. |
KdfParams
Whether an identifier has an account, which decides sign-in or sign-up, and if it does, the KDF parameters its keys derive from.
| Name | Type | Description |
|---|---|---|
exists (required) | boolean | |
kdfIterations | integer (int32) | PBKDF2 iteration count. Present when the account exists. |
kdfSalt | string | Base64 KDF salt. Present when the account exists. |
KeyMaterial
Key material a client needs to unlock the account on this device.
| Name | Type | Description |
|---|---|---|
kdfIterations (required) | integer (int32) | |
kdfSalt (required) | string | |
publicKey | string | Base64 sharing public key. Absent until the client generates a keypair. |
recoveryWrappedMasterKey (required) | string | Base64 master key wrapped by the recovery key. |
signingKey | string | Base64 public signing key (Ed25519, 32 bytes), with which the account signs the keys of the notes it owns. Absent until the client generates its keys. |
wrappedMasterKey (required) | string | Base64 master key wrapped by the password-derived wrap key. |
wrappedPrivateKey | string | Base64 sharing private key wrapped by the master key. Absent until set. |
wrappedSigningKey | string | Base64 signing seed wrapped by the master key. Absent until set. |
KeyStatement
A note owner’s signed statement of the key its members hold (spec/formats/crypto, Key
statements): the epoch it opens, the key’s fingerprint, and whom the key is handed to.
The server keeps the latest and checks that it names the note as it stands; only the members check its signature, against the owner’s signing key.
| Name | Type | Description |
|---|---|---|
epoch (required) | integer (int64) | The key’s epoch: 1 for the note’s first key, one more at each rotation. |
epochId (required) | string | Base64 fingerprint of the key, as its |
recipients (required) | array of string (uuid) | Every account the key is handed to, the owner among them, ascending. |
signature (required) | string | Base64 Ed25519 signature of the note’s owner over the statement’s bytes. |
KeypairUpload
The account’s keypairs, uploaded once: the sharing pair and the signing pair together.
| Name | Type | Description |
|---|---|---|
publicKey (required) | string | Base64 sharing public key (ECDH P-256, SPKI). |
signingKey (required) | string | Base64 public signing key: Ed25519, its 32 bytes. |
wrappedPrivateKey (required) | string | Base64 sharing private key (PKCS#8) wrapped by the master key. |
wrappedSigningKey (required) | string | Base64 signing seed wrapped by the master key. |
LiveTicket
A single-use ticket admitting one WebSocket connection to a note’s room.
| Name | Type | Description |
|---|---|---|
role (required) | GrantRole | The caller’s access level for this connection. |
ticket (required) | string |
LoginRequest
Password sign-in request.
| Name | Type | Description |
|---|---|---|
authKey (required) | string | Base64 client-derived auth key. |
identifier (required) | string | Handle or email address. |
MemberInfo
One member of a shared note.
| Name | Type | Description |
|---|---|---|
handle | string | The addressing key, absent for an account that has no handle. |
name | string | What to show: the handle, or for a member without one the label their owner granted them under, to the owner alone. Never the address their account holds. |
role (required) | Role | |
userId (required) | string (uuid) |
MemberInput
A member to grant access to, with the note key wrapped to their public key.
| Name | Type | Description |
|---|---|---|
label | string | The handle or address the owner found this member by, at most 254 characters: kept for a member without a handle, and shown to the owner alone. |
role (required) | GrantRole | |
userId (required) | string (uuid) | |
wrappedCek (required) | string | Base64 note content key wrapped to this member’s public key. |
MemberList
A note’s members, owner first.
One-page lists carry an always-empty nextPageToken.
| Name | Type | Description |
|---|---|---|
members (required) | array of MemberInfo | |
nextPageToken (required) | string |
MembersUpdate
Replaces a note’s membership set (owner only).
| Name | Type | Description |
|---|---|---|
keyStatement (required) | KeyStatement | The owner’s statement of the key the members hold after the change: the note’s current key at its epoch, or on rotation the new key at the next epoch. |
members (required) | array of MemberInput | |
ownerWrappedCek | string | Base64 content key rewrapped for the owner. Present on key rotation, with its |
reseal | Reseal | The note sealed under the rotated key, stored with the new wraps in one step, so no reader is handed a key its content is not sealed under. Present on key rotation, with |
Money
An amount in minor units of a lowercase ISO 4217 currency.
| Name | Type | Description |
|---|---|---|
amount (required) | integer (int64) | |
currency (required) | string |
NoteChange
One note’s state within a delta-sync response.
| Name | Type | Description |
|---|---|---|
deleted (required) | boolean | |
id (required) | string (uuid) | |
keyStatement | KeyStatement | The owner’s signed statement of the key Absent for tombstones. |
memberCount (required) | integer (int64) | Active members including the owner. A count of 1 means unshared. |
metadata | string | Base64 encrypted metadata digest. Absent for tombstones. |
ownerSigningKey | string | Base64 public signing key (Ed25519, 32 bytes) of the note’s owner, which signs its key statements. Absent for tombstones and the caller’s own notes. |
resealOwed (required) | boolean | Whether a member who held the note’s key has left it since its last rotation, so its owner rotates the key. Only ever true for the owner. |
role (required) | Role | The caller’s role on this note.
|
seq (required) | integer (int64) | |
snapshot | string | Base64 Yjs snapshot. Absent for tombstones and incremental pages. |
snapshotVersion (required) | integer (int64) | |
updatedAt (required) | string (date-time) | Last write time, for the tree’s date column and sort. |
updates (required) | array of string | Base64 encrypted updates in order, the last being A caller holding less than |
version (required) | integer (int64) | |
wrappedCek | string | Base64 content key wrapped to the caller. Absent for tombstones. |
NoteCreate
Note creation request.
id is a client-generated UUID.
| Name | Type | Description |
|---|---|---|
epochId (required) | string | Base64 fingerprint of the content key: writes naming another are refused as stale. |
id (required) | string (uuid) | Client-generated note id. |
keyStatement (required) | KeyStatement | The owner’s statement of the note’s first key: epoch 1, to the owner alone. |
metadata (required) | string | Base64 encrypted metadata digest (title and ordered tags). |
snapshot (required) | string | Base64 encrypted Yjs full-state update. |
wrappedCek (required) | string | Base64 note content key wrapped to the owner’s own public key. |
NoteKey
The key a note’s writes must name.
Committed ahead of its reseal, it refuses every write sealed under another, so none lands that the reseal would leave out.
| Name | Type | Description |
|---|---|---|
epochId (required) | string | Base64 fingerprint of the rotated content key. |
NoteRef
Server-assigned note coordinates after a mutation.
| Name | Type | Description |
|---|---|---|
id (required) | string (uuid) | |
seq (required) | integer (int64) | |
version (required) | integer (int64) |
PasskeyList
The account’s enrolled devices, newest first.
| Name | Type | Description |
|---|---|---|
nextPageToken (required) | string | |
passkeys (required) | array of PasskeySummary |
PasskeySession
A session and the key only its authenticator can unwrap: one without the other reads nothing.
PasskeyState
What this account’s authenticators amount to.
| Name | Type | Description |
|---|---|---|
offerEnrolment (required) | boolean | Whether to offer enrolling one. Server-computed. |
PasskeySummary
One enrolled device.
| Name | Type | Description |
|---|---|---|
createdAt (required) | string (date-time) | |
id (required) | string | The credential id, url-safe base64 as |
label (required) | string | |
lastUsedAt | string (date-time) or null |
PasswordChange
Password change.
The KDF salt is fixed for life, since the recovery credential shares it.
| Name | Type | Description |
|---|---|---|
currentAuthKey (required) | string | Base64 current auth key, re-verified before the change. |
newAuthKey (required) | string | |
newWrappedMasterKey (required) | string | Base64 master key wrapped by the new password-derived wrap key. |
Person
Someone on the board, by the board’s user for them.
| Name | Type | Description |
|---|---|---|
id (required) | integer (int64) | Their user on the board. |
name (required) | string | Their name, as the board shows it. |
Plan
Premium purchase option: an auto-renewing monthly or yearly subscription.
one of "monthly", "yearly"
PlanPrice
Catalog price of one plan in every currency it is offered in.
| Name | Type | Description |
|---|---|---|
amounts (required) | map of integer (int64) | Minor-unit amount per lowercase ISO 4217 code, for example |
plan (required) | Plan |
PriceList
| Name | Type | Description |
|---|---|---|
nextPageToken (required) | string | |
prices (required) | array of PlanPrice |
Problem
RFC 9457 problem details payload.
| Name | Type | Description |
|---|---|---|
detail | string | Explanation specific to this occurrence, written to help correct the request. |
errors | array of InvalidMember | The invalid members of the request. Present on a |
status (required) | integer (int32) | HTTP status code. |
title (required) | string | Short summary of the problem type. For |
type | string | Problem type URI, which resolves to its documentation. Absent means |
Provider
A catalogue the bookshelf looks books up in.
one of "google-books", "dnb", "open-library", "k10plus", "swisscovery", "loc", "porbase", "bne", "bnf", "sudoc"
PublicKeyInfo
A user’s sharing public key, resolved by handle or email.
| Name | Type | Description |
|---|---|---|
handle | string | The addressing key, absent for an account created with an email alone. |
name (required) | string | What to show: the handle, or the address the caller resolved it by. |
notifiable (required) | boolean | True when a verified email means this user is emailed once added. |
publicKey (required) | string | Base64 sharing public key. |
userId (required) | string (uuid) |
RecoverRequest
Account recovery sign-in using the recovery key.
| Name | Type | Description |
|---|---|---|
identifier (required) | string | |
recoveryAuthKey (required) | string | Base64 recovery auth key derived from the recovery key. |
RegisterRequest
Account creation request, with exactly one of identifier and signUpToken.
All key material is derived client-side.
| Name | Type | Description |
|---|---|---|
authKey (required) | string | Base64 client-derived auth key (never the password). |
identifier | string | A handle. An email address signs up through |
kdfIterations (required) | integer (int32) | PBKDF2 iteration count chosen by the client. |
kdfSalt (required) | string | Base64 KDF salt generated by the client. |
recoveryAuthKey (required) | string | Base64 client-derived recovery auth key. |
recoveryWrappedMasterKey (required) | string | Base64 master key wrapped by the recovery key. |
signUpToken | string | The token of a sign-up link: the account takes the address it was sent to, verified. |
tipsByEmail (required) | boolean | Consent to tips by email, given on the sign-up by email: never a condition of it. A handle has no address to send them to, so it signs up with false. |
wrappedMasterKey (required) | string | Base64 master key wrapped by the password-derived wrap key. |
Reseal
A note’s whole content resealed under a rotated content key.
| Name | Type | Description |
|---|---|---|
epochId (required) | string | Base64 fingerprint of the new key, as |
metadata (required) | string | Base64 encrypted metadata digest under the new key. |
snapshot (required) | string | Base64 encrypted Yjs full-state update, replacing the snapshot and every update. |
snapshotVersion (required) | integer (int64) | The note’s current version, which the snapshot covers whole. |
RevisionCreate
Stores an encrypted revision snapshot (premium feature).
| Name | Type | Description |
|---|---|---|
baseRevision | integer (int64) or null | Anchor revision this delta applies over. Absent for a full snapshot. |
epochId (required) | string | Fingerprint of the key this revision is sealed under, which must be the note’s. |
snapshot (required) | string | Base64 encrypted Yjs update: a full state, or a delta over |
RevisionInfo
Revision descriptor.
Payloads are fetched individually.
| Name | Type | Description |
|---|---|---|
authorHandle | string | Handle of the member who captured it. Absent once that account is deleted. |
baseRevision | integer (int64) | Anchor this delta applies over. Absent for a full snapshot. |
bytes (required) | integer (int64) | |
createdAt (required) | string (date-time) | |
epochId (required) | string | Fingerprint of the sealing key. |
revision (required) | integer (int64) |
RevisionList
A page of a note’s revision descriptors, newest first.
| Name | Type | Description |
|---|---|---|
nextPageToken (required) | string | Where the next page starts, older than this one’s last. Empty on the last page. |
revisions (required) | array of RevisionInfo |
RevisionPayload
| Name | Type | Description |
|---|---|---|
baseRevision | integer (int64) | Anchor this delta applies over. Absent for a full snapshot. |
revision (required) | integer (int64) | |
snapshot (required) | string | Base64 encrypted Yjs update: a full state, or a delta over |
Role
A member’s access level on a note.
Revoked marks a former member’s tombstone.
one of "owner", "editor", "viewer", "revoked"
SessionResponse
| Name | Type | Description |
|---|---|---|
account (required) | Account | |
keys (required) | KeyMaterial | |
token (required) | string |
SignInChallenge
A sign-in challenge and its handle.
| Name | Type | Description |
|---|---|---|
handle (required) | string | |
options (required) | object |
SignInFinish
| Name | Type | Description |
|---|---|---|
credential (required) | object | |
handle (required) | string |
SignUpLinkRequest
The address a sign-up link is sent to.
| Name | Type | Description |
|---|---|---|
email (required) | string |
SimilarIdea
An idea already on the board that a new one may repeat.
| Name | Type | Description |
|---|---|---|
author | Person | Who posted it, absent when the account did. |
number (required) | integer (int64) | |
status (required) | string | |
title (required) | string | |
url (required) | string | |
votes (required) | integer (int64) | How many have backed it. |
SimilarIdeas
| Name | Type | Description |
|---|---|---|
ideas (required) | array of SimilarIdea |
SubscriptionInfo
Subscription state mirrored from Stripe.
| Name | Type | Description |
|---|---|---|
cancelAtPeriodEnd (required) | boolean | True when an auto-renewing subscription ends at |
currentPeriodEnd | string (date-time) | |
plan | Plan | Absent until a plan is purchased. |
status (required) | string | Stripe’s subscription status verbatim: an open vocabulary Stripe owns. |
withdrawableUntil | string (date-time) | Until when a withdrawal ends it and refunds it in full: 14 days from its start. Absent once that has passed, and for a subscription not live. |
SubscriptionUpdate
Sets whether the subscription cancels at the end of its paid period.
| Name | Type | Description |
|---|---|---|
cancelAtPeriodEnd (required) | boolean |
TheirIdea
Someone else’s idea, by its number on the board.
| Name | Type | Description |
|---|---|---|
idea (required) | integer (int64) |
Tier
The plan in force right now, and what holds the account on it.
one of "free", "subscribed", "appStore", "complimentary", "companion"
Told
The shipped ideas the account has now been told of.
| Name | Type | Description |
|---|---|---|
numbers (required) | array of integer (int64) | At most 100 numbers. |
TourEvent
One anonymous tour-watching event: which tour, which moment, and nothing else.
| Name | Type | Description |
|---|---|---|
event (required) | TourEventKind | |
tour (required) | TourId |
TourEventKind
A moment in the tour-watching funnel: mounted, first played, watched through.
one of "view", "play", "complete"
TourId
A marketing tour, named by the frontend catalogue’s slug.
one of "free-flight", "orbit"
UrlResponse
| Name | Type | Description |
|---|---|---|
url (required) | string |
Usage
Account storage consumption against the tier’s aggregate ceiling.
| Name | Type | Description |
|---|---|---|
accountBytes (required) | integer (int64) | Stored bytes across the account: live notes plus revision snapshots. |
maxAccountBytes (required) | integer (int64) | The tier’s aggregate storage ceiling, the sole storage limit. |
noteCount (required) | integer (int64) | |
storageGraceUntil | string (date-time) | Until when the account keeps Orbit’s storage ceiling after its Orbit ended, and no other Orbit perk. Present only while it does, |
Withdrawal
A withdrawal from Orbit: ended at once, its payment refunded in full.
| Name | Type | Description |
|---|---|---|
refund | Money | What was refunded. Absent when nothing was paid, as with a 100% code. |
subscription (required) | SubscriptionInfo | The subscription as Stripe now holds it: cancelled. |
withdrawnAt (required) | string (date-time) | When it was received, which the acknowledgement by email also states. |