# Aloha Social API Reference

> This document is written by hand but mechanically checked: `tests/DocumentationTest.php` asserts that the set of routes documented here matches the set of routes the app registers, which it reads the way the server does — the `#[FrontpageRoute]` attributes on the controller methods, plus what is left in `appinfo/routes.php`. Every route below appears in a table row with its URL exactly as written in the attribute. Paths that are *not* routes of this app (the `.well-known` discovery documents handled by the Nextcloud WellKnown API) are deliberately written without code spans so that check stays exact.

**Rate-limit headers.** Every response from a route that carries a rate limit
also carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
`X-RateLimit-Reset` (seconds since the epoch, at the end of the window this
request fell in), so a client can pace itself rather than hammer until it is
refused. The refusal itself is Nextcloud's and is a **429**; the count in the
header is this app's own and is advisory. A route with no limit carries no
headers, and an instance with **no memcache configured** carries `Limit`
without `Remaining` or `Reset` — there is nowhere to keep a counter, and a
number that was never measured is worse than no number.

## Contents

- [Overview](#overview)
- [Authentication](#authentication)
- [Mastodon-compatible API](#mastodon-compatible-api)
- [Custom Local API](#custom-local-api)
- [OAuth](#oauth)
- [ActivityPub Federation](#activitypub-federation)
- [Legacy OStatus](#legacy-ostatus)
- [Frontend / Document serving](#frontend--document-serving)
- [Async Queue](#async-queue)
- [Error Responses](#error-responses)

---
## Overview

The Aloha Social app exposes four groups of endpoints. Each is registered as a `#[FrontpageRoute]` attribute on the controller method that answers it, with one exception noted at the end of this section:

- **Mastodon-compatible REST API** (the controllers built on `MastodonApiController` — `AccountApiController`, `StatusApiController`, `TimelineApiController`, `MediaApiController`, `InstanceApiController`, `ScheduledStatusApiController`, `AnnualReportApiController` and `ApiController` — plus `TagController` and `OAuthController`) — a partial implementation of the Mastodon client API. Several endpoints are stubs; each is marked below.
- **Custom Local API** (`LocalController`, `ConfigController`) — the endpoints the app's own Vue frontend calls. They are not Mastodon-compatible and their response envelope differs (see Error Responses).
- **ActivityPub Federation API** (`ActivityPubController`, `SocialPubController`) — server-to-server ActivityPub, plus the HTML profile/post pages served on the same URLs.
- **Frontend, document, OStatus and queue endpoints** (`NavigationController`, `OStatusController`, `QueueController`) — HTML pages and internal plumbing.

All URLs are relative to the app's route base, i.e. index.php/apps/social + the URL from the route table (for example, index.php/apps/social/api/v1/statuses).

**Conditional GETs.** The home timeline and the unread counts carry an `ETag` built from the newest id the viewer can see; the routes a page load reads for its sidebar — `/api/v1/custom_emojis`, `/api/v1/trends/tags`, `/api/v1/instance/`, `/api/v2/instance`, `/api/v1/lists` and `/api/v1/followed_tags` — carry one built from the answer itself. All of them go out with `Cache-Control: private, no-cache`, and a request whose `If-None-Match` names the current tag is answered `304` with no body.

None of these are OCS routes: `#[ApiRoute]` would put them under `/ocsapp`, which is not where any of these paths are published.

`GET /api/v1/accounts/{id}` is the one route still declared in `appinfo/routes.php`. Its `{id}` accepts slashes, so it also matches `/api/v1/accounts/{account}/lists` and `/api/v1/accounts/{account}/featured_tags`, and it has to be offered to the matcher after them; those two belong to other controllers, and attribute routes are contributed one controller at a time in filesystem order. The array file is loaded after every attribute route of the app, which is the guarantee that route needs.

### Removed: the superseded half of the Custom Local API

The Custom Local API predates the Mastodon-compatible one, and the frontend
moved off most of it. Nineteen of `LocalController`'s thirty-one routes had no
caller anywhere in `src/` and were documented here as deprecated for a release;
**as of 0.19.39 they are gone**, and with them the `getStream*()` /
`getTimeline*_dep()` query layer that only they used. A caller of one of these
gets a 404 and should move to the Mastodon route beside it:

| Removed | Use instead |
|---|---|
| `GET /api/v1/stream/home` | `GET /api/v1/timelines/home` |
| `GET /api/v1/stream/timeline` | `GET /api/v1/timelines/public?local=true` |
| `GET /api/v1/stream/federated` | `GET /api/v1/timelines/public` |
| `GET /api/v1/stream/tag/{hashtag}/` | `GET /api/v1/timelines/tag/{hashtag}` |
| `GET /api/v1/stream/direct` | `GET /api/v1/conversations` |
| `GET /api/v1/stream/liked` | `GET /api/v1/favourites` |
| `GET /api/v1/stream/notifications` | `GET /api/v1/notifications` |
| `GET /api/v1/account/{username}/stream` | `GET /api/v1/accounts/{account}/statuses` |
| `GET /local/v1/post`, `GET /local/v1/post/replies` | `GET /api/v1/statuses/{nid}`, `…/context` |
| `POST`/`DELETE /api/v1/post/like` | `POST /api/v1/statuses/{nid}/favourite`, `…/unfavourite` |
| `GET /api/v1/current/info` | `GET /api/v1/accounts/verify_credentials` |
| `GET /api/v1/current/followers`, `…/following` | `GET /api/v1/accounts/{account}/followers`, `…/following` |
| `GET /api/v1/global/actor/info` | `GET /api/v1/accounts/{account}` |
| `GET /api/v1/global/actor/header` | the `header` field of the Account entity |
| `PUT /api/v1/account/summary` | `PATCH /api/v1/accounts/update_credentials` |
| `GET /local/v1/search` | `GET /api/v2/search` |

The twelve that the frontend still uses -- the banner uploads, the
`global/account` and `global/tags` searches, the profile field and avatar
endpoints, `POST`/`DELETE /api/v1/post` and `/api/v1/current/follow` -- have no
Mastodon equivalent yet and stay.


---

## Authentication

Two mechanisms exist, and which one applies depends on the controller:

1. **OAuth Bearer token** — `MastodonApiController` and `TagController` read it. The constructor parses the `Authorization` header, accepts a `bearer` auth type, and resolves the token through `ClientService::getFromToken()`. If no bearer token is present it falls back to the logged-in Nextcloud session user. Both declare their routes `#[PublicPage]` with `#[NoCSRFRequired]` and then require a viewer inside the handler: a Mastodon client has no Nextcloud session and no CSRF token, so `#[NoAdminRequired]` would refuse every real caller before the handler ran.
2. **Nextcloud session** — `LocalController`, `ConfigController`, `NavigationController`, `OAuthController` (authorize/authorizing) and `OStatusController` use the session `userId` only. They do **not** honour bearer tokens, so the Custom Local API is effectively usable only from the app's own frontend (or with a Nextcloud session cookie / app password + `OCS-APIRequest`).

Access control is declared with **PHP attributes** (`#[PublicPage]`, `#[NoCSRFRequired]`, `#[NoAdminRequired]`, and `#[BruteForceProtection]` on the OAuth token/revoke endpoints); the legacy PHPDoc annotations are gone. The "Auth" column in the tables below records these attributes:

- `public` — `#[PublicPage]`: reachable without a Nextcloud login (an endpoint may still fail later if it needs a viewer).
- `user` — `#[NoAdminRequired]`: any logged-in user.
- `admin` — no attribute at all: Nextcloud requires an admin session.
- `no-csrf` — `#[NoCSRFRequired]`: no CSRF token needed, which matters for non-browser clients.

The account pages a client app shows — memories, statistics, video channels, the migration exports, imports and move-in, and the authorized apps — are `ClientApiController` routes like the Mastodon ones: the bearer token a client got from this app's own OAuth reaches them, so a client needs no second, Nextcloud login for them. The Nextcloud session still does too: the web page with its CSRF token, and a client holding a Nextcloud app password with Basic auth and `OCS-APIRequest: true`.

### Which credentials a route takes

One rule decides which sign-in a client sends, so that it is not a choice per route:

- **A route that reads or writes the person's Nextcloud files takes the Nextcloud session**, never this app's OAuth token: the web app's session with its CSRF token, or a client's **Nextcloud app password** (from Login Flow v2) sent as HTTP Basic **together with `OCS-APIRequest: true`**. A bearer token is a **403** whatever its scopes. Without the `OCS-APIRequest` header Nextcloud holds the request to its CSRF check, which a client cannot pass, and the answer is a **401**. Files are Nextcloud's business: a client offering them needs the app password for WebDAV and previews anyway.
- **Every other route is Social's own data and takes the Social OAuth token**, with the scope its row names. The Nextcloud session reaches these too, the same two ways, so a client may send either; none of them needs the second sign-in.

The Nextcloud-session routes today — `tests/DocumentationTest.php` holds this table to the routes that refuse every bearer token (`WEB_SESSION_ONLY` in `tests/AppInfo/RouteAuthMatrixTest.php`):

| Method | URL | Why it takes the Nextcloud session |
|---|---|---|
| POST | `/api/v1/media/from-file` | Copies any of the person's own files into an attachment |
| POST | `/api/v1/statuses/{nid}/calendar/import` | Imports a visible Fediverse event into the signed-in user's writable Nextcloud calendar; bearer tokens are refused |

A route added later that touches the person's files belongs in this table and in `WEB_SESSION_ONLY`. Nextcloud's own APIs — WebDAV (remote.php/dav/files/…), previews, the capabilities, app passwords and push registration through the notifications app — take Nextcloud's credentials by nature and are not this app's routes.

One token route reaches further with the session: `DELETE /api/v1/authorized_apps/{id}` lets a bearer token revoke only its own authorization, and signing *another* app out takes the Nextcloud session.

Note that many client API endpoints are annotated `@PublicPage` but call `initViewer(true)` internally, which throws when there is neither a session nor a valid bearer token; those return HTTP 401 with `{"error": "the access_token was revoked"}`.

**A Nextcloud user who has not set up their account here.** Accounts are made when the person chooses a username — on the app's setup page, or on the sign-in page an app opens ([OAuth](#oauth)). Until then, every client route that acts for an account and is reached with that person's Nextcloud session or app password (`OCS-APIRequest: true`) answers **403** with

```json
{"error": "Your account is not set up yet. Open Aloha Social in a web browser and choose your username, then try again.", "code": "account-not-set-up", "setup_url": "https://cloud.example/index.php/apps/social/"}
```

`setup_url` is the absolute address of the app's setup page. 403 rather than 401, because the sign-in is fine and a client reads a 401 as its sign-in having ended; it is also what Mastodon answers for a login that is not usable yet (an unconfirmed email address, a sign-up pending approval). The web app says it in the person's language (`src/utils/serverError.js`). A route anybody may read answers such a caller as it answers anybody. A bearer token never gets this answer: no token is issued without an account, so one whose account is gone is a 401 like a revoked one, and an app token (`client_credentials`) still answers 401 `this token belongs to an app and names no account` where a route acts for an account. The admin API needs no account of the administrator's, and the Bluesky XRPC sign-in takes a Bluesky identity and an app password from the account's settings, neither of which exists before the account.

**Cross-origin requests (CORS).** A browser client served from another origin (Elk, Phanpy, Pinafore and the like) can call the bearer-token API, as on Mastodon: `ClientApiCorsMiddleware` answers the `/api/` routes of `MastodonApiController`, `ClientApiController` and `AdminApiControllerBase`, `POST /api/v1/apps`, `POST /oauth/token`, `POST /oauth/revoke`, `GET /oauth/userinfo` and the NodeInfo documents with `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS`, `Access-Control-Allow-Headers: Authorization, Content-Type, Idempotency-Key` and `Access-Control-Expose-Headers: Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset` — errors included, so a client can read why it was refused. `OPTIONS /api/{path}` answers the preflight with **204** and the same headers, without authentication, and an endpoint this server does not have is a **404** with them; `OPTIONS /oauth/token` and `/oauth/revoke` are answered by the Bluesky preflights below, which allow the same methods and headers a Mastodon client sends. `Access-Control-Allow-Credentials` is never sent and the origin is never reflected, so a browser exposes no answer to a request that carried the session cookie, and such a request is still held to the CSRF check above, which another origin cannot pass. The web app's own session routes (`LocalController`, `ConfigController` and the other controllers outside the three API bases) answer no other origin.

---

## Mastodon-compatible API

### Instance and app metadata

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| OPTIONS | `/api/{path}` | public, no-csrf | — | The CORS preflight of any client-API call from another origin: **204** with the headers described under **Cross-origin requests (CORS)**, for every address it matches, without looking at who asks — the preflight carries no credentials, and the call that follows is authenticated as always. With `GET`, `POST`, `PUT`, `PATCH` or `DELETE` the same address is a **404** `{"error": "Not found"}` with those headers, for an endpoint this server does not have, so a browser client reads that it is missing instead of meeting a network error. Both are in `appinfo/routes.php`, after every other route, and answer only what no route takes. |
| GET | `/api/v1/instance/` | public, no-csrf | — | Mastodon's `V1::Instance` entity, built by `InstanceService::getLocal()` from the live configuration on every request (the stored row is written once at install and only marks that the instance exists). Carries `uri`, `title`, `version`, `short_description`, `description`, `email`, `urls`, `vapid_key`, `stats`, `thumbnail`, `languages`, `registrations` (always `false` — the client API cannot create an account), `approval_required`, `invites_enabled`, `configuration`, `rules` and `contact_account`. `vapid_key` is the stable instance VAPID public key for older Mastodon clients; newer clients can read the same key from `configuration.vapid.public_key`. `urls.streaming_api` is `wss://<host>`; the root proxy rules route Mastodon WebSocket connections to the optional streaming daemon, which serves authenticated user, notification, conversation, list, hashtag and public streams when it is running. `thumbnail` is null when there is no picture. The contact is included only when an administrator selected a current local Aloha Social account; the server stores its owning Nextcloud user id and resolves the actor for this response, while stale/deleted accounts are omitted. `urls`, `stats` and `configuration` are always JSON **objects**, never `[]`. `configuration` reports `statuses` (`max_characters` 5000, `max_media_attachments`, `characters_reserved_per_url`), `media_attachments` (`supported_mime_types`, asked of `CacheDocumentService::filterMimeTypes()` so it cannot drift from what an upload is actually allowed to be, plus `image_size_limit` (`max_size`) and `video_size_limit` (`max_video_size`), in bytes, each lowered to PHP's own upload limit (`\OCP\Util::uploadLimit()`, the smaller of `upload_max_filesize` and `post_max_size`) when that is smaller, since PHP refuses a larger file before the app sees it — and the pixel/frame-rate ceilings), `polls` (`max_options`, `max_characters_per_option`, the expiry bounds), `accounts.max_featured_tags` and `vapid.public_key` (the same stable public key). Clients can fall back to polling when the streaming daemon is unavailable. `stats.status_count` and `stats.domain_count` are counted from the database and memoised for a few minutes (`InstanceService::countedStats()`); `user_count` is the number of Nextcloud users, which is the population the instance is for rather than the number who have answered its setup screen. Nothing is read back from the stored instance row, which holds whatever was true on the day the instance was set up. `rules` comes from one line per rule in the `rules` app value. The `version` field is Pleroma-style — `4.3.0 (compatible; Aloha Social <app version>)`, from `Instance::COMPAT_VERSION` — because clients gate features on it; NodeInfo keeps reporting the real app version. `configuration.translation.enabled` is `true` only where this Nextcloud has a translation provider (`TranslationService`). |
| GET | `/api/v1/instance/rules` | public, no-csrf | — | The instance's rules, as Mastodon's `Rule` entities. They were already served *inside* the instance entity, out of the `rules` app value (`occ config:app:set social rules --value "..."`), so the data was here and the route a client reads it from was a 404. An instance that has set none answers `[]`, which is the truthful answer rather than an error. |
| GET | `/api/v1/instance/domain_blocks` | public, no-csrf | — | The instances this one has decided not to federate with, as `{domain, digest, severity, comment}`. **`[]` unless an admin opts in** with `occ config:app:set social publish_blocks --value 1`: Mastodon publishes the list so somebody choosing a server can see who it will not talk to, and whether *this* server wants that read by anybody is a disclosure decision rather than a default. Only ever the deny list — in allow-list mode the same column holds the instances this server *does* talk to, and publishing that as a block list would be exactly backwards, so that mode answers `[]` too. `severity` is always `suspend` (the only one this list has) and `comment` always `""` (not stored). |
| GET | `/api/v1/instance/extended_description` | public, no-csrf | — | The long form of what this instance is, as `{updated_at, content}`, from the `extended_description` app value. Falling back to the short description the instance entity already carries: an empty page where a server has written a description elsewhere is worse than repeating it. |
| GET | `/api/v1/instance/translation_languages` | public, no-csrf | — | For each language this server can translate *from*, the languages it can translate *to*, as Mastodon's `{"de": ["en", …]}`. Read from the translation provider Nextcloud has, so it is this server's truth rather than a list written here; a server with no provider answers `{}`, which is the same thing `configuration.translation.enabled: false` says. |
| GET | `/api/v1/instance/privacy_policy` | public, no-csrf | — | The server's privacy policy as `{updated_at, content}`. Nextcloud's own, from Theming's privacy policy link, rather than one kept by this app: a server has one privacy policy and a second one here would be a second answer to the same question. Nextcloud stores a link where Mastodon's entity carries text, so the content is that link. **404** where the administrator has published none. |
| GET | `/api/v1/instance/terms_of_service` | public, no-csrf | — | The same, from Theming's legal notice link. **404** where none is set. |
| GET | `/api/oembed` | public, no-csrf, rate-limited | `url` (required), `format` (`json`) | Rich oEmbed for one of this server's own **public** posts. Its iframe targets `/@{username}/{token}/embed`, a minimal page whose only framing exception is scoped to that endpoint. Unlisted, followers-only and remote posts are a **404**; a `format` other than `json` is a **501**, as oEmbed prescribes. |
| GET | `/api/v2/instance` | public, no-csrf | — | The same facts as Mastodon's `V2::Instance`: `uri` becomes `domain`, `thumbnail` an object (null when there is no picture, never `{"url": ""}`), `urls.streaming_api` becomes `configuration.urls.streaming`, and the flat contact/registration fields move under `contact` and `registrations`. It also adds `source_url`, `usage` and `api_versions` — `{"mastodon": 3, "aloha_social": 1}`, the second being this app's own generation (1: `/api/v2/search` honours `account_id` and pages `statuses`) — and folds `urls` and a `translation` block into `configuration`, whose `media_attachments` size limits are v1's, PHP's upload limit included. Newer clients ask for this one first and only fall back to v1 on a 404. |
| GET | `/api/v1/instance/peers` | public, no-csrf | — | The hostnames of every instance this one has heard of, as a bare JSON array — what instance browsers and "about this server" pages read. Derived from the accounts of the cached remote actors, and from the same walk `stats.domain_count` uses, so the list and its size cannot disagree. Public, as Mastodon's is: it says who this instance federates with, not who its users are. Rate-limited per anonymous caller. |
| GET | `/api/v1/instance/activity` | public, no-csrf | — | Twelve weeks of activity, newest first, in Mastodon's shape — every value a string, each week keyed by the unix time its Monday began. `statuses` is counted from the database. `logins` and `registrations` are always `"0"` and cannot be otherwise: an account here is a Nextcloud user, so both belong to the server rather than to this app. Rate-limited per anonymous caller. |
| GET | `/api/v1/preferences` | public, no-csrf (viewer required) | — | The viewer's posting defaults, as Mastodon's Preferences entity: `posting:default:visibility` (the account's `source[privacy]`), `posting:default:sensitive`, `posting:default:language` (null when unset), and the two reading preferences. `reading:expand:media` is **real**: it is this account's choice about media somebody marked sensitive, or what the instance does for somebody who has not chosen (`nsfw_policy`). Its three values are PeerTube's three NSFW policies under the names Mastodon already has for the same three states — `show_all` is PeerTube's *display*, `default` its *blur* (covered, blurhash showing, one press away) and `hide_all` its *hide* (not drawn, and no button to draw it: opening the post is what it takes). `reading:expand:spoilers` is still Mastodon's `false` — a content warning is a different thing from sensitive media and this app keeps no preference about it. A client that cannot read this guesses, which is how it ends up posting publicly for somebody whose default is followers-only. **Nextcloud extension:** `notifications:delivery` echoes the account's notification delivery setting, the same object `GET /api/v1/social/notification_delivery` answers; read-only here, written there. `reading:hide:ai` (bool) echoes whether the account hides posts made with AI, the switch `GET /api/v1/social/ai_content` answers and `PATCH` sets; read-only here too. `reading:hide:counts` (bool) echoes whether the like, boost and follower numbers are hidden (`/api/v1/social/counts`), read-only here as well. |
| PUT | `/api/v1/preferences` | public, no-csrf (viewer required) | `expand_media` (`show_all`, `default`, `hide_all`, or `''`) | **Nextcloud extension, not a Mastodon route** — Mastodon has no write for preferences and sets its own reading preferences on its web front end. The values are Mastodon's all the same, so a client that reads the route above and one that writes here agree about what the three words mean. `''` is a fourth thing and not a fourth policy: it puts the account back to *following the instance*, which is different from choosing what the instance happens to do today — an administrator who later changes the default moves everybody who is following it and nobody who has chosen. Answers with the effective policy, the `choice` behind it (`''` for following the instance) and the `instance` default. Anything else is a **422**. |
| GET | `/api/v1/apps/verify_credentials` | public, no-csrf | — | `{"name", "website", "scopes", "redirect_uris", "vapid_key"}` of the client behind the bearer token (`scopes` and `redirect_uris` are lists, as on Mastodon 4.3); falls back to `{"name": "Aloha Social", "website": "https://github.com/alohasocial/social/"}` when the caller is the app's own session. `vapid_key` is the instance's stable public VAPID key. A missing or revoked token is a 401. |
| GET | `/api/v1/push/subscription` | public, no-csrf (viewer required, `push` scope) | — | The subscription for the caller's bearer token as `{id, endpoint, standard, alerts, server_key, policy}`. A token without a subscription receives 404. |
| POST | `/api/v1/push/subscription` | public, no-csrf (viewer required, `push` scope) | `subscription.endpoint`, `subscription.keys.p256dh`, `subscription.keys.auth`, optional `subscription.standard`; `data.alerts`, `data.policy` | Creates or replaces the subscription belonging to this bearer token. The server checks public HTTPS endpoint resolution, validates the Web Push keys, and encrypts the endpoint, keys and token material at rest. Returns the subscription entity, including the public `server_key` and `policy`; the bearer token is never returned. |
| PUT | `/api/v1/push/subscription` | public, no-csrf (viewer required, `push` scope) | `data.alerts`, `data.policy` | Updates only alert preferences and policy for the caller's existing subscription. A token without a subscription receives 404. |
| DELETE | `/api/v1/push/subscription` | public, no-csrf (viewer required, `push` scope) | — | Removes the caller's subscription and returns `{}`; deleting an absent subscription is also successful. |
| GET | `/api/v1/custom_emojis` | public, no-csrf | — | The emoji this instance publishes, as Mastodon's `CustomEmoji`: `shortcode`, `url`, `static_url`, `visible_in_picker`, and `category` when one was given (omitted rather than null, which is how a client groups them). Only the ones marked visible are listed — that is what the field means, and a picker is what reads this route; a hidden emoji still renders wherever its shortcode is written. `static_url` is the same URL as `url`: a second, still rendering of every upload does not exist, and a `static_url` pointing at nothing would be worse than one pointing at the picture. Managed with `occ social:emoji`. *Remote* custom emoji are unaffected and always worked: `Emoji` tags on incoming statuses and actors are served in the `emojis` field of the status and account entities. |
| GET | `/emoji/{shortcode}` | public, no-csrf | — | The picture behind a shortcode, with its stored media type and a day of cacheability (shared caches included — the route answers everybody the same bytes). Unauthenticated for the same reason `/media/{uuid}` is: this is what a remote server dereferences out of an `Emoji` tag on a post it received, and it has no token of ours to present. An emoji is published by definition. A shortcode nobody published is a **404**. |
| GET | `/api/v1/trends/tags` | public, no-csrf | `limit` (10, capped at 20), `period` (`1h`, `12h`, `1d` — the default —, `3d`, `10d`; anything else falls back to the default) | The hashtags used most on this instance in that window, as Mastodon `Tag` entities. The counts are the ones the cron job already keeps for every hashtag (`HashtagService::manageHashtags()`), so this is a read of stored data rather than a query over the stream — specifically the sortable `trend_*` columns, which `Version1000Date20260910000003` backfills on upgrade because the cron alone would never have filled them for hashtags whose counts had stopped moving. `history` carries a single bucket for the window that was asked for, and `accounts` in it is always `0`: this instance counts uses, not distinct accounts. Hashtags unused in the window are left out. |
| GET | `/api/saved_searches/list.json` | public, no-csrf | — | **Not implemented.** Initialises the viewer, then always returns `[]`. |
| GET | `/.well-known/nodeinfo/2.0` | public, no-csrf | — | NodeInfo 2.0 document: `version`, `software.name` (`nextcloud-social`), `software.version`, `protocols: ["activitypub"]`, `services`, `usage` (`users.total`, `localPosts`), `openRegistrations` and `metadata` (`nodeName`, the instance title, and `nodeDescription`). Falls back to node name `Aloha Social`, the installed app version and `usage: {"users": {}}` — an object, as the schema requires — if no local instance row exists. |
| GET | `/.well-known/nodeinfo/2.1` | public, no-csrf | — | The same document under the 2.1 schema, which adds `software.repository` and `software.homepage` (both the app's repository). Everything else is identical to 2.0, because that is the whole of what 2.1 adds. Reachable since 0.26.5: the method existed and was tested from the day it was written, but carried no route attribute, so no URL was registered for it and the discovery document named only 2.0. |

### Accounts

A Status entity carries **`view_count`** — how many accounts here have opened that post's own page — on the **author's own copy only**, and `null` on everybody else's: how many people read a post is the author's business. What is counted is narrow on purpose: a post's own page (`GET /api/v1/statuses/{nid}`), opened by a signed-in account that is not the author, one row per (post, viewer). Not an impression in a timeline, because a post scrolled past has not been read and counting it would both make the number meaningless and write a row for every post on every page of every timeline. It is never federated: a count that arrived from another server would be that server's readers added to this one's, meaning neither.

A Status entity's **`uri` and `url` are two different things**, as they are in Mastodon's: `uri` is the ActivityPub object, `url` is the page a person can open. They used to be the same value here, which sent "open original" to a JSON document for every remote post. Loops makes the difference plain — its ids live under `/ap/` and a video is only watchable at `loops.video/v/<id>` — but Mastodon, Pixelfed and PeerTube all send a distinct `url` too. It is read off the wire, kept in the row's `details` (`social_stream` has no column for it), and falls back to the id, so a local post — whose id *is* its page — is unchanged. Only `http`/`https` count: `AS_URL` used to validate with `parse_url()`, which parses `javascript:alert(1)` into a scheme and a path quite happily, and this field is rendered as a link by every client that reads it.

An incoming **`interactionPolicy.canQuote`** is honoured. GoToSocial defined the field, Mastodon 4.5 reads it and Loops publishes it on every video; `automaticApproval` naming the public collection means anyone may quote, anything narrower is treated as "ask the author" and quoting is refused here rather than sent to a server that will refuse it after the reader has already been shown their own quote. A post that carries no policy is decided by its visibility, as before. **`canReply`, `canAnnounce` and `canLike` are honoured too**, by the same rule and for the same reason, except that a narrower list is still a yes for whom it names: `automaticApproval` naming the public collection means anyone may; naming the reader, the author's followers collection when the reader follows the author, or the author's following collection when the author follows the reader means that reader may — GoToSocial writes the policy of every direct message and followers-only post that way and approves those interactions itself when they arrive — and anybody a post mentions may reply to it, as GoToSocial lets them whatever its policy says. Everybody else is treated as "ask the author", and the action is refused here rather than sent to a server that will drop it after the reader has been told it went out. What the author allows the reader rides on the status as `interaction_policy` — `{"reply": true, "like": false}` — so a client can leave a button out rather than draw one that will fail. It is **absent** for a local post, where the policy is this instance's to apply when the interaction arrives, and for the many servers that publish no policy at all: an absent key means "the author said nothing", which means yes. Taking an interaction back is never refused, whatever the policy says now — an `Undo` is how this instance stops having sent one.

A Status entity also carries **`archived`**, which is true only on the author's own archived posts — nobody else is ever handed one, because no list this server builds contains one.

A Status entity also carries **`video_card`** — **Aloha Social's own**, the same few facts about every video post whatever it arrived as, which is what the web interface's Videos page draws its cards from. `null` on every post that is not a video; a video is a post that arrived as a PeerTube `Video` (it has a `video` block) or carries an attachment served as `video/*`, the same rule the dislike button follows. On a boost it is on the boosted post in `reblog`. Every key is always present:

| Field | Type | What it is |
|---|---|---|
| `title` | string | The video's own title (`video.title`); else the content warning, so the words behind one are not on the card either; else the first line of the post as plain text, markup and entities resolved. At most 120 characters. `''` for a post with no words at all. |
| `duration` | integer or null | How long it runs, in whole seconds: `video.duration`, else the video attachment's `meta.duration`. `null` when neither says. |
| `thumbnail` | string or null | A picture of it: the video attachment's `preview_url` — the poster frame of an upload here, the thumbnail a PeerTube video publishes. `null` when there is none, including when `preview_url` is the video file itself, as it is for an older upload with no poster. |
| `views` | integer or null | How many times it was watched. For a video posted here, this server's own count: one view per viewer (the account, or the session of somebody not signed in) per video and day, after a few seconds of playback (`POST /api/v1/statuses/{nid}/view`), the author not counted; `0` when nobody has watched it yet. For a video from elsewhere, as its origin counts it (`video.views`). `null` when nobody counted — never invented, and never this instance's `view_count`, which only the author is told — and `null` for a reader who hides the numbers (`/api/v1/social/counts`). |
| `live` | boolean | A live broadcast (`video.live`). |
| `category` | string or null | Its category, as its origin names it (`video.category`); `null` when it has none. |
| `published` | string | When the video was published, in `created_at`'s format: `video.originally_published_at` where it is there and can be read, else `created_at`. |

The channel is the status's own `account` and is not repeated. The attachment that is the video is the first of `type` `video` in `media_attachments`, else the first served as `video/*`; `duration` and `thumbnail` come from it. Mastodon clients ignore the key. No query parameter filters on these fields: the Videos page chooses among the videos it has loaded.

A Status entity also carries **`watch_progress`** — **Aloha Social's own** — `{position, duration, updated_at}`: where in a video the reader stopped, in seconds, out of how many, and when it was last moved (in `created_at`'s format, or `null`). On the statuses `GET /api/v1/videos/continue` answers, and on a video read on its own with `GET /api/v1/statuses/{nid}` by a signed-in reader who began it, which is where a player starts it again; `null` on every other list. It is the reader's own and is never federated.

The **`video`** block — what a post that arrived as a PeerTube `Video` (or was posted here with a video title) says about the video, `null` on every other post — carries two things that are this server's rather than the origin's. On a video posted here, `views` is the count described under `video_card` above. And each of its subtitle tracks, `captions: [{language, url}]`, has as its `url` this server's `/media/captions/{nid}/{index}.vtt`, never the origin's address: a page may not load a track from another host, and a reader turning subtitles on is not announced to it. A reader who hides the numbers is sent the block without `views`.

A Status entity's **`muted`** is real and per viewer: `true` when the viewer muted the conversation the post belongs to (`POST /api/v1/statuses/{nid}/mute`, below), else `false`; anonymous readers always get `false`. It used to be hard-coded `false`, so no client could show or toggle the state. It is computed for a whole page in one pass by `StreamRequestBuilder::markMutedConversations()`: the page's reply chains are walked up to their roots and compared with the viewer's muted roots in `social_convo_state`. Those roots are memoised for the request, and every mute or unmute drops the memo first (`ConversationsRequest::setMuted()`), so the status a mute answers with already says `muted: true`.

**Two of the four profile fields are also sent as their own keys.** An Account
entity carries `pronouns` and `support_link` beside `fields`. Neither is a
field of its own and deliberately so: a pronoun row is what people already
write, it federates as a `PropertyValue` that every other network shows, and a
property only this app understood would be a pronoun nobody else could read.
What this app adds is *recognising* the row — matched case-insensitively
against the spellings people use (`Pronouns`, `Pronomen`, `pronoms`, … and
`Support`, `Donate`, `Sponsor`, …) — so that a client can draw the pronouns
beside the name and the support address as a button without knowing any of
them. `pronouns` is `''` when the value is longer than 40 characters (a
sentence in the wrong row), and `support_link` is `''` unless the value is an
`https://` URL, because it is drawn as a button.

**An Account entity says where it is on Bluesky.** `bluesky` is `null` for
an account that is not on Bluesky; for a Bluesky account read here it is
`{handle, did, url, native: true, verified, verified_by, verified_by_bluesky,
trusted_verifier}` — whether Bluesky shows the account as verified (a
trusted verifier vouched for it and the AppView judges that valid), the DIDs
of the verifiers, whether Bluesky's own account is one of them, and whether
the account is a trusted verifier itself. A local account's carries its own
handle and DID where the controllers that know them attach them.

**An Account entity says whether this instance verified it.**
`verification` is `null` for an account the instance did not verify; for one
it did (`VerificationService`), it is `{by, issuer, created_at}`: the name
the check is given in (the administrator's verifying account, or the
instance's own name when none is chosen), the DID that issued the published
`app.bsky.graph.verification` record (`''` when none was: no verifying
account, Bluesky off, or the account has no DID), and when. The app draws one
check beside the name of an account verified either way — by this instance
or by the verifiers Bluesky trusts (`bluesky.verified`) — labelled with who
verified it.

**An Account entity says whether its pictures are placeholders.**
`avatar_default` and `header_default` are `true` when `avatar` or `header` is
a placeholder rather than a picture the account set: Nextcloud's own avatar
route for a local account without an uploaded picture, the app icon for a
remote account whose picture is missing or not cached yet, and
`img/header-missing.png` (a plain 1500×500 PNG, as Mastodon's `missing.png`)
for an account without a banner. They are on every Account entity,
`verify_credentials` and `update_credentials` included; `avatar` and `header`
stay URLs, so a client that does not know the keys draws what it drew before.

**An Account entity names the Nextcloud user of a local account.**
`nextcloud_user` is the user id a local account belongs to, which its username
need not be: the username is chosen when the account is made. The web app
draws the account's face and links its Nextcloud profile page (`/u/{uid}`) by
it. It is `null` for a remote account, a team account and a channel, and, for a
reader who is not signed in, for an account whose username is not its user id,
so an account named apart from its login does not give the login away. For the
same reason a local account's `avatar` — and the `icon` of its actor document —
is this app's avatar route of the username, `/apps/social/avatar/{username}/128`
(with `?v={version}` once the picture is cached), never Nextcloud's own
`/avatar/{user id}/…`; an icon stored before under Nextcloud's route is
published under this one, keeping its version.
Without them a client could only guess from the shape of the URL, which
depends on URL rewriting, the app folder and the size argument. A local
account's header that is its own avatar — what the header used to fall back
to, kept by the cached copy — counts as no header and is removed from the
cache by the `ClearAvatarHeaders` repair step.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/accounts/verify_credentials` | public, no-csrf | — | The viewer's `Person` actor serialised in local format, with `source` and Mastodon's `role` (see [Admin API](#admin-api-mastodon) for what the role says). 401 `{"error": ...}` when unauthenticated. |
| PATCH | `/api/v1/accounts/update_credentials` | public, no-csrf (viewer required, `write` scope) | JSON, form or multipart body; `display_name`, `note`, `locked`, `discoverable`, `indexable`, `bot`, `source[privacy]`, `fields_attributes`, and `avatar` / `header` (multipart) | Sets the display name, the bio (`note`, at most 500 characters, stored as plain text and rendered to HTML on the way out — an absent `note` leaves the stored one alone rather than clearing it), the profile picture and banner, whether new followers need manual approval (`manuallyApprovesFollowers`), whether the account may be listed in directories and indexed for search, whether it is automated (`bot`, which also decides whether the actor document says `Service` or `Person`), the default audience for new posts, and the profile metadata fields (at most four name/value pairs, both halves required; a list or an object keyed by index — a fifth pair, and a pair with an empty half, are dropped without an error, and `[]` clears the table). Every field is optional and only what was sent is written, so a client that edits one thing leaves the rest alone. **`display_name`, `avatar` and `bot` used to be accepted and dropped**, which meant a profile editor — which sends the whole form in one PATCH — got a 200 and showed the old name and picture. The name and picture belong to the Nextcloud account, so they are written there and the actor cache is refreshed; a backend that owns either (LDAP, SAML, anything provisioned elsewhere) makes the request a **422** rather than a silent success. A multipart PATCH — which is how clients send this route whenever a picture is in it — is read like a multipart POST (`MultipartBodyService`); it used to reach the controller unread, so every field and the picture were missed under a 200. A multipart body that cannot be read, and a picture that was sent and did not arrive (larger than the server takes — the error names the limit, `the avatar is larger than this server accepts (2 MB)` — or cut off), are a **422**; a picture the server itself could not receive (no temporary directory, a failed disk write) is a **500** naming that problem; in each case nothing else in the request is written. **A save is all or nothing, or a 200 with what it stored**: everything that can be refused — the pictures' arrival, an avatar that is not a JPEG, PNG, GIF or WebP, a name or avatar the backend owns, an unknown `source[privacy]` — is checked before anything is written, and the parts are then written banner first (its bytes are only judged as they are stored, so a refused banner still leaves everything unwritten), then avatar, display name, bio, audience, `locked`, the flags and the fields. A part that fails after the first was stored is logged at warning level and the rest is still written; the answer is a 200 whose entity shows what was stored, never a 500 over half a profile. A display name survives Nextcloud's own profile listener failing after the backend stored it — core re-validates the profile's `fediverse` property on every change by fetching that handle's WebFinger over HTTPS, which fails on a server that cannot reach itself by its own name; that failure is logged and the name kept. Other Mastodon profile fields are still ignored. Returns the refreshed account entity, which is the one place besides `verify_credentials` that carries `source`. |
| DELETE | `/api/v1/profile/avatar` | public, no-csrf (viewer required, `write` scope) | — | Removes the account's picture, leaving Nextcloud's generated initials, and answers the refreshed account entity. A local account's picture is this app's avatar route of the username with the avatar's version in the address (`…/apps/social/avatar/{username}/128?v={version}`), in every Account entity and in the actor document, so the new one shows at once and a server that follows the account fetches it again; the change is told to the followers and to Bluesky as an `Update`, whether it was made here or in Nextcloud's own settings. (A remote account whose picture is not cached yet shows the app icon.) `update_credentials` can only replace one picture with another — multipart has no way to send "none" — so without this a client can offer "change picture" and not "remove picture". The avatar is the Nextcloud account's, so a backend that owns it (LDAP, SAML) makes this a **422** rather than a silent success. Removing a picture that was never set is not an error. |
| DELETE | `/api/v1/profile/header` | public, no-csrf (viewer required, `write` scope) | — | Removes the banner and federates the actor `Update`, so the profile does not keep its banner on every other server. Answers the refreshed account entity. The cached picture is left for the document sweep rather than deleted under readers who are mid-request on its URL. |
| GET | `/api/v1/follow_requests` | public, no-csrf (viewer required) | `limit` (default 40, at most 80), `max_id`, `min_id` | Accounts with a pending follow request towards the viewer, newest request first, serialised in local format. Paged as Mastodon pages it, with a `Link` header (`rel="next"` while a page came back full, `rel="prev"`); as in Mastodon the cursor is the follow request's, not the account's, and is to be taken from that header. It is the request's place in the order — its creation second and the row's key — so requests from the same second are neither skipped nor repeated, and it stays valid when the request it names has been answered in the meantime. A cursor this route did not write returns an empty page. |
| POST | `/api/v1/follow_requests/{id}/authorize` | public, no-csrf (viewer required, `follow` or `write` scope) | — | Accepts the pending follow request from account `{id}` (numeric id or full actor id; accepts slashes): federates the `Accept` and marks the follow accepted. Returns the updated relationship entity; 404 when no request is pending. |
| POST | `/api/v1/follow_requests/{id}/reject` | public, no-csrf (viewer required, `follow` or `write` scope) | — | Rejects the pending follow request from account `{id}`: federates a `Reject` and deletes the follow row. Returns the updated relationship entity; 404 when no request is pending. |
| POST | `/api/v1/accounts/{id}/remove_from_followers` | public, no-csrf (viewer required, `write:follows` or `follow` scope) | — | Removes account `{id}` from the viewer's followers (numeric id, actor id or handle; accepts slashes): federates a `Reject` of their follow and drops the row, which is the same activity a refused follow request sends — to the other server a follow rejected and a follow withdrawn after being accepted are one statement. This is **not** a block and **not** an unfollow: whether the viewer follows them, and every block and mute either way, are left as they were. An account that does not follow the viewer is not an error, so a client that lost the answer and retried gets the same one. Returns the updated relationship entity. |
| GET | `/api/v1/blocks` | public, no-csrf (viewer required) | `limit` (40, capped at 50) | Accounts the viewer has blocked. One page, and **no `Link` header**: neither route takes a cursor, so the "next" page a header advertised was the page just sent, and a client paging on it scrolled the same block of accounts for ever. |
| GET | `/api/v1/mutes` | public, no-csrf (viewer required) | `limit` (40, capped at 50) | Accounts the viewer has muted. Same shape, and no `Link` header, for the same reason. |
| GET | `/api/v1/accounts/relationships` | public, no-csrf | `id` (array, default `[]`) | Relationship entries from `FollowService::getRelationships()`. Sent as `id[]=…` on the wire. The parameter carries a default because the dispatcher fills it in before the handler's own error handling can run: a request with no `id[]` at all used to produce a Nextcloud HTML page instead of `{"error": …}`. With none given the answer is an empty list. |
| POST | `/api/v1/accounts/{id}/follow` | public, no-csrf (viewer required, `follow` or `write` scope) | `notify`, `reblogs` | Follows the account (`{id}` is the numeric id or a full actor id; accepts slashes). A locked target leaves the relationship in `requested` until they decide. `notify` is the bell on a profile — a subscription separate from the follow, so that every post by that account raises a `status` notification; **absent means "leave it as it is"**, because a client re-following to change something else must not silently turn the bell off. It is reported back as `notifying` on the relationship, which was hardcoded `false` before, so a client that had turned the bell on was told it was off and drew it that way. A reply is not one of these notifications: the bell means "tell me when they post", and a thread somebody else started is not that. `reblogs` is the other switch Mastodon sends with a follow — `false` keeps that account's **boosts** out of the home and list timelines while leaving their own posts where they are ("I want to read you, not what you pass on"), and it too is left alone when absent. It is reported back as `showing_reblogs`, which was hardcoded `true` before, so a client that had turned the boosts off was told they were on. Stored as a row in `social_actor_relation` only when the answer is *no*, and applied as a predicate of the timeline query rather than by dropping rows after the page was read. Returns the updated relationship entity. |
| POST | `/api/v1/accounts/{id}/unfollow` | public, no-csrf (viewer required, `follow` or `write` scope) | — | Unfollows (federates `Undo{Follow}`). Returns the updated relationship entity. |
| POST | `/api/v1/accounts/{id}/block` | public, no-csrf (viewer required) | — | Blocks the account (`{id}` is the numeric id or a full actor id; accepts slashes). Severs the follow relationship in both directions and, unless `federate_blocks` is `0`, sends a `Block` activity to the account's server. Returns the updated relationship entity. |
| POST | `/api/v1/accounts/{id}/unblock` | public, no-csrf (viewer required) | — | Lifts a block (federates `Undo{Block}` under the same setting). Returns the updated relationship entity. |
| POST | `/api/v1/accounts/{id}/mute` | public, no-csrf (viewer required) | `notifications` (true), `duration` (0) | Mutes the account — purely local, never federated. With `notifications=true` (default) the account's notifications are hidden too. `duration` is seconds until the mute lifts itself; `0` is "until it is lifted by hand", and re-muting with `0` drops the expiry a previous timed mute left behind. Returns the updated relationship entity, whose `mute_expires_at` says when a timed mute runs out. |
| POST | `/api/v1/accounts/{id}/unmute` | public, no-csrf (viewer required) | — | Lifts a mute. Returns the updated relationship entity. |
| GET | `/api/v1/accounts/familiar_followers` | public, no-csrf (viewer required) | `id` (one or more account ids) | For each named account, which of the people the viewer follows also follow it — the "followed by X and 3 others you know" line on a profile. Answers `[{id, accounts}]` with at most ten accounts each, and at most twenty ids per call (Mastodon's caps). The overlap is found by one self-join in the database rather than by intersecting two follower lists in PHP: either list can be tens of thousands of rows. The viewer's own profile answers an empty list, as Mastodon's does. |
| GET | `/api/v1/accounts/search` | public, no-csrf (viewer required) | `q` (required), `limit` (40, capped at 80), `resolve` (false), `following` (false) | Mastodon's account search — what a composer calls to complete a `@handle` as somebody types. `/api/v2/search` answers accounts too, but no client uses it for autocomplete, so mention completion failed in every client that offers it. Searches the cached actors; with `resolve` it also asks the address or handle's own server, which is what makes completing a handle from another instance work at all, and adds the Bluesky accounts the AppView's typeahead finds for a dotted name, each stored so it has an id. Without `resolve`, as in Mastodon, no other server is asked: a client's autocomplete sends it once per keystroke. A whole `user@host` that is not held here is then queued for a background lookup, and a later search finds it. `following=true` narrows the search to accounts the viewer follows (accepted follows only), which is what a client asks when completing a reply rather than searching, and what the web UI's direct-message recipient box asks for the people it lists first. The search itself is narrowed, so `limit` counts followed accounts, and no unknown handle is fetched from its server for it; what `resolve` finds is kept only when the viewer follows it. An empty `q` is an empty list, not an error. Registered **before** `/api/v1/accounts/{id}`, which accepts slashes and would otherwise swallow it. Rate-limited per user and per anonymous caller. |
| GET | `/api/v1/accounts/{id}` | public, no-csrf | — | One account, by the numeric id every API entity emits, an `@user` / `user@host` handle, a bare local username, or the actor's ActivityPub id — all resolved through `resolveTargetAccount()`. Returns the account entity in local format; an unknown reference is a 404. `{id}` accepts slashes (`requirements: .+`), so this route is registered **last** of the /api/v1/accounts routes and must stay there — otherwise it swallows `lookup`, `relationships`, `verify_credentials` and the `{account}` sub-routes. Rate-limited per user and per anonymous caller. |
| GET | `/api/v1/accounts/lookup` | public, no-csrf | `acct` (required) | The account behind a handle, from what is already cached — this route never fetches from another server. A leading `@` is stripped. 404 when the handle is unknown here, 422 when `acct` is missing. Rate-limited per user and per anonymous caller. |
| GET | `/api/v1/accounts/{account}/statuses` | public, no-csrf | `limit` (20), `max_id` (0), `min_id` (0), `since_id` (0), `pinned` (false), `only_media` (false), `media_type` (''), `only_short` (false), `exclude_reblogs` (false), `exclude_replies` (false), `tagged` ('') | Statuses of `{account}`, which may be the numeric id or a handle, answered from what is stored here: its posts and, as on Mastodon, its **boosts**, each a status by the account whose `reblog` is the boosted post, in the order the account made them and paged with them. `exclude_reblogs=true` leaves the boosts out; so does any narrowing to a kind of post (`only_media`, `media_type`, `only_short`, `only_video`, `only_news`) and `tagged` — as on Mastodon, where a boost carries no attachments and no tags of its own. A boost of a post the reader may not see is left out, not served without it. `exclude_replies=true` leaves out the account's replies to other accounts and keeps its replies to its own posts (threads) and its boosts; a reply whose parent is not stored here counts as one to another account. `tagged` keeps the account's posts carrying that hashtag (with or without `#`, any case). Both narrow the page query, so pages stay full and `max_id` walks the narrowed list. The **first page** (no `max_id`, `min_id` or `since_id`) asked by a signed-in caller also queues a background sync of a remote account's outbox (`Cron\SyncRemoteTimeline`, at most once per 15 minutes per account), so a profile opened for the first time starts with what is stored. Exhausted later pages can queue the saved outbox continuation. Pending ActivityPub imports set `X-Social-Filling: 1`, `X-Social-Profile-Filling: 1` and `X-Social-Remote-Profile-Filling: 1`; the web app checks for completion for up to five minutes, initially every two seconds and then every five seconds. Anonymous callers do not trigger outbox imports. The import uses the ordinary ActivityPub parser for Notes, polls, Articles, Pages, Audio, Video and Events, retaining attachment metadata while the media worker caches the files. Updates use the inbox edit handler with author and timestamp checks; an Update can also discover a post not previously stored. A Bluesky profile instead reads its public author feed in bounded AppView pages and returns the same locally stored status entities; while more pages are needed to fill the visible page, or an AppView read temporarily fails, it sets `X-Social-Filling: 1` and `X-Social-Profile-Filling: 1` so the web app retries from the saved AppView cursor at a steady two-second cadence. `{account}` accepts slashes (`requirements: .+`). With `pinned=true` it returns that account's pinned posts, newest pin first, and skips the sync and the paging parameters. Pinned posts are read through the same visibility filter as any other status, so an anonymous caller sees only the public ones — this route is a `#[PublicPage]`, and reading them unfiltered served a pinned followers-only post in full to the internet. A page with remote counts still due carries `X-Social-Filling: 1`; the web app fetches the page again until the background count refresh stamps it. `only_media` is Mastodon's own parameter and keeps just the posts carrying an attachment; `media_type` (`image`, `video`, `audio`) is a **Aloha Social extension** narrowing that to one kind, which is what the Photos and Videos tabs of a profile ask. It implies `only_media`, and anything that is not one of the three kinds an attachment can be is read as no preference. `only_short` keeps the account's short videos, as on the timelines (see `/api/v1/timelines/{timeline}/`), and wins over the other two. Sends a `Link` header. |
| GET | `/api/v1/accounts/{account}/followers` | public, no-csrf | `limit` (20), `max_id` (0), `min_id` (0), `since_id` (0; `since` is accepted for it too) | Followers of `{account}` (numeric id or handle). The accounts this server knows follow it come first, paged by their ids with a `Link` header as always. For an account on another server and a signed-in caller, the ones its own network lists follow after the last of them: the actor's `followers` collection as its server describes it (a few pages), or, for an account on Bluesky, what the AppView lists — read in the background (`FollowListService`, at most every ten minutes per account and list) and kept an hour; accounts not cached here yet are fetched in the background too and appear on a later look. Nobody is listed twice, and an account with no numeric id is left out. A page that reaches into those accounts is continued by the `max_id` of its last account (its `Link` header has only `next`, and none at the end). While that read was just asked for, the answer carries **`X-Social-Filling: 1`** (this app's own); the web app looks again a few seconds later. An account whose server keeps the list to itself (Mastodon's "hide your social graph": the collection's pages are refused, or only its size is given) has an empty list here too. An anonymous caller gets what is known here. |
| GET | `/api/v1/accounts/{account}/following` | public, no-csrf | `limit` (20), `max_id` (0), `min_id` (0), `since_id` (0; `since` is accepted for it too) | Same as above for the accounts `{account}` follows: its `following` collection, or what Bluesky lists it as following; `X-Social-Filling: 1` the same way. |

A `Relationship` carries `id` as a **string**, like every other id on the wire: a client that declares `id: String` (Ivory, Mona, anything built on Swift's Codable) could not decode the integer this used to be, so follow/block/mute button state broke after every action that returns one. `note`, `languages` (always `null` — there is no per-account language filter) and `requested_by` are also present; `requested_by` reports a pending incoming follow — the same rows `/api/v1/follow_requests` lists — and `showing_reblogs` is `true`, which is what the home timeline actually does. `note` carries the viewer's private note about the account, written through `POST /api/v1/accounts/{id}/note` (see below) and readable by nobody else. `mute_expires_at` is this app's own addition: an ISO-8601 date while a timed mute is running, `null` otherwise. Mastodon carries it on the *account* entities of `GET /api/v1/mutes` and not on the relationship, which leaves a client that has just taken a timed mute with no way of being told for how long; it is reported here as well, where every client already looks after a mute. Not to be confused with `note` on an *Account*, which is the bio and is implemented (see `update_credentials` above).

### Search (Mastodon v2)

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/search` | public, no-csrf (viewer required) | `q` (required), `type`, `limit` (20, capped at 40), `resolve`, `account_id`, `offset`, `max_id`, `min_id` | Mastodon's v1 search; identical to `/api/v2/search`, which it delegates to. This path used to be the app's own web-UI search, which answered a client with a Nextcloud envelope and a `content` key — a 200 a client could make nothing of. That search moved to `GET /local/v1/search`. |
| GET | `/api/v2/search` | public, no-csrf (viewer required) | `q` (required), `type` (`accounts`/`statuses`/`hashtags`, empty = all), `limit` (20, capped at 40), `resolve`, `account_id`, `offset`, `max_id`, `min_id` | Mastodon's search entity: `accounts` (URI + name search over cached actors; with `resolve`, an address or handle this instance has never seen is looked up on its server and Bluesky's typeahead adds what it finds, without it nothing is asked of another server and an unknown address or whole `user@host` is queued for a background lookup that a later search finds), `statuses` (the viewer-bounded full-text search: every word of `q` must be in the post and the last may be the beginning of a word, matched case-insensitively against the post's text without its markup), `hashtags` (Tag entities with an empty `history`; a hashtag of a public post can be found as soon as the post is stored, before the trends cron has counted it). `resolve` asks the server to go and get something it has never seen, which is how a reader who pasted a link to a remote post can reply to it or boost it here at all. It only ever fires for a `q` that is an `http(s)` address and only when the local search found nothing; the document fetched has to claim the very address it was fetched from (a document is evidence about itself and nothing else) and has to be a `Note` or a `Question`, or it is refused and the answer is empty. The author is cached before the post is stored, so it renders as theirs. A failed lookup of an address or handle is not repeated for ten minutes. The route requires a viewer, so no anonymous caller can use it to make this instance fetch for them, and it is rate-limited both per user and per anonymous caller. `account_id` (the numeric id, a handle or an actor URL of an account this instance holds; nothing is fetched) narrows `statuses` to that account's posts, still within what the viewer may see; `accounts` and `hashtags` are unaffected, as in Mastodon, so a client that wants the posts alone sends `type=statuses` as well. An `account_id` this instance does not know answers with no posts rather than an error. `offset`, `max_id` and `min_id` page `statuses`, narrowed or not: `offset` skips that many answers and reaches 400 deep (a page past that is empty), `max_id`/`min_id` keep the posts whose id is below/above them, and the order stays newest first; one that is not a number is ignored. `accounts` and `hashtags` are not paged. `resolve` fetches only on the first page of a search that is not narrowed to an account. Clients detect this behaviour by `api_versions.aloha_social >= 1` on `/api/v2/instance`. The first page of a search of posts that is not an address and not narrowed to an account also has the posts matching it beyond this server read in the background (`PostDiscoveryService`, at most every ten minutes per term and reader): Bluesky's, asked as the reader where they are on Bluesky (the fediverse has no public search of posts). They are stored, so the same search finds them the next time; the answer says **`X-Social-Filling: 1`** while that read is new, and the web app asks once more a few seconds later. Rate-limited per user and per anonymous caller. |

### Statuses

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| POST | `/api/v1/statuses` | public, no-csrf (viewer required, `write` scope) | Body (JSON or form-encoded): `status`, `visibility`, `media_ids` (array), `in_reply_to_id`, `quote_id`, `spoiler_text`, `sensitive`, `post_as`, `reply_policy`; Aloha Social extension `event` (`name`, `start_time`, optional `end_time`, optional `location`). Header: `Idempotency-Key` | Creates a post. The body is read from `php://input` and parsed by `Content-Type`; a body that declares itself JSON and is not valid JSON is a **422**, not the HTML error page a `TypeError` used to produce. An `event` creates an ActivityStreams `Event` with a required title and valid start time; it cannot be combined with a poll and is preserved when scheduled or held for moderation. `start_time` and `end_time` are ISO 8601 values normalised to UTC. Only `status`, `visibility`, `media_ids`, `in_reply_to_id`, `quote_id`, `poll`, `spoiler_text` and `sensitive` affect the created post — `sensitive` is stored in its own column and read back (a non-empty `spoiler_text` also reads as sensitive); `spoiler_text` is stored as plain text, so a warning containing an apostrophe stays an apostrophe on the wire. A `poll` is held to the limits `configuration.polls` announces, as on Mastodon: blank options are left out, and fewer than two options, more than `max_options` or an option longer than `max_characters_per_option` is a **422** rather than a poll cut down to what fits. `visibility` maps to the stream type (`public`, `unlisted`, `followers`/`private`, `direct`); **omitting it takes the account's default** (`source[privacy]`, public unless the account set otherwise), and a value this app does not know is a **422** rather than a post silently addressed to nobody. A reply to a `direct` post is `direct` whatever `visibility` says, as on Mastodon — the conversation was addressed to named people — and its attachments stay private with it. An `in_reply_to_id` that names a post the writer may not read is answered as one that names nothing: **404** `The post you are trying to reply to does not appear to exist.`, as on Mastodon, and nothing is posted. `quote_id` quotes another post: the id is resolved the same way `in_reply_to_id` is, and the post is published immediately while the quoted author's server is asked for permission in the background (see **Quote posts** in `docs/Architecture.md`) — so a quote starts out `pending` and becomes `accepted` only when the approval arrives. A status whose text and content warning together run past the instance's `max_characters` is a **422**, counted in characters rather than bytes and the way Mastodon counts them: every URL in the text as 23 characters (`characters_reserved_per_url`) whatever its length, and a mention of an account on another server as its `@name` alone. An `Idempotency-Key` is remembered against the created status for an hour, scoped to the presenting token, and a repeat of the same key returns the same status instead of posting again. Attaching media also decides whether those attachments are world-readable: an attachment only becomes public when the post is `public` or `unlisted`. `scheduled_at` (ISO 8601) publishes the post later instead of now: the answer is a **ScheduledStatus** entity — `id`, `scheduled_at`, `params`, `media_attachments`, and no `content`, `account` or `created_at` — and nothing is posted until `Cron\ScheduledPosts` picks it up. It must be at least **5 minutes** in the future; sooner is a **422**, as is a value that is not a date (it used to be accepted and the post published at once). An account may have 300 scheduled statuses in total and 25 for any one day; past either is a **422**. The visibility is resolved when the post is scheduled and stored resolved, so changing `source[privacy]` afterwards cannot move the audience of a post that is already waiting. `Idempotency-Key` does not apply — a scheduled post creates no status to remember. Rate-limited per user. | **`post_as`** is this app's own: the handle of a team account the poster is a member of. The post is attributed to the team's account and signed with its key — the team speaks, not the person at the keyboard — while the attachments are still looked up as the uploader's own, because an upload belongs to whoever made it. Who actually wrote it is recorded and shown to the team and to moderators, and to nobody else: outside the team, one voice is the point of having a team account. A handle that is not a team account of this instance and one whose group the poster is not in are the same **404**, because which groups exist and what they post as is not a thing to confirm to somebody outside them. Mastodon has no team accounts, so a client that has never heard of this sends nothing and posts as itself. **`reply_policy`** is this app's own too: who may reply, `everyone` (the default, also for a value it does not know), `nobody`, or a combination of `followers`, `following`, `mentioned` and `list:<id>` (the poster's own lists; a list that is not theirs is left out, and nothing left is `nobody`); see `PUT …/interaction_policy`. It waits with a scheduled post. A status of one of this instance's own posts says it back as `reply_policy`; on anybody else's it is `null`.
| GET | `/api/v1/statuses/{nid}` | public, no-csrf | Query: `force_counts=true` (optional) | One status by numeric id, local export format, with the same `reactions` (`me` for the reader), `place`, `tagged_people` and `card` a timeline gives the same post; so do the statuses the create, edit, action, react and `interaction_policy` routes answer with. A boost asked for by its own id carries the boosted status in `reblog`, with the reader's `favourited`, `reblogged` and `bookmarked` on it, as a timeline shows it; a boost of a status the reader may not see is a **404**, as on Mastodon. **Aloha Social extension:** `force_counts=true` bypasses the five-second freshness window for the first detail-page read, so a post opened immediately after its feed card still asks its origin for current counts. It is not sent on short polling requests. `X-Social-Filling: 1` says counts are still being fetched or queued; a client that reads it asks again a few seconds later. |
| GET | `/api/v1/statuses/{nid}/calendar` | public, no-csrf, `read:statuses` | `nid` | Downloads a visible ActivityStreams `Event` with a valid `startTime` as an iCalendar `.ics` file. The status entity carries an app-local `event` extension with its name, UTC start/end, and stated venue. End times before the start are ignored; malformed or missing start times do not produce a calendar file. |
| POST | `/api/v1/statuses/{nid}/calendar/import` | user, session only, CSRF protected | `nid` | Imports a visible ActivityStreams `Event` directly into a writable calendar owned by the signed-in Nextcloud user. Repeated imports are detected by the stable iCalendar UID. |
| PUT | `/api/v1/statuses/{nid}` | public, no-csrf (viewer required, `write` scope) | Body: `status`, `spoiler_text`, `sensitive`, `event`, `media_ids`, `media_attributes` | Edits an own post via `PostService::editPost()`. `media_ids`, when present, replaces the complete attachment list in the given order; an explicit empty list removes every attachment, while omitting the field leaves the list unchanged. IDs must refer to uploads owned by the author, and the list is capped at the instance's maximum attachment count. `media_attributes` (`id` plus `description` and/or `focus` per entry, as a JSON list or as `media_attributes[][id]=…&media_attributes[][description]=…`, which is grouped back per attachment because PHP splits every `[]` into an entry of its own) changes the alt text and focal point of attachments the post carries: the upload is updated, the post's own copy is rebuilt from it, and the Update carries the new words. An id the post does not carry is ignored. Omitting `spoiler_text` or `sensitive` leaves that value unchanged; sending an empty `spoiler_text` explicitly removes the content warning. `event` updates the event details, and `null` removes the event from a post. Editing keeps the original `published` time and advances `updated`, which is used for `edited_at`. |
| DELETE | `/api/v1/statuses/{nid}` | public, no-csrf (viewer required, `write` scope) | — | Deletes one of the viewer's own statuses and answers with the status that was removed, which is what a client's "delete & redraft" puts back in the composer. Somebody else's status is a 404, the same answer an unknown id gets. |
| GET | `/api/v1/statuses/{nid}/delivery` | public, no-csrf (viewer required) | — | **This app's own route.** Where one of the viewer's own posts got to, read from the delivery queue: `delivered`, `sending`, `waiting`, `failing` and `abandoned` counts, `total`, and `instances` — one `{host, state, tries, last}` per server, the ones that need the author's eye first. A zero total means no delivery rows are currently on record; it does not mean that a public post should have been broadcast to every known server. Public posts are sent to resolved followers, mentioned accounts, and subscribed relays. Answered only for the author; anybody else's post is a **404**, the same 404 as a post that does not exist. Only as good as the retention: a delivered or abandoned request is kept for `retention` seconds (seven days) and then purged, so an old post reports nothing rather than reporting wrongly. Rows queued before the column existed carry no object and never appear. |
| GET | `/api/v1/statuses/{nid}/source` | public, no-csrf (viewer required) | — | Mastodon's `StatusSource`: `{"id", "text", "spoiler_text"}` for one of the viewer's own statuses. The stored content is the HTML rendered from the original text, so it is turned back — `<br>` becomes a newline, the remaining tags are stripped and entities are decoded. Tusky and Ivory will not offer their edit button without this route, even though `PUT /api/v1/statuses/{nid}` has always worked. |
| GET | `/api/v1/statuses/{nid}/card` | public, no-csrf | — | The link preview of one status, as Mastodon's `PreviewCard`. The card is already inlined in the status entity, which is what most clients read; this route was a **405** rather than a 404, because the path matched the POST-only action route and nothing answered a GET. A status with no link answers `{}` — Mastodon's own answer, and not an error, since most statuses have no card. |
| GET | `/api/v1/statuses/{nid}/context` | public, no-csrf | — | Ancestors/descendants of the status, as this server holds them, each with the `reactions`, `place`, `tagged_people` and `card` a timeline gives it. Opening a conversation also has the rest of it read from wherever it lives (`ThreadService`, in the background, at most every ten minutes per post): the replies its own server lists, and the replies it has on Bluesky, for a post from another server or a public one of this server's. When that read was just asked for, the answer carries the header **`X-Social-Thread-Filling: 1`** — this app's own; the web app asks once more a few seconds later and adds what came in. The replies the author of the conversation's first post hid (`hide_reply`) are left out, and counted in **`X-Social-Hidden-Replies`**; `with_hidden=true` includes them. In a conversation every reply carries `hidden_by_author` and `can_hide` (whether the reader is that author) — this app's own keys, `null` on a status read anywhere else. |
| GET | `/api/v1/statuses/{nid}/favourited_by` | public, no-csrf (viewer optional) | `limit` (40, capped at 80) | The accounts that favourited the status, newest first, as `Account` entities. The status is resolved through the visibility filter first, so one the caller may not read is a **404** and no reaction of it is looked at — who liked a post is as private as the post. An account this instance has never cached is left out rather than sent without a handle or an avatar. The accounts from here come first, then whoever liked it where it lives — the ones its own server lists in its `likes` collection (many list only the number), and the ones Bluesky lists for a post that is there — read in the background (`InteractionService`, at most every ten minutes per post) and kept an hour; the counts on the post are not changed by it. While that read was just asked for, the answer carries **`X-Social-Filling: 1`** (this app's own); the web app looks again a few seconds later. No `Link` header. |
| POST | `/api/v1/statuses/{nid}/react` | public, no-csrf (viewer required) | `emoji` (required) | Reacts to a status with an emoji and answers the status, its `reactions` rebuilt, so a client redraws the card from one response. Sends an `EmojiReact` to the author's instance — not an ActivityStreams type, but the one Misskey, Pleroma, Akkoma, Iceshrimp and Sharkey all use; Mastodon ignores an activity type it does not know, so a reaction to a Mastodon peer costs nothing there. **Unicode emoji only**: `:shortcode:` custom emoji are refused with a **400**, because accepting one means drawing a picture from somebody else's server inside a reaction bar, which is a per-post request to an arbitrary host and an image this instance neither moderates nor caches. The emoji is a parameter rather than a path segment — one emoji can be a long grapheme cluster, and percent-encoding it into a URL to get it back out again gains nothing. |
| POST | `/api/v1/statuses/{nid}/unreact` | public, no-csrf (viewer required) | `emoji` (required) | Takes a reaction back and answers the status. The row goes whether or not the `Undo` reaches the peer: a reader who presses their own reaction again has taken it off, and leaving it because a server is unreachable would be the app disagreeing with what they just did. |
| GET | `/api/v1/statuses/{nid}/reactions` | public, no-csrf (viewer optional) | — | The reactions on a status: `{name, count, me}` each, most used first, ties broken by the emoji so the bar does not reshuffle between two readers. The status is resolved through the visibility filter first, so one the caller may not read is a **404** and none of its reactions is looked at — who reacted to a post is as private as the post. `me` is false for an anonymous caller. |
| GET | `/api/v1/gifs` | public, no-csrf (viewer required) | `q`, `limit` (24, max 200), `offset` | The pictures the composer offers: what an administrator added here first, then the 881 shipped animated emoji. Answers `{gifs, total, attribution}`, each entry `{slug, title, url, media_type}`. Paged, because a grid of 881 is 881 pictures the instance would fetch because somebody opened a menu. `q` matches a title or slug for the instance's own, and for the shipped emoji also every other name Google gives one and its category, so "sad" or "food" find what a person means. A viewer is required: it is a picker inside the composer, and there is no reason to hand the whole library to anybody who asks. The filtering is done in PHP over the whole set rather than with a `LIKE '%…%'` — a leading wildcard is a scan on all three databases this app supports, and the shipped set is a file rather than rows. |
| GET | `/gif/{slug}` | public, no-csrf | — | The bytes behind a slug, cached for a day. Unauthenticated, like `/emoji/{shortcode}`: the picker draws a grid of these and they are the same bytes for everybody on the instance, which is also why it closes the session before it does anything — PHP runs requests holding one session one at a time, and a picker is sixty of these at once. A `noto-…` slug is one of the shipped animated emoji: if this instance has not served it before, *this* is the request that fetches it from Google, once, and stores it in appdata — which is why the reader's browser never talks to anybody but their own Nextcloud. |
| POST | `/api/v1/media/from-gif` | public, no-csrf (viewer required) | `slug` (required), `description` | Attaches a library picture to a post being written, and answers the `MediaAttachment` the composer holds on to. A copy, through the same `storeAttachment()` an upload and a Files pick go through, so the sniffing, the size guard and the resizing are one path rather than three that can drift — and a copy rather than a reference for the reason `/api/v1/media/from-file` gives: a post keeps the picture it was published with, so an administrator taking something out of the library cannot empty a post that has already federated. With no `description` the picture's title is used, because a library picture arriving with no alt text at all is the thing the ALT badge exists to complain about. |
| GET | `/api/v1/statuses/{nid}/reblogged_by` | public, no-csrf (viewer optional) | `limit` (40, capped at 80) | The accounts that boosted the status, newest first. Same rules as `favourited_by`, with the `shares` collection and Bluesky's reposts. |
| GET | `/api/v1/statuses/{nid}/quotes` | public, no-csrf (viewer optional) | `limit` (20, max 40), `max_id` | **The posts that quote this one**, newest first — Mastodon 4.5's. What comes back is what this server *holds*: a local quote, a remote one that reached somebody here, and — read in the background when the list is asked for, `X-Social-Filling: 1` — the posts that quote it on Bluesky, for a post that is there. A quote written on a fediverse server nobody here follows is not in the list, because the fediverse has no collection of the posts quoting one; Mastodon's own answer has the same edge. Read as the viewer, so a quote inside somebody's followers-only post is not handed to a reader by a list about their own post. |
| PUT | `/api/v1/statuses/{nid}/interaction_policy` | public, no-csrf (bearer `write:statuses`) | `quote_approval_policy`: `public`, `followers` or `nobody`; `reply_policy`: `everyone`, `nobody`, or a combination of `followers`, `following`, `mentioned` and up to five `list:<id>` of the caller's own lists, comma-separated (`followers,mentioned`) | **Who may reply** (`reply_policy`, this app's own field): written onto the post, said to peers as `interactionPolicy.canReply.automaticApproval` (the union of what each part names: the author's followers or following collection, the accounts the post mentions, the members of the lists as they were when the rule was set — or the author alone for nobody) and to Bluesky as the post's threadgate (a rule for each part; a list as the Bluesky list it is published as, `app.bsky.graph.list` with an item for each member that has a Bluesky identity, kept in step as members come and go), rewritten at once; a reply that the rule does not let through is refused with the reason when it is written here (**422**) and not kept when it arrives from elsewhere. The author always may. From now on only: replies already made stay. A body with `reply_policy` alone leaves who may quote as it was. **Who may quote one of the caller's own posts.** Written onto the post (`social_stream.quote_policy`) and advertised on its ActivityPub document as `interactionPolicy.canQuote.automaticApproval`, which is what Mastodon 4.5 reads before it offers a quote button. It decides what happens to `QuoteRequest`s that arrive **from now on**; it does not reach back and withdraw permissions already given, because a quote that has been published and read is not undone by a switch being flipped. Somebody else's post is a **404**, the same answer an id that does not exist gets. |
| POST | `/api/v1/statuses/{nid}/quotes/{quoting}/revoke` | public, no-csrf (bearer `write:statuses`) | `nid` the quoted post, `quoting` the post to detach | **Takes one quote of the caller's own post back.** A `Reject` naming the `QuoteRequest` that was accepted goes to the quoting server — FEP-044f's way of withdrawing a permission, and what `social_quote_grant` was written for: the request has to have been recorded at the moment the grant was made or there is nothing to name. The quote then shows there as *revoked* rather than refused, which is what this app does with an incoming one. A **local** quoting post is withdrawn here directly, because there is nobody to tell. A **Bluesky** quoting post has no request to refuse, since Bluesky asks nobody's permission: it is listed in the quoted post's `app.bsky.feed.postgate` as `detachedEmbeddingUris` (the newest 50), which every AppView honours by showing the quote detached, and it is withdrawn here. A post that does not quote this one, or a post that is not the caller's, is a **404**. |
| POST | `/api/v1/statuses/{nid}/translate` | public, no-csrf (viewer required) | `lang` (the language to translate into; defaults to the reader's Nextcloud language) | One status in the reader's language, as Mastodon's **`Translation`** entity — `{content, spoiler_text, media_attachments, poll, detected_source_language, provider}`, not a `Status`: a translation has no id, no author and no counters, and a client shows it under the post rather than instead of it. Declared before `{act}`, which would otherwise match this path. Translated by whatever translation provider this Nextcloud has; a server with none answers **503** and says so in `configuration.translation.enabled`. It never answers with the original text — which is what this route used to do, and what a reader could not tell from a translation. The body and the content warning are always translated, then poll options and alt texts while the per-request budget lasts (`TranslationService::MAX_TEXTS`, 12 — each text is a round-trip to the provider); what is past the budget is left out of the entity rather than returned untranslated, so a client shows the original for it. |
| POST | `/api/v1/statuses/{nid}/{act}` | public, no-csrf | `act` (path) | Performs an action on a status — see the action table below. |

`{act}` is validated against `ActionService::$availableStatusAction`. Accepted values are `favourite`, `unfavourite`, `reblog`, `unreblog`, `bookmark`, `unbookmark`, `hide_reply`, `unhide_reply`, `mute`, `unmute`, `pin`, `unpin`, `dislike`, `undislike`; anything else throws `InvalidActionException`:

| `act` value | Effect |
|-------------|--------|
| `favourite`, `unfavourite` | Creates/deletes a Like (`LikeService`). A poll (a `Question`) is a status to its readers and is liked like a note (`Stream::STATUS_TYPES`); anything else — a boost, an activity — is a 404. |
| `reblog`, `unreblog` | Creates/deletes an Announce (`BoostService`), of a note or a poll. The Mastodon-ish names `boost` and `unboost` are **not** accepted. |
| `hide_reply`, `unhide_reply` | Hides a reply from the conversation of one of the caller's own posts, or shows it again — any reply in the thread, wherever it was written (`HiddenReplyService`). Kept on the thread's first post; a thread that is on Bluesky lists it in its threadgate (`hiddenReplies`), which every AppView honours. Anybody but the author of the thread's first post is refused. |
| `bookmark`, `unbookmark` | Toggles the viewer's bookmark flag (`social_stream_act.bookmarked`). Never federated; the bookmarked posts are served by `/api/v1/bookmarks`. A post that is on Bluesky is bookmarked there too, privately (`app.bsky.bookmark.createBookmark`, as the viewer), so a Bluesky app signed in here shows the same bookmark. |
| `pin`, `unpin` | Pins/unpins one of **your own local, public or unlisted posts** to your profile (`PinService`), and tells the followers with an `Add` or `Remove` naming the actor's `featured` collection — a peer has nothing else to prompt it to re-read that collection. At most 5 pins; pinning somebody else's post, a remote post, a followers-only or direct post, or exceeding the limit raises `InvalidActionException` (a 422). The visibility rule is Mastodon's pinnable set, and it exists because the `featured` collection is served to anonymous callers. A pin is stored as a `Pin` row in `social_action` and published in the actor's `featured` collection — it is never federated as an activity of its own. |
| `dislike`, `undislike` | Sends a `Dislike` to the video's author, or an `Undo` of one, and records it against the viewer (`social_stream_act.disliked`). **Only a video can be disliked** — a post with a video file on it, or one that arrived as a `Video` — and anything else is a 422: Mastodon has never had a dislike, and the activity would be dropped as unknown by the server it was sent to. PeerTube publishes both counters and this app could only send one, so the number its authors see was a count of everybody except this instance's viewers. The count comes back on the status as `dislikes_count`, with `disliked` for the viewer's own; both are `null` on anything that is not a video. |
| `mute`, `unmute` | Mutes the **conversation** the status belongs to, for the viewer. Mastodon's conversation mute is about being *told*: the thread's posts stay on every timeline and only the notifications it would produce stop, which is what somebody muting a thread they are in has asked for. The mute is recorded against the thread's **root** (`social_convo_state.muted`), so a reply that arrives tomorrow is covered by a mute taken today — the whole point of muting a conversation rather than a post. A post that replies to nothing, or whose parent this instance does not hold, is its own root. While muted, a notification about a post of that thread is stored but **raises nothing** — no Nextcloud notification, so no bell, push or mail, and no Activity entry (`NotificationService::emit()`) — and is left out of `/api/v1/notifications`, the unread counts and the digest. Unmuting lists again what arrived meanwhile, without raising anything for it. The answer's `muted` says which state the conversation is in now. |

The response is the status itself in local format.

In that format, `in_reply_to_id` and `in_reply_to_account_id` carry the parent status's numeric id and its author's, resolved from the stored ActivityPub id (memoised per request, so a thread's replies are one lookup). Both are `null` for a post that is not a reply and for a parent this instance has never seen. `application` (null: which app wrote a post is not recorded), `filtered` (`[]` until a filter matched, see Filters) and `text` (null; the source is answered by `/api/v1/statuses/{id}/source` and by a delete) are always present, as Mastodon sends them. `tags` is Mastodon's `[{name, url}]`; `Note::jsonSerialize()` still emits the app's own `hashtags: ["foo"]` alongside it when the status is exported with complete details. `edited_at` is when the post was last edited, or `null`. `quotes_count` is Mastodon 4.5's: how many posts quote it — the ones held here, and for a post from Bluesky what Bluesky counts — and is zeroed with the other numbers for a reader who hides them (`/api/v1/social/counts`). `quote` is Mastodon 4.5's Quote entity — `{state, quoted_status}` — or `null` for a post that quotes nothing. `state` comes from the quoted author's approval, not from whether this instance holds the post: `pending` until they answer, then `accepted`, `rejected`, or `revoked` if they take it back. A quote made on Bluesky, or of a Bluesky post, needs no approval — Bluesky asks nobody — and is `accepted` until its quoted author detaches it, then `revoked`. `quoted_status` carries the quoted post inline only when the quote is accepted **and** the viewer may read it — an accepted quote of a post this reader may not see is `accepted` with a null `quoted_status`, so a quote never becomes a way of reading somebody's followers-only post. Mention ids are strings even when the handle could not be resolved. `delivery` is an **Aloha Social extension** and the entity's one key that is absent rather than `null`: it is `"held"` on the author's own copy of a post whose deliveries are waiting for its video to be converted (see `VideoDeliveryHold`), and absent on every other status and on the same post once it has gone out. Computed for the reader's own local posts only — the attachments decide first, so a post without a video costs no query. `attachment` — an ActivityPub-named duplicate of `media_attachments` — is no longer part of the client format. `ai_generated` (bool, always present) is an **Aloha Social extension** too: whether the post *says* it was made with AI — one of its hashtags is in the labelling set (`AiContentService::DEFAULT_TAGS` plus the administrator's `ai_tags`), or one of its pictures carries machine-generation provenance in its metadata — and for a boost, whether the boosted post does (both levels carry it). It is a label the post carries, never a judgement about its content; a reader who turned on *Hide posts made with AI* (`/api/v1/social/ai_content`) never receives such a status at all, and everybody else can be shown a quiet mark. Each `MediaAttachment` carries two keys beyond Mastodon's: `media_type`, the full mime (`image/png`), which is what the ActivityPub `Document` the post is served as states; and `ai_generated` (bool), whether the picture's metadata stated IPTC `DigitalSourceType` `trainedAlgorithmicMedia` or `compositeWithTrainedAlgorithmicMedia` when it was stored — read before the metadata is stripped, so a client cannot re-derive it from the served bytes. A Mastodon client ignores both.

### Scheduled statuses

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/scheduled_statuses` | public, no-csrf (viewer required) | `limit` (20, capped at 40), `max_id` (0), `min_id` (0), `since_id` (0) | The viewer's waiting posts, soonest first, as ScheduledStatus entities with their attachments already expanded. Sends **no `Link` header** — a ScheduledStatus carries no status nid to page on — but the three cursors are honoured. They are scheduled-status row ids, and each is read as **the place that row holds in the order above**, not as a number to compare: an id is creation order, `scheduled_at` is publication order, and `PUT /api/v1/scheduled_statuses/{id}` can move one past the other at any time, so comparing ids while ordering by time repeats rows across pages and hides others. The id is resolved to the `(scheduled_at, id)` pair it stands for and the comparison is made on the pair. `min_id` and `since_id` ask for what comes after that place; `max_id` asks for what comes before it and answers the page **ending at** the cursor, not the earliest page there is. A cursor naming a row that has since been published or cancelled falls back to comparing ids. |
| GET | `/api/v1/scheduled_statuses/{id}` | public, no-csrf (viewer required) | — | One waiting post. One that is not the viewer's is a **404**, which is also the answer for one that does not exist. |
| PUT | `/api/v1/scheduled_statuses/{id}` | public, no-csrf (viewer required, `write` scope) | Body (JSON or form-encoded): `scheduled_at` (required) | Moves a waiting post to another time. The five-minute minimum applies again; a missing or unparseable `scheduled_at` is a **422**, somebody else's post a **404**. Moving a post inside the day it is already in is not counted against that day's cap; moving it into another day that already holds 25 is a **422**. |
| DELETE | `/api/v1/scheduled_statuses/{id}` | public, no-csrf (viewer required, `write` scope) | — | Cancels a waiting post and answers `{}`. Cancelling one that is gone, or one that is not the viewer's, is a **404**. |

A due post is published by `Cron\ScheduledPosts` down the same path an immediate post takes (`PostService::createPost()`), with the request replayed from `params`. The row is deleted before the post is attempted, so exactly one worker publishes it; a post that cannot be published is logged at `warning` and not retried, because the alternative federates it twice.

### Lists

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/lists` | public, no-csrf (viewer required, `read:lists` scope) | — | Every list the viewer owns, oldest first, as Mastodon `List` entities. Unpaged, as Mastodon's is: a client draws the whole sidebar from one call. Asking is also what makes the **group lists** the viewer is missing — one per Nextcloud group they are in — and removes the ones for groups they have left; a failure there is logged and the lists are answered anyway. |
| POST | `/api/v1/lists` | public, no-csrf (viewer required, `write:lists` scope) | `title` (required), `replies_policy` (`list`), `exclusive` (false), `public` (false) | Creates a list and returns it; a public one is published (see **Public lists** below). A blank or whitespace-only title is a **422**, and a `replies_policy` outside `followed`/`list`/`none` is a **422** rather than quietly stored as the default. Titles are not unique: two lists called "Friends" are two lists, as on Mastodon. |
| GET | `/api/v1/lists/{id}` | public, no-csrf (viewer required, `read:lists` scope) | — | One `List`. A list that is not there and a list that is somebody else's are the same **404**: telling them apart would say whether an id exists. |
| PUT | `/api/v1/lists/{id}` | public, no-csrf (viewer required, `write:lists` scope) | `title` (required), `replies_policy`, `exclusive`, `public` | Updates the list and returns it. `title` is required on an update as on a create, so an absent one is a 422 rather than "keep what is there". Omitted `replies_policy`/`exclusive`/`public` are left alone. `public: true` on a group list is a **422**. |
| DELETE | `/api/v1/lists/{id}` | public, no-csrf (viewer required, `write:lists` scope) | — | Deletes the list and its memberships, and answers `{}`. |
| GET | `/api/v1/lists/{id}/accounts` | public, no-csrf (viewer required, `read:lists` scope) | `limit` (40, capped at 500), `max_id` (0), `min_id` (0) | The list's members as `Account` entities, newest addition first. Sends a `Link` header whose cursor is the `social_list_member` row id, not the account: an account can be removed from a list and added again, so its own id does not move in one direction. A member whose actor is no longer cached is left out of the page rather than sent half-filled, but its row still decides the cursor, so paging does not stall on it. **`limit=0` is not accepted**, although Mastodon documents it as "all accounts without pagination": Nextcloud's dispatcher applies a range of 1–500 to every parameter named `limit` (`Dispatcher::ensureParameterValueSatisfiesRange`) and throws before the route is reached, so a 0 comes back as a **500** and an HTML error page rather than JSON. That is true of every `limit` this app takes, on this endpoint and any other. Ask for 500 instead. |
| POST | `/api/v1/lists/{id}/accounts` | public, no-csrf (viewer required, `write:lists` scope) | `account_ids[]` (required; a bare `account_ids` is accepted too) | Adds accounts and answers `{}`. A list is a view of what the owner already follows, so an account they neither follow nor have a pending follow request to is a **404** — Mastodon's answer, because the follow the membership would attach to is what is missing. The owner may be in their own list without following themselves. Every id is resolved before anything is written, so a request naming one account that may not be added adds none of them. Adding an account already in the list is a no-op. |
| DELETE | `/api/v1/lists/{id}/accounts` | public, no-csrf (viewer required, `write:lists` scope) | `account_ids[]` (required) | Removes accounts and answers `{}`. No follow is required — unfollowing somebody must not leave them stuck in a list — and removing one that is not in the list is not an error. |
| GET | `/api/v1/accounts/{account}/lists` | public, no-csrf (viewer required, `read:lists` scope) | — | Which of **the viewer's own** lists `{account}` is in. Never anybody else's: which lists a stranger put somebody in is not a thing either of them may read. |

**Group lists.** Every Nextcloud group the viewer is in is a list of theirs, made on their behalf and kept in step with the group. The `List` entity carries two keys beyond Mastodon's four: `nextcloud_group`, the group's id, or `null` for a list made by hand — a Mastodon client ignores it; this app's own client draws the group icon from it — and `public` (below). A group list's title is the group's display name and its members are the group's members who have an Aloha Social account, so `DELETE /api/v1/lists/{id}`, `POST /api/v1/lists/{id}/accounts` and `DELETE /api/v1/lists/{id}/accounts` on one are a **422** naming the group; `PUT /api/v1/lists/{id}` keeps the title and applies `replies_policy` and `exclusive`. Leaving the group is what removes the list. Groups larger than 500 members get no list.

**Public lists.** A list is private to its owner, as on Mastodon, unless they make it public: `public` on the `List` entity (`false` by default), set with `public` on `POST`/`PUT /api/v1/lists[/{id}]`. A public list is published to Bluesky as a curate list with its members that have a Bluesky identity, renamed and kept in step with its members; made private again it is withdrawn, unless a reply rule of the owner's names it (a threadgate needs the list to be there). A curate list the person makes in a Bluesky app signed in here, or brought when their Bluesky account moved here, is a public list here. The routes stay the owner's alone; what is public is the Bluesky list. A group list cannot be made public.

A list is private to the account that made it, and that is the whole of its access model — there is no sharing and no visibility flag. Every route above resolves its list through `ListsRequest::getOwnedById()`, which carries the owner as a predicate of the SQL statement rather than as a check made after the row was read.

`replies_policy` and `exclusive` are stored and handed back faithfully, and **neither yet changes which posts a timeline selects**: `exclusive` does not remove members from the home timeline, and `replies_policy` does not filter replies out of the list timeline.

### Pixelfed's own routes

Pixelfed speaks the Mastodon client API for almost everything; what follows is the small surface that is its own. **This is not all of Pixelfed's `v1.1`** — it is the part its official app calls to start up and to draw discover. Routes are added when something asks for them, not to fill in a namespace.

Nothing here ranks or selects anything of its own: discover is the same `TrendService` the Mastodon trend routes use and the same `SuggestionService` behind `/api/v2/suggestions`, so a post or an account cannot be popular on one route and absent from the other.

Suggestions come from three places, each filling only the slots the one before it left empty: the follow graph (`friends_of_friends`), the **`fediverse` field of this Nextcloud's own profiles** (`featured` — the handles the people here wrote down, honoured with the field's own visibility and never the ones marked private), and the local accounts that opted in to the directory (`most_interactions`). An account this app creates has its handle written into that field when the field is empty; a value already there is the person's own and is left alone.

**Two spellings, one route.** Pixelfed serves most of this surface at both `/api/v1.1/…` and `/api/pixelfed/v1/…`, and which one its app asks for depends on the version of the app. Twenty of the routes below therefore carry the second spelling as well, each listed as a row of its own directly beneath the first — the same method, the same answer, no second implementation. Two routes Pixelfed's app calls are **not** served, because Pixelfed does not serve them either: `GET /api/v2/media` (its `v2` media route is a POST upload, and a GET there is a **405** here as it is there) and `api/pixelfed/v2/discover/posts/trending` (there is no `v2` under the `pixelfed` prefix; the trending route is the `v1` one below).

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v2/config` | public, no-csrf | — | The numbers and switches the Pixelfed app reads once, on launch, before it will draw anything. Answered without a viewer, because the app asks before anybody has signed in. **Every value is derived, never restated**: the ceilings come from the constants the server enforces and the mime list is asked of `CacheDocumentService::filterMimeTypes()`, so the client cannot be told a limit the server does not keep. `open_registration` is always `false` — an account here exists because a Nextcloud user does. The `features` block says what *this* app does, including the things it does not (`live_streaming`, `push_notifications`, `circles` are `false`): announcing a screen that is not there is worse than not announcing it. `features.shorts` is `true` where the timelines take `only_short`, and `limits.short_max_duration` (seconds) and `limits.short_max_aspect_ratio` (width ÷ height) are the rule they apply, read from `Stream::SHORT_MAX_SECONDS` and `Stream::SHORT_MAX_ASPECT`. |
| GET | `/api/v1.1/teams` | public, no-csrf (viewer required, `read:accounts` scope) | — | The team accounts the viewer may post as right now, as Account entities: `{"teams": [Account, …]}`. Asked of Nextcloud's group manager rather than of a stored membership — somebody who left the group this morning may not post as it this afternoon, and the only way to be sure of that is to ask. An empty list is the ordinary answer, because most instances have none. |
| GET | `/api/v1.1/portfolio` | public, no-csrf (viewer required, `read:accounts` scope) | — | The viewer's own page of work, published or not, with the pictures it would show — **as the internet will see them**, not as their owner can. An owner previewing their draft was shown their followers-only pictures among the rest, and none of those would have been on the published page; a preview that shows a photograph which will not appear is worse than no preview. An account that has never opened the editor gets the defaults rather than a **404**: there is nothing to find, and this is what lets an editor render without a "create it first" step nobody needs. |
| POST | `/api/v1.1/portfolio` | public, no-csrf (viewer required, `write:accounts` scope) | `active`, `title` (128), `intro` (500), `layout` (`grid` or `rows`), `source` (`recent` or `collection`), `collection_id`, `show_captions`, `show_places`, `show_dates`, `show_avatar` | Writes it. `active` is the moment its owner decides the internet may read it; a row without it is a draft. `source: collection` with a collection that is not the viewer's own is a **422**, checked when it is asked for rather than rendered as an empty page afterwards. Returns the page as the GET above would. |
| GET | `/api/v1.1/portfolio/{handle}` | public, no-csrf | — | Somebody's published page, as the internet reads it: the account, the title, the sentence, the display switches, and up to 60 posts. **No viewer is resolved at all**, deliberately — what a portfolio shows is what the whole internet may see, whoever happens to be reading, so the posts are read the way an anonymous reader reads them and a followers-only photograph cannot reach the page. A page its owner has not turned on is a **404**, not an empty page with their name on it, and so is a handle this server does not know. |
| POST | `/api/v1.1/compose/tag` | public, no-csrf (viewer required, `write:statuses` scope) | `status_id` (required), `accounts` (a list of handles or ids) | Names the people in one of the viewer's own photographs — Pixelfed's `MediaTag`, and a staple of every photo network there has been. `accounts` is the **whole list** the post should end up naming, not what to add: anybody dropped from it is untagged, which is what makes a client that re-sends its list on every edit a no-op rather than a growing pile. Only the post's author may name anybody in it; anybody else asking gets the **404** a post that does not exist gets. A post with no picture is a **422**, and so is a list longer than twenty — a photograph of a party is the case that has to fit, and a longer list is not naming people, it is addressing a mailing list. A name this server cannot resolve is dropped from the list rather than failing the rest of it. Each name is written onto the post as a `Mention` and the post is re-sent as an `Update`, which is what makes a remote account's own server tell them; it does **not** widen who may see the post. Returns `{"tagged_people": [Account, …]}`. |
| POST | `/api/pixelfed/v1/compose/tag` | public, no-csrf (viewer required, `write:statuses` scope) | `status_id` (required), `accounts` (a list of handles or ids) | The second spelling of the tagging route above, onto the same method: the same whole-list rule, the same **404** for a post that is not the viewer's and the same **422** for a post without a picture or a list past twenty. Returns `{"tagged_people": [Account, …]}`. |
| POST | `/api/v1.1/compose/tag/untagme` | public, no-csrf (viewer required, `write:statuses` scope) | `status_id` (required) | Takes the viewer's own name off a photograph, which is Pixelfed's whole remedy for being named in somebody else's picture: being in one is not something to need their permission to leave. The post's author may also take a name off, and does so through the same route with the post as theirs. `{"untagged": true}`, or `false` when there was no such name. |
| POST | `/api/pixelfed/v1/compose/tag/untagme` | public, no-csrf (viewer required, `write:statuses` scope) | `status_id` (required) | The second spelling of untagging: takes the viewer's own name off the post and answers `{"untagged": true}`, or `false` when there was no such name. |
| GET | `/api/v1.1/accounts/{account_id}/tagged` | public, no-csrf (viewer required, `read:statuses` scope) | `limit` (20, max 40), `max_id` | "Photos of you", for anybody: the posts that account is named in, newest first, as Status entities. Which of them the reader may see is **not** decided here — the ids come out of the tag table and each post is then read the way any other post is read for this reader, so one they may not see is simply not among them rather than being filtered out by a rule written twice. That is also why a page can be **short without being the last**: whether there is another is said by a `Link: <…?max_id=…>; rel="next"` header, whose cursor is the last tag row read rather than the last post returned, and which is absent once a page read fewer tag rows than it asked for. |
| GET | `/api/pixelfed/v1/accounts/{account_id}/tagged` | public, no-csrf (viewer required, `read:statuses` scope) | `limit` (20, max 40), `max_id` | "Photos of you" under the second prefix: the posts the account is named in, newest first, as Status entities, each read as this reader may read it, with the same `Link` header carrying the next cursor. |
| GET | `/api/v1.1/discover/categories` | public, no-csrf | — | The subjects this instance says it is about, in the order an administrator put them in: `{"categories": [{"id", "name", "hashtags": ["brutalism", …]}]}`. **Curated, not counted** — every other route in this section ranks something, and this one is the instance's own claim about itself, which no trend counter can work out. Public, because an Explore page is the first thing somebody looking at a server sees, and empty (`[]`) until somebody names one, which is why the page renders nothing rather than an empty shelf. Pixelfed's own `DiscoverCategory`, minus its per-category cover picture. |
| GET | `/api/v1.1/discover/accounts/popular` | public, no-csrf (viewer required, `read` scope) | `limit` (20, max 20) | The same suggestions `/api/v2/suggestions` answers, unwrapped — Mastodon wraps each account in a `{source, account}` suggestion and Pixelfed sends the accounts themselves. Needs a viewer, as the Mastodon route does: there is no anonymous "accounts you might follow". |
| GET | `/api/pixelfed/v1/discover/accounts/popular` | public, no-csrf (viewer required, `read` scope) | `limit` (20, max 20) | The same suggested accounts under the second prefix: a bare list of Account entities, and a **401** without a viewer. |
| GET | `/api/v1.1/discover/posts` | public, no-csrf | `limit` (20, max 20), `offset` (0), `period` | The same answer as `/api/v2/discover/posts`, at the path the app asks for — a second route onto one implementation, not a second implementation. |
| GET | `/api/v1.1/discover/posts/hashtags` | public, no-csrf | `limit` (20, max 20), `period` | The trending tags `/api/v1/trends/tags` answers, for the row of tags above the discover grid. |
| GET | `/api/pixelfed/v1/discover/posts/hashtags` | public, no-csrf | `limit` (20, max 20), `period` | The same trending tags under the second prefix, in the same shape. No viewer is needed; one is honoured when a token is sent. |
| GET | `/api/v1.1/discover/posts/trending` | public, no-csrf | `range` (`daily`, `monthly`, `yearly`), `limit` (20, max 20), `offset` | The path the app's Discover screen actually calls, onto the same implementation as `/api/v1.1/discover/posts`. `daily` is this app's one-day trend window, `monthly` and `yearly` its ten-day one — the counters run no further back. |
| GET | `/api/pixelfed/v1/discover/posts/trending` | public, no-csrf | `range` (`daily`, `monthly`, `yearly`), `limit` (20, max 20), `offset` | The same trending grid under the second prefix: public Status entities, most interacted with first in the window `range` names, with link previews and places attached. No viewer is needed; one is honoured when a token is sent. |
| GET | `/api/v1.1/discover/posts/network/trending` | public, no-csrf | `range`, `limit`, `offset` | Pixelfed's "trending across the network". The same answer as above: what this server knows of the network *is* what it has cached, and the trend counters already cover it. |
| GET | `/api/v1.2/stories/carousel` | public, no-csrf (viewer required, `read:stories` scope) | — | The same stories `/api/v1/stories/carousel` answers, in the shape the app's story bar draws: `{self, nodes}`, one node per account (`id`, `user`, `nodes`, `url`, `seen`), each story a node of `id`, `pid`, `type` (`photo`/`video`), `src`, `duration`, `seen`, `created_at`. |
| GET | `/api/pixelfed/v1/stories/carousel` | public, no-csrf (viewer required, `read:stories` scope) | — | The same story bar under the second prefix: `{self, nodes}`, the viewer's own stories first and then those of the accounts they follow, each node shaped as the row above lists. |
| POST | `/api/v1.1/stories/seen` | public, no-csrf (viewer required, `write:stories` scope) | `id` (required) | `POST /api/v1/stories/{id}/seen` with the id in the body, which is where the app puts it. Answers `{"code": 200}`. |
| POST | `/api/pixelfed/v1/stories/seen` | public, no-csrf (viewer required, `write:stories` scope) | `id` (required) | Marks the story seen for this viewer under the second prefix; a repeat is a no-op rather than a second view. Answers `{"code": 200}`. Rate-limited to 300 a minute. |
| POST | `/api/v1.1/stories/self-expire/{id}` | public, no-csrf (viewer required, `write:stories` scope) | — | `DELETE /api/v1/stories/{id}` under the name the app uses. Answers `{"code": 200, "msg": …}`. |
| POST | `/api/pixelfed/v1/stories/self-expire/{id}` | public, no-csrf (viewer required, `write:stories` scope) | — | Removes one of the viewer's own stories early, with the record of who saw it; somebody else's is a **404**. Answers `{"code": 200, "msg": …}`. |
| GET | `/api/v1.2/stories/viewers` | public, no-csrf (viewer required, `read:stories` scope) | `sid` (required) | Who watched one of the viewer's **own** stories, newest viewer first, as Account entities. Somebody else's story is the same **404** as one that does not exist: who watched is told to the poster and to nobody else, like the view count. |
| GET | `/api/pixelfed/v1/stories/viewers` | public, no-csrf (viewer required, `read:stories` scope) | `sid` (required) | Who watched one of the viewer's own stories, newest viewer first, as Account entities; somebody else's story is the same **404** as one that does not exist. |
| POST | `/api/v1.2/stories/react` | public, no-csrf (viewer required, `write:stories` scope) | `sid` (required), `reaction` (required, at most 20 characters) | An emoji sent back to whoever posted a story. Only somebody who **follows** the poster may send one, which is the same condition as being able to see the story at all, and a story the viewer may not see is the same **404** as one that does not exist. At most five answers to one story from one account (Pixelfed's own number) — past that a **422**, because what a story otherwise gives somebody is a private channel to the poster that the poster cannot close. A reaction to a story that came from another server is delivered to its author as a `Story:Reaction`; one to a story posted here notifies its author and goes nowhere else. |
| POST | `/api/pixelfed/v1/stories/react` | public, no-csrf (viewer required, `write:stories` scope) | `sid` (required), `reaction` (required, at most 20 characters) | The emoji reaction under the second prefix, with the same follower rule, the same five-per-story ceiling and the same delivery to a remote author. Answers with the reaction in the shape the reactions list uses. Rate-limited to 60 a minute. |
| POST | `/api/v1.2/stories/comment` | public, no-csrf (viewer required, `write:stories` scope) | `sid` (required), `caption` (required, at most 500 characters) | The same, in words. Pixelfed calls this a comment and turns it into a direct message; here it stays beside the story and is deleted with it. **It is not a post**: there is no `social_stream` row behind one, so it cannot appear in a timeline, on a profile or in an outbox, and it does not outlive the thing it was about. Delivered to a remote author as a `Story:Reply`. |
| POST | `/api/pixelfed/v1/stories/comment` | public, no-csrf (viewer required, `write:stories` scope) | `sid` (required), `caption` (required, at most 500 characters) | The reply in words under the second prefix: kept beside the story rather than as a post, deleted with it, delivered to a remote author as a `Story:Reply`. Answers with the reply in the shape the reactions list uses. Rate-limited to 60 a minute. |
| GET | `/api/v1.2/stories/reactions` | public, no-csrf (viewer required, `read:stories` scope) | `sid` (required) | What has been said about one of the viewer's **own** stories, oldest first: `{"reactions": [{"id", "story_id", "type": `reaction` or `reply`, "content", "created_at", "account"}]}`. Somebody else's story is a **404**, like the viewer list and the view count: who answered is the poster's business. |
| GET | `/api/pixelfed/v1/stories/reactions` | public, no-csrf (viewer required, `read:stories` scope) | `sid` (required) | What has been said about one of the viewer's own stories, oldest first, as `{"reactions": […]}` in the shape the row above lists; somebody else's story is a **404**. |
| GET | `/api/v1.2/stories/mention-autocomplete` | public, no-csrf (viewer required, `read` scope) | `q` (required) | The accounts a `@` in a caption could mean — the same search `/api/v1/accounts/search` runs without `resolve`, capped at 24. |
| GET | `/api/v1.1/collections/self` | public, no-csrf (viewer required, `read:collections` scope) | — | The viewer's collections in Pixelfed's shape: `id`, `pid`, `visibility` (`public`, or `private` for followers-only), `title`, `description`, `thumb` (the first picture of the first post), `url` (this app's own page for it), `post_count`, `published_at`, `created_at`, `updated_at`. |
| GET | `/api/pixelfed/v1/collections/self` | public, no-csrf (viewer required, `read:collections` scope) | — | The viewer's collections in Pixelfed's shape under the second prefix — the same rows as above, down to `thumb` and `post_count`. |
| GET | `/api/v1.1/accounts/username/{username}` | public, no-csrf | — | An Account by its username — bare for a local account, `name@host` for a remote one this server already knows, an actor URL or a client id. Nothing is fetched from elsewhere: `/api/v1/accounts/lookup` with the name in the path. |
| GET | `/api/v1.1/accounts/mutuals/{id}` | public, no-csrf (viewer required, `read` scope) | — | The accounts the viewer follows that also follow `{id}` — which is exactly Mastodon's `familiar_followers`, unwrapped, capped at 24. |
| DELETE | `/api/v1.1/accounts/avatar` | public, no-csrf (viewer required, `write:accounts` scope) | — | `DELETE /api/v1/profile/avatar` under the app's name: removes the picture and answers with the account as it now is. |
| DELETE | `/api/pixelfed/v1/accounts/avatar` | public, no-csrf (viewer required, `write:accounts` scope) | — | Removes the viewer's picture under the second prefix and answers with the account as it now is. |
| POST | `/api/v1.1/report` | public, no-csrf (viewer required, `write:reports` scope) | `report_type` (required: `spam`, `sensitive`, `abusive`, `underage`, `violence`, `copyright`, `impersonation`, `scam`, `terrorism`), `object_id` (required), `object_type` (required: `post`, `user`, `story`), `message` | A report as the app files one, kept as the report this server keeps. The reason becomes Mastodon's category (`spam` → `spam`, `copyright` → `legal`, `abusive`/`underage`/`violence`/`terrorism` → `violation`, the rest → `other`) and is kept in the comment as well, because `violation` says less than `underage` did. A post is reported against its author and carried with the report; a story against its owner alone. Reporting yourself is a **422**. Answers `{"msg", "code": 200}`. Rate-limited to 30 an hour, per address and per account. |
| POST | `/api/pixelfed/v1/report` | public, no-csrf (viewer required, `write:reports` scope) | `report_type` (required), `object_id` (required), `object_type` (required: `post`, `user`, `story`), `message` | The report route under the second prefix: the same nine reasons, the same mapping onto a Mastodon category, the same **422** for reporting yourself. Answers `{"msg", "code": 200}`. Thirty an hour per account. |
| GET | `/api/v1.1/compose/settings` | public, no-csrf (viewer required, `read` scope) | — | What the app's composer reads first: `allowed_media_types`, `max_caption_length`, `default_license` (1, all rights reserved — the only licence a post here carries), `media_descriptions` (`false`: alt text is asked for, not demanded), `max_file_size`, `max_media_attachments`, `max_altext_length`, `default_scope` (the viewer's posting default, in Pixelfed's words). |
| GET | `/api/pixelfed/v1/compose/settings` | public, no-csrf (viewer required, `read` scope) | — | The composer's ceilings and defaults under the second prefix — the same eight keys as the row above, `default_scope` being the viewer's own posting default. |
| POST | `/api/pixelfed/v1/archive/add/{id}` | public, no-csrf (viewer required, `write:statuses` scope) | — | **Puts one of the caller's own posts away.** It leaves this server's profile, timelines, hashtag pages, search and outbox — every list this server builds — and is *not* deleted and *not* federated: the post is still on every server that received it, and taking it back from them is what `DELETE /api/v1/statuses/{id}` is for. Reversible, which is the point. A post that is not the caller's own, or not this server's, is a **404**. `{"code": 200}`. |
| POST | `/api/pixelfed/v1/archive/remove/{id}` | public, no-csrf (viewer required, `write:statuses` scope) | — | Puts it back. Same 404. |
| GET | `/api/pixelfed/v1/archive/list` | public, no-csrf (viewer required, `read:statuses` scope) | `limit` (50, max 50), `max_id` | The caller's own archive, newest first, as Status entities. The one read in this app that answers with archived posts: every other read is fail-closed (`StreamRequestBuilder::hideArchived()`), so a list written later shows none until somebody decides it should. |
| GET | `/api/pixelfed/v1/app/settings` | public, no-csrf (viewer required, `read` scope) | — | The Pixelfed app's own switches, kept on the server so that a reinstall finds the app as it was left: `timelines` (`show_public`, `show_network`, `hide_likes_shares`), `media` (`hide_public_behind_cw`, `always_show_cw`, `show_alt_text`) and `appearance` (`links_use_in_app_browser`, `theme` — `light`, `dark` or `system`). Answered as `{id, username, updated_at, common}`, with Pixelfed's own defaults and `updated_at: null` until the account has saved them once, which is how the app tells "never set" from "set to the defaults". **Not one of them is a setting of this app**: they decide what that client draws, and the server's part is to remember rather than to interpret. |
| POST | `/api/pixelfed/v1/app/settings` | public, no-csrf (viewer required, `write:accounts` scope to store, `read` without `common`) | `common` | Stores the switches and answers the same `{id, username, updated_at, common}`. Storing needs `write:accounts` (or `write`): the switches are the account's, and a token that may only read must not be able to turn content warnings off in somebody's app. Only the eight switches are kept and anything else is dropped — a blob written by a client and handed back to a client that kept whatever it was given would be a place to park arbitrary content under somebody's account. A POST with no `common` is a read. |
| GET | `/api/v1.1/nag/state` | public, no-csrf (viewer required, `read` scope) | — | `{"active": false}`. Pixelfed's nag is a banner its server raises when it wants something of the user; this one never does. |
| GET | `/api/v1.1/push/state` | public, no-csrf (viewer required, `read` scope) | — | The legacy Pixelfed-compatible push settings route is disabled: `notify_enabled`, `has_token` and all `notify_*` values are `false`. This route is separate from Mastodon's working Web Push subscription API at `/api/v1/push/subscription`. |
| POST | `/api/v1.1/push/disable` | public, no-csrf (viewer required, `write:accounts` or `push` scope) | — | The same state as above. Disabling what is already off changes nothing. |
| POST | `/api/v1.1/push/update` | public, no-csrf (viewer required, `write:accounts` or `push` scope) | — | The same state as above: asking to enable push answers with what is actually the case, so the toggle the app draws is the honest one. Whatever the app sends with it is not read. |
| POST | `/api/v1.1/push/compare` | public, no-csrf (viewer required, `read` scope) | `expo_token` | `match: false`, `has_existing: false` — there is no token here to compare against. |
| GET | `/api/v1/tags/{hashtag}/related` | public, no-csrf | `limit` (20, max 40) | The tags that travel with one — those on the same **public** posts, most often first — as Tag entities. A tag on a followers-only post is not public knowledge and does not count, however often it recurs. Pixelfed's route; Mastodon has no equivalent. |
| GET | `/api/v1.1/direct/thread` | public, no-csrf (viewer required, `read:statuses` scope) | `pid` (required), `max_id`, `min_id` | One direct-message thread as the app's chat screen draws it: the other party on top (`id`, `name`, `username`, `avatar`, `url`, `isLocal`, `domain`, `lastMessage`, `timeAgo`) and `messages`, oldest first, twenty a page — each `id`, `isAuthor`, `type` (`text`, `photo`, `video`), `text` (the post without its markup), `media`, `carousel`, `created_at`, `timeAgo`, `seen`, `reportId`. The messages are this app's direct posts, read through the same destination rows the direct timeline uses: a direct post writes one for every party to it, so the thread is every direct post with a row for both. |
| GET | `/api/pixelfed/v1/direct/thread` | public, no-csrf (viewer required, `read:statuses` scope) | `pid` (required), `max_id`, `min_id` | The chat screen under the second prefix: the other party on top and `messages`, oldest first, twenty a page, in the shape the row above lists. |
| POST | `/api/v1.1/direct/thread/send` | public, no-csrf (viewer required, `write:statuses` scope) | `to_id` (required), `message` (required, 1–500), `type` (`text`, `emoji`) | Sends one message: a direct post to the account, through the same path the composer's own direct messages take, with the recipient's handle in front of the text — which is how a direct post names who it is for here. Answers with the message as the thread shows it. Sending to yourself is a **422**. Rate-limited to 60 a minute. |
| POST | `/api/pixelfed/v1/direct/thread/send` | public, no-csrf (viewer required, `write:statuses` scope) | `to_id` (required), `message` (required, 1–500), `type` (`text`, `emoji`) | Sends one direct message under the second prefix and answers with it as the thread shows it. Sending to yourself is a **422**. Rate-limited to 60 a minute. |
| DELETE | `/api/v1.1/direct/thread/message` | public, no-csrf (viewer required, `write:statuses` scope) | `id` (required) | Takes one of the viewer's own messages back — `DELETE /api/v1/statuses/{id}` under the app's name. Somebody else's is the same **404** as one that never existed. Answers `[200]`, as Pixelfed does. |
| DELETE | `/api/pixelfed/v1/direct/thread/message` | public, no-csrf (viewer required, `write:statuses` scope) | `id` (required) | Takes one of the viewer's own messages back under the second prefix; somebody else's is the same **404** as one that never existed. Answers `[200]`. |
| GET | `/api/v1.1/direct/compose/mutuals` | public, no-csrf (viewer required, `read` scope) | — | Who the app's "new message" screen offers: the accounts the viewer follows that follow them back, at most 50, as Account entities. A direct message to a stranger is the thing most people never want to receive, so the screen starts from the people who already talk to each other. |

### Starter packs

A named handful of accounts worth following. They answer the one question a new account has that no algorithm here can: `SuggestionService` works off the follow graph, and on day one there is none — it falls back to whoever posted recently, which is a list of strangers sorted by luck.

A pack is a list of `user@host` handles and nothing else. No table: the accounts are not this instance's to own, and the handles are the only durable reference to them. The exception is a pack read in from another server: see *Collections from other servers* below.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/starter_packs` | public, no-csrf | — | Every pack, **resolving nobody**: names, descriptions and sizes. Turning a handle into a profile means a WebFinger lookup and an actor fetch against another server, and doing that for every handle of every pack to draw a list of names would make the page wait on the internet for nothing. Answered to a signed-out visitor — what an instance suggests is something it publishes about itself. |
| GET | `/api/v1/starter_packs/{slug}` | public, no-csrf | — | One pack with its handles resolved to Mastodon `Account` entities — the same shape `/api/v1/suggestions` answers with, because what draws a pack draws a name, a handle and an avatar per account. Drawn from the accounts this instance holds, in one lookup, without asking other servers: a handle not held here yet comes back in `unresolved` and is queued to be fetched in the background (`Cron\ResolveActor`), so the next look has it; so does one that will not resolve — host down, account moved or deleted — rather than being dropped, because a pack that quietly shrinks looks like one somebody wrote badly. An account this instance's moderation keeps out (silenced or suspended here, on a blocked or silenced server, or a Bluesky account blocked here or limited by Bluesky) is not offered. **404** for an unknown slug, and for a pack read in whose curator this instance's moderation keeps out. |
| POST | `/api/v1/starter_packs/{slug}/follow` | public, no-csrf (viewer required, `write:follows` scope) | — | Follows everyone in the pack who can be reached, and answers with `followed`: the handles that actually were. A member not held here yet is fetched now, once, and every member is followed as the actor found. One unreachable host skips that account rather than failing the lot — the point of the button is that nobody has to follow six accounts by hand. The viewer's own account is skipped, and so is an account the pack would not offer. |

**The shipped packs are an editorial choice and a deliberately narrow one**: the official accounts of the projects this app federates with. They are organisations rather than people, they are unambiguously the accounts they claim to be, and none was chosen because somebody liked them. Anything broader is a judgement an instance should make for itself.

An administrator replaces or extends them with the `starter_packs` app value — a JSON array of `{slug, name, description, handles}`. Three states, deliberately distinguishable: **unset** is whatever ships; **`[]`** is no packs at all, which is the right answer for an instance that would rather suggest nobody; **a list** is the shipped packs with any same-slug entry replaced and the rest added, so a shipped pack can be edited rather than only added to. Malformed JSON is no packs and a log line, never an exception: a typo in a config value must not be why a page is blank. (A JSON *object* decodes to an array too, so each entry is checked as well as the whole.)

**Collections from other servers.** Mastodon 4.6 lets an account publish Collections — named lists of up to 25 accounts it recommends — and federates them as FEP-7aa9 `FeaturedCollection`s, linked from the curator's actor as `featuredCollections`. Once a day (`Cron\StarterPackSources`, or now with `occ social:starter-packs:refresh`) `CollectionPackService` reads the collections of the curators the `starter_pack_sources` app value names — unset, the curated collections on mastodon.social — and keeps them in `social_starter_pack`. Only a collection marked discoverable and not sensitive is kept, and only the members whose own server serves a `FeatureAuthorization` naming them and this collection, as the FEP requires a reader to check — the first 50 this instance's moderation does not keep out, as many as a pack offers. A member whose server does not answer that day stays if it was in the pack before, a collection none of whose members could be checked keeps what was read last time, and only a collection the curator no longer lists, or one whose source was taken out, is removed. A curator this instance's moderation keeps out offers no pack. The daily read stops after five minutes and leaves what it did not get to as it was. They are listed after the packs this instance chose and never replace one of them; `starter_packs` set to `[]` hides them too.

**Bluesky's suggested starter packs** are read with them, the same day and into the same table, while Bluesky is on and `bluesky:suggested` is among the sources (it is by default): `SuggestedStarterPacks` asks the AppView, signed out, for `app.bsky.unspecced.getSuggestedStarterPacks` and each pack's list, keeping at most 50 members a pack, and leaving out any account this instance blocks or Bluesky's moderation limits. A pack whose list cannot be read that day keeps what was read last time. Bluesky asks no consent of an account to be in a starter pack, so there is nothing to verify the way a collection's members are.

Such a pack answers like the others, with `source` `fediverse` (or `bluesky`) and four fields the others leave `null`: `curator` (who published it, `user@host`), `url` (where it can be seen on the curator's server), `topic` (its hashtag, without `#`) and `language`. Its members are actor ids rather than handles, resolved from the cache the daily read fills (a member not cached yet is queued to be fetched), so opening one does not wait on its members' servers, and *follow* follows each as the actor it is, on whichever network. In the index its `size` is the stored member count, at most 50. `{slug}` is the collection's name made safe plus a 16-character hash of its id; a pack keeps the slug it was first stored with, so the packs stored before carry an 8-character one.

### Finding people in other servers' directories

The app could already resolve a handle somebody had already given you, and suggest people out of a follow graph a new account is not part of. Neither answers "who is out there", which is what a directory is for — so these ask several of them at once.

Every API used is one those servers serve to anybody without a token, because a directory is the part of a server that exists to be read by strangers. **Nothing is aggregated**: no list is stored, nothing is indexed, and an answer is held in the distributed cache for five minutes so that typing does not hammer four servers a keystroke.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/follow_graph` | public, no-csrf (viewer required, `read` scope) | `limit` (20, capped at 40) | **Who the people you follow follow.** For each of at most 20 accounts the viewer follows, their `following` collection is fetched from the server that owns it and the names in it are counted; an account several of them follow ranks above one that a single account follows. Answers `{suggestions, asked, needs}`, where a suggestion carries the `account`, `followed_by` (how many) and `via` (a few of the handles that do) — Mastodon's Suggestion entity has nowhere to put the count, and the count is the whole reason to believe a graph suggestion. `asked` is how many collections actually answered: many servers do not publish one, Mastodon has a "hide your social graph" setting, and a server that will not say is not an error. `needs` is how many more follows it would take to be worth asking, so a page can say *follow one more account* instead of *nothing found*. Costs one outgoing request per account followed, so it is a route of its own rather than part of `/api/v2/suggestions`, and is rate-limited to 10 per five minutes, per address and per account. An answer is kept for half an hour. |
| GET | `/api/v1/follow_graph/status` | public, no-csrf (viewer required, `read` scope) | — | Whether that walk is worth making: `{suggestions: [], asked: 0, needs}`. Reads this instance's own follows and goes nowhere near the network, which is why it is not rate-limited and the walk is — the page asks this when it opens and the walk only when somebody presses the button. |
| GET | `/api/v1/directories` | public, no-csrf (viewer required, `read` scope) | — | The sources that will be asked, in the order they are asked, this instance first. Each is `{host, kind, label}`. Published rather than left for the client to assume: which servers get asked is an administrator's decision, and a reader is entitled to see whose directory they are searching before they search it. |
| GET | `/api/v1/directories/hashtags` | public, no-csrf | `q` (''), `source` (''), `limit` (20, capped at 40) | **What other servers are talking about.** With `q` empty, each asked server's own trending hashtags; with `q` set, that tag wherever those servers know it. Answers `{tags, sources}` with the same `sources` reporting as the search above. Ranked by **how many servers named a tag**, not by their counts added together: instances differ in size by four orders of magnitude, so a sum ranks the biggest server's opinion as everybody's, while "busy on four servers" is a fact a reader can check. Nothing is fetched, ingested or stored — a tag is a string, no post is retrieved and no actor is cached, which is why this needs no viewer where the people search does. At most five servers are asked, each answer is kept for fifteen minutes, and a tag a moderator here has rejected is gone before ranking. |
| GET | `/api/v1/directories/search` | public, no-csrf (viewer required, `read` scope) | `q` (''), `source` (''), `limit` (20, capped at 40) | People matching `q`, merged from every source — or from one, with `source` naming its host. Answers `{accounts, sources}`. A viewer is required, unlike the local directory beside it: this route makes requests to other servers on the caller's say-so, and an endpoint that does that for anonymous callers is an open proxy with extra steps. Rate-limited to 30 a minute, per address and per account. |

A `tags` row is `{name, servers, servers_count, uses, local}`. `name` is the tag as this instance spells it — lower-cased, without the `#`, and only if it is shaped like a hashtag at all: what comes back is a string this instance is about to show and offer to follow, so a server answering with a sentence, a URL or markup has its answer dropped rather than displayed. `servers` names them in the order they were asked, `local` says whether this instance has seen the tag as well, and `uses` is what those servers said added up — kept because it is what they said, and used only to break ties between tags the same number of servers named.

**Which servers can answer what is a fact about their APIs, not a choice here.** A `mastodon` source is asked `/api/v1/trends/tags`, which is public; it has no public tag search, since `/api/v2/search` needs a token exactly as it does for accounts, so a search matches `q` against that same trending page and finds a tag that is busy there and nothing else. A `misskey` source is asked `hashtags/trend` and, for a search, `hashtags/search` — both public, so Misskey answers a search properly. `lemmy` and `wordpress` sources are not asked at all and are reported as `unsupported`: Lemmy organises by community and the curated directory lists people, so neither has the question.

`accounts` are **not** Mastodon `Account` entities and deliberately do not look like them. An `Account` carries an `id` a client hands straight back to this instance's API, and the id in a remote directory's answer is a row number in somebody else's database — the same string means a different person here. These carry `acct` (always a full `user@host`), `username`, `host`, `display_name`, `note` (**text**, with markup stripped: a bio arrives as HTML on Mastodon and as plain text on Misskey), `avatar`, `url`, `followers_count`, `statuses_count` (`-1` where the directory did not say), `bot`, `known` (whether this instance already holds the actor, so a client can offer the local profile instead of a stranger's website), `source` and `source_kind`. The handle is the durable reference and the only thing a client should act on — `POST /api/v1/current/follow?account=…` takes exactly that.

`sources` reports every source with a `status`: `ok`, `failed` (it did not answer) or `skipped` (the fan-out's ten-second budget ran out first). **A client is expected to show it.** "Nobody by that name" and "that server did not answer" are different answers, and a reader deciding whether to try another spelling needs to know which one they got.

Five kinds of source are understood. For a configured source the kind is configured rather than sniffed — sniffing means a request before the request for an answer that changes once in a server's lifetime, and a wrong guess is a source that silently answers nothing. A source this instance worked out for itself is the exception and has to ask, which is what NodeInfo is for; see below.

- **`local`** — this instance's own directory and its cached actors. Always first, always present, never a network request, so it answers even when every other source is unreachable.
- **`mastodon`** — `/api/v1/directory` and `/api/v1/accounts/lookup`, which is also what Pixelfed, Hometown, Glitch and most forks serve. Mastodon has **no public search** (`/api/v2/search` needs a token), which is a fact about Mastodon rather than an omission here: the lookup answers "is there a `nextcloud` on that server" exactly, the directory page answers "who is active there", and the query is applied to that page by this app. One page of 80, not a walk of somebody else's user list.
- **`misskey`** — `users/search`, a real substring search. A user's `host` is `null` when they are that server's own, which is the one thing that makes a Misskey handle ambiguous if taken at face value.
- **`lemmy`** — `search` with `type_=Users`. Lemmy hands over the full `actor_id`, so the handle is read out of that and a person that server merely knows about is attributed to the server they are actually on.
- **`wordpress`** — a directory somebody keeps by hand, published as a WordPress site and asked through `/wp-json/wp/v2/posts?search=`. It is the only kind that answers a **subject**: every other source can say whether there is an `alice` on that server, this one says who writes about mycology, because a person wrote that down. The entries are prose about accounts all over the fediverse, so the handle is read out of the entry text and the host comes from the handle rather than from the directory. Only the entry's own text is read — nothing follows the links in it, so an entry cannot make this instance fetch an address somebody else chose. `fedi.directory` is the one that ships.

Nobody on a domain this instance will not federate with is offered, silenced domains included. The fetch is already guarded — `CurlService` refuses a host the access list excludes — but that guards the server being *asked*; these are people it is telling us about, and a follow button for somebody on a blocked domain would be this instance recommending exactly what it refuses to deliver to.

An administrator sets the sources with the `directories` app value — a JSON array of `{host, kind, label?}`. The same three states as the starter packs, and for the same reasons: **unset** is what ships; **`[]`** is this instance alone; **a list** replaces the shipped sources entirely. A host written as a URL is read as a host, an unknown `kind` is read as `mastodon` rather than dropped, and `local` cannot be claimed by a remote entry. What ships is `fedi.directory` and the largest public instance of each software family whose purpose is people posting to people — `mastodon.social`, `misskey.io`, `lemmy.world`, `pixelfed.social`. None was chosen because somebody here likes it, and this instance publishes its own directory to them on exactly the same terms.

Two more kinds of source are not configured at all, and each entry says which it is in its `origin` (`configured`, `federation`, `discovered`), because a reader is entitled to know how their Nextcloud came to be asking a stranger's server about people:

- **The servers this instance already federates with**, most-known first — ranked by how many of their accounts are cached here, which is the strongest available signal for "we deal with them a lot". An editorial list is somebody else's idea of where people are; this is the instance's own, and asking them costs nothing that following people on them did not already cost. The kind cannot be configured for a server nobody configured, so each is asked its NodeInfo, by `Cron\Cache` and never by the request, and the answer — including "runs something none of these APIs fit", which leaves it out rather than asking it in a language it does not answer — is kept for a week in the `directory_known` app value. A peer the cron has not asked yet is not listed until it has, at most eight a run. How many are asked is the `directory_peers` app value, default 4; `0` asks none.
- **Servers named by a directory of servers** — `fediverse.info`, which publishes a curated list with each server's software, so nothing has to be sniffed. The weakest of the three, being somebody else's editorial choice about servers this instance has never spoken to, so it comes last and contributes at most three. `Cron\Cache` reads the list once a day into the same app value, and a list that does not answer is remembered as empty until the next day, so listing the sources never waits on `fediverse.info` — on a fresh install there are no discovered servers until the cron has run. Set the `directory_discovery` app value to `0` to ask nobody.

A host reached by more than one of these routes is one source, asked once, keeping the label and origin of whichever named it first — so an administrator's own entry is never relabelled by a directory.

`communitywiki.org/trunk` is **not** among them, though it is the kind of curated list that would fit: it answers an automated request with an HTTP 402 and a bot-check page. That is a boundary the site states, and a source that has to be tricked into answering is not a source.

### Collections

Pixelfed's albums: a set of the owner's own posts, in an order the owner chooses. Mastodon defines nothing equivalent, so these are Pixelfed's route shapes — a client that knows Pixelfed finds them where it expects them. Every collection answered by these routes carries its owner as `account` (a Mastodon Account entity), so a page for one has somebody to head it with and can tell whether the reader may manage it.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/collections` | public, no-csrf (viewer required, `read:collections` scope) | — | Every collection the viewer owns, newest first, each with its first three posts as a cover. |
| POST | `/api/v1/collections` | public, no-csrf (viewer required, `write:collections` scope) | `title` (required), `description`, `visibility` (`public`) | Creates a collection and returns it. A blank or whitespace-only title is a **422**. A `visibility` outside `public`/`followers` is stored as `public` rather than refused — there are only two meaningful values and neither is destructive. An account may hold 200 collections. |
| GET | `/api/v1/collections/{id}` | public, no-csrf | — | One collection with its cover. A public one is answered to a signed-out visitor, which is the point of publishing one; a `followers` one is answered to its owner and to accounts that follow them, and is a **404** to everybody else — the same 404 as an id that does not exist. |
| PUT | `/api/v1/collections/{id}` | public, no-csrf (viewer required, `write:collections` scope) | `title`, `description`, `visibility` | Updates only the fields that are sent, and returns the collection. Somebody else's collection is a **404**. |
| DELETE | `/api/v1/collections/{id}` | public, no-csrf (viewer required, `write:collections` scope) | — | Removes the collection and its contents. The posts themselves are untouched. |
| GET | `/api/v1/collections/{id}/items` | public, no-csrf | `limit` (40, max 40), `offset` (0) | The posts of a collection in the owner's order, as `Status` entities. Same visibility rule as the collection itself, and each post is then filtered as the reader: a follower sees the followers-only posts the owner put in, a visitor only the public ones. |
| POST | `/api/v1/collections/{id}/items` | public, no-csrf (viewer required, `write:collections` scope) | `status_id` (required) | Adds one of the viewer's **own** posts, at the end. Adding a post that is already in the collection is a no-op rather than a second entry, so the route is safe to retry. A collection holds at most 100 posts. |
| DELETE | `/api/v1/collections/{id}/items/{status_id}` | public, no-csrf (viewer required, `write:collections` scope) | — | Takes a post out. Removing one that is not in the collection is a no-op. |
| GET | `/api/v1/accounts/{account_id}/collections` | public, no-csrf | — | The collections of an account, as the caller may see them: the public ones to anybody, all of them to the owner and to a follower. This is what a profile draws. |

A collection may only hold posts its **owner wrote**. A collection of other people's pictures would re-publish them on a page with a visibility they never agreed to, and no amount of checking at read time takes that back off the peers that already mirrored the page. Pixelfed has the same rule.

Collections are local. They are not federated as ActivityPub collections and a peer does not see them; what a peer sees is the posts, which it already had.

A post that is deleted leaves every collection holding it, through the same cascade that removes its recipient and tag rows. Suspending or deleting an account removes its collections.

### Places

Where a post was taken. **Nothing here geocodes anything** — no call goes to Nominatim, Google or anyone else. Sending somebody's location to a third party at the moment they are deciding whether to publish it is the same failure the Exif stripping exists to prevent, and doing it deliberately would be worse than doing it by accident.

A place is therefore either one this instance has already seen, or one the client names outright with coordinates it already had. The search is over `social_place`, which holds one row per distinct place anyone here has posted from.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/places/search` | public, no-csrf (viewer required, `read` scope) | `q` (required), `limit` (20, max 20) | Places whose name **begins with** `q`. A prefix match, not a substring one: `LIKE '%term%'` cannot use an index and this is called on every keystroke. A viewer is required because the set of places an instance knows is a rough map of where its people go. |
| GET | `/api/v1/places/{id}` | public, no-csrf (viewer required, `read` scope) | — | One place. |
| GET | `/api/v1/places/{id}/statuses` | public, no-csrf | `limit` (20, max 40), `max_id` | The **public** posts taken at a place, newest first, keyset-paged on the post id — what the place's page draws. Public only whoever asks: the page is a public page, and a followers-only post's location is as private as the post. Replies are left out, being fragments of somebody else's thread rather than pictures of the place. An unknown place is a **404** before any post is read. A viewer is optional and only marks the reader's own bookmarks and favourites on the posts. |

A post carries one by sending either `place_id` (from the search route) or `place_name` with optional `place_country`, `place_lat` and `place_long` to `POST /api/v1/statuses`. A `place_id` that no longer exists means "nowhere" rather than an error — a post is worth more than its location, and refusing to publish over a stale id is the wrong trade. Coordinates outside ±90/±180 are dropped, and a `place_country` that is not two letters is dropped, because a country column holding "United Kingdom" in one row and "GB" in another cannot group anything.

The `Status` entity gains `place`, which is `null` for almost every post: a place is never inferred, only stated. It is filled in one query per page, like the link preview card, rather than joined into every timeline query — almost no post has one, and the join would cost every page regardless.

Places are local and are not federated: a peer sees the post, not where it was taken.

### Stories

**In the API and on the wire, a 24-hour short is a story.** The web client presents one feature, Shorts, with two lifetimes: a *kept* short is an ordinary status with a video, made and read through the status and timeline routes; a *24-hour* short is a story, made, read, seen, answered and deleted through the routes below, with the `read:stories`/`write:stories` scopes, and federated as Pixelfed's `Story` object (fetched through a bearcap, answered with `View`, `Story:Reaction` and `Story:Reply`). The web client's Shorts bar and the first part of its Shorts stack are drawn from the carousel; its composer posts a 24-hour short through `POST /api/v1/stories`. Route names, scopes and fields keep the word story, as Pixelfed's app expects them to.

Pixelfed's stories: one picture, video or text card (drawn into a picture) that stops existing after a day. A story has no `social_stream` row — it is not a post and does not belong in a timeline — but it does travel. A local story is sent to the author's followers as an `Add` whose object is a `Story`, and is withdrawn with a `Delete`: Pixelfed's verbs, and the ones its inbox handles. A `Create` would put it where posts go, and a server that does not know the type ignores the activity, which is the right outcome.

An arriving story is kept only when somebody on this instance follows its author, and no longer than a day whatever the sender's `expiresAt` says — one already past is not stored at all. That a copy cannot be recalled after the day is up is why the expiry is bounded here rather than trusted: this instance's promise about its own copy is one it can keep.

Every route requires a viewer. There is no public story, so there is nothing here to answer a signed-out caller with, and whether an account even *has* a story up is told only to its followers — which is why "not yours to see" and "there are none" are the same **404**.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/stories/carousel` | public, no-csrf (viewer required, `read:stories` scope) | — | The viewer's own live stories, then those of the accounts they follow, oldest first — the order a carousel plays them in. Each carries `seen` for this viewer. |
| GET | `/api/v1/stories/self` | public, no-csrf (viewer required, `read:stories` scope) | — | The viewer's own live stories. Only here and in the carousel is `view_count` filled in: how many accounts watched is told to the poster and to nobody else. |
| POST | `/api/v1/stories` | public, no-csrf (viewer required, `write:stories` scope) | `media_id` (required), `caption`, `duration` (5) | Posts one of the viewer's own uploads. `duration` is clamped to 3–30 seconds and `caption` to 500 characters. An account may have 40 live at once. An unknown or someone else's `media_id` is a **422**. |
| DELETE | `/api/v1/stories/{id}` | public, no-csrf (viewer required, `write:stories` scope) | — | Removes it early, with the record of who saw it. Somebody else's is a **404**. |
| POST | `/api/v1/stories/{id}/seen` | public, no-csrf (viewer required, `write:stories` scope) | — | Marks it seen. Called as a client scrolls, so a repeat is a no-op rather than a second view. |
| GET | `/api/v1/accounts/{account_id}/stories` | public, no-csrf (viewer required, `read:stories` scope) | — | The live stories of one account: its own, or those of somebody the viewer follows. Anything else is a **404**. |

**The shape on the wire is Pixelfed's, because Pixelfed is the only network that has stories.** Its inbox does not read a story out of the activity that carries it: `StoryFetch` requires `object.object`, decodes it as a **bearcap** (`bear:?t=…&u=…`, FEP-d8c2) and fetches what it names with the token. An `Add` without one is dropped without a word. So a published story carries the capability beside the fields themselves — the fields for this app's own inbox and anything else that would rather read than fetch, the capability for Pixelfed — its `attachment` is **one object typed `Image` or `Video`** rather than a list of `Document`s, and it states `published`, an `expiresAt` after it, and `can_reply`/`can_react` as `false`. Each of those is a gate in `StoryFetch::validatePayload()`; every one of them was measured against Pixelfed's source rather than guessed at.

One thing this cannot fix from here: Pixelfed fans its own stories out with `FollowerService::softwareAudience($id, 'pixelfed')`, so it sends them **only to instances it has identified as Pixelfed**. Stories from a Pixelfed account therefore do not arrive here at all, whatever this app implements, and the direction that works is ours to theirs.

Stories from followed remote accounts appear in the carousel beside local ones; a story of the viewer's own is always local, since this instance is where they post.

The expiry is enforced twice, by design. Every read filters on `expires_at`, and `Cron\ExpiredStories` deletes what is due, hourly. If the job never runs nothing expired is ever shown; if a read is ever written without the filter, the job has already removed the row. For a feature whose promise is that the thing goes away, "what you can see" and "what is stored" have to be the same statement.

### Conversations

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/conversations` | public, no-csrf (viewer required, `read:statuses` or `read` scope) | `limit` (20, capped at 40), `max_id` (0), `min_id` (0), `since_id` (0) | The viewer's direct messages grouped into threads, as Mastodon `Conversation` entities — `{id, unread, accounts, last_status}` — newest message first. This is the screen Tusky, Ivory, Ice Cubes and Phanpy read direct messages from. `accounts` are the other participants and never the viewer, so a note to self has an empty `accounts`; `last_status` is nullable, as Mastodon declares it. Sends a `Link` header whose cursor is a **message** nid, not a conversation id: conversations are ordered by their newest message, and a conversation id does not move when a message arrives, so it cannot page. |
| GET | `/api/v1/conversations/unread_count` | public, no-csrf (viewer required) | — | `{count}`: how many conversations hold something the account has not read. This app's own route — Mastodon has none, because its clients count the `unread` flags on a page of conversations, and drawing one number should not cost a page of exchanges with their participants and newest message each. A conversation and not a message: five messages in one exchange are one thing to go and read. Capped at 99. Carries an `ETag` and answers `304` while nothing that changes the count — a direct message, a conversation marked read or dismissed, a block or mute — has changed. |
| POST | `/api/v1/conversations/read_all` | public, no-csrf (viewer required, `write:conversations` scope) | — | Marks every unread conversation read, up to its newest message; answers `{count}` with how many that was. The Direct messages page is one list with the messages on it rather than exchanges opened one at a time, so having looked at it is having read them — the rule the Activities page already follows. Without it the sidebar badge would never come down, since nothing else in the web interface marks a conversation read. Only unread conversations are written. |
| POST | `/api/v1/conversations/{id}/read` | public, no-csrf (viewer required, `write:conversations` or `write` scope) | — | Marks the conversation read up to its newest message and answers with the `Conversation`. The mark is a position, not a flag: a message arriving afterwards makes the conversation unread again. Marking read twice is a no-op, and the mark never moves backwards. Where the conversation runs on Bluesky too, it is marked read there as well, in the background (`chat.bsky.convo.updateRead`; for `read_all`, `updateAllRead`), and one read in a Bluesky app is read here (ATProto chat synchronization). |
| DELETE | `/api/v1/conversations/{id}` | public, no-csrf (viewer required, `write:conversations` or `write` scope) | — | Removes the conversation from the list and answers `{}`. No message is deleted — Mastodon deletes its conversation row and leaves the statuses — and a later message in the same thread brings the conversation back. A conversation that is still a message request on Bluesky is turned down there (`leaveConvo`), never accepted (ATProto chat synchronization). |

A conversation here is **derived**, not stored. Mastodon keeps a conversation row and takes the id from it; this app keeps messages, and the only thing the messages of one exchange share is their chain of `in_reply_to`. A conversation is therefore the thread, and its id is the nid of the thread root — the message with no parent, or the topmost parent this instance stores. That is what makes the id survive the round trip: a client reads the list, the user taps a row minutes later, and the id they send back names the same thread.

Two consequences a client can see. A thread whose root this instance never received groups under the topmost message it does have, so its id changes if that parent arrives later. And because paging is by message, a thread with messages on both sides of the cursor can appear on two pages, the second time with an older `last_status`; a client keys on `id` and updates the row rather than growing a second one.

What an account has *done* with a thread is stored, since it cannot be derived: `social_convo_state` holds how far the account has read it and how far it has dismissed it, both as the nid of the newest message the action covered. A thread with no row has been neither read nor dismissed, which is what an instance upgrading into the table starts with — nothing to backfill. `unread` is false for a message the viewer sent themselves: writing a message is having read the conversation, as on Mastodon.

A conversation the viewer is no part of, and one that does not exist, are the same **404**: membership is decided by the `dm` rows in `social_stream_dest` — the same predicate that put the message in the direct timeline — so telling the two apart would say whether a thread exists and who is in it.

### Keyword filters

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v2/filters` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | Every keyword filter of the viewer, newest first, as Mastodon v2 `Filter` entities. Not paged, as Mastodon does not page it: an account has a handful of filters and a client needs all of them to decide what to blur. `statuses` carries the posts the filter covers by name, as `FilterStatus` entities. |
| POST | `/api/v2/filters` | public, no-csrf (viewer required, `write:filters` or `write` scope) | `title`, `context[]` (`home`, `notifications`, `public`, `thread`, `account`), `filter_action` (`warn` default, or `hide`), `expires_in` (seconds; absent means never), `keywords_attributes[][keyword]`, `[][whole_word]` | Creates a filter and answers with it. A missing `title`, a `context` naming none of the five, an unknown `filter_action` and an empty keyword are each a **422**: a filter with no context applies nowhere, and one with an empty keyword would match every status there is. |
| GET | `/api/v2/filters/{id}` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | One filter of the viewer. Somebody else's is a **404**, not a 403: whether another account has a filter is not this route's to tell. |
| PUT | `/api/v2/filters/{id}` | public, no-csrf (viewer required, `write:filters` or `write` scope) | `title`, `context[]`, `filter_action`, `expires_in`, `keywords_attributes[][id]`, `[][keyword]`, `[][whole_word]`, `[][_destroy]` | Changes a filter. What is not named is left as it is, so a client sending only `title` does not thereby clear the contexts, the expiry or the keywords. `keywords_attributes` edits in place: an entry with an `id` changes that keyword, one with `_destroy` removes it, one without an id adds it. A keyword id belonging to another filter — the viewer's own included — is a 404, and the whole request is then undone: a refused change leaves the filter exactly as it was, so a client may retry what it was told had failed. |
| DELETE | `/api/v2/filters/{id}` | public, no-csrf (viewer required, `write:filters` or `write` scope) | — | Deletes the filter and its keywords, and answers `{}`. |
| GET | `/api/v2/filters/{id}/keywords` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | The `FilterKeyword` entities of that filter. |
| POST | `/api/v2/filters/{id}/keywords` | public, no-csrf (viewer required, `write:filters` or `write` scope) | `keyword`, `whole_word` | Adds one keyword and answers with it. |
| GET | `/api/v2/filters/keywords/{id}` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | One keyword of one of the viewer's filters; anybody else's is a 404. |
| PUT | `/api/v2/filters/keywords/{id}` | public, no-csrf (viewer required, `write:filters` or `write` scope) | `keyword`, `whole_word` | Changes it. What is not named is left as it is. |
| DELETE | `/api/v2/filters/keywords/{id}` | public, no-csrf (viewer required, `write:filters` or `write` scope) | — | Removes the keyword; the filter stays. Answers `{}`. |
| GET | `/api/v2/filters/{id}/statuses` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | The posts that filter covers by name, as `FilterStatus` entities. |
| POST | `/api/v2/filters/{id}/statuses` | public, no-csrf (viewer required, `write:filters` or `write` scope) | `status_id` | Adds one post to the filter — a client's "filter this post" — and answers with the entry. The post is **not** looked up: a filter is the reader's own list and may name a post this server has since deleted or never held, and a lookup would refuse to filter a post the reader is looking at. A missing or non-numeric `status_id` is a **422**. Adding the same post twice makes a second entry, each with its own id, as it does on Mastodon. |
| GET | `/api/v2/filters/statuses/{id}` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | One entry of one of the viewer's filters; anybody else's is a 404. |
| DELETE | `/api/v2/filters/statuses/{id}` | public, no-csrf (viewer required, `write:filters` or `write` scope) | — | Stops the filter covering that post; the filter stays. Answers `{}`. |
| GET | `/api/v1/filters` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | Mastodon's **v1** filters, served over the v2 ones. v1 has no notion of a filter with several keywords — a filter *is* a phrase — so a v1 filter here is a v2 **keyword**, carrying its parent's contexts, expiry and action. That is the mapping Mastodon serves for clients that have not moved, and the reason the ids in the two APIs are different things. The entity is `{id, phrase, context, whole_word, expires_at, irreversible}`, where `irreversible` is v1's name for `filter_action: hide`. |
| POST | `/api/v1/filters` | public, no-csrf (viewer required, `write:filters` or `write` scope) | `phrase`, `context[]`, `irreversible`, `whole_word`, `expires_in` | Creates a v2 filter whose title is the phrase, holding that one keyword, and answers with the v1 entity. |
| GET | `/api/v1/filters/{id}` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | One v1 filter — one keyword of one of the viewer's filters. Anybody else's is a **404**. |
| PUT | `/api/v1/filters/{id}` | public, no-csrf (viewer required, `write:filters` or `write` scope) | `phrase`, `context[]`, `irreversible`, `whole_word`, `expires_in` | Changes it; what is not named is left as it is. |
| DELETE | `/api/v1/filters/{id}` | public, no-csrf (viewer required, `write:filters` or `write` scope) | — | Removes the keyword, and the filter with it when that was its last one — a v2 filter with no keywords matches nothing, and leaving one behind would appear in the v2 list as an empty filter the user never made. Answers `{}`. |
| GET | `/api/v1/social/ai_content` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | **Aloha Social's own route.** Whether the viewer hides posts made with AI: `{"hide": false}` until they turn it on. A filter the app keeps for the reader rather than one they wrote keyword by keyword, so it lives under the filter scopes and is applied in the same place, `FilterService::apply()` — in **every** context at once, lists and notifications included, and whatever contexts the keyword filters name. What counts as made with AI is a *label the post carries*: one of the specific hashtags in `AiContentService::DEFAULT_TAGS` (`#aigenerated`, `#aigeneratedart`, `#midjourney`, `#stablediffusion`, …) plus whatever the administrator added with the `ai_tags` app value, compared case-insensitively and without the `#` (`#ai` by itself is always ignored); or an attachment whose picture states machine-generation provenance in its metadata (IPTC `DigitalSourceType` of `trainedAlgorithmicMedia` or `compositeWithTrainedAlgorithmicMedia`, in XMP or inside a C2PA manifest). A boost is read as the post it boosts. Nothing looks at the pixels or the prose: an unlabelled generated post is not recognised. Every `Status` and `MediaAttachment` entity carries `ai_generated` (bool) whatever this switch says, so a client can draw a quiet label instead. |
| PATCH | `/api/v1/social/ai_content` | public, no-csrf (viewer required, `write:filters` or `write` scope) | `hide` (required; `true`/`false`, `1`/`0`, `on`/`off`, `yes`/`no`) | Turns the switch and answers with the same object. `hide` missing, empty or anything that is not one of those spellings is a **422** — a request that is unclear about a switch must not flip it. The change moves the timelines' ETag like every other write here. |
| GET | `/api/v1/social/counts` | public, no-csrf (viewer required, `read:accounts` or `read` scope) | — | **Aloha Social's own route.** Whether the viewer hides how many likes, dislikes, boosts, replies and followers things have: `{"hide": true}` unless they turned the numbers on — **hidden is the default**, for every account, stored the other way round (`show_counts`) so no migration was needed. While hidden, **every client-API answer to this viewer** carries `favourites_count`, `reblogs_count`, `replies_count` and `dislikes_count` (where it is not null) as `0` on every status, at any depth — timelines, statuses, threads, profiles, notifications, search, conversations, for the web app and for apps signed in with a token alike (`HideCountsMiddleware`). Zero rather than absent, because the entities declare the fields and a client decoding into a typed struct fails on a missing one. How many times a video was watched goes too: `video_card.views` is `null` and `video` has no `views`, which is how those two say nobody counted. An account's `followers_count`, `following_count` and `statuses_count` are **always the real numbers**, the viewer's own and anybody else's: a client told `0` shows "0 followers" as a fact, and the followers list and Statistics count the same people. The web app leaves other people's follower number off their profile for a viewer who hides the numbers, and shows a viewer their own. View counts are left alone too. |
| PATCH | `/api/v1/social/counts` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | `hide` (required; `true`/`false`, `1`/`0`, `on`/`off`, `yes`/`no`) | Turns the switch and answers with the state, `{"hide": …}`. Anything that is not a boolean is a **422** and leaves the switch as it was. |
| GET | `/api/v1/social/feed_preferences` | public, no-csrf (viewer required, `read:filters` or `read` scope) | — | **Aloha Social's own route.** Whether reply posts are hidden as standalone cards in the viewer's home, public and hashtag feeds, plus `thread_sort`, read from the linked account's saved Bluesky `threadViewPref` (defaults to `oldest`). Social applies `oldest`, `newest`, `most-likes` and `random`; `hotness` currently falls back to `oldest`. The replies remain available inside their conversations. |
| PATCH | `/api/v1/social/feed_preferences` | public, no-csrf (viewer required, `write:filters` or `write` scope) | `hide_replies` (required; `true`/`false`, `1`/`0`, `on`/`off`, `yes`/`no`) | Turns the reply-card switch and answers with the state, including the read-only `thread_sort`. Anything that is not a boolean is a **422** and leaves the preference as it was. |
| GET | `/api/v1/social/files_comments` | public, no-csrf (viewer required, `read:accounts` or `read` scope) | — | **Aloha Social's own route.** Whether replies to the viewer's posts made from Files are shown as comments on those files: `{"enabled": true}` unless turned off — **on is the default**, stored as `files_comments` = `0` only once somebody turns it off. While on, a picture or video attached through `POST /api/v1/media/from-file` remembers its file; when the post it is attached to is published public or unlisted, the post is linked to the file. Every **public or unlisted** reply to a linked post — from this server or another, and replies to those — is then copied onto the file as a Nextcloud comment, credited in its first line to its author (`actor_type` `social_fediverse`), with a content warning shown in place of the text and the reply's address added when the comment cannot hold all of it. Replies from accounts or servers the author blocked or muted are not copied; an edit or a delete of the reply follows it. The other way, **only the post's author** speaks for the post: a comment they write on the file goes out as their reply, with the post's visibility, past the same review a post from the composer goes through, and editing or deleting the comment edits or deletes the reply. Anybody else's comment on the file stays on this server. Needs the Comments app. |
| PATCH | `/api/v1/social/files_comments` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | `enabled` (required; `true`/`false`, `1`/`0`, `on`/`off`, `yes`/`no`) | Turns the switch and answers with the state, `{"enabled": …}`. Anything that is not a boolean is a **422** and leaves the switch as it was. Turning it off stops new links, new copies and new replies; comments already on a file stay. |
| PATCH | `/api/v1/social/keyboard_shortcuts` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | `enabled` (required; `true`/`false`, `1`/`0`, `on`/`off`, `yes`/`no`) | **Aloha Social's own route.** Whether the web app's one-key shortcuts (`j`, `k`, `l`, `b` and the rest) are on for the viewer, stored as `keyboard_shortcuts` = `0` once somebody turns them off — **on is the default**. Answers with the state, `{"enabled": …}`. The web app reads it from the page (`serverData.keyboardShortcuts`), so there is no GET. Anything that is not a boolean is a **422** and leaves the switch as it was. |
| GET | `/api/v1/social/direct_messages` | public, no-csrf (viewer required, `read:accounts` or `read` scope) | — | **Aloha Social's own route.** Who may send the viewer direct messages: `{"from": "all"}` (everybody), `"following"` (the people they follow) or `"none"` (nobody). It is the notification policy's `for_private_mentions` seen from the other side — `accept` is `all`, `filter` or `drop` is `following` — plus a stored `none`, which holds direct messages from people followed as well; a sender accepted from the requests still reaches the viewer. A direct message from somebody who may not send one is held like any held notification: it does not notify, and its sender waits among the requests (`/api/v1/notifications/requests`). An account created here starts at `following`; one that never stored a policy is at `all`. On Bluesky the same answer is the `chat.bsky.actor.declaration` record, which its chat service goes by (ATProto chat synchronization). |
| PATCH | `/api/v1/social/direct_messages` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | `from` (required; `all`, `following` or `none`) | Changes who may, and answers `{"from": …}`. `all` sets `for_private_mentions` to `accept`; `following` and `none` set it to `filter` unless it is `drop` already. A change is written to the viewer's Bluesky repository as `chat.bsky.actor.declaration` when they have a Bluesky identity. Anything else is a **422** and changes nothing. |

A filter matches on everything of a status a reader reads: the content warning, the text with its markup taken out and its entities decoded, the descriptions of the attachments and the options of a poll. A boost is matched on **the status it boosts**, which is the only reading under which a filter cannot be escaped by boosting. `whole_word` puts a word boundary on each side of the keyword, but only on a side that starts or ends with a word character — `\b` before a `#` can never hold, and anchoring it blindly would make `#spoiler` match nothing at all. Comparison is case-insensitive and Unicode-aware, and a keyword is never run as a pattern.

A filter stops applying the moment its `expires_at` passes: the expiry is a predicate of every read, not a row something deletes, so an instance with no working cron behaves like one that has.

Where each context is applied, since a filter that names a timeline nothing reads it in is a filter its owner believes is working: `home` on `/api/v1/timelines/home`, `public` on `/api/v1/timelines/public` and `/api/v1/timelines/tag/{hashtag}`, `account` on `/api/v1/accounts/{account}/statuses`, `thread` on `/api/v1/statuses/{nid}/context`, and `notifications` on `/api/v1/notifications`. `/api/v1/favourites/`, `/api/v1/bookmarks` and the direct timeline are read in no context — their statuses carry an empty `filtered`, because its absence is an answer of its own — and so is `/api/v1/statuses/{nid}`, which is one status a client asked for by id rather than a timeline. **`/api/v1/timelines/list/{id}` applies no filter at all**, though `home` is documented by Mastodon as covering lists: the route is `ListController`'s and never reaches `FilterService`, so a `home` filter narrows the home timeline and not the list timelines drawn from it.

The web client edits these through the v2 routes only (`src/components/FiltersSettings.vue`); v1 is left for clients that have not moved. It also *draws* `filtered`: a status carrying one is folded behind the names of the filters that matched (`TimelinePost.vue`, `.post-filtered`) and its body is not rendered at all until the reader presses "Show anyway", the same treatment a content warning gets. Two places a `warn` filter therefore does nothing visible, both because the key never arrives rather than because the client ignores it: `/api/v1/timelines/list/{id}`, which applies no filter, and `/api/v1/notifications`, where `Stream::exportAsNotification()` serialises the nested status without `filtered` — there a `hide` filter drops the notification and a `warn` filter is inert.

### Discovery, trends and relationships

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/trends/statuses` | public, no-csrf | `limit` (20, capped at 40), `offset` (0), `period` (`1h`, `12h`, `1d` — the default —, `3d`, `10d`) | The public statuses interacted with most in that window, most interactions first, with their link previews attached. Counted live from `social_action` — the rows a like and a boost already write — rather than from a stored counter, so the trend cannot drift from the counts a status reports. Public `Note`s only: this is an unauthenticated route, and an aggregate over followers-only posts would report on them to the whole internet even if it never showed one. A status nobody touched in the window is absent rather than a zero at the end. `period` is this app's own parameter, shared with `/api/v1/trends/tags` so a discover page sees one stretch of time; Mastodon has none and gets the default. |
| GET | `/api/v1/timelines/link` | public, no-csrf | `url` (required), `limit` (20, capped at 40), `max_id` (0), `min_id` (0) | The public posts carrying one link, newest first — what a reader gets by tapping a trending link rather than following it off the instance. The links themselves were already served at `/api/v1/trends/links`, so the data was here and the timeline that reads it was not. The url is matched **exactly** rather than by prefix: two pages of the same site are two links, and a prefix match would fold a whole domain into whichever of its pages happened to trend. A missing or unknown `url` is an empty timeline, not an error — the link a client holds may be one nobody here has posted since. |
| GET | `/api/v2/discover/posts` | public, no-csrf | `limit`, `offset` (0), `period` | Pixelfed's discover route: the trending statuses narrowed to the ones with a picture, because a discover screen is a grid of squares and a text post is a poor thing to put in one. The *same* ranking as `/api/v1/trends/statuses`, not a second one, so a post cannot trend there and not here. Public statuses only. |
| GET | `/api/v1/trends/links` | public, no-csrf | `limit` (20, capped at 40), `offset` (0), `period` (as above) | The links most often attached to a public status in that window, as Mastodon `Trends::Link` entities. Counted by url, not by card row: the same article posted by five accounts is one trending link. The card half is the stored preview, serialised by the same class the card on a status uses, so the two cannot disagree about a page. A url still being shared whose preview row went with the post it was fetched for is answered as a bare link rather than dropped. `history` carries a single bucket and `accounts` in it is always `0`: this instance counts uses, not distinct accounts. |
| GET | `/api/v1/directory` | public, no-csrf | `offset` (0), `limit` (40, capped at 80), `order` (`active` default, or `new`), `local` (accepted, no effect) | The local profile directory: the accounts that set `discoverable`. **Opt-in, and that is the whole access rule** — the flag has been stored and federated since `Version1000Date20260911000002` and was read by nothing, so turning it off changed nothing because there was no listing to be kept out of. It is a predicate of the deciding query, so an account that did not opt in is never read and then dropped. `active` orders by when the account last posted in public, accounts that never have at the end; `new` by when it was created. Silenced and suspended accounts are not listed — removing an account from the public timeline and leaving it in the shop window is the same mistake twice. Remote accounts are never listed, which is why `local` makes no difference. |
| GET | `/api/v2/suggestions` | public, no-csrf (viewer required, `read` scope) | `limit` (40, capped at 80) | Accounts to follow, as Mastodon `Suggestion` entities. Derived from two things the app already has: the accounts followed by the accounts the viewer follows, ranked by how many of them do (`friends_of_friends`), then — for a viewer whose graph has nothing to say — local accounts that opted in to the directory, most recently active first. No scoring model: both halves are facts that can be counted. The deprecated `source` field is sent beside `sources`, because clients in the wild read one or the other. Never the viewer, an account they already follow **or have a pending request to**, one they have blocked or muted, one that has blocked them, or one under a moderation decision — every exclusion applies to both halves, since they come from different queries. |
| GET | `/api/v1/suggestions` | public, no-csrf (viewer required, `read` scope) | `limit` (40, capped at 80) | The same list in Mastodon's v1 shape: bare `Account` entities without the source that explains them. Served rather than deprecated away, because a client that never moved to v2 would otherwise draw an empty "who to follow" panel. |
| DELETE | `/api/v1/suggestions/{id}` | public, no-csrf (viewer required, `write` scope) | — | "Stop suggesting this account", and the reason the panel is usable at all: without it the same handful of accounts comes back on every visit, the ones already decided about included. Permanent — the ranking would otherwise put a dismissed account back at the top for the same reasons it put it there the first time. Answers `{}` whether or not the account was ever suggested: the client asked for a state and that state is what it gets. The account may be named by its numeric id, its actor URI or its handle. |
| GET | `/api/v1/featured_tags` | public, no-csrf (viewer required, `read:accounts` or `read` scope) | — | The viewer's own featured tags — the hashtags they pin to their profile. Unpaged, as Mastodon's is. `statuses_count` and `last_status_at` are counted at read time over the account's public and unlisted posts, not stored, so they cannot disagree with the tag timeline a visitor gets by clicking through; `last_status_at` is a date and is `null`, not `""`, for a tag nothing has been posted with. |
| POST | `/api/v1/featured_tags` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | `name` (required) | Pins a hashtag and answers with it. The name is stored as posts are tagged — no leading `#`, lowercased, at most 127 characters — and a name that is not a hashtag at all is a **422** rather than a row nobody can post with. Featuring one that is already featured answers the existing entity. One past `configuration.accounts.max_featured_tags` is a **422**. |
| DELETE | `/api/v1/featured_tags/{id}` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | — | Unpins a tag and answers `{}`. A tag that is not there and a tag that is somebody else's are the same **404**. |
| GET | `/api/v1/featured_tags/suggestions` | public, no-csrf (viewer required, `read:accounts` or `read` scope) | — | The hashtags the viewer posts with most and has not featured, built by the same helper the trends use so they cannot mean something different here. At most ten. |
| GET | `/api/v1/accounts/{account}/featured_tags` | public, no-csrf | — | Somebody's featured tags. Public, as the profile they are drawn on is, and the counts come from public and unlisted posts only. |
| GET | `/api/v1/accounts/{account}/highlights` | public, no-csrf | — | The shape of somebody's posting history, for the top of their profile: `since` (when the account was created, as a unix time), `weeks` (how many public posts fell in each of the last twelve weeks, oldest first), `week_starts` (the unix time the first bucket begins at) and `hashtags` (the three tags they have used most over the last year, `{name, count}`, most used first). Public, and built from public posts alone, so it cannot differ per viewer — a chart that did would say which posts the viewer is allowed to see. **A remote account answers `available: false` with empty arrays**, and a client should then draw nothing: this instance holds a remote account's posts only from whenever somebody here started following them, so a chart of that would show a quiet year for an account that was busy, and there is nothing to tell that apart from an account that really was quiet. Bounded at 5000 posts, so a very prolific account cannot make a profile view an unbounded query. |
| GET | `/api/v1/statuses/{nid}/history` | public, no-csrf (viewer optional, `read:statuses` or `read` scope when a token is sent) | — | Every version the status has been through, oldest first, as Mastodon `StatusEdit` entities — the first being what was posted and the last what is showing now. A revision is written on every edit, so the first entry is never the current text. Answered to anybody, like `GET /api/v1/statuses/{nid}` itself: the status is resolved through the visibility filter first, so one the caller may not read is a **404** and no revision is looked at. A token that *is* presented still has its scope checked — too little is a **403**, not a silent downgrade to an anonymous read. `media_attachments` are the attachments as they were in that version — the same `MediaAttachment` entity a status carries, with `id`, `type`, `url`, `preview_url`, `description` and `meta.focus` — so an edit that only changed a description or a focal point through `media_attributes` shows as one; a revision recorded before the attachments were kept with it has `[]`. `poll` and `emojis` are always `null`/`[]`: no edit here changes a poll. A status edited before the revisions table existed is answered with the one version in the database; nothing is invented. |
| POST | `/api/v1/accounts/{id}/note` | public, no-csrf (viewer required, `write:accounts` scope) | `comment` (empty clears) | Keeps the viewer's private note about the account and returns the updated relationship, whose `note` carries it. At most 2000 characters, counted as characters. An empty or blank comment clears it rather than storing a blank. Never federated, and readable by nobody but its author — not by the account it is about. |
| POST | `/api/v1/accounts/{id}/pin` | public, no-csrf (viewer required, `write:accounts` scope) | — | Features the account on the viewer's profile; `endorsed` becomes true. An account the viewer does not follow is a **422**, and so is a follow the other side has not answered — featuring somebody who may still refuse would publish a claim the viewer has not earned. Your own account is refused. Featuring twice features once. |
| POST | `/api/v1/accounts/{id}/unpin` | public, no-csrf (viewer required, `write:accounts` scope) | — | Stops featuring it. Unfeaturing one that was not featured is not an error. |
| GET | `/api/v1/endorsements` | public, no-csrf (viewer required, `read:accounts` scope) | `limit` (40, capped at 80) | The accounts the viewer features, newest first. The viewer's own and nobody else's. |
| GET | `/api/v1/domain_blocks` | public, no-csrf (viewer required, `read:blocks` scope) | `limit` (100, capped at 200) | The instances the viewer has blocked **for themselves**, newest first, as a flat list of domain strings — which is what Mastodon answers here, not entities. Not the admin's instance-wide access list (`occ social:fediverse`), which applies to everybody at once. |
| POST | `/api/v1/domain_blocks` | public, no-csrf (viewer required, `write:blocks` scope) | `domain` (required) | Blocks every account on that instance for the viewer. What is sent is normalised to the host it names — `Example.COM`, `@user@example.com` and `https://example.com/@user` are one instance. Anything outside `a-z0-9.-` is a **422** rather than a stored pattern, because the comparison is a `LIKE` and a stored `%` would be a block that quietly matched other instances; this instance's own domain is a 422 too. The instance's posts stop reaching every timeline, thread and notification list, matched on the host of the author's actor id — including posts boosted into view by somebody else. Nothing is federated and the instance is never told. |
| DELETE | `/api/v1/domain_blocks` | public, no-csrf (viewer required, `write:blocks` scope) | `domain` (required) | Lifts the block and answers `{}`. Unblocking one that was not blocked is not an error. Posts that arrived while it held come back: the block filtered the read, it did not delete anything. |

### Announcements

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/announcements` | public, no-csrf (viewer required, any token — no scope) | — | The announcements that apply right now, oldest effective first, as Mastodon `Announcement` entities, each carrying `read` for the viewer. Unpaged, as Mastodon's is, and no scope is asked for: what the instance is telling everybody is readable by any user token. An announcement with a start and an end is served **only between them**, and the window is a predicate of the query rather than something a cron deletes — it starts and stops on time on an instance whose cron is broken. `mentions`, `statuses`, `tags` and `emojis` are always `[]` — an announcement is plain text and nothing is parsed out of it — and all four keys are sent because a client that declares them non-optional cannot decode the entity otherwise. `reactions` carries what accounts have put on it: most-reacted first, alphabetical within a tie so a redraw is stable, each with `name`, `count`, `me` for the viewer, and — only when the name is a custom emoji this instance publishes — `url` and `static_url`, which is how a client tells a picture to fetch from a character to render. `content` is HTML built from what the admin typed, escaped, one paragraph per blank line. |
| PUT | `/api/v1/announcements/{id}/reactions/{name}` | public, no-csrf (viewer required, `write:favourites` or `write` scope) | — | Puts one emoji on the announcement for the viewer and answers `{}`. `{name}` is a single emoji or the shortcode of one `occ social:emoji` publishes — the same two things Mastodon accepts, and anything else is a **422**: a label somebody wrote on an instance-wide notice, shown to everybody who reads it, is not a reaction but a second announcement. One emoji is often several code points (a flag, a ZWJ family, a skin tone, a keycap), and all of those are accepted, while two emoji are not. Reacting twice with the same emoji is a no-op; an account may put at most **8** distinct emoji on one announcement, and one at that ceiling can still take one back and put another on. An announcement outside its window can still be reacted to. An id that names nothing is a **404**. |
| DELETE | `/api/v1/announcements/{id}/reactions/{name}` | public, no-csrf (viewer required, `write:favourites` or `write` scope) | — | Takes it back and answers `{}`. Taking back one that was never there succeeds — a client that has lost track of what it sent should not be told the announcement does not exist. Per account: another account's reaction is neither changed nor removable. An id that names nothing is a **404**. |
| POST | `/api/v1/announcements/{id}/dismiss` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | — | Marks it read for the viewer and answers `{}`. Per account: another account's read state is neither changed nor readable. Dismissing twice is a no-op, and an announcement whose window has closed can still be dismissed — a client that was showing it must be able to put it away. An id that names nothing is a **404**. |

### Timelines and notifications

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/timelines/{timeline}/` | public, no-csrf | `local` (false), `limit` (20), `max_id` (0), `min_id` (0), `since_id` (0), `only_media` (false), `only_video` (false), `only_short` (false), `only_news` (false) | One of `home`, `account`, `public`, `direct`, `favourites` (case-insensitive); anything else is a 422 (`UnknownProbeException`). `only_media` keeps just the posts that carry an attachment, which is what the **Photos** view asks of `home`, or of `public` with and without `local` when its switcher is set to Local or Global. It had been parsed off the request since the hashtag timeline gained it and never put to a query, so it used to be accepted and ignored; "no media" has three spellings in the stored column (NULL, `''` and `'[]'`) and all three are excluded. `only_video` is **this app's own, not Mastodon's**, and is what the **Videos** view asks the same three feeds; it is the narrower of the two and wins when both are sent, since every video is media. It keeps a post that carries an attachment whose Mastodon `type` is `video`, *or* that arrived as a PeerTube `Video` — the second counts whether or not this instance found a file in it a browser can play, because the post is a video either way. `only_short` is **this app's own** too, and narrower still: a post whose **only attachment is a `video` of at most 180 seconds that is upright or square** (width ÷ height at most 1), both read from the attachment's `meta` — `duration`, and `original.width`/`original.height` (or the top-level ones, or `aspect`). It wins over `only_media`, `only_video` and `media_type`. A video whose meta does not state both is not a short: a remote video that arrived without them becomes one once this instance has cached the file and measured it. The rule is `Stream::shortKindOf()`, decided on the write and kept in `social_stream.short_kind` (indexed with `nid`), so the narrowing is in the query that picks the page and a page of twenty finds the shorts however far below the newest posts they are; the two thresholds are announced in `/api/v2/config` (`limits.short_max_duration`, `limits.short_max_aspect_ratio`) beside `features.shorts`, which says the parameter is there. `only_news` is **this app's own** as well, and is what the **News** view asks those same three feeds. It is not a narrowing of `only_media` and does not imply it: a post is news when it arrived as an `Article` or a `Page` — the object the blogging servers publish — or when its text carries a link to somewhere else, and an article with nothing attached is news while a holiday photograph is not. A client that sends `only_media` and `only_news` gets the posts that are both. The answer is decided on the write and kept in `social_stream.news_kind`, so a post stored before that column existed is not news until the backfill reaches it. `public` is readable without a token, as Mastodon's is — a client asks for it before it has one — though a token that *was* presented still has to be a good one. Every other timeline needs a viewer. A page with remote counts still due carries `X-Social-Filling: 1`; the web app fetches a fresh page again until the background count refresh stamps it. Sends a `Link` header. Rate-limited per user and per anonymous caller. |
| GET | `/api/v1/timelines/tag/{hashtag}` | public, no-csrf | `limit` (20), `max_id` (0), `min_id` (0), `since_id` (0), `local` (false), `only_media` (false), `only_video` (false), `only_short` (false), `only_news` (false) | Posts carrying `{hashtag}` that are addressed **to** the public collection. An unlisted post carries the tag and anybody may read it, but it names the public collection only in `cc` and is kept off the tag timeline, as on Mastodon; the same rule holds for the followed-tags half of the home timeline and for the For you candidates. The first page of the timeline that is not `local` also has the hashtag's posts beyond this server read in the background (`PostDiscoveryService`, at most every ten minutes per hashtag): the public hashtag timelines of the fediverse servers this one talks to, each post fetched from its own server, and Bluesky's posts with the hashtag. They are stored, so the timeline has them the next time; the answer says **`X-Social-Filling: 1`** while that read is new or while counts on the page are still due. |
| GET | `/api/v1/timelines/list/{id}` | public, no-csrf (viewer required, `read:lists` scope) | `limit` (20, capped at 50), `max_id` (0), `min_id` (0), `since_id` (0), `only_media` (false), `only_video` (false), `only_short` (false), `only_news` (false) | The list's timeline: the home timeline narrowed to the list's members. A route of its own rather than a name in `/api/v1/timelines/{timeline}/`, because a list timeline is a name *and an id*. Narrowed, not widened — every visibility, block, mute and duplicate-boost filter the home timeline applies applies here unchanged, and the membership join can only take posts away, so a list never shows its owner a post their home timeline would not have. `only_media`, `only_video`, `only_short` and `only_news` narrow it in the query that picks the page, as on the other timelines. A list that is not theirs is a **404**. A page with remote counts still due carries `X-Social-Filling: 1`; the web app fetches a fresh page again until the background count refresh stamps it. Sends a `Link` header. |
| GET | `/api/v1/favourites/` | public, no-csrf | `limit` (20), `max_id` (0), `min_id` (0), `since_id` (0) | The viewer's favourited posts, among those the viewer may read now: a followers-only post favourited while following its author is not listed once the follow has ended. Ordered by when each was favourited, newest favourite first, as Mastodon orders it — a post from last month favourited today is first — and paged on the favourite's own id (`social_stream_act.liked_nid`): the cursors in `Link` name the favourite, not the post, and a client follows them as it would Mastodon's. |
| GET | `/api/v1/bookmarks` | public, no-csrf | `limit` (20), `max_id` (0), `min_id` (0), `since_id` (0) | The viewer's bookmarked posts, among those the viewer may read now, ordered and paged on the bookmark (`bookmarked_nid`) as `/api/v1/favourites/` is on the favourite. |
| GET | `/api/v1/notifications` | public, no-csrf | `limit` (20), `max_id` (0), `min_id` (0), `since_id` (0), `types` (array), `exclude_types` (array), `account_id` (the notifications from one account, by its id, handle or actor id) | Notification stream for the viewer. `types`/`exclude_types` keep or drop notification kinds. Nine are served: `mention`, `reblog`, `favourite`, `update`, `follow`, `follow_request`, and — added with the conversation-mute work — `poll` (a poll you voted in, or ran, has closed; its `status` carries the closed poll with its final counts), `status` (an account whose bell you turned on has posted), `moderation_warning` (a moderator acted on your account) and `severed_relationships` (a domain block cut your follows). Eight more are this app's own (`Stream::FIRST_PARTY_NOTIFICATION_TYPES`): `story:react` and `story:comment` (a reaction or a reply to your story), `tagged` (you were tagged in a photo), and five for what only Bluesky tells: `bluesky:repost_liked` and `bluesky:repost_reposted` (somebody liked or reposted your repost; `status` is the post you reposted), `bluesky:verified` and `bluesky:unverified` (a trusted verifier verified your account on Bluesky, or no longer does) and `bluesky:starterpack_joined` (somebody joined Bluesky with your starter pack). **These eight are served to the web app (the Nextcloud session) and to a client that names them in `types[]`; a request with a bearer token that does not name them has them excluded in the query**, so its page stays full — Mastodon's set of types is closed, and a client with a closed enum shows an unknown type as an "unknown notification" row or fails to decode the page. Notifications the account's **notification policy** holds back are not on this list, and neither are those about a post in a conversation the viewer muted; see `/api/v1/notifications/policy` and `/api/v1/notifications/requests`. A `types` naming only kinds this app has no notification for returns nothing, and a stored notification whose sub-type has no Mastodon name is left out of the page rather than sent with an empty `type`. `admin.sign_up`, `admin.report` and `annual_report` are among the ones it does not have: the first two describe a sign-up and a report queue that reach an administrator through Nextcloud's own notifications instead. Sends a `Link` header. |
| GET | `/api/v1/notifications/unread_count` | public, no-csrf (viewer required) | — | `{"count": n}` — notifications newer than the viewer's `notifications` marker that the list shows: neither held by the notification policy (those are counted as requests, `summary.pending_requests_count` on the policy, so a client adding the two counts nobody twice) nor from a muted conversation. Notifications **released by accepting a request** count as unread even where the marker had already moved past them while they were hidden, until the viewer next sets the `notifications` marker (`POST /api/v1/markers`, moving or not). Counted up to 99; past that the answer is 100, which is all a badge shows. Carries an `ETag` and answers `304` while nothing that changes the count — a new notification, the marker, the policy, a decision about a sender, what was released, the muted conversations — has changed. |
| GET | `/api/v1/notifications/{id}` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | — | One notification, as `/api/v1/notifications` serves it. Read through the notification timeline itself, so one that is not the viewer's is a **404** rather than a refusal that would say it exists — as is one whose sub-type has no Mastodon name, which the list leaves out too. |
| POST | `/api/v1/notifications/{id}/dismiss` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | — | Dismisses one notification and answers `{}`. The row is deleted, not flagged: a dismissal is final in Mastodon and the list is built straight off these rows. The post and the Like or Announce behind it are untouched, so no counter moves. Dismissing one that is already gone is a **200** — the client is asking for a state that holds. The Nextcloud notification raised from the same row is withdrawn with it. |
| GET | `/api/v2/notifications` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | `limit` (40), `max_id`, `min_id`, `since_id`, `types[]`, `exclude_types[]`, `grouped_types[]`, `account_id` | Mastodon 4.3's **grouped** notifications: the same list (and, as on v1, this app's own eight types only for the web app or a client naming them in `types[]`), as `GroupedNotificationsResults` — `notification_groups` plus the `accounts` and `statuses` they refer to, each carried once. A page of forty favourites of one post is one group and one copy of the post here, where v1 sends forty rows and forty copies. What groups: favourites and boosts of the same post, and follows. Mentions never group — two people writing to you are two things to read — and neither does anything about a poll, an edit or a moderation decision; each of those is its own group, keyed `ungrouped-{id}` as Mastodon keys them. The `group_key` is built from what the group *is* (`favourite-{status id}`, `follow-all`) and never from the ids in it, so it still names the same group after more arrive. `page_min_id`/`page_max_id` bound the group **on this page**, which is what makes paging work. |
| GET | `/api/v2/notifications/unread_count` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | `limit` (100, the cap), `types[]`, `exclude_types[]`, `account_id`, `grouped_types[]` | How many *groups* are unread, not how many rows: the number on a bell should say how many things happened, and one popular post is one thing. Unread is what is newer than the viewer's `notifications` marker, as Mastodon counts it, plus what accepting a request released behind it, as the v1 count has it; the groups are those `/api/v2/notifications` would draw for the same parameters. Counted up to `limit` (at most 399). Carries the v1 count's `ETag` and answers `304` on the same terms. |
| GET | `/api/v2/notifications/{group_key}` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | — | One group, in the same shape the list serves. A key nothing matches is a **404**. |
| GET | `/api/v2/notifications/{group_key}/accounts` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | — | Everybody in the group, not only the eight the group samples — this is what "and 34 others" opens. |
| POST | `/api/v2/notifications/{group_key}/dismiss` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | — | Dismisses every notification in the group. A group is what the reader sees, so dismissing it has to mean the rows behind it; dismissing only the newest would leave the group on screen with one fewer in it. |
| GET | `/api/v1/notifications/policy` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | — | What this account does with notifications from people it has no relationship with: `for_not_following`, `for_not_followers`, `for_new_accounts`, `for_private_mentions`, `for_limited_accounts`, each `accept`, `filter` or `drop`, plus a `summary` with the two counts a client draws the badge from — exactly the senders and notifications `/api/v1/notifications/requests` lists, counted from who sent what rather than from the notifications read whole. The `GET` carries an `ETag` and answers `304` while nothing that changes it — a notification, a decision about a sender, the policy, the muted conversations, the silenced accounts, the day — has changed; an account that stops following the viewer shows with the next notification. An account **created** here is given a stored policy at creation — the administrator's choice for new accounts (`/admin/notification-policy`), by default the *calm* one: `for_not_following` `filter`, `for_not_followers` `accept`, `for_new_accounts` `filter`, `for_private_mentions` `filter`, `for_limited_accounts` `filter`. An account with no stored policy — every account from before new ones started calm — answers `accept` for all five, as it always did, until its owner chooses. **Nextcloud extension:** `notice` (bool) is `true` exactly for such an account that has neither stored a policy nor dismissed the pointer to it (`POST /api/v1/social/notifications/policy/notice/dismiss`); the web app shows a one-time notice from it. Saving the policy once also puts it away. A notification the policy holds is stored but **raises nothing**: no Nextcloud notification, so no bell, no push to phone apps (they read the same notification), no mail and no Activity entry, and it is not counted in a digest. The hold is decided with the same rules where the notification is stored (`NotificationService::emit()`) as where the list is read. A sender the viewer accepted is never held. |
| PATCH | `/api/v1/notifications/policy` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | any of the five keys | Changes the policy and answers it. What is not named is left as it is, and a decision this app does not recognise leaves its key alone rather than failing the request — a client from a newer Mastodon sending a sixth key must not lose the five that work here. **`drop` behaves as `filter`**: the notification row is written by the inbox long before anybody reads it, and the policy is applied when the list is read, so a policy loosened on Tuesday can still show what was held on Monday. The reader sees the same thing either way; what differs is whether the decision can be taken back. **`drop` is API-only:** it stays available for Mastodon apps, but the web app offers *Allow* (`accept`) and *Hold for review* (`filter`) only, shows a stored `drop` as hold-for-review with a note, and never writes it. Saving puts away the one-time `notice`. |
| GET | `/api/v2/notifications/policy` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | — | The policy at the path a Mastodon 4.3 client reads — and the only place it looks; the v1 spelling above stays for clients written against 4.2, the release this server used to announce. The same five decisions and the same `summary`, from one method behind both spellings. Declared ahead of the group routes, so the word policy is never taken for a group key. |
| PATCH | `/api/v2/notifications/policy` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | any of the five keys | Changes the policy at the 4.3 path and answers it. What is not named is left as it is, a key this app does not recognise is left alone rather than refused, and `drop` behaves as `filter`, as the v1 row explains. A change of `for_not_following` is also a Bluesky app's "who may notify you" (`include` on its notification settings): it is told to the AppView, as the person, and the app's own change of it becomes this one. |
| GET | `/api/v1/social/notification_delivery` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | — | **Nextcloud extension, not a Mastodon route.** *When* this account's Nextcloud notifications are raised, as opposed to the policy's *whether*: `{"mode": "instant"\|"digest", "times": ["08:00", "18:00"], "passthrough": {"direct": true, "mentions_from_followed": true}, "quiet": {"from": "", "to": ""}}`. `instant` is what every account had before this existed. In `digest` the bell is held and rung once per time in `times` (one to four local times, in the zone Nextcloud's own settings hold for the user) with the counts of what came in since the last digest — not counting what the notification policy held or what a muted conversation produced, which never ring. When senders are waiting in the requests inbox the digest's message ends with "{count} people are waiting to reach you"; requests alone never raise a digest; a direct message and a mention from an account the reader follows ring at once, each on its own switch. Quiet hours apply in either mode: inside the window nothing but a pass-through is raised, and a digest is raised when it ends. The in-app list, `/api/v1/notifications` and the markers are unaffected — the stored rows are the hold. Defaults as shown. |
| PATCH | `/api/v1/social/notification_delivery` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | any subset of `mode`, `times` (array), `passthrough` (`direct`, `mentions_from_followed`), `quiet` (`from`, `to`); JSON or form | Changes the setting and answers the whole of it. What is not named is left as it is. Validation refuses the whole change with **422** `{"error": "…"}`: `mode` is `instant` or `digest`; `times` lists one to four distinct `HH:MM` (24-hour, zero-padded) and is sorted on save; `quiet.from` and `quiet.to` are both `HH:MM` and different, or both empty; the pass-throughs are booleans (`true`/`false`, `1`/`0`, or those as strings). Switching to `digest` starts the clock at that moment, so the first digest is not a dump of the backlog; switching away from it raises what it was holding as one last digest. |
| GET | `/api/v1/notifications/requests` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | `limit` (40, capped at 80) | The senders whose notifications the policy is holding, one row each with how many they have sent and their most recent post. One row per *sender* is the point: somebody held back has usually sent more than one thing, and being asked about each in turn is what makes a filtered inbox worse than an unfiltered one. Derived from the notifications themselves rather than stored, over the last `NotificationPolicyService::LOOKBACK` of them. The `id` is the sender's account id, since that is the only stable name a derived row has. |
| GET | `/api/v1/notifications/requests/{id}` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | — | One of those rows; an account that is not being held is a **404**. |
| POST | `/api/v1/notifications/requests/{id}/accept` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | — | "Show me this account's notifications after all." The decision is about the account, so it settles what they have sent and what they send later: the sender is **always allowed** from then on, whatever the policy says, until `DELETE /api/v1/social/notifications/allowed/{account_id}`. What they sent while held joins the list **without raising anything now** — it is old news — and counts as unread in `/api/v1/notifications/unread_count`, even behind the marker. Stored as a relation; it is not a follow and federates nothing. A sender on Bluesky whose conversation with the viewer is a message request there has it accepted on Bluesky too, in the background (ATProto chat synchronization). |
| POST | `/api/v1/notifications/requests/{id}/dismiss` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | — | "Stop asking me about this account." What they sent stays where it is and stays hidden; what changes is that they are no longer offered as a decision. Mastodon deletes those notifications — nothing is deleted here, so a policy the reader loosens later still has something to show. A sender on Bluesky whose conversation with the viewer is still a message request there has it turned down on Bluesky (`leaveConvo`), never accepted (ATProto chat synchronization). |
| GET | `/api/v1/social/notifications/allowed` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | `limit` (40, capped at 80) | **Nextcloud extension, not a Mastodon route.** The senders this account accepted from its requests — *always allowed* — as Account entities, the most recently accepted first. No `Link` header. |
| DELETE | `/api/v1/social/notifications/allowed/{account_id}` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | — | **Nextcloud extension.** Stops always allowing that sender (`account_id` is the account's id): their next notification is judged by the policy again, as if nobody had decided about them. Answers `{}`; an id naming nobody, or a sender that was not allowed, is the state asked for already and answers `{}` too. |
| POST | `/api/v1/social/notifications/policy/notice/dismiss` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | — | **Nextcloud extension.** Puts away the one-time pointer to the policy for good (the user value `notification_policy_notice_dismissed`) and answers the policy, whose `notice` is then `false`. Changes no decision. |
| POST | `/api/v1/notifications/requests/accept` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | `id[]` | The same, for several senders at once. An id naming no account is skipped rather than refused: these arrive from a client clearing a screenful, and one stale entry must not lose the rest of the decisions. |
| POST | `/api/v1/notifications/requests/dismiss` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | `id[]` | The same, dismissing. |
| GET | `/api/v1/notifications/requests/merged` | public, no-csrf (viewer required, `read:notifications` or `read` scope) | — | Always `{"merged": true}`. Mastodon answers `false` while it is still moving rows about after a policy change; nothing is moved here, because the policy is applied when the list is read, so there is never anything in flight. |
| POST | `/api/v1/notifications/clear` | public, no-csrf (viewer required, `write:notifications` or `write` scope) | — | Dismisses every notification the viewer has and answers `{}`. |
| GET | `/api/v1/markers` | public, no-csrf (viewer required) | `timeline` (array of `home`, `notifications`; all of them when omitted) | How far through each timeline the viewer has read: `{"notifications": {"last_read_id": "42", "version": 3, "updated_at": "…"}}`. Always a JSON object, `{}` for an account with no markers yet — never `[]`. Absent timelines have no marker yet. The web client itself draws the line on My Feed from `home` and the New/Earlier headings on Activities from `notifications`. |
| POST | `/api/v1/markers` | public, no-csrf (viewer required, `write` scope) | Body (JSON or form-encoded): `home[last_read_id]`, `notifications[last_read_id]` | Moves markers forward and returns the ones it changed. A marker never moves backwards: two clients reading the same account report their own positions, and the one further behind must not un-read what the other has seen. |
| GET | `/api/v1/annual_reports` | public, no-csrf (viewer required) | — | **The year an account had**, Mastodon's `#Wrapstodon` — one report per year the account wrote anything in, newest first, in Mastodon's `WrappedAnnualReports` shape (`annual_reports`, `accounts`, `statuses`). Each report carries `archetype` (`lurker`, `booster`, `pollster`, `replier` or `oracle`), a `time_series` of twelve months with what was posted and who arrived, the `top_hashtags` used, and `top_statuses` by boosts, replies and favourites. **Computed on demand and never stored**: the same answer comes out of the posts already in the database, so a report cannot go stale and an instance that never runs its cron still has one. `share_url` is **null** — Mastodon's points at a public page of its own, this app has none, and inventing an address would be a link that 404s in somebody's post. `schema_version` is 1, the shape Mastodon 4.3 defined. At most 10000 posts and 5000 followers are walked. |
| GET | `/api/v1/annual_reports/{year}` | public, no-csrf (viewer required) | `year` | The one year, in the same wrapper. A year the account wrote nothing in answers with an empty wrapper rather than twelve empty months. |
| GET | `/api/v1/annual_reports/{year}/state` | public, no-csrf (viewer required) | `year` | `{"state": "available"}` or `"ineligible"`. **`generating` never comes back**: the report is a query rather than a job, so there is nothing to wait for. A future year is `ineligible`. |
| POST | `/api/v1/annual_reports/{year}/read` | public, no-csrf (viewer required) | `year` | Marks one read, so a client stops offering it. Kept as a per-account preference (`annual_reports_read`), because that is all it is: a note about a report that is not stored either. |
| POST | `/api/v1/annual_reports/{year}/generate` | public, no-csrf (viewer required) | `year` | A **no-op that answers 200**. There is nothing to generate — the report is ready the moment it is asked for — and the route exists because a Mastodon client calls it before it reads, and a 404 there is a client that never asks again. 30 an hour. |

All four return a bare JSON array of statuses (no envelope) together with a `Link` header — see Pagination.

The home timeline is two pages, not one query. A post belongs there if the viewer follows its **author** or follows one of its **hashtags** and the post is public; each half is a query over `social_stream.nid`, and they are merged, deduplicated and cut to `limit` before the rows are read. Written as one query the two halves would be an OR across two different joins, which no index can serve. Merging is exact rather than approximate: both halves are cut to the same `limit`, so anything belonging in the top `limit` of the union is in the top `limit` of its own half. A post that is both followed and tagged appears once, and the visibility, block, mute, silence and duplicate-boost filters apply to both halves — the hashtag half additionally reaches no further than a stranger can read, since a followed hashtag is not a relationship with the author.

### Followed hashtags

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/followed_tags` | public, no-csrf (viewer required, `read:follows` or `read` scope) | `limit` (20, capped at 50), `max_id` (0), `min_id` (0) | The hashtags the viewer follows, as Mastodon `Tag` entities with `following: true`. Newest follow first. Sends a `Link` header whose cursor is the `social_followed_tag` row id, not the tag: a tag can be unfollowed and followed again, so its name does not move in one direction and cannot page. |
| GET | `/api/v1/tags/{hashtag}` | public, no-csrf (viewer required, `read:follows`, `read:statuses` or `read` scope) | — | One `Tag` entity — `name`, `url`, `history`, `following` — for `{hashtag}`, with or without its leading `#`. A tag nobody has posted is not a 404: it is a real tag with an empty `history` and `following: false`. |
| POST | `/api/v1/tags/{hashtag}/follow` | public, no-csrf (viewer required, `write:follows`, `write` or `follow` scope) | — | Follows the hashtag and returns the `Tag` with `following: true`. Following one that is already followed is not an error, so a client that lost the answer and retried gets the same tag back. From then on the hashtag's new posts beyond this server are read in the background every quarter of an hour (`Cron\FillFollowedTags`, at most 20 a network, none older than two days) and reach the home timeline like any public post carrying it. |
| POST | `/api/v1/tags/{hashtag}/unfollow` | public, no-csrf (viewer required, `write:follows`, `write` or `follow` scope) | — | Unfollows it and returns the `Tag` with `following: false`. Unfollowing what was never followed is not an error either. |

Following a hashtag is what puts its **public** posts into the viewer's home timeline, as if their authors were followed — that is the whole of the feature, and the rest of it is how a client says which tags.

A hashtag is stored and compared in one form: the tag with no leading `#`, trimmed, lowercased, and cut to the 127 characters `social_stream_tag.hashtag` holds (`FollowedTagsRequest::normalise()`). So `#NextCloud` and `nextcloud` are one tag to follow, one tag to look up and one tag to unfollow. A post's tags are stored in the same form, so `/api/v1/timelines/tag/{hashtag}` normalises `{hashtag}` the same way and compares it with the stored tag exactly, which the `social_st_ht` index can answer. Something that normalises to nothing — `#`, or spaces — is a **422**, not a stored row that no post could ever match.

The `history` of a `Tag` from any of these routes is the one the trends endpoint sends: a single bucket for the default window (`1d`), `uses` from the counts the cron keeps, and `accounts` always `0` because this instance counts uses rather than distinct accounts. A hashtag nobody has posted has an empty `history` rather than a zeroed bucket, because a zero would be a claim about a day. `following` is present on every `Tag` these routes return and absent from `/api/v1/trends/tags`, which is a public route with no viewer to answer it for.

### For you

#### For You recommendation preferences

These additive routes are controlled by the separate instance-wide `rec_v4_enabled` switch in Administration → Social → For you. It defaults to off. The web feed learns interests automatically; readers do not choose topics. The API exposes no topic catalog, topic preference write, or topic-specific feed route. Behavioural learning has a separate per-account consent setting and defaults to off. All state is scoped to the authenticated Nextcloud account. Updates use optimistic revisions and a stale write returns **409** with the current owner state.

| Method | Route | Access and parameters | Outcome |
|---|---|---|---|
| GET | `/api/v1/recommendations/preferences` | `read:accounts` | Activity-learning status only: revision, reset generation, consent mode, and whether learning is currently active under the instance switches. Topic preferences are not exposed or writable. |
| PUT | `/api/v1/recommendations/learning` | `write:accounts`; `if_revision`, `mode` (`off`, `on`, `paused`) | Changes the separate behavioural-learning consent; every transition advances the generation so buffered earlier events are rejected |
| POST | `/api/v1/recommendations/signals` | `write:statuses`; at most 100 events with UUID `event_id` and integer current `generation` | Accepts `impression`, `skip`, `open`, `media`, `link`, `video_watch_ratio` and `profile_visit`. Post events use the established reading contexts (`home`, `local`, `federated`, `tag`, `explore`, `detail`, `interests`, `photos`, `videos`, `shorts`, `reels`); profile visits use `profile`. An impression needs a UUID `session_id` and integer `visible_ms` ≥ 750, and a video ratio must be a JSON number from 0 to 1. Validates current visibility and consent before projection, deduplicates events, and updates eligible topic, author and format signals. |
| POST | `/api/v1/recommendations/reset` | `write:accounts`; `if_revision`, optional `scope` (`learning`, `all`) | `learning` clears implicit signals and impressions; `all` also clears legacy internal fields and feedback. Neither changes follows, mutes or blocks |
| POST | `/api/v1/recommendations/feedback` | `write:statuses`; `event_id`, visible `post_id`, `kind` | Records an idempotent, owner-scoped `HIDE_POST`, `MORE_SIMILAR`, `LESS_SIMILAR`, `MORE_AUTHOR` or `MORE_FORMAT` action; similarity feedback applies to an automatically derived non-sensitive content cluster; returns a ten-minute Undo token |
| DELETE | `/api/v1/recommendations/feedback/{feedbackId}` | `write:statuses` | Reverses only the named owner's feedback action before its Undo deadline; repeating Undo is safe |
| GET | `/api/v1/recommendations/context/{postId}` | `read:statuses` | Returns whether automatic similarity feedback is available and the detected format for a post the reader can currently see; no topic labels are exposed |
| GET | `/api/v1/recommendations/export` | `read:accounts` | Versioned export of the reader's activity-learning status and active feedback |
| GET | `/api/v1/recommendations/timeline` | `read:statuses`; optional `limit` (1–50), opaque `cursor`, and `media` (`photos`, `videos`, `shorts`, `media`) | Web For You timeline envelope: existing status objects in `items`, snapshot/session metadata, profile and algorithm versions, coverage state, and an opaque continuation cursor. One automatic ranker combines learned interests, content classification, freshness, follows and local discovery; separately consented behavioural signals refine new sessions. Legacy topic preferences do not control the feed. |
| GET/PUT | `/admin/recommendations` | administrator, CSRF; PUT accepts any subset of `enabled`, `remoteDiscoveryPaused`, `learningPaused`, `forceLegacyFeed` | Reads or partially updates instance-wide rollout and emergency switches. Pausing remote discovery keeps cached candidates rankable; pausing learning blocks behavioral signal writes; forcing the legacy feed affects only the web For You timeline. Unnamed switches are unchanged. |
| GET | `/admin/recommendations/discovery` | administrator, CSRF; optional `hours` (1–168, defaults to 24) | Reads instance-wide per-provider discovery calls, failed/rate-limited requests, posts seen/stored, average batch duration and last attempt/success. Seven-day hourly aggregates contain no query terms, topics, reader identities or post IDs. |

An ancestor `HIDE` is inherited by descendants and cannot be overridden in this foundation release. A child choice overrides an inherited soft value. The catalog and persistence layer perform no remote requests.

For ranked timeline statuses, `interest.explanation` is bound to the immutable feed snapshot and is present only on this personalized timeline. It contains a primary reason, selected non-sensitive topic IDs, additional signals that actually affected ranking, the local cached-candidate source and ActivityPub/ATProto representation, selection stage and re-ranking note, plus profile, policy, explanation, and algorithm versions and the snapshot creation time. It contains no raw scores or event history. The client localizes the topic names and explanation, and labels it as recorded when the feed was loaded; it must not treat the explanation as an authorization decision.

Legacy hashtag-interest routes remain available to the web client. They expose the reader's own learned profile and controls, but do not let clients add, pin, move, or delete individual topics. New For You learning and feedback use the `/api/v1/recommendations/` routes above.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/interests` | public, no-csrf (viewer required, `read:accounts` scope) | — | The reader's learning settings, ranked hashtag interests, nearby candidates, thin-profile flag, and configured cap. |
| POST | `/api/v1/interests/reset` | public, no-csrf (viewer required, `write:accounts` scope) | — | Clears the reader's learned hashtag profile and reading baseline, then returns the current state. |
| PUT | `/api/v1/interests/settings` | public, no-csrf (viewer required, `write:accounts` scope) | Any of `learning`, `paused`, `languages` (up to 20 language codes), `noticeAcknowledged` | Saves only the named settings and returns the current state, including `instancePaused` when the administrator has globally stopped behavioral learning. |
| POST | `/api/v1/interests/signals` | public, no-csrf (viewer required, `write:statuses` scope), 30 a minute | Up to 100 `{status_id, kind, ms, context}` events | Records eligible reading signals from posts the viewer can see. The server reads hashtags from the stored post; the client cannot supply them. Answers **204**, including when learning is paused. |
| POST | `/api/v1/interests/less/{nid}` | public, no-csrf (viewer required, `write:statuses` scope) | — | Hides a visible post from the legacy interest feed and reduces its hashtags' learned weight. Answers `{}`. |
| DELETE | `/api/v1/interests/less/{nid}` | public, no-csrf (viewer required, `write:statuses` scope) | — | Undoes a recorded “less like this” action and restores its learned weight. Repeating the undo is safe. Answers `{}`. |
| GET | `/api/v1/timelines/interests` | public, no-csrf (viewer required, `read:statuses` scope), 300 a minute | `limit`, `max_id`, `offset`, `media`, `only_media`, `only_short` | The compatibility timeline ranked from learned interests and existing fallback sources. Visibility, mute, block, language and keyword filters apply as on other timelines. |

**Paging a ranked feed.** The next page of a ranking is not “older than the last post”, so the ranking is made once, kept for an hour (each read extends it) and cut into pages. `max_id` is the last post of the previous page, which is what every Mastodon client sends, and the `Link` header's `next` names it; there is no `prev`. A request with no cursor ranks afresh. Where no ranking is kept — it expired, or the instance has no memory cache — it is made again and the cursor looked up in it; a cursor that is no longer in it ends the feed.

**Learning from actions.** A favourite, a boost, a bookmark and a reply teach the reader's interests wherever they come from, a Mastodon app included (`ActionService`, `PostService`). Reading-time signals come from the web interface.

### Polls

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/polls/{nid}` | public, no-csrf (viewer required) | — | The Mastodon `Poll` entity of the status `{nid}`: options with vote counts, `expires_at`/`expired` (true from `expires_at` itself on: the sweep that tells the voters runs on that second, and a vote taken on it would change results already announced), `multiple`, `voters_count`, and the viewer's `voted`/`own_votes`. 404 when the status is not a poll. |
| POST | `/api/v1/polls/{nid}/votes` | public, no-csrf (viewer required, `write` scope) | `choices` (array of option indices) | Votes on a *federated* poll: each choice is delivered to the poll's author as an ActivityPub vote note; the chosen indices are remembered locally so the poll renders as voted, and the authoritative counts arrive later as an `Update{Question}` from the origin. 422 on invalid or duplicate votes and on expired polls. A vote on a **local** poll is counted here instead of being delivered — this instance is the origin, so there is nobody to ask — and polls are created like any other post, by passing `poll` to `POST /api/v1/statuses`. |

Incoming federated polls (`Question` objects) are stored like notes, appear in every timeline, and carry the `poll` entity in their status export; a remote `Update{Question}` refreshes the counts, and one that changes nothing but the counts is not an edit: no new version in the history, no `update` notification.

### Link previews

Statuses carry Mastodon's `card` entity: `url`, `title`, `description`, `type` (always `link`), `provider_name`, `image`, and the fields this app cannot fill (`author_name`, `html`, `width`/`height`, `embed_url`, `blurhash`) as empty values so that clients reading them blindly keep working. It is `null` for a post that links nowhere.

There is no endpoint for cards — they are derived data, never federated, and every instance reads the linked page itself:

- The first plain link of a post is what gets previewed; mentions and hashtags are skipped, and only `http(s)` links count.
- The page is read by a background job (a `LinkPreview` item in the stream queue, drained by cron or `occ social:queue:process`), so posting and inbox delivery never wait for a stranger's web server. A post therefore gains its card shortly *after* it appears.
- The fetch goes through `CurlService`, which means: `http(s)` only on the request and on every redirect, no local addresses, a download size cap, a 5 s timeout, and **the instance access list** — with an allow-list configured, previews only come from listed hosts.
- The card is read from `OpenGraph`, then Twitter-card tags, then the plain `<title>` and `<meta name="description">`. Title and description are length-capped and stored as text, never as markup; a preview image must itself be an `http(s)` URL.
- Cards live in `social_stream_card`, keyed by the post, and are deleted with it (including by the retention job).

### Reports

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| POST | `/api/v1/accounts` | public, no-csrf | — | **403** in Mastodon's registration-error shape (`error` plus `details.base[].error`/`description`), because an account here is a Nextcloud account: the server creates it through whatever provisioning it is configured with, and this app is handed one that already exists. The description says where to sign up instead — the server's own registration page when the `registration` app is enabled, and otherwise that an administrator creates accounts. A 404 was the wrong way to say this: a client reads it as "this server is broken" and shows a person nothing they can act on, while a 403 like this is decoded and displayed. `registrations: false` in the instance entity tells the same thing to a client that looks before it asks. The approval queue, the invites and the email confirmation Mastodon builds on top of its sign-up are the server's for the same reason, and this app has no route for any of them. |
| POST | `/api/v1/reports` | public, no-csrf (viewer required, `write` scope) | `account_id` (required), `status_ids` (array), `comment`, `category` (`spam`, `legal`, `violation` or `other`; anything else becomes `other`), `forward` | Files a moderation report about the account (numeric id or full actor id) for the instance admins, who are notified and review it in the Aloha Social section of the administration settings. Reporting yourself is a 422, a missing `account_id` too. With `forward` set and the account on another instance, the report is also delivered there as a `Flag` — **anonymised**: the activity names this instance's own actor and is signed with its key, never the reporter, who is reporting an account on the very instance that would receive their handle. The comment travels as written. Returns the Mastodon `Report` entity (`action_taken`, `category`, `comment`, `status_ids`, `target_account`, …); `forwarded` is `true` only once the remote inbox has accepted the `Flag`, so a forward that could not be delivered reads `false` and the report still stands. Rate-limited to 30 an hour, per address and per account: every report notifies the moderators. |

Incoming federated reports (`Flag` activities from other instances) are stored the same way and land in the same admin panel. One none of whose objects is an account or a post of this instance is dropped — no row, no notification — since there is nothing here for a moderator to act on; one that names a local post but no local account is filed against the post's author. A report that arrived that way is never forwarded on: passing it along would put this instance's name on somebody else's complaint, and two instances doing that to each other is a loop.

### Admin API (Mastodon)

Mastodon's `/api/v1/admin/*`, over the moderation the admin panel has always
had. Every route requires a **moderator**: the user behind the bearer token (or
behind the session) is resolved first and asked of
`AdminApiService::isAdministrator()`, and anyone else is a **403** having had
nothing done on their behalf. A moderator is a Nextcloud administrator, or
somebody an administrator has handed the **Aloha Social** settings section to under
*Administration privileges* — Nextcloud's own settings delegation
(`IManager::getAllowedAdminSettings()`), which is the same gate the admin panel
and its buttons sit behind, so the two cannot disagree about who may act.
Moderating otherwise meant administering the whole server, which is a great
deal of power to hand somebody so they can act on a report. Nothing is
delegated by default, so out of the box only administrators pass. A scope is *not* that check and cannot be — this app's
OAuth registration stores whatever scope string a client asks for, so
`admin:write` on a token says only that some client asked for it. The scope is
required in addition, as Mastodon requires it: a bearer token needs
`admin:read` (or the broad `admin`) to read and `admin:write` to write, and
the `read`/`write` every timeline client holds satisfies neither. An
administrator's own browser session (with its CSRF token) needs no scope,
having no token to carry one.

Every write about one account (`action`, `unsilence`, `unsuspend`,
`unsensitive`, `DELETE`, and Pixelfed's `/api/admin/users/action`) is a **403**
with nothing done when it names the caller's own account, or a Nextcloud
administrator's account and the caller is only a delegate
(`AdminApiService::assertMayActOn()`).

A client finds out whether to offer moderation at all from the `role` of the
CredentialAccount — `verify_credentials`, `update_credentials` and the two
`/api/v1/profile/*` deletions — so it can ask for `admin:read admin:write` only
from somebody who can use them. `AdminApiService::credentialRole()` works it out
on every request, from the same checks as the gate above:

| Who | `id` | `name` | `permissions` | `highlighted` |
|-----|------|--------|---------------|---------------|
| A Nextcloud administrator | `"3"` | `Admin` | every Mastodon flag (`"8388607"`), as Mastodon reports a role with the administrator bit | `true` |
| A user the section is delegated to | `"1"` | `Moderator` | `"591288"`: invite users, view dashboard, manage reports, federation, blocks, taxonomies and users, delete user data — what the admin API lets them do | `true` |
| Anyone else | `"-99"` | `""` | `"65536"`, Mastodon's default role | `false` |

`color` is always `""`. A non-moderator is refused with **403** and no
`WWW-Authenticate` header — see [Client API status codes](#client-api-status-codes)
for why the header would turn it into a 401.

Entities carry every key Mastodon documents. Where this app has nothing behind
one it is sent as the empty value of its type rather than omitted, because a
client that declares a field non-optional cannot decode the entity otherwise:
on `Admin::Account` that is `email` (`""` — the address belongs to the
Nextcloud account and is not republished here), `ip` (`null`), `ips` (`[]`),
`locale` (`""`), `invite_request` (`null`), `role` (`null` — the role is reported to the
signed-in user on their own CredentialAccount, and Mastodon also sends `null`
for an account it holds no user of),
`disabled` and `sensitized` (always `false`, no state here corresponds to
either), `created_by_application_id` and `invited_by_account_id` (`null`).
`confirmed` and `approved` are `true` for a local account and `false` for a
remote one, as on Mastodon: both describe a user of *this* instance.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/admin/accounts` | public, no-csrf (**admin required**, `admin:read` scope) | `origin` (`local` or `remote`), `status` (`active`, `silenced`, `suspended`, `pending`, `disabled`), `username`, `display_name`, `by_domain`, `email`, `ip`, `limit` (40, capped at 200), `max_id` (0), `min_id` (0) | A page of accounts as `Admin::Account`, newest first, with a `Link` header. `origin` outside `local` and `remote` is a **422** rather than an unfiltered page. `status=silenced` and `status=suspended` are read from the instance's decisions rather than from the account table — a suspension deletes the cached actor, so the accounts a moderator most needs to find are the ones the account table no longer holds; those two pages are capped by `limit`, are not paged further, and carry no `Link` header. `pending` and `disabled` are states this app does not have (nothing awaits approval, and a fediverse account has no login to disable) and answer with **no accounts**, as do `email` and `ip` — this instance holds neither for a fediverse account, and a filter that was ignored would have shown the whole instance as the answer to a question about one account. An account whose cached actor cannot be read is left out of the page, but its row still moves the cursor. |
| GET | `/api/v2/admin/accounts` | public, no-csrf (**admin required**, `admin:read` scope) | the same filters and cursors as the v1 row | The same page of `Admin::Account` entities at the path a current admin client calls — one method behind both spellings, so the two cannot disagree about who is on the page or which filters are honoured. |
| GET | `/api/v1/admin/accounts/{id}` | public, no-csrf (**admin required**, `admin:read` scope) | — | One `Admin::Account`. `{id}` is the numeric id, the account's ActivityPub id or a handle (it accepts slashes). The ActivityPub id is accepted because it is the only name left on an account whose cached actor a suspension purged — without it a suspension could be applied over this API and never lifted over it — and it is the `id` the entity itself reports for such an account. Nothing is ever fetched from another server to answer this. Unknown is a **404**. |
| POST | `/api/v1/admin/accounts/{id}/action` | public, no-csrf (**admin required**, `admin:write` scope) | `type` (`silence`, `suspend`, `sensitive`, `none`), `text`, `report_id` | Applies the decision through `ModerationService`, which is the same call the admin panel makes: **silence** takes the account out of the public and global timelines and changes no data; **suspend** deletes what it has posted here, drops its cached actor and refuses what it sends afterwards. `none` is Mastodon's own "warn and take no action": it records a warning, tells the account if it is local, and leaves whatever stands standing — lifting is what the `unsilence` and `unsuspend` routes below are for. (It used to lift instead, because a warning is a strike in a history this app did not keep.) Every one of the three is recorded as a strike, with `text` and `report_id`, in a history a lift does not empty. `text` is kept as the comment on a decision that stands. **`sensitive`** marks everything the account posts from now on sensitive without taking it out of the timelines — the step between doing nothing and silencing, lifted by `unsensitive` below. It was a **422** by name until this app had the tier, and the refusal outlived the gap by a wave. `disable` is still a **422**: it turns off a *login*, and on this server a login belongs to Nextcloud. With `report_id` the report is resolved in the same call, so the decision and the report it came from cannot disagree; a `report_id` that is not a report about this account is a **404** with nothing done, so an unrelated report cannot be closed as a side effect. Answers `{}`. |
| POST | `/api/v1/admin/accounts/{id}/enable` | public, no-csrf (**admin required**, `admin:write` scope) | — | Answers the `Admin::Account` and **changes nothing**: nothing here can disable a login (a fediverse account has none of its own, and the Nextcloud account behind a local one is enabled where Nextcloud keeps it), so there is nothing to undo. It exists because a moderation client calls it unconditionally when clearing a strike, and a 404 there reads as "no such account". |
| POST | `/api/v1/admin/accounts/{id}/unsilence` | public, no-csrf (**admin required**, `admin:write` scope) | — | Lifts a silence, and only a silence: a suspended account is left suspended, so a client that meant to unsilence cannot free one by accident. Returns the `Admin::Account`. |
| POST | `/api/v1/admin/accounts/{id}/unsensitive` | public, no-csrf (**admin required**, `admin:write` scope) | — | Lifts "everything this account posts is sensitive", and only that. The counterpart of `action` with `sensitive`, which this app has had since the tier between doing nothing and silencing was added — without this route an admin client could apply it and not take it off. |
| DELETE | `/api/v1/admin/accounts/{id}` | public, no-csrf (**admin required**, `admin:write` scope) | — | Deletes what the account posted **here**, leaving the account itself. Mastodon's route means the same thing — it removes the data, not the login — and here it could not mean anything else: an account on this server is a Nextcloud account and the server owns it. This is the suspension's destructive half without the refusal: the posts go, the cached actor goes, and a local account's deletion is federated as a `Delete`. **Irreversible**, which is why it is its own verb rather than a severity inside `action`. |
| POST | `/api/v1/admin/accounts/{id}/unsuspend` | public, no-csrf (**admin required**, `admin:write` scope) | — | Lifts a suspension, and only a suspension. What the suspension deleted stays deleted — lifting stops the refusal of what the account sends from now on. Returns the `Admin::Account`. |
| GET | `/api/v1/admin/reports` | public, no-csrf (**admin required**, `admin:read` scope) | `resolved` (absent = the open queue), `account_id` (the reporter), `target_account_id`, `limit` (40, capped at 200), `max_id` (0), `min_id` (0) | A page of `Admin::Report`, newest first, with a `Link` header. The two account filters take the same references `{id}` does; one this instance has never heard of matches **nothing** rather than falling off the query. Each report carries the reporter and the reported account as `Admin::Account` — built from the id the report was filed against when the account itself is gone, which is what a suspension leaves behind — the reported posts as `Status` entities (one no longer here is left out, the commonest reason being that a moderator already took it down), `rules` always `[]` (a report here carries a category, never a rule id) and `forwarded` always `false` (nothing forwards a report to the reported account's own instance). |
| GET | `/api/v1/admin/reports/{id}` | public, no-csrf (**admin required**, `admin:read` scope) | — | One `Admin::Report`; unknown is a **404**. |
| PUT | `/api/v1/admin/reports/{id}` | public, no-csrf (**admin required**, `admin:write` scope) | `category` (`spam`, `legal`, `violation` or `other`), `rule_ids` | Files a report under a different category. A moderator reading one often finds it under the wrong one — `spam` for something that is harassment — and until this the category a reporter chose was the category for ever. A category this app has no name for is a **422**; an unknown id is a **404**, because the report is read before anything is written rather than updated blind. `rule_ids` is accepted and ignored, exactly as it is on `POST /api/v1/reports`: a report here carries a category and never a rule id, and two halves of one API disagreeing about that would be worse than the omission. |
| POST | `/api/v1/admin/reports/{id}/resolve` | public, no-csrf (**admin required**, `admin:write` scope) | — | Marks the report handled through `ReportService` — the same write the admin panel makes — and records the administrator who did it and when, which is what `action_taken_by_account` and `action_taken_at` report. |
| POST | `/api/v1/admin/reports/{id}/reopen` | public, no-csrf (**admin required**, `admin:write` scope) | — | Puts the report back in the queue and clears the record of who acted on it: it described a decision that no longer stands. |
| POST | `/api/v1/admin/reports/{id}/assign_to_self` | public, no-csrf (**admin required**, `admin:write` scope) | — | Takes the report, so a second administrator can see it is being worked on — `assigned_account`. Stored on the report row by `Version1000Date20260911000013`; what is kept is the Nextcloud user id, because an administrator moderates as a user of this server and need not have an Aloha Social account at all (one who has none is reported as `null` rather than as a failure). |
| POST | `/api/v1/admin/reports/{id}/unassign` | public, no-csrf (**admin required**, `admin:write` scope) | — | Gives the report back to the queue. |
| POST | `/api/v1/admin/measures` | public, no-csrf (**admin required**, `admin:read` scope) | `keys` (array, required), `start_at`, `end_at`, `instance`, `id` | One `Admin::Measure` per key: `key`, `unit` (`null`), `total`, `previous_total` and `data`, one point **per day of the window whether or not anything happened on it** — a chart with holes in it is a chart nobody can read. `previous_total` is the same span ending where this one starts, which is the comparison the arrow on the chart is drawn from. The window is snapped to whole days, must be a real range, and may span at most **370** days. The keys this instance can answer: `active_users` (distinct local accounts that **posted** that day — this app has no session of its own to count), `new_users`, `interactions` (likes and boosts), `opened_reports`, `resolved_reports`, and, with the instance named in `instance`, `instance_accounts`, `instance_statuses` and `instance_reports`; with a hashtag in `id`, `tag_uses` and `tag_accounts`. **Any other key is a 422 naming the ones that work**, rather than a row of zeroes: the rest of Mastodon's keys describe a sign-up, an invite system, an email address or a media store this app does not own, and answering `0` to "how many accounts signed up through an invite" reads as "none did", which is a different claim an admin would act on. |
| POST | `/api/v1/admin/dimensions` | public, no-csrf (**admin required**, `admin:read` scope) | `keys` (array, required), `start_at`, `end_at`, `limit` (10, capped at 100), `id` | One `Admin::Dimension` per key, each `{key, data: [{key, human_key, value}]}`. Answerable here: `servers` (the instances whose accounts posted most in the window — the host is read off the author's id in PHP, since there is no host column and four databases do not agree on how to cut one out of a string), `tag_servers` (the same for one hashtag, named in `id`) and `software_versions` (this app, the Nextcloud it runs in, PHP and the database — what an admin is asked for in a bug report; Mastodon lists its own dependencies here). Any other key is a **422**, on the same reasoning as `measures`. |
| POST | `/api/v1/admin/retention` | public, no-csrf (**admin required**, `admin:read` scope) | `start_at`, `end_at` | `Admin::Cohort` rows: one per month of local sign-ups in the window, each carrying one value per month since — how many of that month's accounts posted in it, and that over the size of the cohort as `rate`. An account that never posted is in its cohort and in none of its buckets. Always monthly, whatever `frequency` asks for: a cohort is read over months, and a daily one on an instance with a handful of sign-ups a month is a table of zeroes. |
| GET | `/api/v1/admin/trends/tags` | public, no-csrf (**admin required**, `admin:read` scope) | `limit` (10, capped at 100) | The trending hashtags, exactly as `/api/v1/trends/tags` answers them. On Mastodon these carry a moderator's extra field — whether the trend is approved or awaiting review — and this instance reviews nothing: a trend here is what the counts say. The route exists because a moderation client asks for it by this path and a 404 reads as "this server has no trends". |
| GET | `/api/v1/admin/trends/statuses` | public, no-csrf (**admin required**, `admin:read` scope) | `limit` (10, capped at 100), `offset` (0) | The trending statuses, as `/api/v1/trends/statuses` answers them. |
| POST | `/api/v1/admin/trends/tags/{id}/approve` | public, no-csrf (**admin required**, `admin:write` scope) | — | Records that a moderator has looked at a hashtag and is content for it to trend. **Grants nothing**: trending here shows everything nobody has objected to, which is what it did before these routes existed, so an approval is a note to the next moderator rather than a permission. `{id}` is the hashtag, with or without its `#`. |
| POST | `/api/v1/admin/trends/tags/{id}/reject` | public, no-csrf (**admin required**, `admin:write` scope) | — | Keeps a hashtag out of every trending list and out of Explore. The counters keep counting it, so lifting the decision puts it back with the number it would have had — a decision that could only be undone by waiting for counters to refill is one nobody would risk making. |
| POST | `/api/v1/admin/trends/links/{id}/approve` | public, no-csrf (**admin required**, `admin:write` scope) | — | The same for a trending link, named by its URL. |
| POST | `/api/v1/admin/trends/links/{id}/reject` | public, no-csrf (**admin required**, `admin:write` scope) | — | Keeps a link out of the trending links. |
| POST | `/api/v1/admin/trends/statuses/{id}/approve` | public, no-csrf (**admin required**, `admin:write` scope) | — | The same for a trending post, named by its ActivityPub id. |
| POST | `/api/v1/admin/trends/statuses/{id}/reject` | public, no-csrf (**admin required**, `admin:write` scope) | — | Keeps a post out of the trending statuses, and out of the discover grid that reads the same ranking. It is **not** a takedown: the post stays where its author put it and everybody who follows them still sees it. |
| GET | `/api/v1/admin/tags` | public, no-csrf (**admin required**, `admin:read` scope) | — | The hashtags a moderator has decided about, newest first, with who decided and when. Not every hashtag the instance has ever seen: a decision is the thing worth listing, and the counted ones are already at `/api/v1/admin/trends/tags`. |
| GET | `/api/v1/admin/tags/{id}` | public, no-csrf (**admin required**, `admin:read` scope) | — | One hashtag as Mastodon's `Admin::Tag`: `trendable` is the one field that means anything here. `usable` and `listable` are always `true` — they describe a tag row that can be disabled for *posting* and for *search*, and this app has no equivalent, since a hashtag here is written by whoever types it and exists because a post carries it. Saying `true` is the honest answer to "may this be used", not a placeholder. |
| PUT | `/api/v1/admin/tags/{id}` | public, no-csrf (**admin required**, `admin:write` scope) | `trendable` | Sets whether the hashtag may trend. `usable` and `listable` are accepted and ignored, for the same reason `rule_ids` is on a report: a client sending all three should not have the one that works refused along with the two that do not. |
| GET | `/api/v1/admin/trends/links` | public, no-csrf (**admin required**, `admin:read` scope) | `limit` (10, capped at 100), `offset` (0) | The trending links, as `/api/v1/trends/links` answers them. |
| GET | `/api/v1/admin/ip_blocks` | public, no-csrf (**admin required**, `admin:read` scope) | — | The addresses this instance answers nothing from, newest first, as `Admin::IpBlock`: `ip` (always a CIDR range — a bare address is stored as the range holding only itself, so there is one shape to match against), `severity`, `comment`, `created_at`, `expires_at` (`null` when it does not lift itself). |
| POST | `/api/v1/admin/ip_blocks` | public, no-csrf (**admin required**, `admin:write` scope) | `ip` (required), `severity` (`no_access`), `comment`, `expires_in` (seconds from now) | Refuses an address or range **everything this app serves** — enforced in one middleware rather than per route, because "no access" is a statement about the whole app and a block that held on the inbox but not on the API is not what an admin switched on. A refused request is a **403**, so a peer stops redelivering rather than queueing for days. `severity` may only be `no_access`: Mastodon's `sign_up_block` and `sign_up_requires_approval` police a sign-up this instance has not — an account here is a Nextcloud account and the server decides who gets one — and asking for either is a **422** rather than a row nothing will ever read, since an admin told their rule was stored would believe it was being enforced. A `ip` that is not an address or range is a **422**. Blocking a range already blocked replaces it. |
| GET | `/api/v1/admin/ip_blocks/{id}` | public, no-csrf (**admin required**, `admin:read` scope) | — | One `Admin::IpBlock`. Unknown is a **404**. |
| PUT | `/api/v1/admin/ip_blocks/{id}` | public, no-csrf (**admin required**, `admin:write` scope) | `severity` (`no_access`), `comment`, `expires_in` | Changes the severity, the comment and the expiry. The range is not among what can change — a block on a different range is a different block, as it is on Mastodon. |
| DELETE | `/api/v1/admin/ip_blocks/{id}` | public, no-csrf (**admin required**, `admin:write` scope) | — | Lifts it and answers `{}`. Unknown is a **404**. |
| GET | `/api/v1/admin/email_domain_blocks` | public, no-csrf (**admin required**, `admin:read` scope) | — | The email domains this instance gives no fediverse account to, newest first, as `Admin::EmailDomainBlock`: `domain`, `created_at`, and `history` always `[]` — Mastodon counts the sign-up attempts it turned away and this app does not count them, but the key is sent because a client that declares it non-optional cannot decode the entity. |
| POST | `/api/v1/admin/email_domain_blocks` | public, no-csrf (**admin required**, `admin:write` scope) | `domain` (required) | Refuses a fediverse identity to Nextcloud accounts whose email is at that domain, checked in `AccountService::createActor()`, and at the registration form of external users. Mastodon refuses a sign-up at one of these; for an internal user this is the same question one step later, for an external user it is the same question. It matters on a server with open registration, which is where a throwaway-address domain turns up. Subdomains are covered, the way a domain block covers them. An account with **no** email address is allowed — there is nothing to check it against, and a server that stores no addresses would otherwise hand out no fediverse accounts at all. Anything that is not a domain is a **422**. |
| GET | `/api/v1/admin/email_domain_blocks/{id}` | public, no-csrf (**admin required**, `admin:read` scope) | — | One `Admin::EmailDomainBlock`. Unknown is a **404**. |
| DELETE | `/api/v1/admin/email_domain_blocks/{id}` | public, no-csrf (**admin required**, `admin:write` scope) | — | Lifts it and answers `{}`. Unknown is a **404**. |
| GET | `/api/v1/admin/domain_allows` | public, no-csrf (**admin required**, `admin:read` scope) | — | The instances this server will talk to at all, as `Admin::DomainAllow` entities. The other half of `domain_blocks`, and it means something only while `access_type` is `none_but` — **allowlist federation**, which this app has had all along with no API over it, so an admin client on an allowlisted instance saw an empty block list and no way to tell why. `id` is derived from the domain (the first twelve hex digits of its md5) because the access list is a config array with no ids of its own, and giving it a table so a client could address a row by number would be storing something for the client's benefit alone; every route here takes the domain itself as well. `created_at` is the epoch, the list holding no timestamps. **While the instance federates by a block list every route in this group is a 422** — the mirror of the rule on `domain_blocks`, and for the same reason: one app value holds both lists and only the mode says which it is, so served as allows the entries would read as their exact opposite, and a client removing one to "disallow" it would have unblocked it. |
| GET | `/api/v1/admin/domain_allows/{id}` | public, no-csrf (**admin required**, `admin:read` scope) | — | One of them, by the derived id or by the domain itself. |
| POST | `/api/v1/admin/domain_allows` | public, no-csrf (**admin required**, `admin:write` scope) | `domain` (required) | Adds a domain to the allow list. |
| DELETE | `/api/v1/admin/domain_allows/{id}` | public, no-csrf (**admin required**, `admin:write` scope) | — | Takes one off it. |
| GET | `/api/v1/admin/domain_blocks` | public, no-csrf (**admin required**, `admin:read` scope) | — | Every domain this instance holds at arm's length, at whichever tier, as `Admin::DomainBlock` entities: the **deny list** — the one `occ social:fediverse` and the admin panel manage — as `severity: suspend`, and the **silenced list** as `severity: silence`. Not to be confused with `/api/v1/domain_blocks`, which is one user hiding a server from themselves. A suspension refuses the domain outright, so `reject_media` and `reject_reports` are `true`; a silence refuses nothing and only takes the domain's accounts out of the public timelines, so both are `false`. A domain on both lists is reported as suspended — the stronger tier is the one in force. `private_comment` and `public_comment` are `null` (the lists have no room for a reason), `obfuscate` is `false` (this instance publishes no list of what it blocks), and `created_at` is the epoch — the lists store no timestamps, and that is how this API says so rather than inventing a date. `id` is derived from the domain (the first eight hex digits of its md5, as a decimal string), so it is numeric like every other id here and stable for as long as the entry names the same domain; the routes below take the domain itself just as happily. While the instance federates by an **allow list** (`none_but`) every route in this group is a **422**: the same app value holds the deny list and the allow list, and served as blocks its entries would read as their own opposite — a client that then "blocked" a domain would have added it to the list of the allowed. |
| POST | `/api/v1/admin/domain_blocks` | public, no-csrf (**admin required**, `admin:write` scope) | `domain` (required), `severity` (`suspend` or `silence`; `suspend` when absent) | Blocks a domain at the tier named and returns the entry. An address no hostname could be is a **422**, and so is Mastodon's third severity, `noop`, which records a domain without doing anything to it: there is no such list here, and a 200 that had quietly applied something else would tell the client the domain was under a block it is not. Blocking one already blocked adds nothing and is not an error, so a client that lost the answer may retry. `reject_media`, `reject_reports`, `obfuscate` and the two comments are accepted and ignored — the lists have no room for any of them. |
| GET | `/api/v1/admin/domain_blocks/{id}` | public, no-csrf (**admin required**, `admin:read` scope) | — | One entry, by the derived id or by the domain; unknown is a **404**. |
| PUT | `/api/v1/admin/domain_blocks/{id}` | public, no-csrf (**admin required**, `admin:write` scope) | `severity` (`suspend` or `silence`) | Moves the block between the two tiers: a change of severity takes the domain off one list and puts it on the other, the same severity again changes nothing, and `noop` is the same **422** as above. Answers with the entry as it now stands. |
| DELETE | `/api/v1/admin/domain_blocks/{id}` | public, no-csrf (**admin required**, `admin:write` scope) | — | Lifts the block at whichever tier it was, and answers with the entry that was lifted. |

### Media

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| POST | `/api/v1/media` | public, no-csrf (viewer required, `write` scope) | Multipart: `file` (required, read from `$_FILES['file']`), `description` (the alt text), `thumbnail` (an image, for a video only) | Stores an upload and returns the `MediaAttachment` (images get a resized preview and blurhash; video/audio are stored as-is with the media itself as `preview_url`). Refuses a mime type outside `CacheDocumentService::filterMimeTypes()` — images, video, audio and the document kinds in `DOCUMENT_MIME_TYPES` (PDF, text, Markdown, CSV, ZIP, EPUB, ODF, Office), which come back as `type: "unknown"` with no `preview_url` and, when no `description` was sent, the upload's file name as the description — and a file over its ceiling with a 422. A file PHP itself did not deliver is answered by the reason: over `upload_max_filesize` or the form's `MAX_FILE_SIZE` is a 422 naming the advertised limit for the declared type (`the file is larger than this server accepts (2 MB)`); an empty `$_FILES` under a `Content-Length` over `post_max_size` — PHP drops such a body whole — is the same 422 naming PHP's limit, not `no media found`; an interrupted upload is a 422 `the file upload was interrupted, try again`; no temporary directory, a failed disk write or an extension stopping the upload is a **500** naming the server problem, since nothing is wrong with the file. Each is logged at warning level with the PHP limits in force. **Two ceilings**: `max_size` (10 MB by default) for everything, and `max_video_size` (2048 MB) for video, because an image is read whole into memory to be stripped and resized while a video is copied to storage a chunk at a time and never held. The request-time check can only go on the type the *client* declared, so it is applied again after the content is sniffed — a file that claimed to be a video to get past the first check is refused by the second. The stored row is **not** public: `public` is set later, when a post attaches the media and that post is `public` or `unlisted`, and what it decides is whether a *shared* cache may keep the bytes — not whether `/media/{uuid}` will serve them, which it does for any uuid it is given. `focus` is accepted and not stored. `thumbnail` is Mastodon's field for a video's cover: it replaces the poster frame the server would otherwise take (resized to the preview size, re-encoded as JPEG, with its own blurhash) and is ignored on anything that is not a video, or that is not a picture — a broken cover costs the cover, never the upload. Rate-limited per user. |
| POST | `/api/v2/media` | public, no-csrf (viewer required, `write` scope) | Same as v1 | The same upload; modern clients POST v2 and only fall back to v1 on a 404. |
| POST | `/api/v1/media/from-file` | public, no-csrf (**the Nextcloud session only**: the web app's with its CSRF token, or a Nextcloud app password over Basic with `OCS-APIRequest: true`; a bearer token is a **403** whatever its scopes) | Body (JSON or form-encoded): `path` (required, relative to the viewer's own files), `description` (the alt text) | **Nextcloud extension, not a Mastodon route.** Attaches a file the viewer already has in Nextcloud, so a picture that is already on the server does not have to be downloaded and uploaded back. Reading any of the user's files is more than a client allowed to upload media was granted, so no token scope opens this route: it takes the Nextcloud session, as every route touching the person's files does ([Which credentials a route takes](#which-credentials-a-route-takes)) — the web app's file picker sends it with its session, and a client with a Nextcloud app password. The path is resolved inside the viewer's own user folder and nowhere else — a share they can read is fair game, a traversal is a 422 `no such file`, and so is a folder. The bytes are copied, not referenced: a post keeps the picture it was published with, so moving or deleting the original later cannot empty a post that has already federated. Everything after that is the upload path — the same size ceiling, the same mime filter, the same resizing — and the answer is the same `MediaAttachment`, equally not public until a post says so. The file is remembered against the attachment, so that replies to the post can be shown as comments on it (`/api/v1/social/files_comments`). Rate-limited per user. |
| GET | `/api/v1/media/{nid}` | public, no-csrf | `nid` (path), `preview` (default `''`, ignored) | One of the viewer's own attachments, by the id the upload returned. 404 for an unknown id or someone else's attachment. |
| PUT | `/api/v1/media/{nid}` | public, no-csrf | Body: `description`, `focus` | Updates the alt text or the focal point of the viewer's own upload and returns it. Only before it is posted: an upload one of the viewer's posts carries is a **422** that names `media_attributes` on the edit route, as Mastodon refuses it too. It used to answer 200 while the post kept its own copy with the old words, and no other server heard of the change. 404 for an unknown id or someone else's attachment. Rate-limited to 30 a minute, the same ceiling the upload beside it carries. |
| GET | `/media/{uuid}` | public, no-csrf | `uuid` (path, may carry a `.ext` suffix); the request's own `Range` header is honoured | Streams a cached document by UUID. Either of a document's copies resolves it — the full one that `url` names and the resized one that `preview_url` names. **Range-capable**: answers `Accept-Ranges: bytes` always, and a `Range` request with `206` and a `Content-Range` (a suffix range is the last N bytes, an open range runs to the end, one past the end is a **416** carrying the length, and anything unparseable — the multipart form included — is answered with the whole file, which is always correct). Without this a video could not be seeked and asking for its duration alone cost the whole file. The `Content-Type` is the media type sniffed from the content at ingest, except for the **resized copy of a video**, which is its poster frame and is served as `image/jpeg` — a browser with `nosniff` on, which is every Nextcloud, refuses to draw an image served as `video/mp4`. The extension in the URL is ignored. **Any local copy is served to whoever holds its uuid**, public or not: the uuid is a v4 from `random_bytes()`, unguessable, and handed out only with the post it belongs to — which is also how every other fediverse server fetches media, unsigned and on behalf of a reader it has already checked. Restricting this to rows flagged `public`, as it once did, only meant a broken image under every followers-only and direct post carrying one. What `public` still decides is **caching**: the bytes may be kept for ever either way, but only a public row's may be kept by a *shared* cache, since a proxy in front of the instance would otherwise answer the same URL to anybody. **404** when the uuid names nothing. Rate-limited to 600 an hour anonymous and 3000 for a session — the most generous pair in this group, and deliberately: this is the highest-volume route the app has (a timeline is forty to sixty of these a screen), and a peer pulling a popular post's pictures arrives as one anonymous address. It caps the unbounded case rather than controlling bandwidth, which belongs in front of the server. |
| GET | `/media/stream/{nid}` | public, no-csrf | `nid` (path); the request's own `Range` header is forwarded | **Nextcloud extension, not a Mastodon route.** A federated video, passed through from the instance that holds it — a PeerTube `Video` is referenced rather than mirrored (see [Architecture.md](Architecture.md#peertube-and-federated-video)), so there is no local copy to serve and the bytes come from the origin as they are played. The page cannot point a `<video>` at that origin directly: Nextcloud's content security policy says `media-src 'self'`, and widening it would also mean every reader who pressed play announcing themselves to a server they never chose to talk to. What keeps this from being an open proxy is that it takes a **row id, not a URL**, and only a `social_cache_doc` row this app itself wrote as streamed answers — anything with a local copy is served by `/media/{uuid}` and is a **404** here. Answers `206` with `Content-Range` when the caller sent a `Range` and the origin honoured it, `Accept-Ranges: bytes` either way; nothing is stored, in either direction. **404** for an unknown or non-streamed row, **502** when the origin cannot be reached. |
| GET | `/media/playlist/{nid}` | public, no-csrf | `nid` | **An HLS playlist, with every URI in it pointed back through this server.** A PeerTube transcoding to HLS — the default, and what a public instance federates — publishes a `.m3u8` and nothing but Safari can open one, so the client loads hls.js and asks for this. The rewrite is the point: a playlist names its segments *relative to itself*, so handing one over verbatim would have every segment fetched straight from the origin — which is what `/media/stream/{nid}` exists to prevent, and worse, because it is one request per few seconds of video. Both plain URI lines and `URI="…"` attributes (the encryption keys among them) are rewritten, because a player follows both. Read whole, up to 2 MB. 60 an hour anonymous. |
| GET | `/media/playlist/{nid}/file` | public, no-csrf | `nid`, `u` (the file's address) | One file out of such a playlist — a segment, a key, or a nested playlist — fetched from the origin and streamed on with `Range` support. **`u` is not trusted**: it has to be on the same host, scheme and port as the playlist `nid` names, which is the property `/media/stream/{nid}` has by taking a row id rather than a url, one level further in. Generous limits, because a film is hundreds of segments. |
| GET | `/media/captions/{nid}/{index}.vtt` | public, no-csrf | `nid` (the status), `index` (the track's place in its `video.captions`) | **Nextcloud extension, not a Mastodon route.** One of a video's subtitle tracks, passed through from where it was published as `text/vtt`, stored nowhere — the address `video.captions[].url` carries. Keyed on the post and the track's place in the list it stored, never on a url, and the post is read as the caller may see it, so a track is no easier to reach than its video. Read whole up to 1 MB and refused unless it is WebVTT (it must begin `WEBVTT`). **404** for a post the caller may not see, a track that is not there, and anything that is not WebVTT or could not be read. 60 a minute anonymous. |
| GET | `/media/hls/{uuid}/master.m3u8` | public, no-csrf | `uuid` (path) | **Nextcloud extension, not a Mastodon route.** The master playlist of a *local* video's ladder: which sizes it exists at. Keyed on the **uuid**, the same handle `/media/{uuid}` takes and for the same reason — a ladder is the same video, so it must be no easier to reach than the video; a route on a row id would make a followers-only post's video findable by counting. **404 when the video has no ladder**, rather than an empty playlist: a player handed a master with no rungs reports a broken video, where one that gets a 404 falls back to the plain file, which is what should happen. Served as `application/vnd.apple.mpegurl`. Every address in this group ends in the extension its content actually has, and the three are at different depths so none can be read as another: browsers and hls.js go by the `Content-Type`, but ffmpeg's HLS demuxer checks the **extension** of every segment URI and refuses one it does not recognise. |
| GET | `/media/hls/{uuid}/{height}/index.m3u8` | public, no-csrf | `uuid`, `height` (path) | One rung's playlist: where each segment is inside that rung's file. The stored playlist keeps a placeholder where the media URI goes and it is filled in here — the address is a route on this server, not known when ffmpeg writes the file and different if the instance moves. **404** for a height this video has no rung at. |
| GET | `/media/hls/{uuid}/{height}/video.mp4` | public, no-csrf | `uuid`, `height` (path); the request's own `Range` header is honoured | One rung's fragmented MP4, whole, with ranges. Every segment of a rung is a byte range into this one file (`-hls_flags single_file`), so a player watching a ten-minute video asks this a few hundred times with a different `Range` each time — hence the generous limits. Cached on the same terms as the video itself: for ever in the reader's own cache, and in a shared one only where the post is public. |
| POST | `/api/v1/statuses/{nid}/watched` | public, no-csrf (viewer required) | `position`, `duration` (seconds) | **Remembers where the reader got to in a video.** A two-hour talk watched in three sittings is three sittings of finding the place again. A fact about the *reader*: never federated, never shown to anybody else, never counted into anything, one row per (post, viewer). A video watched to past 95% is **forgotten** rather than bookmarked at the credits, because a "continue watching" row that offers back a finished video is one nobody presses twice. Answers `{"stored": bool}`: `false` when the server could not write the row, so a player does not mistake its own copy for a stored one. 600 a minute — a player reports as it goes. |
| DELETE | `/api/v1/statuses/{nid}/watched` | public, no-csrf (viewer required) | `nid` | Takes a video off the reader's own list. |
| POST | `/api/v1/statuses/{nid}/view` | public, no-csrf | `nid` | **Counts a view of a video posted here**, which is what `video_card.views` shows. The web player sends it once somebody has watched five seconds of the video. At most one view per viewer — the account, or for somebody not signed in the Nextcloud session — per video and day; the author's own plays, videos from other servers and posts that are not videos are not counted. What is kept to tell a second view from a first is a keyed hash of (day, video, viewer), deleted with the day (`VideoViewService`). Answers `{"counted": bool}`, which is nothing to act on: a view not counted is not an error. A post the caller may not see is a **404**. 60 an hour anonymous, 600 for an account. |
| GET | `/api/v1/videos/continue` | public, no-csrf (viewer required) | `limit` (20, max 40) | The videos the reader was in the middle of, newest first — neither the ones they barely started (under 10 seconds) nor the ones they finished. Each status carries `watch_progress`, where the reader stopped in it. |

`POST /api/v1/media` and `POST /api/v2/media` are both served by `MediaApiController::mediaNew()`, and it and `mediaFromFile()` share the storing half (`storeAttachment()`) so the two ways in cannot drift apart on the things that matter — the mime filter, the resizing, and the row not being public. On the wire an attachment's alt text travels as the ActivityPub `name`, both incoming and outgoing.

Every key of a `MediaAttachment` is always present, `null` when there is nothing to put in it (`url`, `preview_url`, `remote_url`, `meta`, `description`, `blurhash`). `meta` is an object, never a list.

`url` is `null` where this instance holds no copy of the file — the cache refused it, or has not fetched it yet. It used to name `/media/` with an empty id in it, which 404s for every client that follows it and is indistinguishable from an attachment that is merely slow. `remote_url` still says where the file came from and `cache_error` why there is no copy (`1` size, `2` type, `3` unreachable, `4` unreadable), which is what a reader is shown. The origin is deliberately **not** offered as a fallback: loading it in the reader's browser would tell the origin who is reading and walk straight past the limits that refused the copy in the first place. The ActivityPub `Document` this row is served as names the origin instead, because a peer asking for the bytes has to be told a host that serves them and no browser is doing that fetch.

`hls_url` is a key of this app's own, alongside Mastodon's. Where an
administrator has turned the ladder on (`video_ladder`) and the background job
has been over a video, it is the address of that video's master playlist — the
same video at two or three sizes, so a player can pick the one that fits the
connection. `null` everywhere else, which is every video on an instance that has
not turned it on, and a client that does not know the key plays `url` and gets
the same video at one size. It is not a *replacement* for `url`: the whole file
is always there beside it, and the bundled player falls back to it if the ladder
cannot be loaded.

### Search (Mastodon-adjacent, app-specific shapes)

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/global/accounts/search` | user | `search` (required) | `{"result": {"accounts": [...], "exact": <account or null>}, "status": 1}`, each a Mastodon `Account` entity (a remote bio sanitised, no copy of the cached actor document). A leading `@` is stripped; an empty query returns empty lists. Nothing is fetched from another server for `exact`. A dotted name also gets the accounts Bluesky's typeahead finds; one not stored here is offered as the AppView described it, with id `0`, and is stored once it is mentioned, opened or followed. The typeahead's answer to a query is reused for a minute. |
| GET | `/api/v1/global/tags/search` | user | `search` (required) | `{"result": {"tags": [...], "exact": <tag or null>}, "status": 1}`. A leading `#` is stripped. |

### Pagination

Client API list endpoints accept the cursor parameters shown per route above (`limit`, `max_id`, `min_id`, and either `since_id` or `since`), all integers defaulting to `0` except `limit` (20 — 40 on `/api/v1/blocks` and `/api/v1/mutes` — capped at 50).

Every paged client API route except `/api/v1/blocks`, `/api/v1/mutes` and `/api/v1/scheduled_statuses` also sends a `Link` header in Mastodon's form, which is the only cursor masto.js — and therefore Elk and Phanpy — reads:

```
Link: <https://cloud.example/index.php/apps/social/api/v1/timelines/home?limit=20&max_id=41>; rel="next",
      <https://cloud.example/index.php/apps/social/api/v1/timelines/home?limit=20&min_id=60>; rel="prev"
```

`next` points below the lowest id on the page and is sent only while a further page may exist (a page shorter than `limit` is the last one); `prev` points above the highest id and is sent whenever the page is not empty. Every other filter the caller sent survives into both links. The routes that send one are `/api/v1/timelines/{timeline}/`, `/api/v1/timelines/tag/{hashtag}`, `/api/v1/notifications`, `/api/v1/favourites/`, `/api/v1/bookmarks`, `/api/v1/followed_tags`, `/api/v1/accounts/{account}/statuses`, `/api/v1/accounts/{account}/followers` and `/api/v1/accounts/{account}/following`. `/api/v1/followed_tags` takes no `since_id` and pages on the followed-tag row id rather than a status id. On the followers and following lists, a page that reaches past the accounts known here into the ones the account's network lists carries only `next`, pointing after its last account. `/api/v1/blocks` and `/api/v1/mutes` send none because they take no cursor to page with, and `/api/v1/scheduled_statuses` sends none because a ScheduledStatus carries no status nid for the header to point at.

"A page shorter than `limit` is the last one" is decided on what the *query* returned, not on what survived any filtering the controller then did. `/api/v1/notifications` drops entries whose sub-type has no Mastodon name; counting those out would have made a filtered page look like the end of the list and stopped a paging client with the rest of it still in the database.

`LocalController` stream endpoints use a different pair: `since` (a numeric cursor, default `0`) and `limit` (default **5**, not 20), and send no `Link` header.

### PeerTube's own routes

The same move as the section above, for the same reason: the official PeerTube app, Tubelab and Fedilab all exist and are good, and a client somebody already has is worth more than one nobody has written. PeerTube's API is **not** Mastodon's — different names, different ids, a different idea of what a video is — so this is a translation and not an alias. The shapes are built in `PeerTubeApiService`.

**Read the two caveats before judging this by what is missing.**

It is **read-only**. PeerTube's upload is a resumable protocol with a transcoding state machine behind it, and a half-built one that took somebody's file and lost it would be worse than none. Comments are read and not posted, because a client posting through this route would go round the review queue the composer goes through — the same reason the Pixelfed routes do not post either.

And it is **gated on the domain root**. No PeerTube client will ask under `/apps/social/`: they all build `https://<host>/api/v1/…` from the address a person types. Every route here is correct and **none of them is reachable by a real client** until this instance answers at its own root, which is item 1 of [Mastodon-Compatibility.md](Mastodon-Compatibility.md) and a decision for whoever runs the server rather than something this app can do to a Nextcloud. Until then these serve `curl`, the interop harness, and anybody willing to configure a rewrite.

Every list answers PeerTube's `{total, data}`. **`total` is the size of this page**, not of everything there is: this app's timelines are keyed on a cursor and have no count to give, and a number invented for the shape's sake is one a client would draw a pager from.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/config` | public, no-csrf | — | What a client reads once, on launch, to decide whether it can talk to this server at all — answered without a viewer, because it asks before anybody has signed in. Every switch says what is **true here** rather than PeerTube's default: `signup.allowed` is `false` (an account here is a Nextcloud account and is not made through this API), the import and upload switches are `false` (nothing here writes), `transcoding.hls` and `enabledResolutions` are the real state of `video_ladder`, and `user.videoQuota` is the real `video_quota` in **bytes** with `-1` for no quota, which is PeerTube's own way of saying it. `instance.defaultNSFWPolicy` is this instance's `nsfw_policy` translated back into PeerTube's three words (`display`, `blur`, `do_not_list`). `serverVersion` is the PeerTube version whose API this answers; a `software` object beside it says what is **actually** running, so a client that reports a version to its user is not told this server runs PeerTube. |
| GET | `/api/v1/oauth-clients/local` | public, no-csrf | — | The client id and secret to log in with. PeerTube hands out **one pair per instance**, the same one to everybody for ever; this app mints a pair per client and **hashes the secret**, deliberately and as a fix to a real problem, so there is no stored plaintext to hand back a second time. A **fresh registration** is answered instead — which satisfies what the route is for, since a client fetches a pair immediately before logging in and uses it at once, and is exactly what a Mastodon client does through `/api/v1/apps`. Registered with the out-of-band redirect urn and `read write follow`. 10 an hour. |
| GET | `/api/v1/videos` | public, no-csrf | `start` (default 0), `count` (default 20, max 100) | The videos this instance has, newest first: the public timeline narrowed with the same `only_video` the app's own Videos timeline uses, so the two cannot come to disagree about what a video is. **Paging is by cursor here and by offset there**, so `start` is applied to the page that was read rather than turned into a cursor that would drift as posts arrive — a client asking for a deep page gets fewer rows rather than wrong ones. |
| GET | `/api/v1/videos/{id}` | public, no-csrf | `id` (**numeric only**) | One video, with its description, tags, support line, files and streaming playlist. **Not addressable by uuid**, although the listing carries one: that uuid is derived from the post's address by a one-way hash — it is the same one this app publishes over ActivityPub, which is the point of it — so there is nothing to look it up by without a column to store it in. A client that lists and then fetches has the id already. The `\d+` requirement is also what keeps this from swallowing `/api/v1/videos/continue`, this app's own "continue watching" route at the same depth. |
| GET | `/api/v1/videos/{id}/comment-threads` | public, no-csrf | `id` (numeric), `count` (default 20, max 100) | The replies to one video, out of the same thread the app's own status context is drawn from — so a reply a client sees here is one the web page shows too. `totalReplies` on each is `0` rather than a count: this app threads replies to replies and PeerTube draws a tree from that number, and a wrong one is a tree with branches that lead nowhere. |
| GET | `/api/v1/video-channels` | public, no-csrf | `count` (default 20, max 100) | The channels of this instance. Capped rather than paged: an instance with more channels than one page is one where a directory is the right answer. |
| GET | `/api/v1/video-channels/{handle}` | public, no-csrf | `handle` (`alice_channel`, or `alice_channel@host` — the host half is dropped) | One channel with its description, owner and follower count. A handle is an actor's `preferredUsername` and is not on the channel row, so the actor is resolved first — which is also what decides that a handle belonging to an ordinary account is **not a channel**, rather than a channel nobody can find. 404 otherwise. |
| GET | `/api/v1/users/me` | public, no-csrf (viewer required) | — | The signed-in account as PeerTube's `User`, with its channels, its NSFW policy (in PeerTube's words) and its video quota and usage in bytes. **The email is `null`**: PeerTube's own answer carries one, and a Nextcloud account's address is not this API's to hand to whatever client holds a token — nothing a video client does needs it, and an absent field reads as "this server does not say" rather than as a wrong address. 401 without credentials. |
| GET | `/api/v1/search/videos` | public, no-csrf | `search`, `count` (default 20, max 100) | Videos matching a word, from the same `SearchService` the rest of the app searches with and narrowed to videos afterwards — so a video findable on one route cannot be missing from the other. An empty `search` is an empty page rather than everything. |

Ids: a video's `id` is the post's `nid`, which is what this app's own API gives a client; its `uuid` and `shortUUID` are both the uuid `PeerTubeService::uuidFor()` mints and already publishes on the wire, so a video seen through this API and the same video seen over ActivityPub carry **one** uuid rather than two nothing can tell apart. `category`, `licence` and `language` are `{id: 0, label}`: PeerTube's ids are indexes into its own lists, which this app does not have and must not guess at — a wrong id is a client showing the wrong category with confidence — and the label is the half that means anything off its own instance.

---

---

## Custom Local API

These endpoints exist to serve the app's own Vue frontend. They are session-authenticated only, mostly wrap their payload in the `{"result": …, "status": 1}` envelope, and are not part of any Mastodon client contract.

A failure on the routes of `LocalController`, `NavigationController` and `OStatusController` answers `{"status": -1, "error": "request failed"}` with a status that says whose failure it is: **404** for a post, account or document that does not exist, **422** for a request that cannot be carried out as asked (somebody else's post, a malformed handle, following yourself), **403** where another instance's policy refuses it, **429** over the follow limit and **502** when another server could not be reached or answered nonsense. Only what is left, a failure of this server's own, is a **500**, and only that is logged.

### Posts

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| POST | `/api/v1/post` | user | `content` (`''`), `to` (array), `type` (default `public`), `replyTo` (`''`), `attachments` (mixed, default `[]`), `hashtags` (array), `poll` (object, optional), `spoilerText` (`''`, the content warning) | Creates a post. A `replyTo` naming a post the writer may not read is a **404**, as one naming nothing is. Returns `{"result": {"post": <object>, "token": "<request token>"}, "status": 1}`. |
| DELETE | `/api/v1/post` | user | `id` (required) | Deletes an own post; `{"result": [], "status": 1}`. An unknown id is a **404**, a post not attributed to the caller a **422**. |

Boosting from a client goes through `POST /api/v1/statuses/{nid}/{act}` with `reblog`.

### Current user

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| PUT | `/api/v1/account/profile-layout` | user, CSRF | `layout`: `{default_tab, tabs}` | Saves the personal account's public profile presentation. Defaults: `posts`, all five tabs. The default can be `posts`, `photos` or `videos` and must remain visible; Posts cannot be hidden. Invalid values are rejected. Returns `{"status": 1, "result": {"layout": {...}}}`. Does not change post audiences or grant access. |
| PUT | `/api/v1/account/fields` | user | `fields` (list of `{name, value}`) | Replaces the profile metadata fields (at most four name/value pairs; entries with an empty half are dropped, names capped at 255 and values at 500 characters). Federated as `PropertyValue` attachments on the actor. A verified link keeps its tick across the save; only a value that actually changed loses one, and it is checked again on the next cron pass rather than a day later. `{"result": {"account": <Person>}, "status": 1}`. |
| PUT | `/api/v1/current/follow` | user | `account` (required) | Follows an account; `{"result": [], "status": 1}`. |
| POST | `/api/v1/account/create` | user | `username` (the handle; empty takes the one derived from the user id) | Creates the reader's account — the one place an actor is made for a logged-in person; the page no longer creates one on its first load. The handle has to be theirs to take (`AccountService::assertHandleAvailable()`: the pattern, not another Nextcloud user's id, not a handle an actor holds); a refused handle is a **422** whose `error` says why. `{"result": {"account": <Account>}, "status": 1}`. |
| POST | `/api/v1/account/link` | user | `handle` (`user@server.example`, a leading `@` is fine) | Writes an account the reader already has elsewhere into the `fediverse` field of their Nextcloud profile, where Discover's colleague suggestions read it, and creates nothing here. An address on this server, or anything that is not `user@host`, is a **422** with the reason. `{"result": {"handle": "…"}, "status": 1}`. |
| POST | `/api/v1/account/delete` | user | `confirm` (required: the handle being deleted, with or without a leading `@`, either `name` or `name@host`, case-insensitive) | **Deletes the caller's own Aloha Social account**, and only theirs. The same deletion `occ social:account:delete` performs: the posts go, the follows go, and a `Delete` federates to every server that knew the account. The Nextcloud user is untouched — this is for somebody who wants their fediverse presence gone and their Nextcloud account kept, which until now meant asking an administrator. The typed handle is the whole of the guard and is deliberately **not** a password: an account signed in through SSO has none to give. A confirmation that does not name this account is a **422** whose message says what to type. The handle is held for the retention hour (`AccountService::TIME_RETENTION`) so nobody else can take it at once; a new account under a different handle can be created straight away, because `ActorsRequest::getFromUserId()` skips deleted rows. Every app signed in to the account is signed out with it, because `verify_credentials` creates an actor for a user who has none and a phone left running would otherwise re-make the account a minute later. **It cannot be undone.** Rate-limited to 3 an hour. The channels the account runs are deleted with it, each as an account of its own. |
| POST | `/api/v1/introduction/dismiss` | user, csrf | — | Records that the signed-in reader has completed or skipped the first-run introduction. |
| DELETE | `/api/v1/current/follow` | user | `account` (required) | Unfollows an account; `{"result": [], "status": 1}`. |
| GET | `/api/v1/social/moderation_lists` | user | — | The shared lists of accounts to mute or block that the viewer subscribes to, each `uri`, `name`, `kind` (`mute` or `block`) and `accounts`: how many accounts the list mutes or blocks here, not counting the ones the viewer had muted or blocked already. Today these are Bluesky's moderation lists, the one network that publishes them; a subscriber reads one list whichever network its members are on. |
| POST | `/api/v1/social/moderation_lists` | user, csrf | `url` (required: the list's bsky.app link, `https://bsky.app/profile/<handle or did>/lists/<rkey>`, or its `at://` URI), `kind` (`mute`, the default, or `block`) | Subscribes: everybody on the list (up to 1,000) is muted or blocked here at once, and again every six hours as the list changes (`Cron\ModerationLists`). A mute list is also muted at the AppView (`app.bsky.graph.muteActorList`), so a Bluesky app signed in here hides the same accounts. A block list is published as an `app.bsky.graph.listblock` record only when the viewer publishes their blocks, as a Bluesky block is public. Answers the subscription in the shape above. A list nobody here can read, an unknown `kind` or a 21st list is a **422**. |
| DELETE | `/api/v1/social/moderation_lists` | user, csrf | `uri` (required) | Ends a subscription and takes back only the mutes or blocks the list made: an account the viewer had muted or blocked themselves stays so. The AppView mute or the `listblock` record goes too. Answers the remaining lists. |

### Account info

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/account/{username}/info` | user, public | — | Local account with complete details, returned **unwrapped** as a `Person`; rebuilds the actor cache if it is missing. A name nobody holds is a 404 and is not logged. Rate-limited: 60 per minute anonymously, 300 per minute per user — a local read that a reader makes once per profile they open, rather than the remote route's ceiling below, but bounded: a name that is held here and a name that is not answer differently. |
| GET | `/api/v1/global/account/info` | user, public | `account` (required, e.g. `user` or `user@domain`) | Local or remote account, returned **unwrapped**. A leading `@` is stripped; remote accounts get follower/following/post counts fetched. **No actor is created here**, not even the viewer's own: reading a profile is not asking for an account, and an account made this way took the handle the setup screen was about to offer. An account is made where somebody asks for one — the setup screen (`POST /api/v1/account/create`) and `occ social:account:create`. Rate-limited: 10 per five minutes anonymously, 120 per minute per user, because a handle this instance has never seen costs a host-meta, a WebFinger and four signed actor fetches against a host the caller names. As a GET without a CSRF check it can be reached by a link on another site with the reader's session, so other servers are asked — an unknown account resolved, a remote account's counts fetched — only for a request that passes the CSRF check (the web app's, which sends its request token, on a public page too) or carries `Authorization: Bearer`; any other request is answered from what this server holds, and an account it does not hold is a 404. |
| GET | `/api/v1/global/actor/avatar` | user, public, no-csrf | `id` (required) | Streams the cached avatar with a 24 h cache header; 404 (envelope shape) when the actor has no icon. Rate-limited: 600 per minute anonymously, 3000 per minute per user — stored bytes served to anybody holding the address, at the ceiling `/media/{uuid}` carries, generous because a timeline draws dozens at once. |
| GET | `/avatar/{username}/{size}` | public, no-csrf | `username` (path), `size` (path, digits; at most 64 is the small picture, anything larger the large one, as Nextcloud's own route rounds it), `v` (the version, ignored but part of the address) | The avatar of a local account by its username: the icon of its actor and the `avatar` of its Account entity. Serves what Nextcloud's avatar route would serve this reader — a private avatar only to those who know its user — except that a visitor gets the generated initials where the avatar's scope keeps the picture off the actor. Cached for a day, privately and `immutable`, since the address carries the version. 404 for a name nobody here holds, a team account, a channel or a deleted account. Rate-limited like `/media/{uuid}`. |

The followers and following lists of an arbitrary account are reachable through the Mastodon-compatible `/api/v1/accounts/{account}/followers` and `/api/v1/accounts/{account}/following`.

### Banner

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| POST | `/api/v1/banner` | user, no-csrf | `file` (multipart, `$_FILES['file']`) | Stores the upload as the current user's header image, updates the actor cache and federates an Update. Returns `{"result": {"url", "id"}, "status": 1}`. A file that is not a readable image, is of a refused type, or is over the ceiling is a **400**: the file is the problem and the reader can pick another one. It used to be a 500, which told them the server had broken and logged a fault against it. |
| POST | `/api/v1/banner/url` | user, no-csrf | `url` (string, default `''`, required in practice) | Downloads the image at the given `url` with cURL (follows up to 5 redirects, 30 s timeout, user agent `Nextcloud-Social/0.10`) and stores it as the current user's header image. Same response shape. An empty `url`, or a non-2xx response, fails. |

### Migration

The Migration page's three buttons: take a copy of the account's Aloha Social data, put one back, and bring the follows over from another server. The exports, the imports and moving in are client-API routes, so a client app reaches them with its bearer token as well as the page with its session: the whole archive asks for the broad `read` — it is everything the account ever wrote, more than any one granular scope covers — a single CSV for the scope that reads that list, and everything that writes into the account for the broad `write`. Moving away and undoing it, the move-in callback, the aliases and the switch wizard's helpers stay session routes with CSRF: the move is behind Nextcloud's password confirmation, which a token cannot give.

Every error answer of these routes is `{"error": "…", "code": "<slug>"}`: the code is stable and the page explains it in the person's language, with what they can do next (`src/utils/serverError.js`); the English sentence is for logs and older clients, and the page keeps it behind *Details*. Anything that is not one of the refusals in [Migration error codes](#migration-error-codes) is logged and answered **500** `server-error` with the fixed sentence `Something went wrong on this server`, never with the exception's own message. A token the route does not accept is answered as on the Mastodon routes.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/migration/export` | public, no-csrf (viewer required, `read` scope) | — | The account's Aloha Social data as a zip: `social/actor.json`, `social/following_accounts.csv`, `social/followers.csv`, `social/blocked_accounts.csv`, `social/muted_accounts.csv`, `social/lists.csv`, `social/blocked_domains.csv`, `social/bookmarks.csv`, `social/likes.csv`, `social/outbox.json`, the Bluesky account under `social/bluesky/` where the account has one hosted here (see `GET /api/v1/social/bluesky/archive`), plus a `social/export.json` manifest naming the app version, the account and the migrator version. Written by the same `SocialMigrator` Nextcloud's whole-account export uses, so the two archives hold the same files at the same paths. The **private key is never in it** — see the class comment on `SocialMigrator` — so an archive cannot be used to sign as the account it came from. Downloads as `social-<uid>-<date>.zip`. Rate-limited to 6 an hour. |
| POST | `/api/v1/migration/import` | public, no-csrf (viewer required, `write` scope) | `file` (multipart, `$_FILES['file']`, ≤ 100 MB) | Reads such an archive back into the signed-in account: the profile, the follows, the blocks, the mutes, the lists (after the follows, through the same import as `/api/v1/migration/lists`), the blocked domains, the bookmarks and the favourites. **Additive** — nothing is deleted, and the posts in `outbox.json` are reported rather than re-published. An archive with no `social/actor.json` is a **400** `archive-not-social`, a file that is not a zip **400** `archive-unreadable`. Returns `{"imported": true, "log": [...]}`, the migrator's own account of what it did. Rate-limited to 6 an hour. |
| POST | `/api/v1/migration/follows` | public, no-csrf (viewer required, `write` scope) | `file` (multipart, `$_FILES['file']`) | **Queued** (see `/api/v1/migration/imports`): the upload is kept and the import runs in the background; answers **202** with `{"import": {...}}` as queued, **409** while one of this kind is still running, **413** over 100 MB. 30 an hour. A follows export — Mastodon's, GoToSocial's or Akkoma's `following_accounts.csv`, **Pixelfed's `pixelfed-following.json`** (a JSON array of actor URLs; Pixelfed offers no CSV), or the archive above — re-followed one account at a time through the ordinary follow path. A file that parses as JSON is read as JSON, anything else as CSV; a JSON entry may be a URL, a handle, or an object naming one under `url`/`acct`/`account`/`id`, and the array may sit under `following` or `orderedItems`. An actor URL is fetched and followed as the actor it resolves to. A follow is a relationship two servers have to agree on, so it cannot be carried in a file and is requested again from here. Returns `{"followed", "skipped", "failed"}`, where `failed` maps a handle to the reason. Rate-limited to 4 an hour. |
| POST | `/api/v1/migration/people` | user | `file` (multipart, `$_FILES['file']`) | The accounts an **Instagram** archive says you followed, as fediverse handles worth trying: `{"handles": ["name@threads.net", …]}`. Instagram exports no fediverse names because it has none, but Threads federates and a Threads handle is the Instagram one at `threads.net`. The archive is searched for the *shape* Instagram writes (`string_list_data[].value`) rather than for a path, because that path has changed between exports; a value that could not be a handle — a display name, a URL — is left out, repeats are collapsed, and at most 5,000 come back. Nothing is followed and nothing is stored. Rate-limited to 10 an hour. |
| POST | `/api/v1/migration/people/find` | user | `handles` (array) | Which of those accounts exist, **one batch at a time**: `{"checked": n, "found": [{"handle", "name", "url", "avatar"}]}`. Each name is a webfinger against another server, so at most `SwitchService::PROBE_BATCH` (25) are looked up per request. `checked` is how many were *looked at*, not how many were there — a client's cursor moves on that, because a batch where nobody is on Threads is the common case and a cursor that moved by the number found would ask about the same names for ever. Nothing is followed here either. Rate-limited to 120 an hour. |
| GET | `/api/v1/migration/announcement` | user | — | The handle and address to leave behind on the network being left: `{"handle": "@alice@cloud.example", "url", "text"}`. Built from the actor rather than from the Nextcloud user id, which is not the same thing for any account whose fediverse name differs from it. **403** `account-not-set-up` when the caller has no account here yet. |
| POST | `/api/v1/migration/posts` | public, no-csrf (viewer required, `write` scope) | `file` (multipart, `$_FILES['file']`), `fetch_media` (`1`) | **Queued** (see `/api/v1/migration/imports`): the upload is kept and the import runs in the background; answers **202** with `{"import": {...}}` as queued, **409** while one of this kind is still running, **413** over 100 MB. 30 an hour. **An account's own posts, brought over from the server it wrote them on** — the one thing a `Move` has never carried. Reads this app's own archive (`social/outbox.json` in the zip, with the files under `media_attachments/`), Mastodon's and GoToSocial's (`outbox.json` at the root, the layout ours copied), an `outbox.json` on its own, Pixelfed's `pixelfed-statuses.json`, **PeerTube's** (the one its own My account → Import/Export offers), or **Instagram's** "Download your information" archive — `content/posts_*.json` (both the current `your_instagram_activity/content/` layout and the older one) plus `reels.json`, `igtv_videos.json` and `other_content.json`, with the pictures out of the archive's own `media/` folder. An Instagram post has no id, no visibility and no hashtags as data: an id is derived from the file it carries and the moment it was posted (so a second run is still a no-op), the **importing account's own default visibility** is used, and the hashtags are read out of the caption. Its captions are mojibake by construction — the exporter escapes each UTF-8 byte as a character — and are converted back. `stories.json`, `archived_posts.json` and `recently_deleted_content.json` are deliberately not read. Instagram's **HTML** download is refused with the sentence that says to ask for JSON. A PeerTube export is read from `peertube/videos.json` rather than the `activity-pub/outbox.json` beside it: the ActivityPub half names each video's file by its address on the old server while the PeerTube half names the copy inside the archive, so one import needs the old server still running and the other does not — and the PeerTube half states the privacy as a number, and carries the title, tags, category and licence, which is most of what a video is. Private, internal and password-protected videos are skipped (each is one its author decided not to publish, and there is no audience here that means "the people who had the password"), so are lives, and so is any video whose file is not in the archive. An export taken **without** its video files is refused by name, because the JSON alone is a catalogue and the run would otherwise report "nothing imported" about a perfectly valid archive that is simply not the one to ask for. View, like and dislike counts are **not** carried over: they are numbers about the old instance's readers. Each post is written as a **new local post of the importing account**, dated when it was written, with its pictures — from inside the archive where it has them, and from the old server (which therefore has to still be up) where the export named only their addresses, unless `fetch_media` is `0`. **Nothing is federated**: not one delivery is queued, because re-publishing somebody's five years of posts would put five years of posts into every follower's timeline in one afternoon. Boosts and direct messages are skipped — the first is somebody else's post, the second is addressed to accounts on a server that is not this one. A reply keeps its parent where the export holds both. Answers `{"imported", "skipped", "already", "media", "failed", "total", "capped"}`; a repeat of the same file imports nothing, because `social_import_post` remembers what each post became. At most 2000 posts a run — `capped` says the run stopped there and another will carry on — and 2 runs an hour. A bigger archive than a browser will upload goes through `occ social:account:import-posts`. |
| POST | `/api/v1/migration/video` | public, no-csrf (viewer required, `write` scope) | `url` (required), `fetch_media` (`1`) | **One video, by its address** — the single-video half of the job above, which PeerTube also has and people use: an export is a heavy tool for one video, and somebody who has lost their account on the old server cannot take one at all while the video is still there to be fetched. The document is fetched, and has to be a `Video` that **names the address it was fetched from** among its own `url` links — the same evidence `resolveStatus()` requires, so a redirect cannot substitute one video for another. The playable file link is stored (the tallest one; an HLS playlist is passed over, since storing a list of segments on somebody else's server and calling it a video is not an import). The same three rules as the archive: nothing is federated, the id is ours with the original remembered so a second attempt is a **no-op**, and it is written as a new local post of the caller, keeping its title, running time, category and licence. Refuses a video **already on this server** (bringing a neighbour's post over as your own is not an import, and it is the one case the server can actually tell), and anything that is not a video. What it *cannot* check is whether the video is yours — neither can PeerTube's own importer, nor the archive import, which reads a file somebody uploaded; what stands in for it is the same thing: one deliberate act, rate-limited to **10 an hour**, producing an ordinary post that moderation and reporting reach like any other. Answers the same tally. A refusal is a **422** whose `code` says which one it was: `video-address-invalid`, `video-here-already`, `video-unreachable` or `video-unsupported`. |
| POST | `/api/v1/migration/blocks` | public, no-csrf (viewer required, `write` scope) | `file` (multipart, `$_FILES['file']`) | **Queued** (see `/api/v1/migration/imports`): the upload is kept and the import runs in the background; answers **202** with `{"import": {...}}` as queued, **409** while one of this kind is still running, **413** over 100 MB. 30 an hour. The accounts an export blocks — Mastodon's `blocked_accounts.csv`, a bare list of handles, and the same file the archive above holds. A block is this account's own decision rather than a relationship two servers agree on, so each one is applied here directly, severing the follows both ways and federating a `Block` exactly as blocking somebody from the web client does. Its own route rather than a `kind` on the follows one, so a client that got the kind wrong cannot follow the people it meant to block. An account that does not resolve is named in `failed` rather than dropped. Returns `{"blocked", "skipped", "failed"}`. Rate-limited to 4 an hour. |
| POST | `/api/v1/migration/mutes` | public, no-csrf (viewer required, `write` scope) | `file` (multipart, `$_FILES['file']`) | **Queued** (see `/api/v1/migration/imports`): the upload is kept and the import runs in the background; answers **202** with `{"import": {...}}` as queued, **409** while one of this kind is still running, **413** over 100 MB. 30 an hour. The accounts an export mutes — Mastodon's `muted_accounts.csv`, whose `Hide notifications` column is the one thing a mute stores besides its target and is honoured here. A mute federates nothing. Returns `{"muted", "skipped", "failed"}`. Rate-limited to 4 an hour. |
| POST | `/api/v1/migration/lists` | public, no-csrf (viewer required, `write` scope) | `file` (multipart, `$_FILES['file']`) | **Queued** (see `/api/v1/migration/imports`): the upload is kept and the import runs in the background; answers **202** with `{"import": {...}}` as queued, **409** while one of this kind is still running, **413** over 100 MB. 30 an hour. The lists an export names — Mastodon's `lists.csv`, one `list name,account address` per row, with no header (one is skipped where it is there). **Run it after the follows**: a list here holds accounts this one follows, as Mastodon's do, so an account not followed yet is counted in `skipped` rather than followed on the quiet by a route that says lists. A list whose title is already there is filled rather than duplicated, so a second run changes nothing; a list that follows a Nextcloud group is left alone, because its members are the group's. Returns `{"lists", "added", "skipped", "failed"}`, where `failed` maps `list/handle` to the reason. Rate-limited to 4 an hour. |
| POST | `/api/v1/migration/bookmarks` | public, no-csrf (viewer required, `write` scope) | `file` (multipart, `$_FILES['file']`) | **Queued** (see `/api/v1/migration/imports`), as the other uploads: **202** with `{"import": {...}}`, **409** while one of this kind runs, **413** over 100 MB, 30 an hour. The posts an export bookmarked — Mastodon's `bookmarks.csv`, one post address a line. Each address is fetched from the server it lives on (`SearchService::resolveStatus()`, as the importing account) and marked here if the account may read the post; a bookmark is a local flag and nothing is sent to anybody. Unlike the account-export restore, which only marks posts this server already holds, fetching is the point: a person's bookmarks are mostly other people's posts elsewhere. `report.failed` names the addresses that could not be fetched or that name a post the account may not read, with the reason; a line that is not an address counts as skipped. |
| POST | `/api/v1/migration/domain_blocks` | public, no-csrf (viewer required, `write` scope) | `file` (multipart, `$_FILES['file']`) | **Queued**, as above. The servers an export blocks — Mastodon's `blocked_domains.csv`, one domain a line, a `#domain` header tolerated. Each is blocked through `DomainBlockService::block()`, the same as `POST /api/v1/domain_blocks`; the instance itself cannot be blocked and is reported under `report.failed`. Federates nothing. |
| GET | `/api/v1/migration/export/{kind}` | public, no-csrf (viewer required, the scope of the list: `read:follows` for `following` and `followers`, `read:blocks` for `blocks` and `domain_blocks`, `read:mutes`, `read:lists`, `read:bookmarks`; any other `kind` `read`; or the broad `read`) | `kind`: `following`, `followers`, `blocks`, `mutes`, `lists`, `bookmarks` or `domain_blocks` | One of those lists as a single CSV, written the way Mastodon writes it — `following_accounts.csv`, `followers.csv`, `blocked_accounts.csv`, `muted_accounts.csv`, `lists.csv`, `bookmarks.csv` (post addresses, newest first) or `blocked_domains.csv` — so another server's importer reads it without being handed a whole archive. The same files the zip above holds, one at a time. An account this server never cached has no handle to write and is left out, and so is the account's own handle — every local actor holds a loopback follow of itself, and a `following_accounts.csv` naming you is a row Mastodon's importer tries to follow you with. A handle or list name that a spreadsheet would run as a formula (starting with `=`, `+`, `-`, `@`, a tab or a carriage return) is written with a leading `'`, and the importers here take it off again. At most 5000 rows a file. Any other `kind` is a **404** `list-unknown`. Rate-limited to 30 an hour. |

| POST | `/api/v1/migration/move-in/inspect` | public, no-csrf (viewer required, `write` scope) | `handle` (required: `@you@old.example`, or the actor id) | The old account, and what its server lets this one read off it: `{"account": {"id", "acct", "name", "url", "avatar", "following": {"total", "readable"}, "posts": {"total", "readable"}}}`. `readable` is false for a collection the server answers with a count and no page — Mastodon's "hide your social graph", Pixelfed always — which is when the file import is the way instead; the page says so before anything is started. **422** with the reason when the handle names nobody: `account-address-invalid`, `account-not-found`, or `account-not-verifiable` for a server that answers only servers it can verify and could not verify this one. 30 an hour. |
| POST | `/api/v1/migration/move-in` | public, no-csrf (viewer required, `write` scope) | `handle` (required), `follows` (`1`), `posts` (`1`), `fetch_media` (`1`) | **Moving here from the old account, from nothing but its handle.** Sets the alias at once (the half the old server asks for, and which federates nothing), then queues a `move_in` import that follows everyone the old account follows, from its public `following` collection, and writes its public and unlisted posts here as this account's own, from its public `outbox`, through the same `FollowService` and `PostImportService` paths the file imports use — so nothing is federated that those do not federate, and a post already brought over from an archive is not written twice. At most 5000 of each. Answers **202** `{"import": {...}}`; the import's `report` ends with `followed`/`skipped`/`failed`/`failures`, `imported`/`already`/`posts_skipped`/`posts_failed`/`media`, and `following_readable`/`posts_readable`. The followers themselves are the old server's `Move`, which the page points at once this has run. **409** `import-running` while a move is already running, **422** when the handle names nobody (as for inspect) or names this account (`alias-self`). 10 an hour. |
| POST | `/api/v1/migration/move-in/finish` | public, no-csrf (viewer required, `write` scope) | `handle` (the old account), `bluesky` (what becomes of the old account's Bluesky identity, passed on to the old server; `deactivate` by default) | **Finishing the move from here, when the old server is this app too.** Mastodon has no API for a move, so a person moving from Mastodon always ends in Mastodon's own form; between two Aloha Social servers the last step is done from the new side. This instance registers itself at the old one as an OAuth application asking for the one scope `write:migration` (`MoveFinishService::start()`), keeps the client credentials and a random `state` on the user (`move_finish`, 15 minutes), and answers `{"authorize_url"}` — the old instance's consent page, where the person logs in to their *old* Nextcloud and agrees. **422** `finish-not-possible` when the old server is not this app (`FediverseDirectoryService::softwareName()` of its host), `old-server-refused` when it will not register us, and the codes of inspect when the handle names nobody. 10 an hour. |
| GET | `/api/v1/migration/move-in/finish` | public, no-csrf (viewer required, `read` scope) | — | Where a finish started from here stands: `{"status": "none"\|"pending"\|"done"\|"failed", "acct", "at", "error"}`. A `pending` older than 15 minutes reads as `failed`. |
| GET | `/migration/move-in/callback` | user, no-csrf | `code`, `state` (or `error`) | Where the old server sends the person back. The code is exchanged at the old instance's `/oauth/token` with the kept credentials and the same redirect URI, and with the token the old instance's `POST /api/v1/migration/move/authorized` is called naming this account (`MoveFinishService::finish()`); the outcome is kept for the page. A wrong or missing `state`, an expired start or a refusal by the old server are recorded as `failed` with the reason. Always redirects to the Migration page, which reads the status. |
| POST | `/api/v1/migration/move/authorized` | public, no-csrf (token with **exactly** `write:migration`) | `target` (handle or actor id), `bluesky` (as for `POST /api/v1/migration/move`) | The same move as `POST /api/v1/migration/move` — `MigrationService::move()`, cooldown included — for a token the account's owner granted to their new instance by consenting there. The scope has to be spelled out on the token: the broad `write` every phone app holds is refused with **403**, as is a session without a token (the button, with its password step, is for sessions). `MigrationApiController`. **422** with the reason when the move is refused (cooldown, target does not name this account). |
| GET | `/api/v1/migration/move` | user | — | Where this account stands: `{"moved_to", "moved_at", "can_move_at"}` — the actor it moved to (`""` when it has not), when, and when it may move (again): `moved_at + 30 days`, Mastodon's cooldown, or `0` for an account that never moved. |
| POST | `/api/v1/migration/move` | user, **password confirmation** | `target` (required: `@you@new.example` or the actor id), `confirm` (required: this account's own handle, typed back), `bluesky` (`deactivate`, the default, `keep` or `move`) | **Moves this account away**: every follower's server is told to follow `target` instead and this account is marked as moved — what `occ social:account:move` does, now the person's own to do. Three things stand in front of it: Nextcloud's password confirmation, the handle typed back as `confirm` (case and the leading `@` do not matter; **422** naming the handle otherwise), and `target` already listing this account in its `alsoKnownAs`, which the service checks against a fresh fetch (**422** with what to do otherwise). A move within thirty days of the last is a **422** saying when the next may happen; the `occ` command may skip that, the button may not. Answers the status above plus `target: {acct, url}`. Afterwards the account may not post or follow from here (**403** on those routes), its profile and the sidebar say where it went, and `verify_credentials` carries `moved`. `bluesky` says what becomes of the account's Bluesky identity: `deactivate` announces it inactive on Bluesky (`IdentityService::deactivate()`; Settings can switch it on again), `keep` leaves it, `move` is only taken while or after its own move away runs (**422** `bluesky-move-first` before anything moves). Every **422** carries a `code`: `confirm-handle`, `move-cooldown`, `alias-missing`, `move-onto-self`, `bluesky-move-first`, `bluesky-choice-invalid`, or the codes of inspect for a target that names nobody; anything else is a **500** `server-error`. 5 an hour. |
| DELETE | `/api/v1/migration/move` | user, **password confirmation** | — | Takes the redirect off: clears `movedTo`, so the account may post and follow from here again and stops saying it moved. The followers do not come back — their servers acted on the Move when it arrived, and nothing in ActivityPub takes one back — and the cooldown stands, because the move did happen. Answers the status. |
| GET | `/api/v1/migration/imports` | public, no-csrf (viewer required, `read` scope) | — | The imports this account asked for, newest first, at most 20: `{"imports": [{"id", "kind" (`follows`, `blocks`, `mutes`, `lists`, `posts`, `move_in`, `bluesky_follows`), "status" (`queued`, `running`, `done`, `failed`), "total", "done", "skipped", "failed", "report", "options", "created_at", "updated_at"}]}`. While one is `running`, `done`/`total` move as it goes, written every ten items or two seconds; afterwards `done`, `skipped` and `failed` are the outcome and `report` carries the detail — the failed handles by name with the reason (`failed`, the first 50) for the account lists, `failures` for the follows and `post_failures` for the posts of a move-in (the first 20 each, post URL → reason; also `failures` on a posts import), the importer's tally for the posts, `error` for a run that failed. The page polls this while anything is active. Every import used to run inside the upload request, where a few hundred follows outlived the web server's timeout and the rate limit then kept the person from trying again for an hour. |
| DELETE | `/api/v1/migration/imports/{id}` | public, no-csrf (viewer required, `write` scope) | `id` | Takes a finished import off the list and answers the list as it now stands. One still queued or running is left — its job would write to a row that is gone — and answers **404** `import-not-found`, as does somebody else's. |

| GET | `/api/v1/migration/aliases` | user | — | The accounts this one also answers to — its `alsoKnownAs`. `{"aliases": [...]}`. |
| POST | `/api/v1/migration/aliases` | user | `alias` (required: a `@user@host` handle, resolved through WebFinger, or an actor id) | Adds one. **This federates nothing**: it is a statement this server makes about an account it owns, and it is what the *old* server demands before it will accept a `Move` pointing here — so it is the person's own to make rather than an administrator's. Idempotent. An address that is not an actor id (a hostname, a handle nobody answers to, this account's own id) is a **422** naming the reason, with the codes of inspect or `alias-self`. 30 an hour. |
| DELETE | `/api/v1/migration/aliases` | user | `alias` (required) | Stops answering to it. Idempotent, and answers with the list as it now stands. 30 an hour. |

#### Migration error codes

The codes of the routes above, beside the English sentence. A move away that asks for `bluesky: move` too early answers the codes of the ATProto move error codes (`bluesky-move-first`, `bluesky-choice-invalid`).

| Code | When | What the person can do |
|---|---|---|
| `not-signed-in` | A session route without a signed-in user (**401**) | Sign in again |
| `no-file` | An upload route without a file, or with an upload that did not arrive whole (**400**) | Pick the file again |
| `file-too-large` | The upload is over 100 MB (**413**); the sentence names the limit | Ask the administrator; `occ social:account:import-posts` takes a larger posts archive |
| `file-unreadable` | The uploaded file could not be read (**400**) | Pick the file again |
| `archive-unreadable` | The archive import was given something that is not a zip (**400**) | Pick the archive the export made |
| `archive-not-social` | The zip holds no `social/actor.json` (**400**) | Pick the archive the export made |
| `import-running` | An import of the kind, or a move here, is running already (**409**) | Wait for it on the imports list |
| `import-not-found` | Dismissing an import that is not a finished one of the caller's (**404**) | Reload the list |
| `list-unknown` | A CSV export of a `kind` that names no list (**404**) | — |
| `account-address-invalid` | What was typed is neither a `@user@host` handle nor an `https://` address | Check the address |
| `account-not-found` | No account answers to the handle or at the address | Check the address |
| `account-not-verifiable` | That server answers only servers it can verify (a 401 or 403 to the fetch), and could not verify this one | Ask the administrator to make this server reachable from the internet over https |
| `alias-self` | The alias names this account itself | Name the other account |
| `confirm-handle` | Moving away without this account's own handle typed back | Type it |
| `move-cooldown` | Moving away within 30 days of the last move; the sentence names the day | Wait until then |
| `move-onto-self` | Moving away onto this account itself | Name the new account |
| `alias-missing` | The new account does not list this one in its `alsoKnownAs` | Add the alias on the new account first |
| `finish-not-possible` | Finishing from here when the old server is not this app | Finish the move on the old server |
| `old-server-refused` | The old server would not register this one, or answered a step with an error | Try again later, or finish there |
| `video-address-invalid` | The video address is not `http(s)://` | Copy the video page's address |
| `video-here-already` | The video is on this server already | Nothing to bring over |
| `video-unreachable` | The video address could not be read | Check it, or try again later |
| `video-unsupported` | The address is not a video that can be brought over | — |
| `server-error` | Anything else; logged, and answered **500** with a fixed sentence | Try again; ask the administrator if it repeats |

#### Other refusal codes

Routes elsewhere whose refusal is advice — a limit, the field to change — carry a code too, beside the English `error` (or `message`) that API clients keep reading, and the numbers or names the advice needs as fields of their own. The web page says them in the person's language (`src/utils/serverError.js`). A route not listed here answers its refusals with the sentence alone.

| Code | Route | When | Beside it |
|---|---|---|---|
| `featured-tags-full` | `POST /api/v1/featured_tags` (**422**) | One past `max_featured_tags` | `limit` |
| `shorts-full` | `POST /api/v1/stories` (**422**) | The account has as many live 24-hour shorts as it may | `limit` |
| `handle-length` | `POST /api/v1/account/create` (**422**) | The handle is empty or longer than allowed | `max` |
| `handle-characters` | `POST /api/v1/account/create` (**422**) | The handle has characters other than letters, digits and `_`, with `.` and `-` inside | — |
| `handle-other-user` | `POST /api/v1/account/create` (**422**) | The handle is another Nextcloud user's id | — |
| `handle-in-use-here` | `POST /api/v1/account/create` (**422**) | An actor here holds the handle | — |
| `handle-held` | `POST /api/v1/account/create` (**422**) | The handle belonged to an account deleted within the retention time | — |
| `account-exists` | `POST /api/v1/account/create` (**422**) | The user has an account already | — |
| `email-domain-refused` | `POST /api/v1/account/create` (**422**) | The user's email address is at a domain this server makes no accounts for | — |
| `linked-handle-invalid` | `POST /api/v1/account/link` (**422**) | What was typed is not `user@server.example` | — |
| `linked-handle-local` | `POST /api/v1/account/link` (**422**) | The address is on this server | — |
| `no-file` | `POST /api/v1/banner` (**400**) | No file arrived | — |
| `upload-interrupted` | `POST /api/v1/banner` (**400**) | The upload did not finish | — |
| `banner-too-large` | `POST /api/v1/banner` (**400**) | The picture is over the smallest of `upload_max_filesize`, `post_max_size` and the instance's ceiling | `limit` (as people read it, e.g. `10 MB`) |
| `push-auth-required` | `POST /api/v1/push/subscription` (**422**) | The subscription store was called without an account or app token | — |
| `push-endpoint-unreachable` | `POST /api/v1/push/subscription` (**422**) | The push distributor URL is not a reachable public HTTPS endpoint | — |
| `push-keys-invalid` | `POST /api/v1/push/subscription` (**422**) | The Web Push subscription keys are absent or invalid | — |
| `push-policy-invalid` | `POST`, `PUT /api/v1/push/subscription` (**422**) | The notification policy is not supported | — |
| `push-alerts-invalid` | `POST`, `PUT /api/v1/push/subscription` (**422**) | A push alert preference has an invalid value | — |
| `push-standard-invalid` | `POST /api/v1/push/subscription` (**422**) | The standard-format flag is not a boolean value | — |
| `push-subscriptions-full` | `POST /api/v1/push/subscription` (**422**) | The account already has the maximum number of subscriptions | `limit` |
| `push-subscription-invalid` | `POST /api/v1/push/subscription` (**422**) | `subscription` is not an object | — |
| `push-data-invalid` | `POST`, `PUT /api/v1/push/subscription` (**422**) | `data` is not an object | — |
| `banner-unusable` | `POST /api/v1/banner` (**400**) | Not a picture, or one of a type refused | — |
| `setting-not-email` | `POST /admin/server` (**422**) | The field is not an email address | `field` |
| `setting-too-long` | `POST /admin/server` (**422**) | The field is longer than allowed | `field`, `max` |
| `setting-not-local-account` | `POST /admin/server` (**422**) | The field does not name a local account | `field` |
| `setting-out-of-range` | `POST /admin/server` (**422**), `POST /admin/interests` (**400**) | The number is outside its range | `field`, `min`, `max` |
| `setting-zero-or-range` | `POST /admin/server` (**422**) | The number is neither 0 nor in its range | `field`, `min`, `max` |
| `setting-heights` | `POST /admin/server` (**422**) | The list of heights has none in range | `field`, `min`, `max` |
| `setting-not-choice` | `POST /admin/server` (**422**) | The value is not one of the choices | `field`, `choices` |
| `group-unknown` | `POST /admin/sections` (**400**) | A group id names no group | `group` |
| `groups-too-many` | `POST /admin/sections` (**400**) | More groups than may become lists | `max` |
| `account-not-found` | `POST`/`DELETE /moderation/verifications` (**404**) | No account goes by the name | — |
| `account-not-set-up` | Every client route that acts for an account, reached with a Nextcloud session or app password (**403**, see [Authentication](#authentication)): the client-API bases, the web app's own routes (the Bluesky settings, feeds and recovery routes, held posts, shared moderation lists, moving away and its announcement included), and `POST /oauth/authorize` | The signed-in Nextcloud user has not set up their account here yet | `setup_url` |

`field` is the parameter's name as the server spells it (`contact_email`, `halfLife`); the page puts its own label for the field in its place.

### Channels

The `Group` actor a video is published under. PeerTube resolves a video's channel by looking for a `Group` in its `attributedTo` and refuses the video with *"Cannot find associated video channel"* when there is none — so before these existed, every `Video` this app published was thrown away on arrival, silently and in PeerTube's log rather than ours. One is made for an account the first time it posts a video (`PostService::createPost()`), named after the account, so nobody has to learn the word; these routes are for the person who wants a second one or a better name on the first. Client-API routes: the list asks a token for `read:accounts`, and making or changing one for `write:accounts` — a channel is an actor on this instance like the profile is, an address other servers will follow and cache, so a token that may not edit the profile may not mint one either. A public or unlisted video is delivered to the followers of its channel as well as the author's, and so are its edits and its deletion: a PeerTube follows the channel, never the person, and was sent nothing until this was done. A followers-only post never reaches a channel's followers, who have not followed the author.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/channels` | public, no-csrf (viewer required, `read:accounts` or `read` scope) | — | Every channel this account has, oldest first: `{"channels": [{"id", "actor_id", "handle", "name", "description", "default"}]}`. |
| POST | `/api/v1/channels` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | `handle` (required), `name`, `description` | Makes one, with a `Group` actor of its own — its own key pair, inbox, outbox and followers, followable and moderatable like any other actor. The handle is an address on this instance and cannot be changed afterwards, which is why it is asked for separately from the name; one that is taken or is not a handle is a **422** naming the reason. At most 20 channels an account. 5 an hour. |
| PUT | `/api/v1/channels/{id}` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | `id`, `name`, `description` | Renames one, or changes what it says it is about — on the row and on the actor document both. Somebody else's channel is a **422**, the same answer an id that does not exist gets. 30 an hour. |

The dangerous direction is deliberately not here. `Move` tells every server that knows you to follow somebody else instead, cannot be taken back, and stays `occ social:account:move`.

### Posts held for review

The other end of the review queue: what of the **caller's own** is waiting, and a way to take one back. Session routes with CSRF — unpublished text of the caller's own is not something a third-party token should be able to read, and there is no account parameter here, so there is nothing to point at anybody else. What a caller may reach is scoped in SQL on the way out, not checked after the row has been read.

A held post is **not** in `social_stream`. What is stored is the request, so a post waiting for a moderator appears in no timeline, no profile, no outbox and no search — not even its author's — and there is no read path that could be written without the filter that would leak one. Approving it replays the request through the ordinary posting path.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/review` | user | — | The caller's own held posts, newest first: `{"held": [{"id", "account_id", "reason", "text", "spoiler_text", "visibility", "media_count", "created_at"}], "reasons": [...]}`, where `reasons` is the same list in a sentence a person reads. |
| DELETE | `/api/v1/review/{id}` | user | — | Takes one back. An author changing their mind about a post nobody has seen is not a moderation decision and leaves no record. Somebody else's, and one that does not exist, are the same **404**. |

What happens at the moment of posting is on `POST /api/v1/statuses`: a held post answers **422** with `held_for_review: true`, the rule under `reason`, and the held post itself — the vocabulary Mastodon's API has for "this did not become a status", with enough beside it for a client to say something better than "failed". The request has been kept, so writing it again only finds the first one: the queue is unique on (account, text).

### Statistics

The Statistics page, and the memories beside it. Client-API routes, so a client app reaches them with its bearer token as well as the page with its session. The reads ask for `read:statuses`: the figures and the memories are the caller's own posts, all of them, and the account block beside the figures (handle, follower and following counts) is what every status entity carries about its author anyway. Switching the recap asks for `write:accounts`. There is no account parameter — they only ever answer about the caller.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/v1/statistics` | public, no-csrf (viewer required, `read:statuses` or `read` scope) | `days` (0, 30, 90, 365), `fresh` (false) | Everything the Statistics page shows, counted from this instance's rows at the moment it is asked for: nothing is stored and no cron precomputes it. See the shape below. `days` is the window — `0` is as far back as the cap allows — and the answer says which one it used and which are on offer. The result is **cached per account and window for fifteen minutes**; `fresh=true` counts again, and `window.cached` says which was served. Rate-limited to 90 an hour, which the cache makes affordable: before it, every reload was a walk of up to 2,000 posts plus a follower-count lookup for everybody who boosted any of them. One block is the exception and says so: **`network`** — `{servers, accounts, active, posts, peers, measured, source, source_url}` — is how big the fediverse is according to FediDB, which counts servers by crawling their NodeInfo, quoted with the date it was measured because it is somebody's survey rather than something this instance can check. `peers` beside it *is* counted here: the servers this one federates with, the same number as `stats.domain_count` on `/api/v1/instance`, remembered for five minutes like it. The block is **null** when the `network_stats` app value is `0` or the survey did not answer, and the page then leaves the section out rather than drawing zeros. |
| GET | `/api/v1/statistics/export` | public, no-csrf (viewer required, `read:statuses` or `read` scope) | `days` (0, 30, 90, 365), `format` (`csv`, `json`) | The same figures as a file to keep: `social-statistics-<date>.csv` or `.json`. The CSV is flattened to `section,name,value` — the totals, the rates, the per-month series (posts, engagement and what the account did), the conversation partners in both directions, the top languages, domains and hashtags, the servers of the followers and of the engagement, the starter-pack joins and the networks the posts also went out on — because a CSV of a nested structure is a worse JSON file. A text cell that a spreadsheet would run as a formula — one starting with `=`, `+`, `-`, `@`, a tab or a carriage return, as an account name or a server name another server chose can — is written with a leading `'`, so it opens as text; numbers are written as they are. Nothing here is stored by the server, so the only copy of a month's numbers is the one somebody takes. Rate-limited to 30 an hour. |
| GET | `/api/v1/memories/on_this_day` | public, no-csrf (viewer required, `read:statuses` or `read` scope) | — | The caller's own top-level posts from this calendar day in each of the last five years, newest first, at most six. Status entities in the local format, with their link previews and places attached, as a timeline page carries them. It answers with the caller's followers-only and direct posts as well as their public ones, which is what `read:statuses` grants on the caller's own timelines. **There is no account parameter and there must never be one** — the query behind it does not filter by audience, because it is only ever asked about the caller. Each year is looked up as that calendar day in the reader's own timezone rather than as "about a year ago", so the 4th of March finds the 4th of March; a post written at 23:50 belongs to the day it was written on. A leap day is found in leap years only, rather than sliding to the 1st of March. Replies are left out: a reply read outside its thread is a fragment. |
| GET | `/api/v1/memories/recap` | public, no-csrf (viewer required, `read:statuses` or `read` scope) | — | How the caller's week went: `enabled`, `this_week` and `last_week`. **Off until the reader switches it on**, and then it answers `enabled: false` with no counts at all rather than counts the client is expected to hide. The two counts are read off the same twelve-week chart `/api/v1/accounts/{account}/highlights` draws, so one place decides what a week is and the recap cannot disagree with the reader's own profile. There is no streak field and there should not be one: a run of consecutive weeks is a thing that can be lost, and telling somebody they have broken one is asking them for posts. |
| POST | `/api/v1/memories/recap` | public, no-csrf (viewer required, `write:accounts` or `write` scope) | `enabled` (required, bool) | Turns the weekly recap on or off for the caller and answers `{enabled}`. |

The answer:

| Key | What it holds |
|-----|---------------|
| `account` | `acct`, `display_name`, `created_at`, `followers`, `following` |
| `posts` | `total`, `originals`, `replies`, `boosts`, `with_media`, `sensitive` |
| `engagement` | `likes`, `boosts`, `replies`, `quotes` and a `*_per_post` for each. A quote counts as engagement like the other three, in every total, rate and score below |
| `rates` | `total` engagement and `per_post`; `applause`, `amplification` and `conversation` (likes, boosts and replies per post, under the names an agency reports them under); `per_follower`, engagement per post against the follower count as a percentage; `median` and `best`, because a mean is one viral post away from meaningless; `silent` and `silent_share`, the posts that got no answer at all |
| `visibility` | how many posts went to each audience |
| `by_month`, `engagement_by_month` | twelve months of posts, and of what they collected |
| `by_hour` | twenty-four hours of posts |
| `by_weekday` | seven days, each with `posts`, `engagement` and the `average` — the average is the useful one, since posting twice as often on a Monday collects twice as much on a Monday without Monday being better |
| `best_hour` | `{hour, average, posts}`, or `hour: null` where no hour holds three posts yet: one lucky post is not a time of day that works |
| `content` | one row per kind of post (`with_media`/`text_only`, `with_hashtag`/`no_hashtag`, `original`/`reply`, `visibility_*`), each with `posts`, `engagement` and `average`. A kind with no posts is absent rather than reported as zero |
| `hashtags`, `hashtag_performance` | the tags used most, and separately the tags whose posts average best — the second only counts tags used twice or more |
| `audience` | `by_month` followers gained, `instances` the servers they are on, `local_share` the percentage on this server, `counted` and `capped`, and `starter_pack_joins`: how many accounts followed after joining through one of the account's starter packs in the window. A follower's server is the host of its id, except where its network knows better: a Bluesky account is on its PDS, with Bluesky's own `*.bsky.network` hosts as one `bsky.social`, and so is an account whose PDS is unknown or not a valid hostname |
| `engagement_sources` | where the likes, boosts and replies came from: `servers`, at most six with `host` and `count`, by the server of whoever made them as `audience` names it; `local_share`, the percentage made from this server; `counted`. The account's replies to itself are left out |
| `best` | the three most-answered posts, each with an `excerpt`, its counts and its `score` |
| `periods` | the last `days` (30) beside the 30 before them: `current` and `previous`, each with `from`, `until`, `posts`, `reach`, `interactions`, `likes`, `boosts`, `replies` and a `series` of 30 daily buckets for reach, interactions, likes and boosts; plus `change`, the percentage each moved by, or `null` where the earlier window held nothing — everything is infinitely more than nothing |
| `timeline` | every post of the current window, newest first and at most 100, each with `id`, `url`, `published_at`, `excerpt`, `likes`, `boosts`, `replies`, `quotes`, `score`, `media`, `visibility` and `reach` |
| `reach` | `followers`, and `known_boosters`/`unknown_boosters`: how many of the accounts that boosted a post in the window this server knows the audience of, and how many it does not; plus `instances`, the number of servers the window's posts were actually addressed to, which is measured rather than modelled `networks` lists the other networks the window's posts also went out on, which no instance path records, each with `network` and how many `posts`: a post published to Bluesky is a record in its author's repository, read from there rather than delivered |
| `activity` | `originals`, `replies` and `boosts`, twelve months each: what the account *did*, beside the twelve months of what came back. A quiet month in `by_month` can mean either, and until this block there was no way to tell which |
| `consistency` | `active_days`, `span_days`, `share`, `streak` and `longest_gap`: the days posted on out of the days counted, the longest run and the longest silence |
| `media` | `images`, `described` and `described_share`: how many pictures were posted and how many of them carry alt text |
| `languages`, `domains` | the languages posted in, and the hosts linked to, each with a count |
| `partners` | `inbound` (who replies to this account) and `outbound` (who it replies to), at most ten each with `account`, `replies` and `followed`; plus `not_followed_share`, the percentage of the people who replied that the account does not follow. Counted from the replies rather than from the follow graph, which are rarely the same list |
| `window` | `days` and the `choices` on offer, `cached`, `counted`, `capped`, `max`, `first_at`, `last_at`, `followers_counted` |

`reach` is an estimate and the page says so: an account's own followers today plus the followers of everybody who boosted the post, as the boosters' own instances last reported them. Two audiences that overlap are counted twice, a booster this server knows nothing about counts as nobody (and is counted in `unknown_boosters` instead), a direct message has no follower audience at all, and nobody anywhere can count the people who read a post without touching it. A post is counted on the day it was published together with everything it has collected since — there is no record of *when* a like arrived, only that it did. Both windows are the same length and anchored to the start of today, so opening the page twice in an afternoon draws the same two lines.

Every engagement figure is a post's `details` — the local count plus whatever the origin reported — so all of them are a floor rather than a total, which is true of every Fediverse statistic. There are no impressions to divide by, so `per_follower` is against the follower count and says so on the page. A boost the account made is counted under `posts.boosts` and excluded from everything else, because its likes belong to whoever wrote it. The post walk stops at 2000 and the follower read at 5000, newest first, and `window` and `audience` each say whether they stopped early.

### Pixelfed's administration routes

Pixelfed's app shows its administration screens to anybody the server calls an administrator, and they call Pixelfed's own `/api/admin/*` routes — not Mastodon's `/api/v1/admin/*`. They stand behind the **same gate** (`AdminApiControllerBase`: a Nextcloud administrator, or a group the Aloha Social section has been delegated to under *Administration privileges*, with a session and CSRF token or a bearer token carrying `admin:read`/`admin:write`) and are answered by the **same service**, so who may moderate and what a moderation does are decided in one place: a takedown from the Pixelfed app is the same takedown as one from the Mastodon API or the settings page. What has no equivalent here is answered as absent — an empty list, or a **422** that says why — never as a 200 that changed nothing. Every failure is worded as in the Mastodon admin API: **401** without credentials, **403** for a non-administrator (the same answer whether the user exists or not), **404** for an unknown thing, **422** for what this instance does not have.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/api/admin/stats` | public, no-csrf (**admin required**, `admin:read` scope) | — | The four numbers on the app's admin home: `users_count`, `posts_count` and `instances_count` are this instance's own counts (the ones `/api/v2/instance` carries), `autospam_count` is `0` because there is no autospam queue here, and `cached_at` is now. |
| GET | `/api/admin/config` | public, no-csrf (**admin required**, `admin:read` scope) | — | Pixelfed's five instance switches (`federation.activitypub.enabled`, `pixelfed.open_registration`, `instance.stories.enabled`, `pixelfed.enforce_email_verification`, `pixelfed.bouncer.enabled`), each with the state that is actually true of this instance, so the screen describes this server rather than a Pixelfed one. |
| POST | `/api/admin/config/update` | public, no-csrf (**admin required**, `admin:write` scope) | `key`, `value` | Always a **422** naming where the setting lives: every one of these is configured in Administration settings → Aloha Social or belongs to the Nextcloud server, and a 200 that flipped nothing would leave the administrator believing it had. |
| GET | `/api/admin/users/list` | public, no-csrf (**admin required**, `admin:read` scope) | `q` (a username prefix), `sort` (`asc`/`desc` by creation, `desc` when absent) | The local accounts as the app's user browser lists them, fifty at most, each `id`, `username`, `email` (always `''` — the address is the Nextcloud account's, which this app does not read out to a client), `created_at`, `is_admin` (whether the user may administer *this* instance) and `status` (`disabled` for a suspended account, `null` otherwise). |
| GET | `/api/admin/users/get` | public, no-csrf (**admin required**, `admin:read` scope) | `user_id` (required; a client id or a username) | One account: the row above under `data`, and under `meta` the Account entity, `report_count` (reports filed against it), and the three per-account flags Pixelfed has and this instance does not (`unlisted`, `cw`, `no_autolink`), all `false`. `dms_sent` and `remote_report_count` are `0`: nobody here counts direct messages sent, and a remote report is a report like any other. |
| POST | `/api/admin/users/action` | public, no-csrf (**admin required**, `admin:write` scope) | `id` (required), `action` (required), `value` | `delete` — the app's word for removing an account — **suspends** it, which takes its posts down here and sends the same `Delete` to every peer that the account's own deletion would. `unlisted` is this instance's **silence** tier and `cw` marks everything the account posts sensitive: both are words for things this instance does have, and were refused until 0.20.6 with a 422 that was true of the words and not of the instance. `no_autolink` is a state an account does not have here, and `verify_email` and `refresh_stats` are the server's: each a **422** that says so. |
| GET | `/api/admin/mod-reports/list` | public, no-csrf (**admin required**, `admin:read` scope) | — | The open reports as the app's queue draws them: `id`, `type` (`post` when the report carries one, `user` otherwise), `message` (the reporter's comment, with the reason in front of it when it came from the app's own report route), `object_id`, `object_type` (`App\\Status` or `App\\Profile`, Pixelfed's class names), `created_at`, `reported_by_account`, `reported_account`, `status` (the first reported post) and `parent` (`null`). |
| POST | `/api/admin/mod-reports/handle` | public, no-csrf (**admin required**, `admin:write` scope) | `id` (required), `action` (required) | `ignore` resolves the report, in the signed-in moderator's name, and answers `{"success": true}`. `cw` and `unlist` would apply a per-post flag this instance does not have and are a **422**: a post here is taken down or left. |
| GET | `/api/admin/autospam/list` | public, no-csrf (**admin required**, `admin:read` scope) | — | This instance's **review queue**, fifty at most: the posts held because their author had published nothing here yet, or because one of the spam rules tripped. Each carries `id`, `status_id` (the same id — a held post has no status), `account_id`, `username`, `content`, `is_nsfw`, `scope`, `created_at`, and the rule that held it as both `reason` and `reason_text`. Pixelfed's screen shows a score here; a rule is what a moderator can act on and a score is not. |
| POST | `/api/admin/autospam/handle` | public, no-csrf (**admin required**, `admin:write` scope) | `id` (required), `action` (required) | `approve` (Pixelfed's "not spam", also `not_spam`) publishes the post as its author; `delete` (also `spam`) refuses it, which tells the author and is recorded against them as a strike. Anything else is a **422**. `{"success": true}`. |
| GET | `/api/admin/instances/list` | public, no-csrf (**admin required**, `admin:read` scope) | `q` (a domain fragment), `sort` (`asc`/`desc`), `sort_by` (`id`, `user_count`, `status_count`, `domain`), `filter` (`all`, `unlisted`, `banned`, `auto_cw`) | The remote instances this one has heard of — every host a cached account is on — fifty at most, each with what this instance has decided about it in Pixelfed's words: `unlisted` is this app's **silence**, `banned` a **deny-list** entry, `auto_cw` a flag this instance does not have and always `false`. `user_count` is how many of the host's accounts are cached here; `status_count` is `0`, because nothing here counts posts per host and a guess would be worse than a zero the docs explain. `id` is the same derived id the domain-block routes use, so an instance and its block name the same thing. |
| GET | `/api/admin/instances/get` | public, no-csrf (**admin required**, `admin:read` scope) | `id` (required; the derived id or the domain) | One instance, as above; unknown is a **404**. |
| POST | `/api/admin/instances/moderate` | public, no-csrf (**admin required**, `admin:write` scope) | `id` (required), `key` (`unlisted`, `banned`, `auto_cw`), `value` (a boolean) | Writes the list the Pixelfed word names: `unlisted` silences or unsilences the domain, `banned` puts it on the deny list or takes it off. On an instance that federates by an **allow list**, `banned` is a **422** — the same reason the domain-block routes refuse there — and `auto_cw` is a **422** everywhere. Answers with the instance as it now stands. |

### Config and system

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| POST | `/api/v1/config/cloudAddress` | admin | `cloudAddress` (required) | Sets the app's cloud base URL. Returns a bare `[]`. |
| GET | `/local/` | public, no-csrf | — | `{"result": {"version": "<installed_version>", "setup": <bool>}, "status": 1}`. |
| GET | `/test/{account}/` | public, no-csrf | `account` (path) | WebFinger self-test. Only active when the `social.tests` system value is set — otherwise it returns exactly the same payload as `/local/`. On failure it returns the error envelope with HTTP **200** and a `result` key holding the test data. |

### Moderation (moderators only)

Backing routes of the Aloha Social section in the administration settings. All of them require a session **and** a CSRF token (they are deliberately not part of the bearer-token client API), and every one of them carries `#[AuthorizedAdminSetting(settings: AdminSettings::class)]`: a Nextcloud administrator passes, and so does a group the administrator has handed the Aloha Social section to under *Administration privileges*. That is the same gate core puts on the page itself, so whoever can open it can use the buttons on it.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/moderation/reports` | moderator, csrf | `resolved` (false), `page` (1) | One page of 50 reports, newest first — the open ones, or with `resolved=true` the ones already dealt with. `{"reports": [{"id", "account_id", "account", "reporter", "local", "category", "comment", "status_ids", "creation", "resolved", "level"}], "total", "page", "perPage"}`. `level` is what stands against the reported account *now* (`silence`, `suspend` or `""`), so a report from last month says whether the account it named is still suspended. The page renders the first page of the open reports itself; this is what its "Show more" button and the folded-away resolved section read. A `page` past the end answers with no reports and the same `total`. |
| POST | `/moderation/reports/{id}/resolve` | moderator, csrf | `resolved` (true) | Marks the report resolved (or reopens it with `resolved=false`). Returns the report entity; 404 for an unknown id. |
| GET | `/moderation/review` | moderator, csrf | `page` (1) | One page of 50 held posts, **oldest first** — the order the queue should be drained in. `{"held": [{"id", "account_id", "reason", "text", "spoiler_text", "visibility", "media_count", "created_at"}], "total", "page", "perPage", "reviewFirstPost", "autospam"}`. The text is in the row because that is what there is to decide about: a held post is in no timeline, no profile and no outbox, so there is nowhere else to go and read it. |
| POST | `/moderation/review/{id}/approve` | moderator, csrf | — | Publishes it, as its author, down the path an immediate post takes — dated **now**, because that is when it became a post. `{"approved": "<id>"}`; an id that is not waiting is a 404. |
| POST | `/moderation/review/{id}/reject` | moderator, csrf | `comment` | Refuses it. The request is deleted, the author is told through the same notification a takedown uses, and a `delete_statuses` strike is recorded against the account so the next moderator can see this was not the first time. Nothing else about the account changes — a refused post is not a silence. `{"rejected": "<id>"}`. |
| POST | `/moderation/review/settings` | moderator, csrf | `reviewFirstPost` (required), `autospam` (required) | Turns first-post review and the spam rules on and off (`review_first_post`, `autospam`; both `1` by default). Both are sent together because the section draws them together. Answers with both as they now stand. |
| POST | `/moderation/accounts/sensitive` | moderator, csrf | `actorId` (required), `sensitive` (true) | Marks **everything this account posts** sensitive, or stops. The step between doing nothing and silencing: an account can be asked to put a content warning on its pictures without being taken out of the timelines. Applied where a post is written (`StreamRequest::save()`), so it covers a local post, one that arrived in the inbox and one the importer restored alike — and it applies from the **next** post: rewriting somebody's old posts is a different and much larger decision. Pixelfed's app calls this `cw`. |
| GET | `/moderation/media/blocks` | moderator, csrf | `maxId` | The pictures this instance refuses, by sha256 of the file as it arrived, a page of 100 at a time, newest first: `{"blocks": [{"id", "hash", "reason", "moderator", "blocked", "creation"}], "next", "total"}`, where `blocked` is how many times that file has since been turned away. Pages are cut on the row `id`: `next` is the `maxId` that asks for the page after this one, `null` on the last, and `total` is how many files are refused in all. |
| POST | `/moderation/media/blocks` | moderator, csrf | `hash` (required, sha256 hex), `reason` | Adds one. Every other tool here acts on an account, and none of them stops a **file** coming back: the account is suspended, the picture is posted again by the next one, and a moderator is deleting the same image for the third time. Checked in `CacheDocumentService::saveFromTempToCache()`, which is the one place both an upload and a fetched remote attachment pass through. Hashed as the file arrived, before the metadata is stripped: it answers "this exact file, again", and does not claim to answer "a picture that looks like this one". Anything that is not a sha256 is a **422**. |
| DELETE | `/moderation/media/blocks` | moderator, csrf | `hash` (required) | Removes one, whichever page it is on. It and `POST` both answer with the first page, in the shape `GET` does. |
| GET | `/moderation/trends` | moderator, csrf | — | What is being kept out of Explore, and what is currently trending to choose from: `{"tags", "links", "statuses", "trending"}`, each decision carrying who made it and when. |
| POST | `/moderation/trends` | moderator, csrf | `kind` (`tag`, `link` or `status`), `ref` (the hashtag, URL or post id) | Keeps one thing out of every trending list and out of Explore. The counters keep counting it, so lifting the decision puts it back with the number it would have had. A kind this app does not review is a **422**. |
| DELETE | `/moderation/trends` | moderator, csrf | `kind`, `ref` | Lets it back in. |
| GET | `/moderation/emojis` | moderator, csrf | — | The instance's own custom emoji, which could only be managed with `occ social:emoji` until now. |
| POST | `/moderation/emojis` | moderator, csrf | `shortcode`, `category`, and a `picture` upload | Adds one. The upload is handed to the same service the command calls, so the checks on the shortcode, the size and the format live in one place rather than two that could drift. Anything it refuses is a **422** with the reason. |
| DELETE | `/moderation/emojis` | moderator, csrf | `shortcode` | Removes one. An unknown shortcode is a **404**. |
| GET | `/moderation/rules` | moderator, csrf | — | The rules this instance asks people to follow, as the one-per-line text they are stored as. |
| POST | `/moderation/rules` | moderator, csrf | `rules` | Writes them. Stored as typed, trimmed of surrounding blank lines: the reader splits on newlines and drops the empties anyway, and storing what somebody typed is easier to explain than storing a normalised version of it. They are what `/api/v1/instance/rules` serves and what every client shows on sign-up; before this they could only be set with `occ config:app:set social rules`. |
| GET | `/moderation/discover/categories` | moderator, csrf | — | The subjects named so far, the same list the public route hands out: `{"categories": [{"id", "name", "hashtags"}]}`. |
| POST | `/moderation/discover/categories` | moderator, csrf | `name` (required, at most 64 characters), `hashtags` | Names one. `hashtags` is written the way somebody pastes it — separated by spaces or commas, with or without the `#` — because that is what an administrator will type; at most 12 are kept and a tag that is not a word is dropped. A subject with no name, one with no hashtags (it would link to nothing), and the twenty-fifth subject are each a **422** with the reason. Returns the whole list, so the caller never has to ask again. |
| DELETE | `/moderation/discover/categories` | moderator, csrf | `id` (required) | Removes one. Returns the whole list. |
| POST | `/moderation/fediverse/add` | moderator, csrf | `address` (required) | Adds an instance to the Fediverse access list (the list `occ social:fediverse` manages). Invalid addresses are a 422. Returns `{"list": [...]}`. |
| POST | `/moderation/fediverse/remove` | moderator, csrf | `address` (required) | Removes an instance from the access list. Returns `{"list": [...]}`. |
| POST | `/moderation/fediverse/access` | moderator, csrf | `type` (required) | Switches the access mode: `all_but` (blocklist) or `none_but` (allowlist). Anything else is a 422. Returns `{"accessType": "..."}`. |
| POST | `/moderation/fediverse/blocklist/preview` | moderator, csrf | `csv` (required) | Reads an uploaded block list and says what applying it would do, changing nothing: `{"blocked", "silenced", "alreadyBlocked", "alreadySilenced", "entries": [{"domain", "severity"}], "rejected": [...], "skipped"}`. A Mastodon-style CSV — a `#domain` column, optionally `#severity` — or one domain a line. `severity` is `suspend` (block) or `silence`; a row with no severity is a block. `rejected` names rows that describe no instance the list may hold: a single label (`com`, which would cover every server under it), a name with no dot, or this instance itself. Over 8 MB or more than 10,000 instances is a 422. |
| POST | `/moderation/fediverse/blocklist/import` | moderator, csrf | `csv` (required) | Applies the same list. Fail-closed: any rejected row is a **422** naming them and nothing is applied, because this is a file the administrator chose. Returns the counts plus `{"list": [...]}`. Importing into an allow list is a 422. |
| GET | `/moderation/fediverse/blocklist/sources` | moderator, csrf | — | The published lists this instance can follow, as `{"sources": [{"id", "label", "url", "format", "enabled", "lastRun", "lastResult"}]}`. Two are offered — `mastodon.social` and `thebad.space` — and both are off until an administrator turns one on. Mastodon answers `/api/v1/instance/domain_blocks` only where its administrators turned publishing on, so a source can be re-pointed at another server that does. |
| POST | `/moderation/fediverse/blocklist/sources` | moderator, csrf | `id` (required), `enabled` (required), `url` | Follows a published list, or stops. `url` points the source somewhere else and must be HTTPS at a named host — not an IP address, and not a name with no dot — because the server fetches it on a timer. Returns every source. |
| POST | `/moderation/fediverse/blocklist/fetch` | moderator, csrf | `id` (required), `dryRun` (false) | Reads one source now instead of waiting for the daily job. `dryRun` fetches and reports without applying, which is what a page shows before a source is turned on; its result is not recorded as what that source last did. A server that does not publish a list answers `{"error": "that server did not hand over a list"}` rather than failing. Returns `{"result", "sources", "list"}`. |
| GET | `/moderation/accounts` | moderator, csrf | `query`, `origin` (`local`, `remote`, or empty for both), `status` (`active`, `silenced`, `suspended`), `maxId` (0) | A page of up to 40 accounts for the browser on the settings page, as `{"accounts": [{"actor_id", "handle", "username", "domain", "local", "level", "strikes"}], "cursors": [nid, …]}`. `strikes` is how many decisions have ever been taken about the account, counted for the whole page in one query. `query` is tried as all three of the things a moderator types: `bob@instance.example` (and `@bob@instance.example`) is an account on an instance, `instance.example` is the instance, and a bare `bob` is a username anywhere. Pass the last cursor back as `maxId` for the next page. An `origin` that is neither `local` nor `remote` means both, and a `status` outside the three above is passed on to the same reader the Mastodon admin API uses — so `pending` and `disabled` answer with no accounts, as they do there. |
| GET | `/moderation/accounts/history` | moderator, csrf | `actorId` (required) | What has been decided about one account before now, newest first, as `{"strikes": [{"action", "text", "moderator", "report_id", "creation"}]}` — up to 50. `action` is `none` for a warning, otherwise `silence` or `suspend`. `moderator` is the Nextcloud user who took it, or `""` for one taken by a command or a job. A missing `actorId` is a **400**. |
| POST | `/moderation/accounts` | moderator, csrf | `actorId` (required), `level` (`silence`, `suspend`, or empty to lift), `comment` | The instance's own decision about an account, as opposed to one user's block. **Silence** keeps the account reachable for the people who follow it and takes it out of the public and global timelines; it changes no data and is undone by lifting. **Suspend** deletes what the account has posted here, drops its cached actor and refuses everything it sends afterwards — lifting stops the refusal but does not bring back what was deleted. Returns the decision, or `{"actor_id": …, "level": ""}` when lifted. |
| GET | `/moderation/verifications` | moderator, csrf | — | The accounts this instance verified, newest first, and the verifying account: `{"verifier": {"actor_id", "account", "name", "did"} or null, "publishing", "verifications": [{"actor_id", "account", "name", "did", "local", "verified_by", "created_at"}]}`. `publishing` is whether verifications are published (Bluesky on, and a verifying account with a DID); `did` is `''` for an account verified here only; `verified_by` is the moderator's user id. |
| POST | `/moderation/verifications` | moderator, csrf | `account` (required: a handle, a numeric account id or an actor id) | Verifies the account, fetching it first when it is not known here yet; one already verified stays as it was. With a verifying account and Bluesky on, an account with a DID is also published as an `app.bsky.graph.verification` record. Answers `{"actor_id", "verification"}`, the entity's new `verification`. An account nobody can find is a **404**. |
| DELETE | `/moderation/verifications` | moderator, csrf | `account` (required, as above) | Takes the verification back, and its published record. Answers `{"actor_id", "verification": null}`; an account that is not verified is a **404**. |
| POST | `/moderation/statuses/remove` | moderator, csrf | `streamId` (required) | Deletes one post, whoever wrote it. Returns `{"stream_id": …}`. Reached from the **Take down** button beside each post a report names — the lightest thing a moderator can do about a report, and until that button existed, the one thing the panel could not do. |
| GET | `/admin/announcements` | moderator, csrf | — | Every announcement, newest first, as the administration page shows one: `id`, `text` (as typed, not HTML), `starts_at`, `ends_at`, `all_day`, `published_at` and `active` — whether it is being served at this moment. One that has not started and one that has run out are both listed, because those are the ones an admin has to act on. |
| POST | `/admin/announcements` | moderator, csrf | `text` (required), `starts_at`, `ends_at`, `all_day` (false) | Posts an announcement and answers with the whole list. Blank text, text past 10000 characters, a date the server cannot read, one bound without the other (Mastodon's own rule) and an end not after its start are each a **422**. `all_day` rounds the window out to whole days and is ignored without a window. There is no edit route: an announcement people have already read is replaced by a new one, not changed under them. |
| DELETE | `/admin/announcements/{id}` | moderator, csrf | — | Removes the announcement and every dismissal of it, for everybody, read or not, and answers with what is left. An unknown id is a **404**. |
| POST | `/admin/server` | **administrator**, csrf | `contactEmail`, `contactAccount` (empty), `extendedDescription`, `maxSize` (10), `maxVideoSize` (2048), `inboxThrottle` (300), `secureMode` (false), `publishBlocks` (false), `allowSelfSigned` (false) | The Server card of the settings page: the instance-wide settings that had no interface at all and could only be set with `occ config:app:set social`. Writes all of them or none, and answers with what stands afterwards — the same shape the page is rendered from. `contactAccount` accepts a local Aloha Social username (with or without a leading `@`) or an empty string; it resolves and stores the owning Nextcloud user id. Remote actors, missing accounts, and local team actors without a Nextcloud user are rejected with HTTP **422**. A refusal names the field: `contactEmail` must be an address (or empty) and at most 255 characters, `extendedDescription` at most 10000, `maxSize` 1–10240 MB, `maxVideoSize` 1–102400 MB, `inboxThrottle` 0–100000 requests per instance per minute (0 disables it). Unlike every other route in this table this one is **not** delegated: it carries no `AuthorizedAdminSetting`, so a group the Aloha Social section was handed to is refused. What it holds is a decision about the server rather than about a report. Since 0.20.6 it also takes `imageMaxEdge` (0, or 480–16384 pixels — the longest edge a **stored** picture may have; `0` keeps every upload exactly as it arrived, which is the default and the only value that loses nothing) and `imageQuality` (40–100), consulted only when the first is set. |
| GET | `/admin/notification-policy` | **administrator**, csrf | — | What the notification policy of an account **created from now on** starts as: the five keys of `/api/v1/notifications/policy`, each `accept` or `filter`. Until an administrator chooses it is the calm policy (`for_not_following`, `for_new_accounts`, `for_private_mentions`, `for_limited_accounts` `filter`; `for_not_followers` `accept`). Stored as the app value `notification_policy_defaults` (JSON). Not delegated, like `/admin/server`. |
| POST | `/admin/notification-policy` | **administrator**, csrf | any of the five keys | Changes it and answers all five. A key with any value but `accept` or `filter` refuses the whole change with **422** `{"error": "…"}` and nothing is written: an administrator decides whether something waits for review, never that it is discarded for somebody who has not chosen that. **Existing accounts are never touched**; each keeps the policy it has. |
| POST | `/admin/sections` | **administrator**, csrf | `stories` (true), `photos` (true), `videos` (true), `groupLists` (`[]`) | The Features section of the administration page: what this instance offers the people using it. The three switches decide whether stories (the web client's 24-hour shorts) are taken at all and whether the Photos and Videos timelines appear in the sidebar; all three are **on** by default, and turning one off hides the section without touching a single post. `groupLists` is the Nextcloud groups whose members each get a list for the group — **empty by default**, because a group list tells everybody in the group who else is in it. Writes all of it or none, and answers with what stands afterwards. A refusal is a **400** naming what it would not take: a group id that names no group, or more than 100 groups. Not delegated, for the same reason `/admin/server` is not: it is a decision about the instance rather than about a report. |
| POST | `/admin/interests` | **administrator**, csrf | `enabled` (true), `learningDefault` (true), `halfLife` (30), `threshold` (3), `cap` (30), `window` (7) | The For you card. `enabled` switches the whole feature — off, nothing is learned and every route of it is a 404, and what was learned is kept for when it is switched back on. `learningDefault` is whether a reader who never touched their own switch learns: on out of the box, and the one to turn off where learning from reading must be opted into. `halfLife` (7–180 days) is how long a learned score takes to halve, `threshold` (0.5–20) the score a learned tag needs to be listed, `cap` (5–100) how many interests are listed, and `window` (1–30 days) how far back the feed looks. Writes all of it or none; a value out of range is a **400** naming it. |
| GET | `/admin/relays` | **administrator**, csrf | — | **The relays this instance subscribes to**, newest first: `{"id", "actor_id", "host", "inbox", "status", "error", "created_at", "last_update"}`. `status` is `pending` (the `Follow` has gone out), `accepted` (posts flow both ways) or `rejected` (the relay said no, or could not be reached — `error` says which). |
| POST | `/admin/relays` | **administrator**, csrf | `address` (the relay actor, e.g. `https://relay.example/actor`) | Subscribes. The actor is fetched first, because its inbox is what the subscription needs and there is no way to guess one; an address that answers with no actor, or with an actor that publishes no inbox, is a **422** saying so. A `Follow{object: as:Public}` — what Mastodon sends and what relay software reads as "subscribe me" — is then signed by the **instance actor** and delivered inline, because the delivery queue resolves its signing key from `social_actor` and the instance actor is deliberately not a row there. Answers with the row, which will say `pending`: the relay answers in its own time. Subscribing twice is the same row. |
| POST | `/admin/verifications/verifier` | **administrator**, csrf | `account` (a local username, or empty for none) | Chooses the local account the instance verifies in the name of: its name is the `by` of every verification, and, with Bluesky on, it is given a Bluesky identity when it has none and the verification records are published from its repository — every existing one moved there off the request. Answers `{"verifier", "publishing"}` as above; an account that is not local, or not found, is a **422**. |
| GET | `/admin/bluesky` | **administrator**, csrf | — | The Bluesky card: the settings (`enabled`, `relays`, `plc_directory`, `appview`, `jetstream`, `chat`, `sync_ceiling`), the numbers (identities, repositories, events in the replay window, the head sequence number, the daemon's last report, the rotation key's age) and the requirement checks, run fresh. |
| POST | `/admin/bluesky` | **administrator**, csrf | any of `enabled`, `relays` (a list of origins), `plc_directory`, `appview`, `jetstream`, `chat` (Bluesky's chat service, an https origin, or empty to turn direct messages off), `sync_ceiling` | Saves what is sent. Switching on needs every requirement check to pass — https, `*.<host>` in `trusted_domains`, the root rules, the handle host, the daemon, the firehose proxy — and answers **422** with the card and an `error` otherwise; switching off always works. |
| GET | `/admin/bluesky/figures` | **administrator**, csrf | — | The *Bluesky figures* section, counted from this server's own tables and app values with no request elsewhere, and cached for a minute. While Bluesky is switched off it answers only `{"enabled": false}`. Otherwise `enabled`, `computed` (when it was counted), `accounts` (`identities`, the local accounts with a Bluesky identity, and `off`, those whose owners switched their presence there off), `posts` (`day`, `week`: post records written to the local repositories in the last 24 hours and 7 days, not counting the records a moved-in repository brought), `repositories` (`count`, `records`, `blob_bytes`, summed from the repository heads), `reader` (`watched`, the Bluesky accounts read; `jetstream`, whether an endpoint is set; `jetstream_lag`, seconds between now and the stored Jetstream cursor, `null` without one) and `firehose` (`running`; `subscribers` as the daemon last reported them, `null` while it is not running; `head_seq` and `head_time` of the newest event; `events_kept`, the events in the replay window). |
| POST | `/admin/bluesky/crawl` | **administrator**, csrf | — | Sends `com.atproto.sync.requestCrawl` to every configured relay now; answers `results`, relay → `ok` or the reason. |
| GET | `/admin/bluesky/blocks` | **administrator**, csrf | — | The Bluesky block list: `blocks`, each `kind` (`did` or `host`), `value`, `reason`, `creation` |
| POST | `/admin/bluesky/blocks` | **administrator**, csrf | `target` (a DID or a PDS host), `reason` | Blocks it and purges the accounts of it that are followed here (their posts, the follows, the watch); answers the list and how many were `purged`. 422 for a target that is neither a DID nor a host |
| DELETE | `/admin/bluesky/blocks` | **administrator**, csrf | `target` | Takes it off the list; answers the list |
| GET | `/api/v1/social/bluesky/identity` | user | — | The viewer's own Bluesky identity — `handle`, `did`, `url` (the bsky.app profile), `state`, `active` (false while the viewer has switched their presence on Bluesky off), whether a `recovery_key` was issued — made now when there is none yet, and the profile record written while it is on. **404** when Bluesky is off. On this and the other `bluesky/*` account routes, a key of this server that the instance secret no longer opens is **503** `{"error": "This server's keys need to be re-sealed by an administrator (occ social:atproto:keys:reseal)", "code": "keys-sealed"}`. |
| POST | `/api/v1/social/bluesky/recovery` | user, csrf, password confirmation | — | Issues a recovery phrase: twelve words that are the private half of a key listed second, after the instance's, on the account's DID. Answers `phrase`, `key` — the same key as other atproto tools take it: `multibase` (`z…`, what `goat plc sign --plc-signing-key` reads), `hex`, and the public `did_key` — and the identity. Shown once and never stored; a second call issues a new key and the old words stop working. |
| GET | `/bluesky-recovery` | public, no-csrf | — | The offline recovery tool: one HTML page, its script inline (allowed by its CSP hash; `connect-src https:`), its strings in the viewer's language and the BIP-39 word list. It moves a DID to another server with the person's recovery key — see Moving.md "If this server goes away". **503** `tool-missing` when the app's JavaScript is not built |
| GET | `/bluesky-recovery/download` | public, no-csrf | — | The same page as a file to keep, `bluesky-recovery-tool.html` |
| GET | `/api/v1/social/bluesky/control` | user | — | Who controls the viewer's DID, read from the PLC directory's audit log (kept a minute, and asked again at once after this server confirmed an operation): `rotation_keys` (highest first, each `{key, role}`, `role` one of `server`, `server-retired`, `recovery`, `unknown`), `state` (`active`, `tombstoned`), `last_operation` (`cid`, `created_at`, `signed_by`), and `undo` — `{until, by}` while a key ranking above the one that signed the latest operation can still nullify it (72 hours), else `null`. Times are unix seconds. **404** `no-identity` or `did-not-found`, **503** `directory-unreachable` |
| GET | `/api/v1/social/bluesky/archive` | user, no-csrf (a download the browser navigates to), password confirmation, 3 per hour per user | — | The viewer's Bluesky account as a zip, sent while it is written — the files stored, not compressed, with no `Content-Length` — so the first bytes go out at once and nothing of it is kept on disk: `bluesky/repo.car` (the repository, as `getRepo` streams it), `bluesky/blobs/<cid>` (every blob that still reads; the ones that do not are named in the README), `bluesky/plc-log.json` (the PLC directory's audit log, or the operations this server confirmed when the directory cannot be asked), `bluesky/did.json`, `bluesky/recovery/recovery-key.py` with the BIP-39 word list it reads, `bluesky/recovery/bluesky-recovery-tool.html` (the recovery tool, where the JavaScript is built), and `bluesky/README.txt` (what each file is, and the goat steps to move the account with the recovery phrase). Downloads as `bluesky-<handle>-<date>.zip`. **404** `no-identity` when the account has none hosted here (none, moved away or deleted). A failure once the download has begun cannot change its status: the zip then ends without its central directory, which unzip tools report as damaged, and the log has the details. |
| POST | `/api/v1/social/bluesky/publish-blocks` | user, csrf | `publish` (bool) | Whether the viewer's blocks of Bluesky accounts go to Bluesky as `app.bsky.graph.block` records, where a block is public and keeps the blocked account from replying, quoting or mentioning them there. On, the ones they hold are published now and each one after; off, every published one is withdrawn. Answers `publish_blocks`; `GET …/identity` carries it too. Off unless the viewer turns it on. **404** without a Bluesky identity |
| POST | `/api/v1/social/bluesky/state` | user, csrf | `active` (bool) | Switches the viewer's own presence on Bluesky off or on ("Be on Bluesky", spec §4.6). Off, the account is deactivated there: announced inactive on the firehose and by `getRepoStatus`, its repository no longer served, nothing more published for it, every Bluesky app signed out and refused, its Bluesky notifications and direct messages no longer read. The DID, the handle and the repository stay, so switching back on is the same account as it was; what was written while off is not published afterwards. Answers the identity as `GET …/identity` does, `active` included, with `publish_blocks`; 404 when there is no identity here to switch. |
| POST | `/api/v1/social/bluesky/handle` | user, csrf, password confirmation | `handle` | Makes a domain the viewer owns their Bluesky handle, once `_atproto.<domain>` (TXT `did=<DID>`) or `https://<domain>/.well-known/atproto-did` names their DID: the DID document is updated and the firehose tells the network. **422** with a sentence and a `code` (the ATProto identity error codes) when the domain does not name the DID yet (`handle-not-verified`), is not a domain name (`handle-domain-invalid`), is under this server's handle host (`handle-reserved`), or is another account's (`handle-in-use`), or the account is switched off (`identity-inactive`). Answers the identity, now with `assigned_handle`, `custom_handle` and `custom_handle_broken` (the daily check no longer finds the record) |
| DELETE | `/api/v1/social/bluesky/handle` | user, csrf | — | The handle this server assigned, again; answers the identity |
| GET | `/api/v1/social/bluesky/move` | user | — | The viewer's latest move of their Bluesky account, or `null`: `direction` (`away`, `in`, `inbound`), `pds`, `handle` (there), `step` (`repo`, `blobs`, `prefs`, `identity`, `activate`, `follows`, `code`, `invited`, `posts`, `done`), `state` (`running`, `waiting`, `needs_decision`, `failed`, `cancelled`, `done`), `progress` (`progress.missing`, the pictures and videos that did not arrive, and `progress.missing_records`, the first 20 records that lose them, each `collection`, `rkey`, `created_at`, `text` (a post's first 120 characters) and `url` (the post here, else its address on Bluesky; '' for the profile); for a move away `progress.stage`: `account_created`, `repo_copied`, `identity_switched`, `activated`, `done`; and `progress.code` once it stopped), `error`. `posts_on_bluesky`: how many of the viewer's posts are on Bluesky now under the identity a move here would retire. An inbound move whose invitation or session ran out is ended on the way. Beside `move`, who controls the account once it moved away: `has_recovery_key`, `rotation_keys` (the handover's rotation keys by role, never the keys: `["recovery", "new_server"]`, or `["new_server"]` without a recovery key — this server keeps none) and `new_host` (the other server's host once a move away is done, else `null`) |
| POST | `/api/v1/social/bluesky/move` | user, csrf, password confirmation, 3 per hour per user | `pds`, `handle`, `email`, `password`, `inviteCode`, `without_recovery`, `announce` | Moves the viewer's Bluesky account to another PDS. `announce` (`post`, `profile` or `none`, the default) says where the account went once the move is done: one public post, or a profile field "Also at" with the new address (`progress.announced`, and `progress.announce_code` when it could not be written); **422** `announce-invalid` for anything else. Without a recovery key the request has to say `without_recovery: true` (only the other server controls the account afterwards), else **422** `recovery-key-missing`: the account is made there now, with a token the account signs (each call waited for up to twenty seconds), and the rest follows in the background. **422** with the other server's reason when it refuses, or when another move is under way. Every error carries a `code` beside the sentence (the ATProto identity error codes), and a stopped move keeps it as `progress.code` |
| DELETE | `/api/v1/social/bluesky/move` | user, csrf, password confirmation | — | Calls off a move away before the DID moved (`state` `cancelled`). The account made on the other server stays there, deactivated — deleting it takes a code that server e-mails — so the answer says so: `{"move", "code": "target-account-left", "host"}`. **422** `move-past-switch` once the DID points at the other server ("Try again" finishes the move from where it stopped; a move that failed handing the DID over is asked of the directory first), `move-switching` while it is being pointed there, `plc-unreachable` while the directory cannot be asked whether it took the handover, `no-move-to-call-off` |
| POST | `/api/v1/social/bluesky/move/continue` | user, csrf | `without_missing` | Goes on with a move away that stopped before the DID moved for the viewer to decide (`state` `needs_decision`, `progress.code` `blobs-missing` with `progress.missing`, or `repo-incomplete`): with `without_missing: true` the DID moves now without what is missing, else the blobs (or the repository) are copied again and checked again. **422** `no-decision-pending` |
| POST | `/api/v1/social/bluesky/follow-from` | user, csrf, 5 per hour per user | `account` (a Bluesky handle or DID) | Follows from here everyone a Bluesky account follows, while that account stays where it is: the account and its server are looked up now (the DID, then the PDS from the PLC directory, asked through the outbound guard), and a `bluesky_follows` import reads its public follow records (`com.atproto.repo.listRecords`, no password, at most 5000 accounts and 100 pages) and follows each from the viewer's account through the ordinary follow path; one already followed is skipped. Answers **202** `{"import", "account": {"did", "pds", "handle"}}`; `GET /api/v1/migration/imports` is where it gets to (`report.failed`: DID → reason). Only a move brings followers. **422** with a `code`: `handle-invalid`, `handle-not-found`, `did-not-supported` (not a `did:plc`), `did-not-found`, `plc-unreachable`, `pds-address-invalid`, `import-in-progress`; **404** `bluesky-off` |
| GET | `/api/v1/social/bluesky/move/target` | user, 30 per hour per user | `pds` | What a PDS the viewer may move to says of itself (`describeServer`, asked through the outbound guard that refuses local addresses): `{"pds", "did", "availableUserDomains", "inviteCodeRequired"}`, so the form can offer the handle domains before anything starts. **422** with a `code` when it cannot be asked (`pds-unreachable`, also for an address this server does not send requests to, `pds-unknown`, …), **404** `no-identity` |
| POST | `/api/v1/social/bluesky/move/retry` | user, csrf | — | Starts a failed move again from the step it stopped at — a move here whose code was refused asks for a new one; a move away that failed handing the DID over goes on from the activation when the directory points the DID at the other server already; **422** when there is none (`no-failed-move`), `plc-unreachable` while the directory cannot be asked whether it took the handover |
| GET | `/api/v1/social/bluesky/bridgy-twin` | user | `search` (`1` to ask Bluesky's search) | `{"twin": {"handle", "did"}}` when Bridgy Fed bridges the viewer's Fediverse account to Bluesky — the handle Bridgy gives it (`alice.social.example.com.ap.brid.gy`) resolves, through the AppView or its DNS record, to a DID whose PDS is Bridgy's; with `search`, Bluesky's search is given the viewer's Fediverse address and a result taken only when its DID document names the viewer's actor — else `{"twin": null}`. `handle` is the twin's handle now |
| POST | `/api/v1/social/bluesky/move-invite` | user, csrf, password confirmation, 5 per hour per user | `account` (handle or DID) | Invites a Bluesky account to move here driven by the other side (`state` `waiting`, `step` `invited`, good for a day). For a Bridgy Fed twin the viewer's account sends Bridgy's bot the `migrate-to` command as a direct message; for anything else the answer carries what a migration tool needs: `{"move", "bridgy", "pds", "handle", "email", "code"}` — the one-time code, shown only now, is both the password and the invite code. **422** when the account is here already, another move is under way, or Bridgy could not be sent the message |
| DELETE | `/api/v1/social/bluesky/move-invite` | user, csrf, password confirmation | — | Calls off an inbound move that has not finished: what arrived of the repository and its blobs is dropped and its session ends. **422** when there is none |
| POST | `/api/v1/social/bluesky/move-in` | user, csrf, password confirmation, 5 per hour per user | `handle` (or DID), `password` (the Bluesky account's own, not an app password, and not kept), `authFactorToken` | Moves a Bluesky account here: this server signs in to its PDS (at most 20 sign-ins to one PDS host per 10 minutes for the whole instance, **422** `rate-limited` past that), and the copy of the repository, blobs and preferences follows in the background, until the old PDS e-mails a code (`state` `waiting`, `step` `code`; `progress.code_sent_to` is the address it went to, '' when the old PDS does not say). The viewer's Bluesky account here so far is retired once the move is done; the follows come over after the DID. **422** when the sign-in is refused, the account is here already, or another move is under way |
| DELETE | `/api/v1/social/bluesky/move-in` | user, csrf, password confirmation | — | Calls off the viewer's move here while the DID has not switched: it ends in `state` `cancelled`, the session on the old PDS is ended and dropped, and the copied repository and blobs are deleted. **422** `move-past-switch` once the PLC operation may have been sent, `no-move-to-call-off` when there is none |
| POST | `/api/v1/social/bluesky/move-in/code` | user, csrf, 3 per hour per user | — | Asks the old PDS again to e-mail the code a waiting move needs. Answers the move and `sent_to`, the address the code went to, '' when the old PDS does not say. **422** `no-move-waiting` when no move waits for a code |
| POST | `/api/v1/social/bluesky/move-in/continue` | user, csrf | `without_missing` (bool, false) | The viewer's decision on a move here that stopped in state `needs_decision` because pictures or videos did not arrive (`progress.missing`: `count`, `cids`): `true` goes on without them, `false` copies them again first (from the old PDS, for a move driven by a tool too). Answers the move. **422** `no-decision-pending` when no move waits for one |
| POST | `/api/v1/social/bluesky/move-in/republish` | user, csrf | — | Once a move here is done, publishes the posts it took off Bluesky (the local public posts written while the retired identity was the account's, `progress.republish`) again, into the moved repository, in the background. Answers the move. **422** `nothing-to-republish`, `republish-queued` |
| POST | `/api/v1/social/bluesky/move/code` | user, csrf | `code` | The code the old PDS e-mailed: it signs the operation that points the DID here, the account takes the DID and is switched off there. **422** when no move waits for one |
| GET | `/api/v1/social/bluesky/labelers` | user | — | The viewer's Bluesky labelers: Bluesky's own moderation service first (`removable` false), then the ones subscribed to, each with `did`, `name` and `labels` — every label value it declares with its `name`, `description` and the viewer's `setting` (`ignore`, `warn` or `hide`; the labeler's default until changed) |
| POST | `/api/v1/social/bluesky/labelers` | user, csrf | `labeler` (a handle or a DID) | Subscribes the viewer; 422 when it is not a Bluesky labeler. Answers the list |
| DELETE | `/api/v1/social/bluesky/labelers` | user, csrf | `did` | Unsubscribes the viewer; Bluesky's own cannot be removed. Answers the list |
| PUT | `/api/v1/social/bluesky/labelers/setting` | user, csrf | `did`, `label`, `setting` | What one label of a subscribed labeler does: `ignore`, `warn` (the post carries a filter result naming the label) or `hide` (the post is left out). Answers the list |
| GET | `/api/v1/social/bluesky/app-passwords` | user | — | The viewer's app passwords for Bluesky apps: `app_passwords`, each `id`, `name`, `creation`, `last_used` — never the password |
| POST | `/api/v1/social/bluesky/app-passwords` | user, csrf, password confirmation | `name`, `privileged` (false) | Makes one: `id`, `name`, `privileged` and the `password` (four groups of four, as Bluesky's), the only time it is shown, with the list (each with `privileged`). A privileged one lets the app reach the account's Bluesky direct messages, as Bluesky's privileged app passwords do. **422** with a sentence and a `code` for an empty or overlong name (`app-password-name-invalid`), a taken one (`app-password-name-taken`), or past 25 (`app-password-limit`) |
| DELETE | `/api/v1/social/bluesky/app-passwords/{id}` | user, csrf | — | Revokes it, and every Bluesky app signed in with it; answers the list |
| GET | `/api/v1/social/bluesky/oauth-sessions` | user | — | The Bluesky apps the viewer signed in to with Bluesky sign-in (OAuth): `sessions`, each `id`, `client_id` (the app's metadata address, the one thing about it that is checked), `client` (its host), `scopes`, `created`, `last_used` |
| DELETE | `/api/v1/social/bluesky/oauth-sessions/{id}` | user, csrf | — | Signs that app out: its tokens stop working at once; answers the list |
| GET | `/api/v1/social/bluesky/feeds` | user | — | The Bluesky custom feeds and lists the viewer keeps — their Bluesky preference `savedFeedsPrefV2`, the one a Bluesky app signed in here keeps too — pinned first: `feeds`, each `uri` (`at://`), `type` (`feed` or `list`), `name`, `description`, `avatar`, `creator` (a handle), `pinned`. One the AppView no longer knows is left out. **404** when Bluesky is off; **422** when the viewer has no Bluesky identity; **502** when the AppView does not answer |
| POST | `/api/v1/social/bluesky/feeds` | user, csrf | `feed` (an `at://` URI, or a bsky.app address of a feed or a list) | Keeps it, pinned; answers `feed`. **422** when it is not a feed or list the AppView knows |
| DELETE | `/api/v1/social/bluesky/feeds` | user, csrf | `uri` | Stops keeping it; answers `{}` |
| GET | `/api/v1/social/bluesky/feeds/suggested` | user | — | The feeds Bluesky suggests to the viewer (`getSuggestedFeeds`), as `feeds` in the same shape; empty when the AppView does not answer |
| GET | `/api/v1/social/bluesky/starter-pack` | user | `pack` (a bsky.app starter-pack address, or its `at://` URI) | The starter pack, read from the AppView as the viewer where they are on Bluesky: `pack` with `uri`, `url`, `name`, `description`, `joined` (how many joined with it), `creator` (`did`, `handle`, `name`, `avatar`), `members` (at most 150, each `did`, `handle`, `name`, `avatar`, `description`, `following` — whether the viewer follows them on Bluesky) and `feeds` (as `GET …/feeds` describes one). **422** for an address that is not a starter pack's, or one Bluesky does not know |
| POST | `/api/v1/social/bluesky/starter-pack/follow` | user, csrf | `pack`, `dids` (at most 25), `feeds` (bool, false) | Follows the members named — only ones in the pack — as any Bluesky account is followed, and with `feeds` keeps the pack's feeds. Answers `followed` and `failed`, each a list of DIDs. **422** for more than 25 at once |
| GET | `/api/v1/social/bluesky/trends` | user | — | The topics trending on Bluesky (`app.bsky.unspecced.getTrendingTopics`), kept ten minutes: `trends`, each `topic`, `label`, and either `feed` (the `at://` URI of the custom feed it opens) or `search` (the text to search for). Empty where the AppView has no trends |
| GET | `/api/v1/social/bluesky/suggestions` | user | — | The accounts Bluesky suggests to the viewer (`app.bsky.actor.getSuggestions`, as the viewer where they are on Bluesky), without ones they follow: `accounts`, each `id` (the DID), `acct` and `username` (the handle, which follows them here), `display_name`, `avatar`, `note` (the bio, escaped) and `url` |
| GET | `/api/v1/timelines/bluesky` | user | `feed` (required, the `at://` URI of a feed or a list), `limit` (20, at most 100), `max_id` | A page of the feed or list as statuses, read from the AppView as the viewer (`getFeed`, `getListFeed`), in the feed's own order. The next page is asked with `max_id` the id of the last status of this one; an empty answer is the end. **422** for a URI that is neither |
| GET | `/.well-known/oauth-protected-resource` | public, no-csrf | — | The protected resource metadata of this PDS (AT Protocol OAuth): `resource` and `authorization_servers`, both this instance's origin. 404 while Bluesky is off. Served at the root through the web-server rules |
| POST | `/oauth/par` | public, no-csrf, rate-limited | `client_id`, `response_type=code`, `code_challenge` (S256), `state`, `redirect_uri`, `scope` (with `atproto`), `login_hint`, `response_mode`, and for a confidential client `client_assertion_type`/`client_assertion`; a `DPoP` proof | A Bluesky app's pushed authorization request: **201** `{request_uri, expires_in}`. The client metadata is fetched from the `client_id` and checked; a proof without this server's current nonce is answered **400** `use_dpop_nonce` with a `DPoP-Nonce` header, as every answer carries one. Errors are `{error, error_description}` |
| OPTIONS | `/oauth/par`, `/oauth/token`, `/oauth/revoke` | public, no-csrf | — | The CORS preflights of a Bluesky browser app |
| GET | `/xrpc/{method}` | public, no-csrf | the method's parameters | The AT Protocol query surface of this instance as a PDS, served at the root through the web-server rules in `contrib/webserver`: `com.atproto.server.describeServer`; `com.atproto.identity.resolveHandle` (local and DNS/`.well-known` handles), `resolveDid` (local, PLC and `did:web` DIDs), and `resolveIdentity` (with a bi-directionally verified handle); `com.atproto.sync.getRepo` (a CAR), `getLatestCommit`, `getRepoStatus`, `getRecord` (a CAR of commit, tree and record), `getBlob`, `listBlobs`, `listRepos`, `com.atproto.repo.describeRepo`, `getRecord`, `listRecords`, and `_health`. `subscribeRepos` on this URL answers **426**: it is the WebSocket `occ social:atproto:serve` serves. Anything else is **501** `MethodNotImplemented`; errors are `{error, message}`. |
| POST | `/xrpc/{method}` | public, no-csrf | the method's body | The procedure surface. `createSession`, `refreshSession` and `deleteSession` sign a Bluesky app in and out with an app password; `com.atproto.identity.refreshIdentity` re-resolves an identifier and returns its verified identity info without changing account state. With a signed-in session — an app password's bearer token, or a Bluesky sign-in (OAuth) token with its `DPoP` proof — `com.atproto.identity.updateHandle` validates and assigns the account's handle, including reverting to its assigned `alice.<host>` handle; OAuth requires `identity:handle` or `identity:*`. `putRecord` updates supported post text, language, self-labels and media under the existing AT URI, and can replace or remove supported quoted-post and non-post record embeds. Both creation and replacement accept image galleries up to ten owned uploads, including galleries inside `recordWithMedia`; the older `images` embed remains limited to four. Oversized lists are rejected before any upload metadata is changed, and empty image/video alt text clears an old description. Reply targets can be replaced or removed with access, reply-permission, audience and cycle checks; embeds that cannot be represented without loss are refused. `app.bsky.actor.link` records are kept as written, and profile `links` accepts up to ten ordered strong references to link records in the same account repository. Ordinary profile publishing preserves this selection. Local and remote profile responses expose safe display links in `bluesky.links` as `{url, title}`. Repository writes, `uploadBlob`, preferences, `createReport` and the `app.bsky.*` procedures (passed to the AppView) are answered for the signed-in account; `uploadBlob` also takes a token the account signed for Bluesky's video service. Without a session, **401** `AuthenticationRequired`; without the required scope, **403** `InsufficientScope`; anything else **501**. `createAccount` makes an account only for a DID invited to move here, with its one-time code (as `password` or `inviteCode`) and a service-auth token the DID signs for this server (**400** `InvalidInviteCode`, **401** `AuthenticationRequired`); its session may only move the account: `checkAccountStatus`, `importRepo` (a CAR up to 64 MB, checked against the DID's key), `listMissingBlobs`, `uploadBlob` (kept byte for byte), `getRecommendedDidCredentials`, `submitPlcOperation` (only an operation naming this server and the recommended key), `activateAccount` (once the directory names them), preferences, `refreshSession`; anything else **403** `InsufficientScope`. |
| OPTIONS | `/xrpc/{method}` | public, no-csrf | — | The CORS preflight a Bluesky web client sends. It is answered for every origin and allows the XRPC headers `Authorization`, `Content-Type`, `DPoP`, `X-Atproto-Session-Id`, `X-Atproto-Device-Id`, `X-Atproto-Bsky-Topics`, `X-Bsky-Topics`, `atproto-accept-labelers` and `atproto-proxy`; these headers are available on every PDS instance running this app, regardless of its domain. This XRPC policy is separate from the Fediverse `/api/` CORS policy above. |
| GET | `/.well-known/atproto-did` | public, no-csrf | `handle` (optional; the request's host otherwise) | The DID of the handle this request's host is, as plain text — what `https://alice.<host>/.well-known/atproto-did` answers once the wildcard host reaches the app. A handle that was never issued is a **404**. |
| GET | `/.well-known/did.json` | public, no-csrf | — | The instance's own `did:web:<host>` document: its service key and the PDS endpoint. |
| DELETE | `/admin/relays/{id}` | **administrator**, csrf | `id` | Unsubscribes and forgets it. The `Undo{Follow}` is sent first and its failure does not stop the row going — an administrator who pressed this wants to stop taking that relay's posts, and nothing further is taken from it either way, because taking one in needs a row. An unknown id is a **404**. |
| POST | `/moderation/retention` | moderator, csrf | `days` (required, 0–3650) | Sets the `retention_days` app setting: remote statuses older than this that no local user cares about are pruned (0 disables). Returns `{"retentionDays": n}`. |


### External users

Self-registered external users: people without a Nextcloud account who create one that reaches the Aloha Social app only. See the "External users" section of `docs/Architecture.md` for how the accounts work; these are the routes of the registration page, of the settings page's External users cards, and of the invitations people may send.

The registration routes are public and refuse a visitor who is logged in. The administration routes carry none of the relaxing attributes: they are dispatched for an administrator with a session and a CSRF token and for nobody else, not for a group the Aloha Social section was delegated to. The ones marked **password** also need a recent password confirmation, which the page asks for.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/signup` | public, no-csrf | `invite` | The registration landing page and form, drawn in the guest layout like the login page. Initial state `signup` includes `open`, `reason`, mode, email confirmation, minimum age, server rules, privacy and legal links, the instance's plain-text `signupNotice`, and `bluesky` (`enabled`, `host`: whether an account made here gets a Bluesky handle and the host it is issued under, for the page to preview it). An `invite` token that is valid opens registration in every mode. A logged-in visitor is sent to Aloha Social. |
| POST | `/signup` | public, csrf | `handle`, `email`, `password`, `rules` (false), `age` (false), `invite`, `website` | A registration. Answers `{"state", "handle"}`: `verify` (a confirmation email was sent), `approval` (it waits for an administrator) or `created` (the account exists, the person may log in). A refusal is a **422** with `{"message", "field"}`, the message translated and fit to show. `website` is a honeypot no person fills in; a registration that fills it is answered as if it had worked and nothing is stored. Rate limited to 10 an hour per address, and 5 an hour per address across all registrations. |
| GET | `/signup/verify/{token}` | public, no-csrf | `token` | The link from the confirmation email. Draws the registration page with a `result`: `approval`, `created`, or `error` with a `message`. A link is good for 24 hours and once. |
| GET | `/admin/external` | **administrator**, csrf | — | Everything the External users cards show: `{"settings", "twoFactor", "requests", "invites", "users"}`. Settings include the instance's plain-text `signupNotice`. The same shape every administration route below answers with after a change. |
| POST | `/admin/external` | **administrator**, csrf | `enabled` (false), `max` (100), `quota` (1024), `mode` (`approval`), `verifyEmail` (true), `minAge` (16), `reserved` (`[]`), `userInvites` (false), `signupNotice` (empty) | Writes the settings, all or none, and answers with `settings`. `max` is 0 to 1000000 accounts, `quota` the megabytes of media each may upload (0 is no quota), `mode` is `open`, `invite` or `approval`, `minAge` 0 to 99 (0 asks nothing), `reserved` the handles nobody may register. `signupNotice` is plain text up to 4000 characters and is shown before registration. A value out of range is a **422** naming it. Switching the feature on where Aloha Social is restricted to groups adds the externals' group to them. |
| POST | `/admin/external/restriction` | **administrator**, csrf | — | Adds the externals' group, `social-external`, to the groups Aloha Social is restricted to. Answers with `settings`. |
| POST | `/admin/external/two-factor` | **administrator**, csrf, **password** | `enforced` (false) | Requires two-factor authentication of external users, or stops requiring it, by changing core's mandatory two-factor setting for their group. Answers `{"enforced", "everybody"}`; `everybody` is true when core enforces it for everybody, externals included unless excluded. |
| GET | `/admin/external/users` | **administrator**, csrf | `search`, `offset` (0) | A page of 50 external accounts: `uid`, `displayName`, `email`, `created`, `lastLogin`, `enabled`, `mediaBytes`, `origin`. |
| POST | `/admin/external/users/{uid}/promote` | **administrator**, csrf, **password** | `uid` | Makes the external user an ordinary local user, keeping the user id, the password, two-factor and the Aloha Social account. A **422** when it is not an external user or cannot be promoted. |
| POST | `/admin/external/users/{uid}/enabled` | **administrator**, csrf | `uid`, `enabled` (true) | Disables the account, or enables it again. Answers `{"uid", "enabled"}`; **404** for somebody who is not an external user. |
| DELETE | `/admin/external/users/{uid}` | **administrator**, csrf, **password** | `uid` | Deletes the account, and with it the Aloha Social account and everything it posted, the way deleting any Nextcloud user does. **404** for somebody who is not an external user. |
| POST | `/admin/external/requests/{id}` | **administrator**, csrf | `id` | Admits a registration that is waiting for approval: the account is created and the person is emailed. A **422** when there is no such registration or the account cannot be created, the server being full among the reasons. |
| DELETE | `/admin/external/requests/{id}` | **administrator**, csrf | `id`, `reason` | Turns a registration down and forgets it. The person is emailed, with `reason` when there is one. **404** for an unknown id. |
| POST | `/admin/external/invites` | **administrator**, csrf | `note`, `maxUses` (1), `days` (7) | An invitation link. `maxUses` 0 admits any number of registrations and `days` 0 never expires. Answers with the invitation: `{"id", "url", "creator", "note", "maxUses", "uses", "expires", "created"}`. |
| DELETE | `/admin/external/invites/{id}` | **administrator**, csrf | `id` | Withdraws anybody's invitation. **404** for an unknown id. |
| GET | `/invites` | user, csrf | — | Whether this person may send invitations (`allowed`, which the administrator switches on) and the ones they sent (`invites`). |
| POST | `/invites` | user, csrf | `note` | An invitation from this person: single-use, valid for 7 days, at most 10 open at a time. A **422** when invitations are off or the limit is reached. Rate limited to 20 an hour. |
| DELETE | `/invites/{id}` | user, csrf | `id` | Withdraws one of this person's own invitations. **404** for anybody else's. |

---

## OAuth

A partial, Mastodon-shaped OAuth 2 flow (`OAuthController`, `ClientService`).

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| POST | `/api/v1/apps` | public, no-csrf | `client_name` (`''`), `redirect_uris` (string or array, `''`), `website` (`''`), `scopes` (`'read'`) | Registers a client. Returns `{"id", "name", "website", "scopes", "redirect_uris", "client_id", "client_secret", "redirect_uri", "vapid_key"}`; `scopes` and `redirect_uris` are lists, as Mastodon 4.3 sends them, and `redirect_uri` is the first of the registered URIs. `redirect_uris` may be an array or, as Mastodon's own API takes it, several URIs newline-separated in one field — those are split into separate entries, trimmed, de-duplicated and stripped of blanks. They used to be wrapped into a single entry, which `ClientService::confirmData()` then compared a lone URI against, so a client registered with more than one could never authorize with any of them. Each URI has to be the out-of-band urn, an `http`/`https` address with a host, or a native application's own scheme (`tusky://…`), written in lower case; a scheme a browser runs rather than follows (`javascript`, `data`, `vbscript`, `file`), a relative path or anything else is a **422** `{"error": "..."}`, as is a registration with no name or no URI at all. Rate-limited to 15 registrations per five minutes, per address and per account. A registration nobody has authorized within **seven days** is removed by `Cron\Cache` (`ClientService::sweep()`); one that was authorized once is kept even after its authorizations expire. |
| POST | `/oauth/device_authorization` | public, no-csrf | `client_id`, `client_secret` when registered, `scope` (`'read'`) | Starts RFC 8628 device authorization for a registered app. Returns a 43-character one-time `device_code`, an eight-character `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in` (600) and `interval` (5). Only the SHA-256 digest of the device code is stored. Confidential apps must present their registered client secret; scopes must be a subset of the app's registered scopes. |
| GET | `/oauth/device` | user | `user_code` (optional, may include its hyphen) | Verification page. Enter the code shown on a screen you control; it shows the registered app, its requested scopes and the signed-in account before approval. Unknown, expired and already-used codes are presented alike. A reader without a Social account is offered account setup before consent. |
| POST | `/oauth/device` | user, CSRF-protected, brute-force protected | `user_code`, `decision` (`allow` or `deny`) | Records the signed-in account's one-time decision for a pending device request. A code can only be approved once. |
| GET | `/.well-known/oauth-authorization-server` | public, no-csrf | — | RFC 8414 discovery, which a Mastodon 4.3 client asks for before it registers an app: the authorization, device-authorization, token, revocation, userinfo and app-registration endpoints, `scopes_supported` (every scope this server understands), `response_types_supported: ["code"]`, `grant_types_supported` (including RFC 8628 device authorization) and the two client-authentication methods. **The addresses are this app's real ones**, under the app's own path rather than the domain root — the honest answer and the useful one, because a client that reads this document is told where the endpoints are rather than assuming Mastodon's root paths. A client that does not read it looks at the root, finds nothing and is no worse off than before. |
| GET | `/oauth/userinfo` | public, no-csrf (bearer token) | — | Who the token belongs to, in OpenID Connect's shape: `sub`, `name`, `preferred_username`, `profile`, `picture`. Mastodon 4.3 added it so a client can show "signed in as …" without spending a `read:accounts` call on `verify_credentials`, and it needs no scope beyond having a token. `sub` is the actor's **ActivityPub id**, not the Nextcloud user id: it is the identifier that means the same thing to everybody, and an internal user id is not a thing to hand to every client that asks. An invalid token is a **401**. |
| GET | `/oauth/authorize` | public, no-csrf (redirects a visitor to Nextcloud login) | `client_id`, `redirect_uri`, `response_type` (must be `code`), `scope` (`'read'`), `state` (`''`) | Renders the `oauth2` consent template. `redirect_uri` has to be, exactly, one of the URIs the client registered (RFC 6749 §3.1.2.3: compared as a string, so another path, port or query string is not it), checked before the page exists, so there is nothing to confirm on a forged link; one that is not is HTTP 400 `{"error": "invalid_request", "error_description": "..."}`, never a redirect, since the one parameter that is wrong is where the redirect would go. `state` is carried through to the POST. Anything else wrong with the request — an unknown `client_id`, a `response_type` that is not `code`, a scope the client never registered — is HTTP 400 `{"error": "..."}`, the way the POST answers it; these used to escape as a Nextcloud HTML error page. **A reader without an account here** — somebody whose first visit is from an app — is asked for a username on the same page, once the request has passed every check above (an invalid request is refused without that): the page gets a `setup` initial state (`suggestedHandle`, `socialAddress`, `bluesky`) instead of `account`, creates the account through `POST /api/v1/account/create` with the page's session, as the app's own setup page does, and then loads the same address again, which carries the client's request unchanged and now draws the consent for the new account. A Bluesky app's pushed request (`request_uri`) is answered the same way once the request is found good; the account's Bluesky identity is made when the consent is drawn for it. A visitor without a Nextcloud session is redirected to the Nextcloud login form with this authorization URL as `redirect_url`, so login returns to the same validated OAuth request before consent. Any other failure is logged and answered HTTP 500 `{"error": "server_error"}`, as from `/oauth/token`, since its message describes the server. |
| POST | `/oauth/authorize` | user | `client_id`, `redirect_uri`, `response_type`, `scope` (`'read'`), `state` (`''`) | Issues an authorization code. Answers with a redirect to `redirect_uri` (`RedirectResponse`, so HTTP **303**) carrying `code` and, when one was sent, `state` — appended with `http_build_query`, so a `redirect_uri` that already has a query string or a fragment stays valid. `state` used to be dropped, which a spec-following client rejects and a lax one is open to code injection through. For `urn:ietf:wg:oauth:2.0:oob` the code (and `state`) come back as the response body instead. `redirect_uri` is held to the same rule as the GET — exactly one of the registered URIs, else HTTP 400 `{"error": "invalid_request", ...}` and no code is issued — and the one the code is sent to is recorded on the authorization, because the token exchange has to name it again. Errors: HTTP 400 `{"error": "..."}` for what is wrong with the request, as for the GET; HTTP 403 `account-not-set-up` with `setup_url` (see [Authentication](#authentication)) for a reader without an account, checked after the request, and no code is issued — a token always names an account; and HTTP 500 `{"error": "server_error"}` for anything else. |
| POST | `/oauth/token` | public, user, no-csrf | `client_id`, `client_secret` when registered, `redirect_uri`, `grant_type` (`authorization_code`, `client_credentials` or `urn:ietf:params:oauth:grant-type:device_code`), `scope` (`'read'`), `code`, `code_verifier`, `device_code` | Exchanges an authorization code, app credentials or an approved device code for a bearer token: `{"access_token", "token_type": "Bearer", "scope", "created_at"}`. Authorization codes still require the exact `redirect_uri` they were issued for. Device polling returns RFC 8628's `authorization_pending`, `slow_down` (raising the required interval by five seconds each time), `access_denied`, `expired_token`, and a one-time token response; a device code cannot be used twice. Confidential apps must present their registered client secret for device polling. `scope` reports the scopes the **token** carries — what `ApiController::checkTokenScope()` enforces — not the scope of this call. Credential failures are brute-force throttled; a server failure is HTTP 500 `{"error": "server_error"}` with the cause in the log. |
| POST | `/oauth/revoke` | public, user, no-csrf | `client_id`, `client_secret`, `token` | Revokes an access token (RFC 7009). Only the client the token was issued to may revoke it; an unknown or already-revoked token still returns HTTP 200 `[]`. Wrong client credentials return a throttled HTTP 401. |
| GET | `/api/v1/authorized_apps` | public, no-csrf (viewer required, the broad `read` scope) | — | **The apps this account has signed in to**, newest first: `{"id", "name", "website", "scopes", "created_at", "last_used_at", "expires_at", "signed_in"}` per row. `id` is the `social_client_auth` row, `created_at` is when *this account* granted it (not when the app registered on the instance), `last_used_at` is the last request the token made (kept to within five minutes), `expires_at` is when the token stops working however much it is used — `created_at` plus `token_max_days`, or `0` where that is off — and `signed_in` is false for an authorization whose code was never exchanged for a token — the browser came back and the app never asked. A client reaches it with its bearer token, but only one granted all of `read`: this is the list of the person's *other* apps, and one granular read is not consent to see it. The token itself is never in the answer; it is stored hashed and nothing here wants it. |
| DELETE | `/api/v1/authorized_apps/{id}` | public, no-csrf (viewer required, `write` scope; a token only its own authorization) | `id` | Takes one of them back — the app is signed out at once, because the token is the row and the row is gone. The authorization is looked up among this account's own rather than deleted by the id it was handed, so signing a stranger's device out is impossible rather than unlikely; an id that is not this account's is a **404**, the same answer an id that does not exist gets. **A bearer token may revoke only its own authorization** (an app signing itself out); any other id is a **403** whether it exists or not, so that answer says nothing either. Signing *another* app out takes the Nextcloud session — the settings page, or an app password with `OCS-APIRequest: true`: this route manages other apps' tokens, Mastodon has no API for that at all, and nothing a client was granted is consent to sign the person's other apps out. |

**Grant types:** `authorization_code`, `client_credentials` (RFC 6749 §4.4), and `urn:ietf:params:oauth:grant-type:device_code` (RFC 8628). The device grant gives an app a short code and address to show on a device without a keyboard; a signed-in person enters the code on another device, checks the app and scopes, then approves or denies it. The client polls `/oauth/token` at the advertised interval, and the token is issued once to the account that approved the request. The app-only `client_credentials` token is bound to no account and has `read` scope only. Device polling errors use RFC names: `authorization_pending`, `slow_down`, `access_denied`, `expired_token` and `invalid_grant`.

**Scopes:** `SocialClient::getScopesFromString()` splits requested scopes on spaces and `ClientService::confirmData()` checks they are a subset of the scopes registered for the app; the default everywhere is `read`. Bearer tokens are enforced per endpoint by `ApiController::checkTokenScope()`: creating, editing and deleting statuses, uploading media and updating its alt text, status actions, poll votes, moving markers, `update_credentials` and filing reports need `write`; follow/unfollow, block, mute and authorizing or rejecting follow requests need `follow` or `write`; the Web Push subscription routes require `push`; `/api/v1/apps/verify_credentials` accepts any valid token; every other `/api/` route needs `read`. A granular scope is satisfied by itself or by the broad scope that contains it (`write:statuses` by `write:statuses` or `write`), never by a sibling (`write:favourites` does not permit posting); the other client-API controllers apply the same rule through `ClientApiController`. Session-cookie requests are not scope-restricted, but are only accepted together with a valid CSRF token.

**Credential storage:** client secrets, authorization codes and access tokens are stored as `sha256:<hex>` digests (`SecretHasher`); rows from before hashing held the bare value and were hashed by migration `Version1000Date20261008000100` — or, where that failed, deleted, signing that app out — and **a bare stored value is no longer accepted**. A presented credential that already looks hashed is refused rather than looked up — accepting it made the stored digest a working bearer token of its own, so a database dump held usable credentials.

**Token lifetime:** `ClientService::TIME_TOKEN_TTL` is 30672000 s (~1 year) since last use; a used token's `last_update` is refreshed at most once per `TIME_TOKEN_REFRESH` (300 s).

---

## ActivityPub Federation

`ActivityPubController` decides per request, via `checkSourceActivityStreams()`, whether the caller is a Fediverse server: it splits the `Accept` header on commas, trims each entry at the first `;`, and returns true if any entry equals `application/ld+json` or `application/activity+json`. Anything else (a browser) is treated as HTML.

JSON-LD responses are emitted through `activityPubSuccess()`, i.e. `Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams"`. The controller also registers `activity+json` and `ld+json; …` responders for format-based negotiation.

| Method | Route | Auth | Content negotiation | Description |
|--------|-------|------|--------------------|-------------|
| GET | `/actor` | public, no-csrf | always JSON-LD | This instance's own `Application` actor — the identity every outbound signed fetch is made as, and the `publicKey.id` owner a peer dereferences to check one. It is not an account: no outbox, no followers, no following and no featured collection are named, because naming a collection no route serves makes a peer that follows it conclude the actor is gone; `manuallyApprovesFollowers` is true and `discoverable`/`indexable` are false, so nothing offers it as somebody to follow or index. `inbox` and `endpoints.sharedInbox` both point at the shared `/inbox`, which is a real endpoint and the right one — anything addressed to this actor is addressed to the server. The key pair lives in app config (`instance_actor_public_key`, and the private half sealed with the instance secret), generated on first use; an instance that does not yet know its own social URL 404s here and signs nothing rather than signing with a `keyId` nobody can resolve. |
| GET | `/users/{username}` | public, no-csrf | JSON-LD for AP `Accept`, else HTML | Actor object (with W3C security context). Unknown actor → error envelope with HTTP 404. Without an AP `Accept` header it delegates to `SocialPubController::actor()`, which answers a browser: the app for a reader with a session, the public page for a visitor, a **404** for an account this instance does not hold. The client-side router has no view for this path — it owns `/@{username}` — so a browser sent here lands on the app with nothing in it; the alias below is the address to link. |
| GET | `/@{username}/` | public, no-csrf | same as above | Alias that calls `actor()`. For a browser (`Accept` without an ActivityPub type) `SocialPubController` answers: a reader with a session gets the app, the same page as `/`, since the client-side router has a view for the path; a visitor gets the public page; an account this instance does not know is a **404** — a small guest page for a visitor, the app with a 404 status for a reader. The lookup is of what is cached and does not go and fetch an unknown name, which is where an unknown name used to become a 500. |
| GET | `/@{username}/collections` | public, no-csrf | HTML | An account's collections, for a browser: a reader with a session gets the app, whose router owns the path, and a visitor the public page — the same page the profile itself answers with. Not an ActivityPub URL: a collection is local and federates nothing, so unlike the followers page there is no JSON to answer first. |
| GET | `/@{username}/portfolio` | public, no-csrf | HTML | An account's page of work, for a browser — and the point of the feature: a portfolio is what a photographer links from a CV, and a link that asks the reader to sign in first is not that. The client-side router owns the path; this exists so a link to it opened cold is not a 404. |
| POST | `/@{username}/inbox` | public, no-csrf | JSON | Per-user inbox. Rate-limited on the source address and read with a **2 MB ceiling** (`ActivityPubController::MAX_INBOX_BODY`, Mastodon's figure) before any signature work — a body past it is a **413** and nothing is digested, fetched or verified — then verifies the HTTP signature, checks the Fediverse access list, spends the *verified* origin's own looser bucket, requires the local actor to exist, imports the activity, then async-processes the stream cache queue (`inbox_throttle` app setting, default 300/min, 0 disables; either bucket → HTTP 429). Returns `{"result": [], "status": 1}`; a gone signature also returns success. A refusal is answered with the status that says what was wrong — 401, 403, 400, 404 or 503, and 500 only for a fault of ours; see the rejection table in `docs/Architecture.md`. |
| GET | `/@{username}/inbox` | public, no-csrf | JSON-LD | Empty `OrderedCollection` (`totalItems: 0`) for the actor's inbox; bare `[]` with HTTP 404 if the actor is unknown. |
| POST | `/inbox` | public, no-csrf | JSON | Shared inbox, same processing (including both rate limits and the same rejection statuses) without the per-actor check. |
| GET | `/@{username}/outbox` | public, no-csrf | always JSON-LD | Outbox collection; with `?page=N` (or `?page=true`) one `OrderedCollectionPage` of the author's public posts, newest first, as `Create` activities. A full page's `next` is a cursor, `?page=true&max_id=<nid of its last post>`, read below the cursor rather than at an offset — a numbered page reads and discards every post before it, so only `first` is numbered; a `max_id` that is not a nid is an empty page. The HTML fallback is commented out in the source, so browsers get JSON-LD too. |
| POST | `/@{username}/outbox` | public, no-csrf | always JSON-LD | Same route handler as the GET, registered as `ActivityPub#outbox_post`; posting an activity is **not** implemented — the method only returns the outbox collection. |
| GET | `/@{username}.rss` | public, no-csrf | `username` | **An account's public posts as an RSS 2.0 feed.** PeerTube publishes one per channel and Mastodon one per account, and PeerTube's users in particular live in feed readers and podcast apps: a channel with no feed is one they cannot subscribe to from outside. A video carries an `<enclosure>`, which is what makes such a feed usable in a podcast client at all. Built from an **anonymous** read — the same one a stranger visiting the profile gets — because a feed is the easiest possible way to leak a followers-only post: one wrong predicate and it is in somebody's reader and out of reach for ever, so `FeedService` refuses a non-public post a second time. Twenty posts, cached ten minutes. |
| GET | `/@{username}/followers` | public, no-csrf | JSON-LD for AP `Accept`, else HTML | Followers collection, or the page: the app for a reader with a session, the public page for a visitor, a 404 for an unknown account. With `?page=N` (or `?page=true`) one `OrderedCollectionPage` of follower ids, newest follow first; a full page's `next` is a cursor, `?page=true&max_id=<creation>-<follow prim>`, read after the cursor on the `social_f_ocr` index rather than at an offset. A `max_id` that is not such a cursor is an empty page. The AP branch is refused with 401 under `secure_mode` when nothing signed the fetch; the page is not, since a browser has nothing to sign with. |
| GET | `/@{username}/following` | public, no-csrf | JSON-LD for AP `Accept`, else HTML | Following collection, or the page, the same way, paged by the same cursor. The AP branch is refused with 401 under `secure_mode` the same way. |
| GET | `/@{username}/collections/featured` | public, no-csrf | always JSON-LD | The actor's pinned posts as an `OrderedCollection` whose `orderedItems` carry the full posts (at most 5). This is where remote servers read pinned posts from; the actor document points at it with `featured`. The route has no `Accept` gate and no viewer, so the posts are read through the anonymous visibility filter and only public ones appear; it is refused with 401 under `secure_mode` when nothing signed the fetch — `PinService::pin()` refuses anything narrower in the first place, but posts pinned before that rule existed stop being exposed here with no cleanup step. Unknown actor → error envelope with HTTP 404. |
| GET | `/@{username}/stories/{id}` | public, no-csrf | always JSON-LD | One story as a `Story` object — and the **capability** the `Add` carried. Two ways in: a request bearing the story's own token (`Authorization: Bearer …`), which is how Pixelfed fetches a story, or the rule the client API keeps — the author, or whoever signed the fetch and follows them. The token names one story, is derived rather than stored (HMAC of the story's address under an instance secret generated on first use), and stops working when the story does. Anybody else, and an expired story, is the same **404**, because whether an account has a story up is told to its followers and to nobody else. `{id}` is numeric, which is what keeps it out of the way of the `/@{username}/{token}` catch-all below. |
| GET | `/@{username}/{token}` | public, no-csrf | JSON-LD for AP `Accept`, else HTML | Single post. `{token}` values `outbox`, `followers` and `following` (case-insensitive) are re-routed to those handlers first. For AP callers the `Stream` is returned as JSON-LD (HTTP 404 error envelope with a `stream` key when missing). A browser is answered by `SocialPubController::displayPost()`: the post is resolved by its address and then, when `{token}` is all digits, by the numeric id the app itself links with, and is rendered into the page as `item` in the client format, so it shows before the app has asked for anything. A reader with a session gets the app around it, the same page as `/`; a visitor gets the public page. Only a local public post advertises the oEmbed endpoint through a `Link` header. A post that resolves to nothing is a **404**: a small guest page for a visitor, the app with a 404 status for a reader, whose post view says the post is not available once it has asked. |
| GET | `/@{username}/{token}/embed` | public, no-csrf, rate-limited | minimal HTML | A responsive embeddable view of a local public post, without the app shell. It shows the author, avatar, handle, date, body, and same-instance image, video or audio attachments; it follows the viewer's light/dark preference. Unlisted, followers-only, direct, remote or missing posts all return the same **404**. Only this endpoint allows cross-origin framing; its oEmbed response and the post action menu's **Copy code** item point here. Content warnings remain collapsed, only same-instance media is loaded, and the response is not cached so a deletion or visibility change takes effect immediately. |
| GET | `/@{username}/{token}/quote_authorizations/{stamp}` | public, no-csrf | always JSON-LD | The FEP-044f approval a quote of `{token}` rests on, as a `QuoteAuthorization` naming the quoted author (`attributedTo`), the quoting post (`interactingObject`) and the quoted post (`interactionTarget`). `{stamp}` is the quoting post's id, base64url-encoded without padding — the same URI this instance put in the `Accept` that granted the approval. Answered from the quoted post's current policy where that lets anybody quote it, and otherwise from the grant `QuoteRequestInterface::accept()` recorded for exactly that quoting post, so a stamp anybody could mint approves nothing a followers-only or quote-nobody author never accepted; a post narrowed after the fact stops being quotable and the approval 404s with it, as does a grant that was taken back. A stamp this instance would not have written (a second base64 spelling, or one that does not decode to an address) is a 404 as well. No viewer is set: an approval is a public statement about a public post. Refused with 401 under `secure_mode` when nothing signed the fetch. |
| GET | `/@{username}/{token}/replies` | public, no-csrf | always JSON-LD | The replies to `{token}`, as an `OrderedCollection` whose `first`/`last` point at `?page=N`; with `?page=N` (or Mastodon's `?page=true`, which means the first) it answers with an `OrderedCollectionPage` of at most `OrderedCollection::PAGE_SIZE` (40) items. A full page's `next` is a cursor, `?page=true&min_id=<nid of its last reply>`, and that page is read after the cursor rather than at an offset; a numbered page also carries `prev`, a cursor page does not. A `min_id` that is not a nid is an empty page. The note itself points here with `replies`. Items are the replies' **ids**, not the replies: a reply is its author's document, served by their instance, which may since have edited or deleted it. No viewer is set, so only **public** replies appear — a followers-only or direct reply is not listed even as an id, because an id is enough to fetch the reply from the instance that holds it. Oldest first, so a page stays stable as the thread grows. A post this instance does not hold, or one that does not exist, is an error envelope with HTTP 404 — and so is a followers-only or direct post: like the post itself, its replies collection is not confirmed to exist to a reader it was not addressed to. Refused with 401 under `secure_mode` when nothing signed the fetch. |
| GET | `/@{username}/{token}/likes` | public, no-csrf | always JSON-LD | How many likes `{token}` has had, as an `OrderedCollection` carrying `totalItems` and nothing else: who liked a post is not published, which is what Mastodon and PeerTube do too. A `Video` points here with `likes`. PeerTube fetches it for every video it takes in and writes the number it finds; a video without it made PeerTube write an undefined count, and the unhandled failure crashed the whole server. `totalItems` is stated when it is 0, which every collection here now does. The same 404s and 401 as `replies`. |
| GET | `/@{username}/{token}/dislikes` | public, no-csrf | always JSON-LD | The same for dislikes, PeerTube's other counter; a `Video` points here with `dislikes`. |

### Discovery documents (not app routes)

WebFinger, NodeInfo discovery and host-meta are served by `lib/WellKnown/WebfingerHandler.php`, registered through `registerWellKnownHandler()` in `lib/AppInfo/Application.php` — they are Nextcloud-level paths (.well-known/webfinger, .well-known/nodeinfo, .well-known/host-meta), not entries in this app's route table. Only the NodeInfo 2.0 *document* itself is an app route (see `/.well-known/nodeinfo/2.0` above).

The handler first checks `FediverseService::jailed()` and passes the previous response through when the instance is not allowed to federate. For `webfinger` with a `resource` query parameter (`acct:` prefix stripped; the raw request URI is parsed as a fallback):

- The app's own subject gets an extra link added to the existing response, carrying `app`, `name` and `version` properties.
- For a local actor it returns a JRD document whose `subject` is the requested resource, with aliases for the actor URL and the Nextcloud profile page, a `self` link of type `application/activity+json` pointing at the `/@{username}/` route, an `http://webfinger.net/rel/profile-page` link (`text/html`) to the Nextcloud profile page, and an `http://ostatus.org/schema/1.0/subscribe` link with a `template` of `<social url>ostatus/follow/?uri={uri}`.
- `acct:<host>@<host>` — the instance's own handle, the one Mastodon gives its instance actor — returns a JRD with an alias and a `self` link (`application/activity+json`) pointing at `/actor`. It is answered before any local account is looked up, so a Nextcloud user whose id happens to equal the instance host cannot take the name the server signs under.
- A missing or empty `resource` parameter is an empty JRD with HTTP 400 (RFC 7033 makes the parameter mandatory).
- Unknown or non-local subjects produce an empty JRD with HTTP 404 (or hand back to the previous handler when the actor lookup fails outright).

The `nodeinfo` service returns one link per schema the app serves — rel `http://nodeinfo.diaspora.software/ns/schema/2.0` and `…/2.1`, pointing at `/.well-known/nodeinfo/2.0` and `/.well-known/nodeinfo/2.1`. Oldest first, so that a consumer which naively takes the first link keeps getting what it got before 2.1 was reachable, while one that reads the document properly takes the highest version it understands. The list is `OAuthController::NODEINFO_SCHEMAS`, which is also what the controller serves, so the two cannot drift apart. The `nodeinfo` answer carries `Access-Control-Allow-Origin: *`, as the documents it links to do, so a browser client of another origin can read it. `host-meta` returns XRD (`application/xrd+xml`) with an `lrdd` template pointing at the instance's WebFinger URL.

---

## Legacy OStatus

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/ostatus/follow/` | user, no-csrf | `uri` (required; an address, an `acct:` URI or an actor id) | Renders the Vue app with `account`, `resolve` and `currentUser` in initial state. Anybody can write the link, so the account is looked up only among those this server holds: one it holds is `account`; one it does not is `resolve` (`account` `''`), and the page asks no other server until the reader presses **Look up**, which calls the route below. Requires a logged-in user; failures return the error envelope. |
| POST | `/api/v1/ostatus/resolve` | user (CSRF checked, 30 a minute) | `uri` | Looks the account `uri` names up, on its own server where this one does not hold it, and answers `{"result": {"account": "user@host"}}` for the page to load; one nobody has is the error envelope with 404. |
| GET | `/api/v1/ostatus/followRemote/{local}` | public, user, no-csrf | — | Renders the Vue app with the **guest** layout, providing `local` and `account` in initial state, so a remote visitor can follow the local account `{local}`. |
| GET | `/api/v1/ostatus/link/{local}/{account}` | public, user, no-csrf, rate-limited (10/5min per IP) | — | WebFingers `{account}`, extracts its `http://ostatus.org/schema/1.0/subscribe` link template, substitutes `{uri}` with `{local}`'s account, and returns `{"result": {"url": "<subscribe url>"}, "status": 1}`. A template whose result is not an `http(s)` URL is a **422**: the browser is sent to the result, and the template is the remote server's to write. |

---

## Frontend / Document serving

These serve HTML or files for the app's own UI; they are not client API endpoints.

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| GET | `/` | public, user, no-csrf | `cloudAddress` (read from the request during first-run setup, admins only) | A signed-in reader gets the Vue app and private home feed as before. An anonymous visitor gets `PublicTemplateResponse` with only public-page state; no actor, cloud setup, current account or private feed is loaded. The client routes guests to the instance's public local feed. |
| GET | `/timeline/{path}` | public, user, no-csrf | `path` (default `''`, `requirements: .+`) | Same page. A visitor asking for one of the reader's own timelines — `notifications`, `direct`, `favourites`, `bookmarks`, `list/…`, `interests` — is sent to Nextcloud's login with the address as `redirect_url`, which brings them back once signed in; every other timeline is the public page. |
| GET | `/follow_requests` | user, no-csrf | — | Same page. The path belongs to the client-side router; the server answers it so that reloading or bookmarking the follow-requests page works instead of 404ing. **Signed-in only**: not a public page, so Nextcloud sends a visitor to its login with the address as `redirect_url`, and back here once signed in. |
| GET | `/blocked` | user, no-csrf | — | Same page, for the blocked-and-muted-accounts view (**Settings → Blocking** in the app's sidebar). **Signed-in only**: not a public page, so Nextcloud sends a visitor to its login with the address as `redirect_url`, and back here once signed in. |
| GET | `/discover` | public, user, no-csrf | — | Same page, for the Discover view — who to follow (suggestions and starter packs), and what is being looked at (pictures and hashtags). The client-side router owns the path; this route exists so that reloading or bookmarking it is not a 404. |
| GET | `/migration` | user, no-csrf | — | Same page for the path Migration used to have. It is a section of Settings now, and the client-side router redirects there; the route stays so that a bookmark or a link somebody was sent is not a 404. **Signed-in only**: not a public page, so Nextcloud sends a visitor to its login with the address as `redirect_url`, and back here once signed in. |
| GET | `/switch` | user, no-csrf | — | Same page, for the step-by-step way in from another network (**Moving in**, linked from Migration). The client-side router owns the path; this route exists so that reloading or bookmarking it is not a 404. **Signed-in only**: not a public page, so Nextcloud sends a visitor to its login with the address as `redirect_url`, and back here once signed in. |
| GET | `/statistics` | user, no-csrf | — | Same page, for the Statistics view — what the account has posted and what came back. The client-side router owns the path; this route exists so that reloading or bookmarking it is not a 404. **Signed-in only**: not a public page, so Nextcloud sends a visitor to its login with the address as `redirect_url`, and back here once signed in. |
| GET | `/shorts` | public, user, no-csrf | — | Same page, for the Shorts stack — the videos of a timeline watched one at a time rather than chosen from a grid. The client-side router owns the path; this route exists so that reloading or bookmarking it is not a 404, and so that a link to it is a link somebody can be sent. |
| GET | `/reels` | public, user, no-csrf | — | The Shorts stack's earlier address, kept so that old links and bookmarks still open it: the same page, whose client-side router sends it on to `/shorts` with the query (`?scope=`) intact. |
| GET | `/collections/{id}` | public, user, no-csrf | — | Same page, for the collection view — one album, as a grid of its posts, with the owner's edit, remove-posts and delete controls. The client-side router owns the path; this route exists so that reloading or bookmarking it is not a 404. |
| GET | `/places/{id}` | public, user, no-csrf | — | Same page, for the place view — the public posts taken at one place, as a grid. The client-side router owns the path; this route exists so that reloading or bookmarking it is not a 404. |
| GET | `/starter-pack/{actor}/{rkey}` | public, user, no-csrf | — | Same page, for a Bluesky starter pack, at the path bsky.app gives it (`actor` a handle or a DID): who is in it, which feeds come with it, and following them. A starter-pack card in a post opens it, and so does a starter-pack address typed into the search. |
| GET | `/settings` | user, no-csrf | — | Same page, for the Settings view — what this app holds about how the reader uses it, which for now is the keyboard shortcuts. The client-side router owns the path; this route exists so that reloading or bookmarking it is not a 404. **Signed-in only**: not a public page, so Nextcloud sends a visitor to its login with the address as `redirect_url`, and back here once signed in. |
| GET | `/search` | public, user, no-csrf | — | Same page, for the Search view with nothing searched yet. The client-side router owns the path; this route exists so that reloading it is not a 404. |
| GET | `/search/{term}` | public, user, no-csrf | `term` (accepted and ignored; the client-side router reads it off the address) | Same page, for the results of one search. Reloading a search, or opening one somebody sent, used to be a 404: the client-side router had the route and the server did not. |
| GET | `/account-deleted` | public, no-csrf | — | Public farewell page shown after a self-registered Aloha Social-only account and its active session have been removed. |
| GET | `/document/get` | user, no-csrf | `id` (required) | Streams a cached document with its stored mime type: a picture, video or sound inline, anything else as a sandboxed `attachment` download. Errors: error envelope, HTTP 500. |
| GET | `/document/public` | public, no-csrf | `id` (required) | Same for documents marked public. |
| GET | `/document/get/resized` | user, no-csrf | `id` (required) | Streams the resized/preview variant. |
| GET | `/document/public/resized` | public, no-csrf | `id` (required) | Same for public documents. |

---

## Async Queue

| Method | Route | Auth | Parameters | Description |
|--------|-------|------|------------|-------------|
| POST | `/async/request/{token}` | public, no-csrf, signed | `token` (path); header `X-Social-Async-Signature` | Internal endpoint the app calls against itself to deliver queued federation requests for `{token}`. The call carries an HMAC of the token under the instance secret (`AsyncRequestSigner`); without a valid one it is a **403** before the queue is read, counted by Nextcloud's brute-force protection — failures only, so the server's own calls are never slowed. With nothing queued it returns an empty HTTP 200. Otherwise it closes the connection (`async()`) and processes standby requests for at most `QueueController::MAX_DURATION` (20 s), the first `ASYNC_ROWS` (40) of them — whatever is left stays standby for the cron — then ends in `exit()`, since the connection is already gone. |

---

## Error Responses

There is no single error format; three shapes exist.

**1. `TNCDataResponse` envelope** (`LocalController`, `ConfigController`, `ActivityPubController`, `OStatusController`, `NavigationController` — everything using the trait):

```json
{"result": {}, "status": 1}
```

on success (`success()`; `more` keys are merged in at the top level), and

```json
{"status": -1, "error": "request failed"}
```

on failure (`fail()`) — the exception class and message go to the log, never into the response, since several callers are public pages. The HTTP status is whatever the caller passed — the default is **500**, callers also use 404, and `Config#remote` deliberately returns the failure envelope with HTTP 200. Failures are logged as warnings unless the caller disables it. The one failure that says more is a reader who has not set up their account here: `failFor()` answers it **403** `{"status": -1, "error": "...", "code": "account-not-set-up", "setup_url": "..."}`, not logged. One related helper bypasses the envelope: `activityPubSuccess()` returns the object as-is with HTTP 200 and `Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams"`.

**2. `MastodonApiController` and `TagController` errors** — a bare object, never the envelope:

```json
{"error": "the access_token was revoked"}
```

from the private `error()` helper of each, which maps the failure to a status a client can act on — see the table below. `TagController` maps the same four cases it can raise: 403 for a token whose scope is too narrow, 401 for no or stale credentials (`Bearer error="invalid_token"`), 422 for something that is not a hashtag, and 500 for anything else — with the message withheld, since these are public routes. Failures raised with no message of their own get a wording that fits the status (`the access_token is invalid`, `not found`, `the request could not be processed`, `request failed`) rather than `{"error": ""}`. `mediaOpen()` is the one route that does not go through it: a missing or non-public document is a 404, any other failure a 400.

Every handler catches `Throwable`, not `Exception`. A `TypeError` — an empty or truncated JSON body was the way to raise one, on seven public endpoints — used to escape as a Nextcloud HTML error page, with a stack trace where debug is on, to a client that can only read JSON.

**3. `OAuthController` errors** — `{"error": "<RFC 6749 name>", "error_description": "..."}` with HTTP 400 (`unsupported_grant_type`, `invalid_request` for a missing code, `invalid_grant`) or HTTP 401 (`invalid_client` for an unknown `client_id`; a wrong secret or a spent code answers with the reason as `error`).

### Client API status codes

`MastodonApiController::error()` keeps Mastodon's `{"error": "..."}` body and maps the failure to a status a client can act on. Every failure used to be a 401, which a client reads as a revoked token: a deleted status, a mistyped timeline name, a database hiccup and a slow remote all logged the reader out of their client.

| Status | When |
|--------|------|
| 401 | No credential, or one that is no longer valid (`ClientNotFoundException`, `AccountDoesNotExistException`). Carries `WWW-Authenticate: Bearer error="invalid_token"`. |
| 403 | A Nextcloud session or app password whose user has not set up their account here (`AccountNotSetUpException`): `{"error", "code": "account-not-set-up", "setup_url"}`, see [Authentication](#authentication). An account that moved away, writing or following from here (`AccountMovedException`): its followers were sent to the new account, so the post or the follow would reach nobody, and Mastodon locks a moved account the same way. Undoing the move lifts it. A valid token whose grant does not cover the route (`InsufficientScopeException`, tested ahead of the list because it extends `ClientException`). Sent **without** `WWW-Authenticate`: PHP rewrites the status of any response carrying that header to 401, so `Bearer error="insufficient_scope"` made every scope refusal arrive as a 401, which a client reads as a dead token and answers by signing the user out. Also a fediverse access rule (`UnauthorizedFediverseException`). |
| 404 | The thing asked for is not here: `StreamNotFoundException`, `CacheActorDoesNotExistException`, `ActorDoesNotExistException`, `ItemNotFoundException`, `CacheDocumentDoesNotExistException`, `HashtagDoesNotExistException`, `ReportNotFoundException`, `FollowNotFoundException`, `InstanceDoesNotExistException`, `OCP\Files\NotFoundException`, and a remote that answered with nothing (`RequestContentException`). |
| 422 | The request was understood and refused, and retrying it unchanged cannot help: `InvalidActionException` (which now also covers a body that claims to be JSON and is not, and a `visibility` this app does not know), `UnknownProbeException`, `InvalidResourceException`, `InvalidResourceEntryException`, `InvalidHandleException`, `ItemUnknownException`, `CacheContentMimeTypeException`, `ClientException`. |
| 429 | `TooManyRequestsException`, and the `#[AnonRateLimit]` / `#[UserRateLimit]` limits on the write, search, account and timeline routes. |
| 502 | Another server let us down: `RequestNetworkException`, `RequestServerException`, `RequestResultNotJsonException`, `RequestResultSizeException`. |
| 500 | Anything unrecognised. The body is always `{"error": "internal server error"}` and the real message is logged with its stack trace — these routes are all `#[PublicPage]`, and echoing `getMessage()` published whatever the failure happened to name. |

Successful Mastodon-compatible responses are **not** wrapped: the client API controllers return the object or array directly with HTTP 200. HTTP status codes in use across the app are 200, 303 (the actor-header and OAuth authorization redirects — `RedirectResponse`'s default), 400, 401, 403, 404, 422, 429, 500, 502 and 503 (a refused inbox delivery whose signature could not be checked); no endpoint returns 201 or 204.


## Numeric status identifiers

Status `nid` values are exposed as decimal strings wherever the API carries IDs or pagination cursors. This preserves their exact value on 32-bit PHP, where generated IDs can be larger than `PHP_INT_MAX`; clients should keep IDs as strings and must not parse them through a fixed-width signed integer. Their numeric order is the timeline order, so `min_id`, `max_id`, and `since_id` continue to work as before.

### ATProto post reply replacement

`com.atproto.repo.putRecord` supports replacing or omitting `reply` on an existing local `app.bsky.feed.post`. Omission removes its parent; unchanged references preserve the existing relationship. Parent access, reply permissions, audience and cycle checks apply before persistence. The Social row and ATProto repository use the existing conditional-write transaction. See [federation compatibility](Federation-Compatibility.md#editing-reply-targets).

### Remote profile synchronization metadata

For an authenticated read of `GET /api/v1/accounts/{account}/statuses` for a
remote ActivityPub actor, `X-Social-Profile-Sync-State` is one of `pending`,
`failed` or `idle`. It describes the background read, not whether the entire
remote account has been indexed. A failed outbox read or queue write remains
visible for a 60-second backoff before normal reads may queue it again. No raw
remote exception is exposed. `X-Social-Profile-Filling` and the existing filling
headers remain backward compatible. Anonymous requests remain cache-only.

An empty first page can continue an existing outbox cursor too, including a
Photos/Videos filter that has not found matching posts yet. The web frontend
keeps cached posts while checking, stops automatic profile polls after their
bounded window, and offers a first-page recheck without clearing or duplicating
those posts. A stalled check is not a declaration that the remote account is empty.

### Event card status metadata

The optional event extension includes lowercase `status` (`confirmed`, `tentative`,
`cancelled`) when the source supplied a recognized iCalendar or Schema.org status.
Unknown values are omitted. ICS downloads include the corresponding STATUS and a
valid LAST-MODIFIED when the post has been updated. Calendar import confirms its
outcome through `imported: true`; `already_imported: true` identifies an existing
stable-UID copy and does not mean that copy was updated. See [Events.md](Events.md)
for timezone, content-warning, import and attendance boundaries.

### Visual media timeline filter

The Social `media_type` extension accepts `visual` in addition to `image`, `video`
and `audio`. It selects posts with photos, videos or animated images, including
native ActivityPub Video objects. It implies media filtering and excludes pure
text, audio and documents before pagination. Existing individual media filters
and unfiltered timeline semantics are unchanged. Photos timeline layouts share
this filter; profile Photos tabs continue to request `image`.
