API reference
The contract itself is openapi.yaml.
Astro Notes is an end-to-end encrypted, Markdown-only note service. This is the API its web app uses: accounts and sessions, note storage and sync, sharing, billing, and a few supporting services. Bodies are JSON unless an operation names another media type.
End-to-end encryption
The server holds only ciphertext. Notes, their titles and their tags are sealed in the browser before they are sent, and the server never holds a key that opens them.
- Password. The password never leaves the browser. The client stretches it with PBKDF2-SHA-256 over the account’s
kdfSaltandkdfIterations, then splits the result with HKDF into an auth key and a wrap key. The auth key signs in, and the server stores only an Argon2id hash of it. The wrap key stays in the browser. - Master key. A random key, sealed with AES-256-GCM under the wrap key as
wrappedMasterKey, and under the recovery key asrecoveryWrappedMasterKey. The server stores both and can open neither. - Note keys. Each note has its own content key. Its snapshot, updates and metadata are sealed under that key, and the key is wrapped to each member’s sharing public key (ECDH P-256) as
wrappedCek. The sharing private key is stored wrapped by the master key. - Passkeys. Each passkey unwraps its own copy of the master key with its PRF output, which never reaches the server. The server checks only the WebAuthn signature.
Ciphertext members are opaque to the server: it stores, orders and relays them without reading them. When a member is removed, the owner reseals the note under a new content key, named by its fingerprint epochId, and a write that names the retired key is refused as stale-key.
Binary values
Binary members, such as ciphertext, wrapped keys, salts and fingerprints, are standard base64 with padding (RFC 4648, section 4). Passkey credential ids are url-safe base64 without padding, as WebAuthn spells them. Session tokens, tickets and page tokens are opaque strings.
The examples in this reference use placeholders. Each base64 value has the width of the real one and decodes to a short label, never to data or a real key.
Authentication and sessions
Signing in and signing up share one flow. POST /v1/accounts:lookupAuthParams says whether a handle or email address has an account and, if it does, returns the KDF parameters its keys derive from. The client then signs in with POST /v1/sessions, or signs up with POST /v1/accounts: by handle, or by email address through the link that POST /v1/accounts:sendSignUpLink mails. A passkey signs in through POST /v1/sessions:beginPasskey and POST /v1/sessions:finishPasskey, and the recovery key through POST /v1/sessions:recover.
Each of these answers a session: its token, the account, and the key material the client needs to unlock the account on this device. Send the token in the Authorization header as a bearer token on every operation that is not public. A session expires after a period without requests, and at the latest a fixed time after it opened. DELETE /v1/sessions/current ends it at once, and a password change ends every other session of the account. A missing or refused token is answered with 401 and a WWW-Authenticate challenge.
WebSocket connections take a single-use ticket instead of the token, as Live connections describes.
Sync
A note is a Yjs document, a CRDT, stored as a sealed snapshot followed by an ordered log of sealed updates. The server orders, stores and pages them, but cannot read or merge them. Clients merge, and the CRDT converges whatever order the updates arrive in.
POST /v1/notes/{id}/updatesappends updates. Each update is one version, and the answer is the note’s newversion. ArequestIdmakes a retry safe: a repeat from the same session appends nothing and answers as the first did, for each of its last 8 to the note.PUT /v1/notes/{id}/snapshotreplaces the snapshot with one the client compacted, and drops the updates it covers.GET /v1/changespages through every note that changed since a token: the caller’s own and those shared with it, with tombstones for deleted notes and revoked access. FollownextPageTokenuntil it is empty, then keepnextSyncTokenfor the next sync. Without a token it is a full sync, with snapshots, of the notes the caller can still read. Tombstones are kept as long as deleted notes, 90 days: an older token is refused assync-expired, and the client syncs in full and treats every note the server had given it that the full sync did not list as deleted.GET /v1/notes/{id}reads one note whole, for a client that cannot bridge the gap a compaction left.POST /v1/notes/{id}/members:leavetakes the caller off a note shared with them, on any plan. Their feeds take its tombstone, and its owner’s changes carryresealOweduntil the owner next rotates the key, which the owner’s client does at its next sync.
Every change carries seq, the caller’s delivery order, which a write also answers in NoteRef. The change feed says when to pull.
Conditional requests
A representation a write depends on carries an ETag. PATCH /v1/account and PUT /v1/notes/{id}/members require If-Match with the ETag last read: a stale one is refused with 412, a missing one with 428. GET /v1/notes/{id} and GET /v1/notes/{id}/revisions/{revision} honour If-None-Match and answer 304 when nothing changed. The sharing keypair is written once, with If-None-Match: *.
Rate limits
Requests are counted per client address, an IPv6 one by its /64, the least a subscriber is given. An allowance is a number of requests a minute, which may all come at once. Past it, one more is accepted each time its share of the minute passes. One allowance covers every operation, and a much smaller one covers signing in and signing up, counted per address and identifier as well, and the password asked for again to change it or to delete the account. Failed password sign-ins are also counted per identifier, from every address together, and a password asked for again that fails is counted per account the same way. Live tickets have their own allowance per account, and so do the reads that cost the most: pages of changes with snapshots, a whole note and its revisions, and another account’s sharing key. The journal’s anonymous counts have an allowance of their own per address. A request past an allowance is refused with 429, with Retry-After in seconds until the next one is accepted, when the server knows it.
Some allowances belong to the product and have their own problem types: verification and sign-up emails, feedback, and the command bridge’s cadence. A server at capacity answers 503: retry after a short delay.
Errors
Every refusal is an RFC 9457 problem details object, sent as application/problem+json. It has status and title, and usually detail, which says what to correct. A refusal a client can act on names its problem type in type. One without type is about:blank, and its title is the HTTP status phrase. A validation problem lists each invalid member in errors, located by a JSON Pointer.
Some operations need the paid plan, Orbit. On the free plan they answer 402 with the plan-limit problem type. When an Orbit ends, the account keeps Orbit’s storage ceiling for 30 days more, and no other perk: usage.storageGraceUntil in GET /v1/account says until when.
Each problem type below is named by its slug, and its type is https://docs.astronotes.eu/problems/ followed by the slug and a slash.
validation
The request is not valid (400). A member of the request failed validation. errors lists each one with a JSON Pointer to it and what is wrong with it.
plan-limit
Plan limit reached (402). The account’s plan does not include this feature, or its allowance is used. detail says which. A higher plan lifts the limit.
identifier-taken
Identifier already in use (409). Another account already uses this handle or email address.
note-exists
Note already exists (409). A note with this id already exists. A client that retried its own create can read the note to confirm it is the one it sent.
note-deleted
Note deleted (409). The note has been deleted and accepts no more writes. Stop syncing it.
sync-expired
Sync token expired (410). The token is older than the deleted notes and ended shares the server keeps. Sync in full without a token, then treat every note the full sync did not list as deleted.
snapshot-version-out-of-range
Snapshot version out of range (409). snapshotVersion must lie between the stored snapshot’s version (at least 1) and the note’s current version. Read the note again and compact from there.
stale-key
Sealed under a retired key (409). The note’s content key was rotated, and this write names another key or none. Read the note again, take up its key, and seal the write anew.
revision-anchor-gone
Revision anchor gone (409). The stored revision this one was written against is no longer available. Store a full snapshot instead of a delta.
device-link-out-of-order
Device link out of order (409). The handshake has expired or has already moved past this step. Start a new one.
subscription-active
Subscription already active (409). The account already has an active subscription. Changes to it are made in the billing portal.
withdrawal-closed
Withdrawal period over (409). A withdrawal refunds Orbit in full for 14 days from its start, and those days have passed. Cancelling still ends it at the end of the paid period.
passkey-enrolled
Passkey already enrolled (409). This authenticator is already enrolled on the account.
note-too-large
Note too large (413). The note has reached the most one note can hold. Splitting it across several notes keeps every part searchable.
storage-full
Storage full (409). The account’s storage is full. Removing notes or revisions frees space.
bridge-cadence
Inside the bridge cadence (429). The command bridge accepts one transmission per member per interval. Retry-After says when the next one is accepted.
bridge-withdrawn
Withdrawn from the bridge (403). A transmission this account sent was reported and removed, and the account was withdrawn from the command bridge with it. Every other feature works as before.
ticket-invalid
Ticket invalid (401). The WebSocket ticket has expired, was already redeemed, or names another subject. Mint a new one. The bearer token is not accepted here.
sandbox-grant-used
Sandbox week used (403). An account’s first purchase in the App Store’s sandbox holds Orbit for a week from that purchase, once. Any other sandbox purchase on the account, or one after that week, unlocks nothing.
feedback-allowance-used
Feedback allowance used (429). The year’s feedback allowance is used. Retry-After says when the oldest message leaves the window.
transmission-gone
Transmission gone (404). The bridge holds no transmission by that seq that this account could read: it expired, was removed, or was sealed under a key the account never held.
report-outside-bridge
Outside the bridge (403). A transmission is reported by a member of the bridge, an account that holds one of its keys.
feedback-reports-used
Reports used for the day (429). An account sends a few reports of bridge transmissions and ideas in any 24 hours, apart from its feedback allowance. Retry-After says when the oldest one leaves. Past them, a block still holds.
idea-allowance-used
Idea allowance used (429). An account shares a few ideas a week with the feedback board. Retry-After says when the oldest one leaves the window. Backing an idea already there is never limited.
board-access-withdrawn
Withdrawn from the board (403). The feedback board blocked this account’s user there, so the account shares and backs no more ideas. Every other feature works as before.
verification-allowance-used
Verification emails used (429). An account is sent one verification email a minute and five a day. Retry-After says when the next one is accepted.
sign-up-link-invalid
Sign-up link invalid (400). The sign-up link was already used, has expired, or was never sent. Ask for a new one.
sign-up-links-used
Sign-up emails used (429). An address is sent one sign-up email a minute and five a day. Retry-After says when the next one is accepted.
invalid-isbn
Not an ISBN (400). The number is not a valid ISBN-10 or ISBN-13: a digit is missing or wrong, or it numbers printed music (ISMN) or a magazine (ISSN). detail says which.
book-not-found
Book not found (404). None of the catalogues the server asks knows this ISBN. The book can still be added by hand.
companionship-exists
One companionship at a time (409). A person has one companion at a time, as inviter or as companion. Ending the companionship from the Journey screen frees both.
invitation-pending
An invitation is pending (409). One invitation is pending at a time, until it’s answered, withdrawn, or expires after 14 days.
nudge-allowance-used
Today’s nudge sent (429). A companion is nudged once a day. Retry-After says when the next nudge is accepted.
journey-in-progress
A journey is under way (409). The caller’s journey hasn’t reached day 365. It carries on whatever the plan, and another year can be chosen once it does.
journey-not-started
No journey yet (409). The caller has no journey. Starting one, or accepting a companion’s invitation, begins it.
year-not-complete
The year isn’t complete (409). Another year can be chosen once the journey reaches day 365.
Live connections
Three WebSocket upgrades sit beside the HTTP operations. OpenAPI cannot describe them, so they are specified here.
GET /v1/notes/{id}/live?ticket=…joins a note’s relay.GET /v1/changes/live?ticket=…opens the caller’s change feed.GET /v1/device-links/{id}/eventswatches one device-link handshake.
A ticket is single-use and comes from the matching ticket operation. An upgrade is refused with 401 when its ticket is invalid or expired, with 403 when a browser sends another site’s Origin, with 429 when the account already holds all the sockets it may or, for a handshake watch, its address all the watches it may, with 503 when the server holds all it can, and the handshake watch with 404 when the handshake is unknown or expired. Every socket refuses a message above 1048576 bytes.
Binary frames exist on the note relay only. The server reads none of their content: each is ciphertext, relayed unchanged to the other connections in the room.
Text frames are JSON control messages, told apart by t.
On the note relay the server sends {"t":"role","editor":true} (whether this connection holds an editor seat), {"t":"slot"} (a seat was freed) and {"t":"last","value":true} (whether this connection is alone in the room). A client sends {"t":"claim"} to take a freed seat.
On the change feed the server sends {"t":"changed"} (a note moved: pull /v1/changes. It may carry "seq", the caller’s delivery seq for that change, which a write’s NoteRef also answers, so a writer can tell its own echo) and {"t":"account"} (the account moved: read it again). To Orbit members it also carries the command bridge: {"t":"bridge","m":BridgeMessage} (one transmission), {"t":"bridge-removed","seq":int64} (that transmission was reported and removed: drop it), {"t":"bridge-gap"} (this socket fell behind: fetch the page again), {"t":"bridge-seal","epochId":base64,"members":[{"user":uuid,"publicKey":base64}]} (seal that key to every member listed, in one /v1/bridge/keys:batchCreate), {"t":"bridge-keys"} (try your keys again) and {"t":"bridge-alone"} (nobody holding a key is here: mint the first). A client sends {"t":"bridge-airlock"} when the bridge opens while it holds no usable key, and {"t":"bridge-aboard"} when it opens holding one. Either is answered with the work that opening owes.
The handshake watch sends {"t":"link"} (the handshake advanced: read it again) and nothing else. While the claimer’s offer awaits its seal, the frame also carries it as "offer":{"claimerPubKey":base64,"proof":base64}, sparing that read.
The server pings every 30 seconds and closes a connection silent for 75 seconds. It closes with 1000 normally, as it does once the session that opened a socket ends or the member’s access to a note changes, with 1001 when the server is stopping, with 4001 when a reader fell too far behind, and with 1013 when the server could not read the account a feed serves: reconnect and sync again.