Skip to content
Omicron

Reference

HTTP API

The JSON API under /api — authentication, posts, users, feeds, tags, lists, and notifications.

The backend serves a JSON API under /api, shared by the web app and other clients. The bundled Caddy gateway forwards it directly to the backend at the same public origin. SvelteKit also provides a proxy for development and SSR.

Authentication

Signing in creates a server-side session, represented by an httpOnly cookie backed by the Postgres sessions table. Browsers use that cookie directly.

Independent clients should use scoped OAuth. Applications register on an instance, request consent through its browser UI, and send the resulting access token with API requests. They do not need the account’s password, cookie, or a second JWT exchange.

First-party non-cookie clients can instead use the existing short-lived JWT transport: establish a Better Auth session, request a token, then send:

Authorization: Bearer <token>
Method Path Authentication Purpose
GET /api/auth/jwks None Public keys for JWT signature validation
GET /api/auth/token Better Auth session Mint a JWT for normal API calls

/api/auth/token returns {"token":"ey…"}. Tokens contain only standard claims and expire after 15 minutes. Keep the JWT in memory, refresh it through the session before expiry, and never send either credential to another origin. Session revocation prevents a new token from being minted; an issued token stays valid until it expires.

There is no general-purpose personal-access-token flow. OAuth API grants use explicit scopes and can renew for up to 90 days. Existing identity-only grants remain limited to public identity verification; they cannot read /api/me or authorize normal app operations. The content webhook uses separate publishing credentials.

Public gateway origin checks

The updated bundled gateway routes /api/*, /oauth/token, and /oauth/revoke directly to the backend. Native clients using a valid OAuth or JWT bearer token do not need to manufacture an Origin header, and API calls/preflights must not receive an Anubis challenge. Upgrades must recreate Caddy to activate that routing.

Cookie-authenticated writes require the instance’s exact Origin. For ordinary API resources, POST, PUT, PATCH, and DELETE requests using an active browser session must carry an Origin matching the configured instance origin, including its scheme, hostname, and port. Missing, null, or mismatched origins receive 403 with {"error":"A same-origin request is required."}. A sibling subdomain is a different origin too.

This backend check applies regardless of content type, including JSON, raw uploads, and bodyless writes, even when Caddy bypasses SvelteKit. GET, HEAD, and OPTIONS do not require an origin for this cookie check. The trusted origin comes from the instance’s runtime configuration, not caller-supplied Host or forwarded-host headers. Browser fetch supplies Origin on writes; proxies must preserve it unchanged.

Browser OAuth clients use bearer-token CORS with credentials: "omit". Cross-origin session cookies are not supported. The cookie-write origin check does not restrict a request authenticated by a valid OAuth or JWT bearer token, even if a cookie is also present. Browser clients send their actual origin; they must not try to impersonate the instance’s origin.

When calling through a SvelteKit development proxy or an older/custom gateway, use JSON for bearer-token mutations: its browser-origin protection can reject bodyless or form-content-type writes before the backend sees them. JSON does not bypass the backend’s cookie-write check. Do not disable browser CSRF checks globally.

OAuth consent and connected-application management still require a live same-origin browser session; tokens cannot replace it.

Conventions

  • Cursor pagination. Listing endpoints accept a cursor and return the next one. There is no offset.
  • Rate limiting. Writes are throttled per signed-in user, or per IP when anonymous; reads are not throttled by the general limiter. A limited request gets 429 with Retry-After.
  • Backend errors normally use JSON {"error": "…"} with an appropriate status code. A request body that fails validation gets 400 and a message naming the field, for example {"error":"displayName: Invalid input: expected string, received number"}. A body that is not valid JSON gets 400 too, not 500. SvelteKit or custom-gateway rejections can instead return plain text; check the response status and content type before decoding JSON. The backend’s cookie-origin rejection uses the normal JSON error shape shown above. OAuth failures additionally use protocol error and error_description values; a scoped denial can return 403 insufficient_scope.

Client discovery — /api/client

GET /api/client is public and reports apiVersion, apiBase, OAuth metadata, token lifetimes, human-readable scope descriptions, and a method/path/scope list of delegated operations. It also identifies the browser account-security URL. Discover capabilities before asking for authorization; see Third-party clients.

Health

Method Path Purpose
GET /healthz {"status":"ok"}
GET /version Name, version, federation flag

These sit at the root, not under /api.

Browser account security — /api/auth

Better Auth owns /api/auth/*; these are not general OAuth resource endpoints. Independent apps should open the instance’s login/registration or /settings screens for credential, email, passkey, and session management. The full application profile is GET /api/me, not a separate /api/auth/me resource.

Posts — /api/posts

Method Path Purpose
GET / List posts — the Global timeline, assembled with per-author diversity (see Reading and following)
POST / Create a post (draft, scheduled, or published)
GET /drafts The current user’s drafts
GET /mine?status= The current user’s posts in one state — draft, scheduled, or published
GET /mine/counts How many the current user holds in each state
GET /trending Trending posts
GET /random?scope=&langMode=&langs= Choose a random post from a feed
GET /by/:username/:slug A single post by its public URL
GET /:id A single post
GET /:id/related Up to three posts to read next, topped up with recent posts
PATCH /:id Update a post
DELETE /:id Delete a post
POST / DELETE /:id/like Like / unlike
POST / DELETE /:id/recommend Recommend / un-recommend (federates as Announce/Undo(Announce))
GET /:id/comments List comments
POST /:id/comments Add a comment
PATCH / DELETE /:id/comments/:commentId Edit / delete a comment
POST / DELETE /:id/comments/:commentId/like Like / unlike a comment

Post payloads with an author carry the viewer’s engagement: likeCount, liked, commentCount, recommendCount, recommended, and saved (true when the post is in one of the viewer’s reading lists). Signed out, the booleans are false.

Each comment’s author is { id, username, displayName, avatarUrl, remote }. remote is always present: false for a local account, true for a remote actor, whose username is its user@host handle. Replies nest in replies with the same shape.

GET /api/posts/random returns {"post": …} or {"post": null} when no posts match. scope accepts global (the default), local, or for-you; the last requires a signed-in reader. langMode=show|hide and comma-separated langs=en,az apply to Local and Global, using the same unknown-language and visibility rules as those feeds. For you is not language-filtered. The endpoint samples across the full eligible archive rather than a recent page, and returns Cache-Control: no-store.

Content portability — /api/content

These endpoints require a first-party session or JWT. They are deliberately not delegated to third-party OAuth grants. Cookie-authenticated POSTs retain the same-origin requirement described above. Successful content responses use Cache-Control: no-store.

Method Path Purpose
GET /api/content/export Download omicron-content.zip as an application/zip attachment.
POST /api/content/preview Inspect an archive without writing posts or images.
POST /api/content/import?preservePublished=false Import content; publication preservation is opt-in.

POST the file as raw bytes, for example with Content-Type: application/octet-stream, not JSON or multipart form data. The input may be an Omicron/Medium/Substack ZIP, a WordPress WXR file, or RSS XML. preservePublished accepts only true or false; omitted means false.

The preview returns format, items, imageCount, and warnings. Each item has key, title, status, createdAt, duplicate, and warnings. The import result is { "imported": number, "skipped": number, "failed": [...] }; each failure has title and error. A successful HTTP response can report per-post failures. Posts already imported remain in place and are skipped on retry.

The archive manifest is defined by ContentArchive in packages/contract; JSON preview/results use ContentImportPreview and ContentImportResult. No existing response shape or API version changes.

The fixed input cap is 50 MiB; oversized inputs receive 400 from the backend or 413 from the SvelteKit proxy. Missing authentication is 401; a delegated grant is rejected with 403 insufficient_scope. Six transfer requests per account per minute share one budget, including downloads; import and preview also consume the ordinary API-write budget. 429 includes Retry-After. See Import and export for content, visibility, image, and destination-format limitations.

Feed, search, dashboard

Method Path Purpose
GET /api/feed The personalised feed
GET /api/search Posts, accounts, and tags
GET /api/dashboard Writer dashboard figures

GET /api/dashboard?days=N covers the signed-in writer’s published posts. days defaults to 30 and is clamped to 1–365. The response holds:

Field Contents
onInstanceViews false when the instance disables view counting; view figures are then 0 and series empty
totals All-time views, likes, comments, and current followers
period { days, views, likes, comments, followers } within the last days; followers counts new ones
series Daily { day, views } over the window
posts Per post: postId, title, slug, createdAt, and all-time views, likes, comments

Umami Cloud — /api/site

These routes are unauthenticated and support the optional Umami Cloud integration, not the writer dashboard.

Method Path Purpose
GET /api/site Enabled website ID, or null when disabled
GET /api/site/script.js Proxy the fixed Cloud tracker
POST /api/site/api/send Forward a validated public-page pageview

GET /api/site returns { "websiteId": string | null }. The script route returns JavaScript while enabled and 404 while disabled. All three routes use Cache-Control: no-store; the backend caches successful script fetches in memory for one hour.

Collection accepts application/json with { "type": "event", "payload": {...} }. The payload contains website (the configured UUID), hostname, screen, language, title, and url; referrer is optional. Unknown fields, reader identifiers, custom event names, and other event types are rejected. The server removes query strings and fragments and restricts page paths before forwarding. X-Umami-Cache, when present, is forwarded for Cloud session continuity; the successful Cloud JSON response is returned to the tracker.

Disabled collection or a request carrying DNT: 1 or Sec-GPC: 1 returns 204 without contacting Cloud, subject to rate limits. Cross-site browser collection requests are refused with 403. Invalid payloads return 400, bodies over 16,384 bytes return 413, exhausted request budgets return 429 with Retry-After, and upstream failures return a generic 502. See Rate limits.

Configuration uses the separate admin-only API.

Users — /api/users

Method Path Purpose
PATCH /me Update the profile
PATCH /me/privacy Update privacy settings
PATCH /me/preferences { showAiAssistedPosts }
POST /me/custom-section/preview Render the custom About Markdown
POST / DELETE /me/avatar Upload / remove the avatar
GET /me/follow-requests Pending follow requests
POST /me/follow-requests/:id/approve Approve a request
POST /me/follow-requests/:id/reject Reject a request
GET /me/muted, /me/blocked Muted / blocked accounts
DELETE /me/followers/:identifier Remove a follower
GET /suggested Suggested accounts
GET /:username A profile
GET /:username/followers, /:username/following, /:username/posts Their collections
GET /:username/recommendations Posts they’ve recommended
POST / DELETE /:username/follow Follow / unfollow
POST / DELETE /:username/mute Mute / unmute
POST / DELETE /:username/block Block / unblock

Remote actors — /api/remote

Federated equivalents, keyed by handle (user@domain):

Method Path Purpose
GET /users/:handle Resolve and fetch a remote profile
GET /users/:handle/posts Their posts, as cached locally
GET /users/:handle/recommendations Posts they’ve recommended (recorded from inbound Announce)
POST / DELETE /users/:handle/follow Follow / unfollow
POST / DELETE /users/:handle/mute Mute / unmute
POST / DELETE /users/:handle/block Block / unblock

Tags — /api/tags

Method Path Purpose
GET / Trending tags
GET /suggest?q= Composer autocomplete
GET /search?q= Search tags by name
GET /following Tags the user follows
GET /:slug One tag
GET /:slug/posts Posts under a tag
POST / DELETE /:slug/follow Follow / unfollow a tag

Lists — /api/lists

Method Path Purpose
GET / The user’s lists
POST / Create a list
GET /read-later The built-in read-later list
GET /user/:username A user’s public lists
GET /for-post/:postId Which of your lists hold this post
GET /:id One list
GET /:id/items Its posts
PATCH / DELETE /:id Update / delete the list
POST /:id/items Add a post
DELETE /:id/items/:postId Remove a post

Notifications — /api/notifications

Method Path Purpose
GET / List notifications
GET /unread-count Unread badge count
POST /read Mark all as read
POST /:id/read Mark one as read

Media — /api/uploads

Method Path Purpose
POST / Upload a file
GET /:file Serve an uploaded file
GET /og/:id.jpg A JPEG copy of an upload, for link-preview crawlers

/og/:id.jpg takes the id of an existing upload — whatever its stored format — and returns it as a JPEG fitted inside 1200×630, generated on first request and cached on disk. It exists because uploads are stored as WebP, which several preview crawlers refuse, and because a share image has to be a format every one of them reads. Unauthenticated by necessity: the caller is a crawler with no session.

Remote images — /api/media/proxy

GET /api/media/proxy?url=<encoded-absolute-url> is an unauthenticated image endpoint. The web UI uses it for remote avatars, covers, body images, and image previews so the remote host receives the instance’s request, not the reader’s. Stored URLs and ActivityPub payloads are unchanged.

  • Only public HTTPS destinations on the default port are fetched. Legacy HTTP URLs are upgraded to HTTPS; HTTP-only sources stop displaying.
  • PNG, JPEG, GIF, and WebP must match their declared MIME type and raster signature. SVG and other active content are refused.
  • Transfers are capped at 5 MiB, 10 seconds total, and 3 redirects. Each redirect is revalidated; DNS answers are checked and pinned to the socket.
  • The process-local cache lasts 1 hour, with at most 64 entries / 16 MiB. Concurrent misses for one URL share a fetch. There are at most 8 fetches globally and 2 per initial origin, per backend process.
  • The request limiter allows 240 requests per minute per source IP. These image-proxy limits are source constants, not environment variables.

A successful response contains image bytes, Cache-Control: public, max-age=3600, X-Content-Type-Options: nosniff, and Cross-Origin-Resource-Policy: same-origin. Visitor cookies and request headers are not forwarded upstream; upstream cookies are not returned. Invalid targets return 400, unavailable or rejected images 404, and exhausted request or concurrency budgets 429.

Share cards — /api/og

Method Path Purpose
GET /posts/:id.jpg The card drawn for a post that has no image of its own
GET /profiles/:username.jpg A profile’s card: its public header only, never posts

A 1200×630 JPEG carrying the post’s title, its author, and the instance — generated on first request and cached on disk. What a link-preview crawler fetches as og:image when the post has neither a chosen banner nor an image in its body. Unauthenticated, like the media route above, and built from the same visibility check a signed-out reader gets: a draft’s card is a 404, exactly like the draft.

Answers 302 to the instance’s brand image when no card can be drawn — a federated copy of someone else’s post, an untitled one, or a title in a script the bundled font has no glyphs for. A redirect rather than a 404 because an og:image that fails puts no picture on the card at all.

Profile cards are cached for a day rather than forever, since an edited profile draws a different card; the web app puts the profile’s updatedAt in the URL. Private accounts get a card too, because it draws only the public header.

Its own prefix rather than a path under /api/posts/ so robots.txt can allow it by name — see Discoverability. Nothing but share images belongs here.

Photos — /api/photos

Free-photo search for the editor’s banner picker. Signed in only — one provider spends an instance-wide quota.

Method Path Purpose
GET /providers Which providers this instance can search, in order
GET /search?provider=&q=&page= Search one provider
POST /use Tell a provider one of its photos was used

/providers is never empty: Openverse needs no credentials, so it is always present. Unsplash joins it only when an admin has configured a key. Results from either provider come back in one shape, carrying the attribution to store with the post.

/use takes { provider, token } and exists for Unsplash’s API terms, which require a per-photo call when an image is actually used; it is a no-op for providers that ask for nothing. Search carries its own per-user rate limit on top of the general one, because a GET is not covered by the write throttle and both providers are shared resources.

Webhooks — /api/webhooks

Method Path Auth Purpose
POST /content Token Publish a document from an external CMS
GET /tokens Session Your live publishing tokens
POST /tokens Session Mint one (plaintext returned once)
DELETE /tokens/:id Session Revoke one

/content is the one endpoint that does not use the session cookie: it authenticates with a bearer credential in X-Webhook-Secret or Authorization: Bearer, and publishes as that credential’s owner. Managing tokens is an ordinary session-authenticated call, so a token cannot mint or revoke tokens. Full reference in Content webhook.

Email change undo — /api/email-change

Method Path Purpose
POST /undo { token } from the link sent to the old email

Public: the link reaches the old address, whose owner may be signed out. It restores the old email and locks the account down: every session ends, passkeys are removed, and the password is cleared, then a password-reset link goes to the restored address. Returns { email }. Links last 7 days and are single-use. See Account and security.

Reports, instance, setup, SEO

Method Path Purpose
POST /api/reports Report a post or actor
GET /api/instance Public instance metadata, including visitor card and public information
POST /api/setup Complete the first-run wizard
POST /api/setup/test-email Send a test email during setup
GET /api/seo Indexing flag and verification tokens (the IndexNow key is withheld)
GET /api/seo/sitemap-entries Profiles, tags, and public lists for the sitemap, plus the post count
GET /api/seo/sitemap-posts?page=N One page of published local posts for the sitemap
GET /api/seo/indexnow-key/:key Whether key is this instance’s IndexNow key

GET /api/instance is unauthenticated and powers the site chrome and the public About, privacy, contact, and status pages. Alongside the name, domain, federation flag, and visitor card it returns the admin-managed public information as sanitized HTML (aboutHtml, rulesHtml, privacyPolicyHtml) plus the contact and status links; each is null when the admin has not set it, in which case the page shows its built-in placeholder or environment fallback.

It also reports apiVersion, the version of the API contract the instance speaks. It is bumped on every breaking change (a response field removed, renamed, or retyped), so a client older than the instance can tell its user to update.

GET /api/instance/tls-check?domain=… is internal only: Caddy calls the backend directly before issuing a certificate. Both the public Caddy route and the frontend API proxy return 404 for it. A custom reverse proxy must preserve that boundary rather than publishing the backend directly.

GET /.well-known/security.txt publishes the project’s vulnerability-reporting contact, an expiry 180 days ahead, and the preferred language. It is served as plain text with a one-day cache and bypasses federation routing and the bot challenge.

Administrative endpoints are documented separately in Admin API.

Found a mistake?Edit this page on GitHub.