HTTP API reference

This document describes the HTTP API exposed by a self-hosted Standard Red Notes server. It is generated from the source of truth in this repository:

• The API gateway route map — server/packages/api-gateway/src/Service/Resolver/EndpointResolver.ts and the gateway controllers under server/packages/api-gateway/src/Controller.
• The client path map the official clients actually call — app/packages/snjs/lib/Services/Api/Paths.ts and the published @standardnotes/api Server/*/Paths.ts modules.
• The auth and syncing-server controllers under server/packages/auth/src/Controller and server/packages/syncing-server.

Everything here is documented from real code paths. Endpoints unique to this fork are marked (Standard Red Notes).

Contents

• Base URL and versioning
• Authentication model
• How to call the API
• End-to-end encryption implications
• Endpoints
  • Authentication and sessions
  • Account recovery
  • Users, settings and features
  • Sync and items
  • Revisions
  • Files
  • WebSocket realtime
  • Subscriptions and offline tokens
  • Two-factor: authenticators and magic link
  • Collaboration: shared vaults, invites, messages
  • App passwords (Standard Red Notes)
  • MCP tokens (Standard Red Notes)
  • Trusted devices and push MFA (Standard Red Notes)
  • Public share links (Standard Red Notes)
  • Dead man’s switches (Standard Red Notes)
  • Email reminders (Standard Red Notes)
  • AI assistant proxy (Standard Red Notes)
  • Integrations (Standard Red Notes)
  • Admin (Standard Red Notes)
  • Server metadata

Base URL and versioning

All requests go to the API gateway. In the bundled Docker stack everything enters through the single app front door on http://localhost:3001: its nginx serves the web client and proxies /v1, /v2, /auth, /subscription, and /healthcheck to the gateway, /files/ to the files service (prefix-stripped), and /sockets to the realtime websocket - the gateway and files service publish no host ports of their own. In a production deployment you put a reverse proxy in front of that one port and use your own domain. The examples below use $SERVER for the gateway origin:

export SERVER="http://localhost:3001"

Paths are versioned by a leading /v1 or /v2 segment. The clients send a payload-level API version field too (api_version), defined in app/packages/api/src/Domain/Api/ApiVersion.ts: v0 = 20200115, v1 = 20240226. The legacy snjs client sends 20240226.

The current sign-in flow is /v2 (PKCE). The older /v1/login path still exists and resolves to the same PKCE handler on the gateway.

Authentication model

Standard Red Notes uses the Standard Notes authentication protocol. The account password is never sent to the server as-is and is never used to decrypt on the server. The high-level flow:

1. Key params (PKCE). The client generates a random code_verifier, derives code_challenge = base64url(sha256(code_verifier)), and calls POST /v2/login-params with the email and the code_challenge. The server returns the account’s key params (KDF algorithm, salt/nonce, iterations).
2. Local key derivation. The client derives the root key from the user’s password + key params on device (argon2). It splits that into a “server password” (used only to prove knowledge to the server) and a master key (never leaves the device, used to encrypt/decrypt items).
3. Sign in (PKCE). The client calls POST /v2/login with the email, the password (the derived server password, not the user’s password), and the code_verifier. On success the server returns a session containing an access_token and a refresh_token, plus the account’s key params and user object.
4. Authenticated requests. Bearer the access token: Authorization: Bearer <access_token>. The FetchRequestHandler sets this header from the session access token. Browser clients additionally rely on session cookies set by the server (see the self-hosting guide on cookie configuration).
5. Refresh. When the access token expires, call POST /v1/sessions/refresh with { access_token, refresh_token } to receive a new pair. The session body shape is in SessionRefreshResponseBody.ts: { session: { access_token, refresh_token, access_expiration, refresh_expiration, readonly_access } }.

Obtaining access (credentials and tokens)

• Account credentials — email + password (registered via POST /v1/users) are the primary way to obtain a session. Two-factor (TOTP authenticator or email magic link) may be required as a second factor at sign-in.
• App passwords (Standard Red Notes) — a per-account secret that satisfies the interactive 2FA challenge for a single sign-in, so headless clients do not need a live TOTP code. The account password is still required. See App passwords.
• MCP tokens (Standard Red Notes) — the API issues an authentication credential (<uuid>.<auth-secret>); the client adds a separate wrap secret to form the full bridge token. The full token authenticates without the account email/password and unwraps client-wrapped items keys. See MCP tokens.
• Trusted devices (Standard Red Notes) — a per-device token that bypasses only the 2FA gate (never the account password) on future sign-ins. See Trusted devices.

How to call the API (curl)

The full sign-in flow requires deriving the server password locally (argon2), so the simplest faithful client is the bundled srn-client CLI (see cli/srn-client), which runs the real protocol via an embedded snjs client. The raw HTTP sketch below shows the request/response shapes; replace the derivation step with the snjs/srn-client logic for a real call.

SERVER="http://localhost:3001"
EMAIL="me@example.com"

# 1) Get key params (PKCE). Generate a code_verifier and its SHA-256 challenge.
#    (Pseudocode: code_challenge = base64url(sha256(code_verifier)))
curl -s -X POST "$SERVER/v2/login-params" \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"20240226\",\"email\":\"$EMAIL\",\"code_challenge\":\"<challenge>\"}"
# -> { "identifier": ..., "pw_nonce": ..., "version": ..., ... key params }

# 2) Derive the root key locally from your password + key params (argon2),
#    split into the server password. Then sign in:
curl -s -X POST "$SERVER/v2/login" \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"20240226\",\"email\":\"$EMAIL\",\"password\":\"<server_password>\",\"code_verifier\":\"<code_verifier>\",\"ephemeral\":false}"
# -> { "session": { "access_token": "...", "refresh_token": "...", ... },
#      "key_params": { ... }, "user": { ... } }

# 3) Make an authenticated request with the access token:
ACCESS_TOKEN="<from step 2>"
curl -s -X GET "$SERVER/v1/sessions" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
# -> [ { "uuid": ..., "api_version": ..., "user_agent": ..., ... }, ... ]

End-to-end encryption implications

Item payloads are ciphertext. When you push items to POST /v1/items the content and enc_item_key fields are already encrypted on the client with keys derived from the account password; the server stores and relays them without being able to read them. Likewise file contents, share payloads, and MCP key material are stored as ciphertext or as opaque client-side wrappings.

Practical consequences when talking to the API directly:

• You cannot construct a valid item payload server-side — you must encrypt with the user’s keys (use snjs / srn-client).
• The server-visible metadata is limited: item uuid, content_type, created_at/updated_at timestamps, item existence and size, the account email, and session/device info. It cannot see note titles or contents.
• Public share links store only ciphertext keyed by a shareId; the decryption key lives in the link fragment and never reaches the server.

Endpoints

Notation: each entry shows the client-facing method + path (what you call on the gateway). The “Resolver id” is the internal identifier the gateway maps the route to in EndpointResolver.ts; it is included for traceability. Unless noted, request/response bodies are JSON. Authenticated endpoints require Authorization: Bearer <access_token> (and, for browser sessions, the session cookies).

Authentication and sessions

Account recovery

Two different mechanisms use similar names:

• MFA recovery codes satisfy or restore a server-side second-factor challenge. They do not contain account encryption keys and cannot replace a forgotten account password.
• Optional account recovery (v2 escrow) is a Standard Red Notes client flow. A signed-in client encrypts root-key material with a separately generated high-entropy code. A signed-out client uses the code’s UUID locator to fetch the bounded ciphertext, decrypts it locally, obtains a normal session with the recovered root key, and rotates credentials through the authenticated credentials endpoint.

The server never receives the v2 recovery secret or wrapping key. The only public lookup takes a UUID locator and returns a generic unavailable response for absent, malformed, or legacy escrow. The UI under Preferences -> Security -> Account recovery is the supported way to enroll, rotate, disable, and exercise this contract.

Users, settings and features

Credential changes atomically invalidate the current account-recovery escrow. After a successful password change or recovery, the client must explicitly re-enroll and show a new one-time code. There is no administrator-only endpoint that installs a new password or returns decrypted recovery material.

Sync and items

The gateway route POST /v1/items is resolved to items/sync (see ItemsController); the snjs client path constant is /v1/items.

Revisions

Files

File chunk operations (handled by the files service, authorized with the valet token from above; client paths in snjs/.../Paths.ts, joined onto the files host above, e.g. http://localhost:3001/files/v1/files/upload/chunk): POST /v1/files/upload/create-session, POST /v1/files/upload/chunk, POST /v1/files/upload/close-session, GET/DELETE /v1/files, plus the shared-vault variants under /v1/shared-vault/files/*.

WebSocket realtime

The worker upgrades the exact /sockets/sync path with an allowed Origin and no query string. It sends the one-use ticket in the first protocol AUTH frame; credentials and tickets are never put in this URL. HTTP item sync is the fallback when this capability is absent or the socket disconnects.

Subscriptions and offline tokens

In this fork every account has full access regardless of subscription (features mode included), so these endpoints exist for protocol compatibility but full access does not depend on them.

Two-factor: authenticators and magic link

Collaboration: shared vaults, invites, messages

App passwords (Standard Red Notes)

App-specific passwords let headless clients satisfy the 2FA challenge without a live TOTP code. The account password is still required. Source: AppPasswordsController.ts.

To use an app password, present it as app_password in the POST /v2/login-params body; a valid value marks the interactive 2FA challenge satisfied for that sign-in.

MCP tokens (Standard Red Notes)

The API-facing token (<uuid>.<auth-secret>) authenticates without the account email/password and returns client-side-wrapped items keys. The web client appends a client-only wrap secret to create the full three-part bridge token. Source: McpTokensController.ts.

Trusted devices and push MFA (Standard Red Notes)

A trusted-device token bypasses only the 2FA gate (never the account password) on future sign-ins. Push-MFA approvals let another signed-in device approve a pending sign-in. Sources: TrustedDevicesController.ts, PendingMfaApprovalsController.ts.

To use a trusted-device token at sign-in, present it as trusted_device_token in the POST /v2/login-params body. The server fails closed: a wrong/expired token is ignored and the normal 2FA prompt still appears.

Public share links (Standard Red Notes)

A signed-in user can publish a note as ciphertext keyed by a shareId; the decryption key lives only in the link fragment and never reaches the server. Source: SharesController.ts.

Dead man’s switches (Standard Red Notes)

A survivor switch: the server stores a full share URL (link + key) and emails it to a recipient if the user stops checking in by the deadline. Source: DeadManSwitchesController.ts.

Email reminders (Standard Red Notes)

Reminders the server may email to the account email when due. Unlike in-app reminders (E2E-encrypted in note appData), the time + message here are stored in plaintext because the user opted that reminder into email delivery. Source: EmailRemindersController.ts.

Published reminder delivery (Standard Red Notes)

Authenticated users may explicitly publish individual reminders for server-side delivery. The published message, due time, channel, and destination are plaintext by design; ordinary note content remains end-to-end encrypted. All management routes except opt-out require both the server master switch and the user’s synced opt-in setting. Source: ReminderDeliveryController.ts.

AI assistant proxy (Standard Red Notes)

A stateless LLM streaming proxy. Notes are E2E-encrypted, so the agent loop and all tools run in the browser; this controller only forwards one model turn at a time using a server-held provider key. Source: AssistantController.ts. These routes are not part of the home-server EndpointResolver map.

Integrations (Standard Red Notes)

Source: IntegrationsController.ts. Not part of the EndpointResolver map.

Admin (Standard Red Notes)

In-app admin panel endpoints, gated server-side on the internal-team role. Source: AdminController.ts.

Email delivery administration.

These admin-only endpoints manage the advanced email-delivery subsystem. The full Redis-backed topology supports prioritized SMTP, SendGrid, Mailgun, and AWS SES profiles, per-profile rate limits, optional fallback, an encrypted durable queue, and redacted attempt logs. POST /test is owned by AdminController; the other routes are owned by the isolated AdminEmailDeliveryController.ts boundary.

The single/home in-memory topology has no advanced relay, queue, or log service: those routes return 501, while the shared /test route retains its compatible direct SMTP behavior. 503 means the advanced service exists in the current topology but is temporarily unavailable. Provider failures are sanitized and directed to the redacted log; administrative audit events contain operation metadata only.

Server metadata

See also

• Onboarding guide — using the app, accounts, editors, privacy.
• Self-hosting guide — env vars, reverse proxy, cookies/auth, backups.
• cli/srn-client — a real, end-to-end-encrypted CLI client that exercises this API via an embedded snjs client.
• MCP Bridge — the implemented bridge runtime that uses MCP tokens.
• Security and Account — the user-visible account-recovery lifecycle and trust boundary.