Skip to content

API reference: schemas

Account

Fields
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 email once verified.

subscription (required) SubscriptionInfo
tier (required) Tier

Server-computed.

Clients must not re-derive it from subscription.

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.

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

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

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

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

Fields
Name Type Description
discoverableByEmail boolean

Opt into email discovery for sharing.

It cannot be removed.

email string or null

A new address waits in pendingEmail until verified.

The current one, resubmitted, withdraws it, and null removes both.

handle string or null

null removes the handle.

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.

Fields
Name Type Description
mine (required) boolean
theirs (required) boolean

AppStoreNotification

An App Store Server Notification, version 2, as Apple posts it.

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

Fields
Name Type Description
signedTransaction (required) string

The transaction’s JWS (jwsRepresentation in StoreKit), signed by the App Store.

AppendUpdates

Appends encrypted Yjs updates to a note.

Fields
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 stale-key.

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.

Fields
Name Type Description
identifier (required) string

Handle or email address.

BackRequest

Backing an idea already on the board.

Fields
Name Type Description
emailUpdates (required) boolean

As for a new idea: the address goes with the account’s first idea only.

BlockedPeople

Fields
Name Type Description
people (required) array of BlockedPerson

Newest first.

BlockedPerson

Someone the account blocked.

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

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

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

Fields
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 pageToken for the next older page.

Empty when none remain.

BridgeKey

The bridge key as one member holds it, named by its own fingerprint.

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

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

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

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

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

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

Fields
Name Type Description
bridgeKeys (required) array of BridgeSealed

BridgeSend

Fields
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

Fields
Name Type Description
changes (required) array of NoteChange
nextPageToken (required) string

Pass as pageToken for the next page.

Empty on the last page of this listing.

nextSyncToken string

On the last page only: the non-expiring sync watermark, to pass as pageToken later.

CheckoutRequest

Starts a Stripe Checkout session, which the page completes with Stripe.js.

Stripe picks the currency from the buyer’s location.

Fields
Name Type Description
plan (required) Plan

CheckoutSession

A Checkout session for the page’s payment dialog to complete with Stripe.js.

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

Fields
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 stale-key.

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.

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

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

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

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

Fields
Name Type Description
claimerProof string

The claimer’s QR proof, verified by the sealer, present from offered on.

claimerPubKey string

The claimer’s ephemeral public key, present from offered on.

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

Fields
Name Type Description
token (required) string

EndedCompanionship

The caller’s last companionship, ended in the last 14 days, so each app tells of it.

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

Fields
Name Type Description
handle (required) string
options (required) object

Enrolment

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

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

Fields
Name Type Description
ticket (required) string

FeedbackQuota

Feedback usage against the rolling-year allowance.

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

Fields
Name Type Description
seq (required) integer (int64)

The transmission’s seq.

FeedbackRequest

A feedback message for Mission Control, or a report of a bridge transmission.

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

Fields
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

open, planned, started, completed, declined, duplicate or deleted.

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.

Fields
Name Type Description
limit (required) integer (int64)
used (required) integer (int64)

IdeaRequest

A new idea for the board.

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

Fields
Name Type Description
allowance (required) IdeaAllowance
boardUrl (required) string
emailUpdates (required) EmailUpdates
enabled (required) boolean

Whether this server offers ideas. When not, ideas is what was shared before.

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

Fields
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 header:<name> or query:<name>.

Invitation

A pending invitation, sent by the caller or to them.

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

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

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

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

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

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

Fields
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, HH:MM, 20:00 unless set.

timeZone (required) string

An IANA time zone, as Europe/London, in which time is read.

JourneyStart

The day a journey starts, on the calendar of the one starting it.

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

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

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

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

Fields
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 epochId.

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.

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

Fields
Name Type Description
role (required) GrantRole

The caller’s access level for this connection.

ticket (required) string

LoginRequest

Password sign-in request.

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

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

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

Fields
Name Type Description
members (required) array of MemberInfo
nextPageToken (required) string

MembersUpdate

Replaces a note’s membership set (owner only).

Fields
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 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 ownerWrappedCek.

Money

An amount in minor units of a lowercase ISO 4217 currency.

Fields
Name Type Description
amount (required) integer (int64)
currency (required) string

NoteChange

One note’s state within a delta-sync response.

Fields
Name Type Description
deleted (required) boolean
id (required) string (uuid)
keyStatement KeyStatement

The owner’s signed statement of the key wrappedCek holds.

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.

revoked accompanies deleted.

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 version: every one newer than the snapshot, or on an incremental page only those from the first the caller’s last pull may have missed.

A caller holding less than version minus their count reads the note.

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.

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

Fields
Name Type Description
epochId (required) string

Base64 fingerprint of the rotated content key.

NoteRef

Server-assigned note coordinates after a mutation.

Fields
Name Type Description
id (required) string (uuid)
seq (required) integer (int64)
version (required) integer (int64)

PasskeyList

The account’s enrolled devices, newest first.

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

SessionResponse

PasskeyState

What this account’s authenticators amount to.

Fields
Name Type Description
offerEnrolment (required) boolean

Whether to offer enrolling one.

Server-computed.

PasskeySummary

One enrolled device.

Fields
Name Type Description
createdAt (required) string (date-time)
id (required) string

The credential id, url-safe base64 as navigator.credentials spells it.

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.

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

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

Fields
Name Type Description
amounts (required) map of integer (int64)

Minor-unit amount per lowercase ISO 4217 code, for example {"eur": 400}.

plan (required) Plan

PriceList

Fields
Name Type Description
nextPageToken (required) string
prices (required) array of PlanPrice

Problem

RFC 9457 problem details payload.

Fields
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 validation problem.

status (required) integer (int32)

HTTP status code.

title (required) string

Short summary of the problem type.

For about:blank, the status phrase.

type string

Problem type URI, which resolves to its documentation.

Absent means about:blank.

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.

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

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

Fields
Name Type Description
authKey (required) string

Base64 client-derived auth key (never the password).

identifier string

A handle.

An email address signs up through sendSignUpLink and its token instead.

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.

Fields
Name Type Description
epochId (required) string

Base64 fingerprint of the new key, as PUT /v1/notes/{id}/key committed it.

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

Fields
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 baseRevision.

RevisionInfo

Revision descriptor.

Payloads are fetched individually.

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

Fields
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

Fields
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 baseRevision.

Role

A member’s access level on a note.

Revoked marks a former member’s tombstone.

one of "owner", "editor", "viewer", "revoked"

SessionResponse

Fields
Name Type Description
account (required) Account
keys (required) KeyMaterial
token (required) string

SignInChallenge

A sign-in challenge and its handle.

Fields
Name Type Description
handle (required) string
options (required) object

SignInFinish

Fields
Name Type Description
credential (required) object
handle (required) string

SignUpLinkRequest

The address a sign-up link is sent to.

Fields
Name Type Description
email (required) string

SimilarIdea

An idea already on the board that a new one may repeat.

Fields
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

Fields
Name Type Description
ideas (required) array of SimilarIdea

SubscriptionInfo

Subscription state mirrored from Stripe.

Fields
Name Type Description
cancelAtPeriodEnd (required) boolean

True when an auto-renewing subscription ends at currentPeriodEnd.

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.

Fields
Name Type Description
cancelAtPeriodEnd (required) boolean

TheirIdea

Someone else’s idea, by its number on the board.

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

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

Fields
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

Fields
Name Type Description
url (required) string

Usage

Account storage consumption against the tier’s aggregate ceiling.

Fields
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, maxAccountBytes then being Orbit’s.

Withdrawal

A withdrawal from Orbit: ended at once, its payment refunded in full.

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