Skip to content
Astro Notes

Overview

Astro Notes API 1.0.0

Section titled “Astro Notes API 1.0.0”

Astro Notes: end-to-end encrypted, Markdown-only note service. Note content and metadata are opaque ciphertext to the server. Binary values cross the wire as standard base64.

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}/events watches 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, and the handshake watch with 404 when the handshake is unknown or expired.

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, and refused above 1048576 bytes.

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) 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-gap"} (this socket fell behind: fetch the page again), {"t":"bridge-seal","user":uuid,"publicKey":base64,"epochId":base64} (sent to one nominated member: seal the key to that user) and {"t":"bridge-keys"} (try your keys again). A client sends {"t":"bridge-airlock"} while it holds no usable key, and {"t":"bridge-aboard"} the moment one opens.

The handshake watch sends {"t":"link"} (the handshake advanced: read it again) and nothing else.

The server pings every 30 seconds and closes a connection silent for 75 seconds. It closes with 1000 normally, and with 4001 when a reader fell too far behind: reconnect and sync again.

How the service is built, every problem type, and this reference

Operations

Section titled “Operations”
POST
/v1/accounts
POST
/v1/accounts:lookupAuthParams
POST
/v1/sessions
DELETE
/v1/sessions/current
POST
/v1/sessions:beginPasskey
POST
/v1/sessions:challengePasskey
POST
/v1/sessions:finishPasskey
POST
/v1/sessions:recover
GET
/v1/passkeys
POST
/v1/passkeys
GET
/v1/passkeys/{id}
DELETE
/v1/passkeys/{id}
POST
/v1/passkeys:beginEnrolment
POST
/v1/passkeys:declineOffer
GET
/v1/account
PATCH
/v1/account
POST
/v1/account:changePassword
POST
/v1/account:delete
POST
/v1/account:sendVerification
POST
/v1/account:verifyEmail
GET
/v1/changes
POST
/v1/changes/tickets
POST
/v1/notes
GET
/v1/notes/{id}
DELETE
/v1/notes/{id}
GET
/v1/notes/{id}/revisions
POST
/v1/notes/{id}/revisions
GET
/v1/notes/{id}/revisions/{revision}
PUT
/v1/notes/{id}/snapshot
POST
/v1/notes/{id}/updates
GET
/v1/account/sharing-key
PUT
/v1/account/sharing-key
POST
/v1/notes/{id}/live-tickets
GET
/v1/notes/{id}/members
PUT
/v1/notes/{id}/members
GET
/v1/users/{identifier}/sharing-key
POST
/v1/billing/checkout-sessions
POST
/v1/billing/portal-sessions
GET
/v1/billing/prices
PATCH
/v1/billing/subscription
POST
/v1/billing/webhook
GET
/v1/bridge/keys
POST
/v1/bridge/keys
GET
/v1/bridge/messages
POST
/v1/bridge/messages
GET
/v1/bridge/messages/{seq}
GET
/v1/feedback
POST
/v1/feedback
POST
/v1/device-links
GET
/v1/device-links/{id}
DELETE
/v1/device-links/{id}
PUT
/v1/device-links/{id}/offer
GET
/v1/device-links/{id}/seal
PUT
/v1/device-links/{id}/seal
POST
/v1/journey-events
POST
/v1/tour-events

Authentication

Section titled “Authentication”

bearerAuth

Section titled “bearerAuth”

Opaque session token from login/register/recover.

Security scheme type: http