HTTP API

The backend serves a JSON API under /api. The web app is its first consumer: the frontend reverse-proxies /api/* to the backend, so the browser talks to one origin, there is no CORS configuration, and the session cookie flows naturally.

Authentication

Session-based. Signing in sets an httpOnly cookie backed by a row in the Postgres sessions table. Send that cookie with subsequent requests.

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.
• Errors are JSON with an appropriate status code.

Health

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

These sit at the root, not under /api.

Auth — /api/auth

Method	Path	Purpose
POST	/register	Create an account
POST	/login	Sign in, setting the session cookie
POST	/logout	End the session
GET	/me	The current user
DELETE	/me	Delete the account
POST	/password/forgot	Send a reset email
POST	/password/reset	Complete a reset with a token
POST	/password/change	Change password while signed in
POST	/email/verify	Verify an address with a token
POST	/email/resend	Resend the verification email

Posts — /api/posts

Method	Path	Purpose
GET	/	List posts
POST	/	Create a post (draft or published)
GET	/drafts	The current user’s drafts
GET	/trending	Trending posts
GET	/:id	A single post
PATCH	/:id	Update a post
DELETE	/:id	Delete a post
POST / DELETE	/:id/like	Like / unlike
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

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

Users — /api/users

Method	Path	Purpose
PATCH	/me	Update the profile
PATCH	/me/privacy	Update privacy settings
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
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
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	/	List tags
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

Reports, instance, setup, SEO

Method	Path	Purpose
POST	/api/reports	Report a post or actor
GET	/api/instance	Public instance metadata
GET	/api/instance/tls-check	Whether a hostname may be issued a certificate
POST	/api/setup	Complete the first-run wizard
POST	/api/setup/test-email	Send a test email during setup
GET	/api/seo, /api/seo/sitemap-entries	SEO metadata and sitemap data

Administrative endpoints are documented separately in Admin API.