// Generated by scripts/build-docs.mjs — do not edit by hand.
// Run `npm run docs` after changing content/.

export type DocTocItem = { id: string; text: string; level: number };

export type DocSectionLink = {
  path: string;
  title: string;
  description: string;
  parent: boolean;
};

export type DocPage = {
  slug: string;
  path: string;
  title: string;
  description: string;
  group: string;
  html: string;
  toc: DocTocItem[];
  source: string | null;
  sections: DocSectionLink[] | null;
  anchor: string | null;
  manual: boolean;
  prev: { path: string; title: string } | null;
  next: { path: string; title: string } | null;
  parent: string | null;
};

export type DocCategory = {
  id: string;
  label: string;
  title: string;
  lede: string;
  groups: string[];
};

export type DocGroup = {
  id: string;
  category: string;
  title: string;
  description: string;
  source?: string;
  pages: string[];
};

export const DOC_CATEGORIES: DocCategory[] = [{"id":"users","label":"For users","title":"For users","lede":"Getting an account, your first post, the feeds you read and the settings that keep it calm.","groups":["features","start","user","for-you","notifications","moving","mastodon","atproto"]},{"id":"admins","label":"For administrators","title":"For administrators","lede":"Checks before you federate, moderation, commands, compatibility and what a page costs.","groups":["admin","occ","atproto-live"]},{"id":"developers","label":"For developers","title":"For developers","lede":"The API, the architecture, the protocols, and how the project itself is maintained.","groups":["federation","integrations","events","frontend","evaluation","releasing","api","architecture"]}];

export const DOC_GROUPS: DocGroup[] = [{"id":"features","category":"users","title":"Everything it does","description":"The feature tour from the project README: writing, reading, conversations, your profile, notifications, safety and the rest — one page per topic.","pages":["/docs/feature","/docs/feature-what-it-supports","/docs/feature-integrations-and-documentation","/docs/feature-install","/docs/feature-develop","/docs/feature-license"]},{"id":"start","category":"users","title":"Getting started","description":"Your first hour with Aloha Social: an account, a first post, and the people you want to follow.","pages":["/docs/start","/get-started"]},{"id":"user","category":"users","title":"User guide","description":"Everything a person with an account does in Aloha Social — posting, reading, following, filtering and looking after the account.","source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","pages":["/docs/user","/docs/user-getting-an-account","/docs/user-finding-and-following-people","/docs/user-writing-a-post","/docs/user-following-events-from-gancio","/docs/user-reading","/docs/user-for-you","/docs/user-announcements-from-your-administrators","/docs/user-how-a-post-reads","/docs/user-shorts-that-last-24-hours","/docs/user-collections","/docs/user-posting-as-a-team","/docs/user-a-page-of-your-work","/docs/user-who-is-in-the-photo","/docs/user-who-may-reach-you-and-requests","/docs/user-muting-a-conversation","/docs/user-hiding-a-whole-server","/docs/user-posts-made-with-ai","/docs/user-what-a-post-used-to-say","/docs/user-filtering-out-words","/docs/user-managing-your-account","/docs/user-bluesky","/docs/user-keyboard-shortcuts"]},{"id":"for-you","category":"users","title":"For You feed","description":"How the optional For You feed is built, ranked, administered and kept private.","source":"https://github.com/AlohaSocial/social/blob/master/docs/For-You.md","pages":["/docs/for-you","/docs/for-you-what-readers-see","/docs/for-you-how-the-feed-is-assembled","/docs/for-you-signals-consent-and-privacy","/docs/for-you-api-and-operations","/docs/for-you-evaluation-and-known-limits"]},{"id":"notifications","category":"users","title":"Notifications","description":"What produces a notification, what does not, and how you control it.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Notification-Policy.md","pages":["/docs/notify","/docs/notify-reader-controls","/docs/notify-delivery-and-conversation-mutes","/docs/notify-api-surface","/docs/notify-related-documentation"]},{"id":"moving","category":"users","title":"Moving an account","description":"Coming to Aloha Social from another server, and leaving again without losing the people who follow you.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Moving.md","pages":["/docs/moving","/docs/moving-what-a-move-is-on-the-fediverse","/docs/moving-moving-to-aloha-social","/docs/moving-moving-away","/docs/moving-your-bluesky-account","/docs/moving-if-this-server-goes-away","/docs/moving-what-does-not-move-whatever-you-do"]},{"id":"admin","category":"admins","title":"Administration","description":"Running an Aloha Social server: the checks before you federate, moderation, external users, configuration and scale.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","pages":["/docs/admin","/docs/admin-before-it-federates","/docs/admin-the-setup-checks","/docs/admin-mastodon-apps-cannot-connect","/docs/admin-webfinger-does-not-answer","/docs/admin-the-address-aloha-social-is-set-up-for","/docs/admin-the-delivery-job-has-not-run","/docs/admin-deliveries-are-stuck","/docs/admin-posts-the-index-repairs-skipped","/docs/admin-the-post-tables-keep-growing","/docs/admin-no-memory-cache","/docs/admin-videos-do-not-play-elsewhere","/docs/admin-raising-the-upload-limit","/docs/admin-bluesky","/docs/admin-the-administration-page","/docs/admin-external-users","/docs/admin-moderating","/docs/admin-configuration","/docs/admin-set-by-the-app-not-by-you","/docs/admin-server-settings","/docs/admin-moderation-and-federation","/docs/admin-external-users-2","/docs/admin-per-account","/docs/admin-system-configuration","/docs/admin-commands-by-task","/docs/admin-running-a-large-instance","/docs/admin-what-to-watch","/docs/admin-empty-application-after-installing-development-dependencies","/docs/configuration","/docs/maintenance"]},{"id":"occ","category":"admins","title":"OCC commands","description":"Every command the app adds to occ, grouped by the task it performs.","source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","pages":["/docs/occ","/docs/occ-account-management","/docs/occ-post-note-management","/docs/occ-timeline-and-stream","/docs/occ-queue-management","/docs/occ-social-worker","/docs/occ-social-atproto-serve","/docs/occ-social-atproto-listen","/docs/occ-social-mastodon-stream","/docs/occ-social-atproto-identities","/docs/occ-social-atproto-plc","/docs/occ-social-atproto-resolve","/docs/occ-social-atproto-repo","/docs/occ-social-atproto-block","/docs/occ-social-atproto-crawl","/docs/occ-social-atproto-rotate-key","/docs/occ-social-atproto-keys-reseal","/docs/occ-social-queue-process","/docs/occ-social-queue-status","/docs/occ-social-queue-retry","/docs/occ-development","/docs/occ-cache","/docs/occ-social-cache-refresh","/docs/occ-social-counts-refresh","/docs/occ-social-starter-packs-refresh","/docs/occ-social-media-retry","/docs/occ-social-media-recover","/docs/occ-social-media-posters","/docs/occ-social-team","/docs/occ-social-media-transcode","/docs/occ-social-media-ladder","/docs/occ-social-media-strip-metadata","/docs/occ-social-media-usage","/docs/occ-federation","/docs/occ-external-users","/docs/occ-installation-and-maintenance","/docs/occ-exit-codes","/docs/occ-background-jobs"]},{"id":"mastodon","category":"users","title":"Mastodon compatibility","description":"What a Mastodon client and a migrating administrator can expect, tested against the code rather than claimed.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Mastodon-Compatibility.md","pages":["/docs/mastodon","/docs/mastodon-mastodon-clients","/docs/mastodon-activitypub-federation","/docs/mastodon-moving-accounts","/docs/mastodon-pixelfed-and-other-servers","/docs/mastodon-verification"]},{"id":"atproto","category":"users","title":"Bluesky / AT Protocol","description":"Optional native AT Protocol hosting alongside ActivityPub, including supported records, setup and operational boundaries.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Compatibility.md","pages":["/docs/atproto","/docs/atproto-supported-capabilities","/docs/atproto-how-posting-works","/docs/atproto-deliberate-limits","/docs/atproto-operations-and-verification","/docs/atproto-account-recovery-phrase","/docs/atproto-runtime-configuration-keys","/docs/atproto-protocol-references"]},{"id":"federation","category":"developers","title":"Federation compatibility","description":"Implemented remote profile and content behavior across ActivityPub and AT Protocol.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Federation-Compatibility.md","pages":["/docs/federation","/docs/federation-activitypub-profiles","/docs/federation-bluesky-client-writes","/docs/federation-confirmed-remaining-gaps","/docs/federation-post-detail-presentation"]},{"id":"integrations","category":"developers","title":"Integrations","description":"A practical map of supported protocols, clients, services and their boundaries.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Integrations.md","pages":["/docs/integrations","/docs/integrations-at-a-glance","/docs/integrations-protocol-boundaries","/docs/integrations-what-supported-means"]},{"id":"events","category":"developers","title":"Federated events","description":"Event cards, federated event data and optional Nextcloud Calendar copies.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Events.md","pages":["/docs/events","/docs/events-import-is-not-attendance","/docs/events-remaining-scope","/docs/events-verification"]},{"id":"frontend","category":"developers","title":"Frontend interoperability","description":"Shipped web-client behavior and its practical compatibility limits.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","pages":["/docs/frontend","/docs/frontend-public-profile-presentation-fr-01-fr-02","/docs/frontend-shared-composer-and-progressive-entry-fr-03-revised-interaction","/docs/frontend-remote-profile-synchronization-fr-04-fr-13","/docs/frontend-photos-feed-presentation-fr-01-fr-11","/docs/frontend-continuing-drafts-from-photos","/docs/frontend-composer-attachment-gallery-fr-03-fr-11","/docs/frontend-shorts-playback-fr-11-fr-13","/docs/frontend-optional-explanatory-and-activity-cards","/docs/frontend-completed-stabilization","/docs/frontend-remaining-work-and-dependencies"]},{"id":"atproto-live","category":"admins","title":"Bluesky live-host checks","description":"Distinguish local protocol support from public relay and AppView visibility.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Live-Test.md","pages":["/docs/atproto-live","/docs/atproto-live-before","/docs/atproto-live-from-outside-the-probe","/docs/atproto-live-by-hand","/docs/atproto-live-afterwards"]},{"id":"evaluation","category":"developers","title":"For You evaluation","description":"Reproducible offline evaluation of the recommendation ranker.","source":"https://github.com/AlohaSocial/social/blob/master/docs/ForYouEvaluation.md","pages":["/docs/evaluation","/docs/evaluation-run-it","/docs/evaluation-compared-variants-and-metrics"]},{"id":"releasing","category":"developers","title":"Releasing","description":"Versioning, build, signing and App Store release workflow.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Releasing.md","pages":["/docs/releasing","/docs/releasing-once-before-the-first-release","/docs/releasing-every-release","/docs/releasing-what-the-release-changes-elsewhere","/docs/releasing-when-it-goes-wrong"]},{"id":"api","category":"developers","title":"API reference","description":"The route-by-route reference for the app's registered API.","source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","pages":["/docs/api","/docs/api-contents","/docs/api-overview","/docs/api-authentication","/docs/api-mastodon-compatible-api","/docs/api-instance-and-app-metadata","/docs/api-accounts","/docs/api-search-mastodon-v2","/docs/api-statuses","/docs/api-scheduled-statuses","/docs/api-lists","/docs/api-pixelfeds-own-routes","/docs/api-starter-packs","/docs/api-finding-people-in-other-servers-directories","/docs/api-collections","/docs/api-places","/docs/api-stories","/docs/api-conversations","/docs/api-keyword-filters","/docs/api-discovery-trends-and-relationships","/docs/api-announcements","/docs/api-timelines-and-notifications","/docs/api-followed-hashtags","/docs/api-for-you","/docs/api-polls","/docs/api-link-previews","/docs/api-reports","/docs/api-admin-api-mastodon","/docs/api-media","/docs/api-search-mastodon-adjacent-app-specific-shapes","/docs/api-pagination","/docs/api-peertubes-own-routes","/docs/api-custom-local-api","/docs/api-posts","/docs/api-current-user","/docs/api-account-info","/docs/api-banner","/docs/api-migration","/docs/api-channels","/docs/api-posts-held-for-review","/docs/api-statistics","/docs/api-pixelfeds-administration-routes","/docs/api-config-and-system","/docs/api-moderation-moderators-only","/docs/api-external-users","/docs/api-oauth","/docs/api-activitypub-federation","/docs/api-legacy-ostatus","/docs/api-frontend-document-serving","/docs/api-async-queue","/docs/api-error-responses","/docs/api-numeric-status-identifiers"]},{"id":"architecture","category":"developers","title":"Architecture","description":"The app's data model, routing, services, federation flows and frontend.","source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","pages":["/docs/architecture","/docs/architecture-identifier-width-and-php-32-bit-support","/docs/architecture-introduction","/docs/architecture-directory-structure","/docs/architecture-http-routing","/docs/architecture-database-schema","/docs/architecture-key-services","/docs/architecture-account-and-identity","/docs/architecture-content-and-timelines","/docs/architecture-federation","/docs/architecture-media","/docs/architecture-system","/docs/architecture-mastodon-web-push","/docs/architecture-mastodon-websocket-and-sse-streaming","/docs/architecture-activitypub-federation","/docs/architecture-resuming-bluesky-synchronization","/docs/architecture-actor-identity","/docs/architecture-outgoing-flow","/docs/architecture-incoming-flow","/docs/architecture-peertube-and-federated-video","/docs/architecture-reading-a-timeline-at-scale","/docs/architecture-delivering-at-scale","/docs/architecture-what-a-poll-costs","/docs/architecture-quote-posts","/docs/architecture-whole-conversations","/docs/architecture-who-liked-boosted-or-quoted","/docs/architecture-who-follows-an-account-and-whom-it-follows","/docs/architecture-counts-where-a-post-lives","/docs/architecture-hashtags-and-searches-beyond-this-server","/docs/architecture-hidden-replies","/docs/architecture-who-may-reply","/docs/architecture-bluesky-custom-feeds-and-lists","/docs/architecture-bookmarks-here-and-on-bluesky","/docs/architecture-direct-messages-with-bluesky","/docs/architecture-lists-here-and-on-bluesky","/docs/architecture-switching-off-bluesky","/docs/architecture-shared-lists-to-mute-or-block","/docs/architecture-accounts-this-instance-verified","/docs/architecture-discovery","/docs/architecture-reading-a-timeline","/docs/architecture-frontend-architecture","/docs/architecture-entry-bundles","/docs/architecture-store","/docs/architecture-routes-and-views","/docs/architecture-components","/docs/architecture-direct-messages","/docs/architecture-integration-points","/docs/architecture-replies-as-comments-in-files","/docs/architecture-events-this-app-publishes","/docs/architecture-account-export-and-import","/docs/architecture-external-users","/docs/architecture-security","/docs/architecture-supporting-two-nextcloud-versions","/docs/architecture-keeping-this-document-in-sync"]}];

export const DOC_PAGES: DocPage[] = [{"slug":"feature","path":"/docs/feature","title":"Everything it does","description":"A federated social app for Nextcloud. Post and read across ActivityPub services, and optionally host native AT Protocol accounts, from the same Nextcloud instance.","group":"features","html":"<div align=\"center\"><picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"img/social.svg\">\n  <img src=\"https://raw.githubusercontent.com/AlohaSocial/social/master/img/social-dark.svg\" alt=\"Aloha Social\" width=\"72\">\n</picture><h2 id=\"aloha-social\">Aloha Social</h2>\n<p><strong>A federated social app for Nextcloud.</strong> Post and read across ActivityPub services,\nand optionally host native AT Protocol accounts, from the same Nextcloud instance.</p>\n</div><p><img src=\"https://raw.githubusercontent.com/AlohaSocial/social/master/img/readme/home.png\" alt=\"Aloha Social timeline\"></p>\n<p>Aloha Social gives Nextcloud users a Fediverse identity and connects it to other\nActivityPub servers. Administrators can also enable Bluesky/AT Protocol support.\nThese are separate protocols with separate identities and services; see\n<a href=\"/docs/integrations\">Integrations</a> for what works and where the limits are.</p>\n","toc":[{"id":"aloha-social","text":"Aloha Social","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/README.md","sections":[{"path":"/docs/feature-what-it-supports","title":"What it supports","description":"Supported features: Profiles, follows, posts, replies, edits, deletes, likes, boosts, polls, warnings, media and federated timelines","parent":false},{"path":"/docs/feature-integrations-and-documentation","title":"Integrations and documentation","description":"The feature tour from the project README: writing, reading, conversations, your profile, notifications, safety and the rest — one page per topic.","parent":false},{"path":"/docs/feature-install","title":"Install","description":"For federation, configure a stable public URL, HTTPS, .well-known redirects, outbound HTTPS access and system cron. For Mastodon clients, configure the shipped root API/OAuth web-server…","parent":false},{"path":"/docs/feature-develop","title":"Develop","description":"Integration and browser tests require a running Nextcloud instance; see tests/Integration/README.md and tests/e2e/. To build a release archive, run make appstore.","parent":false},{"path":"/docs/feature-license","title":"License","description":"Aloha Social is licensed under AGPL-3.0-or-later. Third-party assets and dependencies keep their own licenses; see their *.LICENSE.txt files and REUSE.toml.","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/feature-what-it-supports","title":"What it supports"},"parent":null},{"slug":"feature-what-it-supports","path":"/docs/feature-what-it-supports","title":"What it supports","description":"Supported features: Profiles, follows, posts, replies, edits, deletes, likes, boosts, polls, warnings, media and federated timelines","group":"features","html":"<h2 id=\"activitypub\">ActivityPub</h2>\n<p><strong>Supported features: </strong>Profiles, follows, posts, replies, edits, deletes, likes, boosts, polls, warnings, media and federated timelines</p>\n<p>Remote delivery and imports depend on the other server, network access and scheduled Nextcloud jobs.</p>\n<h2 id=\"mastodon-clients\">Mastodon clients</h2>\n<p><strong>Supported features: </strong>A broad Mastodon-compatible API, OAuth, app passwords, media uploads, notifications and timelines</p>\n<p>This is not a full Mastodon replacement. Root <code>/api</code> and <code>/oauth</code> proxy rules are needed for many clients; some optional API features are not implemented.</p>\n<h2 id=\"bluesky-at-protocol\">Bluesky / AT Protocol</h2>\n<p><strong>Supported features: </strong>Optional hosted identities and PDS/XRPC, posts, profiles, follows, likes, custom feeds, lists, starter packs, chat proxying and synchronization</p>\n<p>Requires administrator setup and reachable PLC, relay, AppView and (for chat) chat services. A reachable endpoint does not guarantee indexing or remote availability.</p>\n<h2 id=\"pixelfed\">Pixelfed</h2>\n<p><strong>Supported features: </strong>Federated photo posts and media, profile collections and supported story flows</p>\n<p>Pixelfed-specific app/API behavior is partial; it is not a complete Pixelfed server replacement.</p>\n<h2 id=\"peertube\">PeerTube</h2>\n<p><strong>Supported features: </strong>Read and publish federated video posts, channels, playback and video metadata</p>\n<p>PeerTube&#39;s complete creator, moderation and administration APIs are outside scope. Video processing depends on server configuration.</p>\n<h2 id=\"events\">Events</h2>\n<p><strong>Supported features: </strong>ActivityPub event cards and one-click import to Nextcloud Calendar where available</p>\n<p>Calendar import copies an event; it is not an RSVP or attendance action.</p>\n<h2 id=\"other-fediverse-services\">Other Fediverse services</h2>\n<p><strong>Supported features: </strong>Compatible ActivityPub profiles, posts and interactions; recognized Articles, Pages, audio, video, polls and events</p>\n<p>Rendering and actions depend on the remote server&#39;s object types and extensions. Lemmy/PieFed community moderation and voting are not full-featured here.</p>\n<p>The web app also includes home, local and federated timelines, Photos and Videos\nfeeds, Shorts, search, lists, notifications, moderation controls and an optional\nFor You feed. See the <a href=\"/docs/user\">user guide</a> for the web experience.</p>\n","toc":[{"id":"activitypub","text":"ActivityPub","level":2},{"id":"mastodon-clients","text":"Mastodon clients","level":2},{"id":"bluesky-at-protocol","text":"Bluesky / AT Protocol","level":2},{"id":"pixelfed","text":"Pixelfed","level":2},{"id":"peertube","text":"PeerTube","level":2},{"id":"events","text":"Events","level":2},{"id":"other-fediverse-services","text":"Other Fediverse services","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/README.md","sections":null,"anchor":"what-it-supports","manual":false,"prev":{"path":"/docs/feature","title":"Everything it does"},"next":{"path":"/docs/feature-integrations-and-documentation","title":"Integrations and documentation"},"parent":null},{"slug":"feature-integrations-and-documentation","path":"/docs/feature-integrations-and-documentation","title":"Integrations and documentation","description":"The feature tour from the project README: writing, reading, conversations, your profile, notifications, safety and the rest — one page per topic.","group":"features","html":"<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Document</th>\n<th>Use it for</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><a href=\"/docs/integrations\">Integration support matrix</a></td>\n<td>Supported networks, data flows, dependencies and known limits</td>\n</tr>\n<tr>\n<td><a href=\"/docs/user\">User guide</a></td>\n<td>Posting, reading, accounts, settings and everyday use</td>\n</tr>\n<tr>\n<td><a href=\"/docs/admin\">Administration</a></td>\n<td>Setup checks, federation, Bluesky, media, moderation and configuration</td>\n</tr>\n<tr>\n<td><a href=\"/docs/api\">API reference</a></td>\n<td>Mastodon-compatible, local and Bluesky/XRPC endpoints</td>\n</tr>\n<tr>\n<td><a href=\"/docs/federation\">ActivityPub compatibility</a></td>\n<td>Remote profile import behavior and known federation boundaries</td>\n</tr>\n<tr>\n<td><a href=\"/docs/mastodon\">Mastodon compatibility</a></td>\n<td>Client API coverage and intentional differences</td>\n</tr>\n<tr>\n<td><a href=\"/docs/atproto\">AT Protocol compatibility</a></td>\n<td>PDS/XRPC behavior, identity and protocol limits</td>\n</tr>\n<tr>\n<td><a href=\"/docs/events\">Events and Calendar</a></td>\n<td>Event cards, ICS import and supported behavior</td>\n</tr>\n<tr>\n<td><a href=\"/docs/for-you\">For You</a></td>\n<td>Recommendation design, privacy and controls</td>\n</tr>\n<tr>\n<td><a href=\"/docs/architecture\">Architecture</a></td>\n<td>Services, storage, queues and protocol flows</td>\n</tr>\n<tr>\n<td><a href=\"/docs/performance\">Performance</a></td>\n<td>Current CI query measurements and benchmark limits</td>\n</tr>\n<tr>\n<td><a href=\"/docs/debt\">Technical debt</a></td>\n<td>Current maintenance inventory and priorities</td>\n</tr>\n<tr>\n<td><a href=\"/docs/occ\">OCC commands</a></td>\n<td>Command-line administration and maintenance</td>\n</tr>\n<tr>\n<td><a href=\"https://github.com/AlohaSocial/social/blob/master/SECURITY.md\">Security policy</a></td>\n<td>Reporting a security issue</td>\n</tr>\n</tbody></table></div>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/README.md","sections":null,"anchor":"integrations-and-documentation","manual":false,"prev":{"path":"/docs/feature-what-it-supports","title":"What it supports"},"next":{"path":"/docs/feature-install","title":"Install"},"parent":null},{"slug":"feature-install","path":"/docs/feature-install","title":"Install","description":"For federation, configure a stable public URL, HTTPS, .well-known redirects, outbound HTTPS access and system cron. For Mastodon clients, configure the shipped root API/OAuth web-server…","group":"features","html":"<p>Aloha Social supports Nextcloud <strong>34–36</strong> and PHP <strong>8.3–8.5</strong>. Install it from\nthe Nextcloud App Store, or place the app in the Nextcloud <code>apps/</code> directory and\nenable it with <code>occ app:enable social</code>. Then run the setup check:</p>\n<pre><code class=\"language-sh\">occ social:check:install\n</code></pre>\n<p>For federation, configure a stable public URL, HTTPS, <code>.well-known</code> redirects,\noutbound HTTPS access and system cron. For Mastodon clients, configure the\n<a href=\"https://github.com/AlohaSocial/social/blob/master/contrib/webserver/\">shipped root API/OAuth web-server rules</a>. Bluesky hosting\nis optional and has additional requirements. Follow <a href=\"/docs/admin\">Admin.md</a> before exposing a\nnew instance publicly.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/README.md","sections":null,"anchor":"install","manual":false,"prev":{"path":"/docs/feature-integrations-and-documentation","title":"Integrations and documentation"},"next":{"path":"/docs/feature-develop","title":"Develop"},"parent":null},{"slug":"feature-develop","path":"/docs/feature-develop","title":"Develop","description":"Integration and browser tests require a running Nextcloud instance; see tests/Integration/README.md and tests/e2e/. To build a release archive, run make appstore.","group":"features","html":"<pre><code class=\"language-sh\">composer install\nnpm ci\nnpm run build\n</code></pre>\n<p>Enable the app in a development Nextcloud instance. Frontend watch mode is\n<code>npm run watch</code>. Useful checks are:</p>\n<pre><code class=\"language-sh\">composer run test:unit\nnpm test\nnpm run lint\nnpm run stylelint\nnpm run typecheck\n</code></pre>\n<p>Integration and browser tests require a running Nextcloud instance; see\n<a href=\"/docs/feature\"><code>tests/Integration/README.md</code></a> and\n<a href=\"https://github.com/AlohaSocial/social/blob/master/tests/e2e/\"><code>tests/e2e/</code></a>. To build a release archive, run <code>make appstore</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/README.md","sections":null,"anchor":"develop","manual":false,"prev":{"path":"/docs/feature-install","title":"Install"},"next":{"path":"/docs/feature-license","title":"License"},"parent":null},{"slug":"feature-license","path":"/docs/feature-license","title":"License","description":"Aloha Social is licensed under AGPL-3.0-or-later. Third-party assets and dependencies keep their own licenses; see their *.LICENSE.txt files and REUSE.toml.","group":"features","html":"<p>Aloha Social is licensed under <a href=\"https://github.com/AlohaSocial/social/blob/master/LICENSES/AGPL-3.0-or-later.txt\">AGPL-3.0-or-later</a>.\nThird-party assets and dependencies keep their own licenses; see their\n<code>*.LICENSE.txt</code> files and <a href=\"https://github.com/AlohaSocial/social/blob/master/REUSE.toml\"><code>REUSE.toml</code></a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/README.md","sections":null,"anchor":"license","manual":false,"prev":{"path":"/docs/feature-develop","title":"Develop"},"next":null,"parent":null},{"slug":"start","path":"/docs/start","title":"Getting started with Aloha Social","description":"The good guide for your first day: an account, a first post, the people you want to follow, and the few settings worth changing straight away.","group":"start","html":"<p>Everything on this page happens in the Aloha Social app inside your workspace. If your organisation has not set up Aloha Social yet, the <a href=\"/install\">installation guide</a> is the page to send your administrator — it takes about ten minutes.</p>\n<h2 id=\"before-you-start\">Before you start</h2>\n<p>You need an Aloha account on a server that runs Aloha Social. That is the whole requirement: the same login, the same password, the same two-factor authentication you already use for files, calendar and chat. There is no second account to create and no separate password to remember.</p>\n<p>Open the app menu in Aloha and choose <strong>Aloha Social</strong>. The first screen asks whether you want a fediverse identity here. Nothing is created until you answer.</p>\n<h2 id=\"step-1-pick-your-handle\">Step 1 — Pick your handle</h2>\n<p>Your address will be <code>@handle@your.cloud</code>. The handle is suggested from your user name and accepts letters, digits, underscore, dot and dash.</p>\n<p>Pick it carefully: <strong>the handle cannot be changed later.</strong> Your display name and avatar come from your Aloha account and can be changed there whenever you like.</p>\n<p>Where the administrator allows open registration, the login page also has a <strong>Create an account</strong> button for people who are not Aloha users yet. Such an account is for Aloha Social only.</p>\n<h2 id=\"step-2-take-the-four-step-introduction\">Step 2 — Take the four-step introduction</h2>\n<p>On your first visit the app shows four short screens:</p>\n<ol>\n<li>your address, with a copy button for it;</li>\n<li>people to follow;</li>\n<li>a way to bring the follows you already have from another server;</li>\n<li>a button that puts you in the composer.</li>\n</ol>\n<p>Every step can be skipped. Once closed it stays closed, and <strong>Settings → Help → Introduction</strong> shows it again.</p>\n<h2 id=\"step-3-follow-a-handful-of-people\">Step 3 — Follow a handful of people</h2>\n<p>A timeline with nobody in it tells you nothing. The introduction offers a starting set, and <a href=\"/docs/user-finding-and-following-people\">Discover</a> searches across several fediverse directories at once — the results name which directory answered, so a short list is never mistaken for an empty fediverse.</p>\n<p>Three things worth knowing:</p>\n<ul>\n<li><strong>Starter packs</strong> follow a whole named group of accounts with one click. Your administrator curates the ones for this server.</li>\n<li><strong>Colleagues are suggested</strong> from the workspace you share, so the people you already work with are the first results.</li>\n<li><strong>Followed hashtags</strong> work like a subscription: follow <code>#photography</code> and those posts arrive in your timeline without anybody following anybody.</li>\n</ul>\n<h2 id=\"step-4-write-your-first-post\">Step 4 — Write your first post</h2>\n<p>Open the composer and write. The four things worth deciding on that first post:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Decision</th>\n<th>What it does</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><strong>Audience</strong></td>\n<td>Public, unlisted, followers-only or direct. A reply inherits the audience of the post it answers.</td>\n</tr>\n<tr>\n<td><strong>Content warning</strong></td>\n<td>Collapses the post behind a line of your choosing.</td>\n</tr>\n<tr>\n<td><strong>Alt text</strong></td>\n<td>The composer asks before a picture without a description goes out. A nudge, never a refusal.</td>\n</tr>\n<tr>\n<td><strong>Language</strong></td>\n<td>Labels the post so readers and translation know what to expect.</td>\n</tr>\n</tbody></table></div>\n<p>Anything up to 120 characters can go out drawn big on colour as a short text post. Pictures, video, polls, files and scheduled posts all live behind the same toolbar — see the <a href=\"/features/write\">Write feature page</a>.</p>\n<h2 id=\"step-5-change-these-four-settings\">Step 5 — Change these four settings</h2>\n<p>Everything works with the defaults, but these four are worth two minutes:</p>\n<ol>\n<li><strong>Settings → Appearance</strong> — light, dark, or follow your device. The dark design is the same design, not an afterthought.</li>\n<li><strong>Settings → Notifications → Who may reach you</strong> — five questions, each answered <em>Allow</em> or <em>Hold for review</em>. New accounts start with the calm policy: strangers and brand-new accounts wait quietly instead of ringing the bell.</li>\n<li><strong>Settings → Filters</strong> — add the words you would rather not see. Filters fold matching posts behind the filter&#39;s name or take them out altogether.</li>\n<li><strong>Settings → For you</strong> — the optional ranked feed. Recommendations explain why they appear; behavioral learning has its own consent control, and learned data is account-scoped and not federated.</li>\n</ol>\n<h2 id=\"where-to-go-next\">Where to go next</h2>\n<ul>\n<li><a href=\"/docs/user\">The full user guide</a> — posting, reading, following, filtering and your account, topic by topic.</li>\n<li><a href=\"/docs/user-keyboard-shortcuts\">Keyboard shortcuts</a> — <code>j</code>, <code>k</code>, <code>l</code>, <code>f</code>, <code>b</code>, and <code>?</code> for the whole list.</li>\n<li><a href=\"/docs/moving\">Moving an account</a> — bringing your posts and follows from another server.</li>\n<li><a href=\"/clients\">Apps and downloads</a> — the web app today, and the apps for iPhone, Android and desktop.</li>\n</ul>\n","toc":[{"id":"before-you-start","text":"Before you start","level":2},{"id":"step-1-pick-your-handle","text":"Step 1 — Pick your handle","level":2},{"id":"step-2-take-the-four-step-introduction","text":"Step 2 — Take the four-step introduction","level":2},{"id":"step-3-follow-a-handful-of-people","text":"Step 3 — Follow a handful of people","level":2},{"id":"step-4-write-your-first-post","text":"Step 4 — Write your first post","level":2},{"id":"step-5-change-these-four-settings","text":"Step 5 — Change these four settings","level":2},{"id":"where-to-go-next","text":"Where to go next","level":2}],"source":null,"sections":[],"anchor":null,"manual":false,"prev":null,"next":null,"parent":null},{"slug":"user","path":"/docs/user","title":"User guide","description":"How to use Aloha Social as a person with an account on this Nextcloud: getting onto the fediverse, following people, writing and reading posts, and looking after the account. It describes…","group":"user","html":"<p><strong>Reviewed against:</strong> Aloha Social <strong>0.26.279</strong> on <strong>2026-10-27</strong>.</p>\n<p>How to use Aloha Social as a person with an account on this Nextcloud:\ngetting onto the fediverse, following people, writing and reading posts, and\nlooking after the account. It describes the web client that comes with the\napp; where something is only reachable through the Mastodon-compatible API or\na Mastodon client, it says so.</p>\n<p>This guide describes the current web experience represented by this checkout.\nMenu and button names are the English strings of the web client. Federation,\nthird-party client and deployment behavior can vary; see\n<a href=\"/docs/integrations\">Integrations.md</a> and <a href=\"/docs/admin\">Admin.md</a> for those limits.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":[{"path":"/docs/user-getting-an-account","title":"Getting an account","description":"A Nextcloud account is the account: the first time you open Aloha from the app menu, a short screen asks whether you want a fediverse identity here, or would rather name the one you…","parent":false},{"path":"/docs/user-finding-and-following-people","title":"Finding and following people","description":"Everything a person with an account does in Aloha Social — posting, reading, following, filtering and looking after the account.","parent":false},{"path":"/docs/user-writing-a-post","title":"Writing a post","description":"New post at the top of the sidebar, the compact post field on a feed or profile, or n opens the shared composer. The compact field sends a simple text post directly; expand it to open the…","parent":false},{"path":"/docs/user-following-events-from-gancio","title":"Following events from Gancio","description":"Gancio publishes events over ActivityPub from one instance-wide account. Search for and follow that account from Social: it is usually @events@gancio.example on Gancio 1.24 and newer, or…","parent":false},{"path":"/docs/user-reading","title":"Reading","description":"The browser tab names the page you are on — the feed, the account, the author of the post, Settings — in front of the app's name, so the history and a screen reader can tell the pages…","parent":false},{"path":"/docs/user-for-you","title":"For you","description":"For You is an optional ranked feed beside My Feed and the local and global timelines. The administrator can enable it. It combines relevant posts already known to this server with bounded…","parent":true},{"path":"/docs/user-announcements-from-your-administrators","title":"Announcements from your administrators","description":"When the administrators of this Nextcloud post a notice — a maintenance window, a move, a new rule — it appears at the top of the timeline, above the composer, on every page except a…","parent":true},{"path":"/docs/user-how-a-post-reads","title":"How a post reads","description":"A feed is a column of posts separated by thin lines, not a stack of boxes, narrow enough that a line of text is easy to follow back to its start (the photo and video grids keep the wider…","parent":true},{"path":"/docs/user-shorts-that-last-24-hours","title":"Shorts that last 24 hours","description":"A short you post for 24 hours is one picture, video or card of words that the people who follow you can see for a day, and then it is gone. It is not on your profile and nobody else can…","parent":true},{"path":"/docs/user-collections","title":"Collections","description":"A profile has a Collections tab beside Posts, Photos, Videos and Tagged: the account's albums. Each is a page of the posts the owner gathered into it, drawn as the same grid of squares the…","parent":true},{"path":"/docs/user-posting-as-a-team","title":"Posting as a team","description":"If an administrator has given one of your Nextcloud groups an account, a small picker appears in the composer beside the language and the audience: As myself, or the team. Choose the team…","parent":true},{"path":"/docs/user-a-page-of-your-work","title":"A page of your work","description":"Settings → Profile and privacy → Portfolio makes a page with its own address, to put on a CV. A profile is a feed: everything you posted, newest first, with the follow button and the…","parent":true},{"path":"/docs/user-who-is-in-the-photo","title":"Who is in the photo","description":"Open one of your own posts with a picture in it, choose Tag people from its menu (…), and type the handles of the people in it, separated by commas. Their names appear under the post…","parent":true},{"path":"/docs/user-who-may-reach-you-and-requests","title":"Who may reach you, and requests","description":"Held people can still write to you. Their posts, likes and follows wait in Activities until you look; they do not ring, push or mail. Everything a held person does waits together —…","parent":true},{"path":"/docs/user-muting-a-conversation","title":"Muting a conversation","description":"Mute conversation stops the notifications one thread would give you without muting anybody. It is in every post's menu, and in the menu of a mention or reply card in Activities. The mute…","parent":true},{"path":"/docs/user-hiding-a-whole-server","title":"Hiding a whole server","description":"Settings → Blocking now has a third list: the servers you have hidden. Hiding one hides every account on it and everything they post, and takes your follows in both directions with it. It…","parent":true},{"path":"/docs/user-posts-made-with-ai","title":"Posts made with AI","description":"Settings → Blocking has a switch, Hide posts made with AI, off until you turn it on. On, a post that says it was made with AI is kept out of everything you read — your feed, the public…","parent":true},{"path":"/docs/user-what-a-post-used-to-say","title":"What a post used to say","description":"A post that has been edited says so under it. That line is a button now: it opens every version, oldest first, with the content warning and the pictures each one carried. A reader who has…","parent":true},{"path":"/docs/user-filtering-out-words","title":"Filtering out words","description":"Some words are not worth reading. Blocking → Filtered words is where you say so — with the accounts you have blocked and muted and the servers you have hidden, because it is the same…","parent":false},{"path":"/docs/user-managing-your-account","title":"Managing your account","description":"(in the account menu at the foot of the sidebar) has six groups: Profile and privacy, Reading, Notifications, Your posts, Apps and account and Help. Pick a group on the left (at the top on…","parent":false},{"path":"/docs/user-bluesky","title":"Bluesky","description":"If the administrator has switched Bluesky on, your account is a Bluesky account too, hosted here: your handle there is yourname.<this server>, and anybody on Bluesky who looks it up sees…","parent":true},{"path":"/docs/user-keyboard-shortcuts","title":"Keyboard shortcuts","description":"Press ? anywhere, or open Settings → Help → Keyboard shortcuts, for the list. Shortcuts are off while you are typing in a field or the composer, while a modifier key is held, and while a…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/user-getting-an-account","title":"Getting an account"},"parent":null},{"slug":"user-getting-an-account","path":"/docs/user-getting-an-account","title":"Getting an account","description":"A Nextcloud account is the account: the first time you open Aloha from the app menu, a short screen asks whether you want a fediverse identity here, or would rather name the one you…","group":"user","html":"<p>A Nextcloud account is the account: the first time you\nopen <strong>Aloha</strong> from the app menu, a short screen asks whether you want a\nfediverse identity here, or would rather name the one you already have\nsomewhere else. Nothing is created until you choose. You pick your handle on\nthat screen — it starts out as a suggestion made from your Nextcloud user id,\nmay use letters, digits and underscore with dot and dash inside, and <strong>cannot\nbe changed later</strong> — and your address is <code>@handle@your-nextcloud-host</code>. Anyone\non Mastodon, Pixelfed, PeerTube or any other server that speaks ActivityPub can\nfollow it. Where the administrator has Bluesky switched on, the screen also\nshows the Bluesky address the account gets, <code>@handle.your-nextcloud-host</code>, as\nBluesky writes it: small letters, digits and dashes only, so <code>Frank_K</code> becomes\n<code>frank-k</code>, and a handle starting with a digit gets <code>u-</code> in front. If another\naccount here already has that Bluesky address, a number is added to it.</p>\n<p><strong>Link an existing account</strong> creates nothing here: it writes the address you\nalready have elsewhere into your Nextcloud profile, so the people on this\nNextcloud can find you. The screen then says it is done and offers <strong>Back to\nNextcloud</strong>; opening Aloha Social again shows the same choice with a note of the\naccount you linked, so you can still create an account here later.</p>\n<p>Your display name and avatar come from your Nextcloud account and are changed\nthere. The rest of the profile — banner, bio, profile fields — is edited in\nAloha Social (see <a href=\"/docs/user-managing-your-account#managing-your-account\">Managing your account</a>).</p>\n<p>On the first visit the app shows a four-step introduction: your address with a\ncopy button (and your Bluesky address under it, where the account has one), people to follow, a way to bring the follows you already have from\nanother server, and a button that puts you in the composer. Every step can be\nskipped; once closed it stays closed, and <strong>Settings → Help → Introduction</strong> shows it\nagain.</p>\n<h2 id=\"signing-in-from-an-app-for-the-first-time\">Signing in from an app for the first time</h2>\n<p>You can start with an app on your phone or computer instead of the web page:\na Mastodon app, or a Bluesky app where the administrator has Bluesky switched\non. The app opens a sign-in page in your browser, and after you log in to\nNextcloud that page first asks you to choose your username, with the same\nrules and the same address preview as the screen above. <strong>Create account</strong>\nmakes your account, and the page goes straight on to asking whether to let\nthe app in. <strong>Cancel</strong> sends you back to the app, and nothing is created.\nLinking an account you have somewhere else is not offered there: the app\nneeds an account on this server to sign in to.</p>\n<p>An app that signs in with a Nextcloud app password instead is told, until you\nhave an account here, that your account is not set up yet, with the address\nof the setup page: open it in a browser, choose your username, and try the\napp again.</p>\n<h2 id=\"registering-without-a-nextcloud-account\">Registering without a Nextcloud account</h2>\n<p>Where the administrators allow it, the login page has a <strong>Create an account</strong>\nbutton, and an invitation link from somebody here leads to the same form. The\nusername you choose is your handle, so the same rules apply, and your address\nis <code>@username@your-nextcloud-host</code> from the start; where Bluesky is switched\non, the form shows the Bluesky address it gets as well. Depending on the server you\nconfirm your email address first, and an administrator may look at the\nregistration before it becomes an account; you are emailed either way.</p>\n<p>Such an account is for Aloha Social only. You log in on the normal login page, with\ntwo-factor authentication if you set it up or the server requires it, and\nland in Aloha Social. Your personal settings for your details, password, security,\nappearance and notifications are there; Files, Talk and the other apps are\nnot, and Nextcloud&#39;s own desktop and mobile clients are refused. Mastodon apps\ncan. <strong>Settings → Apps and account → Your storage</strong> shows how much of the space the server gives\neach such account your pictures and videos take up. Deleting your Aloha Social\naccount deletes the whole account.</p>\n<p>Where the administrators let everybody invite people, <strong>Settings → Apps and account → Invite\npeople</strong> makes an invitation link: it works once and for a week.</p>\n","toc":[{"id":"signing-in-from-an-app-for-the-first-time","text":"Signing in from an app for the first time","level":2},{"id":"registering-without-a-nextcloud-account","text":"Registering without a Nextcloud account","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"getting-an-account","manual":false,"prev":{"path":"/docs/user","title":"User guide"},"next":{"path":"/docs/user-finding-and-following-people","title":"Finding and following people"},"parent":null},{"slug":"user-finding-and-following-people","path":"/docs/user-finding-and-following-people","title":"Finding and following people","description":"Everything a person with an account does in Aloha Social — posting, reading, following, filtering and looking after the account.","group":"user","html":"<ul>\n<li><strong>Search.</strong> The search box at the top of the sidebar looks through the\npeople, hashtags and posts this server knows. Somebody this server has never\nmet is found by their full handle, <code>@someone@example.org</code> — or, where this\nserver is connected to Bluesky, <code>@someone.example.com</code> — or a profile or post\nlink: press <strong>Enter</strong>, or <strong>Look up</strong> under the heading, and their own server\nis asked. While you type, only this server is searched. When nobody is\nthere, the page says so.</li>\n<li><strong>Discover</strong> (in the sidebar) has five tabs: <strong>People</strong> (suggestions, with\nthe people who share your Nextcloud and have said where they are on the\nfediverse listed first under <em>On your Nextcloud</em>), <strong>Starter packs</strong>,\n<strong>Pictures</strong> and <strong>Videos</strong> being looked at, and <strong>Hashtags</strong> that are\ntrending, ranked over a window you pick.</li>\n<li><strong>Your island and its neighbours</strong> opens the People tab: a map of the\nfediverse as islands. Your own server is in the middle, with your picture on\nit. Around it is an island for each server you follow people on (up to\neight, larger where you follow more people), each joined to yours by a canoe\nroute, and the sentence under the map says how many there are.</li>\n<li><strong>Find people across the fediverse</strong> comes next on the People tab. Type a\nname, a handle or a subject and this server asks several directories at once —\nits own first, then the ones its administrator configured — and offers a\n<strong>Follow</strong> on every row. Pick one directory with the buttons under the box to\nask only that one. Servers that did not answer are named under the results, so\na short list is never mistaken for an empty fediverse. Somebody this server\nalready knows opens here; a stranger opens on their own server. Somebody who\nis in none of these directories is found by their full handle in the search\nat the top of the sidebar.</li>\n<li><strong>Look at who they follow</strong>, on the People tab, suggests the people the\npeople you follow follow. Once it has answered, <strong>Constellation</strong> shows the\nsame suggestions as a small sky: you in the middle, the people you follow who\nled somewhere around you, and the suggestions at the edge, tied to whoever\nthey came through. It settles by itself; drag a star anywhere and it stays\nthere, and press one to follow. <strong>List</strong> puts it back. Every star is a\nbutton that says who it is and why, so a keyboard gets there too.</li>\n<li><strong>Starter packs</strong> are named handfuls of accounts. Open one to see who is in\nit: everybody you do not follow yet has a <strong>Follow</strong> of their own, and one\nbutton follows them all, counting as it goes, asking first when that is more\nthan ten people, and saying how many could not be followed. Once you follow\neverybody it says so. Two ship with the app — the projects behind the\nnetwork, and photography — and an administrator can curate more. The\ncollections curators publish on Mastodon and the starter packs Bluesky\nsuggests are starter packs here too, and open the same way: they say who\ncurated them, link to where they live, and are read again every day. An\nopened pack shows the people this server already knows; anybody it has not\nmet yet is looked up in the background and is there the next time you open\nthe pack, and following everybody follows them either way. Accounts your\nadministrator has blocked or limited are never offered.</li>\n<li><strong>Follow</strong> on a profile, in search results or on a Discover card sends a\nfollow request. On an open account it is accepted at once; on a locked\naccount the button reads <strong>Requested</strong> until the owner answers. <strong>Unfollow</strong>\nasks you to confirm, because on a locked account you would have to ask\nagain.</li>\n<li><strong>Followed hashtags.</strong> A hashtag timeline (<code>#tag</code> in a post, or a trending\ntag) has a follow button; following a tag puts the <em>public</em> posts carrying\nit into your home feed. It is not a relationship with anybody, and the tags\nyou follow are listed above any hashtag timeline.</li>\n<li><strong>Coming from another server?</strong> Every Mastodon-like server exports the\npeople you follow as <code>following_accounts.csv</code>, and Pixelfed as\n<code>pixelfed-following.json</code>. Upload it in the first-run\nintroduction or on the <strong>Migration</strong> page and each account is followed\nagain from here.</li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"finding-and-following-people","manual":false,"prev":{"path":"/docs/user-getting-an-account","title":"Getting an account"},"next":{"path":"/docs/user-writing-a-post","title":"Writing a post"},"parent":null},{"slug":"user-writing-a-post","path":"/docs/user-writing-a-post","title":"Writing a post","description":"New post at the top of the sidebar, the compact post field on a feed or profile, or n opens the shared composer. The compact field sends a simple text post directly; expand it to open the…","group":"user","html":"<p><strong>New post</strong> at the top of the sidebar, the compact post field on a feed or\nprofile, or <code>n</code> opens the shared composer. The compact field sends a simple\ntext post directly; expand it to open the full popup for attachments, polls,\nevents, warnings, scheduling and other options. Replies use the same compact\nentry and popup with the reply context. An empty composer greets you by first\nname: &quot;Aloha, Frank. What’s new?&quot; A post may be up to\n5,000 characters, content warning included. What is in the composer is kept\nas a draft across a failed post, a reload or leaving the page: the words, the\ncontent warning, the audience, the language, who may reply, the team account\nyou write as, the poll, the time it is scheduled for, the place, a video&#39;s\ntitle and a card. Attachments are kept too, with their descriptions, focal\npoints and filters. When the draft comes back the server is asked about each\nattachment again; one it has cleared away in the meantime is taken off, and a\nshort message says so. An attachment that is still uploading cannot be kept\nyet, so leaving the page while one is on its way asks you first. A draft is\nkept for a week, for your account only. A reply keeps its own draft, under the\npost it answers, and so does a quote, so starting one does not take the place\nof a post you were still writing.\n<strong>Ctrl+Enter</strong> (<strong>⌘+Enter</strong> on a Mac) sends from the full composer. Closing the\npopup preserves the draft; unsaved edits and unfinished uploads ask before\ndiscarding. <strong>Escape</strong> closes the popup subject to that protection.</p>\n<ul>\n<li><p><strong>Visibility</strong> is chosen with the globe menu next to the post button. The\nchoice decides who receives the post on the fediverse, not only who sees it\nhere:</p>\n<ul>\n<li><strong>Public</strong> — visible to everyone; appears in the Local and Global\ntimelines of every server it reaches, and on your profile to anyone.</li>\n<li><strong>Unlisted</strong> — visible to everyone who has the link or follows you, but\nkept out of public timelines and discovery features.</li>\n<li><strong>Followers</strong> — delivered to your followers only. It cannot be boosted,\npinned or quoted, because those would carry it to people it was not\nwritten for.</li>\n<li><strong>Direct message</strong> — delivered to the people mentioned in it and nobody\nelse. The button will not send a direct post without at least one\n<code>@mention</code>.</li>\n</ul>\n<p>Where your account is on Bluesky, Unlisted, Followers and Direct message\nsay <em>Not on Bluesky</em> in the menu: only a public post goes there, so people\nwho follow you from Bluesky do not see the others.</p>\n</li>\n<li><p><strong>Mentions and hashtags.</strong> Type <code>@</code> and the first letters of a name to pick\nan account, or <code>#</code> for a hashtag; both are also recognised when typed in\nfull. A mention makes that person a recipient of the post; a hashtag makes\nthe post part of that tag&#39;s timeline everywhere it is delivered.</p>\n</li>\n<li><p><strong>Content warning.</strong> The speech-bubble button adds a warning field. Readers\nsee the warning and a <strong>Show more</strong> button; the body stays out of the page\nuntil they ask. Attachments on a post with a warning are treated as\nsensitive. Warnings written on other servers are honoured here the same way.</p>\n</li>\n<li><p><strong>Attachments.</strong> Up to ten per post: pictures (JPEG, PNG, GIF, WebP, AVIF,\nand HEIC/HEIF from a phone, converted on the way in), video (MP4, WebM,\nQuickTime) and audio (MP3, AAC, OGG/Opus, WAV, FLAC). A video other\nservers cannot play as it is gets converted before the post leaves: it is\non this server straight away, and your own copy says <em>Converting video —\nreaches other servers when done</em> until it has. Drag them in, use\n<strong>Add attachment</strong>, or <strong>Add from Files</strong> to attach something already in\nyour Nextcloud without uploading it again — the Files app&#39;s own menu also\nhas <strong>Share to Aloha Social</strong> for the same thing. Attachments show under the\nbox you write in. Every picture has its Exif\nmetadata (including the location a phone writes) removed before it is\nstored or sent anywhere. A picture can be given one of eight mild filters,\npreviewed live and baked into the copy that is posted when you press Post,\nin every browser, Safari and iPhone included. A photo larger than 4096 pixels\non its longest side, or larger than the size your server takes, is made\nsmaller before it is uploaded. Animated GIFs and WebPs are never changed, so\none that is too large is refused before it is sent. A video has its own,\nlarger ceiling, and one over it is refused before it is sent too — the\nmessage names the size your server takes. When the server itself refuses an\nupload, its reason is what you are shown.</p>\n</li>\n<li><p><strong>The GIF button</strong> opens a picker with 881 animated emoji in it, searchable by\nname — &quot;party&quot;, &quot;sad&quot;, &quot;hedgehog&quot; — plus whatever your administrator has added\nfor this instance, which comes first. Nothing you type goes anywhere but your\nown Nextcloud, and neither does your browser: your server keeps its own copy of\nevery picture it has been asked for. Picking one attaches it to the post you are\nwriting, exactly as though you had uploaded it.</p>\n</li>\n<li><p><strong>Alt text.</strong> Each attachment has a <strong>Describe this for people who cannot\nsee it</strong> field. Posting with an undescribed attachment shows a nudge, never\na refusal.</p>\n</li>\n<li><p><strong>Polls.</strong> <strong>Add poll</strong> gives two to four options, a <strong>Multiple choice</strong>\nswitch and a duration from 30 minutes to 7 days. Readers on any server\nvote; the totals come back and are shown under the poll, with when it\ncloses or that it has.</p>\n</li>\n<li><p><strong>Emoji.</strong> The smiley opens a Unicode emoji picker. A custom emoji this\ninstance publishes is written by its shortcode, <code>:name:</code>, and renders here\nand on other servers.</p>\n</li>\n<li><p><strong>Send it later.</strong> The clock button turns <strong>Post</strong> into <strong>Schedule</strong>: pick a\ntime at least five minutes from now and the post waits on the server until\nthen. What is waiting is listed under <strong>Settings → Your posts → Scheduled posts</strong>, where\none can be cancelled or moved: the clock beside an entry opens the same\npicker at the time it has, and <strong>Save</strong> sends the new one. The five-minute\nrule applies again, and so does the limit of 25 posts a day; a time the\nserver refuses leaves the post where it was, and the reason is shown.\nWhat a waiting post says cannot be changed there.</p>\n</li>\n<li><p><strong>A card.</strong> While a post is short (up to 120 characters) and has nothing\nattached, the card button draws it big on one of six backgrounds. It goes\nout as a picture of the words, described with those words, and the words\nstay in the post as well.</p>\n</li>\n<li><p><strong>Games.</strong> <code>/dice</code> rolls a six-sided die (<code>/dice 20</code> a twenty-sided one),\n<code>/flip</code> tosses a coin, and <code>/pick tea, coffee</code> picks one of the options on\nthe rest of the line. A line under the box says they will be played; when\nyou post, the dice tumble for a moment, and what is sent is the result as\nplain text, so everybody sees the same one.</p>\n</li>\n<li><p><strong>Replying and quoting.</strong> <strong>Reply</strong> under a post opens the composer\naddressed to its author; <strong>Quote</strong> in a post&#39;s menu embeds it in yours. Only\npublic and unlisted posts held by this server can be quoted, and the quoted\nauthor receives the post that carries their words.</p>\n</li>\n</ul>\n<p>Your own posts carry more in their <code>…</code> menu: <strong>Edit</strong> (saved and sent to the\nservers that have the post as an update), <strong>Delete</strong> (removed here, and a\ndeletion is sent to every server that received it — this cannot be undone),\n<strong>Pin to profile</strong> (up to five public or unlisted posts), and <strong>Delivery\nstatus</strong>, which says which servers received the post, which are still being\ntried and which gave up.</p>\n<h2 id=\"putting-a-post-away\">Putting a post away</h2>\n<p>A post you no longer want on your profile does not have to be deleted. <strong>Archive</strong>,\nin the post&#39;s own <code>…</code> menu, takes it off your profile and out of every timeline,\nsearch and hashtag page on this server, and leaves it exactly where it is\notherwise: nobody is told, nothing is sent anywhere, and you can put it back at\nany time from <strong>Settings → Your posts → Archived posts</strong>.</p>\n<p>What archiving is not is a way to take a post back from the fediverse. Other\nservers that received it still have it, and somebody who kept the link still\nopens it — that is what <strong>Delete</strong> is for, and deleting cannot be undone.</p>\n<h2 id=\"if-your-post-is-kept-back\">If your post is kept back</h2>\n<p>Your server may show some posts to a moderator before they go out. There are\ntwo reasons it does: the <strong>first post</strong> of an account that has not published\nanything here yet, and a post that tripped one of the server&#39;s spam rules — a\nlot of links, or a lot of mentions from an account nobody follows yet. Your\nadministrator can turn either off, and neither applies to a <strong>direct\nmessage</strong>: nobody reads those but the people you wrote to. If you are an\nadministrator of this server, nothing of yours is ever held — you are the\nperson the queue is waiting for.</p>\n<p>When it happens the app says so at once, and your writing is kept — there is\nno need to write it again, and writing it again only finds the copy already\nwaiting. Nobody but you and the moderators can see it in the meantime: it is\nin no timeline, not even your own. <strong>Settings → Your posts → Waiting for review</strong> is\nwhere yours are, and you can take one back from there, which deletes it and\ntells nobody.</p>\n<p>If it is approved, it goes out as an ordinary post, dated the moment it was\napproved rather than when you wrote it. If it is refused, it is deleted and\nyou are told.</p>\n<h2 id=\"replies-in-files\">Replies in Files</h2>\n<p>A picture or video you post from Files — with <strong>Share to Aloha Social</strong> or\n<strong>Add from Files</strong> — keeps a link to its file. Public and unlisted replies to\nthe post then appear in that file&#39;s <strong>Comments</strong> tab in Files, each one naming\nwho wrote it, so the conversation sits next to the picture it is about. Replies\nfrom people or servers you blocked or muted are left out, and a reply with a\ncontent warning shows only the warning there.</p>\n<p>A comment <strong>you</strong> write on that file is posted as your reply, to everyone who\ncan see the post. Comments from anybody else who can open the file stay on this\nserver, as they always did. Editing or deleting your comment edits or deletes\nthe reply.</p>\n<p>This is on unless you turn it off: <strong>Settings → Your posts → Replies in Files</strong>. Followers-only\nposts and direct messages are never linked.</p>\n<h2 id=\"where-it-was-taken\">Where it was taken</h2>\n<p>The pin in the composer&#39;s toolbar says where a post was taken. It offers the\nplaces people on this server have already posted from as you type; a name\nnobody here has used yet becomes a place the moment your post goes out, with\na country if you add one. <strong>Nothing is looked up on a map service</strong> — the app\nnever sends your location anywhere to work out what it is, which is the same\npromise it keeps by stripping the camera&#39;s location from your pictures. The\nplace shows as a small marker under the post, and tapping it opens the page\nof everything public that was taken there. Release the pin and the post has\nno place.</p>\n","toc":[{"id":"putting-a-post-away","text":"Putting a post away","level":2},{"id":"if-your-post-is-kept-back","text":"If your post is kept back","level":2},{"id":"replies-in-files","text":"Replies in Files","level":2},{"id":"where-it-was-taken","text":"Where it was taken","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"writing-a-post","manual":false,"prev":{"path":"/docs/user-finding-and-following-people","title":"Finding and following people"},"next":{"path":"/docs/user-following-events-from-gancio","title":"Following events from Gancio"},"parent":null},{"slug":"user-following-events-from-gancio","path":"/docs/user-following-events-from-gancio","title":"Following events from Gancio","description":"Gancio publishes events over ActivityPub from one instance-wide account. Search for and follow that account from Social: it is usually @events@gancio.example on Gancio 1.24 and newer, or…","group":"user","html":"<p>Gancio publishes events over ActivityPub from one instance-wide account. Search\nfor and follow that account from Social: it is usually <code>@events@gancio.example</code>\non Gancio 1.24 and newer, or <code>@relay@gancio.example</code> on older instances. The\nGancio administrator can customize this name, so use the federation address\nshown on that Gancio site&#39;s follow link when it differs. The Gancio instance\nmust have federation enabled. Once the follow is accepted, new public events\nthat Gancio delivers appear in Social like other followed ActivityPub posts,\nwith a card for the event title, time and venue. Following alone does not\nbackfill the instance&#39;s existing event catalogue. To look for older events,\nopen the followed Gancio account&#39;s profile in Social; Social reads its public\nActivityPub outbox in bounded pages, including Gancio <code>Event</code> objects, as you\nopen and page through that profile. This uses ActivityPub rather than Gancio&#39;s\ninstance-specific API, and only imports entries the Gancio outbox exposes.</p>\n<p>On a signed-in Social timeline, choose <strong>Add to Nextcloud Calendar</strong> on an\nevent card to import it directly into your first writable Nextcloud calendar.\nThe event keeps its title, start and end time, venue and source link. Social\ndetects an event that is already in a calendar and avoids adding it twice. If\nthe Calendar app is unavailable or no writable calendar exists, the card offers\nan <code>.ics</code> download instead. Public status pages offer the <code>.ics</code> download;\ndirect import requires a signed-in Nextcloud session and a writable calendar.\nThe calendar entry is a copy, not a live subscription. If Gancio later changes\nan event, Social updates the event in its timeline when it receives the\nActivityPub update or reads the changed event from the followed account&#39;s\noutbox. Social also applies a Gancio <code>Delete</code> found in that outbox to the\ntimeline copy. An entry already imported into Calendar stays as it was, even\nif the event is changed or deleted. To import changed details, delete the old\nentry in Calendar first and then import the event again from Social.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"following-events-from-gancio","manual":false,"prev":{"path":"/docs/user-writing-a-post","title":"Writing a post"},"next":{"path":"/docs/user-reading","title":"Reading"},"parent":null},{"slug":"user-reading","path":"/docs/user-reading","title":"Reading","description":"The browser tab names the page you are on — the feed, the account, the author of the post, Settings — in front of the app's name, so the history and a screen reader can tell the pages…","group":"user","html":"<p>The browser tab names the page you are on — the feed, the account, the author\nof the post, <em>Settings</em> — in front of the app&#39;s name, so the history and a\nscreen reader can tell the pages apart. A link to a page that does not exist\nsays <em>Page not found</em> and offers the way back to your feed.</p>\n<p>The sidebar is the map:</p>\n<ul>\n<li><strong>My Feed</strong>, <strong>Local</strong>, <strong>Global</strong> — a switcher above the posts. My Feed is\nwhat the people and hashtags you follow post; Local is every public post\nwritten on this Nextcloud; Global is every public post this server has\nreceived. <strong>Photos</strong> and <strong>Videos</strong> carry the same switcher over posts that\nare pictures, or videos — including videos from PeerTube channels anyone\nhere follows — with <strong>For you</strong> in it as well (see below). A thin line\nacross My Feed — <em>Up to date since 14:02</em> — marks where you had got to last\ntime, and the posts below it are drawn a shade quieter. It is the position\nMastodon apps keep too: read your feed on your phone and the line here has\nmoved, and the other way round.</li>\n</ul>\n<h2 id=\"videos\">Videos</h2>\n<p> looks like a video site&#39;s front page: large cards, four to a\nrow on a wide screen, two on a tablet and one on a phone. Each card shows the\nvideo&#39;s picture with its running time (or <strong>Live</strong>), the channel&#39;s face, the\ntitle, the channel, and how many views it has and how long ago it was\npublished — the views of a video posted here are counted here, those of a\nvideo from elsewhere only where its own site counts them, and none at all\nwhile you hide the numbers (see <strong>Likes and followers</strong> below). Rest the\nmouse on a card and after a moment it plays a silent preview; it does not on\na touch screen, when your device asks for less motion, or when it asks to\nsave data. Press a card to watch the video. Chips above the cards narrow\nwhat you see: <strong>All</strong>, <strong>Live</strong> when anything is live, the categories of the\nvideos shown, and <strong>Recently uploaded</strong> (the last seven days). Between the\nrows are shelves: <strong>Shorts</strong> (press one to watch it in Shorts), <strong>From\nchannels you follow</strong> when you are looking at Local, Global or For you, and\n<strong>Continue watching</strong> once there is something you started. <strong>Upload a\nvideo</strong> next to the chips picks the file first and then opens the post\naround it, with the video&#39;s title and category. The arrow keys move from\ncard to card.</p>\n<h2 id=\"watching-a-video\">Watching a video</h2>\n<p> A video&#39;s page plays it in a player of its own. It\nstarts where you stopped last time, unless you had nearly finished it, and\nremembers where you are as you watch, so <strong>Continue watching</strong> offers it\nback. Under the picture are play and pause, the sound and its volume, the\ntime, and on the right <strong>Subtitles</strong> (when the video has them, in your own\nlanguage first), the <strong>speed</strong> (half to double; this browser remembers\nyour choice), <strong>Quality</strong> (Auto, or one size, when the video comes in\nseveral), <strong>Play in a floating window</strong> where your browser can, and <strong>Full\nscreen</strong>. The keys are the ones video sites use — see <strong>Keyboard\nshortcuts</strong> below. A view is counted once you have watched five seconds of\na video posted here, once a day per person; nothing about who watched is\nkept past the day.</p>\n<h2 id=\"the-small-player\">The small player</h2>\n<p> Leave a video&#39;s page while it plays — open the\ntimeline, a profile, anything in the app — and it goes on in a small\nplayer in the bottom corner, with play and pause, <strong>Back to the video</strong> and\n<strong>Close the player</strong>. Back to the video goes on from the same moment on its\npage; closing it stops the video. It only ever holds a video you were\nwatching: nothing starts in it on its own.</p>\n<h2 id=\"shorts\">Shorts</h2>\n<p>short videos watched one at a time, full height, each\nplaying as it comes up and pausing as you scroll past. A short is kept on\nits poster&#39;s profile like any other post, or lasts <strong>24 hours</strong> and is seen\nonly by its poster&#39;s followers (see <strong>Shorts that last 24 hours</strong> below).\nThe 24-hour shorts of the people you follow come first, grouped by person\nand the ones you have not seen before the rest, each marked <strong>24h</strong> with the\nhours it has left; then come the kept ones. <strong>What counts as a short:</strong> a\npost with a single video of <strong>at most 3 minutes</strong> that is <strong>upright or\nsquare</strong> — a landscape video, a longer one, or a post with several videos\nstays on the Videos page instead. A video from another server counts once\nthis server knows how long it is and how it is shaped, which it learns\nfrom the other server or by measuring the file when it keeps a copy. Where\nthere are no shorts yet, Shorts says so.\nThe switch in the top corner picks whose videos (<strong>My Feed</strong>, <strong>For you</strong>,\n<strong>Local</strong> or <strong>Global</strong>); it opens on For you once your reading has taught\nit something, and on My Feed before that. It plays\nwith sound; opened from a link, the browser may hold the sound back until\nyou tap the speaker, which a &quot;Tap for sound&quot; hint points at. Once you have\ntapped it, the videos after it keep their sound as you scroll, and if you\nmute one they stay muted until you close the tab. Tap to pause,\narrow keys to move, space to pause, <code>m</code> for sound, <code>l</code> to like. The <strong>+</strong>\nopens <strong>New short</strong>, which first asks how long it should last: <strong>Keep it on\nmy profile</strong>, or <strong>Only for 24 hours, for my followers</strong>. A kept short is a\nvideo; a 24-hour one can also be a picture or a few words on a card.</p>\n<ul>\n<li><strong>Upload a video</strong>, drop one on the dialog, or <strong>Record</strong> one with your\ncamera. Recording counts down 3-2-1 first, can switch between the front\nand back camera, and stops by itself at the limit you pick (15 s, 60 s or\n3 min). Browsers only lend a page the camera over https, so on a server\nreached by plain http the Record button says so instead.</li>\n<li><strong>Trim</strong> it by dragging the two handles on the strip under the preview,\nor focus a handle and use the arrow keys (Shift for bigger steps, Home and\nEnd for the ends). The preview loops over just the part you kept.</li>\n<li><strong>Cover</strong>: slide to the frame people see before the short plays.</li>\n<li>Write a <strong>caption</strong>; the popular hashtags underneath add themselves with\none press. For a kept short, choose <strong>Everyone</strong>, <strong>Quiet public</strong> or\n<strong>Followers</strong>, and switch on <strong>Sensitive content</strong> to hide it until\nsomebody chooses to watch; a 24-hour short always goes to your followers.</li>\n<li><strong>Post</strong> shows how far it has got: cutting (as long as the trimmed short\nlasts, since the browser plays it through once), uploading, posting.\nClosing the dialog with a video in it asks before throwing it away.</li>\n</ul>\n<h2 id=\"activities\">Activities</h2>\n<p>your notifications: mentions, favourites, boosts, new\nfollowers and follow requests, poll results, edits of posts you boosted.\nIt is in the sidebar, between Shorts and Direct messages. The badge\nbeside it counts what arrived since you last looked, plus the people\n<a href=\"/docs/user-who-may-reach-you-and-requests#who-may-reach-you-and-requests\">waiting for your review</a>; the same\nevents reach the Nextcloud bell and its mail digest; a follow request can be\naccepted or declined from the bell itself. While anybody is waiting, the\nfirst line of the page says so — <em>3 people are waiting — Review</em> — and\nopens the list of them in place. The page says how many new activities there are at\nthe top — <em>3 new activities</em>, with a <strong>Mark all as read</strong> button that clears\nthe badge whichever filter you are looking at — and marks the activities\nthemselves: each new one carries a <strong>New</strong> tag beside its age and a bar\ndown its edge, and a <strong>New</strong> heading separates them from <strong>Earlier</strong> where\nthe page holds both. Each activity is a row like a post in My Feed: who did\nwhat and how long ago (<em>3h</em>, <em>2w</em>), with the post or account it is about\nunderneath. A private message is not laid out there beside the public\nmentions: its row says <em>sent you a private message</em> with a lock, shows its\nfirst words (or its content warning), and <strong>Open the conversation</strong> takes\nyou to Direct messages.\nOtherwise the page marks itself read after a couple of seconds in front of\nyou, and that position is the one every other Fediverse client shares: a\nbadge cleared on your phone is cleared here too.</p>\n<h2 id=\"direct-messages\">Direct messages</h2>\n<p>private conversations, one chat per person: every\nmessage between you and the same people is in that one chat, however it\nwas started (other apps may list such messages as separate\nconversations). <strong>New\nmessage</strong> first offers people from your existing chats and the accounts you\nfollow. Search by name, <code>@handle</code> or profile link to find somebody else:\nthe people you know — accounts you follow and people from your chats — are\nlisted first under <strong>People you know</strong>, and every other account the search\nfinds follows under <strong>Other accounts</strong>. A full handle or profile link that\nis not known here yet is offered with <strong>Look up</strong> (or press <strong>Enter</strong>), which\nasks that person&#39;s own server. A search failure is shown separately\nfrom a genuine empty result. Selecting somebody with an\nexisting conversation opens that chat instead of creating another one.\nThe new chat uses the same person header and message field as an existing\nconversation. Messages are sent privately to that person, so there is no\npublic, follower-only or other audience to choose and no repeated mention to\ntype. The inbox lists conversations the way the feed lists posts — the\nperson&#39;s face and name, a line of the last message and how long ago it was\n(<em>3h</em>, <em>2w</em>) — with <strong>All</strong> and <strong>Unread</strong> in the same switcher as My Feed\nand Local. A search box joins them once there are more than a handful of\nconversations, and <strong>Remove conversation</strong> is in a row&#39;s <strong>…</strong> menu, which\nappears when you point at the row. Opening a chat marks it read, and the\nsidebar badge comes down with it; new messages appear in the inbox and the\nopen chat on their own. Your\nmessages are drawn in your own colour, the other person&#39;s in grey; a run of\nmessages carries its time under the last one, and you see the others&#39; by\npointing at them. The message field is the feed composer&#39;s rounded line with\nyour face beside it, and the send button appears once you have written\nsomething; <strong>Ctrl+Enter</strong> (<strong>⌘+Enter</strong> on a Mac) sends, Enter starts a new\nline. A conversation keeps to the feed&#39;s reading width. On a phone, the\nconversation list and chat open as separate screens, with a back arrow.</p>\n<h2 id=\"explore\">Explore</h2>\n<p>one collapsible entry holding everything there is to look at\nbesides your own feed: the hashtags you follow, your <strong>lists</strong>, and the tags\nthis server is busy with right now, in that order. Each list is a timeline of\nits own; a Nextcloud group you belong to (up to 500 members) is a list too\nwhen your administrator has chosen that group for it — none are, until they\ndo — kept in step with the group, and your own are made in\n<strong>Settings → Reading → Lists</strong>. Explore shows as much as the sidebar has room for and\nno more — make the window taller and more appears. What you follow is never\npushed out by what happens to be trending: the trending tags take only the\nroom the rest leave, and a tag you already follow is not offered twice.</p>\n<h2 id=\"liked-posts\">Liked posts</h2>\n<p> and <strong>Bookmarks</strong> — what you favourited, and what you saved\nwith <strong>Bookmark</strong> in a post&#39;s menu. Bookmarks are private and never leave\nthis server.</p>\n<h2 id=\"statistics\">Statistics</h2>\n<p>what you have posted here and what came back: likes,\nboosts, replies and quotes per post, your best posts, when your posts do\nbest, which of your hashtags work, which servers your followers and the\npeople who answer you are on, and where else your posts went out.</p>\n<p>Open a post (its timestamp, <code>o</code> or <code>Enter</code>) for its own page: the thread, a\nreply box, who boosted and favourited it, and the details a card leaves out —\nexact time, audience, language, whether it was edited, and a link to the\noriginal on its home server. <strong>Like</strong>, <strong>Boost</strong> and <strong>Reply</strong> sit under every\npost; a post&#39;s <code>…</code> menu adds <strong>Bookmark</strong>, <strong>Open on original instance</strong> and\n<strong>Report</strong>.</p>\n<p>A post that links somewhere gets a preview card, read by this server rather\nthan by your browser. With the <code>notify_push</code> app installed, new posts arrive\nlive; without it the page checks every 30 seconds.</p>\n","toc":[{"id":"videos","text":"Videos","level":2},{"id":"watching-a-video","text":"Watching a video","level":2},{"id":"the-small-player","text":"The small player","level":2},{"id":"shorts","text":"Shorts","level":2},{"id":"activities","text":"Activities","level":2},{"id":"direct-messages","text":"Direct messages","level":2},{"id":"explore","text":"Explore","level":2},{"id":"liked-posts","text":"Liked posts","level":2},{"id":"statistics","text":"Statistics","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":[{"path":"/docs/user-for-you","title":"For you","description":"For You is an optional ranked feed beside My Feed and the local and global timelines. The administrator can enable it. It combines relevant posts already known to this server with bounded…","parent":true},{"path":"/docs/user-announcements-from-your-administrators","title":"Announcements from your administrators","description":"When the administrators of this Nextcloud post a notice — a maintenance window, a move, a new rule — it appears at the top of the timeline, above the composer, on every page except a…","parent":true},{"path":"/docs/user-how-a-post-reads","title":"How a post reads","description":"A feed is a column of posts separated by thin lines, not a stack of boxes, narrow enough that a line of text is easy to follow back to its start (the photo and video grids keep the wider…","parent":true},{"path":"/docs/user-shorts-that-last-24-hours","title":"Shorts that last 24 hours","description":"A short you post for 24 hours is one picture, video or card of words that the people who follow you can see for a day, and then it is gone. It is not on your profile and nobody else can…","parent":true},{"path":"/docs/user-collections","title":"Collections","description":"A profile has a Collections tab beside Posts, Photos, Videos and Tagged: the account's albums. Each is a page of the posts the owner gathered into it, drawn as the same grid of squares the…","parent":true},{"path":"/docs/user-posting-as-a-team","title":"Posting as a team","description":"If an administrator has given one of your Nextcloud groups an account, a small picker appears in the composer beside the language and the audience: As myself, or the team. Choose the team…","parent":true},{"path":"/docs/user-a-page-of-your-work","title":"A page of your work","description":"Settings → Profile and privacy → Portfolio makes a page with its own address, to put on a CV. A profile is a feed: everything you posted, newest first, with the follow button and the…","parent":true},{"path":"/docs/user-who-is-in-the-photo","title":"Who is in the photo","description":"Open one of your own posts with a picture in it, choose Tag people from its menu (…), and type the handles of the people in it, separated by commas. Their names appear under the post…","parent":true},{"path":"/docs/user-who-may-reach-you-and-requests","title":"Who may reach you, and requests","description":"Held people can still write to you. Their posts, likes and follows wait in Activities until you look; they do not ring, push or mail. Everything a held person does waits together —…","parent":true},{"path":"/docs/user-muting-a-conversation","title":"Muting a conversation","description":"Mute conversation stops the notifications one thread would give you without muting anybody. It is in every post's menu, and in the menu of a mention or reply card in Activities. The mute…","parent":true},{"path":"/docs/user-hiding-a-whole-server","title":"Hiding a whole server","description":"Settings → Blocking now has a third list: the servers you have hidden. Hiding one hides every account on it and everything they post, and takes your follows in both directions with it. It…","parent":true},{"path":"/docs/user-posts-made-with-ai","title":"Posts made with AI","description":"Settings → Blocking has a switch, Hide posts made with AI, off until you turn it on. On, a post that says it was made with AI is kept out of everything you read — your feed, the public…","parent":true},{"path":"/docs/user-what-a-post-used-to-say","title":"What a post used to say","description":"A post that has been edited says so under it. That line is a button now: it opens every version, oldest first, with the content warning and the pictures each one carried. A reader who has…","parent":true}],"anchor":"reading","manual":false,"prev":{"path":"/docs/user-following-events-from-gancio","title":"Following events from Gancio"},"next":{"path":"/docs/user-for-you","title":"For you"},"parent":null},{"slug":"user-for-you","path":"/docs/user-for-you","title":"For you","description":"For You is an optional ranked feed beside My Feed and the local and global timelines. The administrator can enable it. It combines relevant posts already known to this server with bounded…","group":"user","html":"<p><strong>For You</strong> is an optional ranked feed beside My Feed and the local and global\ntimelines. The administrator can enable it. It combines relevant posts already\nknown to this server with bounded discovery; available candidates can include\nActivityPub and Bluesky posts. Photos, Videos and Shorts can use the same ranking\nwith the relevant media filter. A sparse candidate pool may include fallback\ndiscovery, so this feed is not a complete or guaranteed index of either network.</p>\n<p>Post menus offer feedback such as hiding a post, seeing more from an author, or\nseeing less like similar content. These actions influence recommendations; they\ndo not follow, mute or block anyone. The feed may show a short explanation for a\npost while it is in For You. The explanation is tied to that feed and does not\nappear in ordinary timelines.</p>\n<p>Behavioral learning is a separate setting and is not required for the feed to\nwork. If enabled, supported reading and video actions can refine future feed\nsessions. Learned data is private to the account and is not federated. The\ncurrent interface does not provide manual topic selection or topic editing.\nFor details about signals, consent, data export and operational limits, see\n<a href=\"/docs/for-you\">For-You.md</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"for-you","manual":false,"prev":{"path":"/docs/user-reading","title":"Reading"},"next":{"path":"/docs/user-announcements-from-your-administrators","title":"Announcements from your administrators"},"parent":"user-reading"},{"slug":"user-announcements-from-your-administrators","path":"/docs/user-announcements-from-your-administrators","title":"Announcements from your administrators","description":"When the administrators of this Nextcloud post a notice — a maintenance window, a move, a new rule — it appears at the top of the timeline, above the composer, on every page except a…","group":"user","html":"<p>When the administrators of this Nextcloud post a notice — a maintenance\nwindow, a move, a new rule — it appears at the top of the timeline, above the\ncomposer, on every page except a single post&#39;s own. It is there because you\nhave not read it yet.</p>\n<p><strong>Got it</strong> marks it read. It does not disappear under you: it stays where it\nwas, greyed, with a <strong>Read</strong> mark, so you can finish the sentence you were on.\nIt is gone the next time you open the app, and gone on your phone too — being\nread is remembered by the server for your account, not by this browser.</p>\n<p>Announcements you have already read are not shown. While the card is up —\nthat is, while something in it is still unread — a line at its foot, <strong>Show 2\nannouncements you have read</strong>, brings them back; once everything is read the\ncard is gone entirely and so are they. An announcement with an end says when\nit runs out (&quot;Until 21 September&quot;), and one that has not started yet, or has\nrun out, is never shown at all.</p>\n<p>The emoji buttons under an announcement are the one thing you can say back to\none. Press one to add yours or to take it back, or press the smiley with a\nplus on it to choose another; you may put up to eight different emoji on the\nsame announcement.</p>\n<p>Administrators post and remove announcements in <strong>Administration → Aloha Social</strong>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"announcements-from-your-administrators","manual":false,"prev":{"path":"/docs/user-for-you","title":"For you"},"next":{"path":"/docs/user-how-a-post-reads","title":"How a post reads"},"parent":"user-reading"},{"slug":"user-how-a-post-reads","path":"/docs/user-how-a-post-reads","title":"How a post reads","description":"A feed is a column of posts separated by thin lines, not a stack of boxes, narrow enough that a line of text is easy to follow back to its start (the photo and video grids keep the wider…","group":"user","html":"<p>A feed is a column of posts separated by thin lines, not a stack of boxes,\nnarrow enough that a line of text is easy to follow back to its start (the\nphoto and video grids keep the wider page). Each post has its author&#39;s face\nbeside their name, how old it is in a word — <em>now</em>, <em>5m</em>, <em>3h</em>, <em>2d</em>, <em>2w</em>,\nthen the date — and the full date when you point at it. A post shows who can\nsee it only when that is not everybody: a mark for unlisted, followers-only or\ndirect posts, nothing for public ones.</p>\n<p>The reply, boost and like buttons stay out of sight until you point at a post\nor reach it with the keyboard, so a page of posts is a page of words; a like\nor boost you have given shows as a small heart or arrows beside the post&#39;s age.\nWith the numbers turned on, a post that has replies, boosts or likes keeps\nthem in a row under its words, each beside a faint icon, and your own like or\nboost is shown there instead. On a phone they are always there. The\nthree are on every post in the same place; one that cannot be used — a boost\nof a followers-only post, a reply the author does not take — is greyed out and\nsays why. To react with an emoji, hold the heart (or right-click it), or choose\n<strong>Add a reaction</strong> in the post&#39;s menu; the reactions people left are shown under\nthe post.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"how-a-post-reads","manual":false,"prev":{"path":"/docs/user-announcements-from-your-administrators","title":"Announcements from your administrators"},"next":{"path":"/docs/user-shorts-that-last-24-hours","title":"Shorts that last 24 hours"},"parent":"user-reading"},{"slug":"user-shorts-that-last-24-hours","path":"/docs/user-shorts-that-last-24-hours","title":"Shorts that last 24 hours","description":"A short you post for 24 hours is one picture, video or card of words that the people who follow you can see for a day, and then it is gone. It is not on your profile and nobody else can…","group":"user","html":"<p>A short you post for <strong>24 hours</strong> is one picture, video or card of words that\nthe people who follow you can see for a day, and then it is gone. It is not on\nyour profile and nobody else can open it.</p>\n<p>Above your own feed is the <strong>Shorts</strong> bar. Your own tile, <strong>Your shorts</strong>,\ncomes first, with a <strong>+</strong> on it to make a new one. After it come the people\nyou follow who have a 24-hour short up, the ones holding something you have\nnot seen first, with a coloured ring around their face; the ring goes grey\nonce you have seen them all. The last tile, <strong>All shorts</strong>, opens the Shorts\nstack. The bar is there only while somebody you follow has a 24-hour\nshort up, and takes no room at all while nobody does; <strong>Shorts</strong> in the\nsidebar is always there.</p>\n<p>Tap a face and that person&#39;s shorts play one after another in the same\nplayer as every other short: a picture or a card for the seconds its poster\ngave it, a video for as long as it runs. Hold the picture to pause it, tap\nthe left or right of it to go back or forward, and use the arrows at the\nsides to move to the next person. A video plays with its sound on; the\nspeaker at the top turns it off (or <code>m</code>), and when the browser holds the\nsound back a &quot;Tap for sound&quot; hint points at the speaker.</p>\n<p>To post one, press the camera at the end of the box you write posts in\n(<strong>New short</strong>) — it opens on 24 hours — or the <strong>+</strong> (on your tile or in the\nShorts stack) and choose\n<strong>Only for 24 hours, for my followers</strong>, and either record or upload a video\nas for any short, or choose a picture or words. A picture goes on to an\neditor: add a caption if you like, and say how many seconds it should show\nfor. On a picture you can add\n<strong>stickers</strong> — eight emoji, or a line of your own words — drag them where you\nwant them, move a selected one with the arrow keys and remove it with Delete;\nthey are drawn into the picture before it goes up. Or write a few words, pick\none of six backgrounds (the first is your own colour), and the short is a\ncard with those words on it, sent with the words as its description so\nsomebody who cannot see it is told what it says. Either way the picture goes\nup the way every attachment does — stripped of the camera&#39;s metadata — and\nyour short is up for a day, to your followers and nobody else. While it is\nup, <strong>Who has seen it</strong> in the player lists the people who watched it, and\n<strong>Delete this short</strong> takes it down early.</p>\n<p>Somebody watching a 24-hour short can answer it: a row of emoji under it for\na reaction, and a box beside them for a line of text. Either one goes to the\nperson who posted it and to nobody else — a reply to a 24-hour short is a\nmessage, not a comment on a page — and only somebody who follows them can\nsend one, which is the same condition as being able to see the short at all.\nFive answers to one short is the limit, because without one what it hands\nsomebody is a private channel to its poster that the poster cannot close.\nWhat was said shows under your own short while it is up, and goes with it\nwhen it expires: a reply is not a post, and nothing keeps it after the thing\nit was about has gone.</p>\n<p>24-hour shorts travel. Yours go to the people who follow you on Pixelfed,\nand Pixelfed shows them in its stories bar. Pixelfed&#39;s own come the other way\nonly to servers it recognises as Pixelfed, and that is Pixelfed&#39;s decision\nrather than this server&#39;s. Taking yours down early takes it down there too.\nWhat another server does with its copy after the day is up is that server&#39;s\nbusiness, which is why one that arrives here is kept for a day at the most,\nwhatever the sender says, and one that has already expired is not kept at\nall. Watching one from another server sends a receipt to its author so that\ntheir own server can count it, and reactions and replies travel the same way\nin both directions, in the shape Pixelfed&#39;s own inbox reads.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"shorts-that-last-24-hours","manual":false,"prev":{"path":"/docs/user-how-a-post-reads","title":"How a post reads"},"next":{"path":"/docs/user-collections","title":"Collections"},"parent":"user-reading"},{"slug":"user-collections","path":"/docs/user-collections","title":"Collections","description":"A profile has a Collections tab beside Posts, Photos, Videos and Tagged: the account's albums. Each is a page of the posts the owner gathered into it, drawn as the same grid of squares the…","group":"user","html":"<p>A profile has a <strong>Collections</strong> tab beside Posts, Photos, Videos and Tagged: the\naccount&#39;s albums. Each is a page of the posts the owner gathered into it, drawn\nas the same grid of squares the Photos tab uses, with a lock on the ones that\nare for followers only.</p>\n<p>Your own shelf has a <strong>New collection</strong> field at the top. To put a post into\none, open the post&#39;s menu (<strong>…</strong>) and choose <strong>Add to a collection</strong>; only your\nown posts with a picture or a video in them offer it, because that is all a\ncollection may hold. On a collection&#39;s page you can <strong>Edit</strong> its title,\ndescription and audience, <strong>Remove posts</strong> from their own squares, or\n<strong>Delete</strong> it — the posts stay where they are.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"collections","manual":false,"prev":{"path":"/docs/user-shorts-that-last-24-hours","title":"Shorts that last 24 hours"},"next":{"path":"/docs/user-posting-as-a-team","title":"Posting as a team"},"parent":"user-reading"},{"slug":"user-posting-as-a-team","path":"/docs/user-posting-as-a-team","title":"Posting as a team","description":"If an administrator has given one of your Nextcloud groups an account, a small picker appears in the composer beside the language and the audience: As myself, or the team. Choose the team…","group":"user","html":"<p>If an administrator has given one of your Nextcloud groups an account, a small\npicker appears in the composer beside the language and the audience: <strong>As\nmyself</strong>, or the team. Choose the team and the post goes out from the team&#39;s\naccount — its name, its picture, its followers — rather than from yours.</p>\n<p>Everybody in the group can post as it, and the list is checked at the moment\nyou press post: leaving the group takes the account away with it, with nothing\nto remember to undo.</p>\n<p>Who actually wrote each post is recorded. The team can see it, and so can a\nmoderator looking at a report; nobody else can. Outside the team, the team\nspeaks with one voice, which is the point of having a team account.</p>\n<p>An administrator makes one with <code>occ social:team &lt;group&gt; &lt;username&gt;</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"posting-as-a-team","manual":false,"prev":{"path":"/docs/user-collections","title":"Collections"},"next":{"path":"/docs/user-a-page-of-your-work","title":"A page of your work"},"parent":"user-reading"},{"slug":"user-a-page-of-your-work","path":"/docs/user-a-page-of-your-work","title":"A page of your work","description":"Settings → Profile and privacy → Portfolio makes a page with its own address, to put on a CV. A profile is a feed: everything you posted, newest first, with the follow button and the…","group":"user","html":"<p><strong>Settings → Profile and privacy → Portfolio</strong> makes a page with its own address, to put on a CV.\nA profile is a feed: everything you posted, newest first, with the follow\nbutton and the boosts and the replies around it. A portfolio is the opposite —\na title, a sentence, the pictures you chose, and nothing else on it.</p>\n<p>Give it a title and a line about the work, choose a grid of squares or one\npicture at a time, and say where the pictures come from: your most recent\npublic photos, or one of your collections. Then decide what goes under each\none — the caption, where it was taken, the year — and whether your own picture\nis at the top.</p>\n<p>Until you turn <strong>Publish my portfolio</strong> on, the page is a draft only you can\nsee. Once it is on, the address appears under the switch and anybody with it\ncan read the page without signing in, which is the whole point. <strong>Only your\npublic photos are ever on it</strong>, whatever the rest of the settings say: the page\nis built by asking for your posts as an anonymous reader, so a followers-only\nphotograph cannot reach it. The draft shows you exactly what will be published,\nwhich is why a followers-only photo is missing from it too.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"a-page-of-your-work","manual":false,"prev":{"path":"/docs/user-posting-as-a-team","title":"Posting as a team"},"next":{"path":"/docs/user-who-is-in-the-photo","title":"Who is in the photo"},"parent":"user-reading"},{"slug":"user-who-is-in-the-photo","path":"/docs/user-who-is-in-the-photo","title":"Who is in the photo","description":"Open one of your own posts with a picture in it, choose Tag people from its menu (…), and type the handles of the people in it, separated by commas. Their names appear under the post…","group":"user","html":"<p>Open one of your own posts with a picture in it, choose <strong>Tag people</strong> from its\nmenu (<strong>…</strong>), and type the handles of the people in it, separated by commas.\nTheir names appear under the post, linked to their profiles, and each of them is\ntold — including somebody on another server, because the name is written onto\nthe post as a mention and the post is sent out again.</p>\n<p>The field holds the whole list rather than only what you are adding, so taking\nsomebody out of the photo is deleting their handle. Only the person who posted a\nphoto can name anybody in it: if anybody could, writing your own name onto\nsomebody else&#39;s picture would put their post in front of an audience that never\nasked for it.</p>\n<p>Naming somebody does <strong>not</strong> change who may see the post. A followers-only\nphotograph stays followers-only.</p>\n<p>Each profile has a <strong>Tagged</strong> tab: the photographs that account is named in,\nwhoever took them. If you are named in one and would rather not be, <strong>Remove me</strong>\nunder the post takes your name off, and needs nobody&#39;s permission.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"who-is-in-the-photo","manual":false,"prev":{"path":"/docs/user-a-page-of-your-work","title":"A page of your work"},"next":{"path":"/docs/user-who-may-reach-you-and-requests","title":"Who may reach you, and requests"},"parent":"user-reading"},{"slug":"user-who-may-reach-you-and-requests","path":"/docs/user-who-may-reach-you-and-requests","title":"Who may reach you, and requests","description":"Held people can still write to you. Their posts, likes and follows wait in Activities until you look; they do not ring, push or mail. Everything a held person does waits together —…","group":"user","html":"<p><strong>Settings → Notifications → Who may reach you</strong> is one place for\neverything about being interrupted: the digests and quiet hours first, then\nwho may reach you at all. Five rows, each answered <strong>Allow</strong> or <strong>Hold for\nreview</strong>:</p>\n<ul>\n<li>People you don&#39;t follow</li>\n<li>People who don&#39;t follow you</li>\n<li>New accounts (less than 30 days old, counted from the account&#39;s creation\ndate, on any server)</li>\n<li>Private mentions you didn&#39;t ask for</li>\n<li>Accounts this server limited</li>\n</ul>\n<p>Held people can still write to you. Their posts, likes and follows wait in\nActivities until you look; they do not ring, push or mail. Everything a held\nperson does waits together — mentions, replies, direct messages, likes,\nboosts, follows. A choice is saved the moment you make it; if the server\nrefuses it, the row goes back and says why.</p>\n<p><strong>Who may send you direct messages</strong> — in Settings → Profile and privacy —\nis the private-mentions row seen from the other side: <em>Everybody</em>, <em>People\nyou follow</em> (a message from anybody else waits with the rest), or <em>Nobody</em>\n(every direct message waits, except from people you allowed). People on\nBluesky go by the same choice.</p>\n<p>A new account starts calm: people you don&#39;t follow, new accounts, private\nmentions you didn&#39;t ask for and accounts this server limited are held, and\neverybody else is allowed. An account that existed before this setting keeps\naccepting everybody until you choose, and sees one notice at the top of\nActivities pointing here; it goes away when you close it or save a choice.\nMastodon apps can also set a row to discard instead of hold. The web app does\nnot offer that: such a row shows as <strong>Hold for review</strong> with the note <em>An app\nset this to discard; choosing here replaces it</em>, and choosing either answer\nhere replaces it.</p>\n<p><strong>Requests.</strong> The people being held wait at the top of <strong>Activities</strong>: a line\nsays how many — <em>2 people are waiting — Review</em> — and <strong>Review</strong> opens the\nlist there, one row per person with how many notifications they sent and the\nfirst words of their most recent post. The count is part of the Activities\nbadge in the sidebar; a request never rings the bell. If a digest is due while\nsomebody waits, it ends with <em>2 people are waiting to reach you</em>; nobody\nwaiting never raises a digest of its own. (<strong>Filtered notifications</strong> on the\nBlocking page links to the same list.)</p>\n<p>You decide about the <strong>person</strong>, not about each notification. <strong>Show these</strong>\naccepts them: what they sent moves into Activities — counted as unread, without\nringing now — and they are always allowed from then on. Accepting does not\nfollow them. <strong>Dismiss</strong> discards what they sent; whatever they do next is\njudged by your rows again. There are buttons for the whole list too.</p>\n<p>Under the rows, <strong>Always allowed</strong> lists everybody you accepted, each with\n<strong>Stop allowing</strong>, which hands that person back to your rows. Nobody is on it\nuntil you accept somebody.</p>\n<p><strong>Digests and quiet hours.</strong> Who may reach you is about <em>whether</em> you are\ntold; <strong>Settings → Notifications → When to tell you</strong> is about <em>when</em> the Nextcloud\nbell — and with it the mobile app and the notification mail — rings for what\nhappens in Aloha Social. Left at <strong>instant</strong>, it rings the moment somebody\nmentions, favourites, boosts or follows you, as it always did. Set to\n<strong>digest</strong>, it stays quiet and rings once at each time of day you choose, up\nto four, with a count of what came in since the last one: &quot;14 new\nnotifications in Aloha Social — 3 mentions, 6 favourites, 4 boosts, 1 new\nfollower&quot;. Two kinds of news can still reach you at once, each on its own\nswitch: a direct message, and a mention from somebody you follow. <strong>Quiet\nhours</strong> work in either mode — between the two times you set, nothing but those\npass-throughs rings, and one digest of what arrived is raised when the window\nends. The times are read in the time zone of your Nextcloud account. None of\nthis changes the notifications page itself: everything is listed there the\nmoment it happens, read or unread, and the digest only counts what you have\nnot read yet. Switching a digest on does not deliver a backlog, and switching\nit off raises one last digest of what it was still holding.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"who-may-reach-you-and-requests","manual":false,"prev":{"path":"/docs/user-who-is-in-the-photo","title":"Who is in the photo"},"next":{"path":"/docs/user-muting-a-conversation","title":"Muting a conversation"},"parent":"user-reading"},{"slug":"user-muting-a-conversation","path":"/docs/user-muting-a-conversation","title":"Muting a conversation","description":"Mute conversation stops the notifications one thread would give you without muting anybody. It is in every post's menu, and in the menu of a mention or reply card in Activities. The mute…","group":"user","html":"<p><strong>Mute conversation</strong> stops the notifications one thread would give you\nwithout muting anybody. It is in every post&#39;s menu, and in the menu of a\nmention or reply card in Activities. The mute covers the whole thread,\nreplies that arrive later included: nothing from it rings the bell, pushes or\nmails, and nothing from it is listed in Activities. The posts stay on every\ntimeline. The post menu reads <strong>Unmute conversation</strong> on any post of a muted\nthread; unmuting lists what arrived meanwhile without ringing for it. A mute\nlasts until you unmute it. Neither entry is offered to somebody not signed in\nor on a public page.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"muting-a-conversation","manual":false,"prev":{"path":"/docs/user-who-may-reach-you-and-requests","title":"Who may reach you, and requests"},"next":{"path":"/docs/user-hiding-a-whole-server","title":"Hiding a whole server"},"parent":"user-reading"},{"slug":"user-hiding-a-whole-server","path":"/docs/user-hiding-a-whole-server","title":"Hiding a whole server","description":"Settings → Blocking now has a third list: the servers you have hidden. Hiding one hides every account on it and everything they post, and takes your follows in both directions with it. It…","group":"user","html":"<p><strong>Settings → Blocking</strong> now has a third list: the servers you\nhave hidden. Hiding one hides every account on it and everything they post, and\ntakes your follows in both directions with it. It is the answer to being\nbothered by a server rather than by one person — the alternative was blocking\naccounts one at a time as they appeared.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"hiding-a-whole-server","manual":false,"prev":{"path":"/docs/user-muting-a-conversation","title":"Muting a conversation"},"next":{"path":"/docs/user-posts-made-with-ai","title":"Posts made with AI"},"parent":"user-reading"},{"slug":"user-posts-made-with-ai","path":"/docs/user-posts-made-with-ai","title":"Posts made with AI","description":"Settings → Blocking has a switch, Hide posts made with AI, off until you turn it on. On, a post that says it was made with AI is kept out of everything you read — your feed, the public…","group":"user","html":"<p><strong>Settings → Blocking</strong> has a switch, <strong>Hide posts made with AI</strong>, off until\nyou turn it on. On, a post that says it was made with AI is kept out of\neverything you read — your feed, the public timelines, hashtags, threads,\nprofiles, lists and your notifications alike — the same way a filtered word\ntakes a post out, and nothing of it reaches this app. Off, such a post arrives\nas usual and carries a quiet <strong>AI</strong> mark, so you can tell without being told.</p>\n<p>&quot;Says it was made with AI&quot; is meant literally. A post counts when it carries\none of the specific hashtags people and tools use for it. Built-in labels include\n<code>#AIgenerated</code>, <code>#midjourney</code> and <code>#stablediffusion</code>; your administrator can add\nothers, such as <code>#aiart</code>, to the list. It also counts when its author marked it in the composer (which adds\n<code>#AIgenerated</code>), or when one of its pictures states in its own metadata that a\nmodel produced it, as the generators that label their output write. Nothing\nhere looks at the picture itself or guesses from the words: a generated post\nthat carries no label is not recognised. The generic topic tag <code>#AI</code> by itself\nis never treated as a generated-content label, so a real photograph tagged\n<code>#ai</code> is not mistaken for one. Like your filters, the switch is yours alone — nothing is\nsent to another server and nobody is told.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"posts-made-with-ai","manual":false,"prev":{"path":"/docs/user-hiding-a-whole-server","title":"Hiding a whole server"},"next":{"path":"/docs/user-what-a-post-used-to-say","title":"What a post used to say"},"parent":"user-reading"},{"slug":"user-what-a-post-used-to-say","path":"/docs/user-what-a-post-used-to-say","title":"What a post used to say","description":"A post that has been edited says so under it. That line is a button now: it opens every version, oldest first, with the content warning and the pictures each one carried. A reader who has…","group":"user","html":"<p>A post that has been edited says so under it. That line is a button now: it\nopens every version, oldest first, with the content warning and the pictures\neach one carried. A reader who has been quoted or replied to can see what\nchanged rather than being told only that something did.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"what-a-post-used-to-say","manual":false,"prev":{"path":"/docs/user-posts-made-with-ai","title":"Posts made with AI"},"next":{"path":"/docs/user-filtering-out-words","title":"Filtering out words"},"parent":"user-reading"},{"slug":"user-filtering-out-words","path":"/docs/user-filtering-out-words","title":"Filtering out words","description":"Some words are not worth reading. Blocking → Filtered words is where you say so — with the accounts you have blocked and muted and the servers you have hidden, because it is the same…","group":"user","html":"<p>Some words are not worth reading. <strong>Blocking → Filtered words</strong> is where you say\nso — with the accounts you have blocked and muted and the servers you have hidden,\nbecause it is the same decision aimed at a word rather than at a person. It is the\nsame list a Mastodon app on your phone writes to: a filter you made there has been\napplying here all along, and this is the first page that shows it.</p>\n<p>A filter is four things:</p>\n<ul>\n<li><p><strong>A name.</strong> Whatever reminds you later what it was for.</p>\n</li>\n<li><p><strong>The words.</strong> One or more; a post matches if <em>any</em> of them appears in its text,\nits content warning, the description of one of its pictures, or an option of a\npoll. Upper and lower case never matter, and a boost is read as the post it\nboosts, so nothing escapes a filter by being boosted. Each word can be marked\n<strong>whole word only</strong>, which is the difference between filtering &quot;cat&quot; and also\nfiltering every &quot;catalogue&quot;.</p>\n</li>\n<li><p><strong>Where it applies.</strong> <strong>My Feed</strong>, <strong>Activities</strong> (your notifications), the\n<strong>Local, Global and hashtag</strong> timelines, <strong>Conversations</strong> (the replies above and\nbelow an opened post), and <strong>Profiles</strong>. Somewhere you did not tick, a matching\npost arrives as usual. Ticking nothing is refused: a filter with no place applies\nnowhere. Two exceptions worth knowing: <strong>list timelines are never filtered</strong>, even\nwith My Feed ticked, and in <strong>Activities</strong> only taking a post out has an effect —\na notification is never folded.</p>\n</li>\n<li><p><strong>What happens to a matching post.</strong> Either it is <strong>folded away</strong> — the post keeps\nits place in the timeline, with the name of the filter where its text would be and\na <strong>Show anyway</strong> button; nothing of the post is on the page until you press it, so\nthe words you filtered cannot be read on the way past. In the Photos and Videos\ngrids the same post shows a covered tile with no picture. Or it is <strong>taken out of\nthe timeline</strong>, and never reaches this app at all. Either way nothing is deleted\nand nobody is told; lift the filter and the post is back as it was.</p>\n<p>A post that carries a content warning of its own is still warned about after you\npress Show anyway: the author&#39;s cover is not yours to lift.</p>\n</li>\n</ul>\n<p>A filter can also be given an expiry — thirty minutes up to a week — after which it\nsimply stops applying. It stays in the list, marked <strong>Expired</strong>, and saving it again\nstarts it over. Editing a filter that is still counting down leaves its expiry alone\nunless you change it.</p>\n<p>Because a filter that removes posts is easy to forget and looks exactly like a\nconversation with a hole in it, the page says at the top which of your filters are\ntaking posts away right now, and where.</p>\n<p>Filters are private: they are never sent to another server, and they change nothing\nfor anybody else reading the same post.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"filtering-out-words","manual":false,"prev":{"path":"/docs/user-what-a-post-used-to-say","title":"What a post used to say"},"next":{"path":"/docs/user-managing-your-account","title":"Managing your account"},"parent":null},{"slug":"user-managing-your-account","path":"/docs/user-managing-your-account","title":"Managing your account","description":"(in the account menu at the foot of the sidebar) has six groups: Profile and privacy, Reading, Notifications, Your posts, Apps and account and Help. Pick a group on the left (at the top on…","group":"user","html":"<h2 id=\"settings\">Settings</h2>\n<p> (in the account menu at the foot of the sidebar) has six groups:\n<strong>Profile and privacy</strong>, <strong>Reading</strong>, <strong>Notifications</strong>, <strong>Your posts</strong>, <strong>Apps\nand account</strong> and <strong>Help</strong>. Pick a group on the left (at the top on a phone) to\nsee its settings, or type into <strong>Find a setting</strong> to search all of them at once.\nEvery change is saved as you make it; there is no Save button to forget, except\nin a form you fill in, such as the portfolio.</p>\n<h2 id=\"pronouns-and-a-support-link\">Pronouns and a support link</h2>\n<p> Two of the four profile fields on <strong>Edit\nprofile</strong> have boxes of their own, because this app draws them differently: the\npronouns appear beside your name rather than in the table at the bottom, and a\nsupport address (<code>https://…</code>) becomes a button on your profile. They are still\nordinary profile fields underneath, so Mastodon and the rest show them in their\ntable as they always did — and if you already wrote a row called &quot;Pronouns&quot; by\nhand, it is picked up as one.</p>\n<h2 id=\"likes-and-followers\">Likes and followers</h2>\n<p> You are not shown how many likes, dislikes, boosts\nor replies anything has, or how many times a video was watched — not on your\nposts, not on anybody else&#39;s — and\nother people&#39;s profiles show <strong>Followers</strong> without a number. A number next\nto a post is a score, and a score is pressure.\n<strong>Settings → Reading → Likes and followers → Show the numbers</strong> brings them back. It\nbelongs to your account, so your phone apps follow it too: they are sent\nzero for each of a post&#39;s numbers while they are hidden. Who liked or boosted a\npost is still there to look at, and so is every reply; your own follower\ncount, following and post counts are not hidden — your profile, Statistics\nand your phone apps all tell you how many people follow you.</p>\n<h2 id=\"sound-and-touch\">Sound and touch</h2>\n<p> <strong>Settings → Reading → Sound and touch</strong> has three switches:\n<strong>Play sounds</strong> (a tick on a like, a breath of air when a post goes out, a\nchime when a direct message arrives; off until you turn it on, with\n<strong>Listen</strong> to hear them first), <strong>Vibrate</strong> (a short tap on a phone; on\nunless you turn it off, and off whenever your system asks for less motion)\nand <strong>Start videos with sound</strong> (Shorts; on unless you turn it\noff). All three belong to the device you are on, not to your account.</p>\n<h2 id=\"profile\">Profile</h2>\n<p> <strong>My profile</strong> (behind your portrait at the bottom of the\nsidebar) → <strong>Edit profile</strong>: a banner (upload one or give the address of\none), a bio, and up to four name/value fields shown under it — your website,\nyour pronouns, where you work. All of it is shared with other servers. The\npronouns and the support link are two of those four, and the editor shows\nhow many are used (&quot;2 of 4 fields used&quot;): <strong>Add field</strong> goes away when\nthere is no room left, and a fifth field is refused with a message rather\nthan dropped. A row with only one half filled in is dropped;\nemptying the table and saving removes it from your profile everywhere.</p>\n<h2 id=\"your-nextcloud-profile-page\">Your Nextcloud profile page</h2>\n<p> The native <code>/u/username</code> page shows your\ncustom Aloha Social banner across the profile header, behind your profile picture,\nand your posts below. The banner starts at the top of the native profile\ncontent and meets the profile details without an extra coloured strip.\nWithout a native profile header, the banner appears at\nthe top of the Aloha Social section. Its <strong>Posts</strong>, <strong>My Feed</strong>, <strong>Local</strong> and\n<strong>Global</strong> tabs read Aloha Social&#39;s feeds; <strong>My Feed</strong> is available only on your\nown profile. This page is for reading. To publish, open the Aloha Social app.</p>\n<h2 id=\"missing-pictures-on-older-remote-posts\">Missing pictures on older remote posts</h2>\n<p> If a federated post shows its text\nbut none of its pictures, an administrator can run\n<code>occ social:media:recover --dry-run</code> to list posts whose stored ActivityPub\noriginal still names attachments. Run <code>occ social:media:recover</code> to fetch\nthose attachments and restore the post&#39;s media and Photos index. The command\nonly examines remote posts with an empty attachment list; posts with no\nattachment in their original are left alone. <code>--limit=N</code> bounds how many\nposts are examined in one run. A failed download is reported and can be\nretried by running the command again.</p>\n<h2 id=\"verified-links\">Verified links</h2>\n<p> A field whose value is a full web address — written out,\nstarting with <code>http://</code> or <code>https://</code> — can carry a <strong>verified tick</strong>, and\nthe editor shows where each of yours stands: verified and when it was\nproved, not verified yet, or, for a bare <code>example.org</code>, that nothing written\nthat way can be verified at all.</p>\n<p>To earn one, put a link back to your profile on that page:\n<code>&lt;a rel=&quot;me&quot; href=&quot;https://your-server/@you&quot;&gt;…&lt;/a&gt;</code> anywhere in its HTML, or\n<code>&lt;link rel=&quot;me&quot; href=&quot;…&quot;&gt;</code> in its <code>&lt;head&gt;</code>. <code>me</code> only has to be one of the\n<code>rel</code> words, and a trailing slash or a <code>#fragment</code> on the address makes no\ndifference. The editor shows the exact line to paste, with a copy button, as\nsoon as a value looks like an address.</p>\n<p>This server fetches the page itself, in the background, at most once a day\nper account and only over http or https, and marks the field when it finds\nthe link back. A page it cannot reach is left unverified and asked again\nlater; a page that stops linking back loses the tick. Editing a field&#39;s value\ndrops that field&#39;s tick straight away — the tick belongs to the address, not\nto the row — and it returns once the page at the new address has been\nchecked. Your other fields keep theirs.</p>\n<h2 id=\"featured-hashtags\">Featured hashtags</h2>\n<p> <strong>Settings → Profile and privacy → Featured hashtags</strong> decides which tags sit under\nyour bio — up to ten, and anybody reading your profile can click one to see what you\nposted under it. It opens with the hashtags you post with most and have not featured\nyet, so you pick from your own writing rather than guessing; anything else goes in\nthe box beside them, with or without the <code>#</code>. The <strong>×</strong> on a row stops featuring that\ntag and does nothing else — your posts keep their hashtags. Your own profile links\nhere from where the tags are shown, whether you feature any or not.</p>\n<h2 id=\"blocking-and-muting\">Blocking and muting</h2>\n<p> Both are in the menu on an account&#39;s profile.\n<strong>Block</strong> severs the relationship in both directions, hides the account\neverywhere, and tells the other server (unless the administrator turned\nthat off). <strong>Mute</strong> hides the account from your timelines and notifications\nwithout it ever knowing. <strong>Blocking</strong>, under <strong>Settings</strong>\nin the sidebar, lists both with unblock and unmute inline.</p>\n<h2 id=\"follow-requests\">Follow requests</h2>\n<p> When your account is locked, people asking to follow\nyou appear under <strong>Follow requests</strong> in the sidebar — <strong>Accept</strong> or\n<strong>Reject</strong> — and on the Nextcloud bell. Locking the account itself is the\n<strong>Approve who follows you</strong> switch under <strong>Settings → Profile and privacy</strong>, which\nis <code>locked</code> on <code>PATCH /api/v1/accounts/update_credentials</code> underneath.</p>\n<h2 id=\"reporting\">Reporting</h2>\n<p> <strong>Report</strong> in a post&#39;s menu sends the post, with an optional\nnote, to the moderators of this instance. From the web client it is never\nsent to the reported account or their server.</p>\n<h2 id=\"your-year\">Your year</h2>\n<p> <code>GET /api/v1/annual_reports</code> serves what Mastodon calls\n<code>#Wrapstodon</code>: one report per year you wrote anything in, with twelve months\nof what you posted and who arrived, the hashtags you used most, your three\nposts that travelled furthest, and a word for how you use the account. It is\nworked out from the posts already here whenever it is asked for, so there is\nnothing to wait for and nothing to go stale. The web client has no page for\nit yet; a phone client that has the feature shows it.</p>\n<h2 id=\"who-may-quote-your-post\">Who may quote your post</h2>\n<p> A post&#39;s menu has <strong>Quotes of this post</strong> on\nyour own posts. The top half is who may quote it from now on — anybody, the\npeople who follow you, or nobody but you — and the bottom half is who already\nhas, with a button that detaches one. The two are separate on purpose:\nchanging the setting does not take back a quote somebody has already posted\nand other people have read. Detaching tells the other server, which then\nshows the quote as withdrawn; the post itself is theirs and stays where it is.</p>\n<h2 id=\"authorized-apps\">Authorized apps</h2>\n<p> <strong>Settings → Apps and account → Authorized apps</strong> lists every app you have\nsigned in to with this account — a phone client, a cross-poster, anything\nthat asked — with what it may do, when you granted it and when it was last\nused. <strong>Sign this app out</strong> takes the key back, and the app asks you to sign\nin again the next time you open it. It is the page to open after losing a\nphone, and the only page where signing an app out does not depend on still\nhaving the app.</p>\n<h2 id=\"export-and-migration\">Export and migration</h2>\n<p> The whole move, in order, is one page:\n<a href=\"/docs/moving\">Moving.md</a>. <strong>Migration</strong> (in the account menu at the foot of\nthe sidebar, a page of its own) has these sections.\n<strong>Export</strong> downloads a zip of your profile, follows, followers, blocks,\nmutes, lists, blocked domains, bookmarks, likes and every post you wrote — your private key is\ndeliberately not in it. <strong>Import</strong> reads such an archive (or a Nextcloud\naccount export) back in without deleting anything; posts in it are listed,\nnot published again. The third section imports the follows from another\nnetwork&#39;s export — a <code>following_accounts.csv</code>, or Pixelfed&#39;s\n<code>pixelfed-following.json</code>.</p>\n<h2 id=\"one-list-at-a-time-out\">One list at a time, out</h2>\n<p> Under the Export button, <strong>Or one list at a\ntime</strong> downloads your follows, your followers, your blocks, your mutes,\nyour lists, your bookmarks or your blocked domains as a single CSV, each\nwritten the way Mastodon writes it. It is\nthe same content as the files inside the zip, for when the other end wants\none file rather than an archive. The followers file is a record rather than\nsomething an import can re-create: a follower follows you again, or their\nserver is told by the move.</p>\n<h2 id=\"blocks-mutes-lists-bookmarks-and-blocked-domains-in\">Blocks, mutes, lists, bookmarks and blocked domains, in</h2>\n<p> <strong>Bring your\nblocks, mutes, lists, bookmarks and blocked domains</strong> reads the other files\nfrom the same export. Bookmarks are the addresses of posts: each is fetched\nfrom the server it lives on and marked here, for you alone — if it is a\npost you may read; the others are listed as not imported. A blocked\ndomain hides a whole server from you, as it did there. Blocks and mutes are decisions\nyour account makes on its own, so they apply as soon as the file is read —\nand a block federates, exactly as blocking somebody from here does. Do the\nfollows first and the lists after: a list here can only hold accounts you\nfollow, as on Mastodon, so anybody you have not followed again yet is counted\nas skipped rather than followed by a button that says lists. A list you\nalready have is filled rather than made a second time, and a list that\nfollows a Nextcloud group is left alone — its members are the group&#39;s.</p>\n<h2 id=\"moving-in-from-another-server\">Moving in from another server</h2>\n<p> The quickest way in is the first thing\non the <strong>Migration</strong> page: type the handle of your old account\n(<code>@you@mastodon.example</code>) and press <strong>Look it up</strong>. You are shown who that\nis, how many accounts it follows and how many posts it has, and whether its\nserver lets those be read — Mastodon hides them if you turned on <em>Hide your\nsocial graph</em>, and Pixelfed always does; the file imports below are for\nthat case. Press <strong>Move here</strong> and this account is marked as also being\nthat one, and in the background everyone the old account follows is followed\nfrom here and its public posts are written here as yours, dated when you\nwrote them. The list at the top of the page shows where it has got to, and\nonce it is done, <strong>Copy newer posts</strong> under it runs the copy again for\nwhatever you wrote on the old account since — only what is new is written.\nNothing is sent to anybody; your followers stay where they are until the\nlast step, which is done on the old server and which the page tells you\nabout when the run is done: on Mastodon, <em>Preferences → Account → Move to a\ndifferent account</em>, and enter your handle here. If the old server is Aloha\nSocial too, the page offers <strong>Finish the move from here</strong> instead: you are\nsent to your old Nextcloud to log in and agree, and your followers are moved\nwithout a visit to its settings.</p>\n<h2 id=\"naming-your-old-account\">Naming your old account</h2>\n<p> Your old server will not send your followers\nhere until this account says it is also you. <strong>Migration →\nAccounts you also answer to</strong> is where you say it: type the old account&#39;s\nhandle (<code>@you@pixelfed.social</code>) and press Add. Nothing is sent to anybody — it is a note this server keeps about an\naccount it owns — and you can take it off again whenever you like. The\nwizard above sets it for you.</p>\n<h2 id=\"moving-away\">Moving away</h2>\n<p> The last section of the <strong>Migration</strong> page moves this\naccount to another server. First, on the new account, name this one as an\naccount you also answer to — on Mastodon, <em>Preferences → Account → Moving\nfrom a different account</em> — then type the new account&#39;s handle here, type\nyour own handle to confirm, and give your password when asked. Every server\nthat knows you is told to follow the new account instead, and this one is\nmarked as moved: it shows where you went, you cannot post or follow from it\nwhile it stays moved, and your posts stay where they are, because a move\ncarries the followers and never the content. You can move again after\nthirty days. <strong>Undo the move</strong> takes the redirect off and lets you post and\nfollow from here again; your followers do not come back by themselves,\nbecause their servers acted on the move when it arrived.</p>\n<h2 id=\"bringing-your-posts\">Bringing your posts</h2>\n<p> The fourth section of the <strong>Migration</strong> page reads\nthe export from your old server — this app&#39;s own archive, Mastodon&#39;s or\nGoToSocial&#39;s <code>outbox.json</code>, or Pixelfed&#39;s <code>pixelfed-statuses.json</code> — and\nwrites the posts in it here as yours, dated when you wrote them, with their\npictures. Nothing is sent to anybody: none of it is published again, so the\npeople who follow you do not receive years of posts in one afternoon. Boosts\nand direct messages are left out, and a reply keeps the post it answers when\nthe file holds both. A picture the export names only by its address is\nfetched from the old server, which has to still be running; the switch above\nthe button turns that off. At most 2000 posts a run — upload the same file\nagain to carry on — and an archive too large for a browser can be imported by\nan administrator with <code>occ social:account:import-posts</code>.</p>\n<h2 id=\"coming-from-instagram\">Coming from Instagram</h2>\n<p> The same button reads an Instagram archive. Ask\nInstagram to download your information and <strong>choose JSON</strong>: the HTML download\nis a set of web pages with the posts taken out, and this says so rather than\nfailing quietly. Your posts and reels arrive with their pictures, their\ncaptions and the hashtags you wrote in them. Two things are worth knowing\nbefore you press it. An Instagram post does not record who could see it, so\nevery one of them is posted here with <strong>your own default visibility</strong> — set\nthat first, in <strong>Settings → Profile and privacy</strong>, if you would rather they were not\npublic. And <strong>what Instagram showed for only a day, your archived posts and\nanything you deleted are not imported</strong>: you put those away on purpose.</p>\n<h2 id=\"leaving\">Leaving</h2>\n<p> <strong>Settings → Apps and account → Delete your Aloha Social account</strong> deletes your fediverse\naccount and keeps your Nextcloud one. Everything you posted goes, your\nfollowers and the people you follow are let go, and every server that knew\nthe account is told it is gone — a post already on somebody else&#39;s server is\ndeleted by asking that server to delete it, which almost all of them do and\nnone of them can be made to. You are asked to type your handle first, because\nit cannot be undone; take an archive from <strong>Migration → Export</strong>\nfirst if you might want one. Afterwards you are back at the setup screen and\ncan make a new account straight away, under a different handle: the old one\nis held for an hour so that nobody can take it the moment you let it go.\nDeleting the Nextcloud user does the same thing to the Aloha Social account along\nthe way.</p>\n","toc":[{"id":"settings","text":"Settings","level":2},{"id":"pronouns-and-a-support-link","text":"Pronouns and a support link","level":2},{"id":"likes-and-followers","text":"Likes and followers","level":2},{"id":"sound-and-touch","text":"Sound and touch","level":2},{"id":"profile","text":"Profile","level":2},{"id":"your-nextcloud-profile-page","text":"Your Nextcloud profile page","level":2},{"id":"missing-pictures-on-older-remote-posts","text":"Missing pictures on older remote posts","level":2},{"id":"verified-links","text":"Verified links","level":2},{"id":"featured-hashtags","text":"Featured hashtags","level":2},{"id":"blocking-and-muting","text":"Blocking and muting","level":2},{"id":"follow-requests","text":"Follow requests","level":2},{"id":"reporting","text":"Reporting","level":2},{"id":"your-year","text":"Your year","level":2},{"id":"who-may-quote-your-post","text":"Who may quote your post","level":2},{"id":"authorized-apps","text":"Authorized apps","level":2},{"id":"export-and-migration","text":"Export and migration","level":2},{"id":"one-list-at-a-time-out","text":"One list at a time, out","level":2},{"id":"blocks-mutes-lists-bookmarks-and-blocked-domains-in","text":"Blocks, mutes, lists, bookmarks and blocked domains, in","level":2},{"id":"moving-in-from-another-server","text":"Moving in from another server","level":2},{"id":"naming-your-old-account","text":"Naming your old account","level":2},{"id":"moving-away","text":"Moving away","level":2},{"id":"bringing-your-posts","text":"Bringing your posts","level":2},{"id":"coming-from-instagram","text":"Coming from Instagram","level":2},{"id":"leaving","text":"Leaving","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":[{"path":"/docs/user-bluesky","title":"Bluesky","description":"If the administrator has switched Bluesky on, your account is a Bluesky account too, hosted here: your handle there is yourname.<this server>, and anybody on Bluesky who looks it up sees…","parent":true}],"anchor":"managing-your-account","manual":false,"prev":{"path":"/docs/user-filtering-out-words","title":"Filtering out words"},"next":{"path":"/docs/user-bluesky","title":"Bluesky"},"parent":null},{"slug":"user-bluesky","path":"/docs/user-bluesky","title":"Bluesky","description":"If the administrator has switched Bluesky on, your account is a Bluesky account too, hosted here: your handle there is yourname.<this server>, and anybody on Bluesky who looks it up sees…","group":"user","html":"<p>If the administrator has switched Bluesky on, your account is a Bluesky account\ntoo, hosted here: your handle there is <code>yourname.&lt;this server&gt;</code>, and anybody on\nBluesky who looks it up sees your profile and your public posts, can follow you\nand like, reply to and quote what you wrote. Nothing is asked of you — no\nBluesky account, no password, no switch.</p>\n<p>Every <strong>public</strong> post goes to Bluesky as you publish it. Bluesky posts hold 300\ncharacters, so a longer post is cut at a word before 280 and the rest is a link\nto the post here; the composer tells you so under the counter. The first four\npictures go with it, with their descriptions; a content warning becomes a\nwarning label and a &quot;Content warning:&quot; line; a poll becomes its question and\noptions with a link to vote here. These added words are in the language of\nyour post. An edit within five minutes replaces the Bluesky copy; a\nlater one leaves the Bluesky copy as it was, with its link leading to the\ncurrent text here. Deleting a post deletes it there too. Followers-only,\nunlisted and direct posts never go to Bluesky, which the audience menu in the\ncomposer says beside each of them, and a reply to a post that is not on\nBluesky goes out as a post with a link to what it answers.</p>\n<p>Your profile page shows both handles under your name, each with a Copy button,\nand the Bluesky one leads to your profile on bsky.app. <strong>Settings → Apps and\naccount → Bluesky</strong> shows the handle and the DID — the permanent identifier your Bluesky\naccount has — and offers a <strong>recovery phrase</strong>: twelve words that are a key of\nyour own on that identifier: on an identifier this server made, it ranks\nsecond, after the server&#39;s; on one you brought here, your own keys rank first,\nand they keep their places whatever the server changes later. They are shown once\nand never stored, so write them down; &quot;Create a new recovery phrase&quot; replaces\nthem, and the old words stop working. You will not need the phrase in ordinary\nuse. What it can do: the key it stands for can sign a change to your identifier\nat the PLC directory without this server — give it another signing key, point it\nat another Bluesky server, drop this server&#39;s key. That is how you take your\nBluesky account with you if this server is ever gone. <strong>Download the recovery\ntool</strong> keeps one HTML page that does it in your browser, step by step, from a\nsaved copy and without this server; open it with your words and the download\nbelow (<a href=\"/docs/moving-if-this-server-goes-away#if-this-server-goes-away\">Moving.md</a>; the <code>goat</code>\ncommand-line tool can do the same). Anyone who has the words can do the same,\nso keep them where only you can find them.</p>\n<p>Other Bluesky tools do not read the words themselves, so the same dialog also\nshows the key they stand for: the private key in the form the <code>goat</code> command-line\ntool takes (<code>z…</code>) and as hex, and the public key (<code>did:key:…</code>) that your\nidentifier lists. Keep the words; the key lines are the same secret written\ndifferently, and the words can be turned back into them offline\n(<a href=\"/docs/atproto\">how</a>).\nThe server&#39;s key ranks above yours: for 72 hours the server can undo a change\nmade with the phrase, a move to another server included.</p>\n<p><strong>Who controls your Bluesky identifier</strong>, in the same section, lists the keys\nthat can change where your identifier points, as the PLC directory has them,\nhighest first: this server, your recovery phrase, or a key this server does not\nknow. For 72 hours after a change, a key ranking above the one that made it can\nundo it; while that is so, the panel says until when and by which key.</p>\n<p><strong>Download your Bluesky account</strong>, in the same section, gives you the account as\nfiles after your password: your repository (every post, like, follow and the\nprofile, in the CAR format other Bluesky servers import), the pictures and videos,\nthe history of your identifier from the PLC directory, and a README with the\nsteps to move the account with your recovery phrase, even when this server is gone;\nit carries the recovery tool too. The archive from the <strong>Migration</strong> page holds the same files\nunder <code>social/bluesky/</code>.</p>\n<p>The post menu&#39;s <em>Delivery status</em> shows whether a post is on Bluesky and opens\nit there.</p>\n<p><strong>Reading Bluesky.</strong> Type a Bluesky handle — <code>alice.bsky.social</code>, no <code>@</code> —\ninto search, the follow box or the composer&#39;s mention picker: the account\nappears with a butterfly badge next to its name, its profile page is\n<code>/@alice.bsky.social</code>, and following it is accepted at once (Bluesky has no\nfollow requests). Their posts then come into your home feed within minutes,\nbadged but otherwise ordinary: like, boost, reply and quote them as you would\nany post — a like or boost reaches Bluesky, a reply lands in their thread\nthere, and a quote shows their post inside yours. Pictures and standard video\nembeds use the usual gallery and player. Audio is playable in the post; files\nfrom supported third-party Bluesky embeds appear as named downloads. Such files\nare streamed from the public PDS when opened, rather than fetched while the\nfeed loads. A post they delete on\nBluesky disappears here too, once the server&#39;s regular check reaches it. If you limit who may quote a post\nof yours (followers only, or nobody), nobody on Bluesky can quote it —\nBluesky has no &quot;followers only&quot;. <em>Open on Bluesky</em> in the post menu leads to the post on bsky.app. When\nsomebody on Bluesky follows you, likes, boosts, answers or mentions you, it\nshows in Activities like anything else, under your notification policy.</p>\n<p><strong>Labels and reports.</strong> Bluesky&#39;s moderation service labels posts, and its\nlabels always apply here: a post it hides never arrives, and adult or\nupsetting pictures come with a warning. Under <em>Settings → Blocking → Bluesky\nlabelers</em> you can add other labelers by their handle and choose, label by\nlabel, whether it does nothing, shows a warning, or hides the post. When you\nreport a Bluesky account or post, <em>Also report to Bluesky&#39;s moderation\nservice</em> passes the report on — sent by this server, not in your name.</p>\n<p><strong>Bluesky apps.</strong> You can use the Bluesky app, or any other Bluesky client,\nwith this account. In <em>Settings → Apps and account → Bluesky</em> make an\n<strong>app password</strong> and copy it — it is shown once. In the app, choose to sign in with\na different hosting provider, give this server&#39;s address, then your Bluesky\nhandle and the app password. This is not your Nextcloud password; never enter\nthat in a Bluesky client. What you post, like or follow there happens\nhere too, as if you had done it in Aloha Social; blocks stay here and cannot\nbe made from the app. Revoking the app password signs the app out.</p>\n<p><strong>Pausing.</strong> <em>Be on Bluesky</em> in Settings → Apps and account → Bluesky switches\nyour presence there off, after asking: nothing new is published, Bluesky is told the\naccount is inactive, Bluesky apps are signed out, and what you had posted comes back\nwhen you switch it on again — same handle, same identity. What you write while it is\noff never reaches Bluesky.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"bluesky","manual":false,"prev":{"path":"/docs/user-managing-your-account","title":"Managing your account"},"next":{"path":"/docs/user-keyboard-shortcuts","title":"Keyboard shortcuts"},"parent":"user-managing-your-account"},{"slug":"user-keyboard-shortcuts","path":"/docs/user-keyboard-shortcuts","title":"Keyboard shortcuts","description":"Press ? anywhere, or open Settings → Help → Keyboard shortcuts, for the list. Shortcuts are off while you are typing in a field or the composer, while a modifier key is held, and while a…","group":"user","html":"<p>Press <code>?</code> anywhere, or open <strong>Settings → Help → Keyboard shortcuts</strong>, for the list.\nShortcuts are off while you are typing in a field or the composer, while a\nmodifier key is held, and while a dialog such as the picture viewer is open.\nThe switch <strong>Use keyboard shortcuts</strong> on the same Settings page turns them off\naltogether; the choice is kept with your account. Turning keyboard shortcuts\noff in Nextcloud&#39;s own <strong>Personal settings → Accessibility</strong> turns them off here\ntoo.</p>\n<p><code>l</code>, <code>b</code>, <code>r</code> and <code>o</code> act on the post <code>j</code> or <code>k</code> moved to, and only while it is\nstill the one you are on: once you click somewhere else or scroll it out of\nview, no post is in focus, and the next <code>j</code> starts from the post at the top of\nthe screen.</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Does</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>j</code></td>\n<td>Next post</td>\n</tr>\n<tr>\n<td><code>k</code></td>\n<td>Previous post</td>\n</tr>\n<tr>\n<td><code>l</code> or <code>f</code></td>\n<td>Like the post in focus</td>\n</tr>\n<tr>\n<td><code>b</code></td>\n<td>Boost the post in focus</td>\n</tr>\n<tr>\n<td><code>r</code></td>\n<td>Reply to the post in focus</td>\n</tr>\n<tr>\n<td><code>o</code> or <code>Enter</code></td>\n<td>Open the post in focus</td>\n</tr>\n<tr>\n<td><code>n</code></td>\n<td>Write a new post</td>\n</tr>\n<tr>\n<td><code>g</code></td>\n<td>Go to the home timeline</td>\n</tr>\n<tr>\n<td><code>?</code></td>\n<td>Show these shortcuts</td>\n</tr>\n</tbody></table></div>\n<p>On a video&#39;s own page the video player has keys of its own, the ones video\nsites use. They work wherever the focus is on that page, except in a text\nfield or behind a dialog; in the small player they work while it has the\nfocus. <code>j</code>, <code>k</code>, <code>l</code> and <code>f</code> are the player&#39;s there, not the timeline&#39;s, and\nthe up and down arrows change the volume only while the player has the focus,\nso they still scroll the page otherwise. The same switches turn them off.</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Does</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>k</code> or <code>Space</code></td>\n<td>Play or pause</td>\n</tr>\n<tr>\n<td><code>j</code> / <code>l</code></td>\n<td>Back / forward 10 seconds</td>\n</tr>\n<tr>\n<td><code>←</code> / <code>→</code></td>\n<td>Back / forward 5 seconds</td>\n</tr>\n<tr>\n<td><code>↑</code> / <code>↓</code></td>\n<td>Louder / quieter, while the player has the focus</td>\n</tr>\n<tr>\n<td><code>m</code></td>\n<td>Sound off or on</td>\n</tr>\n<tr>\n<td><code>f</code></td>\n<td>Full screen</td>\n</tr>\n<tr>\n<td><code>c</code></td>\n<td>Subtitles on or off</td>\n</tr>\n<tr>\n<td><code>&lt;</code> / <code>&gt;</code></td>\n<td>Slower / faster</td>\n</tr>\n<tr>\n<td><code>0</code> … <code>9</code></td>\n<td>Jump to the start, or to 10% … 90% of the video</td>\n</tr>\n</tbody></table></div>\n<p><code>Enter</code> on a focused button or link still presses it — the shortcut only\napplies where nothing else claims the key. Nextcloud&#39;s own <strong>Skip to main\ncontent</strong>, the first Tab stop on every page and visible only while it has the\nfocus, jumps past the sidebar into the page; each page carries one top-level\nheading to jump to.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/User-Guide.md","sections":null,"anchor":"keyboard-shortcuts","manual":false,"prev":{"path":"/docs/user-bluesky","title":"Bluesky"},"next":null,"parent":null},{"slug":"for-you","path":"/docs/for-you","title":"For You recommendations","description":"This page describes the current ranked For You feed, not the earlier hashtag- only design. It is an optional web-app timeline built from content already available to the instance and…","group":"for-you","html":"<p>This page describes the current ranked For You feed, not the earlier hashtag-\nonly design. It is an optional web-app timeline built from content already\navailable to the instance and bounded remote discovery. It does not promise\nthat every remote post has been indexed or that the ranking is better than a\nchronological feed.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/For-You.md","sections":[{"path":"/docs/for-you-what-readers-see","title":"What readers see","description":"The current web UI does not let readers add or select topics manually. That is a separate future capability. The ranker does not require manually chosen topics: it can use content…","parent":false},{"path":"/docs/for-you-how-the-feed-is-assembled","title":"How the feed is assembled","description":"Candidate sources include learned/followed hashtag activity, classified post content, followed accounts, local trends, second-degree follow relationships, cached posts from saved Bluesky…","parent":false},{"path":"/docs/for-you-signals-consent-and-privacy","title":"Signals, consent and privacy","description":"The feed can learn from explicit interactions and supported reading actions, including skips and measured video playback. Passive time spent with a post on screen is neutral; a dwell timer…","parent":false},{"path":"/docs/for-you-api-and-operations","title":"API and operations","description":"The web app uses the ranked endpoint when the administrator enables it. The Mastodon-compatible /api/v1/timelines/interests endpoint remains a separate legacy response for clients that use…","parent":false},{"path":"/docs/for-you-evaluation-and-known-limits","title":"Evaluation and known limits","description":"The deterministic offline evaluator uses synthetic profiles and posts. It is useful for catching regressions in candidate eligibility, diversity and hard filters; it is not a measure of…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/for-you-what-readers-see","title":"What readers see"},"parent":null},{"slug":"for-you-what-readers-see","path":"/docs/for-you-what-readers-see","title":"What readers see","description":"The current web UI does not let readers add or select topics manually. That is a separate future capability. The ranker does not require manually chosen topics: it can use content…","group":"for-you","html":"<ul>\n<li>For You is available beside My Feed and the local/federated timelines when\nthe administrator enables Ranked For You.</li>\n<li>Photos, Videos and Shorts can use the same personalized ranking with their\nmedia constraints. When eligible personalized candidates are sparse, the\nfeed may use bounded discovery or popular cached media to fill a page.</li>\n<li>Post menus provide recommendation feedback such as hiding a post, seeing\nmore from an author, or seeing less like similar content. These actions do\nnot follow, mute or block anyone.</li>\n<li>Explanations and temporary guidance are tied to the personalized feed\ncontext. A recommendation reason does not leak into ordinary timelines.</li>\n</ul>\n<p>The current web UI does <strong>not</strong> let readers add or select topics manually.\nThat is a separate future capability. The ranker does not require manually\nchosen topics: it can use content classification, followed accounts, freshness,\ndiscovery and cached sources to build a useful candidate pool while learning is\noff or sparse.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/For-You.md","sections":null,"anchor":"what-readers-see","manual":false,"prev":{"path":"/docs/for-you","title":"For You recommendations"},"next":{"path":"/docs/for-you-how-the-feed-is-assembled","title":"How the feed is assembled"},"parent":null},{"slug":"for-you-how-the-feed-is-assembled","path":"/docs/for-you-how-the-feed-is-assembled","title":"How the feed is assembled","description":"Candidate sources include learned/followed hashtag activity, classified post content, followed accounts, local trends, second-degree follow relationships, cached posts from saved Bluesky…","group":"for-you","html":"<p>Candidate sources include learned/followed hashtag activity, classified post\ncontent, followed accounts, local trends, second-degree follow relationships,\ncached posts from saved Bluesky feeds and a bounded public discovery sample.\nSaved-feed candidates are read from the local cache; loading a page does not\nwait for an AppView request. The system applies visibility, moderation, language\nand hide filters before returning posts.</p>\n<p>One ranking combines relevance, freshness, follow relationships, explicit\nfeedback and (only with separate consent) behavioral signals. Re-ranking limits\nrepeated authors, topics, formats and similar stories while alternatives are\navailable. Those limits relax when the available pool is too small, to avoid\nturning diversity into an empty feed. Photos, Videos, Shorts and other media\nscopes have separate cursors and snapshots.</p>\n<p>The implementation is deliberately bounded: remote discovery has a shared\nrequest budget, feed snapshots expire, and pagination uses opaque cursors.\nUnderfilled pages can schedule background refresh without holding the current\nrequest open. A failed or stale cursor asks the client to refresh rather than\nsilently repeating a different ranking.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/For-You.md","sections":null,"anchor":"how-the-feed-is-assembled","manual":false,"prev":{"path":"/docs/for-you-what-readers-see","title":"What readers see"},"next":{"path":"/docs/for-you-signals-consent-and-privacy","title":"Signals, consent and privacy"},"parent":null},{"slug":"for-you-signals-consent-and-privacy","path":"/docs/for-you-signals-consent-and-privacy","title":"Signals, consent and privacy","description":"The feed can learn from explicit interactions and supported reading actions, including skips and measured video playback. Passive time spent with a post on screen is neutral; a dwell timer…","group":"for-you","html":"<p>The feed can learn from explicit interactions and supported reading actions,\nincluding skips and measured video playback. Passive time spent with a post on\nscreen is neutral; a dwell timer is not treated as evidence of interest.\nExisting legacy aggregates may still contain older dwell-based signals and\ndecay over time.</p>\n<p>Behavioral learning has its own user consent and can be paused or reset. The\nadministrator&#39;s Ranked For You switch is separate: it controls availability of\nthe ranked endpoint and does not silently opt a person into behavioral\nlearning. Learned data is private to the account and is not federated. Export,\nreset and account deletion are owner-scoped.</p>\n<p>Qualified exposure history is stored only with behavioral consent. It uses\nowner-scoped keyed fingerprints rather than raw post identifiers or story\nterms, and expires after 30 days. Sensitive-topic fingerprints are excluded.\nFeed snapshots and recommendation explanations are short-lived serving data,\nseparate from the shared status index.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/For-You.md","sections":null,"anchor":"signals-consent-and-privacy","manual":false,"prev":{"path":"/docs/for-you-how-the-feed-is-assembled","title":"How the feed is assembled"},"next":{"path":"/docs/for-you-api-and-operations","title":"API and operations"},"parent":null},{"slug":"for-you-api-and-operations","path":"/docs/for-you-api-and-operations","title":"API and operations","description":"The web app uses the ranked endpoint when the administrator enables it. The Mastodon-compatible /api/v1/timelines/interests endpoint remains a separate legacy response for clients that use…","group":"for-you","html":"<p>The web app uses the ranked endpoint when the administrator enables it. The\nMastodon-compatible <code>/api/v1/timelines/interests</code> endpoint remains a separate\nlegacy response for clients that use it.</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Method</th>\n<th>Route</th>\n<th>Purpose</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>GET</td>\n<td><code>/api/v1/recommendations/timeline</code></td>\n<td>Ranked page, media scope, coverage state and cursor</td>\n</tr>\n<tr>\n<td>GET</td>\n<td><code>/api/v1/recommendations/preferences</code></td>\n<td>Read learning consent and revision state</td>\n</tr>\n<tr>\n<td>PUT</td>\n<td><code>/api/v1/recommendations/learning</code></td>\n<td>Change separate behavioral-learning consent</td>\n</tr>\n<tr>\n<td>POST</td>\n<td><code>/api/v1/recommendations/signals</code></td>\n<td>Record supported, consented interaction signals</td>\n</tr>\n<tr>\n<td>POST</td>\n<td><code>/api/v1/recommendations/feedback</code></td>\n<td>Store reversible post/author/similarity feedback</td>\n</tr>\n<tr>\n<td>DELETE</td>\n<td><code>/api/v1/recommendations/feedback/{feedbackId}</code></td>\n<td>Undo the named feedback action within its window</td>\n</tr>\n<tr>\n<td>POST</td>\n<td><code>/api/v1/recommendations/reset</code></td>\n<td>Clear owner-scoped learned state with revision checking</td>\n</tr>\n<tr>\n<td>GET</td>\n<td><code>/api/v1/recommendations/export</code></td>\n<td>Export supported owner-scoped recommendation data</td>\n</tr>\n<tr>\n<td>GET/PUT</td>\n<td><code>/admin/recommendations</code></td>\n<td>Administrator rollout, learning and discovery switches</td>\n</tr>\n</tbody></table></div>\n<p>The exact request and response schemas are in\n<a href=\"/docs/api\">API.md</a>. The ranked feed uses a persistent\nNextcloud memory cache for page snapshots; a supported shared backend such as\nRedis is recommended for multi-worker installations. Run <code>occ upgrade</code> after\nupdating a release that adds a recommendation migration. See\n<a href=\"/docs/admin-what-to-watch#ranked-for-you-recommendations-switch\">Admin.md</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/For-You.md","sections":null,"anchor":"api-and-operations","manual":false,"prev":{"path":"/docs/for-you-signals-consent-and-privacy","title":"Signals, consent and privacy"},"next":{"path":"/docs/for-you-evaluation-and-known-limits","title":"Evaluation and known limits"},"parent":null},{"slug":"for-you-evaluation-and-known-limits","path":"/docs/for-you-evaluation-and-known-limits","title":"Evaluation and known limits","description":"The deterministic offline evaluator uses synthetic profiles and posts. It is useful for catching regressions in candidate eligibility, diversity and hard filters; it is not a measure of…","group":"for-you","html":"<p>The deterministic offline evaluator uses synthetic profiles and posts. It is\nuseful for catching regressions in candidate eligibility, diversity and hard\nfilters; it is not a measure of real-user satisfaction or production latency.\nSee <a href=\"/docs/evaluation\">ForYouEvaluation.md</a>.</p>\n<p>Weights are not claimed to reproduce Bluesky, Mastodon or another platform.\nRecommendation quality depends on local data, remote synchronization, user\nconsent and available candidate diversity. Manual interest creation, changing\nthe ordering of an already-open feed, and proof of quality with real users are\nnot currently implemented.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/For-You.md","sections":null,"anchor":"evaluation-and-known-limits","manual":false,"prev":{"path":"/docs/for-you-api-and-operations","title":"API and operations"},"next":null,"parent":null},{"slug":"notify","path":"/docs/notify","title":"Notification policy and conversation muting","description":"This page describes the current behavior for deciding which incoming notifications reach a person's Activities and Nextcloud notification channels. It is separate from timeline visibility…","group":"notifications","html":"<p>This page describes the current behavior for deciding which incoming\nnotifications reach a person&#39;s Activities and Nextcloud notification channels.\nIt is separate from timeline visibility: a held notification does not hide the\nunderlying post from a timeline the reader is allowed to view.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Notification-Policy.md","sections":[{"path":"/docs/notify-reader-controls","title":"Reader controls","description":"The web interface does not offer drop. Mastodon-compatible API clients may set it; it is treated as a permanently discarded notification. Readers can also review held senders, accept a…","parent":false},{"path":"/docs/notify-delivery-and-conversation-mutes","title":"Delivery and conversation mutes","description":"When policy holds an incoming notification, it is not raised in Activities and does not generate a Nextcloud bell, push or email notification. Requests can be reviewed separately.…","parent":false},{"path":"/docs/notify-api-surface","title":"API surface","description":"The Mastodon-compatible routes expose notification policies and requests. Social-specific routes manage the always-allowed list and the one-time notice; administrator routes set defaults…","parent":false},{"path":"/docs/notify-related-documentation","title":"Related documentation","description":"What produces a notification, what does not, and how you control it.","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/notify-reader-controls","title":"Reader controls"},"parent":null},{"slug":"notify-reader-controls","path":"/docs/notify-reader-controls","title":"Reader controls","description":"The web interface does not offer drop. Mastodon-compatible API clients may set it; it is treated as a permanently discarded notification. Readers can also review held senders, accept a…","group":"notifications","html":"<p>Under <strong>Settings → Notifications</strong>, readers can choose <strong>Allow</strong> or <strong>Hold for\nreview</strong> for five cases:</p>\n<ul>\n<li>accounts they do not follow;</li>\n<li>accounts that do not follow them;</li>\n<li>accounts less than 30 days old;</li>\n<li>unsolicited private mentions/direct messages;</li>\n<li>accounts limited by the instance.</li>\n</ul>\n<p>The web interface does not offer <code>drop</code>. Mastodon-compatible API clients may\nset it; it is treated as a permanently discarded notification. Readers can\nalso review held senders, accept a sender as always allowed, dismiss a sender,\nor remove a sender from the always-allowed list. A waiting indicator appears\nin Activities and contributes to its navigation count.</p>\n<p>New accounts start with a calm policy unless the administrator changes the\ndefaults. Existing accounts without a stored policy continue to accept\nnotifications as before. The administrator defaults are available through the\nadmin notification-policy API; there is not currently a dedicated admin UI\ncard for them.</p>\n<p>The direct-message audience control is shared with the Bluesky chat declaration\nwhen that integration is enabled. Its choices are Everyone, People you follow,\nand Nobody. Notification policy acceptance can allow a sender through the\nreview filter, but it does not create a follow relationship.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Notification-Policy.md","sections":null,"anchor":"reader-controls","manual":false,"prev":{"path":"/docs/notify","title":"Notification policy and conversation muting"},"next":{"path":"/docs/notify-delivery-and-conversation-mutes","title":"Delivery and conversation mutes"},"parent":null},{"slug":"notify-delivery-and-conversation-mutes","path":"/docs/notify-delivery-and-conversation-mutes","title":"Delivery and conversation mutes","description":"When policy holds an incoming notification, it is not raised in Activities and does not generate a Nextcloud bell, push or email notification. Requests can be reviewed separately.…","group":"notifications","html":"<p>When policy holds an incoming notification, it is not raised in Activities and\ndoes not generate a Nextcloud bell, push or email notification. Requests can be\nreviewed separately. Accepting releases eligible waiting notifications without\nraising them as new alerts; dismissing discards them. Muting a conversation\nsuppresses notifications in that thread while leaving its posts in timelines.\nUnmuting allows later notifications again.</p>\n<p>The same policy rules are applied when the server builds notification pages,\ncounts unread items and decides whether to emit a Nextcloud notification. A\nMastodon <code>muted</code> status field reflects the reader&#39;s actual conversation state.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Notification-Policy.md","sections":null,"anchor":"delivery-and-conversation-mutes","manual":false,"prev":{"path":"/docs/notify-reader-controls","title":"Reader controls"},"next":{"path":"/docs/notify-api-surface","title":"API surface"},"parent":null},{"slug":"notify-api-surface","path":"/docs/notify-api-surface","title":"API surface","description":"The Mastodon-compatible routes expose notification policies and requests. Social-specific routes manage the always-allowed list and the one-time notice; administrator routes set defaults…","group":"notifications","html":"<p>The Mastodon-compatible routes expose notification policies and requests.\nSocial-specific routes manage the always-allowed list and the one-time notice;\nadministrator routes set defaults for new accounts. The API reference documents\nthe current paths, authentication and response fields:\n<a href=\"/docs/api\">API.md — notifications</a>.</p>\n<p>The policy is stored per reader. Accepting or dismissing a sender is a local\ndecision, not an ActivityPub or AT Protocol block. Conversation mutes suppress\nalerts; they do not delete posts, unfollow authors or stop federation.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Notification-Policy.md","sections":null,"anchor":"api-surface","manual":false,"prev":{"path":"/docs/notify-delivery-and-conversation-mutes","title":"Delivery and conversation mutes"},"next":{"path":"/docs/notify-related-documentation","title":"Related documentation"},"parent":null},{"slug":"notify-related-documentation","path":"/docs/notify-related-documentation","title":"Related documentation","description":"What produces a notification, what does not, and how you control it.","group":"notifications","html":"<ul>\n<li><a href=\"/docs/user-who-may-reach-you-and-requests#who-may-reach-you-and-requests\">User guide</a></li>\n<li><a href=\"/docs/mastodon\">Mastodon compatibility</a></li>\n<li><a href=\"/docs/architecture\">Architecture</a></li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Notification-Policy.md","sections":null,"anchor":"related-documentation","manual":false,"prev":{"path":"/docs/notify-api-surface","title":"API surface"},"next":null,"parent":null},{"slug":"moving","path":"/docs/moving","title":"Moving to Aloha Social, and moving away","description":"One page for the whole move, in the order it happens. Each button it names is described on its own in the User Guide and each route in the API reference; this is the order, and what does…","group":"moving","html":"<p>One page for the whole move, in the order it happens. Each button it names\nis described on its own in the <a href=\"/docs/user-managing-your-account#managing-your-account\">User Guide</a> and\neach route in the <a href=\"/docs/api-migration#migration\">API reference</a>; this is the order, and\nwhat does not move.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Moving.md","sections":[{"path":"/docs/moving-what-a-move-is-on-the-fediverse","title":"What a move is, on the fediverse","description":"A move carries followers, never posts. Your old server tells every server that knows you to follow your new account instead; your posts stay where they were written, under the old server's…","parent":false},{"path":"/docs/moving-moving-to-aloha-social","title":"Moving to Aloha Social","description":"Pixelfed cannot do step 3: it has no account migration. Your follows and your posts come over; your followers have to follow you again.","parent":false},{"path":"/docs/moving-moving-away","title":"Moving away","description":"You can move again after thirty days. Undo the move takes the redirect off and lets you post and follow from here again — but your followers do not come back by themselves, because their…","parent":false},{"path":"/docs/moving-your-bluesky-account","title":"Your Bluesky account","description":"If this server puts you on Bluesky too, your Bluesky account is a second account of the same person, and it can move on its own.","parent":false},{"path":"/docs/moving-if-this-server-goes-away","title":"If this server goes away","description":"On the fediverse, an account on a server that is gone cannot be moved: the old server has to send the move. Take the export from Settings → Migration while the server runs; its…","parent":false},{"path":"/docs/moving-what-does-not-move-whatever-you-do","title":"What does not move, whatever you do","description":"Coming to Aloha Social from another server, and leaving again without losing the people who follow you.","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/moving-what-a-move-is-on-the-fediverse","title":"What a move is, on the fediverse"},"parent":null},{"slug":"moving-what-a-move-is-on-the-fediverse","path":"/docs/moving-what-a-move-is-on-the-fediverse","title":"What a move is, on the fediverse","description":"A move carries followers, never posts. Your old server tells every server that knows you to follow your new account instead; your posts stay where they were written, under the old server's…","group":"moving","html":"<p>A move carries <strong>followers</strong>, never posts. Your old server tells every server\nthat knows you to follow your new account instead; your posts stay where they\nwere written, under the old server&#39;s addresses. That is how Mastodon does it\ntoo, and it is the right design: a post is signed by the server it was written\non, and nobody else can re-issue it.</p>\n<p>Two things follow from that. Your new account can <strong>copy</strong> your old posts, as\nnew posts of its own, so your profile here is not empty — but they are copies,\nnothing is sent to anybody, and the replies and boosts on the originals stay on\nthe originals. And the old server has to be <strong>running</strong> for any of this: it\nsends the move, and it serves your posts and the people you follow. An account\non a server that is gone cannot be moved; only a follows file exported in time\nsurvives it.</p>\n<p>The same happens in the other direction when somebody <em>you</em> follow moves:\ntheir old server sends the move here, this server checks that the new account\nnames the old one, follows the new account on your behalf, and shows the\nredirect on the old account&#39;s profile from then on. Their old posts stay on\nthe old account, where their old server can still edit or delete them. If you\nalready followed the new account too, you keep that one follow.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Moving.md","sections":null,"anchor":"what-a-move-is-on-the-fediverse","manual":false,"prev":{"path":"/docs/moving","title":"Moving to Aloha Social, and moving away"},"next":{"path":"/docs/moving-moving-to-aloha-social","title":"Moving to Aloha Social"},"parent":null},{"slug":"moving-moving-to-aloha-social","path":"/docs/moving-moving-to-aloha-social","title":"Moving to Aloha Social","description":"Pixelfed cannot do step 3: it has no account migration. Your follows and your posts come over; your followers have to follow you again.","group":"moving","html":"<p>Three steps, two of them here.</p>\n<ol>\n<li><p><strong>Make your account here</strong>, on the setup screen. On its third step,\n<em>Already somewhere else?</em>, type the handle of your old account —\n<code>@you@mastodon.example</code> — and press <strong>Move here</strong>. You can do the same\nlater, at the top of the <strong>Migration</strong> page, where you are first shown\nwho that account is and what its server lets us read.</p>\n<p>What happens: this account is marked as also being the old one (the\n<code>alsoKnownAs</code> the old server will ask for), and in the background everyone\nthe old account follows is followed from here and its public posts are\nwritten here as yours, dated when you wrote them, with their pictures.\nNothing is sent to anybody. The list on the Migration page shows where the\nrun has got to. Posts you write on the old account after that are not\npicked up by anything: <strong>Copy newer posts</strong>, under the finished run, runs\nthe copy again and brings over only what is new.</p>\n</li>\n<li><p><strong>If the old server hides your follows or your posts</strong> — Mastodon does\nwhen you turned on <em>Hide your social graph</em>, Pixelfed always does — the\npage says so, and the file imports further down are for that: upload the\nold server&#39;s <code>following_accounts.csv</code> (Pixelfed: <code>pixelfed-following.json</code>)\nand, for the posts, its archive. Blocks, mutes, lists, bookmarks and blocked\ndomains come the same way.\nEvery upload runs in the background too.</p>\n</li>\n<li><p><strong>On the old server, move your followers here.</strong> On Mastodon that is\n<em>Preferences → Account → Move to a different account</em>; enter your handle\nhere. The Migration page shows it once the run is done. Your old server\nthen tells every server that knows you to follow this account instead, and\nyou are moved.</p>\n</li>\n</ol>\n<p>Pixelfed cannot do step 3: it has no account migration. Your follows and your\nposts come over; your followers have to follow you again.</p>\n<p><strong>From another Aloha Social server, step 3 is here too.</strong> Mastodon has no way\nto ask for a move from outside, which is why the last step is always done on\nthe old server. Another Aloha Social does: once the run is through, the\nMigration page offers <strong>Finish the move from here</strong>. You are sent to your old\nNextcloud to log in and to agree — the only permission asked for is to move\nthe account, nothing else — and the old server moves your followers here.\nIt checks, as it would for its own button, that this account names the old\none; the thirty days between moves apply there as everywhere.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Moving.md","sections":null,"anchor":"moving-to-aloha-social","manual":false,"prev":{"path":"/docs/moving-what-a-move-is-on-the-fediverse","title":"What a move is, on the fediverse"},"next":{"path":"/docs/moving-moving-away","title":"Moving away"},"parent":null},{"slug":"moving-moving-away","path":"/docs/moving-moving-away","title":"Moving away","description":"You can move again after thirty days. Undo the move takes the redirect off and lets you post and follow from here again — but your followers do not come back by themselves, because their…","group":"moving","html":"<ol>\n<li><p><strong>On the new account, name this one</strong> as an account you also answer to.\nOn Mastodon: <em>Preferences → Account → Moving from a different account</em>,\nwith your handle here.</p>\n</li>\n<li><p><strong>Here, in Migration → Move your account away</strong>, type the new\naccount&#39;s handle, type your own handle to confirm, and give your password\nwhen asked. Every server that knows you is told to follow the new account\ninstead; this account is marked as moved, shows where you went, and refuses\nto post or follow while it stays moved. Your posts stay here.</p>\n</li>\n</ol>\n<p>You can move again after thirty days. <strong>Undo the move</strong> takes the redirect off\nand lets you post and follow from here again — but your followers do not come\nback by themselves, because their servers acted on the move when it arrived.\nTake an export from the same page first if you want a copy of everything.</p>\n<p>An administrator can move an account for somebody with\n<code>occ social:account:move</code>, which skips the thirty days.</p>\n<p><strong>When a step is refused</strong>, the page says why in your language and what to\ndo next: the old account cannot be found, the new one does not name this one\nyet, an import of that kind is still running. The server&#39;s own words, in\nEnglish, are behind <em>Details</em>, for whoever helps you. The codes behind those\nsentences are listed in the <a href=\"/docs/api-migration#migration-error-codes\">API reference</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Moving.md","sections":null,"anchor":"moving-away","manual":false,"prev":{"path":"/docs/moving-moving-to-aloha-social","title":"Moving to Aloha Social"},"next":{"path":"/docs/moving-your-bluesky-account","title":"Your Bluesky account"},"parent":null},{"slug":"moving-your-bluesky-account","path":"/docs/moving-your-bluesky-account","title":"Your Bluesky account","description":"If this server puts you on Bluesky too, your Bluesky account is a second account of the same person, and it can move on its own.","group":"moving","html":"<p>If this server puts you on Bluesky too, your Bluesky account is a second\naccount of the same person, and it can move on its own.</p>\n<p><strong>Moving it to another Bluesky server.</strong> In <em>Migration → Move\nyour Bluesky account away</em>, name the server, the handle you want there (one\nending in a domain that server gives out), an e-mail address and a password\nfor the account there. The account is made there at once; your posts,\npictures and settings are copied in the background; then your account is\npointed at the new server and switched on there. Your followers on Bluesky\nfollow you there without doing anything.</p>\n<ul>\n<li><strong>Who controls the account afterwards.</strong> You, with your recovery phrase if\nyou made one, and the new server. This server keeps no say. Without a\nrecovery phrase only the new server controls the account, and the page\nasks you to confirm that before the move starts.</li>\n<li><strong>Posts you write here during the move</strong> wait, and go along right before\nyour account is pointed at the new server.</li>\n<li><strong>Missing pictures.</strong> Before the switch the new server is asked whether\neverything arrived. If pictures or videos are missing, the move waits for\nyou: copy again, or switch without them.</li>\n<li><strong>Calling it off.</strong> Until your account is pointed at the new server you can\ncall the move off. The account made at the new server stays there,\nswitched off; delete it there. Once the switch happened, the move can only\nbe finished: <em>Try again</em> goes on from where it stopped.</li>\n<li><strong>Telling your other followers.</strong> You can ask for one public post, or a\nprofile field <em>Also at</em>, saying where your Bluesky account went. Both are\nordinary posts and fields, yours to edit or delete.</li>\n</ul>\n<p><strong>Following the same people without moving.</strong> If your Bluesky account lives\nelsewhere and stays there, you can still follow from here everyone it\nfollows: give its handle, and the people it follows are followed from your\naccount here in the background (its follows are public, so no password is\nasked). Your Bluesky followers do not come along; only a move brings them.</p>\n<p><strong>Moving your Fediverse account away</strong> leaves the Bluesky account behind on\nthis server, and a moved account posts nothing more here. So the move asks\nwhat becomes of it: switch it off (the default — it is shown as inactive on\nBluesky; your handle stays yours and Settings can switch it on again), keep\nit as it is, or say that it moves too — which is only possible once its own\nmove above is done or under way. <code>occ social:account:move</code> takes the same\nchoice as <code>--bluesky</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Moving.md","sections":null,"anchor":"your-bluesky-account","manual":false,"prev":{"path":"/docs/moving-moving-away","title":"Moving away"},"next":{"path":"/docs/moving-if-this-server-goes-away","title":"If this server goes away"},"parent":null},{"slug":"moving-if-this-server-goes-away","path":"/docs/moving-if-this-server-goes-away","title":"If this server goes away","description":"On the fediverse, an account on a server that is gone cannot be moved: the old server has to send the move. Take the export from Settings → Migration while the server runs; its…","group":"moving","html":"<p><strong>On the fediverse</strong>, an account on a server that is gone cannot be moved:\nthe old server has to send the move. Take the export from <strong>Settings →\nMigration</strong> while the server runs; its <code>following_accounts.csv</code> brings your\nfollows to a new account anywhere, and the archive keeps your posts.</p>\n<p><strong>On Bluesky</strong> your account is a DID, <code>did:plc:…</code>, registered with the PLC\ndirectory, and whoever holds one of its <em>rotation keys</em> can point it at\nanother server — this server&#39;s own key, and, if you made one, your\n<strong>recovery phrase</strong> (Settings, Bluesky section). That is what the phrase is\nfor, and it works without this server.</p>\n<p><strong>While the server runs, keep two files</strong>, both in Settings&#39; Bluesky section:\n<strong>Download your Bluesky account</strong> (your repository as <code>repo.car</code>, the\npictures and videos under <code>blobs/</code>, your DID&#39;s history; the archive from\nthe Migration page has the same under <code>social/bluesky/</code>) and <strong>Download the\nrecovery tool</strong>, one HTML page that also comes inside that archive as\n<code>recovery/bluesky-recovery-tool.html</code>. Without the archive the posts are gone\nwith the server; the DID and your followers still move with the phrase.</p>\n<p><strong>With the recovery tool.</strong> Open the saved page in a browser — it needs no\nserver of its own, and nothing leaves it except the requests you press a\nbutton for — and go through its steps:</p>\n<ol>\n<li><strong>Your key</strong>: type the twelve words (or the key, hex or <code>z…</code>). It shows\nthe <code>did:key</code> they stand for.</li>\n<li><strong>Your identifier</strong>: your DID; <em>Read its latest operation</em> asks the PLC\ndirectory (or paste it). The page checks that your key is one of its\nrotation keys.</li>\n<li><strong>A signing key of your own</strong> — only when the old server cannot sign\nany more: the page makes one, signs with your recovery key an operation\nthat names it, and sends it to the directory when you press <em>Send</em>.\nKeep the signing key it shows until the move is done.</li>\n<li><strong>The new server</strong>: its address; <em>Look the server up</em> fills in its DID;\nhandle, e-mail and password for the account there; <em>Create the account\nwith your identifier</em> signs the request with your signing key.</li>\n<li><strong>Your posts and pictures</strong>: pick <code>repo.car</code> and the files of <code>blobs/</code>\nfrom the unpacked archive; they are uploaded to the new account.</li>\n<li><strong>Point your identifier at the new server</strong>: <em>Ask the new server for its\nrecommended credentials</em>, <em>Build and sign the operation</em> (your key first,\nthen the new server&#39;s), and <em>Send it to the PLC directory</em> — or copy it\nand send it any other way.</li>\n<li><em>Activate the account on the new server.</em></li>\n</ol>\n<p>The page is served here too, at <code>/apps/social/bluesky-recovery</code>, for\nwhen this server still runs. It signs exactly as this server does — the\nsame bytes, the same CID, a signature this server&#39;s code accepts, which the\ntests check against each other — but it has not been run end to end against\nthe live directory from this app&#39;s tests.</p>\n<p><strong>With <a href=\"https://github.com/bluesky-social/goat\">goat</a></strong>, the same without a\nbrowser:</p>\n<ol>\n<li><strong>Turn the phrase into its key</strong>, offline:\n<code>python3 recovery/recovery-key.py recovery/bip39-english.txt</code>, then type\nthe twelve words. It prints the key as hex and as multibase (<code>z…</code>). If\nyou saved the key when you made the phrase, you already have it.</li>\n<li><strong>Give the DID a signing key of your own</strong> and drop this server&#39;s\nrotation key (the other <code>did:key</code> in <code>rotationKeys</code> of the last operation\nin <code>plc-log.json</code>): <code>goat key generate --type secp256k1</code>, then\n<code>goat plc update --atproto-key &lt;its did:key&gt; --remove-rotation-key &lt;this server&#39;s key&gt; &lt;your DID&gt; &gt; op.json</code>,\n<code>goat plc sign --plc-signing-key &lt;your recovery key&gt; op.json &gt; signed.json</code>\nand <code>goat plc submit --did &lt;your DID&gt; signed.json</code>.</li>\n<li><strong>Create the account on the new server with your DID</strong>:\n<code>goat account service-auth-offline --atproto-signing-key &lt;the new signing key&gt; --iss &lt;your DID&gt; --aud &lt;the new server&#39;s did:web&gt; --lxm com.atproto.server.createAccount</code>\ngives a token for\n<code>goat account create --pds-host https://&lt;new server&gt; --existing-did &lt;your DID&gt; --service-auth &lt;token&gt; --handle … --email … --password …</code>.</li>\n<li><strong>Bring your data</strong>: <code>goat account login</code>, <code>goat repo import repo.car</code>,\nand <code>goat blob upload blobs/&lt;cid&gt;</code> for each blob <code>goat account missing-blobs</code>\nlists.</li>\n<li><strong>Point the DID at the new server</strong>: <code>goat account plc recommended</code> names\nits signing key, rotation key, handle and address; build the operation\nwith <code>goat plc update</code> (<code>--atproto-key</code>, <code>--pds</code>, <code>--handle</code>), put your\nrecovery key first in its <code>rotationKeys</code> and the new server&#39;s after it,\nsign it with your recovery key and submit it as in step 2. Then\n<code>goat account activate</code>.</li>\n</ol>\n<p>The <code>README.txt</code> in the archive carries both with your DID filled in. The\ngoat steps follow goat&#39;s own commands as of October 2026 (<code>goat &lt;command&gt; --help</code>\nhas the flags).</p>\n<p><strong>The 72-hour rule.</strong> This server&#39;s key ranks above your recovery key on the\nDID. For 72 hours after an operation signed with your phrase, a key that\nranks above it can undo it — so while this server still exists, its\nadministrator can reverse a change you made with the phrase, a move\nincluded. Once the server is gone, nobody can. A move made from this\nserver&#39;s own <strong>Move your Bluesky account away</strong> puts your recovery key first\non the new server, so the order is yours from then on.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Moving.md","sections":null,"anchor":"if-this-server-goes-away","manual":false,"prev":{"path":"/docs/moving-your-bluesky-account","title":"Your Bluesky account"},"next":{"path":"/docs/moving-what-does-not-move-whatever-you-do","title":"What does not move, whatever you do"},"parent":null},{"slug":"moving-what-does-not-move-whatever-you-do","path":"/docs/moving-what-does-not-move-whatever-you-do","title":"What does not move, whatever you do","description":"Coming to Aloha Social from another server, and leaving again without losing the people who follow you.","group":"moving","html":"<ul>\n<li><strong>Posts.</strong> Copied, never moved: see above.</li>\n<li><strong>Followers from a server that does not implement <code>Move</code>.</strong> Pixelfed is the\none that matters.</li>\n<li><strong>Your handle.</strong> <code>@you@old.example</code> stays on the old server; here you are\n<code>@you@this.server</code>. Keeping a handle across a change of domain is a server\nmigration, not an account one — see\n<a href=\"/docs/mastodon\">Mastodon-Compatibility.md</a>.</li>\n<li><strong>Direct messages and boosts</strong> are left out of the post copy on purpose.</li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Moving.md","sections":null,"anchor":"what-does-not-move-whatever-you-do","manual":false,"prev":{"path":"/docs/moving-if-this-server-goes-away","title":"If this server goes away"},"next":null,"parent":null},{"slug":"admin","path":"/docs/admin","title":"Administering Aloha Social","description":"What an administrator has to set up, what they can change, and what tells them something is wrong. For the routes behind the settings page see API.md, for the commands OCC-Commands.md, and…","group":"admin","html":"<p>What an administrator has to set up, what they can change, and what tells them\nsomething is wrong. For the routes behind the settings page see\n<a href=\"/docs/api\">API.md</a>, for the commands <a href=\"/docs/occ\">OCC-Commands.md</a>, and for\nhow the pieces fit together <a href=\"/docs/architecture\">Architecture.md</a>.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":[{"path":"/docs/admin-before-it-federates","title":"Before it federates","description":"Aloha Social is a fediverse server that happens to live inside Nextcloud, so the things it needs are the things any fediverse server needs: a stable public address, a .well-known answer…","parent":false},{"path":"/docs/admin-the-setup-checks","title":"The setup checks","description":"Aloha Social registers its own checks in Administration → Overview, beside Nextcloud's own. They are the things that break federation, or stop clients connecting, without anything else…","parent":false},{"path":"/docs/admin-mastodon-apps-cannot-connect","title":"Mastodon apps cannot connect","description":"A Mastodon app is given a domain and builds https://<domain>/api/v1/... from it. Not one of them accepts a path, and Aloha Social's routes live under /index.php/apps/social, so out of the…","parent":true},{"path":"/docs/admin-webfinger-does-not-answer","title":"WebFinger does not answer","description":"Nothing answers /.well-known/webfinger for an account of this instance, so no other server can find anybody here — searches for a local account fail everywhere else, and follows from…","parent":true},{"path":"/docs/admin-the-address-aloha-social-is-set-up-for","title":"The address Aloha Social is set up for","description":"Aloha Social builds every id from its stored cloud_url and the server now reports something else. Accounts here cannot be found under the address the server advertises, and every new post…","parent":true},{"path":"/docs/admin-the-delivery-job-has-not-run","title":"The delivery job has not run","description":"Cron\\Queue is what sends. It is meant to run every 12 minutes; the check warns once an hour has passed without it, and errors if the job is not registered at all (disabling and re-enabling…","parent":true},{"path":"/docs/admin-deliveries-are-stuck","title":"Deliveries are stuck","description":"Two things in the outbound queue do not move on their own: a delivery the drain has given up on after every retry (16 attempts over a widening delay, the last gap fourteen hours), and one…","parent":true},{"path":"/docs/admin-posts-the-index-repairs-skipped","title":"Posts the index repairs skipped","description":"Two background jobs walk the posts an older version stored, oldest first, from a cursor kept in the app settings: Cron\\Index writes the timeline and hashtag side rows of posts that lack…","parent":true},{"path":"/docs/admin-the-post-tables-keep-growing","title":"The post tables keep growing","description":"Retention is off unless an administrator turns it on (retention_days, 0 by default), and that default is deliberate: deleting what other servers sent is a decision about the instance, not…","parent":true},{"path":"/docs/admin-no-memory-cache","title":"No memory cache","description":"APCu (memcache.local = \\OC\\Memcache\\APCu) is enough for all of it on a single web server; Redis is what several need.","parent":true},{"path":"/docs/admin-videos-do-not-play-elsewhere","title":"Videos do not play elsewhere","description":"An iPhone records .mov; Android phones, and iPhones exporting through some apps, write HEVC inside an .mp4. Pixelfed's default media_types accepts video/mp4 and nothing else and drops the…","parent":true},{"path":"/docs/admin-raising-the-upload-limit","title":"Raising the upload limit","description":"A client is told, and held to, the smaller of Aloha Social's own ceilings and PHP's. PHP's is the smaller of upload_max_filesize and post_max_size; its own default is 2 MB and 8 MB. A…","parent":true},{"path":"/docs/admin-bluesky","title":"Bluesky","description":"Every account on this instance can be a Bluesky account as well: this Nextcloud is its personal data server (PDS), alice.<host> its handle, and a Bluesky relay reads what it publishes.…","parent":false},{"path":"/docs/admin-the-administration-page","title":"The administration page","description":"On a wide screen the groups are a list beside the page, each with a line saying what is in it, and the sections of the open group are listed under it. On a narrow one they are a row of…","parent":false},{"path":"/docs/admin-external-users","title":"External users","description":"People without an account on this server can register one themselves, when an administrator switches it on. They log in through the normal login page and reach Aloha Social and nothing…","parent":false},{"path":"/docs/admin-moderating","title":"Moderating","description":"Reports arrive from two directions: a local user reporting somebody through a client, and a peer instance sending POST /api/v1/reports about one of its own users' complaints. Both land in…","parent":false},{"path":"/docs/admin-configuration","title":"Configuration","description":"Nothing here is reachable through core's app-config API: the settings page writes through its own validated endpoints, and a delegate can write only what the moderation routes accept.","parent":false},{"path":"/docs/admin-set-by-the-app-not-by-you","title":"Set by the app, not by you","description":"The base address every id is built from, copied from overwrite.cli.url the first time the app is opened. Changing it by hand does not rewrite the ids already issued.","parent":true},{"path":"/docs/admin-server-settings","title":"Server settings","description":"Instance-wide settings. Most of them are on the Server section of the settings page, which validates the ranges given here; every one can be set with occ.","parent":true},{"path":"/docs/admin-moderation-and-federation","title":"Moderation and federation","description":"all_but — federate with everyone except the listed instances (block list). none_but — federate only with the listed ones (allow list).","parent":true},{"path":"/docs/admin-external-users-2","title":"External users","description":"Set from the External users cards; these are the keys they write.","parent":true},{"path":"/docs/admin-per-account","title":"Per account","description":"User values under the app social, written by the app for one account and read back by it; occ user:setting <user> social <key> shows them. The For you learning switches a reader sets for…","parent":true},{"path":"/docs/admin-system-configuration","title":"System configuration","description":"And one of Nextcloud's own that matters here: allow_local_remote_servers, which must be on for an instance to federate with anything on a private address. That is a development arrangement.","parent":true},{"path":"/docs/admin-commands-by-task","title":"Commands by task","description":"The full reference is OCC-Commands.md; these are the ones an administrator reaches for.","parent":false},{"path":"/docs/admin-running-a-large-instance","title":"Running a large instance","description":"Everything below is optional and nothing on a small instance needs any of it. These are the three things that stop working first as an instance grows, and what to do about each.","parent":false},{"path":"/docs/admin-what-to-watch","title":"What to watch","description":"Administration → Social → For You includes an independent Ranked For You recommendations switch. It is off by default. Enabling it makes the ranked timeline available; it does not…","parent":false},{"path":"/docs/admin-empty-application-after-installing-development-dependencies","title":"Empty application after installing development dependencies","description":"A running Nextcloud should use Social's production Composer autoloader. Development packages such as Psalm pull in Amp versions that may collide with the Mail app's Amp functions during…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/admin-before-it-federates","title":"Before it federates"},"parent":null},{"slug":"admin-before-it-federates","path":"/docs/admin-before-it-federates","title":"Before it federates","description":"Aloha Social is a fediverse server that happens to live inside Nextcloud, so the things it needs are the things any fediverse server needs: a stable public address, a .well-known answer…","group":"admin","html":"<p>Aloha Social is a fediverse server that happens to live inside Nextcloud, so the\nthings it needs are the things any fediverse server needs: a stable public\naddress, a <code>.well-known</code> answer, and a cron that runs.</p>\n<p><strong>A stable address.</strong> Aloha Social copies <code>overwrite.cli.url</code> into its own\n<code>cloud_url</code> the first time somebody opens the app, derives <code>social_url</code> (that\naddress followed by <code>/apps/social/</code>) from it, and builds every account id,\npost id and WebFinger answer from those copies. It never reads the system value\nagain. Set <code>overwrite.cli.url</code> — and get it right — before anyone opens Aloha Social;\nchanging the server&#39;s address afterwards is the single most expensive mistake\navailable here, because the old address is inside every id already federated.\nSee <a href=\"/docs/admin-the-address-aloha-social-is-set-up-for#the-address-aloha-social-is-set-up-for\"><em>the address Aloha Social is set up for</em></a>.</p>\n<p><strong><code>.well-known</code> redirects.</strong> Another server looking for <code>@alice@example.com</code>\nasks <code>https://example.com/.well-known/webfinger</code>. Nextcloud serves that from\n<code>/index.php/.well-known/webfinger</code>, and the redirect from the domain root is\nsomething the web server has to do; Nextcloud&#39;s\n<a href=\"https://docs.nextcloud.com/server/latest/go.php?to=admin-setup-well-known-URL\">documented redirects</a>\nare exactly the ones needed. Without them nobody outside can find an account\nhere, however well everything inside works.</p>\n<p><strong>Pretty URLs are not required</strong>, but an instance reachable only at\n<code>https://example.com/index.php/apps/social/...</code> federates under ids with\n<code>index.php</code> in them, which some peers handle poorly. If <code>.htaccess</code>-based URL\nrewriting is available, turn it on before the first account is created rather\nthan after.</p>\n<p><strong>Behind a reverse proxy</strong>, set <code>trusted_proxies</code> and <code>overwritehost</code>,\n<code>overwriteprotocol</code> and <code>overwrite.cli.url</code> as the Nextcloud documentation\ndescribes. Aloha Social signs its outbound requests over the <code>Host</code> and <code>Date</code>\nheaders and verifies the signatures on what arrives, so a proxy that rewrites\nthe host without Nextcloud knowing produces signature failures on both sides\nthat look like nothing else.</p>\n<p><strong>Cron.</strong> Background jobs must be set to <em>Cron</em> (system cron), not <em>AJAX</em> and\nnot <em>Webcron</em>. Everything this instance sends leaves through <code>Cron\\Queue</code>,\nwhich runs every 12 minutes; with AJAX jobs, delivery happens only when\nsomebody happens to load a page, and on a quiet instance that can be hours.\nSee <a href=\"/docs/admin-the-delivery-job-has-not-run#the-delivery-job-has-not-run\"><em>the delivery job has not run</em></a>.</p>\n<p><strong>Outbound HTTP.</strong> The server must be able to reach the rest of the fediverse\nover HTTPS. Requests to local and private addresses are refused unless\nNextcloud&#39;s <code>allow_local_remote_servers</code> is on, which is a development setting\nand not one to carry into production. A host is resolved once, every address\nit answers with is checked, and the request — and each redirect it follows —\nis sent to exactly those addresses.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"before-it-federates","manual":false,"prev":{"path":"/docs/admin","title":"Administering Aloha Social"},"next":{"path":"/docs/admin-the-setup-checks","title":"The setup checks"},"parent":null},{"slug":"admin-the-setup-checks","path":"/docs/admin-the-setup-checks","title":"The setup checks","description":"Aloha Social registers its own checks in Administration → Overview, beside Nextcloud's own. They are the things that break federation, or stop clients connecting, without anything else…","group":"admin","html":"<p>Aloha Social registers its own checks in <strong>Administration → Overview</strong>, beside\nNextcloud&#39;s own. They are the things that break federation, or stop clients\nconnecting, without anything else saying so, and each links back to this page.</p>\n<p><code>occ social:check:install</code> runs the same classes (<code>lib/SetupChecks/</code>),\nprints each with its severity and exits <code>1</code> if any of them reports an error, so\na deployment script can run it. <code>--offline</code> leaves out the WebFinger probe, the\nonly one that goes out on the network.</p>\n<p><strong>Aloha Social: upload size.</strong> Whether PHP will accept the uploads this app promises\nto. PHP&#39;s <code>upload_max_filesize</code> and <code>post_max_size</code> are enforced before a byte\nreaches this app&#39;s code, so <code>/api/v1/instance</code> and <code>/api/v2/instance</code> advertise\n<code>image_size_limit</code> and <code>video_size_limit</code> as the smaller of the app&#39;s own\n(<code>max_size</code>, <code>max_video_size</code>) and PHP&#39;s. When PHP&#39;s is the smaller, every\nclient is held to it: an upload over it is refused with a 422 naming the limit\n(<code>the file is larger than this server accepts (2 MB)</code>), and a warning in the\nNextcloud log names the setting it went over. To let the app&#39;s own ceiling\napply, raise both PHP values; see\n<a href=\"/docs/admin-raising-the-upload-limit#raising-the-upload-limit\">Raising the upload limit</a>.</p>\n<p><strong>Aloha Social: video conversion.</strong> Whether the videos posted here will play\nanywhere else. A warning when <strong>ffmpeg is missing</strong>: iPhone <code>.mov</code> videos and\nHEVC videos are then stored and sent as they were uploaded, and will not play\non other servers — Pixelfed refuses anything that is not an MP4 — or in Chrome\nand Firefox. Information, not a warning, when ffmpeg is there and\n<code>video_transcode</code> has been switched off, because that is a decision. See\n<a href=\"/docs/admin-videos-do-not-play-elsewhere#videos-do-not-play-elsewhere\">Videos do not play elsewhere</a>.</p>\n<p><strong>Aloha Social: reachable by other servers.</strong> Whether the strict peers will talk to\nthis instance at all. Federation does not fail all at once: a plain-HTTP\ninstance, or one on a private address, federates happily with a permissive\nserver and is refused at the first gate by a strict one. The strictest in\ncommon use is <strong>Pixelfed</strong>, which is also the network a photo server most wants\nto reach — it refuses any peer that is not HTTPS on a publicly resolvable name,\nbefore it checks a signature, from its inbox, its delivery and its actor fetch,\nwith nothing to configure. This is expected on a development or intranet\ninstance and is a warning rather than an error.</p>\n<p><strong>Aloha Social: client API.</strong> Whether a Mastodon app can reach this instance at all.\nSee below — this is the one check that is about apps rather than about\nfederation, and it is a warning rather than an error, because everything else\nworks without it.</p>\n<p><strong>Aloha Social: index repairs.</strong> Whether the two repair jobs that walk the\nposts stored by an older version got past every one of them. <code>Cron\\Index</code>\ngives each post its timeline and hashtag rows and <code>Cron\\SearchIndex</code> puts its\nwords into the content search; a post that keeps failing is passed over rather\nthan holding every post after it back, and this check counts what was passed\nover. See <a href=\"/docs/admin-posts-the-index-repairs-skipped#posts-the-index-repairs-skipped\">Posts the index repairs skipped</a>.</p>\n<p><strong>Aloha Social: table growth.</strong> A warning when retention is off and the post\ntables have grown past the size where that starts to cost: more than a million\nposts, or about thirty million words in the search index. See\n<a href=\"/docs/admin-the-post-tables-keep-growing#the-post-tables-keep-growing\">The post tables keep growing</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":[{"path":"/docs/admin-mastodon-apps-cannot-connect","title":"Mastodon apps cannot connect","description":"A Mastodon app is given a domain and builds https://<domain>/api/v1/... from it. Not one of them accepts a path, and Aloha Social's routes live under /index.php/apps/social, so out of the…","parent":true},{"path":"/docs/admin-webfinger-does-not-answer","title":"WebFinger does not answer","description":"Nothing answers /.well-known/webfinger for an account of this instance, so no other server can find anybody here — searches for a local account fail everywhere else, and follows from…","parent":true},{"path":"/docs/admin-the-address-aloha-social-is-set-up-for","title":"The address Aloha Social is set up for","description":"Aloha Social builds every id from its stored cloud_url and the server now reports something else. Accounts here cannot be found under the address the server advertises, and every new post…","parent":true},{"path":"/docs/admin-the-delivery-job-has-not-run","title":"The delivery job has not run","description":"Cron\\Queue is what sends. It is meant to run every 12 minutes; the check warns once an hour has passed without it, and errors if the job is not registered at all (disabling and re-enabling…","parent":true},{"path":"/docs/admin-deliveries-are-stuck","title":"Deliveries are stuck","description":"Two things in the outbound queue do not move on their own: a delivery the drain has given up on after every retry (16 attempts over a widening delay, the last gap fourteen hours), and one…","parent":true},{"path":"/docs/admin-posts-the-index-repairs-skipped","title":"Posts the index repairs skipped","description":"Two background jobs walk the posts an older version stored, oldest first, from a cursor kept in the app settings: Cron\\Index writes the timeline and hashtag side rows of posts that lack…","parent":true},{"path":"/docs/admin-the-post-tables-keep-growing","title":"The post tables keep growing","description":"Retention is off unless an administrator turns it on (retention_days, 0 by default), and that default is deliberate: deleting what other servers sent is a decision about the instance, not…","parent":true},{"path":"/docs/admin-no-memory-cache","title":"No memory cache","description":"APCu (memcache.local = \\OC\\Memcache\\APCu) is enough for all of it on a single web server; Redis is what several need.","parent":true},{"path":"/docs/admin-videos-do-not-play-elsewhere","title":"Videos do not play elsewhere","description":"An iPhone records .mov; Android phones, and iPhones exporting through some apps, write HEVC inside an .mp4. Pixelfed's default media_types accepts video/mp4 and nothing else and drops the…","parent":true},{"path":"/docs/admin-raising-the-upload-limit","title":"Raising the upload limit","description":"A client is told, and held to, the smaller of Aloha Social's own ceilings and PHP's. PHP's is the smaller of upload_max_filesize and post_max_size; its own default is 2 MB and 8 MB. A…","parent":true}],"anchor":"the-setup-checks","manual":false,"prev":{"path":"/docs/admin-before-it-federates","title":"Before it federates"},"next":{"path":"/docs/admin-mastodon-apps-cannot-connect","title":"Mastodon apps cannot connect"},"parent":null},{"slug":"admin-mastodon-apps-cannot-connect","path":"/docs/admin-mastodon-apps-cannot-connect","title":"Mastodon apps cannot connect","description":"A Mastodon app is given a domain and builds https://<domain>/api/v1/... from it. Not one of them accepts a path, and Aloha Social's routes live under /index.php/apps/social, so out of the…","group":"admin","html":"<p>A Mastodon app is given a domain and builds <code>https://&lt;domain&gt;/api/v1/...</code> from\nit. Not one of them accepts a path, and Aloha Social&#39;s routes live under\n<code>/index.php/apps/social</code>, so out of the box adding this instance to an app\nfails at its first request with nothing in the log to show for it. The web\ninterface and federation with other servers are unaffected.</p>\n<p>An administrator opening Aloha Social sees this at the top of the app, with the\nApache rules to paste, until the web server answers; it is the same check as\nin <strong>Administration → Overview</strong>, and it goes quiet within five minutes of the\nrules being in place.</p>\n<p>Nextcloud only lets a short list of apps claim URLs at the root of the domain,\nand Aloha Social is not on it, so this has to be done in the web server. Ready-made\nrules are in <a href=\"https://github.com/AlohaSocial/social/blob/master/contrib/webserver\"><code>contrib/webserver/</code></a>: include\n<code>apache-social-root.conf</code> from the <code>&lt;VirtualHost&gt;</code> that serves Nextcloud, or\n<code>nginx-social-root.conf</code> from its <code>server</code> block, and reload. For Apache that\nis:</p>\n<pre><code class=\"language-apache\">ProxyPreserveHost On\nRequestHeader set X-Forwarded-Proto &quot;https&quot;\n\nRewriteEngine On\nRewriteRule ^/?api/(.*)$   http://127.0.0.1/index.php/apps/social/api/$1   [P,QSA,L]\nRewriteRule ^/?oauth/(.*)$ http://127.0.0.1/index.php/apps/social/oauth/$1 [P,QSA,L]\nRewriteRule ^/?\\.well-known/host-meta$ http://127.0.0.1/index.php/.well-known/host-meta [P,QSA,L]\nRewriteRule ^/?\\.well-known/oauth-authorization-server$ http://127.0.0.1/index.php/apps/social/.well-known/oauth-authorization-server [P,QSA,L]\nRewriteRule ^/?\\.well-known/oauth-protected-resource$ http://127.0.0.1/index.php/apps/social/.well-known/oauth-protected-resource [P,QSA,L]\n</code></pre>\n<p><code>mod_proxy</code>, <code>mod_proxy_http</code>, <code>mod_rewrite</code> and <code>mod_headers</code> have to be enabled. This cannot\ngo in an <code>.htaccess</code> file, because <code>ProxyPreserveHost</code> is not allowed there and\nwithout it the app is handed <code>Host: 127.0.0.1</code> and refuses the request as an\nuntrusted domain.</p>\n<p><strong>Check what <code>127.0.0.1:80</code> actually serves.</strong> These rules proxy to plain HTTP\non the loopback address, which only works if something there serves <em>this</em>\nNextcloud. A server whose virtual hosts are all on <code>:443</code> — what a\ncertbot-managed config looks like once the HTTP ones have been commented out —\nhas no <code>:80</code> virtual host for the domain at all, so the request falls through\nto the main server and its <code>DocumentRoot</code>, and every proxied request answers\n404 from there.</p>\n<p>That 404 is indistinguishable from having no rules at all, which is the trap:\nthe rules are correct, they fire, and the warning stays up. The way to tell them\napart is that an Apache error page names the port it came from —</p>\n<pre><code>/api/v1/instance  →  &quot;Server at example.com Port 80&quot;    the rules fired, the target is wrong\n/login            →  &quot;Server at example.com Port 443&quot;   served by the HTTPS vhost itself\n</code></pre>\n<p>— and <code>apachectl -S</code> will show no <code>*:80</code> section. The app says which of the two\nit is as well: the warning carries what the probe got back.</p>\n<p>The fix is to give the proxy something to land on. A loopback-only listener\nkeeps plain HTTP off the public interface:</p>\n<pre><code class=\"language-apache\">Listen 127.0.0.1:8081\n\n&lt;VirtualHost 127.0.0.1:8081&gt;\n    ServerName example.com\n    DocumentRoot /path/to/nextcloud\n    &lt;Directory /path/to/nextcloud&gt;\n        Options FollowSymLinks\n        AllowOverride All\n        Require ip 127.0.0.1\n    &lt;/Directory&gt;\n&lt;/VirtualHost&gt;\n</code></pre>\n<p>then point the three rules at <code>http://127.0.0.1:8081</code> instead. <code>AllowOverride All</code> is not optional here: Nextcloud&#39;s own <code>.htaccess</code> is what hands the\n<code>Authorization</code> header to PHP, so without it the client API answers <em>the\naccess_token was revoked</em> for every signed-in request — see below.</p>\n<p>They map three things onto the app:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Path</th>\n<th>Why</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>/api/…</code></td>\n<td>every client call, from <code>/api/v1/instance</code> onwards</td>\n</tr>\n<tr>\n<td><code>/oauth/…</code></td>\n<td>registering the app, the consent screen, the token</td>\n</tr>\n<tr>\n<td><code>/.well-known/host-meta</code></td>\n<td>some clients ask for it before anything else</td>\n</tr>\n<tr>\n<td><code>/.well-known/oauth-authorization-server</code></td>\n<td>RFC 8414 discovery; a Mastodon 4.3 client asks for it before it registers anything, and reads a 404 as &quot;not a server I can sign in to&quot;</td>\n</tr>\n<tr>\n<td><code>/.well-known/oauth-protected-resource</code></td>\n<td>OAuth-capable Bluesky clients ask which authorization server accounts here use; the authorization-server document describes AT Protocol OAuth alongside the separate Mastodon OAuth API</td>\n</tr>\n</tbody></table></div>\n<p><strong>Use an internal rewrite, not a redirect.</strong> Nextcloud routes on the address\nthe request arrived at, so a plain internal rewrite to <code>/index.php/apps/social</code>\nreaches PHP but not the route, and answers 404. Sending a redirect instead does\nreach the route, but many HTTP clients drop the <code>Authorization</code> header when\nthey follow one, so every signed-in request then answers 401. The Apache rules\ntherefore proxy internally (<code>mod_proxy</code>, <code>mod_proxy_http</code> and <code>ProxyPreserveHost On</code>), which keeps both the address and the header.</p>\n<p>Apache also has to hand the <code>Authorization</code> header to PHP. Nextcloud&#39;s own\n<code>.htaccess</code> does that, but only where <code>AllowOverride</code> lets it be read; with\n<code>AllowOverride None</code> the rule never runs and every request from a signed-in app\nanswers <code>the access_token was revoked</code>. The shipped rules set it themselves for\nthe same reason.</p>\n<p><strong>The discovery document describes the addresses it was reached at.</strong> RFC 8414\nrequires the <code>issuer</code> in <code>/.well-known/oauth-authorization-server</code> to be the URL\nthe document was fetched from, minus the well-known suffix. A client that asks\nthe domain root and is told the issuer is <code>https://cloud.example/index.php/apps/social/</code>\nhas been handed a mismatch and rejects it — before it opens a browser, so\nnothing here sees it fail. So while the rewrite is working, the document\nadvertises the root addresses the client used; where it is not, it advertises\nthe app&#39;s own, which is the only reachable answer. Which of the two it is comes\nfrom the check below, read from its cache — an internal proxy hands PHP the app\npath either way, so the request itself cannot say.</p>\n<p><strong><code>X-Forwarded-Proto</code> is not optional.</strong> <code>mod_proxy</code> sends <code>X-Forwarded-For</code> and\n<code>X-Forwarded-Host</code> by itself and stops there, and the rules above proxy to plain\nHTTP — so without that header Nextcloud believes every proxied request arrived\nover <code>http</code> and builds every absolute URL it answers with accordingly. A client\nis then handed <code>http://</code> addresses for avatars, posts and the instance\nthumbnail, on a site that is <code>https</code>. An <strong>iOS client refuses them outright</strong>\n(App Transport Security), and its sign-in stops dead after registering the app,\nwith nothing in any log to show for it. The nginx rules set the equivalent\n(<code>proxy_set_header X-Forwarded-Proto $scheme</code>) and always did.</p>\n<p>The symptom is visible without a client: <code>/api/v2/instance</code> fetched through the\nroot answers a <code>thumbnail.url</code> beginning <code>http://</code>, where the same document\nfetched at <code>/index.php/apps/social/api/v2/instance</code> begins <code>https://</code>.</p>\n<p><strong>Add <code>127.0.0.1</code> to <code>trusted_proxies</code>.</strong> Client requests reach PHP from the\nproxy afterwards, so without it every app in the world shares one address for\nrate limiting, brute-force protection and the log — one client tripping a limit\nlocks out all of them. The real address arrives in <code>X-Forwarded-For</code>, which\nApache&#39;s <code>mod_proxy</code> sends by itself and the nginx rules set explicitly.</p>\n<p>The check probes <code>/api/v1/instance</code> at the address Aloha Social is configured for,\nthen at the host the request came in on, then at the server&#39;s base URL, and\nreads the answer rather than only its status, so a login page or a catch-all\n<code>index</code> at the root does not pass for a client API. A success is remembered for\nan hour and a failure for five minutes.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"mastodon-apps-cannot-connect","manual":false,"prev":{"path":"/docs/admin-the-setup-checks","title":"The setup checks"},"next":{"path":"/docs/admin-webfinger-does-not-answer","title":"WebFinger does not answer"},"parent":"admin-the-setup-checks"},{"slug":"admin-webfinger-does-not-answer","path":"/docs/admin-webfinger-does-not-answer","title":"WebFinger does not answer","description":"Nothing answers /.well-known/webfinger for an account of this instance, so no other server can find anybody here — searches for a local account fail everywhere else, and follows from…","group":"admin","html":"<p>Nothing answers <code>/.well-known/webfinger</code> for an account of this instance, so no\nother server can find anybody here — searches for a local account fail\neverywhere else, and follows from outside never arrive.</p>\n<p>Two quite different causes, and the check cannot tell them apart from outside:</p>\n<ol>\n<li>The redirects are missing. Add the\n<a href=\"https://docs.nextcloud.com/server/latest/go.php?to=admin-setup-well-known-URL\">documented ones</a>\nand reload the web server.</li>\n<li>Aloha Social is set up for a different address than the one the request arrives\non, so it answers for a host nobody asks about. The next check is about\nthat.</li>\n</ol>\n<p>The probe is tried at the address Aloha Social is configured for, then at the host\nthe request came in on, then at the server&#39;s base URL, and a success is\nremembered for an hour. If the instance uses a certificate the server itself\ndoes not trust — a private CA during setup — set <code>social.checkssl</code> to <code>false</code>\nin <code>config.php</code> to stop the probe verifying it. That switch is for the probe\nonly, not for federation.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"webfinger-does-not-answer","manual":false,"prev":{"path":"/docs/admin-mastodon-apps-cannot-connect","title":"Mastodon apps cannot connect"},"next":{"path":"/docs/admin-the-address-aloha-social-is-set-up-for","title":"The address Aloha Social is set up for"},"parent":"admin-the-setup-checks"},{"slug":"admin-the-address-aloha-social-is-set-up-for","path":"/docs/admin-the-address-aloha-social-is-set-up-for","title":"The address Aloha Social is set up for","description":"Aloha Social builds every id from its stored cloud_url and the server now reports something else. Accounts here cannot be found under the address the server advertises, and every new post…","group":"admin","html":"<p>Aloha Social builds every id from its stored <code>cloud_url</code> and the server now reports\nsomething else. Accounts here cannot be found under the address the server\nadvertises, and every new post carries an id that resolves nowhere.</p>\n<p>To see the two values:</p>\n<pre><code class=\"language-bash\">occ config:app:get social cloud_url\nocc config:system:get overwrite.cli.url\n</code></pre>\n<p>The same check compares the scheme, host and port of <code>social_url</code> — the base\nthe ids are actually minted from — with <code>cloud_url</code>. They can only disagree on\nan instance set up by an earlier version, which took <code>social_url</code> from the\nfirst request that opened the app: an internal hostname, or <code>http</code> behind a\nproxy that does not pass the scheme on. If nothing has federated yet,\n<code>occ config:app:delete social social_url</code> and it is derived from <code>cloud_url</code>\nthe next time the app is opened; otherwise <code>occ social:reset --uri=&lt;address&gt;</code>\nmoves both.</p>\n<p>Aloha Social reports the mismatch and will not correct it, because the stored address\nis inside every id already written. Either point <code>overwrite.cli.url</code> back at\nthe address Aloha Social knows, or accept the rename and run <code>occ social:reset --uri=&lt;new address&gt;</code>, <strong>which deletes everything Aloha Social holds</strong> — every post,\nfollow and cached account, local and remote alike.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"the-address-aloha-social-is-set-up-for","manual":false,"prev":{"path":"/docs/admin-webfinger-does-not-answer","title":"WebFinger does not answer"},"next":{"path":"/docs/admin-the-delivery-job-has-not-run","title":"The delivery job has not run"},"parent":"admin-the-setup-checks"},{"slug":"admin-the-delivery-job-has-not-run","path":"/docs/admin-the-delivery-job-has-not-run","title":"The delivery job has not run","description":"Cron\\Queue is what sends. It is meant to run every 12 minutes; the check warns once an hour has passed without it, and errors if the job is not registered at all (disabling and re-enabling…","group":"admin","html":"<p><code>Cron\\Queue</code> is what sends. It is meant to run every 12 minutes; the check\nwarns once an hour has passed without it, and errors if the job is not\nregistered at all (disabling and re-enabling the app registers it again).</p>\n<p>Nothing posted here leaves the server while it is not running, and nobody is\ntold: the author sees their post in their own timeline and nowhere else. Check\nthat background jobs are set to Cron, that the system cron is actually running\n<code>cron.php</code>, and that no other job is monopolising the runs.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"the-delivery-job-has-not-run","manual":false,"prev":{"path":"/docs/admin-the-address-aloha-social-is-set-up-for","title":"The address Aloha Social is set up for"},"next":{"path":"/docs/admin-deliveries-are-stuck","title":"Deliveries are stuck"},"parent":"admin-the-setup-checks"},{"slug":"admin-deliveries-are-stuck","path":"/docs/admin-deliveries-are-stuck","title":"Deliveries are stuck","description":"Two things in the outbound queue do not move on their own: a delivery the drain has given up on after every retry (16 attempts over a widening delay, the last gap fourteen hours), and one…","group":"admin","html":"<p>Two things in the outbound queue do not move on their own: a delivery the drain\nhas given up on after every retry (16 attempts over a widening delay, the last\ngap fourteen hours), and one it should have come back for a day ago and has\nnot. The first usually means an instance that is gone or refusing us; the\nsecond means the drain is not draining.</p>\n<pre><code class=\"language-bash\">occ social:queue:status                  # the same summary the settings page shows\nocc social:queue:retry --min-tries 16    # give the abandoned ones the full run again\nocc social:queue:retry --flush --min-tries 16   # or drop them, for a peer that is gone\n</code></pre>\n<p>The <strong>Deliveries</strong> section of the Aloha Social settings names the instances\nthe failures are stacked against, with the highest attempt count so far and\nwhen each was last tried.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"deliveries-are-stuck","manual":false,"prev":{"path":"/docs/admin-the-delivery-job-has-not-run","title":"The delivery job has not run"},"next":{"path":"/docs/admin-posts-the-index-repairs-skipped","title":"Posts the index repairs skipped"},"parent":"admin-the-setup-checks"},{"slug":"admin-posts-the-index-repairs-skipped","path":"/docs/admin-posts-the-index-repairs-skipped","title":"Posts the index repairs skipped","description":"Two background jobs walk the posts an older version stored, oldest first, from a cursor kept in the app settings: Cron\\Index writes the timeline and hashtag side rows of posts that lack…","group":"admin","html":"<p>Two background jobs walk the posts an older version stored, oldest first, from\na cursor kept in the app settings: <code>Cron\\Index</code> writes the timeline and hashtag\nside rows of posts that lack them, and <code>Cron\\SearchIndex</code> (queued once by the\nupgrade that added the word index) adds the words of every older post to the\ncontent search. A post that one of them cannot read — a malformed row, a type\nthis version does not know — would otherwise fail on every run and hold the\ncursor, and with it every post after it, for good. So a post that has failed\nfive passes of the timeline repair is skipped, and a chunk the search backfill\nfails twice is indexed one post at a time until the one that fails is found and\nskipped. Each skip is a warning in the Nextcloud log — <code>skipping stream</code> with\nthe post&#39;s primary key and type, <code>skipping post</code> with its nid — carrying the\nerror that stopped it, and this check counts them (<code>index_skipped</code>,\n<code>search_index_skipped</code>).</p>\n<p>A skipped post is still in the database and still served where it is read by\nits own id; what it lost is its place in the timelines or in the search. Fix or\ndelete the row the log names, then <code>occ social:check:install --index --force</code>\nrebuilds the side rows of everything, and <code>occ config:app:delete social search_index_ready</code> followed by <code>occ config:app:delete social search_index_cursor</code> has the search backfill start again from the first post\non the next cron run. Reset the counters with <code>occ config:app:delete social index_skipped</code> and <code>occ config:app:delete social search_index_skipped</code> once\nthe posts are dealt with.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"posts-the-index-repairs-skipped","manual":false,"prev":{"path":"/docs/admin-deliveries-are-stuck","title":"Deliveries are stuck"},"next":{"path":"/docs/admin-the-post-tables-keep-growing","title":"The post tables keep growing"},"parent":"admin-the-setup-checks"},{"slug":"admin-the-post-tables-keep-growing","path":"/docs/admin-the-post-tables-keep-growing","title":"The post tables keep growing","description":"Retention is off unless an administrator turns it on (retention_days, 0 by default), and that default is deliberate: deleting what other servers sent is a decision about the instance, not…","group":"admin","html":"<p>Retention is off unless an administrator turns it on (<code>retention_days</code>, <code>0</code> by\ndefault), and that default is deliberate: deleting what other servers sent is a\ndecision about the instance, not a tuning knob. Without it, <code>social_stream</code>,\nits recipient rows (<code>social_stream_dest</code>, one per recipient), its hashtag rows,\nits words (<code>social_search_term</code>) and the cached attachments grow with\neverything the instance has ever received. The check counts the posts up to a\nmillion (it stops counting there) and reads the word index&#39;s highest id, and\nwarns past either.</p>\n<pre><code class=\"language-bash\">occ config:app:set social retention_days --value 180   # remote posts nobody here touched, after 180 days\nocc social:stream:prune --dry-run                      # what the next pass would remove\n</code></pre>\n<p>Retention never touches a local post, a direct message, a post somebody here\nliked, boosted, bookmarked or replied to, a post a local post boosts or replies\nto, or anything by an account somebody here follows. The cron pass removes up to\n5,000 posts a run; <code>occ social:stream:prune</code> removes all of them at once. Their\ncached media goes with them, and the orphaned-media sweep takes what is left.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"the-post-tables-keep-growing","manual":false,"prev":{"path":"/docs/admin-posts-the-index-repairs-skipped","title":"Posts the index repairs skipped"},"next":{"path":"/docs/admin-no-memory-cache","title":"No memory cache"},"parent":"admin-the-setup-checks"},{"slug":"admin-no-memory-cache","path":"/docs/admin-no-memory-cache","title":"No memory cache","description":"APCu (memcache.local = \\OC\\Memcache\\APCu) is enough for all of it on a single web server; Redis is what several need.","group":"admin","html":"<p>Without <code>memcache.local</code> or <code>memcache.distributed</code> in <code>config.php</code>, every cache\nAloha Social asks Nextcloud for is one that forgets each write. Nextcloud&#39;s own check\nalready says a memcache would be faster; this one is there because, for this\napp, some of what is lost is protection:</p>\n<ul>\n<li><strong>Kept in the database instead</strong> (<code>social_durable_cache</code>, expired rows\ndeleted by <code>Cron\\Cache</code>): the inbox throttle (<code>inbox_throttle</code>), the\nrecords of Linked Data signatures and of signed requests already accepted,\nwhich are what refuse a replayed activity, the <code>Idempotency-Key</code> record that\nkeeps a client&#39;s retried post from being published twice, and the\nstatistics page&#39;s fifteen-minute copy. All of it works; each costs a few\nqueries.</li>\n<li><strong>Always in the database</strong>, memcache or not: the per-server delivery\nbreaker (<code>social_host_breaker</code>), which every process and the cron share.</li>\n<li><strong>Worked out again on every request</strong>: the network figures, peer trends\nand follow suggestions.</li>\n</ul>\n<p>APCu (<code>memcache.local = \\OC\\Memcache\\APCu</code>) is enough for all of it on a\nsingle web server; Redis is what several need.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"no-memory-cache","manual":false,"prev":{"path":"/docs/admin-the-post-tables-keep-growing","title":"The post tables keep growing"},"next":{"path":"/docs/admin-videos-do-not-play-elsewhere","title":"Videos do not play elsewhere"},"parent":"admin-the-setup-checks"},{"slug":"admin-videos-do-not-play-elsewhere","path":"/docs/admin-videos-do-not-play-elsewhere","title":"Videos do not play elsewhere","description":"An iPhone records .mov; Android phones, and iPhones exporting through some apps, write HEVC inside an .mp4. Pixelfed's default media_types accepts video/mp4 and nothing else and drops the…","group":"admin","html":"<p>An iPhone records <code>.mov</code>; Android phones, and iPhones exporting through some\napps, write <strong>HEVC</strong> inside an <code>.mp4</code>. Pixelfed&#39;s default <code>media_types</code> accepts\n<code>video/mp4</code> and nothing else and drops the rest the moment it arrives, and\nChrome and Firefox do not play HEVC. Aloha Social converts such videos to H.264 in an\nMP4 (<code>video_transcode</code>, on by default) — <strong>but only where ffmpeg is installed</strong>.\nInstall it from the distribution&#39;s packages (<code>apt install ffmpeg</code>,\n<code>dnf install ffmpeg</code>, …); ffprobe comes with it, and is what tells an H.264\nMP4, which is never re-encoded, from an HEVC one. ffmpeg is also what takes\nthe container metadata — where and with what a video or a recording was made,\nits title, its chapters — off every video and sound file as it is stored, by\ncopying its streams into a fresh container (whatever <code>video_transcode</code> says);\nwithout ffmpeg such a file is stored as it was uploaded. Files stored before\nthat are rewritten the same way by <code>occ social:media:strip-metadata</code> (except\nthose published on Bluesky, whose bytes a CID names). Pictures have their\nmetadata taken off by PHP alone. Nextcloud looks for both on the\n<code>PATH</code> of the PHP process and in the directories <code>binary_search_paths</code> in\n<code>config.php</code> names, only where PHP&#39;s <code>exec</code> is not disabled, and remembers the\nanswer for five minutes.</p>\n<p>Nothing needs restarting. Videos uploaded before ffmpeg was there are picked up\nby the background sweep, one every quarter of an hour, or all at once with\n<code>occ social:media:transcode</code>. Posts that already went out with the old file are\nnot sent again. Their poster frames — the still the Videos page and the player\nshow before anything is played — are made by another background job\n(<code>Cron\\VideoPosters</code>), five videos every quarter of an hour, or all at once\nwith <code>occ social:media:posters</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"videos-do-not-play-elsewhere","manual":false,"prev":{"path":"/docs/admin-no-memory-cache","title":"No memory cache"},"next":{"path":"/docs/admin-raising-the-upload-limit","title":"Raising the upload limit"},"parent":"admin-the-setup-checks"},{"slug":"admin-raising-the-upload-limit","path":"/docs/admin-raising-the-upload-limit","title":"Raising the upload limit","description":"A client is told, and held to, the smaller of Aloha Social's own ceilings and PHP's. PHP's is the smaller of upload_max_filesize and post_max_size; its own default is 2 MB and 8 MB. A…","group":"admin","html":"<p>A client is told, and held to, the smaller of Aloha Social&#39;s own ceilings and\nPHP&#39;s. PHP&#39;s is the smaller of <code>upload_max_filesize</code> and <code>post_max_size</code>; its\nown default is 2 MB and 8 MB. A refused upload leaves a warning in the\nNextcloud log saying which of the two it went over (<code>file upload refused: larger than this server accepts, over upload_max_filesize</code>, or <code>… the request body is over post_max_size</code>).</p>\n<p>Raise both, with <code>post_max_size</code> a little above <code>upload_max_filesize</code> so the\nrest of the form fits beside the file, wherever this PHP reads its settings:\nthe <code>php.ini</code> of the PHP-FPM pool or Apache module, a <code>.user.ini</code> in\nNextcloud&#39;s directory (PHP-FPM, picked up within five minutes), or\n<code>php_value</code> lines in Nextcloud&#39;s <code>.htaccess</code> (Apache with <code>mod_php</code>). For\nvideos up to 2 GB:</p>\n<pre><code class=\"language-ini\">upload_max_filesize = 2G\npost_max_size = 2050M\n</code></pre>\n<p>Restart PHP-FPM or Apache after editing <code>php.ini</code>. A reverse proxy or web\nserver in front has a body limit of its own (<code>client_max_body_size</code> in nginx,\n<code>LimitRequestBody</code> in Apache) that refuses a larger request before PHP sees\nit. A refusal there never reaches Nextcloud&#39;s log.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"raising-the-upload-limit","manual":false,"prev":{"path":"/docs/admin-videos-do-not-play-elsewhere","title":"Videos do not play elsewhere"},"next":{"path":"/docs/admin-bluesky","title":"Bluesky"},"parent":"admin-the-setup-checks"},{"slug":"admin-bluesky","path":"/docs/admin-bluesky","title":"Bluesky","description":"Every account on this instance can be a Bluesky account as well: this Nextcloud is its personal data server (PDS), alice.<host> its handle, and a Bluesky relay reads what it publishes.…","group":"admin","html":"<p>Every account on this instance can be a Bluesky account as well: this Nextcloud\nis its personal data server (PDS), <code>alice.&lt;host&gt;</code> its handle, and a Bluesky\nrelay reads what it publishes. Nothing is asked of the person; the\nadministrator switches it on once, on the administration page, after the\nrequirements below are met. The design and what each phase delivers is in\n<a href=\"/docs/atproto\">docs/Atproto-Compatibility.md</a>. Once it is on,\n<code>contrib/atproto-live-probe.sh &lt;host&gt; &lt;handle&gt;</code> checks from outside that the\nnetwork can reach everything it needs, and\n<a href=\"/docs/atproto-live\">docs/Atproto-Live-Test.md</a> goes through the rest by hand.</p>\n<p><strong>Requirements</strong>, each a check on the Bluesky card and in the Overview&#39;s setup\nchecks, and the card refuses to switch Bluesky on while one fails:</p>\n<h2 id=\"https\">https</h2>\n<p> on the instance host. A PDS is reached by relays and apps on the\npublic network, and a plain-http one is not a PDS to them; the one exception is\na development server nobody else talks to.</p>\n<h2 id=\"a-wildcard-host-for-the-handles\">A wildcard host for the handles</h2>\n<p> Every account&#39;s handle is\n<code>alice.&lt;host&gt;</code> and is resolved by <code>GET https://alice.&lt;host&gt;/.well-known/atproto-did</code>,\nso a DNS record <code>*.&lt;host&gt;</code> must point at this server and the certificate must\ncover it (a Let&#39;s Encrypt wildcard needs the DNS-01 challenge). The\nweb-server rules for that host are in <code>contrib/webserver</code> (the handles block\nat the end of each file).</p>\n<h2 id=\"-host-in-trusted-domains\">*.&lt;host&gt; in trusted_domains</h2>\n<p> Nextcloud answers a request for a host it\ndoes not trust with an error page, before the app sees it:</p>\n<pre><code>php occ config:system:set trusted_domains 3 --value=&#39;*.social.example.com&#39;\n</code></pre>\n<h2 id=\"the-root-rules\">The root rules</h2>\n<p> The DID document names the bare host as the PDS, so\n<code>/xrpc/</code> has to be served at the root exactly as <code>/api/</code> is for Mastodon apps,\nalong with <code>/.well-known/did.json</code>. The rules are in the same files:</p>\n<pre><code>RewriteRule ^/?xrpc/com\\.atproto\\.sync\\.subscribeRepos$ ws://127.0.0.1:8787/xrpc/com.atproto.sync.subscribeRepos [P,QSA,L]\nRewriteRule ^/?xrpc/(.*)$ http://127.0.0.1/index.php/apps/social/xrpc/$1 [P,QSA,L]\nRewriteRule ^/?\\.well-known/did\\.json$ http://127.0.0.1/index.php/apps/social/.well-known/did.json [P,QSA,L]\n</code></pre>\n<p>Apache needs <code>mod_proxy_wstunnel</code> for the first of them; nginx the\n<code>Upgrade</code>/<code>Connection</code> headers the shipped block sets.</p>\n<h2 id=\"the-firehose-daemon\">The firehose daemon</h2>\n<p> <code>occ social:atproto:serve</code> is a long-running process\nthat serves the event stream relays subscribe to. It holds at most 256\nconnections, 8 from one address, and answers 503 past that. Under systemd:</p>\n<pre><code>[Unit]\nDescription=Aloha Social Bluesky firehose\nAfter=network.target mariadb.service\n\n[Service]\nUser=www-data\nWorkingDirectory=/var/www/nextcloud\nExecStart=/usr/bin/php occ social:atproto:serve --bind 127.0.0.1:8787\nRestart=always\nRestartSec=5\n\n[Install]\nWantedBy=multi-user.target\n</code></pre>\n<p>In a container, the same command under the container&#39;s supervisor. The daemon\nreports to the card every fifteen seconds; a report older than a minute shows\nas &quot;not running&quot;.</p>\n<h2 id=\"the-jetstream-listener-optional\">The Jetstream listener (optional)</h2>\n<p> With a Jetstream endpoint set on the\ncard (<code>wss://jetstream2.us-east.bsky.network</code>, Bluesky&#39;s own, or one you run),\n<code>occ social:atproto:listen</code> brings the posts of the Bluesky accounts people\nhere follow within seconds rather than on the poller&#39;s next pass. It is a\nsecond unit like the one above, with\n<code>ExecStart=/usr/bin/php occ social:atproto:listen</code>. It reports to the card&#39;s\n&quot;Reading Bluesky&quot; part every fifteen seconds; without it, the poller does all\nthe reading, as before. Where it got to and its reports are kept in the\ndatabase rather than in the app&#39;s settings, so they cost the rest of the\nserver nothing; a value an older version kept in the settings is moved over\nonce.</p>\n<h2 id=\"the-relays\">The relays</h2>\n<p> The card&#39;s &quot;Relays carry this server&quot; check asks each\nconfigured relay how it sees this server: crawled or not, how many of its\naccounts it carries, and whether it throttles or bans it. A relay limits\nhow many accounts and events a new server may have; when it throttles,\nthe posts of the accounts over the limit do not reach Bluesky, and only\nthe relay&#39;s operator can raise the limit. It is a warning, never a reason\nthe switch refuses.</p>\n<h2 id=\"cron\">Cron</h2>\n<p> The maintenance job (every five minutes) brings Bluesky up to\ndate with the last day&#39;s public posts — a post the listener missed is\npublished, an edit within the grace period is replaced, a deleted post&#39;s\nrecord is removed — resends directory operations, prunes the firehose\npast its window, drops retired keys, and removes Bluesky posts read here\nthat their authors deleted there. The ordinary cron requirement\ncovers it.</p>\n<h2 id=\"direct-messages-on-by-default\">Direct messages (on by default)</h2>\n<p> The card&#39;s chat service\n(<code>https://api.bsky.chat</code>, Bluesky&#39;s own) is where people&#39;s direct messages\nwith Bluesky accounts are kept. With it set, a message from somebody on\nBluesky arrives in the person&#39;s Messages here, and one written here to\nsomebody on Bluesky is sent there; the sync cron reads each account&#39;s\nmessages every two minutes while it has any and at least every half hour.\nA Bluesky app signed in here with an app password that allows direct\nmessages reaches the same conversations. Empty turns direct messages with\nBluesky off, both here and in the apps.</p>\n<h2 id=\"switching-on\">Switching on</h2>\n<p> The Bluesky card checks the requirements and flips the switch.\nThen <code>php occ social:atproto:identities</code> gives every existing account its\nidentity (new accounts, and any account the command missed, get one on their\nfirst public post), and <code>php occ social:atproto:crawl</code> tells the relays to\nsubscribe. An identity is <code>pending</code> until the PLC directory has taken it —\nat once when the directory answers, else when the maintenance job gets the\noperation through; nothing goes to Bluesky for it before, and the posts\nwritten meanwhile follow within a day of the directory taking it. From then on every public post of every account goes to Bluesky as\nit is made, edits within five minutes replace the Bluesky copy and later ones\nleave it standing with its link to the current post here, and a deleted post is\ndeleted there. Direct, followers-only and unlisted posts never leave. The other\nway, people here follow Bluesky accounts by their bare handle\n(<code>alice.bsky.social</code>) and read them in their home feed; the sync job reads the\nfollowed authors&#39; feeds from Bluesky&#39;s public AppView, and asks the AppView,\nas each local account, what Bluesky did to it — follows, likes, reposts,\nreplies, mentions — which arrive in Activities like anything else. Each\nperson can switch their own presence on Bluesky off in Settings → Apps and\naccount → Bluesky (&quot;Be on Bluesky&quot;): their account is then deactivated there,\nas Bluesky deactivates one — not shown, nothing published, Bluesky apps signed\nout — and comes back as it was when they switch it on again; what they wrote\nin between stays off Bluesky. Nothing an administrator runs switches it back\non or makes the identity again: <code>occ social:atproto:identities</code> leaves it as\nit is and shows <code>(deactivated)</code> beside it, and <code>--list</code> shows each identity&#39;s\nstate.</p>\n<h2 id=\"what-the-card-shows\">What the card shows</h2>\n<p> The handle host, the PDS endpoint and the instance&#39;s\n<code>did:web</code>; the relays (<code>https://bsky.network</code> by default; &quot;Tell the relays now&quot;\nsends the crawl request again); the PLC directory and the AppView the instance\ntalks to (the defaults are Bluesky&#39;s; the interop job points them at its own —\n<code>atproto_appview</code> for public reads, <code>atproto_appview_auth</code> and\n<code>atproto_appview_did</code> for the reads made as a user, which the public AppView\nrefuses); how many identities and repositories there are — and how many of\nthose identities their owners switched off — how many events the\nreplay window holds and the head sequence number; the daemon&#39;s last report;\nthe age of the instance rotation key; and the reading side — how many Bluesky\nauthors are followed, how many accounts&#39; notifications are asked for, and how\nfar behind the slowest of each is. <code>atproto_sync_ceiling</code> (default 200) caps\nthe AppView requests one sync pass makes.</p>\n<p>The readiness checks also fetch the public OAuth protected-resource and\nauthorization-server documents from the configured PDS origin. They require\nHTTP 200 JSON responses without redirects, one matching authorization server,\nand the AT Protocol OAuth requirements: PAR, DPoP with ES256, authorization\ncode and refresh grants, S256, the <code>atproto</code> scope, public and confidential\nclient authentication, and the shared authorization and token endpoints. A\nfailed check means the public root rewrite is incomplete or the OAuth metadata\nis not suitable for Bluesky sign-in.</p>\n<p>The relay checks distinguish host discovery from repository visibility: each\nconfigured relay is asked both whether it has crawled the PDS host and whether\nit has synchronized one active local DID. The latter catches a relay that\nknows the host but has not yet indexed the sampled account.</p>\n<h2 id=\"bluesky-figures\">Bluesky figures</h2>\n<p> Beside the card, under Federation, a read-only section\nshows how Bluesky is doing here: the accounts with a Bluesky identity and how\nmany of their owners switched it off; the posts written to Bluesky from here\nin the last day and week; the repositories with their records and the size of\nthe media in them; how many Bluesky accounts are read and, with a Jetstream\nendpoint set, how far behind its stored cursor is; and the firehose — the\nsubscribers the daemon last reported, the newest event and how many events\nare kept for replay. Everything is counted from this server&#39;s own tables, at\nmost a minute ago; while Bluesky is off the section says so. The number of\nblocks in the repositories is not shown, because only a count of the whole\nblock table could give it.</p>\n<h2 id=\"blocking-on-bluesky\">Blocking on Bluesky</h2>\n<p> The card&#39;s <em>Blocked on Bluesky</em> list (or <code>occ social:atproto:block</code>) blocks a Bluesky account by its DID, or a whole PDS\nhost and the hosts under it. A blocked account is not resolved, read or heard\nfrom, and one that people here follow is removed with its posts — the\nBluesky counterpart of a domain block. Reports people file about Bluesky\naccounts with <em>forward</em> ticked go to Bluesky&#39;s moderation service\n(<code>atproto_moderation_did</code>, Bluesky&#39;s own by default), sent by this server, not\nin the reporter&#39;s name.</p>\n<h2 id=\"video\">Video</h2>\n<p> A video posted here goes to Bluesky as a Bluesky video: it is sent\nto Bluesky&#39;s video service (<code>atproto_video_service</code>, <code>https://video.bsky.app</code>\nby default, and <code>atproto_video_service_did</code>) in the poster&#39;s name, and the\npost follows once the service has made it, usually within a few minutes.\nA video Bluesky does not take — over 100 MB or three minutes, or past the\naccount&#39;s daily limit — goes out as a link to the post here. Set\n<code>atproto_video_service</code> to an empty value to publish every video as a link.</p>\n<h2 id=\"keys-and-backups\">Keys and backups</h2>\n<p> Each account&#39;s signing key and the instance&#39;s rotation and\nservice keys are stored sealed with the instance secret, like actor keys. They\nare the identities: a DID whose keys are lost can no longer be updated, and the\nperson&#39;s recovery phrase (Settings → Apps and account → Bluesky) is their own way back. Back\nup the database <em>and</em> <code>config.php</code>&#39;s <code>secret</code> together. If the secret changes,\nno key opens any more and nothing can be signed; the Bluesky card and the\nsetup check then say how many keys cannot be opened, and\n<code>OC_OLD_SECRET=&lt;previous secret&gt; php occ social:atproto:keys:reseal --old-secret-from-env</code> seals every key again under the new secret while the\nold one is still known. Without the old secret, the keys are lost. After a restore from an\nolder backup the firehose sequence goes backwards; run <code>php occ social:atproto:crawl</code> and the relays re-read every repository.\n<code>php occ social:atproto:rotate-key</code> replaces the instance rotation key; the old\none stays valid for the directory&#39;s 72-hour window.</p>\n<p><strong>Switching off</strong> keeps every identity and repository and stops the daemon&#39;s\nwork, the maintenance job and the publisher; the handles stop resolving until\nit is switched on again.</p>\n","toc":[{"id":"https","text":"https","level":2},{"id":"a-wildcard-host-for-the-handles","text":"A wildcard host for the handles","level":2},{"id":"-host-in-trusted-domains","text":"*.<host> in trusted_domains","level":2},{"id":"the-root-rules","text":"The root rules","level":2},{"id":"the-firehose-daemon","text":"The firehose daemon","level":2},{"id":"the-jetstream-listener-optional","text":"The Jetstream listener (optional)","level":2},{"id":"the-relays","text":"The relays","level":2},{"id":"cron","text":"Cron","level":2},{"id":"direct-messages-on-by-default","text":"Direct messages (on by default)","level":2},{"id":"switching-on","text":"Switching on","level":2},{"id":"what-the-card-shows","text":"What the card shows","level":2},{"id":"bluesky-figures","text":"Bluesky figures","level":2},{"id":"blocking-on-bluesky","text":"Blocking on Bluesky","level":2},{"id":"video","text":"Video","level":2},{"id":"keys-and-backups","text":"Keys and backups","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"bluesky","manual":false,"prev":{"path":"/docs/admin-raising-the-upload-limit","title":"Raising the upload limit"},"next":{"path":"/docs/admin-the-administration-page","title":"The administration page"},"parent":null},{"slug":"admin-the-administration-page","path":"/docs/admin-the-administration-page","title":"The administration page","description":"On a wide screen the groups are a list beside the page, each with a line saying what is in it, and the sections of the open group are listed under it. On a narrow one they are a row of…","group":"admin","html":"<p><strong>Administration → Aloha Social.</strong> The sections are in six groups, by what an\nadministrator came to do, and one group is shown at a time:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Group</th>\n<th>Sections</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><strong>Overview</strong></td>\n<td>Needs attention, Activity here</td>\n</tr>\n<tr>\n<td><strong>Moderation</strong></td>\n<td>Reports, Posts waiting for review, Accounts, Verified accounts, Refused pictures, Server rules</td>\n</tr>\n<tr>\n<td><strong>Sign-ups</strong></td>\n<td>Who may sign up, Waiting and invited, External accounts (only when the server sends them, see <a href=\"/docs/admin-external-users#external-users\">External users</a>)</td>\n</tr>\n<tr>\n<td><strong>Explore and features</strong></td>\n<td>About this server, What may trend, Custom emoji, Announcements, Features, For you</td>\n</tr>\n<tr>\n<td><strong>Federation</strong></td>\n<td>Allowed and blocked servers, Block lists, Relays, Deliveries</td>\n</tr>\n<tr>\n<td><strong>Server</strong></td>\n<td>Server settings, Retention, Storage, Background jobs</td>\n</tr>\n</tbody></table></div>\n<p>On a wide screen the groups are a list beside the page, each with a line saying\nwhat is in it, and the sections of the open group are listed under it. On a\nnarrow one they are a row of tabs above it. <strong>Find a setting</strong> searches every\ngroup at once, by a section&#39;s name, its description or a word it is known by\n(&quot;cron&quot;, &quot;spam&quot;, &quot;blocklist&quot;).</p>\n<p>The page opens on <strong>Overview</strong>, and <strong>Needs attention</strong> at the top of it lists\nwhat is waiting, most urgent first, each line a link to the section that deals\nwith it: background jobs that are late or not registered, deliveries close to\nbeing given up on, open reports, posts waiting for review, sign-ups waiting for\napproval, and deliveries that failed and will be tried again. The groups with\nsomething waiting carry the number beside their name; a retried delivery is\nlisted but not counted, because it needs nobody yet.</p>\n<p>Each section has an id, and the address names the one on screen:\n<code>/settings/admin/social#reports</code> opens Moderation at Reports. The report\nnotification and the Reports dashboard widget link to <code>#reports</code>, the\nFederation health widget to <code>#federation</code>.</p>\n<h2 id=\"reports\">Reports</h2>\n<p>what people here and peers elsewhere have complained about.\nThe open ones are the table; the resolved ones are folded away below them and\nread a page at a time when the fold is opened. Fifty to a page, server-side,\nwith a <em>Show more</em> under each.</p>\n<h2 id=\"activity-here\">Activity here</h2>\n<p>posts written on this server in the last day and the last\nweek, and how many accounts wrote them. Local posts only: a count that\nincluded what arrived would be a number about other servers and about this\none&#39;s retention setting.</p>\n<h2 id=\"posts-waiting-for-review\">Posts waiting for review</h2>\n<p>the review queue: the first post of a\nnew account, and posts that tripped one of the spam rules. Each row carries\nthe text, because a held post is in no timeline and there is nowhere else to\ngo and read it. <em>Publish</em> sends it out; <em>Refuse</em> deletes it and tells its\nauthor. Three switches at the top turn first-post review, the spam rules and\nholding every post with a video on it on and off.</p>\n<h2 id=\"features\">Features</h2>\n<p>what this instance offers the people using it. Three switches,\n<strong>all on by default</strong>: <em>24-hour shorts</em> (shorts that only followers see\nand that are gone after a day), and the <em>Photos</em> and <em>Videos</em>\ntimelines. Turning one off takes it out of the sidebar and stops it being\noffered; nothing already posted is touched, so a video posted while Videos\nwas off is still a video and appears again the moment it is turned back on.\nThe fourth setting is the Nextcloud groups that become Aloha Social lists, and it is\n<strong>empty by default</strong>: everybody in a chosen group gets a list for it holding\nthe members who have an Aloha Social account, nobody is followed by it and nothing\nfederates, but a group list does tell everybody in the group who else is in\nit -- which is why no group becomes one until an administrator chooses.\nDeselecting a group takes its lists away on the next cron reconcile.\nAdministrators only, not delegates.</p>\n<h2 id=\"accounts\">Accounts</h2>\n<p>every account this instance knows, whether or not anybody has\ncomplained. Search by username, by handle or by instance, filter by origin\nand by what stands against them, and act on any of them.</p>\n<h2 id=\"refused-pictures\">Refused pictures</h2>\n<p>files this instance will not store, named by their\nsha256. The one thing the account-level tools do not do is stop a <em>file</em>\ncoming back; a refused one is turned away wherever it arrives, an upload here\nor an attachment fetched from another server. The list shows the newest 100;\nwhen there are more it says how many, and <strong>Show more</strong> adds the next 100\nbelow. <strong>Allow again</strong> works on any row, on whichever page.</p>\n<h2 id=\"about-this-server\">About this server</h2>\n<p>a few named subjects, each a handful of\nhashtags, shown at the top of Explore above the trending lists. Trending on\na small server is four hashtags and a wedding; this is the part of that page\nchosen rather than counted, and it is what makes Explore look like somewhere\nto start. Nothing is named by default and the section of the page is absent\nuntil something is.</p>\n<h2 id=\"what-may-trend\">What may trend</h2>\n<p>Explore shows whatever is being talked about, counted\nand nothing else, so the first ugly hashtag to catch on does so on\neverybody&#39;s Explore page and the only remedy used to be waiting. Keeping one\nout hides it from every trending list here and from the discover grid; the\ncounters keep counting, so letting it back in restores the number it would\nhave had. Hashtags can be kept out from the live trending list beside them;\na link or a post is kept out by pasting its address. What is kept out is one\nlist whatever kind it is, because the question is &quot;what am I keeping out of\nExplore&quot;.</p>\n<h2 id=\"custom-emoji\">Custom emoji</h2>\n<p>the pictures people here can write into a post as\n<code>:shortcode:</code>. They travel with the post, so somebody on another server sees\nthem too. The upload goes through the same code <code>occ social:emoji</code> uses, so\nwhat is refused here is exactly what the command refuses.</p>\n<h2 id=\"server-rules\">Server rules</h2>\n<p>one per line. Every client shows them to\nsomebody deciding whether to join, and <code>/api/v1/instance/rules</code> serves them.\nBoth this and the emoji were <code>occ</code>-only until now, which is why most\ninstances had neither.</p>\n<h2 id=\"retention\">Retention</h2>\n<p>how long remote statuses nobody here cares about are kept.</p>\n<h2 id=\"storage\">Storage</h2>\n<p>what is on disk, split into what was posted here (somebody&#39;s\nown work, not going anywhere) and what is cached from other servers (what\nRetention removes). Added up by the background job once a day, because\ncounting it is one file lookup per stored file; the page says when it was\nmeasured. <code>occ social:media:usage</code> measures it on demand.</p>\n<p>Not a card, but the thing to know beside this one: a <strong>rejected remote\nattachment</strong> — after changing this instance&#39;s media limits or fixing a\ntemporary origin problem, retry just that file with\n<code>occ social:media:retry &lt;remote_url&gt;</code>. Use the exact <code>remote_url</code> reported\nby the attachment; Aloha Social clears the stored refusal for that one uncached\nrow and tries it immediately. The normal media checks still apply, so a\nretry can be refused again. A picture that simply took too long to arrive\nwhile its post was being received is not refused: the background job fetches\nit again, and it and the retry command allow a download two minutes.</p>\n<h2 id=\"deliveries\">Deliveries</h2>\n<p>what the outbound queue is doing, including how long\nthe longest-failing delivery has been failing: the counts say how much and\nwhere, and that says whether it started an hour ago or a week ago, which is\nthe difference between a peer rebooting and a delivery that is never going to\nhappen.</p>\n<h2 id=\"background-jobs\">Background jobs</h2>\n<p>when each of this app&#39;s cron jobs last ran, and whether\nthat is later than it should be. Almost everything the app does away from a\npage happens on a schedule: posts go out, 24-hour shorts expire, media is swept,\nvideos are transcoded, the storage figures are taken. When cron stops, the\nsymptom is a post that never arrives and a disk that never shrinks, and\nnothing in the app said so. A job is called late after <strong>three</strong> of its own\nintervals, because Nextcloud&#39;s cron is itself periodic and a five-minute job\non a fifteen-minute timer is always two intervals behind with nothing wrong\nwith it. A job missing from the list altogether is what an upgrade whose\nmigrations have not run looks like; the page says so rather than showing a\nzero. Read from Nextcloud&#39;s own job list, so it cannot drift from what\nactually happened.</p>\n<h2 id=\"allowed-and-blocked-servers\">Allowed and blocked servers</h2>\n<p>the block list or the allow list, the same\none <code>occ social:fediverse</code> manages.</p>\n<h2 id=\"block-lists\">Block lists</h2>\n<p>import a list of servers to block, with a preview of what it\nwould do, or follow one somebody else publishes; see\n<a href=\"/docs/admin-commands-by-task#commands-by-task\"><em>following a published list</em></a> under Moderation below.</p>\n<h2 id=\"announcements\">Announcements</h2>\n<p>a notice every account here is shown once.</p>\n<h2 id=\"server-settings\">Server settings</h2>\n<p>the instance-wide settings below, which had no interface at all\nbefore and could only be set with <code>occ config:app:set</code>.</p>\n<h2 id=\"relays\">Relays</h2>\n<p>the relays this server subscribes to. A new server sees only\nwhat the people on it follow, so its federated timeline is empty on the first\nday and thin for months, and nobody out there has heard of it either. A relay\nbreaks that circle: it rebroadcasts the public posts of every server\nsubscribed to it, and sends this server&#39;s public posts on to all of them.\nPaste the relay&#39;s address — relays publish it on their own front page, and it\nusually ends in <code>/actor</code> — and the row will say <strong>Waiting for an answer</strong>\nuntil the relay replies, which for some relays means when a human has looked\nat the request. <strong>Public posts and nothing else</strong> are shared: a\nfollowers-only post has an audience that was chosen, and a relay is the\nopposite of a chosen audience. A relayed post is fetched from the server that\nwrote it rather than believed from the relay, so it arrives as the post it is\nand not as &quot;relay.example boosted this&quot;.</p>\n<p>Each section is one card with its name and a line saying what it is for, and\nthe three things that cannot be taken back — suspending an\naccount, taking a post down, removing an announcement — ask in a dialog that\nsays what they will cost before they do it.</p>\n<p>The page can be <strong>delegated</strong>: hand the Aloha Social section to a group under\n<em>Administration privileges</em> and that group can moderate without administering\nthe server. Server settings and Relays are the exception — neither is rendered for a\ndelegate and their endpoints refuse them, because what they hold is a decision\nabout the server rather than about a report: a relay changes what every\nfederated timeline here holds and where every public post written here is\nsent. A delegate cannot act on a Nextcloud administrator&#39;s account, and\nnobody — administrator or delegate — can silence, suspend, lift or purge their\nown.</p>\n<hr>\n","toc":[{"id":"reports","text":"Reports","level":2},{"id":"activity-here","text":"Activity here","level":2},{"id":"posts-waiting-for-review","text":"Posts waiting for review","level":2},{"id":"features","text":"Features","level":2},{"id":"accounts","text":"Accounts","level":2},{"id":"refused-pictures","text":"Refused pictures","level":2},{"id":"about-this-server","text":"About this server","level":2},{"id":"what-may-trend","text":"What may trend","level":2},{"id":"custom-emoji","text":"Custom emoji","level":2},{"id":"server-rules","text":"Server rules","level":2},{"id":"retention","text":"Retention","level":2},{"id":"storage","text":"Storage","level":2},{"id":"deliveries","text":"Deliveries","level":2},{"id":"background-jobs","text":"Background jobs","level":2},{"id":"allowed-and-blocked-servers","text":"Allowed and blocked servers","level":2},{"id":"block-lists","text":"Block lists","level":2},{"id":"announcements","text":"Announcements","level":2},{"id":"server-settings","text":"Server settings","level":2},{"id":"relays","text":"Relays","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"the-administration-page","manual":false,"prev":{"path":"/docs/admin-bluesky","title":"Bluesky"},"next":{"path":"/docs/admin-external-users","title":"External users"},"parent":null},{"slug":"admin-external-users","path":"/docs/admin-external-users","title":"External users","description":"People without an account on this server can register one themselves, when an administrator switches it on. They log in through the normal login page and reach Aloha Social and nothing…","group":"admin","html":"<p>People without an account on this server can register one themselves, when\nan administrator switches it on. They log in through the normal login page\nand reach Aloha Social and nothing else. It is off by default, and the three cards\nare in the <strong>Sign-ups</strong> group of the administration page, for\nadministrators proper only: who may have an account here is not a\nmoderator&#39;s decision.</p>\n<p><strong>Registration.</strong> The switch <em>Let people register</em>, the maximum number of\nexternal accounts (registration closes when that many exist, with a message\nsaying so), the megabytes of media each may upload, and the minimum age a\nperson confirms. <em>Who gets an account</em> is anybody who registers, anybody an\nadministrator approves, or only the holders of an invitation link; an\ninvitation admits its holder in every mode, without approval. With <em>Confirm\nthe email address</em> on, which is the default, the account is made when the\nlink in the confirmation email is followed, so the server needs working\nmail. The form also asks to accept the server rules (the <strong>Server rules</strong> section) and\nlinks the privacy policy and legal notice set in Administration → Theming.\nThe additional registration and privacy information box is plain text shown\non the introduction page and beside the form. It starts with a translated\ntemplate and can be adapted for this instance. <em>Require registrants to accept\nthis notice</em> adds a required checkbox. When enabled, Aloha Social records the text\nversion, the time and the accepted text with the account. The record remains\nfor the lifetime of that account and is removed when the account is deleted.\nPending records transfer the acknowledgement to the account when it is made;\nrejected records are removed, and unconfirmed registrations expire after 24\nhours. These\nsettings provide an audit trail, not legal advice or a guarantee that a notice\nis sufficient for a particular jurisdiction. The operator remains responsible\nfor local policies and any consent required.\n<em>Usernames nobody may register</em> adds to a built-in list (<code>admin</code>, <code>root</code>,\n<code>support</code>, <code>social</code>, <code>postmaster</code> and similar). Email domains on the access\nblock list are refused here as they are for every account.</p>\n<p>The form does not tell whoever fills it in whether an email address is\nalready registered here, or whether a username is the login of a Nextcloud\nuser without an Aloha Social account. Either is answered like a new\nregistration, with &quot;check your email&quot;, and the email goes to that address\ninstead: <em>You already have an account</em>, or <em>Choose another username</em>. Such a\nregistration counts towards the limit of registrations per address like any\nother. With <em>Confirm the email address</em> off a new registration is answered\ndifferently, so there the answers can be told apart.</p>\n<p><em>Require two-factor authentication</em> is Nextcloud&#39;s own mandatory two-factor\nsetting for the <code>social-external</code> group, the same one as in Administration →\nSecurity; changing it asks for your password. With it on, external users set\nup a second factor when they first log in.</p>\n<p>Where Aloha Social is enabled for some groups only, external users are let in by\nadding <code>social-external</code> to them. Switching registration on does that, and\nthe card warns and offers a button when the restriction leaves them out.</p>\n<p><strong>Waiting and invited.</strong> The registrations waiting for approval, with\n<em>Approve</em>, which makes the account and emails the person, and <em>Reject</em>, which\ndeletes the registration and emails them, with a reason if you give one.\nBelow it, the invitation links: a note to remember who each is for, how many\nregistrations it admits (0 for any number) and how many days it works (0 for\never). <em>Let everybody here send invitation links</em> also gives every user an\n<em>Invite people</em> section in their Aloha Social settings, single-use links that work\nfor a week, at most ten open at a time.</p>\n<p><strong>External accounts.</strong> Every external account with its email and verification\nstatus, enabled or disabled status, registration source, when it registered\nand last logged in, media usage, and the version and time of any accepted\nregistration notice. Search matches the username and display name. Sort by username or registration\ndate, newest or oldest. Filters cover account status, registration source and\ndate, login activity, minimum media usage and notice acceptance. The list is paged and scans at most a\nbounded number of candidates per request.\n<em>Disable</em> and\n<em>Enable</em> are Nextcloud&#39;s own. <em>Promote</em> makes one an ordinary account of this\nserver with the same username, password, two-factor setup and Aloha Social\naccount; from then on the groups and apps you give them apply, and there is\nno way back. <em>Delete</em> removes the account and its Aloha Social account, the way\ndeleting any Nextcloud user does. Both ask for your password. External users\nalso appear on the Users page, with <em>Aloha Social</em> as their backend and in the\n<code>social-external</code> group.</p>\n<p><strong>Guests app.</strong> Aloha Social&#39;s self-registered accounts use Aloha Social&#39;s own <code>Social</code>\nuser backend and the <code>social-external</code> group. They are distinct from accounts\ncreated by the <a href=\"https://github.com/nextcloud/guests\">Guests app</a>, which uses\nthe <code>Guests</code> backend and <code>guest_app</code> group. Aloha Social&#39;s account restrictions and\ncollaborator filtering target only its own backend, so they do not classify a\nGuests-app account as an Aloha Social external account. The two apps can be installed\ntogether, but the Guests app controls which Nextcloud apps its accounts may\nopen: add <code>social</code> to its app whitelist if those accounts should use Aloha Social.\nThis setting does not grant a Guests account the Aloha Social-only restrictions;\nGuests accounts remain governed by the Guests app and Nextcloud group policy.</p>\n<p>What an external user reaches: Aloha Social, logging in and out, their personal\nsettings for their details, language, security, appearance and\nnotifications, and their notifications. Everything else is refused before it\nruns, including every app installed later, and WebDAV, CalDAV and CardDAV are\nrefused altogether, so Nextcloud&#39;s desktop and mobile clients and Talk do not\nwork for them; Mastodon apps do. Nobody outside Aloha Social finds them in the\nshare dialog, the contacts menu, the user status list or the system address\nbook. See <a href=\"/docs/architecture-external-users#external-users\">Architecture.md</a> for how.</p>\n<p><code>occ social:reset</code> refuses to run while external accounts exist: their logins\nare rows of this app.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"external-users","manual":false,"prev":{"path":"/docs/admin-the-administration-page","title":"The administration page"},"next":{"path":"/docs/admin-moderating","title":"Moderating"},"parent":null},{"slug":"admin-moderating","path":"/docs/admin-moderating","title":"Moderating","description":"Reports arrive from two directions: a local user reporting somebody through a client, and a peer instance sending POST /api/v1/reports about one of its own users' complaints. Both land in…","group":"admin","html":"<p>Reports arrive from two directions: a local user reporting somebody through a\nclient, and a peer instance sending <code>POST /api/v1/reports</code> about one of its\nown users&#39; complaints. Both land in the same table, and the administrators (and\nthe delegated group) are notified.</p>\n<p>There are five things a moderator can do to an account, in order of weight:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Action</th>\n<th>What it costs</th>\n<th>Reversible</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><strong>Warn</strong></td>\n<td>Nothing. The account is told there is a problem and everything else stays as it is.</td>\n<td>n/a</td>\n</tr>\n<tr>\n<td><strong>Mark everything sensitive</strong></td>\n<td>Every post the account makes from now on is marked sensitive, whatever it said. It stays in the timelines and its followers still see it — behind a click.</td>\n<td>yes, completely</td>\n</tr>\n<tr>\n<td><strong>Silence</strong></td>\n<td>The account leaves the public and global timelines. Whoever deliberately follows it still sees it.</td>\n<td>yes, completely</td>\n</tr>\n<tr>\n<td><strong>Take down</strong></td>\n<td>One post is deleted. A local post is deleted everywhere it reached; a remote one only here.</td>\n<td>no</td>\n</tr>\n<tr>\n<td><strong>Suspend</strong></td>\n<td>Everything the account posted here is deleted, its cached actor is dropped, its follows in both directions go, and everything it sends afterwards is refused. A <strong>local</strong> account&#39;s suspension is federated as a <code>Delete</code>.</td>\n<td>the refusal stops; nothing deleted comes back</td>\n</tr>\n</tbody></table></div>\n<p><em>Resolve</em> marks the complaint handled and changes nothing about the account, so\na report can be closed with any of the four applied, or with none.</p>\n<p><strong>What is recorded.</strong> <code>social_moderation</code> holds what stands <em>now</em> — one row an\naccount, replaced by the next decision and gone when it is lifted.\n<code>social_strikes</code> is the history: a warning, a silence, a suspension, a takedown\nand a lift each write a row naming the moderator, and nothing removes one\nexcept the account itself going. The strike count in the account browser counts\nwhat stands against the account, so a lift is in the history and not in the\ncount.</p>\n<p><strong>Verified accounts.</strong> This server can vouch for accounts — a company verifying\nits own people, a community the accounts it knows — and a verified account\ncarries a check beside its name everywhere here, labelled <em>Verified by</em> and a\nname. Moderators verify an account under <strong>Moderation → Verified accounts</strong>\n(by its handle, which lists every verified account, who verified it and when)\nor from the account&#39;s profile menu (<em>Verify account</em>, <em>Remove verification</em>).\nAny account can be verified: one here, one on another Fediverse server, one on\nBluesky.</p>\n<p>The name after <em>Verified by</em> is the <strong>verifying account</strong>&#39;s, which an\nadministrator (not a delegate) chooses in the same section: a local account\nthat stands for the server or the organisation. Without one, the checks are\ngiven in the server&#39;s own name (Theming). With Bluesky switched on, the\nverifying account is given a Bluesky identity, and each verification of an\naccount that has one — every local account, every Bluesky account — is also\npublished from it as a Bluesky verification, written again by itself when the\nverified account changes its handle or display name. <strong>Bluesky apps show those\nchecks only once Bluesky trusts the verifying account as a verifier</strong>, which is\nBluesky&#39;s decision and not one this server can make (Bluesky&#39;s announcement:\n<a href=\"https://bsky.social/about/blog/04-21-2025-verification\">https://bsky.social/about/blog/04-21-2025-verification</a>); until then they are\nshown here only. A Fediverse account without a Bluesky identity is verified\nhere only, and the list says so. Choosing another verifying account moves every\nverification to it in the background; choosing none takes the published ones\nback.</p>\n<p><strong>The audit log.</strong> Suspending, silencing, lifting, taking a post down and\nblocking or unblocking an instance each emit\n<code>OCP\\Log\\Audit\\CriticalActionPerformedEvent</code>, so with core&#39;s <code>admin_audit</code> app\nenabled they land in the audit log beside &quot;user X was added to group Y&quot;, naming\nthe moderator who acted. Without that app nothing listens and nothing is\nwritten.</p>\n<p><strong>Before anybody sees it.</strong> Two rules hold a post back instead of publishing\nit. The spam rules are on by default; first-post review is off until an\nadministrator turns it on:</p>\n<ul>\n<li><strong>first-post review</strong> (<code>review_first_post</code>) holds the first post of an\naccount that has published nothing here yet. Accounts here are Nextcloud\nusers, so a spammer has to be given an account by this server before they can\npost at all — and on an instance that hands accounts to strangers, the\ncheapest thing that can be done about it is that the first thing they write\nis seen by a person. <strong>Off by default</strong>: on the ordinary instance, whose\naccounts are colleagues an administrator created, it held every new person&#39;s\nfirst post and made their first five minutes look broken — the composer\nclosed, the post did not appear, and it existed only in a panel nobody had\nopened yet. Turn it on where registration is open.\n<strong>An administrator&#39;s own posts are never held</strong>: somebody who can empty the\nqueue is not somebody to put in it, and the first post on a brand-new\ninstance is the administrator&#39;s — held, it made a fresh install look broken,\nbecause the post did not appear and the only place it existed was a panel\nthey had not opened yet.</li>\n<li><strong>autospam</strong> (<code>autospam</code>) holds a post that trips one of a very short list of\nrules: more than five links in a short post, or more than five mentions from\nan account that nobody follows and that follows nobody. There is no wordlist\nand no score — &quot;seven links&quot; is something a moderator can agree or disagree\nwith in a second, and &quot;0.82&quot; is not.</li>\n</ul>\n<p>A <strong>direct message is never held</strong>, whatever it says: holding one would put\nprivate correspondence in front of a moderator who was not written to, for a\nmachine&#39;s reason. Nor is a post by an account a decision already stands\nagainst — that account is being dealt with by the decision.</p>\n<p>Nothing is published, and nothing is deleted, without somebody pressing\nsomething. A held post is stored as the <em>request</em> the client sent, not as a\npost: it is in no timeline, no profile, no outbox and no search, not even its\nauthor&#39;s, and their own copy of it is in <strong>Settings → Your posts → Waiting for review</strong>,\nwhere they can take it back. Approving replays the request down the path an\nimmediate post takes and dates it now. Refusing deletes it, tells the author,\nand records a takedown strike. One account may have twenty waiting; past that\nits posts are refused outright, because nobody is going to read the fortieth.</p>\n<p><strong>Instances, not accounts.</strong> <em>Allowed and blocked servers</em> is the instance-wide list.\nIn block-list mode (the default, <code>access_type=all_but</code>) everything on it is\nrefused, including every subdomain, and blocking a domain queues a purge of\neverything it ever sent. In allow-list mode (<code>none_but</code>) the list is the only\ninstances this server will talk to at all — and it is matched exactly, so a\nsubdomain of a listed domain is a different instance and is not covered.</p>\n<p>The one thing an entry does cover is <strong>what an allowed instance holds\nelsewhere</strong>. A post&#39;s pictures are fetched from whatever host the post says\nholds them, and that is routinely not the host the post came from: a post on\n<code>mastodon.xyz</code> carries its media on <code>6-28.mastodon.xyz</code>, and object storage or\na CDN is common besides. Those hosts are judged as the instance that named\nthem, because nobody can list the buckets another server keeps its pictures\nin. Judging them on their own refused every picture from every allowed\ninstance, so allow-list mode federated text and nothing else. An instance that is a nuisance\nrather than a menace can be <em>silenced</em> instead with <code>occ social:fediverse silence</code>: its accounts leave the public timelines and stay readable for the\npeople who follow them.</p>\n<hr>\n<h2 id=\"from-a-pixelfed-admin-app\">From a Pixelfed admin app</h2>\n<p>The administration screens of Pixelfed&#39;s official app call Pixelfed&#39;s own\n<code>/api/admin/*</code> routes, and this instance answers them — behind the same gate\nas everything above, and through the same service, so a takedown from the app\nis the same takedown as one from this page. Users, open reports and the\ninstances this server federates with are all there; Pixelfed&#39;s <code>unlisted</code> on\nan instance is the silence tier and its <code>banned</code> the deny list. Its <strong>autospam</strong>\nscreen draws this instance&#39;s own review queue, with <em>not spam</em> publishing a held\npost and <em>delete</em> refusing it. What this instance does not have — per-account\n&quot;unlisted&quot; or &quot;content warning&quot; flags, switches that flip from the app — is\nanswered as absent or refused with a reason, never as a 200 that changed\nnothing. The\nroutes and their answers are in <a href=\"/docs/api\">API.md</a>.</p>\n","toc":[{"id":"from-a-pixelfed-admin-app","text":"From a Pixelfed admin app","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"moderating","manual":false,"prev":{"path":"/docs/admin-external-users","title":"External users"},"next":{"path":"/docs/admin-configuration","title":"Configuration"},"parent":null},{"slug":"admin-configuration","path":"/docs/admin-configuration","title":"Configuration","description":"Nothing here is reachable through core's app-config API: the settings page writes through its own validated endpoints, and a delegate can write only what the moderation routes accept.","group":"admin","html":"<p>Everything below is app configuration under <code>social</code>, read and written with:</p>\n<pre><code class=\"language-bash\">occ config:app:get social &lt;key&gt;\nocc config:app:set social &lt;key&gt; --value=&lt;value&gt;\n</code></pre>\n<p>Nothing here is reachable through core&#39;s app-config API: the settings page\nwrites through its own validated endpoints, and a delegate can write only what\nthe moderation routes accept.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":[{"path":"/docs/admin-set-by-the-app-not-by-you","title":"Set by the app, not by you","description":"The base address every id is built from, copied from overwrite.cli.url the first time the app is opened. Changing it by hand does not rewrite the ids already issued.","parent":true},{"path":"/docs/admin-server-settings","title":"Server settings","description":"Instance-wide settings. Most of them are on the Server section of the settings page, which validates the ranges given here; every one can be set with occ.","parent":true},{"path":"/docs/admin-moderation-and-federation","title":"Moderation and federation","description":"all_but — federate with everyone except the listed instances (block list). none_but — federate only with the listed ones (allow list).","parent":true},{"path":"/docs/admin-external-users-2","title":"External users","description":"Set from the External users cards; these are the keys they write.","parent":true},{"path":"/docs/admin-per-account","title":"Per account","description":"User values under the app social, written by the app for one account and read back by it; occ user:setting <user> social <key> shows them. The For you learning switches a reader sets for…","parent":true},{"path":"/docs/admin-system-configuration","title":"System configuration","description":"And one of Nextcloud's own that matters here: allow_local_remote_servers, which must be on for an instance to federate with anything on a private address. That is a development arrangement.","parent":true}],"anchor":"configuration","manual":false,"prev":{"path":"/docs/admin-moderating","title":"Moderating"},"next":{"path":"/docs/admin-set-by-the-app-not-by-you","title":"Set by the app, not by you"},"parent":null},{"slug":"admin-set-by-the-app-not-by-you","path":"/docs/admin-set-by-the-app-not-by-you","title":"Set by the app, not by you","description":"The base address every id is built from, copied from overwrite.cli.url the first time the app is opened. Changing it by hand does not rewrite the ids already issued.","group":"admin","html":"<h2 id=\"cloud-url\">cloud_url</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>The base address every id is built from, copied from <code>overwrite.cli.url</code> the first time the app is opened. Changing it by hand does not rewrite the ids already issued.</p>\n<h2 id=\"social-url\">social_url</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>The app&#39;s own base URL (<code>…/apps/social/</code>), which every id is minted from and which profile links, WebFinger and NodeInfo use. Derived from <code>cloud_url</code> — never from the request — the first time the app is opened with <code>cloud_url</code> set, and again by <code>occ social:reset</code>.</p>\n<h2 id=\"social-address\">social_address</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>The hostname accounts are federated under, when it is not the host of <code>cloud_url</code>. Only set this if the fediverse address genuinely differs from the Nextcloud host, and only before the first account exists.</p>\n<h2 id=\"service\">service</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Unused; a leftover of the original installer.</p>\n<h2 id=\"installed-version\">installed_version</h2>\n<p>Written by the upgrade machinery.</p>\n<h2 id=\"media-usage\">media_usage</h2>\n<p><strong>Default: </strong><em>(written by the job)</em></p>\n<p>The last measurement of what is on disk, as JSON with the moment it was taken. Bookkeeping, not a setting: the walk is a <code>stat</code> per stored file and belongs in the cron, so the administration page reads this rather than counting on page load.</p>\n<h2 id=\"directory-known\">directory_known</h2>\n<p><strong>Default: </strong><em>(written by the job)</em></p>\n<p>What <code>Cron\\Cache</code> last found out about the servers the Discover page may ask: the <code>fediverse.info</code> server list and each federated peer&#39;s NodeInfo software, as JSON with when each was read. Bookkeeping, not a setting: the page reads this rather than asking those servers while somebody waits.</p>\n<h2 id=\"polls-swept\">polls_swept</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>How far the closed-poll sweep has got, as a timestamp.</p>\n<h2 id=\"stream-author-hosts-filled\">stream_author_hosts_filled</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Set to <code>1</code> by <code>Cron\\StreamAuthorHosts</code> once every post carries the host of its author in <code>social_stream.author_host</code>. Until then the domain-block and silenced-instance filters also match a post by its actor id, which is slower. Bookkeeping, not a setting.</p>\n<h2 id=\"story-secret\">story_secret</h2>\n<p><strong>Default: </strong><em>(generated)</em></p>\n<p>The secret a 24-hour short&#39;s fetch capability (the bearcap Pixelfed fetches it with) is derived from, made the first time one is published. Changing it invalidates every outstanding capability at once, which is the only revocation it needs: a 24-hour short lives a day. Never set this by hand.</p>\n<h2 id=\"cache-cron-start\">cache_cron_start</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Which of <code>Cron\\Cache</code>&#39;s steps the next pass begins with. Written by the job when it runs out of its five-minute budget, so the steps at the end of its list are not the ones that never run on a busy instance; a pass that finishes starts from the top again. Bookkeeping, not a setting.</p>\n<h2 id=\"poster-backfill-cursor\">poster_backfill_cursor</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>The nid of the last stored video <code>Cron\\VideoPosters</code> looked at for a poster frame. Written by the job, five videos every fifteen minutes; a video it could not take a frame from is behind it and is not tried again by the job — <code>occ social:media:posters</code> tries every video that still has none. Bookkeeping, not a setting: delete it to have the job go through every video again.</p>\n<h2 id=\"client-api-root\">client_api_root</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p>Whether the client API answered at the domain root the last time the <em>Mastodon apps cannot connect</em> setup check probed it: <code>1</code>, <code>0</code>, or unset where nothing has asked yet. Written down rather than only cached because the OAuth discovery document is built from it, and that is a route any client may call.</p>\n<h2 id=\"client-api-scheme\">client_api_scheme</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p>Whether that probe&#39;s answer carried addresses in the scheme it was asked over: <code>0</code> once a proxy that drops the scheme has been seen (every absolute URL says <code>http</code> on an <code>https</code> site), which the same setup check reports.</p>\n<h2 id=\"dest-nid-filled\">dest_nid_filled</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Set to <code>1</code> by <code>Version1000Date20260917000001</code> once every recipient row carries the post&#39;s numeric id, which is what lets the home timeline use its fast page query; a flag, because asking the table for a row with a zero nid is a full scan of the largest table the app has. Bookkeeping, not a setting.</p>\n<h2 id=\"atproto-firehose-status\">atproto_firehose_status</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>The firehose daemon&#39;s last report (<code>occ social:atproto:serve</code>), as JSON: whether it runs, its pid, when it started and last reported, the head sequence number and how many relays are subscribed. The Bluesky card and the setup check read it; a daemon that has not reported for a minute is shown as stopped.</p>\n<h2 id=\"atproto-crawl-accepted\">atproto_crawl_accepted</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Unix time of the latest relay crawl request accepted for this PDS. Bookkeeping used by the automatic retry schedule; do not edit it by hand.</p>\n<h2 id=\"atproto-crawl-attempted\">atproto_crawl_attempted</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Unix time of the latest automatic relay crawl attempt, including attempts no relay accepted. Bookkeeping used to avoid requesting crawls too often; do not edit it by hand.</p>\n<h2 id=\"atproto-crawl-results\">atproto_crawl_results</h2>\n<p><strong>Default: </strong><code>[]</code></p>\n<p>JSON result of the latest automatic relay crawl request, keyed by relay, or an error when the request failed. Shown in the Bluesky status diagnostics; do not edit it by hand.</p>\n<h2 id=\"atproto-delete-cursor\">atproto_delete_cursor</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Where the Bluesky deletion sweep got to in its bounded pass over stored Bluesky posts, 25 at a time. The pass restarts at the end so posts with temporarily unavailable PDSes are retried. Bookkeeping, not a setting.</p>\n<h2 id=\"atproto-delete-max-nid\">atproto_delete_max_nid</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Highest post id captured at the start of the current deletion-sweep pass. New posts wait for the next pass, so a growing timeline cannot keep the sweep&#39;s end moving forward. Bookkeeping, not a setting.</p>\n<h2 id=\"atproto-detach-cursor\">atproto_detach_cursor</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>The same for the sweep over the last month&#39;s local quotes of Bluesky posts, which marks a quote the quoted author detached as revoked here too.</p>\n<h2 id=\"stream-archived-filled\">stream_archived_filled</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Set to <code>1</code> by <code>Version1000Date20261013100500</code> once every post carries a value in <code>social_stream.archived</code>. Until then every list of posts also admits a post whose column is still empty, an <code>OR</code> the database plans badly.</p>\n<h2 id=\"stream-media-kind-filled\">stream_media_kind_filled</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Set to <code>1</code> by <code>Version1000Date20261013100500</code> once no post is left without a <code>media_kind</code>. Until then the Photos, Videos and media filters also judge a post by its attachments, and the narrowed timelines use the slower joined query.</p>\n<h2 id=\"retention-checked\">retention_checked</h2>\n<p><strong>Default: </strong><em>(written by the prune)</em></p>\n<p>How far today&#39;s retention walk has judged the old remote posts, as <code>day|creation|id_prim</code>. Each run carries on from it, so a post retention keeps is looked at once a day; the first run of a new day starts again from the oldest post. Deleting it restarts the walk.</p>\n<h2 id=\"index-skipped\">index_skipped</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p>How many posts the timeline index repair (<code>Cron\\Index</code>) gave up on; shown by the <em>index repairs</em> setup check. See <a href=\"/docs/admin-posts-the-index-repairs-skipped#posts-the-index-repairs-skipped\">Posts the index repairs skipped</a>.</p>\n<h2 id=\"search-index-skipped\">search_index_skipped</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p>How many posts the search backfill (<code>Cron\\SearchIndex</code>) left out of the word index; shown by the same check.</p>\n<h2 id=\"search-index-failing\">search_index_failing</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p><code>cursor:count</code> of the chunk the search backfill keeps failing on; after two failures it indexes one post at a time until it finds the post to skip.</p>\n","toc":[{"id":"cloud-url","text":"cloud_url","level":2},{"id":"social-url","text":"social_url","level":2},{"id":"social-address","text":"social_address","level":2},{"id":"service","text":"service","level":2},{"id":"installed-version","text":"installed_version","level":2},{"id":"media-usage","text":"media_usage","level":2},{"id":"directory-known","text":"directory_known","level":2},{"id":"polls-swept","text":"polls_swept","level":2},{"id":"stream-author-hosts-filled","text":"stream_author_hosts_filled","level":2},{"id":"story-secret","text":"story_secret","level":2},{"id":"cache-cron-start","text":"cache_cron_start","level":2},{"id":"poster-backfill-cursor","text":"poster_backfill_cursor","level":2},{"id":"client-api-root","text":"client_api_root","level":2},{"id":"client-api-scheme","text":"client_api_scheme","level":2},{"id":"dest-nid-filled","text":"dest_nid_filled","level":2},{"id":"atproto-firehose-status","text":"atproto_firehose_status","level":2},{"id":"atproto-crawl-accepted","text":"atproto_crawl_accepted","level":2},{"id":"atproto-crawl-attempted","text":"atproto_crawl_attempted","level":2},{"id":"atproto-crawl-results","text":"atproto_crawl_results","level":2},{"id":"atproto-delete-cursor","text":"atproto_delete_cursor","level":2},{"id":"atproto-delete-max-nid","text":"atproto_delete_max_nid","level":2},{"id":"atproto-detach-cursor","text":"atproto_detach_cursor","level":2},{"id":"stream-archived-filled","text":"stream_archived_filled","level":2},{"id":"stream-media-kind-filled","text":"stream_media_kind_filled","level":2},{"id":"retention-checked","text":"retention_checked","level":2},{"id":"index-skipped","text":"index_skipped","level":2},{"id":"search-index-skipped","text":"search_index_skipped","level":2},{"id":"search-index-failing","text":"search_index_failing","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"set-by-the-app-not-by-you","manual":false,"prev":{"path":"/docs/admin-configuration","title":"Configuration"},"next":{"path":"/docs/admin-server-settings","title":"Server settings"},"parent":"admin-configuration"},{"slug":"admin-server-settings","path":"/docs/admin-server-settings","title":"Server settings","description":"Instance-wide settings. Most of them are on the Server section of the settings page, which validates the ranges given here; every one can be set with occ.","group":"admin","html":"<p>Instance-wide settings. Most of them are on the <strong>Server</strong> section of the\nsettings page, which validates the ranges given here; every one can be set with\n<code>occ</code>.</p>\n<h2 id=\"contact-email\">contact_email</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>Who to write to about this instance. Mastodon&#39;s <code>instance.email</code>: every client reads it on its first request and shows it on the server&#39;s about page. Empty until somebody fills it in, which until now most instances never did, because nothing said it existed.</p>\n<h2 id=\"contact-account\">contact_account</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>The local Aloha Social account responsible for this instance. Choose a local account by username under Server settings; remote accounts and team accounts without a Nextcloud user are refused. Aloha Social stores the owning Nextcloud user id and resolves the current account when it builds <code>/api/v1/instance</code> and <code>/api/v2/instance</code>, so profile changes are reflected without rewriting the setting. Clearing the field omits the contact account.</p>\n<h2 id=\"extended-description\">extended_description</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>The long form of what this instance is, for <code>/api/v1/instance/extended_description</code>. Up to 10000 characters.</p>\n<h2 id=\"max-size\">max_size</h2>\n<p><strong>Default: </strong><code>10</code></p>\n<p>The largest picture or file an upload may be, in MB. 1–10240.</p>\n<h2 id=\"max-video-size\">max_video_size</h2>\n<p><strong>Default: </strong><code>2048</code></p>\n<p>The largest video, in MB. 1–102400. A peer will refuse a great deal less than the ceiling.</p>\n<h2 id=\"image-max-edge\">image_max_edge</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>The longest edge a <strong>stored</strong> picture may have, in pixels. <code>0</code> stores every upload exactly as it arrived — the default, and the only setting that loses nothing: this app strips metadata losslessly and re-encodes only a picture it has to rotate. Set it (480–16384) on an instance where storage costs money or whose people post from a 48-megapixel phone. A picture already inside the ceiling is not re-encoded, because shrinking nothing and losing a generation anyway is the worst of both.</p>\n<h2 id=\"image-quality\">image_quality</h2>\n<p><strong>Default: </strong><code>85</code></p>\n<p>What a re-encoded picture is stored at, 40–100. Only consulted when <code>image_max_edge</code> is set.</p>\n<h2 id=\"video-transcode\">video_transcode</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Whether videos uploaded here are re-encoded to H.264 in an MP4 by a background job; a video cached from another server is never touched. <strong>On by default, and it does nothing where ffmpeg is not installed</strong> — the <em>Aloha Social: video conversion</em> setup check says which it is. What it converts: <code>.mov</code>, WebM, Matroska and the other formats in <code>VideoTranscodeService::CONVERTIBLE</code>, and an MP4 whose video ffprobe does not report as H.264 (HEVC, which phones write and only Safari plays). An H.264 MP4 is never re-encoded; without ffprobe an MP4 is left as it is. Why: <strong>Pixelfed&#39;s default <code>media_types</code> accepts <code>video/mp4</code> and nothing else</strong>, so every <code>video/quicktime</code> posted from here, which is every video straight off an iPhone, is dropped by its inbox without a word to anybody, and Safari will not play WebM. <strong>The converted file replaces the original, which is deleted</strong> — re-encoding is lossy, so switch it off where the uploaded files must be kept exactly as they are. Never runs during an upload: converting a video is minutes rather than the seconds a poster frame takes, so the upload finishes as it always did. A <strong>new post</strong> carrying such a video is queued but <strong>held back</strong> while the video it carries is converted by a job of its own at the next cron run, and goes out naming the MP4 — for at most ten minutes (<code>VideoDeliveryHold::HOLD_SECONDS</code>), after which it is delivered as it is. Posts without such a video, and every post on a server without ffmpeg or with this off, are not held at all. Older videos are converted by a sweep, one every quarter of an hour, or <code>occ social:media:transcode</code> to work through a backlog now. An instance that never saved this key has it on after upgrading.</p>\n<h2 id=\"video-max-height\">video_max_height</h2>\n<p><strong>Default: </strong><code>1080</code></p>\n<p>The tallest a converted video is written, 240–2160. Only smaller, never larger: a 480p video is left at 480p. Only consulted when <code>video_transcode</code> is on.</p>\n<h2 id=\"video-ladder\">video_ladder</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Whether each stored MP4 is <strong>also</strong> written at a ladder of smaller sizes, as HLS, so a player can pick the one that fits the connection. A different question from <code>video_transcode</code>, which is about a video being playable at all elsewhere; this is about it being watchable on a phone on a train. Off by default, because it is several ffmpeg encodes per video on this server. Each rung is one file — <code>-hls_flags single_file</code> writes the rendition as a fragmented MP4 and the playlist addresses its segments as byte ranges — so a forty-minute video is three files rather than a thousand, which is also the shape PeerTube publishes. The original is kept and is what a player without HLS falls back to. Needs ffmpeg <strong>and</strong> ffprobe. One video every half-hour, or <code>occ social:media:ladder</code> to work through a backlog now. Built from <code>video/mp4</code> only: a <code>.mov</code> goes through the transcoder first.</p>\n<h2 id=\"video-ladder-heights\">video_ladder_heights</h2>\n<p><strong>Default: </strong><code>360,720,1080</code></p>\n<p>Which heights, comma-separated, 144–2160. Heights at or above a video&#39;s own are skipped rather than upscaled, and the video&#39;s own height is always a rung, so the best rung is never worse than the file beside it. A list with nothing usable in it is refused by the admin card rather than silently replaced with the default. Only consulted when <code>video_ladder</code> is on.</p>\n<h2 id=\"search-window-days\">search_window_days</h2>\n<p><strong>Default: </strong><code>365</code></p>\n<p>How far back a content search scans while it cannot use its word index: before <code>Cron\\SearchIndex</code> has indexed the posts stored before the upgrade (until <code>search_index_ready</code> is <code>1</code>), for a query that is only the beginning of a word, and for one made only of the English and German function words the index leaves out (<code>the</code>, <code>and</code>, <code>der</code>, <code>und</code> …). Such a search is a range rather than one indexed word, and unbounded it reads every post the instance has ever stored; a year covers what anybody is looking for. <code>0</code> searches everything, which an instance small enough can afford to say. A search for whole words reads the index and is not bounded by this.</p>\n<h2 id=\"rec-v4-enabled\">rec_v4_enabled</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Whether the automatically ranked For You timeline and its separate activity-learning controls are available. Off by default; the administrator can change it in Social settings. Changing this switch invalidates pending learning events from open pages.</p>\n<h2 id=\"rec-remote-discovery-paused\">rec_remote_discovery_paused</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Stops recommendation-driven remote Fediverse and Bluesky discovery requests while preserving already cached candidates.</p>\n<h2 id=\"rec-learning-paused\">rec_learning_paused</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Stops instance-wide recommendation behavior learning, including signals from accounts that opted in.</p>\n<h2 id=\"rec-force-legacy-feed\">rec_force_legacy_feed</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Temporarily serves the established hashtag-interest feed instead of the ranked For You feed.</p>\n<h2 id=\"local-actor-cursor\">local_actor_cursor</h2>\n<p><strong>Default: </strong><code>&#39;&#39;</code></p>\n<p>Bookkeeping, not a setting: where the cron&#39;s local-account refresh walk got to. It used to read every local account into memory on every pass; it pages now, and this is what makes the next pass carry on rather than start again.</p>\n<h2 id=\"profile-link-cursor\">profile_link_cursor</h2>\n<p><strong>Default: </strong><code>&#39;&#39;</code></p>\n<p>Bookkeeping, not a setting: where the cron&#39;s walk over the local accounts whose profile fields carry a link got to, so the next pass checks the next ones.</p>\n<h2 id=\"video-quota\">video_quota</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>How many megabytes of video <strong>one account</strong> may keep here; <code>0</code> is no quota, which is what every instance has in effect today. A different question from <code>max_video_size</code>, which is a ceiling on one file: that is about a single request, this about a year of them. Off by default because an instance that has been running without a quota and acquires one on upgrade would start refusing uploads from exactly the accounts that use it most. Checked once, where an upload is written, against the size recorded on each stored file — so a video uploaded before this app recorded sizes counts as nothing until the daily usage job has been past it, which fills the column in as it walks. The <strong>ladders this server builds do not count against it</strong>: they are made because an administrator asked for them, are several times the size of the upload, and would turn a quota somebody was told about into one several times smaller. They are counted in what an administrator is shown, because they are real disk. Who is holding what is under <strong>Administration → Aloha Social → Storage</strong>.</p>\n<h2 id=\"nsfw-policy\">nsfw_policy</h2>\n<p><strong>Default: </strong><code>default</code></p>\n<p>What happens to media somebody marked sensitive, for readers who have not chosen for themselves. PeerTube&#39;s three NSFW policies under Mastodon&#39;s names for the same three states: <code>show_all</code> (PeerTube&#39;s <em>display</em>), <code>default</code> (its <em>blur</em> — covered, the blurhash showing, one press away, and what this app has always done) and <code>hide_all</code> (its <em>hide</em> — not drawn, and no button to draw it). Anybody can override it for themselves under <strong>Settings</strong> in the app, and &quot;follow the instance&quot; stays a state of its own, so changing this moves everybody who is following it and nobody who has chosen. A <strong>content warning is a different thing</strong> and always covers its post, whatever this says.</p>\n<h2 id=\"review-videos\">review_videos</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Whether every post with a video on it waits for a moderator. The third rule of the review queue, beside a new account&#39;s first post and the spam rules, and the one an instance that hosts video wants: a video is minutes of somebody&#39;s attention and a great deal of somebody else&#39;s disk. <strong>Unlike the other two it is not about the account</strong> — a trusted account with a thousand posts behind it is held by it too, every time, because what it is about is the video. A moderator&#39;s own video is not held, and neither is a direct message. Under <strong>Administration → Aloha Social → Posts waiting to be looked at</strong>.</p>\n<h2 id=\"inbox-throttle\">inbox_throttle</h2>\n<p><strong>Default: </strong><code>300</code></p>\n<p>Incoming inbox requests allowed per origin host per minute. <code>0</code> accepts everything, which is what an instance behind its own rate limiter wants.</p>\n<h2 id=\"rate-limit-user\">rate_limit_user</h2>\n<p><strong>Default: </strong><code>900</code></p>\n<p>How many client API requests one <strong>signed-in account</strong> may make per window. The routes that fan out — search, the directories, the follow graph — carry limits of their own and Nextcloud enforces those; this is the budget for everything else, which was some three hundred routes with no limit at all. Generous on purpose: it exists to stop a scraper reading the whole instance at machine speed, not to pace an app. One budget for the whole API, not one per route. <code>0</code> switches it off, which is what an instance behind its own limiter wants. Federation, the internal queue and the routes that serve bytes (attachments, avatars, emoji, GIFs) are never counted — one public page is forty requests for pictures, and deliveries arrive in bursts from a handful of addresses.</p>\n<h2 id=\"rate-limit-anon\">rate_limit_anon</h2>\n<p><strong>Default: </strong><code>300</code></p>\n<p>The same budget for a caller with <strong>no account</strong>, counted per address.</p>\n<h2 id=\"rate-limit-window\">rate_limit_window</h2>\n<p><strong>Default: </strong><code>300</code></p>\n<p>How long that window is, in seconds.</p>\n<h2 id=\"token-max-days\">token_max_days</h2>\n<p><strong>Default: </strong><code>365</code></p>\n<p>How many days an OAuth token works from the moment it was granted, <strong>however much it is used</strong>. A token idle for a year stops working anyway; this is about one in use, which used to live for ever — every request kept it alive, so a token copied off a phone lived as long as whoever held the copy kept using it. Past it the app is signed out and the person signs in again; there are no refresh tokens. Each person sees when under <strong>Settings → Authorized apps</strong>. <code>0</code> lets a token in use live for ever.</p>\n<h2 id=\"follow-limit\">follow_limit</h2>\n<p><strong>Default: </strong><code>100</code></p>\n<p>How many follows <strong>one account</strong> may send in an hour. A compromised account, or one running a script, can fan out follows to thousands of servers from this instance&#39;s address in a few minutes — every one a signed request this instance is answerable for. An hour rather than a day because what this catches is a burst, and high enough that importing a follow list from another server still goes through. Counted from the rows, so it holds on an instance with no memcache. <code>0</code> is no limit.</p>\n<h2 id=\"domain-media-quota\">domain_media_quota</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>How many megabytes of media <strong>one other server</strong> may keep here. Every picture on a post somebody here follows is fetched and cached, and nothing bounded that by where it came from: one server posting large images at a high rate fills the disk of every instance that follows anybody on it. The server is the host of the file&#39;s own address (its <code>url</code>), which for a Mastodon instance is often a separate media host. Counted from the figure the daily storage walk takes, plus successfully cached bytes from that host since — rejected or unreadable downloads do not spend quota. The figure is up to a day coarse and errs towards refusing early. Off by default, because an instance that has been federating for a year and acquires a quota on upgrade would start refusing the pictures of the servers it talks to most. Who is holding what is under <strong>Administration → Aloha Social → Storage</strong>.</p>\n<h2 id=\"secure-mode\">secure_mode</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Refuse ActivityPub fetches that are not signed. Mastodon&#39;s secure mode. Turning it on makes this instance invisible to every peer that does not sign what it asks for, and to every anonymous reader; it is a decision about who to federate with, not a hardening step to apply by default.</p>\n<h2 id=\"publish-blocks\">publish_blocks</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Publish the deny list on <code>/api/v1/instance/domain_blocks</code>, the way Mastodon does, so somebody choosing a server can see who it will not talk to. Whether <em>this</em> server wants that read by anybody is a disclosure decision.</p>\n<h2 id=\"allow-self-signed\">allow_self_signed</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Accept peers whose certificates do not check out. <strong>Development only</strong>: on a server anybody else uses, this hands every federated request to whoever can answer for the address.</p>\n<h2 id=\"stories\">stories</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Whether this instance offers Shorts — a picture or a video that is gone in a day. Off, the bar goes from the timeline and nothing new is taken; what was posted expires as it would have. Set from the Sections card.</p>\n<h2 id=\"gif-pack\">gif_pack</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Whether the composer offers the animated emoji pack. What ships is the list, not the pictures: <code>Cron\\GifPack</code> fetches the first screenful into appdata ahead of time and the rest are fetched as somebody picks them. <code>0</code> fetches nothing and leaves the picker with what <code>occ social:gif add</code> added.</p>\n<h2 id=\"section-photos\">section_photos</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Whether the Photos section is offered in the sidebar: the same posts read through one filter. Turning it off hides the section and stops it being offered; the posts are not touched, and turning it back on shows them again. Set from the Sections card.</p>\n<h2 id=\"section-videos\">section_videos</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>The same for the Videos section.</p>\n<h2 id=\"group-lists\">group_lists</h2>\n<p><strong>Default: </strong><code>[]</code></p>\n<p>Which Nextcloud groups become lists for their members, as a JSON array of group ids; at most 100. Empty is no groups, which is the default: every group a person was in used to become a list, which tells everybody in a group who else is in it. A group that no longer exists is dropped when the setting is read, not written back. Set from the Sections card.</p>\n<h2 id=\"interests\">interests</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Legacy hashtag-interest timeline switch and fallback configuration. The ranked web For You feed is controlled separately by <code>rec_v4_enabled</code>; see <a href=\"/docs/for-you\">For-You.md</a>.</p>\n<h2 id=\"interests-default\">interests_default</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Legacy learning default used by the compatibility interest endpoints. It does not grant consent to the separate ranked-feed behavioral learning system.</p>\n<h2 id=\"interests-half-life\">interests_half_life</h2>\n<p><strong>Default: </strong><code>30</code></p>\n<p>Legacy hashtag score decay, in days. Used only by the compatibility interest system.</p>\n<h2 id=\"interests-threshold\">interests_threshold</h2>\n<p><strong>Default: </strong><code>3</code></p>\n<p>Legacy threshold for listing learned hashtag interests.</p>\n<h2 id=\"interests-cap\">interests_cap</h2>\n<p><strong>Default: </strong><code>30</code></p>\n<p>Legacy limit for the number of listed hashtag interests.</p>\n<h2 id=\"interests-window\">interests_window</h2>\n<p><strong>Default: </strong><code>7</code></p>\n<p>Legacy compatibility timeline lookback window, in days.</p>\n<h2 id=\"cache-actor-days\">cache_actor_days</h2>\n<p><strong>Default: </strong><code>180</code></p>\n<p>Days to keep a cached remote account nobody here refers to any more — not followed, not following, no post stored, no relation pending — before <code>Cron\\Cache</code> evicts it with its avatar. <code>0</code> disables the sweep.</p>\n<h2 id=\"atproto-oauth-trusted\">atproto_oauth_trusted</h2>\n<p><strong>Default: </strong><code>[]</code></p>\n<p>The Bluesky apps an administrator vouches for, by OAuth client id, as a JSON array: the Bluesky sign-in consent page shows those apps&#39; own name and logo, which it never takes from an app on its own word. Set from the Bluesky card.</p>\n","toc":[{"id":"contact-email","text":"contact_email","level":2},{"id":"contact-account","text":"contact_account","level":2},{"id":"extended-description","text":"extended_description","level":2},{"id":"max-size","text":"max_size","level":2},{"id":"max-video-size","text":"max_video_size","level":2},{"id":"image-max-edge","text":"image_max_edge","level":2},{"id":"image-quality","text":"image_quality","level":2},{"id":"video-transcode","text":"video_transcode","level":2},{"id":"video-max-height","text":"video_max_height","level":2},{"id":"video-ladder","text":"video_ladder","level":2},{"id":"video-ladder-heights","text":"video_ladder_heights","level":2},{"id":"search-window-days","text":"search_window_days","level":2},{"id":"rec-v4-enabled","text":"rec_v4_enabled","level":2},{"id":"rec-remote-discovery-paused","text":"rec_remote_discovery_paused","level":2},{"id":"rec-learning-paused","text":"rec_learning_paused","level":2},{"id":"rec-force-legacy-feed","text":"rec_force_legacy_feed","level":2},{"id":"local-actor-cursor","text":"local_actor_cursor","level":2},{"id":"profile-link-cursor","text":"profile_link_cursor","level":2},{"id":"video-quota","text":"video_quota","level":2},{"id":"nsfw-policy","text":"nsfw_policy","level":2},{"id":"review-videos","text":"review_videos","level":2},{"id":"inbox-throttle","text":"inbox_throttle","level":2},{"id":"rate-limit-user","text":"rate_limit_user","level":2},{"id":"rate-limit-anon","text":"rate_limit_anon","level":2},{"id":"rate-limit-window","text":"rate_limit_window","level":2},{"id":"token-max-days","text":"token_max_days","level":2},{"id":"follow-limit","text":"follow_limit","level":2},{"id":"domain-media-quota","text":"domain_media_quota","level":2},{"id":"secure-mode","text":"secure_mode","level":2},{"id":"publish-blocks","text":"publish_blocks","level":2},{"id":"allow-self-signed","text":"allow_self_signed","level":2},{"id":"stories","text":"stories","level":2},{"id":"gif-pack","text":"gif_pack","level":2},{"id":"section-photos","text":"section_photos","level":2},{"id":"section-videos","text":"section_videos","level":2},{"id":"group-lists","text":"group_lists","level":2},{"id":"interests","text":"interests","level":2},{"id":"interests-default","text":"interests_default","level":2},{"id":"interests-half-life","text":"interests_half_life","level":2},{"id":"interests-threshold","text":"interests_threshold","level":2},{"id":"interests-cap","text":"interests_cap","level":2},{"id":"interests-window","text":"interests_window","level":2},{"id":"cache-actor-days","text":"cache_actor_days","level":2},{"id":"atproto-oauth-trusted","text":"atproto_oauth_trusted","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"server-settings","manual":false,"prev":{"path":"/docs/admin-set-by-the-app-not-by-you","title":"Set by the app, not by you"},"next":{"path":"/docs/admin-moderation-and-federation","title":"Moderation and federation"},"parent":"admin-configuration"},{"slug":"admin-moderation-and-federation","path":"/docs/admin-moderation-and-federation","title":"Moderation and federation","description":"all_but — federate with everyone except the listed instances (block list). none_but — federate only with the listed ones (allow list).","group":"admin","html":"<h2 id=\"access-type\">access_type</h2>\n<p><strong>Default: </strong><code>all_but</code></p>\n<p><code>all_but</code> — federate with everyone except the listed instances (block list). <code>none_but</code> — federate only with the listed ones (allow list).</p>\n<h2 id=\"access-list\">access_list</h2>\n<p><strong>Default: </strong><code>[]</code></p>\n<p>The instances on that list, as a JSON array of hostnames. An entry covers every subdomain of itself. Managed from the settings page and by <code>occ social:fediverse</code>.</p>\n<h2 id=\"silenced-list\">silenced_list</h2>\n<p><strong>Default: </strong><code>[]</code></p>\n<p>Instances whose accounts are kept out of the public and global timelines but stay readable for whoever follows them. The middle tier a block does not have.</p>\n<h2 id=\"retention-days\">retention_days</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Remote statuses older than this that no local user interacted with, follows the author of, or replied below are deleted, with their cached attachments. <code>0</code> disables it. Local content is never touched.</p>\n<h2 id=\"notification-retention-days\">notification_retention_days</h2>\n<p><strong>Default: </strong><code>90</code></p>\n<p>In-app notification rows older than this are deleted by the same prune, whether or not <code>retention_days</code> is set. <code>0</code> keeps them for good.</p>\n<h2 id=\"notification-policy-defaults\">notification_policy_defaults</h2>\n<p><strong>Default: </strong><em>(calm)</em></p>\n<p>What the notification policy of a <strong>new</strong> local account starts as, as JSON with the five keys of Mastodon&#39;s policy, each <code>accept</code> or <code>filter</code>. Unset, it is the calm policy: people the account does not follow, accounts younger than 30 days, private mentions it did not ask for and accounts this server limited are <strong>held for review</strong> (no bell, push or mail; they wait in the account&#39;s requests), everyone else gets through. Read once, when the account is created — the first-run screen, <code>occ social:account:create</code>, an external user&#39;s sign-up and every other path go through the same <code>AccountService::createActor()</code> — so changing it <strong>never touches an existing account</strong>; accounts from before this setting existed keep receiving everything until their owner chooses. Written through <code>GET</code>/<code>POST /apps/social/admin/notification-policy</code> (administrators only, not delegates; any value but <code>accept</code> or <code>filter</code> is refused with a 422, because an administrator decides what waits for review, never what is thrown away), whose current value the settings page receives as <code>notificationPolicyDefaults</code>.</p>\n<h2 id=\"federate-blocks\">federate_blocks</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Whether a user&#39;s own blocks are federated to the blocked account&#39;s instance. <code>0</code> keeps them local.</p>\n<h2 id=\"publish-video-objects\">publish_video_objects</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Whether a post that is a video is federated as an ActivityPub <code>Video</code> (PeerTube&#39;s shape) rather than a <code>Note</code> with an attachment. Off by default: Pixelfed&#39;s inbox handles only <code>Note</code>s and silently drops a <code>Video</code>, so with this on no video posted here reaches a Pixelfed follower. Mastodon draws both shapes; PeerTube draws only the <code>Video</code>. Turn it on for an instance whose audience is on PeerTube.</p>\n<h2 id=\"starter-pack-sources\">starter_pack_sources</h2>\n<p><strong>Default: </strong>unset</p>\n<p>Where starter packs are read in from, as a JSON array: a handle (<code>&quot;user@host&quot;</code>) reads every public collection of that account, an <code>https://</code> address reads that one collection, and <code>&quot;bluesky:suggested&quot;</code> reads Bluesky&#39;s suggested starter packs while Bluesky is on. Unset reads the collections @Gargron curates on mastodon.social (<code>Gargron@mastodon.social</code>) and Bluesky&#39;s suggestions; <code>[]</code> reads none and removes what was read. Read once a day, or now with <code>occ social:starter-packs:refresh</code>. Only collections marked discoverable and not sensitive are offered, and only the members whose own server authorized their inclusion (FEP-7aa9), at most 50 a pack. An account you silenced or suspended, one on a server you block or silence, and a Bluesky account you block is left out of every pack, and a pack by such a curator is not offered. A server that does not answer on the day keeps what was read from it last time. The <code>starter_packs</code> value set to <code>[]</code> hides these packs too.</p>\n<h2 id=\"network-stats\">network_stats</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Whether the statistics page may ask <a href=\"https://fedidb.com\">FediDB</a> how big the fediverse is — servers, accounts, accounts that posted in the last month — to show beside the number of servers this one federates with. One request every six hours for the whole instance, carrying no account, no query and nothing about this instance; a survey that does not answer is left alone for half an hour. Set it to <code>0</code> and the section is absent rather than zeroed: an instance that makes no outbound request to draw a page is a legitimate thing to want. The same value governs the <strong>growth</strong> section below it, which asks <a href=\"https://fediverse.observer\">Fediverse Observer</a> for the last two years month by month — FediDB publishes a snapshot and no history, so the shape over time comes from a second survey, once a day. The two do not agree about the totals, because they crawl different servers and count dormant accounts differently, so the page keeps them apart and names each: a page that averaged them would produce a number neither survey would stand behind.</p>\n<h2 id=\"rules\">rules</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>The instance rules shown by <code>/api/v1/instance/rules</code>, one per line.</p>\n<h2 id=\"verification-account\">verification_account</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>The local account this server verifies accounts in the name of, by actor id; set under Moderation → Verified accounts (administrators only). See <a href=\"/docs/admin-moderating#moderating\">Moderating</a>.</p>\n<h2 id=\"review-first-post\">review_first_post</h2>\n<p><strong>Default: </strong><code>0</code></p>\n<p>Hold the first post of an account that has published nothing here yet, for a moderator to see before it goes out. Off by default; turn it on where accounts are handed to strangers. An administrator&#39;s own posts are never held — a moderator waiting on themselves is a circle, and on a new instance the first post is theirs.</p>\n<h2 id=\"review-posts\">review_posts</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>How many posts an account must have had published before its posts stop being held. <code>1</code> is first-post review as it has always meant. An account graduates by having that many posts approved — a person having looked at it that many times, which is the only measure of trust here that is not a guess. Capped at 20.</p>\n<h2 id=\"autospam\">autospam</h2>\n<p><strong>Default: </strong><code>1</code></p>\n<p>Hold a post that trips one of the spam rules — more than five links in a short post, or more than five mentions from an account nobody follows and that follows nobody. Nothing is ever refused by the rules, only shown to a person.</p>\n<h2 id=\"ai-tags\">ai_tags</h2>\n<p><strong>Default: </strong><em>(empty)</em></p>\n<p>Hashtags that label a post as <strong>made with AI</strong>, comma-separated, added to the built-in list (<code>#aigenerated</code>, <code>#aigeneratedart</code>, <code>#generatedbyai</code>, <code>#genai</code>, <code>#generativeai</code>, <code>#madewithai</code>, <code>#midjourney</code>, <code>#stablediffusion</code>, <code>#dalle</code>, <code>#dalle3</code>, <code>#sora</code>, <code>#fluxai</code>, <code>#comfyui</code>). Compared without the <code>#</code> and without regard to case; a built-in tag cannot be removed. The generic topic tag <code>#AI</code> is always ignored, even if listed here; tags such as <code>#aiart</code>, <code>#aiimage</code>, <code>#aiphoto</code> and <code>#aivideo</code> are not built in but an administrator can add them. A reader who turns on <strong>Hide posts made with AI</strong> under Settings → Blocking is shown no post carrying one of these tags, and no post whose picture states machine-generation provenance in its metadata (IPTC <code>DigitalSourceType</code> of <code>trainedAlgorithmicMedia</code> or <code>compositeWithTrainedAlgorithmicMedia</code>, in XMP or inside a C2PA manifest — read when the picture is stored, before the metadata is stripped). <strong>What this can and cannot do:</strong> it recognises <em>labels</em> — a hashtag the author or their tool added, a provenance mark a generator wrote into the file — and nothing else. A generated post that carries neither is not recognised; a real photograph tagged <code>#ai</code> by its author is not mistaken for generated. There is no classifier here and there should not be one.</p>\n<h2 id=\"blocklist-sources\">blocklist_sources</h2>\n<p><strong>Default: </strong><code>[]</code></p>\n<p>The published block lists this instance follows, as JSON: one object per source with its id, where it is fetched from, which format it is in, whether it is on, and what the last run did. Empty until an administrator turns one on under <strong>Block lists</strong>; <code>Cron\\BlocklistSync</code> re-reads the sources that are on daily. See <a href=\"/docs/admin-commands-by-task#commands-by-task\">following a published list</a>.</p>\n","toc":[{"id":"access-type","text":"access_type","level":2},{"id":"access-list","text":"access_list","level":2},{"id":"silenced-list","text":"silenced_list","level":2},{"id":"retention-days","text":"retention_days","level":2},{"id":"notification-retention-days","text":"notification_retention_days","level":2},{"id":"notification-policy-defaults","text":"notification_policy_defaults","level":2},{"id":"federate-blocks","text":"federate_blocks","level":2},{"id":"publish-video-objects","text":"publish_video_objects","level":2},{"id":"starter-pack-sources","text":"starter_pack_sources","level":2},{"id":"network-stats","text":"network_stats","level":2},{"id":"rules","text":"rules","level":2},{"id":"verification-account","text":"verification_account","level":2},{"id":"review-first-post","text":"review_first_post","level":2},{"id":"review-posts","text":"review_posts","level":2},{"id":"autospam","text":"autospam","level":2},{"id":"ai-tags","text":"ai_tags","level":2},{"id":"blocklist-sources","text":"blocklist_sources","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"moderation-and-federation","manual":false,"prev":{"path":"/docs/admin-server-settings","title":"Server settings"},"next":{"path":"/docs/admin-external-users-2","title":"External users"},"parent":"admin-configuration"},{"slug":"admin-external-users-2","path":"/docs/admin-external-users-2","title":"External users","description":"Set from the External users cards; these are the keys they write.","group":"admin","html":"<p>Set from the External users cards; these are the keys they write.</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Default</th>\n<th>Meaning</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>external_enabled</code></td>\n<td><code>0</code></td>\n<td>Whether people without an account may register one for Aloha Social.</td>\n</tr>\n<tr>\n<td><code>external_max</code></td>\n<td><code>100</code></td>\n<td>How many external accounts may exist.</td>\n</tr>\n<tr>\n<td><code>external_media_quota</code></td>\n<td><code>1024</code></td>\n<td>Megabytes of media each external user may upload. <code>0</code> is no quota.</td>\n</tr>\n<tr>\n<td><code>external_signup_mode</code></td>\n<td><code>approval</code></td>\n<td><code>open</code>, <code>approval</code> or <code>invite</code>.</td>\n</tr>\n<tr>\n<td><code>external_verify_email</code></td>\n<td><code>1</code></td>\n<td>Whether the email address is confirmed before the account is made.</td>\n</tr>\n<tr>\n<td><code>external_min_age</code></td>\n<td><code>16</code></td>\n<td>The age a person confirms at registration. <code>0</code> asks nothing.</td>\n</tr>\n<tr>\n<td><code>external_reserved</code></td>\n<td><code>[]</code></td>\n<td>Usernames nobody may register, as a JSON array, on top of the built-in ones.</td>\n</tr>\n<tr>\n<td><code>external_user_invites</code></td>\n<td><code>0</code></td>\n<td>Whether every user may send invitation links.</td>\n</tr>\n<tr>\n<td><code>external_signup_notice</code></td>\n<td><em>(empty)</em></td>\n<td>The additional registration and privacy information shown on the introduction page and beside the form, as plain text. Empty shows the translated template text.</td>\n</tr>\n<tr>\n<td><code>external_signup_notice_required</code></td>\n<td><code>0</code></td>\n<td>Whether registering requires ticking that the notice was read. With it on, the notice&#39;s version, the time and the text as accepted are recorded with the account (the per-account keys below).</td>\n</tr>\n</tbody></table></div>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"external-users","manual":false,"prev":{"path":"/docs/admin-moderation-and-federation","title":"Moderation and federation"},"next":{"path":"/docs/admin-per-account","title":"Per account"},"parent":"admin-configuration"},{"slug":"admin-per-account","path":"/docs/admin-per-account","title":"Per account","description":"User values under the app social, written by the app for one account and read back by it; occ user:setting <user> social <key> shows them. The For you learning switches a reader sets for…","group":"admin","html":"<p>User values under the app <code>social</code>, written by the app for one account and\nread back by it; <code>occ user:setting &lt;user&gt; social &lt;key&gt;</code> shows them. The For\nyou learning switches a reader sets for themselves are listed in\n<a href=\"/docs/for-you\">For-You.md</a>.</p>\n<h2 id=\"app-settings\">app_settings</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p>The Pixelfed app&#39;s own switches for this account, as JSON (<code>updated_at</code> and the <code>common</code> groups), stored for <code>/api/v1.1/compose/settings</code> the way Pixelfed stores them so that a reinstalled app finds itself as it was left. Only Pixelfed&#39;s own switches are kept; the server interprets none of them.</p>\n<h2 id=\"external-signup-notice-version\">external_signup_notice_version</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p>The version of the signup notice an external user accepted, when <code>external_signup_notice_required</code> was on at registration. Removed with the account.</p>\n<h2 id=\"external-signup-notice-accepted\">external_signup_notice_accepted</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p>When they accepted it, as a Unix timestamp.</p>\n<h2 id=\"external-signup-notice-snapshot\">external_signup_notice_snapshot</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p>The notice&#39;s text as it was when they accepted it.</p>\n<h2 id=\"handle-publish-failed\">handle_publish_failed</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p>When Nextcloud last refused the account&#39;s fediverse handle on its profile, as a Unix timestamp. Publishing the handle is not tried again for a day after that, and the value is cleared once a publish succeeds.</p>\n<h2 id=\"keyboard-shortcuts\">keyboard_shortcuts</h2>\n<p><strong>Default: </strong><em>(unset)</em></p>\n<p><code>0</code> once the account turned the web app&#39;s one-key shortcuts off in Settings → Help → Keyboard shortcuts; anything else leaves them on.</p>\n","toc":[{"id":"app-settings","text":"app_settings","level":2},{"id":"external-signup-notice-version","text":"external_signup_notice_version","level":2},{"id":"external-signup-notice-accepted","text":"external_signup_notice_accepted","level":2},{"id":"external-signup-notice-snapshot","text":"external_signup_notice_snapshot","level":2},{"id":"handle-publish-failed","text":"handle_publish_failed","level":2},{"id":"keyboard-shortcuts","text":"keyboard_shortcuts","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"per-account","manual":false,"prev":{"path":"/docs/admin-external-users-2","title":"External users"},"next":{"path":"/docs/admin-system-configuration","title":"System configuration"},"parent":"admin-configuration"},{"slug":"admin-system-configuration","path":"/docs/admin-system-configuration","title":"System configuration","description":"And one of Nextcloud's own that matters here: allow_local_remote_servers, which must be on for an instance to federate with anything on a private address. That is a development arrangement.","group":"admin","html":"<p>Two <code>config.php</code> values, neither documented anywhere else:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Default</th>\n<th>Meaning</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>social.checkssl</code></td>\n<td><code>true</code></td>\n<td>Whether the WebFinger setup check verifies the certificate it is offered. Set it to <code>false</code> on an instance using a certificate the server itself does not trust. It affects the probe only — federation still verifies.</td>\n</tr>\n<tr>\n<td><code>social.tests</code></td>\n<td><em>(unset)</em></td>\n<td>Enables <code>GET /apps/social/test/{account}/</code>, a WebFinger self-test. Leave it unset outside development.</td>\n</tr>\n</tbody></table></div>\n<p>And one of Nextcloud&#39;s own that matters here: <code>allow_local_remote_servers</code>,\nwhich must be on for an instance to federate with anything on a private\naddress. That is a development arrangement.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"system-configuration","manual":false,"prev":{"path":"/docs/admin-per-account","title":"Per account"},"next":{"path":"/docs/admin-commands-by-task","title":"Commands by task"},"parent":"admin-configuration"},{"slug":"admin-commands-by-task","path":"/docs/admin-commands-by-task","title":"Commands by task","description":"The full reference is OCC-Commands.md; these are the ones an administrator reaches for.","group":"admin","html":"<p>The full reference is <a href=\"/docs/occ\">OCC-Commands.md</a>; these are the ones an\nadministrator reaches for.</p>\n<p><strong>Is it working?</strong></p>\n<pre><code class=\"language-bash\">occ social:check:install            # the setup checks it can run from the console, plus repairs\nocc social:check:install --offline  # the same without the network probe\nocc social:queue:status             # what the outbound queue is doing\nocc social:details &lt;id&gt;             # who can see one post and where it lands\n</code></pre>\n<p>Aloha Social also repairs the recipient and hashtag side indexes automatically in\nbounded five-minute cron passes. Each pass visits at most 500 streams, stores\nits last fully indexed NID, and resumes from there; a failed row is retried on\nthe next passes, and after five failures it is logged as skipped and the walk\nmoves on. Once the walk reaches the newest post the repair is complete\n(app config <code>index_done</code> = <code>1</code>) and the job does nothing more; deleting that\nkey runs it again from the stored cursor. Keep Nextcloud background jobs\nworking as <code>Cron\\Index</code> relies on them. The manual <code>occ social:check:install --index --force</code> remains a full\nrebuild for administrators; it clears and repopulates both indexes and should\nnot be scheduled as a cron command.</p>\n<p><strong>External users</strong></p>\n<pre><code class=\"language-bash\">occ social:external list                                        # who, and how many of how many\nOC_PASS=... occ social:external add &lt;handle&gt; --email EMAIL --password-from-env\nocc social:external promote &lt;handle&gt;                            # make one an ordinary account\n</code></pre>\n<p><strong>Delivery is behind</strong></p>\n<pre><code class=\"language-bash\">occ social:queue:process            # drain it now instead of waiting for cron\nocc social:queue:retry              # give failing deliveries the full run of retries again\n</code></pre>\n<p><strong>Moderation</strong></p>\n<pre><code class=\"language-bash\">occ social:fediverse list                  # the access list; bare, it prints the mode\nocc social:fediverse add &lt;instance&gt;        # block it (or allow it, in allow-list mode)\nocc social:fediverse remove &lt;instance&gt;\nocc social:fediverse import &lt;csv_file&gt;     # add reviewed CSV domains to a block list\nocc social:fediverse import &lt;csv_file&gt; --dry-run   # print what it would add, change nothing\nocc social:fediverse silence &lt;instance&gt;    # out of the public timelines, still followable\n</code></pre>\n<p><code>import</code> reads the first CSV column, accepts a <code>#domain</code>/<code>domain</code> header or a\nplain one-domain-per-line file, validates the complete file before changing\nanything, and adds the domains to the existing <code>all_but</code> block list. It refuses\nallow-list mode, does not fetch or enable a list on its own, and applies the\nnormal audit and queued domain-purge behavior to every new entry.</p>\n<p>The same import is on the admin page under <strong>Block lists</strong>, with a file picker\nand a preview: it reads the file, says how many servers it would block and how\nmany it would silence, and changes nothing until the button under that number\nis pressed. The page and the command run the same code, so a list imported one\nway cannot turn out to have been read differently the other.</p>\n<p><strong>Following a published list.</strong> The same section offers two sources, both off\nuntil an administrator turns one on:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Source</th>\n<th>What it is</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>mastodon.social</code></td>\n<td>that server&#39;s own moderated-servers list, through Mastodon&#39;s <code>/api/v1/instance/domain_blocks</code></td>\n</tr>\n<tr>\n<td><code>thebad.space</code></td>\n<td>a shared list rather than one server&#39;s, as a CSV export by how many of its participating servers agree. The default is <code>/80</code>: what eighty per cent of them block</td>\n</tr>\n</tbody></table></div>\n<p>A Mastodon server answers <code>/api/v1/instance/domain_blocks</code> only where its\nadministrators turned publishing on, and most have not — which is why one such\nserver is offered rather than a row of them. Point either source at another\nserver&#39;s endpoint to follow that one instead; a server that does not publish\nanswers &quot;that server did not hand over a list&quot; rather than failing.</p>\n<p>A followed source is re-read once a day by <code>OCA\\Social\\Cron\\BlocklistSync</code>.\n<strong>Check now</strong> reads one immediately; for a source that is off it reports what\nfollowing it <em>would</em> do, which is how to read a list before adopting it.</p>\n<p>Turning a source off stops it being re-read. It does not undo what it already\napplied: a block purges what this instance held of that server, and that does\nnot come back.</p>\n<p><strong>Severity is honoured.</strong> A row marked <code>suspend</code> blocks the server; a row\nmarked <code>silence</code> silences it — out of the public, global and hashtag timelines,\nstill followable — and a row marked <code>noop</code> does nothing. Reading the column and\nblocking everything would delete what this instance holds of servers the source\nmerely limits: of mastodon.social&#39;s 276 entries, 30 are silences, and of The\nBad Space&#39;s 200 at the 80% threshold, 2 are. A list with no severity column is\na list of blocks, which is what a bare one-domain-per-line file has always\nmeant here.</p>\n<p>Every entry added queues a domain purge, which deletes what this instance holds\nof that server, so the import asks before it writes — <code>--no-interaction</code> skips\nthe question, and <code>--dry-run</code> prints the domains and changes nothing. A row\nnaming a single label (<code>com</code>, <code>localhost</code>) is refused, because an entry covers\nevery subdomain of itself and one such row would block a whole top-level\ndomain; so is a row naming this instance. That is not a public-suffix check:\n<code>co.uk</code> still passes, which is what <code>--dry-run</code> is for. Files over 8 MB are\nrefused unread. An\nadministrator can download and review a <a href=\"https://tweaking.thebad.space/exports\">The Bad Space CSV export</a>\nbefore importing it; the export source and moderation policy remain the\nadministrator&#39;s choice.</p>\n<p><strong>Housekeeping</strong></p>\n<pre><code class=\"language-bash\">occ social:stream:prune             # apply retention, purge finished queue rows and old notifications\nocc social:cache:refresh            # re-fetch cached remote accounts\nocc social:domain:purge &lt;instance&gt;  # remove what a now-blocked instance sent\n</code></pre>\n<p><strong>Starting over</strong></p>\n<pre><code class=\"language-bash\">occ social:reset                    # empties every Social table; asks twice\nocc social:reset --uninstall        # and drops the tables, jobs and app config\n</code></pre>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"commands-by-task","manual":false,"prev":{"path":"/docs/admin-system-configuration","title":"System configuration"},"next":{"path":"/docs/admin-running-a-large-instance","title":"Running a large instance"},"parent":null},{"slug":"admin-running-a-large-instance","path":"/docs/admin-running-a-large-instance","title":"Running a large instance","description":"Everything below is optional and nothing on a small instance needs any of it. These are the three things that stop working first as an instance grows, and what to do about each.","group":"admin","html":"<p>Everything below is optional and nothing on a small instance needs any of it.\nThese are the three things that stop working first as an instance grows, and\nwhat to do about each.</p>\n<p><strong>Install <code>notify_push</code>.</strong> Without it every open tab asks the server for the\nhome timeline and the unread count <strong>every thirty seconds</strong>; with it the server\ntells the client instead and the poll drops to once every five minutes — a\ntenfold cut in the request volume, for one app install. The polls also answer\n<code>304</code> now when nothing has changed, so even without it most of them cost an\nindex probe and an empty response rather than a rendered page, and a tab\nnobody is looking at does not poll at all: it catches up once when it is\nreturned to, and while the server keeps failing it backs off to one attempt\nin five minutes.</p>\n<p><strong>Run delivery workers.</strong> <code>Cron\\Queue</code> delivers twenty servers at a time and\ntakes batch after batch for its 240 seconds: with peers that answer within a\nsecond that is up to 6,000 deliveries a run, some 30,000 an hour, and when every\nbatch runs into a dead peer&#39;s 30-second timeout still about 160 a run. A peer\nthat fails is left alone — from a minute, doubling to an hour — and that is\nkept in the database (<code>social_host_breaker</code>), so it holds without a memcache and\nacross runs: a dead server costs one timeout per wait, not one per row. An\ninstance whose accounts are followed across tens of thousands of servers still\noutgrows that with a popular post, and <code>occ social:worker</code> is the same delivery\nin a loop that does not stop; <strong>several may run at once</strong>, see\n<a href=\"/docs/occ\">OCC-Commands.md</a> for a systemd unit. The worker still delivers\none row at a time, so it is more processes, not wider ones, that add capacity.</p>\n<p><strong>Watch the cron actually finish.</strong> The steps are budgeted at 300 seconds a pass\nand resume where they stopped, so a pass that runs out of time is normal. A pass\nthat <em>never</em> reaches the later steps is not: <code>social:check</code> and the Nextcloud log\nare where that shows.</p>\n<p><strong>Cached remote accounts</strong> are refreshed by <code>Cron\\Cache</code> for up to 90 seconds\na pass, and their details (counts, pinned posts, verified links) for up to 90\nmore, batch after batch of fifty, the longest-waiting first. A refresh is one\nfetch, so at a third of a second to a second each that is 90 to 300 accounts a\npass, 11,000 to 36,000 a day — enough for the ten-day refresh cycle to hold\nover roughly 110,000 to 360,000 cached accounts, where one batch of fifty a\npass held to about 60,000. A details refresh is three or more fetches, so it\ncovers fewer, 30 to 90 a pass. Past those sizes the cycle stretches and the\nstalest still go first; a key that rotated in between is fetched again the\nfirst time a signature fails to verify.</p>\n<p><strong>Plan the upgrade window on a large instance.</strong> Three upgrade steps rewrite\n<code>social_stream</code> row by row, and they run inside <code>occ upgrade</code>, while the server\nis in maintenance mode — there is no way to defer them:</p>\n<ul>\n<li><code>Version1000Date20260917000001</code> copies each post&#39;s sort key onto every one of\nits recipient rows in <code>social_stream_dest</code>;</li>\n<li><code>Version1000Date20260917000003</code> reads every post&#39;s attachments to record what\nkind of media it carries;</li>\n<li><code>Version1000Date20260917000005</code> reads every post&#39;s content to record whether\nit is a news item.</li>\n</ul>\n<p>Each walks the table 5,000 posts to a statement, after a <code>COUNT(*)</code> over it, and\nprints its progress every 50,000. The time is proportional to the number of\nposts — for the first step to the number of recipient rows, which is several per\npost — and to how fast the database rewrites rows; none of it has been measured\non a large instance, so time it on a copy of the database first. As a rough\nrule of thumb rather than a measurement, expect minutes per million posts for\neach of the three, and so hours of maintenance mode for ten million. The media\nand news steps only touch rows that still carry no value, so an upgrade\ninterrupted during them picks up where it stopped; the first starts again from\nthe beginning.</p>\n<p>A fourth, <code>Version1000Date20261012500100</code>, records whether each video post is a\nshort (for the <code>only_short</code> timeline filter). It reads only the posts whose\nmedia kind is <code>video</code>, through an index, 2,000 to a statement, so it costs time\nin proportion to the videos an instance holds rather than to all its posts; run\nagain, it finds nothing left to do.</p>\n<p><strong>From a release before 0.23</strong> (0.10.0 and earlier) the upgrade also removes a\nfollow that is recorded twice — once pending and once accepted, which those\nreleases allowed — keeping the accepted one, and gives <code>social_stream_dest</code> and\n<code>social_stream_tag</code> a primary key, which on MySQL/MariaDB rebuilds both tables.\nThose releases run on Nextcloud up to 34, and that is the path the upgrade is\ntested on: upgrade the app on Nextcloud 34 first, then Nextcloud.</p>\n<p>Two settings exist for size and are listed above: <code>search_window_days</code> bounds\nwhat a content search scans when it cannot use its word index, and <code>retention_days</code> bounds what cached remote\nmedia costs. Both trade completeness for a bounded cost, and the default of each\nis the one a medium instance wants.</p>\n<p><code>occ social:benchmark</code> seeds a realistic amount of content and times the\ntimeline queries against it, which is the only honest way to find out what any\nof this costs on the hardware in front of you.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"running-a-large-instance","manual":false,"prev":{"path":"/docs/admin-commands-by-task","title":"Commands by task"},"next":{"path":"/docs/admin-what-to-watch","title":"What to watch"},"parent":null},{"slug":"admin-what-to-watch","path":"/docs/admin-what-to-watch","title":"What to watch","description":"Administration → Social → For You includes an independent Ranked For You recommendations switch. It is off by default. Enabling it makes the ranked timeline available; it does not…","group":"admin","html":"<ul>\n<li><strong>Administration → Overview.</strong> The setup checks above are there precisely so\nthat an administrator who never opens Aloha Social still hears about it.</li>\n<li><strong>The delivery queue.</strong> A rising count of failing deliveries against one host\nis that instance&#39;s problem; a rising count against all of them is this one&#39;s.</li>\n<li><strong><code>social.log</code> / the Nextcloud log.</strong> Signature verification failures on\ninbound requests, and <code>could not federate</code> warnings on outbound ones.</li>\n<li><strong>Disk.</strong> Cached remote attachments are the largest thing this app stores.\n<code>retention_days</code> is what bounds them; on an instance that federates widely,\nleaving it at <code>0</code> means keeping every picture anybody here ever scrolled\npast.</li>\n<li><strong>The audit log</strong>, if <code>admin_audit</code> is enabled: every moderation decision,\nwith the moderator who took it.</li>\n</ul>\n<h2 id=\"ranked-for-you-recommendations-switch\">Ranked For You recommendations switch</h2>\n<p>Administration → Social → For You includes an independent <strong>Ranked For You\nrecommendations</strong> switch. It is off by default. Enabling it makes the ranked\ntimeline available; it does not automatically opt readers into behavioral\nlearning. The feed can draw on learned signals, post content, freshness, follows\nand discovery, so it does not require readers to choose topics. Readers cannot\ncurrently add topics manually or request a topic-specific feed. That is a\nseparate product capability and should not be implied by the ranking switch.\nTurn the switch off to disable the ranked timeline. See\n<a href=\"/docs/for-you\">For-You.md</a> for the data and consent model.</p>\n","toc":[{"id":"ranked-for-you-recommendations-switch","text":"Ranked For You recommendations switch","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"what-to-watch","manual":false,"prev":{"path":"/docs/admin-running-a-large-instance","title":"Running a large instance"},"next":{"path":"/docs/admin-empty-application-after-installing-development-dependencies","title":"Empty application after installing development dependencies"},"parent":null},{"slug":"admin-empty-application-after-installing-development-dependencies","path":"/docs/admin-empty-application-after-installing-development-dependencies","title":"Empty application after installing development dependencies","description":"A running Nextcloud should use Social's production Composer autoloader. Development packages such as Psalm pull in Amp versions that may collide with the Mail app's Amp functions during…","group":"admin","html":"<p>A running Nextcloud should use Social&#39;s production Composer autoloader. Development\npackages such as Psalm pull in Amp versions that may collide with the Mail app&#39;s\nAmp functions during Nextcloud startup. A typical fatal error is\n<code>Cannot redeclare function Amp\\delay()</code>. This can affect even <code>status.php</code>.</p>\n<p>From the Social app directory, regenerate the runtime autoloader without\ndevelopment packages:</p>\n<pre><code class=\"language-sh\">composer dump-autoload --no-dev --no-scripts\n</code></pre>\n<p>For a production installation, install the production dependencies directly with\n<code>composer install --no-dev --prefer-dist --no-interaction</code>. The dump command repairs\nthe local autoloader when the packages are already installed; it does not update\nthe lock file or remove packages. Run development checks in a development checkout\nor restore the development autoloader there with <code>composer dump-autoload --dev</code>.\nDo not leave that development autoloader active in a shared running Nextcloud.</p>\n<p>Afterward verify <code>/status.php</code>, <code>occ status</code>, and the Social page in a browser.\nA successful Webpack build alone does not exercise Nextcloud bootstrap.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Admin.md","sections":null,"anchor":"empty-application-after-installing-development-dependencies","manual":false,"prev":{"path":"/docs/admin-what-to-watch","title":"What to watch"},"next":null,"parent":null},{"slug":"occ","path":"/docs/occ","title":"Aloha Social — OCC Commands Reference","description":"All commands are invoked via php occ <command> from the Nextcloud root directory.","group":"occ","html":"<p>All commands are invoked via <code>php occ &lt;command&gt;</code> from the Nextcloud root directory.</p>\n<p>This page documents the commands the app registers in\n<code>appinfo/info.xml</code>. Every command extends <code>OCA\\Social\\Command\\SocialCommand</code>,\nthe app&#39;s own base class, which extends Symfony&#39;s <code>Command</code> — nothing here\nreaches into the server&#39;s private <code>core/</code>. That base class declares the generic\n<code>--output plain|json|json_pretty</code> option, so the option exists on all of them,\nbut only <code>social:timeline</code> reads it (see below).</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":[{"path":"/docs/occ-account-management","title":"Account Management","description":"Fails with Unknown user if no such Nextcloud user exists. On success the command prints nothing.","parent":false},{"path":"/docs/occ-post-note-management","title":"Post / Note Management","description":"--to and --hashtag each accept only one value. In addition, PostService::fixRecipientAndHashtags() scans the content for @mentions and #hashtags and adds those too.","parent":false},{"path":"/docs/occ-timeline-and-stream","title":"Timeline & Stream","description":"The three bounds are taken as the decimal strings they are typed as, so a status id wider than a PHP integer is not rounded; one that is not a decimal integer fails with --<option> must be…","parent":false},{"path":"/docs/occ-queue-management","title":"Queue Management","description":"Every command the app adds to occ, grouped by the task it performs.","parent":false},{"path":"/docs/occ-social-worker","title":"social:worker","description":"Why it matters: Cron\\Queue runs every twelve minutes with a 240-second budget for deliveries (and 120 seconds of its own for the inbound queue). It delivers twenty servers at a time and…","parent":true},{"path":"/docs/occ-social-atproto-serve","title":"social:atproto:serve","description":"Why it matters: a PDS is only a PDS while something serves its event stream. The web requests append frames to social_atproto_event; this process reads them in order and hands each to…","parent":true},{"path":"/docs/occ-social-atproto-listen","title":"social:atproto:listen","description":"Read the Bluesky accounts somebody here follows from Jetstream, as they post.","parent":true},{"path":"/docs/occ-social-mastodon-stream","title":"social:mastodon:stream","description":"Serve Mastodon's authenticated user and public WebSocket and SSE streams.","parent":true},{"path":"/docs/occ-social-atproto-identities","title":"social:atproto:identities","description":"Give every local account its Bluesky identity now, rather than on first need.","parent":true},{"path":"/docs/occ-social-atproto-plc","title":"social:atproto:plc","description":"This app's log of PLC directory operations beside what the directory holds, or the resend of what never got through.","parent":true},{"path":"/docs/occ-social-atproto-resolve","title":"social:atproto:resolve","description":"What a handle or DID is: the local identity, and the DID document the directory serves.","parent":true},{"path":"/docs/occ-social-atproto-repo","title":"social:atproto:repo","description":"A user's Bluesky repository: its head commit, what it holds, and whether it checks out.","parent":true},{"path":"/docs/occ-social-atproto-block","title":"social:atproto:block","description":"The administrator's Bluesky block list: an account by its DID, or a PDS host and every account on it.","parent":true},{"path":"/docs/occ-social-atproto-crawl","title":"social:atproto:crawl","description":"Ask the configured relays to subscribe to this instance's firehose now.","parent":true},{"path":"/docs/occ-social-atproto-rotate-key","title":"social:atproto:rotate-key","description":"A new instance rotation key, and a PLC update for every identity so the new key is the one in charge.","parent":true},{"path":"/docs/occ-social-atproto-keys-reseal","title":"social:atproto:keys:reseal","description":"Every Bluesky key — the instance rotation keys, the retired ones included, the service key and each account's signing key — sealed again under the instance secret in use, for after…","parent":true},{"path":"/docs/occ-social-queue-process","title":"social:queue:process","description":"Process both queues once: the outbound request queue (federation delivery) and the stream queue (caching of not-yet-resolved incoming objects).","parent":true},{"path":"/docs/occ-social-queue-status","title":"social:queue:status","description":"Report the state of the outbound delivery queue, or dump the rows belonging to one request token.","parent":true},{"path":"/docs/occ-social-queue-retry","title":"social:queue:retry","description":"Retrying clears the attempt count and sets the row back to standby, so it gets the full run of retries again on the next queue cron (or occ social:queue:process) rather than being…","parent":true},{"path":"/docs/occ-development","title":"Development","description":"Seeds a plausible amount of content and times the queries behind the timelines, because a query's cost cannot be judged on the couple of dozen rows a development instance holds. For…","parent":false},{"path":"/docs/occ-cache","title":"Cache","description":"Every command the app adds to occ, grouped by the task it performs.","parent":false},{"path":"/docs/occ-social-cache-refresh","title":"social:cache:refresh","description":"Steps and their output lines: local accounts deleted, local accounts regenerated, remote accounts created, remote accounts updated, remote accounts details updated, documents cached…","parent":true},{"path":"/docs/occ-social-counts-refresh","title":"social:counts:refresh","description":"Ask where each remote post lives — its own server, or the AppView for a post read from Bluesky — what its counts are right now, and store what it says. Local posts of the last seven days…","parent":true},{"path":"/docs/occ-social-starter-packs-refresh","title":"social:starter-packs:refresh","description":"Read the starter packs other servers publish again — the fediverse's collections (Mastodon's Collections, FEP-7aa9 FeaturedCollections) and Bluesky's suggested starter packs — now rather…","parent":true},{"path":"/docs/occ-social-media-retry","title":"social:media:retry","description":"Retry one remote attachment which was previously rejected by the media cache. This is useful after an administrator raises a size limit or the remote origin recovers from a temporary…","parent":true},{"path":"/docs/occ-social-media-recover","title":"social:media:recover","description":"Restore missing pictures on remote posts whose saved ActivityPub original still contains attachments. It does not rewrite post text, audience or date.","parent":true},{"path":"/docs/occ-social-media-posters","title":"social:media:posters","description":"Make the poster frames of videos that have none, so a client shows a still instead of a black rectangle before anybody presses play.","parent":true},{"path":"/docs/occ-social-team","title":"social:team","description":"What it is. Pixelfed's answer to \"several people, one voice\" is its Group* family: twenty models, still in beta, and a second social graph beside the one it already has. Nextcloud's answer…","parent":true},{"path":"/docs/occ-social-media-transcode","title":"social:media:transcode","description":"Convert stored videos to H.264 in an MP4, which is the one format the rest of the network plays.","parent":true},{"path":"/docs/occ-social-media-ladder","title":"social:media:ladder","description":"Write stored videos at a ladder of smaller sizes, as HLS, so a player can pick the one that fits the connection.","parent":true},{"path":"/docs/occ-social-media-strip-metadata","title":"social:media:strip-metadata","description":"Take the container metadata — where and with what it was recorded, its title, its chapters — off the video and sound files that were uploaded before uploads lost it on the way in, or while…","parent":true},{"path":"/docs/occ-social-media-usage","title":"social:media:usage","description":"Report what the app's media occupies on disk, split into what was uploaded here and what was cached off other servers.","parent":true},{"path":"/docs/occ-federation","title":"Federation","description":"import accepts a first-column #domain/domain header or a plain one-domain-per-line file. It validates the entire file before mutation, skips duplicates, caps an import at 10,000 unique…","parent":false},{"path":"/docs/occ-external-users","title":"External Users","description":"Self-registered external users: list them, add one without the registration form, or promote one to an ordinary local user.","parent":false},{"path":"/docs/occ-installation-and-maintenance","title":"Installation & Maintenance","description":"Check the integrity of the installation, or regenerate the stream index.","parent":false},{"path":"/docs/occ-exit-codes","title":"Exit Codes","description":"Every command the app adds to occ, grouped by the task it performs.","parent":false},{"path":"/docs/occ-background-jobs","title":"Background Jobs","description":"Every 12 minutes, with a 300-second budget. Same steps as social:cache:refresh (deleted actors, local actor cache, remote actors and their details, documents, hashtags), and additionally…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/occ-account-management","title":"Account Management"},"parent":null},{"slug":"occ-account-management","path":"/docs/occ-account-management","title":"Account Management","description":"Fails with Unknown user if no such Nextcloud user exists. On success the command prints nothing.","group":"occ","html":"<h2 id=\"social-account-create\"><code>social:account:create</code></h2>\n<p>Create the Aloha Social actor for an existing Nextcloud user.</p>\n<pre><code>php occ social:account:create [--handle HANDLE] &lt;userId&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>userId</code></td>\n<td>Yes</td>\n<td>Nextcloud username of the account</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--handle</code></td>\n<td>required</td>\n<td>Aloha Social handle. If omitted, the <code>userId</code> is used as the handle.</td>\n</tr>\n</tbody></table></div>\n<p>Fails with <code>Unknown user</code> if no such Nextcloud user exists. On success the command\nprints nothing.</p>\n<hr>\n<h2 id=\"social-account-delete\"><code>social:account:delete</code></h2>\n<p>Delete a local Aloha Social account.</p>\n<pre><code>php occ social:account:delete &lt;account&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>account</code></td>\n<td>Yes</td>\n<td>Local Aloha Social account (the handle / preferred username)</td>\n</tr>\n</tbody></table></div>\n<p>Prints nothing on success.</p>\n<hr>\n<h2 id=\"social-account-following\"><code>social:account:following</code></h2>\n<p>Follow or unfollow an account on behalf of a local user.</p>\n<pre><code>php occ social:account:following [--local] [--unfollow] &lt;userId&gt; &lt;account&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>userId</code></td>\n<td>Yes</td>\n<td>Nextcloud user performing the action</td>\n</tr>\n<tr>\n<td><code>account</code></td>\n<td>Yes</td>\n<td>Account to follow (e.g. <code>user@example.org</code>)</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--local</code></td>\n<td>none</td>\n<td>Resolve <code>account</code> as a <strong>local</strong> account first, and use its canonical account name</td>\n</tr>\n<tr>\n<td><code>--unfollow</code></td>\n<td>none</td>\n<td>Send an <code>Undo</code>/unfollow instead of a follow</td>\n</tr>\n</tbody></table></div>\n<p>Prints progress lines (<code>Following account...</code>, the resolved local actor id and nid,\nthen the result). This is the only command that returns exit code <code>1</code> on a handled\nfailure; the rest let the exception surface.</p>\n<hr>\n<h2 id=\"social-account-alias\"><code>social:account:alias</code></h2>\n<p>Since 0.20.6 an account&#39;s own aliases are also settable by its owner, in <strong>Migration → Accounts you also answer to</strong> (<code>/api/v1/migration/aliases</code>) — setting one federates nothing. This command stays for an administrator acting on somebody else&#39;s account, and for scripting a migration.</p>\n<p>Manage the <code>alsoKnownAs</code> list of a local account: the actor ids it also answers\nto. Setting one is the first step of moving an account <strong>to</strong> this server — a\nMastodon (or other) server refuses to start a Move towards an account that does\nnot list the moving one here.</p>\n<pre><code>php occ social:account:alias [--add URL] [--remove URL] [--list] &lt;userId&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>userId</code></td>\n<td>Yes</td>\n<td>Nextcloud user whose actor is aliased</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--add</code></td>\n<td>required</td>\n<td>The old account, as its <code>alice@mastodon.example</code> handle (resolved through WebFinger) or its <code>https://mastodon.example/users/alice</code> actor id; the id is what is stored. Adding one that is already listed changes nothing.</td>\n</tr>\n<tr>\n<td><code>--remove</code></td>\n<td>required</td>\n<td>Actor id to remove. Removing one that is not listed changes nothing.</td>\n</tr>\n<tr>\n<td><code>--list</code></td>\n<td>none</td>\n<td>Print the current list. This is also what happens with no option at all.</td>\n</tr>\n</tbody></table></div>\n<p><code>--add</code> and <code>--remove</code> cannot be combined in one run. Every change refreshes the\nactor cache, so the new list is on the actor document at once; the remote server\nreads it when the Move is started there.</p>\n<p>Prints <code>added &lt;url&gt;</code> / <code>removed &lt;url&gt;</code> followed by the list, or <code>no alias set.</code>.\nExit code <code>1</code> when <code>userId</code> has no actor or the value is not an <code>http(s)://</code> URL.</p>\n<hr>\n<h2 id=\"social-account-move\"><code>social:account:move</code></h2>\n<p>Move a local account to one on another server, the way Mastodon&#39;s account\nmigration works: the new account has to list this one in its <code>alsoKnownAs</code>, every\nfollower is sent a <code>Move</code>, and the account here is marked as moved.</p>\n<p>Since 0.26.113 a person can do this themselves, in <strong>Migration → Move\nyour account away</strong> (<code>POST /api/v1/migration/move</code>), behind their password, their\nown handle typed back and a thirty-day cooldown between moves. This command stays\nfor an administrator acting on somebody else&#39;s account, and it <strong>skips the\ncooldown</strong>. Undoing a move (clearing <code>movedTo</code>) is on the same page.</p>\n<pre><code>php occ social:account:move [-f|--force] [--bluesky=deactivate|keep|move] &lt;userId&gt; &lt;target&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>userId</code></td>\n<td>Yes</td>\n<td>Nextcloud user whose actor moves away</td>\n</tr>\n<tr>\n<td><code>target</code></td>\n<td>Yes</td>\n<td>The new account, as <code>@you@new.example</code> or its <code>https://…</code> actor id</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-f</code>, <code>--force</code></td>\n<td>none</td>\n<td>Do not ask for confirmation (required with <code>--no-interaction</code>)</td>\n</tr>\n<tr>\n<td><code>--bluesky</code></td>\n<td><code>deactivate</code> (default), <code>keep</code>, <code>move</code></td>\n<td>What becomes of the account&#39;s Bluesky identity: switched off, kept as it is, or moving on its own — <code>move</code> only once its Bluesky move away is done or under way</td>\n</tr>\n</tbody></table></div>\n<p>What happens, in order:</p>\n<ol>\n<li>The target is fetched fresh from its server (not read from the cache) and\nmust list this account&#39;s actor id in <code>alsoKnownAs</code> — the same check\n<code>MoveInterface</code> applies to an incoming Move. Without it the command stops\nwith exit code <code>1</code> and nothing changes; add the alias on the new account\nfirst (in Mastodon: <em>Preferences → Account → Moving from a different\naccount</em>).</li>\n<li>A <code>Move{actor, object: this actor, target}</code> is signed and queued through the\nordinary delivery queue to every follower&#39;s inbox and to the new account&#39;s\ninbox. Servers that support migration re-follow the target for their users\nand drop the follow of the old account.</li>\n<li><code>movedTo</code> is recorded on the actor: it appears on the actor document and as\n<code>moved</code> on the account entity, so clients show the &quot;has moved&quot; banner.</li>\n<li>Followers <strong>on this server</strong> never receive the Move (deliveries to ourselves\nare dropped), so the command follows the new account on their behalf through\nthe ordinary follow path. One follower that cannot be re-followed is logged\nand does not stop the others.</li>\n</ol>\n<p>The command asks for confirmation first; under <code>--no-interaction</code> it refuses\nunless <code>--force</code> is given, rather than moving an account because nobody was\nthere to say no. Posts stay where they are — like Mastodon, a move carries the\nfollowers, not the content.</p>\n<hr>\n<h2 id=\"social-account-import-posts\"><code>social:account:import-posts</code></h2>\n<p>Bring an account&#39;s own posts over from the server it wrote them on, with their\npictures: the same importer the Migration page uses, for the archives a browser\ncannot upload.</p>\n<pre><code>php occ social:account:import-posts [--no-media] [--limit LIMIT] &lt;userId&gt; &lt;archive&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>userId</code></td>\n<td>Yes</td>\n<td>Nextcloud user whose account the posts are written as</td>\n</tr>\n<tr>\n<td><code>archive</code></td>\n<td>Yes</td>\n<td>Path to the export: a zip with an <code>outbox.json</code> (this app&#39;s, under <code>social/</code>; Mastodon&#39;s and GoToSocial&#39;s, at the root), an <strong>Instagram</strong> archive (the JSON one — <code>content/posts_*.json</code> and the reels beside them, with the pictures under <code>media/</code>), or a JSON export on its own — an <code>outbox.json</code>, or Pixelfed&#39;s <code>pixelfed-statuses.json</code></td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--no-media</code></td>\n<td>none</td>\n<td>Do not fetch the pictures an export names only by their address. The ones inside the archive are still restored</td>\n</tr>\n<tr>\n<td><code>--limit</code></td>\n<td>number</td>\n<td>How many posts to write at most (default and ceiling 2000). The command says when it stopped there; run it again to carry on</td>\n</tr>\n</tbody></table></div>\n<p>Each post is written as a <strong>new local post</strong> of that account, dated when it was\nwritten. <strong>Nothing is federated</strong> — not one delivery is queued — because\nre-publishing somebody&#39;s years of posts would put them into the timeline of\nevery person who follows them, on every server, at once. The original id is\nremembered in <code>social_import_post</code>, so running the command twice over the same\narchive writes nothing the second time, and a reply keeps its parent where the\narchive holds both. Deleting an imported post forgets it as well, so a later\nrun of the same archive brings that post over again.</p>\n<p>What is left alone: boosts (somebody else&#39;s post), direct messages (addressed\nto accounts on the old server, so a copy here would be addressed to nobody),\nand items with neither words nor pictures. Every file goes through the same\nupload path a post&#39;s own attachment does, so an imported picture is stripped of\nits metadata and held to the sizes and types this instance accepts.</p>\n<p>A picture named only by an address is fetched from the server it is still on,\nwhich means that server learns the import is happening and that it has to be\nrunning. <code>--no-media</code> is the way to import the words without either.</p>\n<h2 id=\"social-account-import-follows\"><code>social:account:import-follows</code></h2>\n<p>Follow every account of a follows export — Mastodon&#39;s <code>following_accounts.csv</code>\nor Pixelfed&#39;s <code>pixelfed-following.json</code> — from a local account: the other half\nof moving an account <strong>to</strong> this server.</p>\n<pre><code>php occ social:account:import-follows &lt;userId&gt; &lt;csv&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>userId</code></td>\n<td>Yes</td>\n<td>Nextcloud user whose actor follows the accounts</td>\n</tr>\n<tr>\n<td><code>csv</code></td>\n<td>Yes</td>\n<td>Path to the export. The current Mastodon format with the header <code>Account address,Show boosts,Notify on new posts,Languages</code> is read by its <code>Account address</code> column wherever it is; the older format — one handle per line, no header — works too. A file that parses as JSON is read as Pixelfed&#39;s export: an array of actor URLs (or handles, or objects naming one), each URL fetched and followed as the actor it resolves to.</td>\n</tr>\n</tbody></table></div>\n<p>Each entry goes through the same path as <code>social:account:following</code>: the\naccount is resolved (WebFinger for a handle, an actor fetch for a URL), a\n<code>Follow</code> is queued, and an account already followed is left alone. A leading\n<code>@</code> is dropped, repeats are followed once, and an entry that is neither a\n<code>user@host</code> handle nor an actor URL is ignored. The other columns (boosts,\nnotifications, languages) are not imported.</p>\n<p>One handle that fails — an unreachable instance, an account that no longer\nexists — is reported and does not stop the rest. The command prints how many\nwere followed, how many were skipped (the importing account&#39;s own handle) and\nhow many failed, each with its reason. Exit code <code>1</code> when the file cannot be\nread, or when something was asked for and none of it could be followed.</p>\n<hr>\n","toc":[{"id":"social-account-create","text":"social:account:create","level":2},{"id":"social-account-delete","text":"social:account:delete","level":2},{"id":"social-account-following","text":"social:account:following","level":2},{"id":"social-account-alias","text":"social:account:alias","level":2},{"id":"social-account-move","text":"social:account:move","level":2},{"id":"social-account-import-posts","text":"social:account:import-posts","level":2},{"id":"social-account-import-follows","text":"social:account:import-follows","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"account-management","manual":false,"prev":{"path":"/docs/occ","title":"Aloha Social — OCC Commands Reference"},"next":{"path":"/docs/occ-post-note-management","title":"Post / Note Management"},"parent":null},{"slug":"occ-post-note-management","path":"/docs/occ-post-note-management","title":"Post / Note Management","description":"--to and --hashtag each accept only one value. In addition, PostService::fixRecipientAndHashtags() scans the content for @mentions and #hashtags and adds those too.","group":"occ","html":"<h2 id=\"social-note-create\"><code>social:note:create</code></h2>\n<p>Create a note (post) as a given user and federate it.</p>\n<pre><code>php occ social:note:create [-r|--replyTo REPLYTO] [-t|--to TO] [-y|--type TYPE] [-g|--hashtag HASHTAG] &lt;user_id&gt; &lt;content&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>user_id</code></td>\n<td>Yes</td>\n<td>Nextcloud user ID of the author</td>\n</tr>\n<tr>\n<td><code>content</code></td>\n<td>Yes</td>\n<td>Content of the post</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-r</code>, <code>--replyTo</code></td>\n<td>optional</td>\n<td>Id of the post this one replies to</td>\n</tr>\n<tr>\n<td><code>-t</code>, <code>--to</code></td>\n<td>optional</td>\n<td>A single mentioned account</td>\n</tr>\n<tr>\n<td><code>-y</code>, <code>--type</code></td>\n<td>optional</td>\n<td>Visibility: <code>public</code>, <code>unlisted</code>, <code>followers</code> (Mastodon&#39;s <code>private</code> is accepted as a synonym) or <code>direct</code>. Anything else — including omitting the option — becomes <strong><code>direct</code></strong>, the most restrictive option, because <code>Post::setType()</code> maps a value it does not know through <code>Stream::visibilityFromClient()</code>. Note the option&#39;s own <code>--help</code> text still says &quot;public (default)&quot;, which is not what happens.</td>\n</tr>\n<tr>\n<td><code>-g</code>, <code>--hashtag</code></td>\n<td>optional</td>\n<td>A single hashtag, without the leading <code>#</code></td>\n</tr>\n</tbody></table></div>\n<p><code>--to</code> and <code>--hashtag</code> each accept only one value. In addition,\n<code>PostService::fixRecipientAndHashtags()</code> scans the\ncontent for <code>@mentions</code> and <code>#hashtags</code> and adds those too.</p>\n<p>Prints the resulting activity as pretty JSON followed by <code>token: &lt;request token&gt;</code>\n(written with <code>echo</code>, so <code>--output json</code> does not change it).</p>\n<hr>\n<h2 id=\"social-note-boost\"><code>social:note:boost</code></h2>\n<p>Boost (<code>Announce</code>) a note, or undo a boost.</p>\n<pre><code>php occ social:note:boost [--unboost] &lt;user_id&gt; &lt;note_id&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>user_id</code></td>\n<td>Yes</td>\n<td>Nextcloud user ID boosting the note</td>\n</tr>\n<tr>\n<td><code>note_id</code></td>\n<td>Yes</td>\n<td>Id of the note</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--unboost</code></td>\n<td>none</td>\n<td>Undo the boost instead of creating one</td>\n</tr>\n</tbody></table></div>\n<p>Prints the activity as pretty JSON plus <code>token: &lt;request token&gt;</code>.</p>\n<hr>\n<h2 id=\"social-note-like\"><code>social:note:like</code></h2>\n<p>Like a note, or undo a like.</p>\n<pre><code>php occ social:note:like [--unlike] &lt;user_id&gt; &lt;note_id&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>user_id</code></td>\n<td>Yes</td>\n<td>Nextcloud user ID liking the note</td>\n</tr>\n<tr>\n<td><code>note_id</code></td>\n<td>Yes</td>\n<td>Id of the note</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--unlike</code></td>\n<td>none</td>\n<td>Undo the like instead of creating one</td>\n</tr>\n</tbody></table></div>\n<p>Prints the activity as pretty JSON plus <code>token: &lt;request token&gt;</code>.</p>\n<hr>\n","toc":[{"id":"social-note-create","text":"social:note:create","level":2},{"id":"social-note-boost","text":"social:note:boost","level":2},{"id":"social-note-like","text":"social:note:like","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"post-note-management","manual":false,"prev":{"path":"/docs/occ-account-management","title":"Account Management"},"next":{"path":"/docs/occ-timeline-and-stream","title":"Timeline & Stream"},"parent":null},{"slug":"occ-timeline-and-stream","path":"/docs/occ-timeline-and-stream","title":"Timeline & Stream","description":"The three bounds are taken as the decimal strings they are typed as, so a status id wider than a PHP integer is not rounded; one that is not a decimal integer fails with --<option> must be…","group":"occ","html":"<h2 id=\"social-timeline\"><code>social:timeline</code></h2>\n<p>Print a timeline as seen by a given local viewer.</p>\n<pre><code>php occ social:timeline [--local] [--min_id MIN] [--max_id MAX] [--since SINCE] [--limit N] [--account ACCOUNT] [--crop N] &lt;userId&gt; &lt;timeline&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>userId</code></td>\n<td>Yes</td>\n<td>Nextcloud user whose view is used. Fails with <code>Unknown user</code> if unknown.</td>\n</tr>\n<tr>\n<td><code>timeline</code></td>\n<td>Yes</td>\n<td>See the table of supported values below</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--local</code></td>\n<td>none</td>\n<td>off</td>\n<td>Restrict to local content</td>\n</tr>\n<tr>\n<td><code>--min_id</code></td>\n<td>required</td>\n<td><code>0</code></td>\n<td>Pagination bound: a status id (<code>nid</code>); rows newer than it</td>\n</tr>\n<tr>\n<td><code>--max_id</code></td>\n<td>required</td>\n<td><code>0</code></td>\n<td>Pagination bound: a status id (<code>nid</code>); rows older than it</td>\n</tr>\n<tr>\n<td><code>--since</code></td>\n<td>required</td>\n<td><code>0</code></td>\n<td>Pagination bound: a status id (<code>nid</code>); rows newer than it</td>\n</tr>\n<tr>\n<td><code>--limit</code></td>\n<td>required</td>\n<td><code>5</code></td>\n<td>Number of items</td>\n</tr>\n<tr>\n<td><code>--account</code></td>\n<td>required</td>\n<td><code>&#39;&#39;</code></td>\n<td>A <strong>local</strong> account, resolved with <code>CacheActorService::getFromLocalAccount()</code>; used as the account filter</td>\n</tr>\n<tr>\n<td><code>--crop</code></td>\n<td>required</td>\n<td><code>0</code></td>\n<td>Truncate the printed content to N characters (<code>0</code> = no cropping)</td>\n</tr>\n</tbody></table></div>\n<p>The three bounds are taken as the decimal strings they are typed as, so a status id wider than a PHP integer is not rounded; one that is not a decimal integer fails with <code>--&lt;option&gt; must be a status id</code>.</p>\n<p>Supported <code>timeline</code> values (the <code>switch</code> in <code>StreamRequest::getTimeline()</code>):</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Value</th>\n<th>Meaning</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>home</code></td>\n<td>Own posts plus posts of followed accounts</td>\n</tr>\n<tr>\n<td><code>public</code></td>\n<td>Public timeline</td>\n</tr>\n<tr>\n<td><code>direct</code></td>\n<td>Direct messages</td>\n</tr>\n<tr>\n<td><code>account</code></td>\n<td>Posts of one account (combine with <code>--account</code>)</td>\n</tr>\n<tr>\n<td><code>favourites</code></td>\n<td>Liked posts</td>\n</tr>\n<tr>\n<td><code>bookmarks</code></td>\n<td>Posts the viewer bookmarked</td>\n</tr>\n<tr>\n<td><code>notifications</code></td>\n<td>Notifications (rendered in the notification format)</td>\n</tr>\n<tr>\n<td><code>#&lt;tag&gt;</code></td>\n<td>A leading <code>#</code> selects the hashtag timeline for <code>&lt;tag&gt;</code></td>\n</tr>\n</tbody></table></div>\n<p>Matching is case-insensitive. <code>ProbeOptions</code> also defines <code>followers</code> and\n<code>following</code>, but <code>getTimeline()</code> has no case for them and silently returns an\nempty list. Any other value behaves the same way.</p>\n<p>Output is a table (<code>Nid</code>, <code>Id</code>, <code>Source</code>, <code>Type</code>, <code>Author</code>, <code>Content</code>).\n<code>--output json</code> switches this command to a JSON dump of the streams.</p>\n<hr>\n<h2 id=\"social-details\"><code>social:details</code></h2>\n<p>Print who can see one stream item and which timelines it lands on.</p>\n<pre><code>php occ social:details [--json] &lt;streamId&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>streamId</code></td>\n<td>Yes</td>\n<td>Id of the stream item. Fails with <code>Unknown item</code> if it does not exist.</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--json</code></td>\n<td>none</td>\n<td>Dump the details object as pretty JSON</td>\n</tr>\n</tbody></table></div>\n<p>Without <code>--json</code> it prints the item id, author and type, then <code>Affected Timelines</code>\nwith the <code>Home</code> viewers, the <code>Direct</code> viewers, and the <code>Public</code> / <code>Federated</code> flags.\nThis command uses its own <code>--json</code> flag; the inherited <code>--output</code> option is ignored.</p>\n<p>Note the command name is <code>social:details</code>, not <code>social:stream:details</code>, even though\nthe class is <code>OCA\\Social\\Command\\StreamDetails</code>.</p>\n<hr>\n<h2 id=\"social-stream-prune\"><code>social:stream:prune</code></h2>\n<p>Deletes remote statuses older than the retention period, together with their\nrecipient/action/tag rows and cached attachments.</p>\n<pre><code class=\"language-bash\">php occ social:stream:prune [-d|--days DAYS] [--dry-run]\n</code></pre>\n<ul>\n<li>Without <code>--days</code>, the <code>retention_days</code> app setting decides the period; <code>0</code>\n(the default) disables status retention and no status is touched.</li>\n<li>Two sweeps run on every call whatever <code>retention_days</code> says: the queue rows\nnothing will act on again (exhausted deliveries, finished cache items) are\npurged, and in-app notification rows older than <code>notification_retention_days</code>\n(default 90; <code>0</code> keeps them) are deleted. The notification count is printed\non its own line.</li>\n<li><code>--dry-run</code> only counts what would be deleted, including the notifications.</li>\n<li>A status is kept when a local user liked, boosted, replied to or bookmarked\nit, when a local user follows its author, when a local status replies to it\nor boosts it, or when it is a direct message. Local content is never touched.</li>\n<li>The same pruning runs from the <code>Cron\\Cache</code> background job (bounded to 5000\nstatuses per run) whenever <code>retention_days</code> is greater than 0; the admin can\nchange the period in the Aloha Social section of the administration settings.</li>\n</ul>\n<hr>\n","toc":[{"id":"social-timeline","text":"social:timeline","level":2},{"id":"social-details","text":"social:details","level":2},{"id":"social-stream-prune","text":"social:stream:prune","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"timeline-and-stream","manual":false,"prev":{"path":"/docs/occ-post-note-management","title":"Post / Note Management"},"next":{"path":"/docs/occ-queue-management","title":"Queue Management"},"parent":null},{"slug":"occ-queue-management","path":"/docs/occ-queue-management","title":"Queue Management","description":"Every command the app adds to occ, grouped by the task it performs.","group":"occ","html":"","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":[{"path":"/docs/occ-social-worker","title":"social:worker","description":"Why it matters: Cron\\Queue runs every twelve minutes with a 240-second budget for deliveries (and 120 seconds of its own for the inbound queue). It delivers twenty servers at a time and…","parent":true},{"path":"/docs/occ-social-atproto-serve","title":"social:atproto:serve","description":"Why it matters: a PDS is only a PDS while something serves its event stream. The web requests append frames to social_atproto_event; this process reads them in order and hands each to…","parent":true},{"path":"/docs/occ-social-atproto-listen","title":"social:atproto:listen","description":"Read the Bluesky accounts somebody here follows from Jetstream, as they post.","parent":true},{"path":"/docs/occ-social-mastodon-stream","title":"social:mastodon:stream","description":"Serve Mastodon's authenticated user and public WebSocket and SSE streams.","parent":true},{"path":"/docs/occ-social-atproto-identities","title":"social:atproto:identities","description":"Give every local account its Bluesky identity now, rather than on first need.","parent":true},{"path":"/docs/occ-social-atproto-plc","title":"social:atproto:plc","description":"This app's log of PLC directory operations beside what the directory holds, or the resend of what never got through.","parent":true},{"path":"/docs/occ-social-atproto-resolve","title":"social:atproto:resolve","description":"What a handle or DID is: the local identity, and the DID document the directory serves.","parent":true},{"path":"/docs/occ-social-atproto-repo","title":"social:atproto:repo","description":"A user's Bluesky repository: its head commit, what it holds, and whether it checks out.","parent":true},{"path":"/docs/occ-social-atproto-block","title":"social:atproto:block","description":"The administrator's Bluesky block list: an account by its DID, or a PDS host and every account on it.","parent":true},{"path":"/docs/occ-social-atproto-crawl","title":"social:atproto:crawl","description":"Ask the configured relays to subscribe to this instance's firehose now.","parent":true},{"path":"/docs/occ-social-atproto-rotate-key","title":"social:atproto:rotate-key","description":"A new instance rotation key, and a PLC update for every identity so the new key is the one in charge.","parent":true},{"path":"/docs/occ-social-atproto-keys-reseal","title":"social:atproto:keys:reseal","description":"Every Bluesky key — the instance rotation keys, the retired ones included, the service key and each account's signing key — sealed again under the instance secret in use, for after…","parent":true},{"path":"/docs/occ-social-queue-process","title":"social:queue:process","description":"Process both queues once: the outbound request queue (federation delivery) and the stream queue (caching of not-yet-resolved incoming objects).","parent":true},{"path":"/docs/occ-social-queue-status","title":"social:queue:status","description":"Report the state of the outbound delivery queue, or dump the rows belonging to one request token.","parent":true},{"path":"/docs/occ-social-queue-retry","title":"social:queue:retry","description":"Retrying clears the attempt count and sets the row back to standby, so it gets the full run of retries again on the next queue cron (or occ social:queue:process) rather than being…","parent":true}],"anchor":"queue-management","manual":false,"prev":{"path":"/docs/occ-timeline-and-stream","title":"Timeline & Stream"},"next":{"path":"/docs/occ-social-worker","title":"social:worker"},"parent":null},{"slug":"occ-social-worker","path":"/docs/occ-social-worker","title":"social:worker","description":"Why it matters: Cron\\Queue runs every twelve minutes with a 240-second budget for deliveries (and 120 seconds of its own for the inbound queue). It delivers twenty servers at a time and…","group":"occ","html":"<p>Drain the queues continuously, instead of once every twelve minutes.</p>\n<pre><code>php occ social:worker [--once] [--max-seconds SECONDS] [--quiet-log]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--once</code></td>\n<td>none</td>\n<td>Drain what is queued now and return, instead of waiting for more — what a cron entry wants</td>\n</tr>\n<tr>\n<td><code>--max-seconds</code></td>\n<td>int (0)</td>\n<td>Stop after this long, so a supervisor can restart it; <code>0</code> runs until stopped</td>\n</tr>\n<tr>\n<td><code>--quiet-log</code></td>\n<td>none</td>\n<td>Do not print a line per batch</td>\n</tr>\n</tbody></table></div>\n<p><strong>Why it matters:</strong> <code>Cron\\Queue</code> runs every twelve minutes with a 240-second\nbudget for deliveries (and 120 seconds of its own for the inbound queue). It\ndelivers twenty servers at a time and takes batch after batch of 200 while time\nis left — up to 6,000 deliveries a run when peers answer within a second, and\nabout 160 when every batch runs into a dead peer&#39;s 30-second timeout — and Nextcloud runs one <code>cron.php</code> at a time, so that is its ceiling.\nAn instance whose accounts are followed across tens of thousands of servers\nreaches it with one popular post.</p>\n<p>This is the same delivery in a loop that does not stop, one row at a time. A healthy peer answers in\na fraction of a second, so one worker moves thousands of rows an hour rather than\na thousand a day — and because claiming a row is already atomic (an\n<code>UPDATE … WHERE status = standby</code> that throws when it loses the race),\n<strong>several workers may run at once</strong> and will not collide. Run as many as the\ninstance needs, under systemd:</p>\n<pre><code class=\"language-ini\">[Unit]\nDescription=Aloha Social delivery worker %i\nAfter=network.target\n\n[Service]\nUser=www-data\nExecStart=/usr/bin/php /var/www/html/occ social:worker --max-seconds=3600 --quiet-log\nRestart=always\nRestartSec=5\n\n[Install]\nWantedBy=multi-user.target\n</code></pre>\n<p><code>systemctl enable --now social-worker@{1..4}</code> for four of them. It finishes the\nrow in hand on <code>SIGTERM</code> rather than abandoning a delivery the receiving server\nmay already have taken, sleeps (with a growing wait) when there is nothing to do,\nand hands rows back to standby when an attempt fails outside the delivery\nservice&#39;s own error handling — without that a killed worker leaves a row\n<code>running</code>, which nothing retries until the stale reaper an hour later.</p>\n<p><strong>The cron job is unchanged.</strong> An instance that will not run a daemon keeps\nexactly the behaviour it has; one that will gets the throughput.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-worker","manual":false,"prev":{"path":"/docs/occ-queue-management","title":"Queue Management"},"next":{"path":"/docs/occ-social-atproto-serve","title":"social:atproto:serve"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-serve","path":"/docs/occ-social-atproto-serve","title":"social:atproto:serve","description":"Why it matters: a PDS is only a PDS while something serves its event stream. The web requests append frames to social_atproto_event; this process reads them in order and hands each to…","group":"occ","html":"<p>Serve the Bluesky firehose: the WebSocket a relay subscribes to.</p>\n<pre><code>php occ social:atproto:serve [--bind ADDRESS:PORT] [--max-seconds SECONDS] [--once]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--bind</code></td>\n<td>string (127.0.0.1:8787)</td>\n<td>Where to listen; the web server proxies <code>/xrpc/com.atproto.sync.subscribeRepos</code> here with the WebSocket upgrade</td>\n</tr>\n<tr>\n<td><code>--max-seconds</code></td>\n<td>int (0)</td>\n<td>Stop after this long, so a supervisor can restart it; <code>0</code> runs until stopped</td>\n</tr>\n<tr>\n<td><code>--once</code></td>\n<td>none</td>\n<td>Serve what is queued now to whoever is connected and return — what a test wants</td>\n</tr>\n</tbody></table></div>\n<p><strong>Why it matters:</strong> a PDS is only a PDS while something serves its event stream. The\nweb requests append frames to <code>social_atproto_event</code>; this process reads them in\norder and hands each to every connected relay, replaying from the cursor a relay\nreconnects with out of the 72-hour window the table keeps. Run it under systemd\n(see <a href=\"/docs/admin-bluesky#bluesky\">Admin.md</a>); the setup checks say when it is not running.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-serve","manual":false,"prev":{"path":"/docs/occ-social-worker","title":"social:worker"},"next":{"path":"/docs/occ-social-atproto-listen","title":"social:atproto:listen"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-listen","path":"/docs/occ-social-atproto-listen","title":"social:atproto:listen","description":"Read the Bluesky accounts somebody here follows from Jetstream, as they post.","group":"occ","html":"<p>Read the Bluesky accounts somebody here follows from Jetstream, as they post.</p>\n<pre><code>php occ social:atproto:listen [--max-seconds SECONDS] [--once]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--max-seconds</code></td>\n<td>int (0)</td>\n<td>Stop after this long, so a supervisor can restart it; <code>0</code> runs until stopped</td>\n</tr>\n<tr>\n<td><code>--once</code></td>\n<td>none</td>\n<td>Read what is there now and return</td>\n</tr>\n</tbody></table></div>\n<p><strong>Why it matters:</strong> without it, a followed Bluesky account&#39;s new post arrives\nwhen the poller next reads that account&#39;s feed — two minutes at best, hours for\nan account that posts rarely. With it, the post is here within seconds. It holds\none WebSocket to the Jetstream set on the admin page (<code>atproto_jetstream</code>),\nnaming the followed accounts (at most 10,000) and nothing else — a listener\nwith nobody to listen for does not connect at all, since an empty list would be\nthe whole network. A post or a repost makes it read that account&#39;s feed the way\nthe poller does; a deleted post is deleted here at once; a changed profile or\nhandle is read again. Where it got to is kept, and a restart picks up from a few\nseconds before. The poller keeps running beside it, so the listener being down\ncosts latency and nothing else. Run it under systemd beside the firehose daemon\n(see <a href=\"/docs/admin-bluesky#bluesky\">Admin.md</a>).</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-listen","manual":false,"prev":{"path":"/docs/occ-social-atproto-serve","title":"social:atproto:serve"},"next":{"path":"/docs/occ-social-mastodon-stream","title":"social:mastodon:stream"},"parent":"occ-queue-management"},{"slug":"occ-social-mastodon-stream","path":"/docs/occ-social-mastodon-stream","title":"social:mastodon:stream","description":"Serve Mastodon's authenticated user and public WebSocket and SSE streams.","group":"occ","html":"<p>Serve Mastodon&#39;s authenticated user and public WebSocket and SSE streams.</p>\n<pre><code>php occ social:mastodon:stream [--bind ADDRESS:PORT] [--max-seconds SECONDS]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--bind</code></td>\n<td>string (127.0.0.1:8788)</td>\n<td>Where to listen; the shipped root proxy rules send <code>/api/v1/streaming</code>, <code>/api/v1/streaming/user</code>, <code>/api/v1/streaming/user/notification</code>, <code>/api/v1/streaming/direct</code>, <code>/api/v1/streaming/list</code>, <code>/api/v1/streaming/public</code>, <code>/api/v1/streaming/public/local</code>, <code>/api/v1/streaming/public/remote</code>, <code>/api/v1/streaming/hashtag</code>, <code>/api/v1/streaming/hashtag/local</code> and <code>/api/v1/streaming/health</code> here</td>\n</tr>\n<tr>\n<td><code>--max-seconds</code></td>\n<td>int (0)</td>\n<td>Stop after this long, so a supervisor can restart it; <code>0</code> runs until stopped</td>\n</tr>\n</tbody></table></div>\n<p>The daemon requires a user access token with <code>read</code> or both <code>read:statuses</code> and\n<code>read:notifications</code> for user streams. Direct and list streams require\n<code>read:statuses</code>; a list stream also requires a list owned by that account. It\npolls the same filtered timelines used by the REST API once per second. Run it under a process supervisor; the\nstreaming health path returns <code>OK</code> while the process is accepting requests.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-mastodon-stream","manual":false,"prev":{"path":"/docs/occ-social-atproto-listen","title":"social:atproto:listen"},"next":{"path":"/docs/occ-social-atproto-identities","title":"social:atproto:identities"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-identities","path":"/docs/occ-social-atproto-identities","title":"social:atproto:identities","description":"Give every local account its Bluesky identity now, rather than on first need.","group":"occ","html":"<p>Give every local account its Bluesky identity now, rather than on first need.</p>\n<pre><code>php occ social:atproto:identities [--user USER] [--list]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--user</code></td>\n<td>string</td>\n<td>Only this Nextcloud user</td>\n</tr>\n<tr>\n<td><code>--list</code></td>\n<td>none</td>\n<td>List the identities there are instead of making any</td>\n</tr>\n</tbody></table></div>\n<p>An identity is a <code>did:plc</code> registered with the PLC directory, a handle\n<code>alice.&lt;host&gt;</code> and a signing key, and the profile record is written with it. An\naccount that already has one is left alone, so the command is safe to run\nagain — one its owner switched off stays off, marked <code>(deactivated)</code>, and\n<code>--list</code> shows every identity&#39;s state; a registration the directory refused is logged and resent by the\nmaintenance job and by <code>social:atproto:plc --repair</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-identities","manual":false,"prev":{"path":"/docs/occ-social-mastodon-stream","title":"social:mastodon:stream"},"next":{"path":"/docs/occ-social-atproto-plc","title":"social:atproto:plc"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-plc","path":"/docs/occ-social-atproto-plc","title":"social:atproto:plc","description":"This app's log of PLC directory operations beside what the directory holds, or the resend of what never got through.","group":"occ","html":"<p>This app&#39;s log of PLC directory operations beside what the directory holds, or\nthe resend of what never got through.</p>\n<pre><code>php occ social:atproto:plc [DID] [--repair]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>did</code></td>\n<td>No</td>\n<td>The DID or handle to show; none with <code>--repair</code></td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--repair</code></td>\n<td>none</td>\n<td>Send every operation the directory never confirmed again</td>\n</tr>\n</tbody></table></div>\n<p>Each row of the log says when the operation was sent and confirmed, or when it\nwas given up on (<code>dead</code>) and what the directory said (<code>reason</code>). <code>--repair</code> is\nwhat the maintenance job does every five minutes: for each DID with a pending\noperation it compares the log with the directory&#39;s audit log — an operation\nthe directory holds is confirmed, one it nullified is dead, one it holds that\nthis log does not is taken into the log — then sends the pending operations in\norder, each built on the directory&#39;s latest confirmed operation and signed\nagain when that moved. One the directory refuses is dead and never sent again;\nthe next one follows the confirmed operation instead. One the directory could\nnot be asked about (unreachable, a 5xx, a 429) waits, with everything behind it.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-plc","manual":false,"prev":{"path":"/docs/occ-social-atproto-identities","title":"social:atproto:identities"},"next":{"path":"/docs/occ-social-atproto-resolve","title":"social:atproto:resolve"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-resolve","path":"/docs/occ-social-atproto-resolve","title":"social:atproto:resolve","description":"What a handle or DID is: the local identity, and the DID document the directory serves.","group":"occ","html":"<p>What a handle or DID is: the local identity, and the DID document the directory\nserves.</p>\n<pre><code>php occ social:atproto:resolve IDENTIFIER\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>identifier</code></td>\n<td>Yes</td>\n<td>A handle (<code>alice.social.example.com</code>) or a <code>did:plc</code></td>\n</tr>\n</tbody></table></div>\n<p>Exits 1 when neither this instance nor the directory knows it.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-resolve","manual":false,"prev":{"path":"/docs/occ-social-atproto-plc","title":"social:atproto:plc"},"next":{"path":"/docs/occ-social-atproto-repo","title":"social:atproto:repo"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-repo","path":"/docs/occ-social-atproto-repo","title":"social:atproto:repo","description":"A user's Bluesky repository: its head commit, what it holds, and whether it checks out.","group":"occ","html":"<p>A user&#39;s Bluesky repository: its head commit, what it holds, and whether it\nchecks out.</p>\n<pre><code>php occ social:atproto:repo USER [--verify]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>user</code></td>\n<td>Yes</td>\n<td>The Nextcloud user id, the handle or the DID</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--verify</code></td>\n<td>none</td>\n<td>Recompute the Merkle search tree from the records and check the head&#39;s signature; exits 1 when either differs</td>\n</tr>\n</tbody></table></div>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-repo","manual":false,"prev":{"path":"/docs/occ-social-atproto-resolve","title":"social:atproto:resolve"},"next":{"path":"/docs/occ-social-atproto-block","title":"social:atproto:block"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-block","path":"/docs/occ-social-atproto-block","title":"social:atproto:block","description":"The administrator's Bluesky block list: an account by its DID, or a PDS host and every account on it.","group":"occ","html":"<p>The administrator&#39;s Bluesky block list: an account by its DID, or a PDS host\nand every account on it.</p>\n<pre><code>php occ social:atproto:block [&lt;target&gt;] [--unblock] [--reason=REASON] [--list]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>target</code></td>\n<td>No</td>\n<td>A DID (<code>did:plc:…</code>), or a PDS host (<code>pds.example.com</code>); none lists the blocks</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--unblock</code></td>\n<td>none</td>\n<td>Take the target off the list</td>\n</tr>\n<tr>\n<td><code>--reason</code></td>\n<td>string</td>\n<td>Why, shown in the list</td>\n</tr>\n<tr>\n<td><code>--list</code></td>\n<td>none</td>\n<td>List the blocks (also what no target does)</td>\n</tr>\n</tbody></table></div>\n<p>A blocked account is not resolved, its posts are not read, its follows, likes\nand replies are dropped on arrival, and it does not appear in search. Blocking\none that is followed here purges it as a domain block purges a Fediverse\naccount: its posts, the follows, and the watch. A host blocks every account\nwhose PDS it is, and the hosts under it. The list is never published.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-block","manual":false,"prev":{"path":"/docs/occ-social-atproto-repo","title":"social:atproto:repo"},"next":{"path":"/docs/occ-social-atproto-crawl","title":"social:atproto:crawl"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-crawl","path":"/docs/occ-social-atproto-crawl","title":"social:atproto:crawl","description":"Ask the configured relays to subscribe to this instance's firehose now.","group":"occ","html":"<p>Ask the configured relays to subscribe to this instance&#39;s firehose now.</p>\n<pre><code>php occ social:atproto:crawl\n</code></pre>\n<p>Sends <code>com.atproto.sync.requestCrawl</code> to every relay in <code>atproto_relays</code>. A relay\nkeeps the subscription from then on. Maintenance also requests the initial crawl\nafter Bluesky is enabled and requests a new crawl after the firehose has been\nunreachable longer than its 72-hour replay window. If a relay accepted the\nrequest but an active repository or profile is still missing from relay/AppView\nchecks after an hour, maintenance retries at most every six hours. Failed\ninitial requests retry after 15 minutes. Use this command when an administrator\nwants to request a crawl immediately.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-crawl","manual":false,"prev":{"path":"/docs/occ-social-atproto-block","title":"social:atproto:block"},"next":{"path":"/docs/occ-social-atproto-rotate-key","title":"social:atproto:rotate-key"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-rotate-key","path":"/docs/occ-social-atproto-rotate-key","title":"social:atproto:rotate-key","description":"A new instance rotation key, and a PLC update for every identity so the new key is the one in charge.","group":"occ","html":"<p>A new instance rotation key, and a PLC update for every identity so the new key\nis the one in charge.</p>\n<pre><code>php occ social:atproto:rotate-key [--force]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--force</code></td>\n<td>none</td>\n<td>Do it without asking</td>\n</tr>\n</tbody></table></div>\n<p>The old key is kept, retired, for the PLC&#39;s 72-hour recovery window and dropped\nby the maintenance job after it. Each active or pending identity gets one\ndirectory operation, paced so the directory&#39;s limits are respected; one the\ndirectory does not confirm is resent by the maintenance job, a pending\nidentity&#39;s behind its genesis.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-rotate-key","manual":false,"prev":{"path":"/docs/occ-social-atproto-crawl","title":"social:atproto:crawl"},"next":{"path":"/docs/occ-social-atproto-keys-reseal","title":"social:atproto:keys:reseal"},"parent":"occ-queue-management"},{"slug":"occ-social-atproto-keys-reseal","path":"/docs/occ-social-atproto-keys-reseal","title":"social:atproto:keys:reseal","description":"Every Bluesky key — the instance rotation keys, the retired ones included, the service key and each account's signing key — sealed again under the instance secret in use, for after…","group":"occ","html":"<p>Every Bluesky key — the instance rotation keys, the retired ones included, the\nservice key and each account&#39;s signing key — sealed again under the instance\nsecret in use, for after <code>config.php</code>&#39;s <code>secret</code> changed.</p>\n<pre><code>php occ social:atproto:keys:reseal\nOC_OLD_SECRET=... php occ social:atproto:keys:reseal --old-secret-from-env\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--old-secret-from-env</code></td>\n<td>none</td>\n<td>Read the previous instance secret from the <code>OC_OLD_SECRET</code> environment variable</td>\n</tr>\n</tbody></table></div>\n<p>Without the option it counts the keys that do not open with the current secret\nand exits 1 when there are any; the Bluesky card and the setup check report the\nsame count. With it, each key that does not open is opened with the previous\nsecret and stored sealed with the current one — the same key, so every DID stays\nas it is — and a key neither secret opens is counted as failed and left alone.\nThe previous secret is read from the environment only, never from the command\nline, so it stays out of the shell history and the process list. Keys of\ntombstoned and moved-away identities sign nothing any more and are not touched.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-atproto-keys-reseal","manual":false,"prev":{"path":"/docs/occ-social-atproto-rotate-key","title":"social:atproto:rotate-key"},"next":{"path":"/docs/occ-social-queue-process","title":"social:queue:process"},"parent":"occ-queue-management"},{"slug":"occ-social-queue-process","path":"/docs/occ-social-queue-process","title":"social:queue:process","description":"Process both queues once: the outbound request queue (federation delivery) and the stream queue (caching of not-yet-resolved incoming objects).","group":"occ","html":"<p>Process both queues once: the outbound request queue (federation delivery) and the\nstream queue (caching of not-yet-resolved incoming objects).</p>\n<pre><code>php occ social:queue:process\n</code></pre>\n<p>No arguments or options. Prints how many items are in each queue, how many are\nprocessable right now, and a <code>.</code> per processed item.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-queue-process","manual":false,"prev":{"path":"/docs/occ-social-atproto-keys-reseal","title":"social:atproto:keys:reseal"},"next":{"path":"/docs/occ-social-queue-status","title":"social:queue:status"},"parent":"occ-queue-management"},{"slug":"occ-social-queue-status","path":"/docs/occ-social-queue-status","title":"social:queue:status","description":"Report the state of the outbound delivery queue, or dump the rows belonging to one request token.","group":"occ","html":"<p>Report the state of the outbound delivery queue, or dump the rows belonging to\none request token.</p>\n<pre><code>php occ social:queue:status [-t|--token TOKEN]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-t</code>, <code>--token</code></td>\n<td>optional</td>\n<td>Token of the request; without it, the whole queue is summarised</td>\n</tr>\n</tbody></table></div>\n<p>With a token, each matching row is printed as one line of JSON.</p>\n<p>Without one, the command prints how many deliveries are waiting and how many are\nbeing sent, how many have already failed at least once and how many are close to\nbeing abandoned (a delivery is dropped after 16 attempts), followed by the worst\ninstances — how many deliveries are stacked up for each, the highest attempt\ncount so far and when it was last tried. The same figures appear in the\nDeliveries section of the administration settings.</p>\n<p>Then the half that matters most: what this instance has <strong>given up on</strong>. An\nabandoned delivery used to appear nowhere — it left the failing count the moment\nit was abandoned, so the queue looked healthiest exactly when a peer had been\nlost for good. The count covers the last seven days, which is how long a\nfinished row is kept, and is followed by the same per-instance table under\n&quot;given up&quot;. <code>occ social:queue:retry --instance HOST</code> puts those deliveries back\nin the queue once the reason they failed has been dealt with.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-queue-status","manual":false,"prev":{"path":"/docs/occ-social-queue-process","title":"social:queue:process"},"next":{"path":"/docs/occ-social-queue-retry","title":"social:queue:retry"},"parent":"occ-queue-management"},{"slug":"occ-social-queue-retry","path":"/docs/occ-social-queue-retry","title":"social:queue:retry","description":"Retrying clears the attempt count and sets the row back to standby, so it gets the full run of retries again on the next queue cron (or occ social:queue:process) rather than being…","group":"occ","html":"<p>Put queued deliveries back on standby, or drop them.</p>\n<pre><code>php occ social:queue:retry [-t|--token TOKEN] [--min-tries N] [-i|--instance HOST]\n                           [--limit N] [--stream] [--flush] [-f|--force]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-t</code>, <code>--token</code></td>\n<td>optional</td>\n<td>Act on one delivery only, by the token <code>social:queue:status</code> prints</td>\n</tr>\n<tr>\n<td><code>--min-tries</code></td>\n<td>int (1)</td>\n<td>Without a token, act on the rows that have already failed at least this many times</td>\n</tr>\n<tr>\n<td><code>-i</code>, <code>--instance</code></td>\n<td>hostname</td>\n<td>Act on the deliveries for one host only, including the ones already given up on. Cannot be combined with <code>--stream</code>, which holds what came in rather than what was going out</td>\n</tr>\n<tr>\n<td><code>--limit</code></td>\n<td>int (500)</td>\n<td>How many rows one run touches at most; run it again to work through the rest</td>\n</tr>\n<tr>\n<td><code>--stream</code></td>\n<td>none</td>\n<td>Act on the inbound stream queue (<code>social_stream_queue</code>) instead of the outbound delivery queue</td>\n</tr>\n<tr>\n<td><code>--flush</code></td>\n<td>none</td>\n<td>Delete the matching rows instead of queueing them again</td>\n</tr>\n<tr>\n<td><code>-f</code>, <code>--force</code></td>\n<td>none</td>\n<td>Do not ask for confirmation (required with <code>--no-interaction</code>)</td>\n</tr>\n</tbody></table></div>\n<p>Retrying clears the attempt count and sets the row back to standby, so it gets the\nfull run of retries again on the next queue cron (or <code>occ social:queue:process</code>)\nrather than being abandoned on its next failure. <code>--flush</code> deletes the rows: those\nactivities are never delivered, which is what you want for a delivery that will\nnever succeed — a peer that is gone, or an activity it refuses.</p>\n<p>Rows that already succeeded are never touched, so a retry cannot send an activity\ntwice. Rows that were <em>abandoned</em> are: they are exactly what this command is for,\nand they are still in the table for seven days after the drain gave up on them.\n<code>--instance</code> is the form that answers <code>social:queue:status</code>, which names the\nhosts this instance has stopped delivering to:</p>\n<pre><code>php occ social:queue:retry --instance gone.example\n</code></pre>\n<p>The host is matched in PHP — it lives inside the JSON <code>instance</code> column — so the\ntable is read in pages of 1000 rows until <code>--limit</code> matching rows are found.</p>\n<p>The command prints how many rows matched, across how many delivery tokens\nand with what spread of attempt counts, and asks before it changes anything.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-queue-retry","manual":false,"prev":{"path":"/docs/occ-social-queue-status","title":"social:queue:status"},"next":{"path":"/docs/occ-development","title":"Development"},"parent":"occ-queue-management"},{"slug":"occ-development","path":"/docs/occ-development","title":"Development","description":"Seeds a plausible amount of content and times the queries behind the timelines, because a query's cost cannot be judged on the couple of dozen rows a development instance holds. For…","group":"occ","html":"<h2 id=\"social-benchmark\"><code>social:benchmark</code></h2>\n<p>Seeds a plausible amount of content and times the queries behind the timelines, because a query&#39;s cost cannot be judged on the couple of dozen rows a development instance holds. <strong>For development instances only</strong> — it writes thousands of rows.</p>\n<pre><code>php occ social:benchmark [--actors=200] [--notes=5000] [--follows=150] [--followers=0] [--viewer=USER]\n                         [--seed-only] [--time-only] [--runs=3] [--output=json|json_pretty]\n                         [--fail-over=MS] [--threshold=PROBE[@LIMIT]=MS ...]\n                         [--baseline=FILE] [--baseline-factor=3] [--clean] [-f|--force]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--actors</code></td>\n<td>int (200)</td>\n<td>Remote actors to seed</td>\n</tr>\n<tr>\n<td><code>--notes</code></td>\n<td>int (5000)</td>\n<td>Public notes to seed, five seconds apart going back from now</td>\n</tr>\n<tr>\n<td><code>--follows</code></td>\n<td>int (150)</td>\n<td>How many of those actors the viewer follows, which is what the home timeline joins through</td>\n</tr>\n<tr>\n<td><code>--followers</code></td>\n<td>int (0)</td>\n<td>How many of those actors follow the viewer <strong>back</strong>, which is what delivery reads: one queue row per distinct inbox when the viewer posts. An instance seeded without it measures reads and says nothing about writes</td>\n</tr>\n<tr>\n<td><code>--viewer</code></td>\n<td>username</td>\n<td>The local account the timelines are read as; the first local actor by default. It needs a Social account (<code>social:account:create</code>)</td>\n</tr>\n<tr>\n<td><code>--seed-only</code></td>\n<td>none</td>\n<td>Write the rows without timing anything</td>\n</tr>\n<tr>\n<td><code>--time-only</code></td>\n<td>none</td>\n<td>Time what is already seeded</td>\n</tr>\n<tr>\n<td><code>--runs</code></td>\n<td>int (3)</td>\n<td>Timed runs of each probe after one warm-up run; the median is reported</td>\n</tr>\n<tr>\n<td><code>--fail-over</code></td>\n<td>ms</td>\n<td>A ceiling for every probe that has no <code>--threshold</code> of its own</td>\n</tr>\n<tr>\n<td><code>--threshold</code></td>\n<td><code>PROBE=MS</code> or <code>PROBE@LIMIT=MS</code></td>\n<td>A ceiling for one probe, at every page size or at one (<code>home=150</code>, <code>home@20=120</code>). Repeatable</td>\n</tr>\n<tr>\n<td><code>--baseline</code></td>\n<td>file</td>\n<td>A JSON file of earlier timings, keyed by database (<code>pgsql</code>, <code>mysql</code>, <code>sqlite</code>) and then by <code>probe@limit</code>; other top-level keys are ignored, so the file can say how it was measured</td>\n</tr>\n<tr>\n<td><code>--baseline-factor</code></td>\n<td>number (3)</td>\n<td>How many times its baseline entry a probe may take</td>\n</tr>\n<tr>\n<td><code>--clean</code></td>\n<td>none</td>\n<td>Delete everything the command wrote and nothing else</td>\n</tr>\n<tr>\n<td><code>-f</code>, <code>--force</code></td>\n<td>none</td>\n<td>Seed without asking (required with <code>--no-interaction</code>)</td>\n</tr>\n</tbody></table></div>\n<p><strong>What is seeded.</strong> Every note is public, by one of the seeded actors in turn,\nand says one of thirteen topic words. One note in ten carries a picture and one\nin twenty-five a video — the share of media a real timeline has, so that the\nPhotos and Videos probes measure a page narrowed out of mostly text rather than\nan empty answer or the home timeline again. One note in twenty mentions the\nviewer and comes with the notification the inbox would have written; one in four\ncarries one of twenty hashtags. The notes&#39; recipient rows (public collection,\nauthor, the author&#39;s followers, and the viewer when mentioned) carry the note&#39;s\nnid, as the home timeline&#39;s page query reads it, and the hashtag rows and the\nwords of the search index are written with them. The tables are then analysed\n(<code>ANALYZE</code>), so that the plans timed are the ones a live instance gets rather\nthan ones made from the statistics of the tables before the seed.</p>\n<p>Seeding writes <strong>multi-row <code>INSERT</code>s directly</strong>, not through the model layer: a\n<code>Note</code> built and saved one at a time is three statements and a transaction per\nrow, about 400 rows a second, which makes ten million posts a seven-hour wait —\nso nobody ever seeded enough to find out what the queries cost. The rows are\nstill <em>shaped</em> like real ones (the prim hashes, the recipient rows, the follower\ncollections), because a query plan is only worth measuring against rows the\nplanner sees the way it sees real data. The cost is that a column added to\n<code>social_stream</code> later is one this command forgets to write; that is the right\ntrade for a development-only command and would be the wrong one anywhere else.</p>\n<p><strong>What is timed.</strong> Nine probes, each at a page of 20 and of 50 (the largest\npage a client may ask for): <code>home</code>, <code>public</code>, <code>direct</code>, <code>notifications</code>,\n<code>photos</code> and <code>videos</code> (the home timeline narrowed as the web client&#39;s Photos\nand Videos pages narrow it), <code>hashtag</code> (the probed tag, <code>benchtag0</code>), <code>account</code>\n(the first seeded actor&#39;s profile) and <code>search</code> (the word <code>harbour</code>). Each is\nread once to warm the caches and then <code>--runs</code> times; the median is the number.</p>\n<p><strong>Limits.</strong> A probe&#39;s ceiling is its <code>--threshold</code>, else <code>--fail-over</code>; its\nbaseline allowance is <code>--baseline-factor</code> times its <code>--baseline</code> entry. It is\nheld to the larger of the two, so a two-millisecond baseline does not fail on a\nshared runner&#39;s noise and a probe that was always slower than its ceiling only\nfails when it gets that much slower again. A probe with neither has no limit.\nAny probe over its limit makes the command exit 1 and name it. Every option is\nchecked before anything is seeded.</p>\n<p><code>--output=json</code> (or <code>json_pretty</code>) prints one JSON document on stdout — each\nprobe&#39;s median, rows, limit and verdict, the database, what was seeded, and the\ntwo switches that decide which query answers (<code>search_index_ready</code>,\n<code>dest_nid_filled</code>) — and sends the progress lines to stderr, so the output can\nbe redirected into a file. <code>.github/workflows/perf-nightly.yml</code> runs it that way\nevery night on MySQL and PostgreSQL with 100,000 notes, against the baseline in\n<code>tests/perf/benchmark-baseline.json</code>, and keeps each night&#39;s report as an\nartifact.</p>\n<p>Seeding says how many rows it is about to write and asks before writing any of\nthem; under <code>--no-interaction</code> it refuses unless <code>--force</code> is given, rather than\nseeding a production database because nobody was there to say no. <code>--clean</code> and\n<code>--time-only</code> write nothing and do not ask.</p>\n<p>Every row it writes carries <code>benchmark.invalid</code> in its id, which is what <code>--clean</code> matches on.</p>\n<hr>\n","toc":[{"id":"social-benchmark","text":"social:benchmark","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"development","manual":false,"prev":{"path":"/docs/occ-social-queue-retry","title":"social:queue:retry"},"next":{"path":"/docs/occ-cache","title":"Cache"},"parent":null},{"slug":"occ-cache","path":"/docs/occ-cache","title":"Cache","description":"Every command the app adds to occ, grouped by the task it performs.","group":"occ","html":"","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":[{"path":"/docs/occ-social-cache-refresh","title":"social:cache:refresh","description":"Steps and their output lines: local accounts deleted, local accounts regenerated, remote accounts created, remote accounts updated, remote accounts details updated, documents cached…","parent":true},{"path":"/docs/occ-social-counts-refresh","title":"social:counts:refresh","description":"Ask where each remote post lives — its own server, or the AppView for a post read from Bluesky — what its counts are right now, and store what it says. Local posts of the last seven days…","parent":true},{"path":"/docs/occ-social-starter-packs-refresh","title":"social:starter-packs:refresh","description":"Read the starter packs other servers publish again — the fediverse's collections (Mastodon's Collections, FEP-7aa9 FeaturedCollections) and Bluesky's suggested starter packs — now rather…","parent":true},{"path":"/docs/occ-social-media-retry","title":"social:media:retry","description":"Retry one remote attachment which was previously rejected by the media cache. This is useful after an administrator raises a size limit or the remote origin recovers from a temporary…","parent":true},{"path":"/docs/occ-social-media-recover","title":"social:media:recover","description":"Restore missing pictures on remote posts whose saved ActivityPub original still contains attachments. It does not rewrite post text, audience or date.","parent":true},{"path":"/docs/occ-social-media-posters","title":"social:media:posters","description":"Make the poster frames of videos that have none, so a client shows a still instead of a black rectangle before anybody presses play.","parent":true},{"path":"/docs/occ-social-team","title":"social:team","description":"What it is. Pixelfed's answer to \"several people, one voice\" is its Group* family: twenty models, still in beta, and a second social graph beside the one it already has. Nextcloud's answer…","parent":true},{"path":"/docs/occ-social-media-transcode","title":"social:media:transcode","description":"Convert stored videos to H.264 in an MP4, which is the one format the rest of the network plays.","parent":true},{"path":"/docs/occ-social-media-ladder","title":"social:media:ladder","description":"Write stored videos at a ladder of smaller sizes, as HLS, so a player can pick the one that fits the connection.","parent":true},{"path":"/docs/occ-social-media-strip-metadata","title":"social:media:strip-metadata","description":"Take the container metadata — where and with what it was recorded, its title, its chapters — off the video and sound files that were uploaded before uploads lost it on the way in, or while…","parent":true},{"path":"/docs/occ-social-media-usage","title":"social:media:usage","description":"Report what the app's media occupies on disk, split into what was uploaded here and what was cached off other servers.","parent":true}],"anchor":"cache","manual":false,"prev":{"path":"/docs/occ-development","title":"Development"},"next":{"path":"/docs/occ-social-cache-refresh","title":"social:cache:refresh"},"parent":null},{"slug":"occ-social-cache-refresh","path":"/docs/occ-social-cache-refresh","title":"social:cache:refresh","description":"Steps and their output lines: local accounts deleted, local accounts regenerated, remote accounts created, remote accounts updated, remote accounts details updated, documents cached…","group":"occ","html":"<p>Run the cache maintenance steps once, printing a counter per step.</p>\n<pre><code>php occ social:cache:refresh [-f|--force] [--rotate-keys]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-f</code>, <code>--force</code></td>\n<td>none</td>\n<td>Refresh cached remote actors even if they are not due — including the ones whose refresh has been given up on after ten consecutive failures, so this is also how an instance that has come back is asked again straight away. Every attempt is recorded either way, and one that works clears the failure count</td>\n</tr>\n<tr>\n<td><code>--rotate-keys</code></td>\n<td>none</td>\n<td>Renew the RSA key pair of local actors older than <code>AccountService::KEY_PAIR_LIFESPAN</code> (60) days. Blind rotation: no <code>Update</code> is federated, remote servers pick the new key up when they next fetch the actor (most do so after a failed signature check), so expect a short delivery hiccup. Deliberately opt-in and never run by the cron</td>\n</tr>\n</tbody></table></div>\n<p>Steps and their output lines: local accounts deleted, local accounts regenerated,\nremote accounts created, remote accounts updated, remote accounts details updated,\ndocuments cached, hashtags updated. With <code>--rotate-keys</code>, <code>N key pairs refreshed</code>\nis printed first.</p>\n<p>Rotation is the only step that is opt-in, and it is the only way to rotate a key\npair: nothing else calls <code>AccountService::blindKeyRotation()</code>, and the cron never\ndoes.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-cache-refresh","manual":false,"prev":{"path":"/docs/occ-cache","title":"Cache"},"next":{"path":"/docs/occ-social-counts-refresh","title":"social:counts:refresh"},"parent":"occ-cache"},{"slug":"occ-social-counts-refresh","path":"/docs/occ-social-counts-refresh","title":"social:counts:refresh","description":"Ask where each remote post lives — its own server, or the AppView for a post read from Bluesky — what its counts are right now, and store what it says. Local posts of the last seven days…","group":"occ","html":"<p>Ask where each remote post lives — its own server, or the AppView for a post\nread from Bluesky — what its counts are right now, and store what it says. Local\nposts of the last seven days that went to Bluesky are asked about too, for the\nlikes and reposts there whose notification never arrived.</p>\n<pre><code>php occ social:counts:refresh [-f|--force] [-l|--limit LIMIT]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-f</code>, <code>--force</code></td>\n<td>none</td>\n<td>Ask about every post, remote ones of any age, rather than only those of the last seven days not asked about in the last <code>RemoteCountService::TTL</code> (7200) seconds</td>\n</tr>\n<tr>\n<td><code>-l</code>, <code>--limit</code></td>\n<td>required</td>\n<td>Stop after this many remote posts, and as many local posts on Bluesky. <code>0</code>, the default, means all that are due, which is what a backfill wants</td>\n</tr>\n</tbody></table></div>\n<p>A post&#39;s counts were a snapshot of the moment it was imported and nothing ever\nlooked again, so a status sitting at two likes an hour ago still reads as two.\nThis asks each post&#39;s origin server for the <code>likes</code> and <code>shares</code> totals of its\nown document and replaces the stored figure with what comes back — the answer\nis only taken if the document&#39;s <code>id</code> is the one that was asked for, and a post\nthat answers with nothing keeps the count it had and is asked about again at\nthe next window rather than every pass.</p>\n<p>The stated total is split as <code>stated - local</code> before it is stored, so what is\ndisplayed stays the origin&#39;s number while the likes, boosts and replies made\nhere keep counting on top of it. Without <code>--force</code> only the remote posts of\nthe last seven days not asked about within the window are, as in the cron&#39;s\npass; with it every remote post is, however old, which is the backfill after a\nversion that never refreshed counts at all. A post whose server answers that it\nis not there (404) or gone (410) is not asked about again for thirty days.</p>\n<p>Reply counts are the limit of this: ActivityPub documents publish\n<code>replies.totalItems</code> on almost no server, so the reply figure is what this\ninstance holds and not a number the origin supplies.</p>\n<p>The cron (<code>OCA\\Social\\Cron\\Cache</code>) runs the same work on its own schedule for\nat most a minute per pass, <code>RemoteCountService::BATCH</code> posts at a time, and the\nposts people look at are asked about again as they are seen (every quarter of\nan hour while a post is less than a day old, every six hours after that; see\n<strong>Counts where a post lives</strong> in Architecture.md), so this command is for the\nother moments. It prints <code>N post(s) asked, M answered with a count</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-counts-refresh","manual":false,"prev":{"path":"/docs/occ-social-cache-refresh","title":"social:cache:refresh"},"next":{"path":"/docs/occ-social-starter-packs-refresh","title":"social:starter-packs:refresh"},"parent":"occ-cache"},{"slug":"occ-social-starter-packs-refresh","path":"/docs/occ-social-starter-packs-refresh","title":"social:starter-packs:refresh","description":"Read the starter packs other servers publish again — the fediverse's collections (Mastodon's Collections, FEP-7aa9 FeaturedCollections) and Bluesky's suggested starter packs — now rather…","group":"occ","html":"<p>Read the starter packs other servers publish again — the fediverse&#39;s\ncollections (Mastodon&#39;s Collections, FEP-7aa9 <code>FeaturedCollection</code>s) and\nBluesky&#39;s suggested starter packs — now rather than at the next daily run of\n<code>Cron\\StarterPackSources</code>, and store them.</p>\n<pre><code>php occ social:starter-packs:refresh\n</code></pre>\n<p>It reads every source the <code>starter_pack_sources</code> app value names (see\nAdmin.md), checks each member&#39;s consent to be in a fediverse collection\n(<code>featureAuthorization</code>), reads Bluesky&#39;s suggestions while Bluesky is on,\nand prints the sources, then <code>N starter pack(s) with M account(s) read from S source(s)</code>, how many accounts were left out\nwithout a valid authorization and how many sources or collections could not\nbe read. A source or collection that cannot be read keeps the packs read from\nit last time, and a member whose server does not answer stays in a pack it\nwas in before. Unlike the daily job, the command has no time limit.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-starter-packs-refresh","manual":false,"prev":{"path":"/docs/occ-social-counts-refresh","title":"social:counts:refresh"},"next":{"path":"/docs/occ-social-media-retry","title":"social:media:retry"},"parent":"occ-cache"},{"slug":"occ-social-media-retry","path":"/docs/occ-social-media-retry","title":"social:media:retry","description":"Retry one remote attachment which was previously rejected by the media cache. This is useful after an administrator raises a size limit or the remote origin recovers from a temporary…","group":"occ","html":"<p>Retry one remote attachment which was previously rejected by the media cache.\nThis is useful after an administrator raises a size limit or the remote origin\nrecovers from a temporary access problem.</p>\n<pre><code>php occ social:media:retry &lt;remote_url&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>remote_url</code></td>\n<td>Yes</td>\n<td>Exact HTTP(S) URL shown in the attachment&#39;s <code>remote_url</code> field</td>\n</tr>\n</tbody></table></div>\n<p>The argument must be the exact HTTP(S) <code>remote_url</code> exposed by Aloha Social. The\ncommand finds the cache row by that media URL and only resets a row with a\nstored media error and no local copy; it does not touch healthy cached files or\nretry every failed attachment at once. It clears the old error and caching\ntimestamp, then fetches that one document immediately through the usual MIME,\nsize, quota, blocklist, and image-decode checks. Exit code 0 means the copy was\nstored. If it is still refused, the command reports failure and the new\nrejection remains recorded for diagnosis.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-media-retry","manual":false,"prev":{"path":"/docs/occ-social-starter-packs-refresh","title":"social:starter-packs:refresh"},"next":{"path":"/docs/occ-social-media-recover","title":"social:media:recover"},"parent":"occ-cache"},{"slug":"occ-social-media-recover","path":"/docs/occ-social-media-recover","title":"social:media:recover","description":"Restore missing pictures on remote posts whose saved ActivityPub original still contains attachments. It does not rewrite post text, audience or date.","group":"occ","html":"<p>Restore missing pictures on remote posts whose saved ActivityPub original still\ncontains attachments. It does not rewrite post text, audience or date.</p>\n<pre><code>php occ social:media:recover [--dry-run] [--limit LIMIT]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--dry-run</code></td>\n<td>none</td>\n<td>List affected posts without downloading or changing anything</td>\n</tr>\n<tr>\n<td><code>--limit</code></td>\n<td>required</td>\n<td>Examine at most this many candidate posts; <code>0</code> (default) examines all</td>\n</tr>\n</tbody></table></div>\n<p>Only remote posts with an empty stored attachment list are candidates. For\neach original attachment, the normal federated media importer validates the\nURL and caches the file, then the command updates the post&#39;s attachment list\nand Photos/Videos index. Posts without usable media remain unchanged and are\nreported; run the command again after fixing a remote or local cache error.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-media-recover","manual":false,"prev":{"path":"/docs/occ-social-media-retry","title":"social:media:retry"},"next":{"path":"/docs/occ-social-media-posters","title":"social:media:posters"},"parent":"occ-cache"},{"slug":"occ-social-media-posters","path":"/docs/occ-social-media-posters","title":"social:media:posters","description":"Make the poster frames of videos that have none, so a client shows a still instead of a black rectangle before anybody presses play.","group":"occ","html":"<p>Make the poster frames of videos that have none, so a client shows a still\ninstead of a black rectangle before anybody presses play.</p>\n<pre><code>php occ social:media:posters [--dry-run] [--limit LIMIT]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--dry-run</code></td>\n<td>none</td>\n<td>Print the videos that have no poster and change nothing</td>\n</tr>\n<tr>\n<td><code>--limit</code></td>\n<td>required</td>\n<td>Stop after this many videos. <code>0</code>, the default, means all of them</td>\n</tr>\n</tbody></table></div>\n<p>A video uploaded here is given a still on its way in. Videos stored before that\nexisted, or while the server had no ffmpeg, have none and would never get one:\nthe frame is taken from the bytes as they are written and they are only written\nonce. This reads them back and takes it now — the same frame, the same JPEG and\nthe same <code>resized_copy</code> an upload gets, with the duration and the dimensions\nwritten into the document&#39;s <code>meta</code> alongside it. <strong>The video itself is not\ntouched</strong>: nothing is transcoded, re-encoded or re-written.</p>\n<p>Exits 1 without doing anything if ffmpeg is not on the server. A video ffmpeg\ncannot read is counted, reported and left alone, so the run finishes and the\nvideo can be tried again after whatever was wrong with it is fixed.</p>\n<p>The background job <code>Cron\\VideoPosters</code> does the same on its own, five videos\nevery fifteen minutes and each video once, so an instance gets its posters\nwithout anybody running this. The command is for doing all of them at once, and\nfor trying again the videos the job could not take a frame from: it reads every\nvideo that still has no poster, however far the job has got.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-media-posters","manual":false,"prev":{"path":"/docs/occ-social-media-recover","title":"social:media:recover"},"next":{"path":"/docs/occ-social-team","title":"social:team"},"parent":"occ-cache"},{"slug":"occ-social-team","path":"/docs/occ-social-team","title":"social:team","description":"What it is. Pixelfed's answer to \"several people, one voice\" is its Group* family: twenty models, still in beta, and a second social graph beside the one it already has. Nextcloud's answer…","group":"occ","html":"<p>Give a Nextcloud group an account to post from.</p>\n<pre><code>php occ social:team &lt;group&gt; &lt;username&gt;\nphp occ social:team --list\nphp occ social:team --remove &lt;username&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>group</code></td>\n<td>No</td>\n<td>The Nextcloud group. Required unless <code>--list</code> or <code>--remove</code> is used</td>\n</tr>\n<tr>\n<td><code>username</code></td>\n<td>No</td>\n<td>The handle the team posts under. Required unless <code>--list</code> or <code>--remove</code> is used</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--list</code></td>\n<td>none</td>\n<td>Show the team accounts there are, group by group</td>\n</tr>\n<tr>\n<td><code>--remove</code></td>\n<td>required</td>\n<td>Stop a handle being a team account. The account itself stays; delete it with <code>social:account:delete</code> if that is what you want</td>\n</tr>\n</tbody></table></div>\n<p><strong>What it is.</strong> Pixelfed&#39;s answer to &quot;several people, one voice&quot; is its\n<code>Group*</code> family: twenty models, still in beta, and a second social graph beside\nthe one it already has. Nextcloud&#39;s answer is the one it has had all along — a\ngroup of people who already work together — and this gives that group an\naccount. It is the one thing in this comparison Nextcloud can do and Pixelfed\ncannot, because Pixelfed has no idea who works with whom.</p>\n<p>A team account is <strong>an actor like any other</strong>: a key pair, a followers\ncollection, an inbox and an outbox, followable from Mastodon and Pixelfed,\nmoderatable and suspendable. What is new is only who may speak as it — and that\nis whoever is in the group, asked live every time rather than copied into a list\nthat would drift.</p>\n<p><strong>A command rather than a route, deliberately.</strong> Creating an actor makes an\naddress other servers will follow, cache and keep, which is an administrator&#39;s\ndecision. Posting as one afterwards needs no administrator at all: everybody in\nthe group finds it in the composer.</p>\n<p>Who wrote each post from a team account is recorded and shown to the team and to\nmoderators, and to nobody else — outside the team, one voice is the point of\nhaving a team account; inside it, and in a report, the trail is.</p>\n<p>A group that does not exist, and one that already has an account, are each\nrefused by name.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-team","manual":false,"prev":{"path":"/docs/occ-social-media-posters","title":"social:media:posters"},"next":{"path":"/docs/occ-social-media-transcode","title":"social:media:transcode"},"parent":"occ-cache"},{"slug":"occ-social-media-transcode","path":"/docs/occ-social-media-transcode","title":"social:media:transcode","description":"Convert stored videos to H.264 in an MP4, which is the one format the rest of the network plays.","group":"occ","html":"<p>Convert stored videos to H.264 in an MP4, which is the one format the rest of\nthe network plays.</p>\n<pre><code>php occ social:media:transcode [--limit LIMIT]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--limit</code></td>\n<td>required</td>\n<td>Stop after this many videos. 25 by default</td>\n</tr>\n</tbody></table></div>\n<p><strong>Why it matters:</strong> Pixelfed&#39;s default <code>media_types</code> accepts <code>video/mp4</code> and\nnothing else, so every <code>video/quicktime</code> posted from here — which is every video\nstraight off an iPhone — is dropped by its inbox without a word to anybody.\nSafari will not play WebM either, and only Safari plays the HEVC that phones\nwrite into an <code>.mp4</code>, so an MP4 whose video ffprobe does not report as H.264 is\nconverted too. An H.264 MP4 is never re-encoded; without ffprobe an MP4 is left\nas it is.</p>\n<p>On by default, and nothing happens on a server without ffmpeg. An administrator\ncan switch it off — re-encoding is lossy, and <strong>the converted file replaces the\noriginal</strong> — under <strong>Administration → Aloha Social → Server → Convert videos to MP4\nin the background</strong>, or with <code>occ config:app:set social video_transcode --value=0</code>. The command exits 1 and changes nothing when it is off, or when the\nserver has no ffmpeg.</p>\n<p>A new post does not wait for this command or the sweep: the video it carries is\nconverted by a job of its own at the next cron run, and the post&#39;s delivery is\nheld until then (at most ten minutes). The same work also runs by itself in the\nbackground for everything else, one video every quarter of an hour, which is\nabout a hundred a day — fast enough that a backlog clears and slow enough that a\nserver converting one is never the reason its cron is late. An MP4 found to be\nH.264 costs a copy and a probe rather than a conversion, and a run reads up to\nfive of those. This command is for an administrator who has just installed\nffmpeg and would rather not wait a week. Posts that went out before their video\nwas converted are not sent again.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-media-transcode","manual":false,"prev":{"path":"/docs/occ-social-team","title":"social:team"},"next":{"path":"/docs/occ-social-media-ladder","title":"social:media:ladder"},"parent":"occ-cache"},{"slug":"occ-social-media-ladder","path":"/docs/occ-social-media-ladder","title":"social:media:ladder","description":"Write stored videos at a ladder of smaller sizes, as HLS, so a player can pick the one that fits the connection.","group":"occ","html":"<p>Write stored videos at a ladder of smaller sizes, as HLS, so a player can pick\nthe one that fits the connection.</p>\n<pre><code>php occ social:media:ladder [--limit LIMIT]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--limit</code></td>\n<td>required</td>\n<td>Stop after this many videos. 10 by default</td>\n</tr>\n</tbody></table></div>\n<p><strong>Why it matters:</strong> a stored video is one file at whatever height it was\nuploaded at, and a reader on a phone on a train downloads the 1080p of it or\nnothing. A ladder is the same video written two or three more times, smaller,\nplus a playlist that lets the player move between them as the connection\nchanges. It is also the shape PeerTube publishes, so a laddered video reaches a\nPeerTube reader the way a native one does.</p>\n<p>Each rung is <strong>one file</strong>: <code>-hls_flags single_file</code> writes the whole rendition\nas a fragmented MP4 and the playlist addresses each segment as a byte range into\nit, so a forty-minute video is three files rather than a thousand. Rungs at or\nabove a video&#39;s own height are skipped rather than upscaled.</p>\n<p>Off unless an administrator turned it on: <strong>Administration → Aloha Social → Server →\nBuild a ladder of video sizes</strong>, or <code>occ config:app:set social video_ladder --value=1</code>. Which heights, with <code>occ config:app:set social video_ladder_heights --value=360,720,1080</code>. The command exits 1 and changes nothing when it is off,\nor when the server has no ffmpeg and ffprobe.</p>\n<p>Slower per video than <code>social:media:transcode</code> by however many rungs the ladder\nhas — worth knowing before starting it on a library of ten thousand. The\nbackground job does one video every half-hour.</p>\n<p>The converted file is written before the row is pointed at it and the original is\ndeleted last, so a failure anywhere leaves a document pointing at a file that\nexists, and the posts carrying the video are pointed at the new file before the\noriginal goes. A video ffmpeg cannot read is recorded as tried and left alone\nrather than retried for ever, and one that is already an H.264 MP4 is passed\nover without being re-encoded into a second generation of loss.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-media-ladder","manual":false,"prev":{"path":"/docs/occ-social-media-transcode","title":"social:media:transcode"},"next":{"path":"/docs/occ-social-media-strip-metadata","title":"social:media:strip-metadata"},"parent":"occ-cache"},{"slug":"occ-social-media-strip-metadata","path":"/docs/occ-social-media-strip-metadata","title":"social:media:strip-metadata","description":"Take the container metadata — where and with what it was recorded, its title, its chapters — off the video and sound files that were uploaded before uploads lost it on the way in, or while…","group":"occ","html":"<p>Take the container metadata — where and with what it was recorded, its title,\nits chapters — off the video and sound files that were uploaded before uploads\nlost it on the way in, or while the server had no ffmpeg.</p>\n<pre><code>php occ social:media:strip-metadata [--dry-run] [--limit LIMIT]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--dry-run</code></td>\n<td>none</td>\n<td>Print the files that would be rewritten, and those left because they are on Bluesky, and change nothing</td>\n</tr>\n<tr>\n<td><code>--limit</code></td>\n<td>required</td>\n<td>Stop after this many files. <code>0</code>, the default, means all of them</td>\n</tr>\n</tbody></table></div>\n<p>Each local upload is read back and remuxed with ffmpeg (<code>-c copy -map_metadata -1 -map_chapters -1</code>): the streams are copied into a fresh container of the same\nkind, nothing is re-encoded. The documents are walked fifty at a time, one line\nper file, and the run ends with how many were rewritten, already clean, left\nbecause they are published on Bluesky, had no stored file, or could not be\nrewritten.</p>\n<p>A rewritten file is stored under a new name and the old one deleted, with the\ndocument&#39;s size updated and the posts carrying it pointed at the new copy —\na stored file is served as immutable by its name, so changing the bytes under\nthe same one would leave the old ones in every cache that holds them. A video&#39;s\nladder (<code>social:media:ladder</code>) is rebuilt from the new copy. A file ffmpeg\ncannot rewrite, or whose rewrite is the same bytes, is left exactly as it is,\nand the first is logged.</p>\n<p><strong>A file published on Bluesky is left as it is</strong>: a blob in a Bluesky repository\nis named by the hash of its bytes (its CID), and so is a video handed to\nBluesky&#39;s video service, so rewriting it would break the record that names it.\nThe output counts these.</p>\n<p>Exits 1 without doing anything if ffmpeg is not on the server. A run over a\nfile that is already clean changes nothing, so it can be repeated.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-media-strip-metadata","manual":false,"prev":{"path":"/docs/occ-social-media-ladder","title":"social:media:ladder"},"next":{"path":"/docs/occ-social-media-usage","title":"social:media:usage"},"parent":"occ-cache"},{"slug":"occ-social-media-usage","path":"/docs/occ-social-media-usage","title":"social:media:usage","description":"Report what the app's media occupies on disk, split into what was uploaded here and what was cached off other servers.","group":"occ","html":"<p>Report what the app&#39;s media occupies on disk, split into what was uploaded here\nand what was cached off other servers.</p>\n<pre><code>php occ social:media:usage\n</code></pre>\n<p>No options of its own. <code>--output=json</code> (or <code>json_pretty</code>) prints the same\nfigures as a structure, for a monitoring script.</p>\n<p>The two halves are very different things: an upload is the only copy there is,\nand a cached remote file is a copy that can be thrown away and fetched again.\nEach half is broken down into attachments and the avatars and headers of\naccounts. Every row of <code>social_cache_doc</code> is walked and the size of each stored\ncopy — the original and the resized one — is read from appdata, file by file,\nrather than taken from anything the row claims:</p>\n<pre><code>12043 document row(s) in social_cache_doc\n\nUploaded here                   842 files     2.1 GiB\n  attachments                   808 files     2.0 GiB\n  avatars and headers            34 files    41.3 MiB\nCached from other servers     19664 files     8.7 GiB\n  attachments                 15912 files     8.4 GiB\n  avatars and headers          3752 files   311.0 MiB\n\nTotal on disk                 20506 files    10.8 GiB\n</code></pre>\n<p>Three counts are printed after the total when they are not zero: copies that are\n<em>streamed</em> (a pointer at a file on the server that holds it, so no bytes here),\ncopies served from Nextcloud&#39;s own avatar store rather than by this app, and\ncopies a row names that are <strong>not in appdata</strong> — reported rather than counted as\nzero bytes, because a cached remote one is simply fetched again when it is next\nasked for.</p>\n<p>No quota accounting: this is what is on disk, not what anybody is allowed. It\nalso does not walk appdata looking for files no row names — the path of a copy\nis derived from its own name, so finding an orphan means listing a four-level\ntree with a directory per file, and there is no safe way to delete a file this\napp cannot name.</p>\n<p>The number to read it against is <code>cache_actor_days</code> (default 180), which is how\nlong a cached remote account nobody here refers to survives before the cache\ncron evicts it with its avatar; <code>occ config:app:set social cache_actor_days --value 0</code> turns that sweep off.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"social-media-usage","manual":false,"prev":{"path":"/docs/occ-social-media-strip-metadata","title":"social:media:strip-metadata"},"next":{"path":"/docs/occ-federation","title":"Federation"},"parent":"occ-cache"},{"slug":"occ-federation","path":"/docs/occ-federation","title":"Federation","description":"import accepts a first-column #domain/domain header or a plain one-domain-per-line file. It validates the entire file before mutation, skips duplicates, caps an import at 10,000 unique…","group":"occ","html":"<h2 id=\"social-fediverse\"><code>social:fediverse</code></h2>\n<p>Inspect and change the Fediverse access list.</p>\n<pre><code>php occ social:fediverse [-t|--type TYPE] [--dry-run] [-f|--force] [&lt;action&gt;] [&lt;address&gt;]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>action</code></td>\n<td>No</td>\n<td><code>&#39;&#39;</code></td>\n<td>One of <code>list</code>, <code>add</code>, <code>remove</code>, <code>import</code>, <code>test</code>, <code>reset</code>, <code>silence</code>, <code>unsilence</code>, <code>silenced</code>, or empty</td>\n</tr>\n<tr>\n<td><code>address</code></td>\n<td>No</td>\n<td><code>&#39;&#39;</code></td>\n<td>Host for single-address actions, or a readable CSV path for <code>import</code></td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-t</code>, <code>--type</code></td>\n<td>required</td>\n<td>Set the access type. Only <code>all_but</code> (deny-list, the default) and <code>none_but</code> (allow-list) are accepted; anything else throws <code>invalid type</code> (<code>FediverseService::setAccessType()</code>).</td>\n</tr>\n<tr>\n<td><code>--dry-run</code></td>\n<td>none</td>\n<td>For <code>import</code>: read and validate the CSV, print the domains it would add, and change nothing.</td>\n</tr>\n<tr>\n<td><code>-f</code>, <code>--force</code></td>\n<td>none</td>\n<td>For <code>import</code>: skip the confirmation prompt. Required with <code>--no-interaction</code>; without it a non-interactive run prints <code>Refusing to run non-interactively without --force</code> and returns 1.</td>\n</tr>\n</tbody></table></div>\n<p>Passing <code>--type</code> <strong>sets the type and exits</strong> — the <code>action</code> argument is not executed\nin the same invocation (<code>Fediverse::typeAccess()</code> returns true and the command\nreturns). Without <code>--type</code>, the\ncommand first prints the current access type and then runs the action:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Action</th>\n<th>Effect</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><em>(empty)</em></td>\n<td>Print the access list under <code>- List:</code></td>\n</tr>\n<tr>\n<td><code>list</code></td>\n<td>Print <code>- Known address:</code> followed by the access list</td>\n</tr>\n<tr>\n<td><code>add &lt;address&gt;</code></td>\n<td>Add the address to the list</td>\n</tr>\n<tr>\n<td><code>remove &lt;address&gt;</code></td>\n<td>Remove the address from the list</td>\n</tr>\n<tr>\n<td><code>import &lt;csv_file&gt;</code></td>\n<td>Read domains from the CSV&#39;s first column and add them to the existing <code>all_but</code> block list, after asking</td>\n</tr>\n<tr>\n<td><code>test &lt;address&gt;</code></td>\n<td>Print <code>Authorized</code> or <code>Unauthorized</code> for that address</td>\n</tr>\n<tr>\n<td><code>reset</code></td>\n<td>Empty the list</td>\n</tr>\n<tr>\n<td><code>silence &lt;address&gt;</code></td>\n<td>Silence the instance: keep it out of the public, global and hashtag timelines</td>\n</tr>\n<tr>\n<td><code>unsilence &lt;address&gt;</code></td>\n<td>Lift the silence</td>\n</tr>\n<tr>\n<td><code>silenced</code></td>\n<td>Print the silenced instances under <code>- Silenced:</code></td>\n</tr>\n</tbody></table></div>\n<p><code>import</code> accepts a first-column <code>#domain</code>/<code>domain</code> header or a plain\none-domain-per-line file. It validates the entire file before mutation, skips\nduplicates, caps an import at 10,000 unique domains and the file at 8 MB, and\nrefuses allow-list mode. Each new domain receives the same audit entry and\nqueued purge as an individual block — which is why it asks before writing, and\nwhy <code>--dry-run</code> exists. A row naming a single label (<code>com</code>, <code>localhost</code>) is\nrefused: an entry covers every subdomain of itself, so one such row would block\na whole top-level domain. So is a row naming this instance. Neither is a\npublic-suffix check — <code>co.uk</code> still passes — so read a file with <code>--dry-run</code>\nbefore applying it. It does not fetch remote sources; review an export before\nrunning it. An unknown action throws\n<code>specify action: add, remove, import, list, reset, silence, unsilence, silenced</code>.\n<code>silence</code> and <code>unsilence</code> without an address throw <code>specify an address to silence</code> / <code>... to unsilence</code>.</p>\n<p><strong>Silencing, the tier between a block and nothing.</strong> A block cuts the instance\noff in both directions and <code>social:domain:purge</code> deletes what it already sent,\nwhich also cuts off the local users who deliberately follow somebody there — so\nthe tool was too blunt to reach for and the nuisance stayed. A silence stores\nthe host in a second list (<code>silenced_list</code>) and changes one thing: posts whose\nauthor is on that instance are left out of the <strong>public</strong>, <strong>global</strong>,\n<strong>hashtag</strong> and <strong>followed-tag</strong> timelines (<code>StreamRequest::filterSilencedInstances()</code>).\nDelivery, fetching, webfinger, search by address, following, and the home\ntimeline of somebody who follows the account are all untouched — a silence is\nnot enforced in <code>authorized()</code>. Nothing is deleted, so <code>unsilence</code> brings the\nposts back.</p>\n<p>The match is on the author&#39;s actor id, so it covers the domain <strong>and everything\nunder it</strong> the way a deny-list entry does: silencing <code>noisy.test</code> also silences\n<code>sub.noisy.test</code>, and not <code>notnoisy.test</code>. The two lists are independent — an\ninstance can be silenced, blocked, both or neither.</p>\n<p><strong>What is actually enforced.</strong> There is a single list (<code>access_list</code>) whose meaning\ndepends on <code>access_type</code>: with <code>all_but</code> every address that is <em>not</em> listed is\nallowed; with <code>none_but</code> only listed addresses and the local host are allowed.\n<code>FediverseService::authorized()</code> is enforced on both inbox routes in\n<code>ActivityPubController</code> and on every outgoing HTTP request in <code>CurlService</code>, so the\nlist does take effect for inbox delivery and for fetching remote data. A refused\ninbox delivery is answered <strong>403</strong>, not 500, so the peer stops redelivering it —\nsee the rejection table in <code>docs/Architecture.md</code>.</p>\n<p><strong>How an address is matched.</strong> Case-insensitively, and without the trailing dot of\nthe absolute form. The two modes then read the list differently, on purpose:</p>\n<ul>\n<li>With <code>all_but</code>, a listed domain covers the domain itself <strong>and everything under\nit</strong> (<code>isListed()</code>). Blocking <code>evil.test</code> while <code>www.evil.test</code> walks straight\nback in is not a block.</li>\n<li>With <code>none_but</code>, an entry matches <strong>exactly</strong> (<code>isExactlyListed()</code>). A subdomain\nof an allowed domain is a different instance, and whoever runs the parent domain\nwas never asked before it appeared.</li>\n</ul>\n<p>There is no wildcard syntax; <code>add</code> stores what you type, and <code>remove</code> takes it away\nby the same exact comparison.</p>\n<p><strong>Known limitations:</strong></p>\n<ul>\n<li><code>list</code> always prints an empty <code>Known address:</code> section, because\n<code>FediverseService::getKnownAddresses()</code> returns an empty array.</li>\n<li>The older two-list implementation (<code>blockAddress()</code>, <code>allowAddress()</code>,\n<code>isBlocked()</code>, <code>isAllowed()</code>, and the separate blacklist/whitelist config keys) is\ncommented out at the end of <code>lib/Service/FediverseService.php</code>. Only the single\n<code>access_list</code> above exists; there is no separate block list.</li>\n<li>Webfinger lookups are not filtered per address; <code>WebfingerHandler</code> only calls\n<code>jailed()</code>, which refuses service when the instance is in <code>none_but</code> mode with an\nempty list.</li>\n</ul>\n<h2 id=\"social-emoji\"><code>social:emoji</code></h2>\n<p>The custom emoji this instance publishes.</p>\n<pre><code>php occ social:emoji [-c|--category CATEGORY] [--hidden] [&lt;action&gt;] [&lt;shortcode&gt;] [&lt;file&gt;]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>action</code></td>\n<td>No</td>\n<td><code>list</code></td>\n<td>One of <code>list</code>, <code>add</code>, <code>remove</code></td>\n</tr>\n<tr>\n<td><code>shortcode</code></td>\n<td>No</td>\n<td><code>&#39;&#39;</code></td>\n<td>Required by <code>add</code> and <code>remove</code>. The name between the colons: 2–64 characters of <code>a-z</code>, <code>0-9</code> and <code>_</code>. Read lowercase and trimmed, so <code>BlobCat</code> and <code>blobcat</code> are the same emoji</td>\n</tr>\n<tr>\n<td><code>file</code></td>\n<td>No</td>\n<td><code>&#39;&#39;</code></td>\n<td>Required by <code>add</code>. A readable path to the picture</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-c</code>, <code>--category</code></td>\n<td>required</td>\n<td>Group it under this in a client&#39;s picker</td>\n</tr>\n<tr>\n<td><code>--hidden</code></td>\n<td>none</td>\n<td>Store it usable by name but not offered in a picker (Mastodon&#39;s <code>visible_in_picker: false</code>)</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Action</th>\n<th>Effect</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>list</code> <em>(the default)</em></td>\n<td>Print every emoji with its category, whether a picker offers it, and the URL it is served from</td>\n</tr>\n<tr>\n<td><code>add &lt;shortcode&gt; &lt;file&gt;</code></td>\n<td>Publish the picture under that shortcode</td>\n</tr>\n<tr>\n<td><code>remove &lt;shortcode&gt;</code></td>\n<td>Stop publishing it</td>\n</tr>\n</tbody></table></div>\n<p>An unknown action throws <code>specify action: list, add, remove</code>; removing one that\nis not there throws <code>no emoji is published as :&lt;shortcode&gt;:</code>.</p>\n<p><strong>What is accepted.</strong> A PNG, GIF, WebP or JPEG of at most <strong>256 KiB</strong> — the\nbytes decide, not the extension, because this is served to every reader of\nevery post that uses it. Anything else is refused with a reason.</p>\n<p><strong>What <code>add</code> does to a shortcode already in use.</strong> Replaces the picture. A\nshortcode names one emoji, and an admin re-uploading under a name in use means\nto replace it rather than to be told it exists.</p>\n<p><strong>What a post carries.</strong> The shortcode stays in the content as text, and an\n<code>Emoji</code> tag beside it says where the picture is — which is how every fediverse\nserver does it, and why an instance that has never heard of <code>:blobcat:</code> still\nrenders the post. A shortcode this instance has no picture for is left as the\ntext it already was. Editing a post rebuilds its tags, so a shortcode added by\nan edit renders and one removed by an edit takes its tag with it.</p>\n<p><strong>What <code>remove</code> does to posts that used it.</strong> Nothing. What they carry is the\ntag they were federated with; this instance no longer offering the picture does\nnot rewrite what was already said. Locally, the picture stops being served, so\nthe shortcode shows as text again.</p>\n<h2 id=\"social-gif\"><code>social:gif</code></h2>\n<p>The shared pictures the composer offers in its GIF picker, on top of the 881\nanimated emoji every instance has (<code>gif_pack</code>, on by default — see\n<a href=\"/docs/architecture\">Architecture</a>). These are the ones that are <em>this</em> instance&#39;s:\nthe in-joke, the team&#39;s own, the thing nowhere else has. They are offered first,\nabove the emoji.</p>\n<pre><code>php occ social:gif [-t|--title TITLE] [&lt;action&gt;] [&lt;slug&gt;] [&lt;file&gt;]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>action</code></td>\n<td>No</td>\n<td><code>list</code></td>\n<td>One of <code>list</code>, <code>add</code>, <code>remove</code></td>\n</tr>\n<tr>\n<td><code>slug</code></td>\n<td>No</td>\n<td><code>&#39;&#39;</code></td>\n<td>Required by <code>add</code> and <code>remove</code>. What the picture is served and searched under: 2–64 characters of <code>a-z</code>, <code>0-9</code>, <code>-</code> and <code>_</code>. Read lowercase and trimmed</td>\n</tr>\n<tr>\n<td><code>file</code></td>\n<td>No</td>\n<td><code>&#39;&#39;</code></td>\n<td>Required by <code>add</code>. A readable path to the picture</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-t</code>, <code>--title</code></td>\n<td>required</td>\n<td>What the picker searches on — &quot;the one with the cat&quot; is how anybody actually looks for one of these</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Action</th>\n<th>Effect</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>list</code> <em>(the default)</em></td>\n<td>Print every picture in the library with its title and the URL it is served from</td>\n</tr>\n<tr>\n<td><code>add &lt;slug&gt; &lt;file&gt;</code></td>\n<td>Put the picture in the library under that slug</td>\n</tr>\n<tr>\n<td><code>remove &lt;slug&gt;</code></td>\n<td>Take it out</td>\n</tr>\n</tbody></table></div>\n<p>An unknown action throws <code>specify action: list, add, remove</code>; removing one that\nis not there throws <code>there is no library picture called &lt;slug&gt;</code>.</p>\n<p><strong>What is accepted.</strong> A GIF, an animated WebP or an MP4 of at most <strong>8 MiB</strong> —\nthe bytes decide, not the extension. Animated formats only: a library of stills\nis what the Files picker beside it is already for. The metadata is stripped the\nway every other upload&#39;s is, because these end up attached to posts that leave\nthis instance.</p>\n<p><strong>Why there is no upload form.</strong> This is a small set curated for a whole\ninstance rather than something every reader adds to, and the files an\nadministrator wants in it are already on a machine they have a shell on.</p>\n<p><strong>Why there is no Giphy or Tenor.</strong> Both would mean every composer on the\ninstance talking to a third party: the search terms people type go there, and\nevery thumbnail is a request from a reader&#39;s browser to a host the instance does\nnot control. That is not a decision this app should make on an administrator&#39;s\nbehalf, and a setting to turn it on would still be a setting that quietly sends\nwhat people are looking for to somebody else&#39;s server.</p>\n<p><strong>What <code>add</code> does to a slug already in use.</strong> Replaces the picture, for the\nreason <code>social:emoji add</code> does.</p>\n<p><strong>What <code>remove</code> does to posts that used it.</strong> Nothing. An attachment is a copy\ntaken when the post was written, so a post keeps the picture it was published\nwith.</p>\n<h2 id=\"social-domain-purge\"><code>social:domain:purge</code></h2>\n<p>Delete everything an instance already sent this one. Blocking the domain\n(<code>social:fediverse add</code>) is what stops it coming back; this removes what arrived\nbefore the block.</p>\n<pre><code>php occ social:domain:purge [-b|--batches BATCHES] [--check] &lt;domain&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>domain</code></td>\n<td>Yes</td>\n<td>The instance to purge, e.g. <code>spam.example</code>. Accepts what a user would type — <code>https://spam.example/@someone</code>, <code>@someone@spam.example</code>, <code>Spam.Example:8443</code> — and reduces it to the host</td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>-b</code>, <code>--batches</code></td>\n<td>required</td>\n<td>Stop after this many batches of 50 accounts instead of running to the end. Without it the command runs until nothing of the domain is left</td>\n</tr>\n<tr>\n<td><code>--check</code></td>\n<td>none</td>\n<td>Only report whether anything of the domain is still stored; deletes nothing</td>\n</tr>\n</tbody></table></div>\n<p><strong>What goes.</strong> For every account of that instance still known here: its cached\nactor, its posts (with their recipient, tag, action, card, revision and cached\nattachment rows), the notifications they caused, the follows in <strong>both</strong>\ndirections, the per-user blocks, mutes and notes about it, and the deliveries\nstill queued towards it. Leaving the follows behind kept the instance in the\ndelivery fan-out of every local post.</p>\n<p><strong>This cannot be undone.</strong> Unblocking the domain lets it reach the instance\nagain; it does not restore anything deleted here. The command says so before it\nexits.</p>\n<p><strong>Safe to interrupt and safe to repeat.</strong> Each pass asks what of the domain is\nstill stored rather than counting off a position, so a run that is killed half\nway is resumed by running it again, and a run against an already-purged domain\ndoes nothing. Accounts are found from three places — the actor cache, the\nauthors of stored posts, and the follow rows — because a post can outlive the\nactor it was cached from and a follow can name an account this instance never\ncached.</p>\n<p><strong>The exact host, not subdomains.</strong> A deny-list entry covers everything under\nthe domain (<code>isListed()</code>), but the purge does not: refusing traffic from one\ninstance too many is undone by editing the list, and deleting one is not. Purge\neach subdomain you mean to include.</p>\n<p><strong>This normally runs on its own.</strong> Adding a domain to the deny list queues\n<code>OCA\\Social\\Cron\\DomainPurge</code>, which does 10 batches per cron run and re-queues\nitself until the instance is gone. Use this command for a domain blocked before\nthe purge existed, for a job that failed part way, or to finish without waiting\nfor cron.</p>\n<hr>\n","toc":[{"id":"social-fediverse","text":"social:fediverse","level":2},{"id":"social-emoji","text":"social:emoji","level":2},{"id":"social-gif","text":"social:gif","level":2},{"id":"social-domain-purge","text":"social:domain:purge","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"federation","manual":false,"prev":{"path":"/docs/occ-social-media-usage","title":"social:media:usage"},"next":{"path":"/docs/occ-external-users","title":"External Users"},"parent":null},{"slug":"occ-external-users","path":"/docs/occ-external-users","title":"External Users","description":"Self-registered external users: list them, add one without the registration form, or promote one to an ordinary local user.","group":"occ","html":"<h2 id=\"social-external\"><code>social:external</code></h2>\n<p>Self-registered external users: list them, add one without the registration\nform, or promote one to an ordinary local user.</p>\n<pre><code>php occ social:external list\nOC_PASS=... php occ social:external add &lt;handle&gt; --email EMAIL --password-from-env\nphp occ social:external promote &lt;handle&gt;\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Argument</th>\n<th>Required</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>action</code></td>\n<td>Yes</td>\n<td><code>list</code>, <code>add</code> or <code>promote</code></td>\n</tr>\n<tr>\n<td><code>handle</code></td>\n<td>No</td>\n<td>The user id, which is also the Aloha Social handle; needed by <code>add</code> and <code>promote</code></td>\n</tr>\n</tbody></table></div>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--email</code></td>\n<td>required</td>\n<td>The email address of a new external user, for <code>add</code></td>\n</tr>\n<tr>\n<td><code>--password-from-env</code></td>\n<td>none</td>\n<td>Read the password of a new external user from the <code>OC_PASS</code> environment variable, for <code>add</code></td>\n</tr>\n</tbody></table></div>\n<p><code>add</code> checks the handle, the email address and the room left under the\nmaximum the same way the registration page does, and needs external users to\nbe switched on. It skips email confirmation and approval. <code>promote</code> moves the\nuser to Nextcloud&#39;s database backend with the same user id and password hash;\nfrom then on the normal app and group rules apply to them. A refusal prints\nthe reason and exits with 1.</p>\n<hr>\n","toc":[{"id":"social-external","text":"social:external","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"external-users","manual":false,"prev":{"path":"/docs/occ-federation","title":"Federation"},"next":{"path":"/docs/occ-installation-and-maintenance","title":"Installation & Maintenance"},"parent":null},{"slug":"occ-installation-and-maintenance","path":"/docs/occ-installation-and-maintenance","title":"Installation & Maintenance","description":"Check the integrity of the installation, or regenerate the stream index.","group":"occ","html":"<h2 id=\"social-check-install\"><code>social:check:install</code></h2>\n<p>Check the integrity of the installation, or regenerate the stream index.</p>\n<pre><code>php occ social:check:install [--index] [--offline] [-f|--force]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--index</code></td>\n<td>none</td>\n<td>Regenerate the stream index instead of running the checks</td>\n</tr>\n<tr>\n<td><code>--offline</code></td>\n<td>none</td>\n<td>Leave out the WebFinger probe, the one check that goes out on the network</td>\n</tr>\n<tr>\n<td><code>-f</code>, <code>--force</code></td>\n<td>none</td>\n<td>Skip the confirmation of <code>--index</code> (required with <code>--no-interaction</code>)</td>\n</tr>\n</tbody></table></div>\n<p>Without <code>--index</code>:</p>\n<ul>\n<li>runs <code>CheckService::checkInstallationStatus()</code>,</li>\n<li>removes the follows and the notes whose accounts are no longer cached, walking both tables 200 rows at a time, and prints how many it removed,</li>\n<li>runs the four checks that Administration → Overview shows (<code>lib/SetupChecks/</code>) and prints each with its severity: whether <code>.well-known/webfinger</code> answers for an account of this instance, whether the address Aloha Social builds ids from still matches the one the server reports, whether the delivery job has run lately, and whether anything in the outbound queue is stuck. A check that fails links to <a href=\"/docs/admin\">Admin.md</a>,</li>\n<li>prints a verdict line — <code>all N checks passed</code>, or <code>M of N checks reported an error</code> — and <strong>exits 1</strong> when any check reported an error, so the command can stand in a deployment script</li>\n<li>prints the current app configuration as pretty JSON.</li>\n</ul>\n<p>The command exits <code>1</code> when any of those four reports an error, so a deployment\nscript can run it. <code>--offline</code> leaves out the WebFinger probe for a machine with\nno route out; the other three read only the database and the configuration.</p>\n<p>With <code>--index</code> the checks are skipped entirely. The command warns that the operation\ntakes a while, asks <code>Do you confirm this operation? (y/N)</code>, and on confirmation\nempties <code>stream_dest</code> and <code>stream_tags</code> and rebuilds both from <code>social_stream</code>, a\nfew hundred rows at a time, with a progress bar. Answering anything but <code>y</code> exits\nwithout changes; under <code>--no-interaction</code> it refuses unless <code>--force</code> is given\n(exit code <code>1</code>), because the index tables are truncated before the rebuild starts\nand a run that stops there leaves every timeline empty.</p>\n<p>Rows it cannot parse are reported at the end (the first ten in full, then a count)\nand make the command exit <code>1</code>; the rest of the index is still rebuilt.</p>\n<hr>\n<h2 id=\"social-reset\"><code>social:reset</code></h2>\n<p>Delete all Aloha Social data, or uninstall the app&#39;s database footprint.</p>\n<pre><code>php occ social:reset [--uninstall] [--uri ADDRESS] [-f|--force]\n</code></pre>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Option</th>\n<th>Value</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>--uninstall</code></td>\n<td>none</td>\n<td>Full removal instead of a data flush</td>\n</tr>\n<tr>\n<td><code>--uri</code></td>\n<td>address</td>\n<td>The cloud base address to rebuild every id from, instead of being asked for it. This is the option <code>social:check:install</code> names when the configured address no longer matches the server. After the flush <code>social_url</code>, the base ids are minted from, is derived from the cloud address again, with or without this option</td>\n</tr>\n<tr>\n<td><code>-f</code>, <code>--force</code></td>\n<td>none</td>\n<td>Skip both confirmations (required with <code>--no-interaction</code>)</td>\n</tr>\n</tbody></table></div>\n<p>The command asks <strong>two</strong> confirmations before doing anything:</p>\n<ol>\n<li><code>Do you confirm this operation? (y/N)</code></li>\n<li><code>Operation is destructive. Are you sure about this? (y/N)</code></li>\n</ol>\n<p>Answering anything but <code>y</code> to either question aborts with exit code <code>0</code> and changes\nnothing. Under <code>--no-interaction</code> the command refuses with exit code <code>1</code> unless\n<code>--force</code> is given: a confirmation prompt answers itself with its default when\nnobody is there, so without this the command would exit <code>0</code> having done nothing.</p>\n<p>It refuses with exit code <code>1</code>, before asking anything, while self-registered\nexternal users exist: their logins are rows of this app, and flushing them\nwould leave Nextcloud users nobody can log in as. Delete them, or promote them\nwith <code>social:external promote</code>, first.</p>\n<p>Without <code>--uninstall</code>:</p>\n<ul>\n<li>empties every Aloha Social table (<code>CoreRequestBuilder::emptyAll()</code>),</li>\n<li>re-runs <code>checkInstallationStatus(true)</code>,</li>\n<li>sets the cloud base address to <code>--uri</code>, or, with somebody at the keyboard and no\n<code>--uri</code>, offers to change it, pre-filled with the current one; entering the same\nvalue leaves it unchanged. Non-interactively and without <code>--uri</code> the address is\nleft as it was.</li>\n</ul>\n<p>With <code>--uninstall</code>:</p>\n<ul>\n<li>drops the Aloha Social tables,</li>\n<li>removes the app&#39;s rows from the migrations table,</li>\n<li>removes the app&#39;s background jobs,</li>\n<li>unsets the app configuration.</li>\n</ul>\n<p>The app files themselves are not removed, and the app is not disabled.</p>\n<hr>\n","toc":[{"id":"social-check-install","text":"social:check:install","level":2},{"id":"social-reset","text":"social:reset","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"installation-and-maintenance","manual":false,"prev":{"path":"/docs/occ-external-users","title":"External Users"},"next":{"path":"/docs/occ-exit-codes","title":"Exit Codes"},"parent":null},{"slug":"occ-exit-codes","path":"/docs/occ-exit-codes","title":"Exit Codes","description":"Every command the app adds to occ, grouped by the task it performs.","group":"occ","html":"<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Code</th>\n<th>Meaning</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>0</td>\n<td>Success, and also a confirmation prompt answered with &quot;no&quot;</td>\n</tr>\n<tr>\n<td>1</td>\n<td>A refusal to act non-interactively without <code>--force</code> (<code>social:reset</code>, <code>social:check:install --index</code>, <code>social:benchmark</code>, <code>social:queue:retry</code>), a <code>social:benchmark</code> probe over its limit or an invalid limit option, a failed flush or uninstall in <code>social:reset</code>, <code>social:reset</code> while external users exist, streams <code>social:check:install --index</code> could not parse, a setup check that <code>social:check:install</code> reports as an error, <code>social:account:following</code> handled failure, or an uncaught exception in any command</td>\n</tr>\n</tbody></table></div>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"exit-codes","manual":false,"prev":{"path":"/docs/occ-installation-and-maintenance","title":"Installation & Maintenance"},"next":{"path":"/docs/occ-background-jobs","title":"Background Jobs"},"parent":null},{"slug":"occ-background-jobs","path":"/docs/occ-background-jobs","title":"Background Jobs","description":"Every 12 minutes, with a 300-second budget. Same steps as social:cache:refresh (deleted actors, local actor cache, remote actors and their details, documents, hashtags), and additionally…","group":"occ","html":"<p>The <code>TimedJob</code>s below are among those registered in <code>&lt;background-jobs&gt;</code> in\n<code>appinfo/info.xml</code> (that list is the complete one), run by Nextcloud&#39;s cron;\nthe last four are queued on demand instead:</p>\n<h2 id=\"cache-maintenance\">Cache maintenance</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\Cache</code></p>\n<p>Every 12 minutes, with a 300-second budget. Same steps as <code>social:cache:refresh</code> (deleted actors, local actor cache, remote actors and their details, documents, hashtags), and additionally closes polls, prunes remote statuses past retention, evicts cached remote accounts nobody here refers to, syncs the timelines of the cached remote actors somebody here follows, verifies profile links, reconciles group lists, finds out which servers the Discover page may ask and deletes the expired rows of the durable cache. A run that spends its budget logs which steps it skipped, and the next run starts with the first of them, so the steps at the end of the list are not the ones that never run. No key rotation is performed.</p>\n<h2 id=\"queue-processing\">Queue processing</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\Queue</code></p>\n<p>Every 12 minutes. Processes the outbound request queue <strong>and</strong> the stream queue, like <code>social:queue:process</code>.</p>\n<h2 id=\"expired-stories\">Expired stories</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\ExpiredStories</code></p>\n<p>Hourly. Deletes the stories whose day is up, at most 500 per run. The second of the two guards on a story&#39;s expiry: every read already filters on <code>expires_at</code>, so an instance whose cron has stopped shows nothing it should not — but without this the rows and their pictures would pile up for ever, and &quot;it disappears after a day&quot; would be true of what people can see and false of what is stored.</p>\n<h2 id=\"scheduled-posts\">Scheduled posts</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\ScheduledPosts</code></p>\n<p>Every 5 minutes. Publishes the posts whose <code>scheduled_at</code> has passed, at most 50 per run. Shorter than the other two on purpose: a scheduled post may be published up to one cron period late, and a longer period would promise a precision the five-minute minimum on <code>scheduled_at</code> implies but the app could not keep.</p>\n<h2 id=\"block-lists\">Block lists</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\BlocklistSync</code></p>\n<p>Daily. Re-reads the block lists an administrator follows and applies what they say; does nothing while no source is on.</p>\n<h2 id=\"external-registrations\">External registrations</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\ExternalSignups</code></p>\n<p>Hourly. Forgets registrations of external users whose email was not confirmed within a day, and invitations that expired or were used up. A registration waiting for an administrator is kept until somebody decides on it.</p>\n<h2 id=\"bluesky-sync\">Bluesky sync</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\AtprotoSync</code></p>\n<p>Every 2 minutes, only while Bluesky is on. Reads the feeds of the Bluesky authors somebody here follows — the newest page of each due watch from the public AppView, what is new stored, the next read soon after a page with posts and doubling up to six hours after empty ones — then the AppView&#39;s notifications of each due local account, asked for as that account; both passes stop at the instance&#39;s request ceiling (<code>atproto_sync_ceiling</code>).</p>\n<h2 id=\"bluesky-maintenance\">Bluesky maintenance</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\AtprotoMaintenance</code></p>\n<p>Every 5 minutes, only while Bluesky is on. Requests the initial relay crawl and recrawls after a firehose outage exceeds the 72-hour replay window. It also retries every six hours when relay/AppView checks still cannot find an active repository after an hour; failed initial requests retry after 15 minutes. Reconciles the last day&#39;s public posts with their Bluesky records — a post the listener missed is published, an edit within the grace period replaced, a deleted post&#39;s record removed; each run looks at the newest 100 and the next 100 of the rest of the day, so a busy day is covered over a few runs — resends directory operations the PLC refused, prunes the firehose past its replay window, drops retired instance keys, checks a page of 25 Bluesky posts read here in the last week against the AppView, deleting the ones it no longer has, checks custom handles once a day (dropping one that failed a week in a row), and picks up account moves whose job stopped (queued again once after an hour without progress, then failed with <code>move-interrupted</code>).</p>\n<h2 id=\"bluesky-video\">Bluesky video</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\AtprotoVideo</code></p>\n<p>Every minute, only while Bluesky is on and <code>atproto_video_service</code> is set. Sends up to three queued videos of posts published here to Bluesky&#39;s video service, asks after the jobs it is making, and publishes each post whose video has ended: with the video when the service stored it here, otherwise as text and a link to the post here.</p>\n<h2 id=\"domain-purge\">Domain purge</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\DomainPurge</code></p>\n<p>Queued with a domain when one is added to the deny list — not registered in <code>appinfo/info.xml</code>, because a job listed there is added once at install time with no argument. Does 10 batches of 50 accounts per run and re-queues itself while anything of the domain is left.</p>\n<h2 id=\"external-promotion\">External promotion</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\ExternalPromoted</code></p>\n<p>Queued with a user id when an external user is promoted to a local one — not in <code>appinfo/info.xml</code>, for the same reason as the domain purge. Writes the user&#39;s system address book card, which external users do not have, in a request that sees them on their new backend.</p>\n<h2 id=\"bluesky-publish\">Bluesky publish</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\AtprotoPublish</code></p>\n<p>Queued by the post listener with a post id and an action (publish, edit, delete) or by the account service for a profile — not in <code>appinfo/info.xml</code>, for the same reason. Does the work off the request that made the post. A failure that may pass is tried again later, up to eight attempts over about 80 minutes, and the last is logged as given up; the maintenance job catches the posts a job that failed or was never queued left behind.</p>\n<h2 id=\"bluesky-move\">Bluesky move</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\AtprotoMove</code></p>\n<p>Queued when a person starts moving their Bluesky account away — not in <code>appinfo/info.xml</code>, for the same reason. Copies the repository, the blobs and the preferences to the other PDS, points the DID there, activates the account there and switches it off here; stops at a step that fails, which the person can start again.</p>\n<h2 id=\"actor-cleanup\">Actor cleanup</h2>\n<p><strong>Class: </strong><code>OCA\\Social\\Cron\\ActorCleanup</code></p>\n<p>Queued with an actor id when a deleted account is addressed by more posts than one inbox request should rewrite — not in <code>appinfo/info.xml</code>, for the same reason as the domain purge. Rewrites 2000 posts per run and re-queues itself while any remain. Without it, the rewrite ran inline in the request a peer was waiting on for its <code>Delete</code>, so the peer timed out, re-sent, and the work started over.</p>\n","toc":[{"id":"cache-maintenance","text":"Cache maintenance","level":2},{"id":"queue-processing","text":"Queue processing","level":2},{"id":"expired-stories","text":"Expired stories","level":2},{"id":"scheduled-posts","text":"Scheduled posts","level":2},{"id":"block-lists","text":"Block lists","level":2},{"id":"external-registrations","text":"External registrations","level":2},{"id":"bluesky-sync","text":"Bluesky sync","level":2},{"id":"bluesky-maintenance","text":"Bluesky maintenance","level":2},{"id":"bluesky-video","text":"Bluesky video","level":2},{"id":"domain-purge","text":"Domain purge","level":2},{"id":"external-promotion","text":"External promotion","level":2},{"id":"bluesky-publish","text":"Bluesky publish","level":2},{"id":"bluesky-move","text":"Bluesky move","level":2},{"id":"actor-cleanup","text":"Actor cleanup","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/OCC-Commands.md","sections":null,"anchor":"background-jobs","manual":false,"prev":{"path":"/docs/occ-exit-codes","title":"Exit Codes"},"next":null,"parent":null},{"slug":"mastodon","path":"/docs/mastodon","title":"Mastodon client and federation compatibility","description":"Aloha Social implements a broad portion of the Mastodon client API and speaks ActivityPub to Mastodon and other Fediverse servers. It is not a drop-in Mastodon server. This page summarizes…","group":"mastodon","html":"<p><strong>Reviewed against:</strong> Aloha Social <strong>0.26.279</strong> on <strong>2026-10-27</strong>.</p>\n<p>Aloha Social implements a broad portion of the Mastodon client API and speaks\nActivityPub to Mastodon and other Fediverse servers. It is <strong>not a drop-in\nMastodon server</strong>. This page summarizes the practical compatibility boundary;\nthe route-by-route reference is <a href=\"/docs/api\">API.md</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Mastodon-Compatibility.md","sections":[{"path":"/docs/mastodon-mastodon-clients","title":"Mastodon clients","description":"The client API supports common account and profile operations, timelines, publishing, media uploads, replies, polls, likes, boosts, notifications, lists, search, moderation and OAuth. An…","parent":false},{"path":"/docs/mastodon-activitypub-federation","title":"ActivityPub federation","description":"Mastodon peers communicate with Aloha Social through signed ActivityPub activities and WebFinger actor discovery. Supported posts, visibility, interactions, media, polls, edits and…","parent":false},{"path":"/docs/mastodon-moving-accounts","title":"Moving accounts","description":"The Fediverse account-move protocol is supported where the source and target servers support ActivityPub Move and alsoKnownAs. A move redirects the follow relationship; it does not…","parent":false},{"path":"/docs/mastodon-pixelfed-and-other-servers","title":"Pixelfed and other servers","description":"Pixelfed, PeerTube, GoToSocial, Akkoma and other implementations share ActivityPub but have different client APIs and extensions. Aloha Social supports interoperability for common posts…","parent":false},{"path":"/docs/mastodon-verification","title":"Verification","description":"Unit and integration tests validate local behavior. The optional tests/Interop/ suite exercises real Mastodon and PeerTube instances when configured; a skipped test is not evidence of a…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/mastodon-mastodon-clients","title":"Mastodon clients"},"parent":null},{"slug":"mastodon-mastodon-clients","path":"/docs/mastodon-mastodon-clients","title":"Mastodon clients","description":"The client API supports common account and profile operations, timelines, publishing, media uploads, replies, polls, likes, boosts, notifications, lists, search, moderation and OAuth. An…","group":"mastodon","html":"<p>The client API supports common account and profile operations, timelines,\npublishing, media uploads, replies, polls, likes, boosts, notifications, lists,\nsearch, moderation and OAuth. An optional streaming daemon serves supported\nWebSocket and SSE streams. Consult the API tables for exact methods, scopes,\nrequest shapes and any endpoint that is partial or unavailable.</p>\n<p>Most Mastodon clients assume the API is at the domain root:</p>\n<ul>\n<li><code>/api/...</code> must reach Social&#39;s client API;</li>\n<li><code>/oauth/...</code> must reach Social&#39;s OAuth endpoints;</li>\n<li><code>/xrpc/...</code> must reach the Bluesky service when that integration is enabled.</li>\n</ul>\n<p>The app is mounted inside Nextcloud, so a web-server rule is required for those\nroot paths. The Apache/nginx examples and setup check are in\n<a href=\"https://github.com/AlohaSocial/social/blob/master/contrib/webserver/\"><code>contrib/webserver/</code></a> and\n<a href=\"/docs/admin-mastodon-apps-cannot-connect#mastodon-apps-cannot-connect\">Admin.md — Mastodon apps cannot connect</a>.\nBrowser-based clients also depend on the documented CORS behavior.</p>\n<h2 id=\"streaming\">Streaming</h2>\n<p>Streaming is optional and separate from ordinary REST requests. The\nadministrator must run <code>occ social:mastodon:stream</code> as a managed service and\nproxy the streaming route as a WebSocket where applicable. Supported WebSocket\nand SSE streams, health checks and authorization are documented in <a href=\"/docs/api\">API.md —\nStreaming</a>. If the daemon or proxy is unavailable, clients\nshould use REST polling; a successful REST request does not prove that the\nstream is connected.</p>\n<p>Mastodon Web Push subscription endpoints are part of the API, but delivery also\ndepends on client subscription, VAPID configuration, outbound connectivity and\nthe push provider. Nextcloud&#39;s own notification channel is a separate feature.</p>\n<h2 id=\"intentional-differences\">Intentional differences</h2>\n<ul>\n<li>Registration and core account credentials belong to Nextcloud. Social does\nnot replace Mastodon&#39;s full sign-up, email or password-management system.</li>\n<li>Mastodon-specific endpoints may be absent or return a documented partial\nresult. <code>API.md</code> is the source of truth for the current route surface; a\nroute being registered does not guarantee identical Mastodon semantics.</li>\n<li>Some Aloha features have no Mastodon equivalent, and some Mastodon client\nfeatures have no Aloha web interface.</li>\n<li>Public client API compatibility does not imply that Aloha can take over an\nexisting Mastodon server&#39;s actor IDs, keys, host domain or followers in place.</li>\n</ul>\n","toc":[{"id":"streaming","text":"Streaming","level":2},{"id":"intentional-differences","text":"Intentional differences","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Mastodon-Compatibility.md","sections":null,"anchor":"mastodon-clients","manual":false,"prev":{"path":"/docs/mastodon","title":"Mastodon client and federation compatibility"},"next":{"path":"/docs/mastodon-activitypub-federation","title":"ActivityPub federation"},"parent":null},{"slug":"mastodon-activitypub-federation","path":"/docs/mastodon-activitypub-federation","title":"ActivityPub federation","description":"Mastodon peers communicate with Aloha Social through signed ActivityPub activities and WebFinger actor discovery. Supported posts, visibility, interactions, media, polls, edits and…","group":"mastodon","html":"<p>Mastodon peers communicate with Aloha Social through signed ActivityPub\nactivities and WebFinger actor discovery. Supported posts, visibility,\ninteractions, media, polls, edits and deletions are handled by the shared\nActivityPub implementation, not by a Mastodon-only transport. See\n<a href=\"/docs/federation\">Federation-Compatibility.md</a> for outbox imports,\nobject types and remaining remote-profile boundaries.</p>\n<p>Federation is asynchronous. A post accepted locally may still be waiting in\nNextcloud&#39;s delivery queue, refused by the remote server, or not displayed by a\nparticular Mastodon view. Check the delivery queue and the remote server&#39;s\nresponse before describing a delivery as accepted. See\n<a href=\"/docs/admin-deliveries-are-stuck#deliveries-are-stuck\">Admin.md — delivery troubleshooting</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Mastodon-Compatibility.md","sections":null,"anchor":"activitypub-federation","manual":false,"prev":{"path":"/docs/mastodon-mastodon-clients","title":"Mastodon clients"},"next":{"path":"/docs/mastodon-moving-accounts","title":"Moving accounts"},"parent":null},{"slug":"mastodon-moving-accounts","path":"/docs/mastodon-moving-accounts","title":"Moving accounts","description":"The Fediverse account-move protocol is supported where the source and target servers support ActivityPub Move and alsoKnownAs. A move redirects the follow relationship; it does not…","group":"mastodon","html":"<p>The Fediverse account-move protocol is supported where the source and target\nservers support ActivityPub <code>Move</code> and <code>alsoKnownAs</code>. A move redirects the\nfollow relationship; it does not transfer the old server&#39;s database, keys,\npost identifiers or full archive. Aloha Social&#39;s export/import tools can bring\nsupported account data and media into a local account, but imported posts use\nlocal identifiers. See <a href=\"/docs/moving\">Moving.md</a>.</p>\n<p>Replacing an existing Mastodon instance while keeping its domain, actor URLs,\nkeys and post IDs is a different migration problem and is not supported by a\nnormal account move. Aloha Social&#39;s ActivityPub identities are minted under\nits own URL space. Do not change the configured public URL after identities\nhave been federated; see <a href=\"/docs/admin-the-address-aloha-social-is-set-up-for#the-address-aloha-social-is-set-up-for\">Admin.md</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Mastodon-Compatibility.md","sections":null,"anchor":"moving-accounts","manual":false,"prev":{"path":"/docs/mastodon-activitypub-federation","title":"ActivityPub federation"},"next":{"path":"/docs/mastodon-pixelfed-and-other-servers","title":"Pixelfed and other servers"},"parent":null},{"slug":"mastodon-pixelfed-and-other-servers","path":"/docs/mastodon-pixelfed-and-other-servers","title":"Pixelfed and other servers","description":"Pixelfed, PeerTube, GoToSocial, Akkoma and other implementations share ActivityPub but have different client APIs and extensions. Aloha Social supports interoperability for common posts…","group":"mastodon","html":"<p>Pixelfed, PeerTube, GoToSocial, Akkoma and other implementations share\nActivityPub but have different client APIs and extensions. Aloha Social\nsupports interoperability for common posts and interactions; it does not\nimplement each product&#39;s entire server API. For concrete behavior, see the\n<a href=\"/docs/integrations\">integration matrix</a> and\n<a href=\"/docs/federation\">remote profile compatibility</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Mastodon-Compatibility.md","sections":null,"anchor":"pixelfed-and-other-servers","manual":false,"prev":{"path":"/docs/mastodon-moving-accounts","title":"Moving accounts"},"next":{"path":"/docs/mastodon-verification","title":"Verification"},"parent":null},{"slug":"mastodon-verification","path":"/docs/mastodon-verification","title":"Verification","description":"Unit and integration tests validate local behavior. The optional tests/Interop/ suite exercises real Mastodon and PeerTube instances when configured; a skipped test is not evidence of a…","group":"mastodon","html":"<p>Unit and integration tests validate local behavior. The optional\n<a href=\"https://github.com/AlohaSocial/social/blob/master/tests/Interop/\"><code>tests/Interop/</code></a> suite exercises real Mastodon and\nPeerTube instances when configured; a skipped test is not evidence of a live\nexchange. For production issues, record the remote host, activity or request,\ndelivery state, response status and relevant time before deciding whether the\nproblem is local or remote.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Mastodon-Compatibility.md","sections":null,"anchor":"verification","manual":false,"prev":{"path":"/docs/mastodon-pixelfed-and-other-servers","title":"Pixelfed and other servers"},"next":null,"parent":null},{"slug":"atproto","path":"/docs/atproto","title":"Bluesky and AT Protocol compatibility","description":"Current scope: native AT Protocol hosting is an optional integration in Aloha Social. It runs alongside ActivityPub; it does not convert a Fediverse account into a Bluesky identity or use…","group":"atproto","html":"<p><strong>Reviewed against:</strong> Aloha Social <strong>0.26.279</strong> on <strong>2026-10-27</strong>.</p>\n<p><strong>Current scope:</strong> native AT Protocol hosting is an optional integration in\nAloha Social. It runs alongside ActivityPub; it does not convert a Fediverse\naccount into a Bluesky identity or use an existing Bluesky account as the local\nPDS identity. Service availability and AppView indexing remain external.</p>\n<p>For shared remote ActivityPub profile behavior, see\n<a href=\"/docs/federation\">Federation-Compatibility.md</a>. For operator setup,\nsee <a href=\"/docs/admin-bluesky#bluesky\">Admin.md — Bluesky</a>; for endpoint details, see\n<a href=\"/docs/api\">API.md — Bluesky/AT Protocol</a>. The real-network\nchecklist is <a href=\"/docs/atproto-live\">Atproto-Live-Test.md</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Compatibility.md","sections":[{"path":"/docs/atproto-supported-capabilities","title":"Supported capabilities","description":"Implemented behavior: Local accounts can have a did:plc; assigned and verified custom handles are resolved; profiles and ordered profile links are served","parent":false},{"path":"/docs/atproto-how-posting-works","title":"How posting works","description":"Public local posts can be published to the ActivityPub network and the native AT Protocol repository as separate writes. Each side has its own identity, records, delivery, deletion and…","parent":false},{"path":"/docs/atproto-deliberate-limits","title":"Deliberate limits","description":"Optional native AT Protocol hosting alongside ActivityPub, including supported records, setup and operational boundaries.","parent":false},{"path":"/docs/atproto-operations-and-verification","title":"Operations and verification","description":"The administrator must configure the PDS host and public endpoints, PLC access, relay/firehose service and the AppView/Chat destinations. The root /xrpc/ route must reach Social through…","parent":false},{"path":"/docs/atproto-account-recovery-phrase","title":"Account recovery phrase","description":"The account settings can create a twelve-word recovery phrase after password confirmation. It is shown once; creating a replacement rotates the recovery key, so store the new phrase…","parent":false},{"path":"/docs/atproto-runtime-configuration-keys","title":"Runtime configuration keys","description":"These persisted keys identify the primary AT Protocol controls and the Jetstream listener state. Configure service endpoints and enablement through the Bluesky administration card where…","parent":false},{"path":"/docs/atproto-protocol-references","title":"Protocol references","description":"Optional native AT Protocol hosting alongside ActivityPub, including supported records, setup and operational boundaries.","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/atproto-supported-capabilities","title":"Supported capabilities"},"parent":null},{"slug":"atproto-supported-capabilities","path":"/docs/atproto-supported-capabilities","title":"Supported capabilities","description":"Implemented behavior: Local accounts can have a did:plc; assigned and verified custom handles are resolved; profiles and ordered profile links are served","group":"atproto","html":"<h2 id=\"identity\">Identity</h2>\n<p><strong>Implemented behavior: </strong>Local accounts can have a <code>did:plc</code>; assigned and verified custom handles are resolved; profiles and ordered profile links are served</p>\n<p>PLC directory and DNS/HTTPS handle proofs must be reachable and valid. ActivityPub identity remains separate.</p>\n<h2 id=\"repository\">Repository</h2>\n<p><strong>Implemented behavior: </strong>Signed local repositories, commits, records and blobs; repository export/import and account moves</p>\n<p>Writes are deliberately allow-listed; this is not arbitrary storage for every AT Protocol Lexicon.</p>\n<h2 id=\"posts\">Posts</h2>\n<p><strong>Implemented behavior: </strong>Public posts, replies, embeds, images/galleries, video, self-labels, edits, deletes and supported reply/quote rules</p>\n<p>The social model and publication pipeline define supported post records. Long text or unsupported embeds may be mapped or refused; inspect the specific write path.</p>\n<h2 id=\"other-records\">Other records</h2>\n<p><strong>Implemented behavior: </strong>Supported profile links, lists and list items, starter packs, feed records, thread gates and post gates can be retained or processed</p>\n<p>Keeping a record does not mean Aloha provides a native editor or operates the referenced feed generator.</p>\n<h2 id=\"client-authentication\">Client authentication</h2>\n<p><strong>Implemented behavior: </strong>PDS sessions, app passwords and OAuth are available for supported clients and permissions</p>\n<p>OAuth scopes and permission sets are checked. General Nextcloud account password/email administration is not delegated to XRPC.</p>\n<h2 id=\"xrpc\">XRPC</h2>\n<p><strong>Implemented behavior: </strong>PDS methods are handled locally; supported <code>app.bsky.*</code> and <code>chat.bsky.*</code> methods not hosted locally are proxied to configured services</p>\n<p>Proxying depends on AppView/Chat service authentication and availability. A successful response does not prove feed indexing.</p>\n<h2 id=\"reading\">Reading</h2>\n<p><strong>Implemented behavior: </strong>Profiles, author feeds, threads, custom feeds, lists, starter packs, search/discovery and interactions are available through supported local and proxied paths</p>\n<p>AppView results can lag behind the PDS or omit content according to its policies.</p>\n<h2 id=\"synchronization\">Synchronization</h2>\n<p><strong>Implemented behavior: </strong>Relay firehose, background polling and optional Jetstream listening can ingest remote activity</p>\n<p>Cron, relay configuration and optional daemons must be running. A stopped or delayed source can leave the local view stale.</p>\n<h2 id=\"chat-and-notifications\">Chat and notifications</h2>\n<p><strong>Implemented behavior: </strong>Supported Bluesky chat methods are proxied; local conversation and notification state is synchronized where implemented</p>\n<p>Chat service is separate from the PDS and requires its own service-auth configuration. Verify live behavior with the checklist.</p>\n<h2 id=\"moderation\">Moderation</h2>\n<p><strong>Implemented behavior: </strong>Supported labels, blocks/mutes, reports and moderation-list behavior are integrated with local controls</p>\n<p>Labeler and AppView decisions remain external; not every moderation method has a local UI.</p>\n<h2 id=\"account-migration\">Account migration</h2>\n<p><strong>Implemented behavior: </strong>Supported flows can bring an account and repository here or move one away, including supported Bridgy Fed twins</p>\n<p>Migration is a multi-step protocol operation. Follow the UI/commands and keep backups; it is not a generic identity takeover.</p>\n","toc":[{"id":"identity","text":"Identity","level":2},{"id":"repository","text":"Repository","level":2},{"id":"posts","text":"Posts","level":2},{"id":"other-records","text":"Other records","level":2},{"id":"client-authentication","text":"Client authentication","level":2},{"id":"xrpc","text":"XRPC","level":2},{"id":"reading","text":"Reading","level":2},{"id":"synchronization","text":"Synchronization","level":2},{"id":"chat-and-notifications","text":"Chat and notifications","level":2},{"id":"moderation","text":"Moderation","level":2},{"id":"account-migration","text":"Account migration","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Compatibility.md","sections":null,"anchor":"supported-capabilities","manual":false,"prev":{"path":"/docs/atproto","title":"Bluesky and AT Protocol compatibility"},"next":{"path":"/docs/atproto-how-posting-works","title":"How posting works"},"parent":null},{"slug":"atproto-how-posting-works","path":"/docs/atproto-how-posting-works","title":"How posting works","description":"Public local posts can be published to the ActivityPub network and the native AT Protocol repository as separate writes. Each side has its own identity, records, delivery, deletion and…","group":"atproto","html":"<p>Public local posts can be published to the ActivityPub network and the native\nAT Protocol repository as separate writes. Each side has its own identity,\nrecords, delivery, deletion and indexing behavior. ActivityPub visibility\nchoices that are not public are not published as public Bluesky posts.</p>\n<p>Bluesky clients can write through <code>com.atproto.repo.createRecord</code>,\n<code>putRecord</code>, <code>deleteRecord</code> and <code>applyWrites</code> for supported collections.\nConditional writes are checked against the repository under its write lock.\nPost updates preserve the record URI where supported. External link embeds,\nrecord embeds, combined media and supported profile-link records are mapped\nexplicitly; unsupported record types are not accepted as if they were valid\nsocial posts. The supported collection and embed handling is defined in\n<code>lib/Atproto/Client/WriteService.php</code> and\n<code>lib/Atproto/Publisher/RecordMapper.php</code>.</p>\n<p>The AT Protocol does not make an uploaded post instantly visible in every\nBluesky surface. The sequence is: PDS commit, relay crawl, AppView indexing,\nthen client refresh. A relay&#39;s acceptance or a local XRPC success only proves\nthe earlier step. Use the live checklist to distinguish those states.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Compatibility.md","sections":null,"anchor":"how-posting-works","manual":false,"prev":{"path":"/docs/atproto-supported-capabilities","title":"Supported capabilities"},"next":{"path":"/docs/atproto-deliberate-limits","title":"Deliberate limits"},"parent":null},{"slug":"atproto-deliberate-limits","path":"/docs/atproto-deliberate-limits","title":"Deliberate limits","description":"Optional native AT Protocol hosting alongside ActivityPub, including supported records, setup and operational boundaries.","group":"atproto","html":"<ul>\n<li>Aloha Social does not accept arbitrary Lexicon records for arbitrary apps.\nIt stores a defined set of social records and proxies selected service APIs.</li>\n<li>Native Bluesky draft synchronization, arbitrary application data storage,\nLive Now profile controls, full starter-pack editing, and a hosted custom-feed\ngenerator are not represented as complete features here.</li>\n<li>Bluesky account activation/deactivation, deletion, email and password\nmanagement are not a replacement for Nextcloud account administration.</li>\n<li>A Bluesky app can use supported APIs while a local web feature is absent; API\nproxy availability and a first-party user interface are different capabilities.</li>\n<li>A public profile or post can be fetched locally while it is still absent from\nan AppView or search index. This is an indexing/availability distinction, not\nproof that an XRPC route is missing.</li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Compatibility.md","sections":null,"anchor":"deliberate-limits","manual":false,"prev":{"path":"/docs/atproto-how-posting-works","title":"How posting works"},"next":{"path":"/docs/atproto-operations-and-verification","title":"Operations and verification"},"parent":null},{"slug":"atproto-operations-and-verification","path":"/docs/atproto-operations-and-verification","title":"Operations and verification","description":"The administrator must configure the PDS host and public endpoints, PLC access, relay/firehose service and the AppView/Chat destinations. The root /xrpc/ route must reach Social through…","group":"atproto","html":"<p>The administrator must configure the PDS host and public endpoints, PLC access,\nrelay/firehose service and the AppView/Chat destinations. The root <code>/xrpc/</code>\nroute must reach Social through the web-server configuration shipped in\n<code>contrib/webserver/</code>. Configure system cron for background work; optionally run\n<code>occ social:atproto:serve</code> for the firehose and <code>occ social:atproto:listen</code> for\nJetstream. The exact setup checks and service requirements are in\n<a href=\"/docs/admin-bluesky#bluesky\">Admin.md</a> and <a href=\"/docs/occ\">OCC-Commands.md</a>.</p>\n<p>The codebase includes unit, integration and protocol interoperability tests.\nThese do not establish live public relay/AppView indexing. For a production-like\ncheck, use <a href=\"/docs/atproto-live\">Atproto-Live-Test.md</a> with test accounts and\nrecord which service acknowledged each step.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Compatibility.md","sections":null,"anchor":"operations-and-verification","manual":false,"prev":{"path":"/docs/atproto-deliberate-limits","title":"Deliberate limits"},"next":{"path":"/docs/atproto-account-recovery-phrase","title":"Account recovery phrase"},"parent":null},{"slug":"atproto-account-recovery-phrase","path":"/docs/atproto-account-recovery-phrase","title":"Account recovery phrase","description":"The account settings can create a twelve-word recovery phrase after password confirmation. It is shown once; creating a replacement rotates the recovery key, so store the new phrase…","group":"atproto","html":"<p>The account settings can create a twelve-word recovery phrase after password\nconfirmation. It is shown once; creating a replacement rotates the recovery\nkey, so store the new phrase safely. This key can sign supported PLC rotation\noperations, but the instance key still ranks above it while the account remains\nhosted here. Keep the phrase private and offline.</p>\n<p>The words encode 128 bits of entropy using the standard English BIP-39 word\nlist and checksum. The private key is the big-endian secp256k1 scalar derived\nas <code>SHA-256(&quot;social.atproto.recovery.v1&quot; || entropy)</code>. This is <strong>not</strong> the\nstandard BIP-39 PBKDF2 wallet derivation. The offline helper is\n<a href=\"https://github.com/AlohaSocial/social/blob/master/resources/atproto/recovery-key.py\"><code>resources/atproto/recovery-key.py</code></a>,\nwith the word list at\n<a href=\"https://github.com/AlohaSocial/social/blob/master/resources/atproto/bip39-english.txt\"><code>resources/atproto/bip39-english.txt</code></a>.</p>\n<p>Reference vector:</p>\n<ul>\n<li>Phrase: <code>abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about</code></li>\n<li>Secret key hex: <code>950f8acc1852f1a2562b2851457a04b1ba22541dd0f3b95ab9302d2894f29397</code></li>\n<li>Private-key multibase: <code>z3vLe2mABz9GSzoARHpVNW8P1rnySJ8rmfg3AKSpyVfHE526</code></li>\n<li>Public <code>did:key</code>: <code>did:key:zQ3shX448VC3xo912wY7zzdUFdMqGifmFTv9GomCodivqkgkt</code></li>\n</ul>\n<p>The code and offline helper are checked against this vector in\n<code>tests/Atproto/Identity/MnemonicTest.php</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Compatibility.md","sections":null,"anchor":"account-recovery-phrase","manual":false,"prev":{"path":"/docs/atproto-operations-and-verification","title":"Operations and verification"},"next":{"path":"/docs/atproto-runtime-configuration-keys","title":"Runtime configuration keys"},"parent":null},{"slug":"atproto-runtime-configuration-keys","path":"/docs/atproto-runtime-configuration-keys","title":"Runtime configuration keys","description":"These persisted keys identify the primary AT Protocol controls and the Jetstream listener state. Configure service endpoints and enablement through the Bluesky administration card where…","group":"atproto","html":"<p>These persisted keys identify the primary AT Protocol controls and the\nJetstream listener state. Configure service endpoints and enablement through\nthe Bluesky administration card where available; cursor and status keys are\nruntime bookkeeping and should not be edited manually.</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Purpose</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>atproto_enabled</code></td>\n<td>Enables or disables native AT Protocol hosting.</td>\n</tr>\n<tr>\n<td><code>atproto_relays</code></td>\n<td>Configured relay endpoints used for repository synchronization.</td>\n</tr>\n<tr>\n<td><code>atproto_plc_directory</code></td>\n<td>PLC directory endpoint used for DID operations.</td>\n</tr>\n<tr>\n<td><code>atproto_chat</code></td>\n<td>Configured Bluesky Chat service endpoint.</td>\n</tr>\n<tr>\n<td><code>atproto_jetstream</code></td>\n<td>Optional Jetstream source for remote repository events.</td>\n</tr>\n<tr>\n<td><code>atproto_jetstream_cursor</code></td>\n<td>Last consumed Jetstream cursor; internal listener state.</td>\n</tr>\n<tr>\n<td><code>atproto_jetstream_status</code></td>\n<td>Listener health/status state; internal bookkeeping.</td>\n</tr>\n</tbody></table></div>\n<p>Other <code>atproto_*</code> values may hold credentials, service DIDs, crawl cursors or\nbackfill progress. These are operational state, not general user preferences.\nSee <a href=\"/docs/admin-bluesky#bluesky\">Admin.md</a> for setup and secret-handling guidance.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Compatibility.md","sections":null,"anchor":"runtime-configuration-keys","manual":false,"prev":{"path":"/docs/atproto-account-recovery-phrase","title":"Account recovery phrase"},"next":{"path":"/docs/atproto-protocol-references","title":"Protocol references"},"parent":null},{"slug":"atproto-protocol-references","path":"/docs/atproto-protocol-references","title":"Protocol references","description":"Optional native AT Protocol hosting alongside ActivityPub, including supported records, setup and operational boundaries.","group":"atproto","html":"<ul>\n<li><a href=\"https://atproto.com/guides/overview\">AT Protocol documentation</a></li>\n<li><a href=\"https://atproto.com/specs/atp\">AT Protocol specifications</a></li>\n<li><a href=\"https://github.com/bluesky-social/atproto/tree/main/lexicons\">Bluesky lexicons</a></li>\n<li><a href=\"/docs/federation\">ActivityPub compatibility</a></li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Compatibility.md","sections":null,"anchor":"protocol-references","manual":false,"prev":{"path":"/docs/atproto-runtime-configuration-keys","title":"Runtime configuration keys"},"next":null,"parent":null},{"slug":"federation","path":"/docs/federation","title":"Remote profiles and content compatibility","description":"This inventory describes the implemented code paths, not a claim that every public server has been tested. ActivityPub and ATProto use their own identity, authentication and transport…","group":"federation","html":"<p>This inventory describes the implemented code paths, not a claim that every\npublic server has been tested. ActivityPub and ATProto use their own identity,\nauthentication and transport; they meet in Social&#39;s local profile and status API.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Federation-Compatibility.md","sections":[{"path":"/docs/federation-activitypub-profiles","title":"ActivityPub profiles","description":"Profiles are resolved through WebFinger and the actor document. The actor cache supports Person, Group, Service, Organization and Application actors. This covers people, community/channel…","parent":false},{"path":"/docs/federation-bluesky-client-writes","title":"Bluesky client writes","description":"The existing PDS surface already supports sessions, OAuth, repository writes, identity resolution, custom handles, blob uploads, preferences and AppView/Chat proxying. See ATProto…","parent":false},{"path":"/docs/federation-confirmed-remaining-gaps","title":"Confirmed remaining gaps","description":"These gaps are distinct from an implemented endpoint returning a remote-service error. PDS, AppView, Chat, ActivityPub delivery and background jobs require their own failure evidence when…","parent":false},{"path":"/docs/federation-post-detail-presentation","title":"Post detail presentation","description":"Author-only local view counts are text metadata on the post detail page, not an eye icon in the floating interaction menu. Background thread polls that still have no ancestors do not…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/federation-activitypub-profiles","title":"ActivityPub profiles"},"parent":null},{"slug":"federation-activitypub-profiles","path":"/docs/federation-activitypub-profiles","title":"ActivityPub profiles","description":"Profiles are resolved through WebFinger and the actor document. The actor cache supports Person, Group, Service, Organization and Application actors. This covers people, community/channel…","group":"federation","html":"<p>Profiles are resolved through WebFinger and the actor document. The actor cache\nsupports Person, Group, Service, Organization and Application actors. This covers\npeople, community/channel accounts and automated accounts without treating every\nprofile as a Mastodon user.</p>\n<p>Opening a remote profile while signed in queues a bounded outbox import. The API\nreturns cached posts immediately and reports a pending import through\n<code>X-Social-Remote-Profile-Filling</code>. The web timeline polls for up to five minutes;\nolder profile pages can resume the saved outbox continuation. The Nextcloud\nbackground jobs and media worker must run for these jobs to finish. Anonymous\nprofile reads serve the cache and do not start arbitrary remote imports.</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Outbox content</th>\n<th>Import behavior</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>Note</code>, including image posts</td>\n<td>Text, warning, language, tags, mentions, reply/quote metadata and attachment metadata use the inbox parser. Image bytes are cached separately.</td>\n</tr>\n<tr>\n<td><code>Question</code></td>\n<td>Poll choices, vote totals, multiple-choice mode and closing time are preserved.</td>\n</tr>\n<tr>\n<td><code>Article</code>, <code>Page</code></td>\n<td>Titles and link attachments are rendered using the same mapping as inbox deliveries, including community link posts.</td>\n</tr>\n<tr>\n<td><code>Audio</code>, <code>Video</code></td>\n<td>The supported object mapping is reused; PeerTube metadata and streamed sources remain available.</td>\n</tr>\n<tr>\n<td><code>Event</code></td>\n<td>Event facts are retained for the event card and Calendar import.</td>\n</tr>\n<tr>\n<td><code>Update</code></td>\n<td>Existing posts use the inbox handler&#39;s author and edit-time checks. An update of a post not cached yet can import its current object.</td>\n</tr>\n<tr>\n<td>URI-only entries and <code>Create.object</code> / <code>Update.object</code> references</td>\n<td>Same-origin objects are dereferenced with exact ID checks. Each background page has six reference requests with a three-second request timeout; exhaustion preserves the current entry in the continuation cursor.</td>\n</tr>\n<tr>\n<td><code>Announce</code></td>\n<td>The outbox owner and activity origin are checked. The regular boost handler stores the boost and queues the referenced post for fetching from its own origin; embedded foreign content is not trusted.</td>\n</tr>\n<tr>\n<td><code>Delete</code></td>\n<td>The outbox owner is checked before the normal idempotent deletion handler is called.</td>\n</tr>\n</tbody></table></div>\n<p>Collection <code>first</code> and <code>next</code> may be URI strings, reference objects, ActivityStreams\nLinks, or embedded pages. Relative continuations use the embedded page&#39;s own ID\nwhen it has one. Page links cannot change the outbox origin, carry credentials,\nor point back to the current page indefinitely.</p>\n<p>WebFinger advertises the existing remote-follow confirmation page using the\nFEP-3b86 <code>Follow</code> relation for both local users and the instance actor. Opening\nthe intent does not follow an account automatically; the person confirms the\naction in Social.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Federation-Compatibility.md","sections":null,"anchor":"activitypub-profiles","manual":false,"prev":{"path":"/docs/federation","title":"Remote profiles and content compatibility"},"next":{"path":"/docs/federation-bluesky-client-writes","title":"Bluesky client writes"},"parent":null},{"slug":"federation-bluesky-client-writes","path":"/docs/federation-bluesky-client-writes","title":"Bluesky client writes","description":"The existing PDS surface already supports sessions, OAuth, repository writes, identity resolution, custom handles, blob uploads, preferences and AppView/Chat proxying. See ATProto…","group":"federation","html":"<p>The existing PDS surface already supports sessions, OAuth, repository writes,\nidentity resolution, custom handles, blob uploads, preferences and AppView/Chat\nproxying. See <a href=\"/docs/atproto\">ATProto compatibility</a> and the\n<a href=\"/docs/api\">XRPC API</a> for their boundaries.</p>\n<p>Both <code>createRecord</code> and <code>putRecord</code> now import <code>app.bsky.embed.gallery</code> through\nthe same owned-upload path as images, including galleries beside a quoted record\nin <code>recordWithMedia</code>. Galleries accept up to ten images; the older images embed\naccepts four. Invalid or oversized lists are refused before upload descriptions\nare changed. An empty image/video alt text clears the previous description.</p>\n<h2 id=\"editing-reply-targets\">Editing reply targets</h2>\n<p><code>putRecord</code> can replace or remove a local post&#39;s <code>reply</code> reference. The update\nkeeps its AT URI and uses the existing repository batch, including conditional\n<code>swapRecord</code> / <code>swapCommit</code> checks. Social updates its parent columns, conversation,\nreply approval state, source snapshot and both parents&#39; reply counts. The new\nparent must be readable, permit replies and pass blocking and thread-gate checks.\nPublic posts cannot be moved under a non-public parent, and ancestor walks reject\ncycles or chains deeper than 64 posts. A missing parent is not silently accepted.\nThe published reference uses the mapped parent&#39;s current thread root; imported\nremote copies and third-party AppViews still need to process the update.</p>\n<h2 id=\"ordered-profile-links\">Ordered profile links</h2>\n<p><code>app.bsky.actor.link</code> records can be created, replaced and deleted through the\nordinary repository endpoints, including batches. A profile&#39;s <code>links</code> property\nselects up to ten strong references to link records in the same repository.\nReplacing the profile updates this selection; publishing a later bio/avatar edit\npreserves it. The links are stored independently of the four Mastodon profile\nfields, so a six-link Bluesky profile does not silently lose two links.</p>\n<p>The profile API exposes the selected links as <code>bluesky.links</code>, each with <code>url</code>\nand <code>title</code>, in display order. Remote AppView profile links use the same shape.\nThe profile page renders HTTPS destinations as direct links and omits hidden,\ntaken-down and unsafe destinations. Link icons are not fetched for this view.</p>\n","toc":[{"id":"editing-reply-targets","text":"Editing reply targets","level":2},{"id":"ordered-profile-links","text":"Ordered profile links","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Federation-Compatibility.md","sections":null,"anchor":"bluesky-client-writes","manual":false,"prev":{"path":"/docs/federation-activitypub-profiles","title":"ActivityPub profiles"},"next":{"path":"/docs/federation-confirmed-remaining-gaps","title":"Confirmed remaining gaps"},"parent":null},{"slug":"federation-confirmed-remaining-gaps","path":"/docs/federation-confirmed-remaining-gaps","title":"Confirmed remaining gaps","description":"These gaps are distinct from an implemented endpoint returning a remote-service error. PDS, AppView, Chat, ActivityPub delivery and background jobs require their own failure evidence when…","group":"federation","html":"<ul>\n<li>General XRPC account activation/deactivation, deletion, email and password\nmanagement are not all ordinary-session handlers. Migration has its own\nrestricted activation/status flow; Nextcloud owns the account credentials.</li>\n</ul>\n<p>These gaps are distinct from an implemented endpoint returning a remote-service\nerror. PDS, AppView, Chat, ActivityPub delivery and background jobs require their\nown failure evidence when diagnosing a live instance.</p>\n<p>Failed reference requests are isolated to their entry, so one unavailable post does not block the remaining page. A fresh profile refresh retries the first page; older failed references require revisiting their page. An HTTP success from the outbox is not proof that all referenced servers were reachable.</p>\n<p>Protocol references:\n<a href=\"https://www.w3.org/TR/activitypub/#outbox\">ActivityPub outboxes</a>,\n<a href=\"https://www.w3.org/TR/activitystreams-vocabulary/\">ActivityStreams vocabulary</a>,\n<a href=\"https://github.com/bluesky-social/atproto/discussions/5032\">Bluesky gallery design</a>,\n<a href=\"https://github.com/bluesky-social/atproto/blob/main/lexicons/app/bsky/embed/recordWithMedia.json\">record-with-media lexicon</a>.\nThe profile-link schema is vendored from the installed official ATProto SDK;\nsee also the <a href=\"https://github.com/bluesky-social/atproto/blob/a6f5a3c7f5e294e96971810d61f23b8f5998a5e2/lexicons/app/bsky/actor/link.json\">upstream link record</a>\nand <a href=\"https://fediverse.codeberg.page/fep/fep/3b86/\">FEP-3b86</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Federation-Compatibility.md","sections":null,"anchor":"confirmed-remaining-gaps","manual":false,"prev":{"path":"/docs/federation-bluesky-client-writes","title":"Bluesky client writes"},"next":{"path":"/docs/federation-post-detail-presentation","title":"Post detail presentation"},"parent":null},{"slug":"federation-post-detail-presentation","path":"/docs/federation-post-detail-presentation","title":"Post detail presentation","description":"Author-only local view counts are text metadata on the post detail page, not an eye icon in the floating interaction menu. Background thread polls that still have no ancestors do not…","group":"federation","html":"<p>Author-only local view counts are text metadata on the post detail page, not an\neye icon in the floating interaction menu. Background thread polls that still\nhave no ancestors do not recenter the page. The initial ancestor reveal avoids\nscrolling while an input is focused and respects reduced-motion preferences.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Federation-Compatibility.md","sections":null,"anchor":"post-detail-presentation","manual":false,"prev":{"path":"/docs/federation-confirmed-remaining-gaps","title":"Confirmed remaining gaps"},"next":null,"parent":null},{"slug":"integrations","path":"/docs/integrations","title":"Integrations and compatibility","description":"This page is the short, user-facing map of Aloha Social's integrations. It describes implemented paths and their practical boundaries; it is not a claim that every remote server or client…","group":"integrations","html":"<p>This page is the short, user-facing map of Aloha Social&#39;s integrations. It\ndescribes implemented paths and their practical boundaries; it is not a claim\nthat every remote server or client has been tested. Network availability,\nremote policy and server configuration still affect live behavior.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Integrations.md","sections":[{"path":"/docs/integrations-at-a-glance","title":"At a glance","description":"Status: Core · What Aloha Social can do: Host local identities; discover accounts; follow; publish, receive and read posts; reply, edit, delete, like and boost; process media, polls…","parent":false},{"path":"/docs/integrations-protocol-boundaries","title":"Protocol boundaries","description":"The Fediverse identity, inbox/outbox, delivery queue and remote actor model are ActivityPub. Remote profile reads can queue a bounded outbox import; cached posts are served while that work…","parent":false},{"path":"/docs/integrations-what-supported-means","title":"What “supported” means","description":"Use the API reference for exact routes and parameters. For implementation details, consult Architecture.md; for operator setup, use Admin.md. If a reported failure may be environmental…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/integrations-at-a-glance","title":"At a glance"},"parent":null},{"slug":"integrations-at-a-glance","path":"/docs/integrations-at-a-glance","title":"At a glance","description":"Status: Core · What Aloha Social can do: Host local identities; discover accounts; follow; publish, receive and read posts; reply, edit, delete, like and boost; process media, polls…","group":"integrations","html":"<h2 id=\"activitypub-fediverse\">ActivityPub / Fediverse</h2>\n<p><strong>Status: </strong>Core · <strong>What Aloha Social can do: </strong>Host local identities; discover accounts; follow; publish, receive and read posts; reply, edit, delete, like and boost; process media, polls, warnings and supported object types</p>\n<p>Federation is asynchronous. Delivery, profile completeness and media retrieval depend on remote servers and background jobs.</p>\n<h2 id=\"mastodon-clients-and-api\">Mastodon clients and API</h2>\n<p><strong>Status: </strong>Broad compatibility · <strong>What Aloha Social can do: </strong>OAuth and app-password sign-in, accounts, timelines, posts, media, notifications, search and common interactions</p>\n<p>Not complete API parity. Many clients need the web-server rules that expose <code>/api</code> and <code>/oauth</code> at the domain root. Streaming and optional endpoints have separate limits.</p>\n<h2 id=\"bluesky-at-protocol\">Bluesky / AT Protocol</h2>\n<p><strong>Status: </strong>Optional, native hosting · <strong>What Aloha Social can do: </strong>Host an AT Protocol identity and repository; support sessions/OAuth and XRPC; publish and read supported records; synchronize with relays and proxy AppView/Chat methods</p>\n<p>AT Protocol is independent of ActivityPub. PLC, relay, AppView and Chat availability, setup and indexing are separate dependencies. Not every Lexicon or account-management method is supported.</p>\n<h2 id=\"remote-bluesky-accounts\">Remote Bluesky accounts</h2>\n<p><strong>Status: </strong>Supported read/interactions · <strong>What Aloha Social can do: </strong>Resolve profiles and author feeds, use saved feeds/lists and starter packs, and exchange supported interactions and chat through configured services</p>\n<p>AppView and Chat proxying is not the same as operating those Bluesky services. Their responses and moderation decisions remain external.</p>\n<h2 id=\"pixelfed\">Pixelfed</h2>\n<p><strong>Status: </strong>Partial interoperability · <strong>What Aloha Social can do: </strong>Exchange ActivityPub photo posts and supported profile/media/story flows</p>\n<p>Pixelfed&#39;s app-specific APIs and complete server behavior are not implemented as a full Pixelfed replacement.</p>\n<h2 id=\"peertube\">PeerTube</h2>\n<p><strong>Status: </strong>Federated video support · <strong>What Aloha Social can do: </strong>Read remote videos and channels, play remote media through the supported proxy path, and publish supported local ActivityPub video objects</p>\n<p>PeerTube&#39;s complete Studio, upload, account and moderation APIs are outside scope. Transcoding and HLS depend on optional server tools/settings.</p>\n<h2 id=\"events-including-gancio-mobilizon\">Events (including Gancio/Mobilizon)</h2>\n<p><strong>Status: </strong>Event display and calendar import · <strong>What Aloha Social can do: </strong>Read supported ActivityPub event metadata, show event cards and import an <code>.ics</code> copy to Nextcloud Calendar when that integration is available</p>\n<p>Importing is a calendar copy, not an RSVP. Federated attendance and event editing are not claimed unless a specific action is shown by the API.</p>\n<h2 id=\"lemmy-piefed-and-other-communities\">Lemmy, PieFed and other communities</h2>\n<p><strong>Status: </strong>Partial ActivityPub interoperability · <strong>What Aloha Social can do: </strong>Display compatible actors and post types, including supported Page/community content</p>\n<p>Community creation, roles, moderation, voting rules and full client workflows are not a Lemmy/PieFed replacement.</p>\n<h2 id=\"nextcloud-calendar\">Nextcloud Calendar</h2>\n<p><strong>Status: </strong>Optional local integration · <strong>What Aloha Social can do: </strong>Add supported event posts to a writable calendar; an ICS download can be used where direct import is unavailable</p>\n<p>Requires the Calendar app and a writable calendar. It does not send an event response to the origin server.</p>\n","toc":[{"id":"activitypub-fediverse","text":"ActivityPub / Fediverse","level":2},{"id":"mastodon-clients-and-api","text":"Mastodon clients and API","level":2},{"id":"bluesky-at-protocol","text":"Bluesky / AT Protocol","level":2},{"id":"remote-bluesky-accounts","text":"Remote Bluesky accounts","level":2},{"id":"pixelfed","text":"Pixelfed","level":2},{"id":"peertube","text":"PeerTube","level":2},{"id":"events-including-gancio-mobilizon","text":"Events (including Gancio/Mobilizon)","level":2},{"id":"lemmy-piefed-and-other-communities","text":"Lemmy, PieFed and other communities","level":2},{"id":"nextcloud-calendar","text":"Nextcloud Calendar","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Integrations.md","sections":null,"anchor":"at-a-glance","manual":false,"prev":{"path":"/docs/integrations","title":"Integrations and compatibility"},"next":{"path":"/docs/integrations-protocol-boundaries","title":"Protocol boundaries"},"parent":null},{"slug":"integrations-protocol-boundaries","path":"/docs/integrations-protocol-boundaries","title":"Protocol boundaries","description":"The Fediverse identity, inbox/outbox, delivery queue and remote actor model are ActivityPub. Remote profile reads can queue a bounded outbox import; cached posts are served while that work…","group":"integrations","html":"<h2 id=\"activitypub\">ActivityPub</h2>\n<p>The Fediverse identity, inbox/outbox, delivery queue and remote actor model are\nActivityPub. Remote profile reads can queue a bounded outbox import; cached\nposts are served while that work proceeds. Anonymous profile reads use cached\ndata and do not initiate arbitrary remote fetches. The importer handles the\nobject and activity types listed in\n<a href=\"/docs/federation\">Federation-Compatibility.md</a>, subject to the\nremote server&#39;s outbox format and availability.</p>\n<p>Set up HTTPS, a stable public URL, <code>.well-known</code> redirects, outbound HTTPS and\nsystem cron. See <a href=\"/docs/admin-before-it-federates#before-it-federates\">Admin.md</a> and the\n<a href=\"/docs/federation\">remote profile notes</a>.</p>\n<h2 id=\"mastodon-compatible-clients\">Mastodon-compatible clients</h2>\n<p>Aloha Social exposes a wide Mastodon-compatible client API, but compatibility\nis not identical to running Mastodon. Check\n<a href=\"/docs/mastodon\">Mastodon-Compatibility.md</a> for endpoint families,\nintentional differences and unsupported areas. Root <code>/api</code> and <code>/oauth</code>\nrewrites are a web-server concern; see\n<a href=\"/docs/admin-mastodon-apps-cannot-connect#mastodon-apps-cannot-connect\">Admin.md</a>.</p>\n<h2 id=\"bluesky-and-at-protocol\">Bluesky and AT Protocol</h2>\n<p>An administrator can enable native AT Protocol hosting. Each local identity\nhas its own DID and repository alongside its ActivityPub identity. A post may\nbe published through both protocols, but identities, authentication, records,\nmoderation and synchronization remain protocol-specific. Users can disable\ntheir Bluesky presence without disabling ActivityPub.</p>\n<p>The local XRPC surface handles supported PDS operations; <code>app.bsky.*</code> and\n<code>chat.bsky.*</code> calls that Social does not host are proxied to configured remote\nservices. A successful proxy response does not prove that a post is indexed in\nevery AppView or visible in every Bluesky client. See\n<a href=\"/docs/atproto\">ATProto-Compatibility.md</a>,\n<a href=\"/docs/admin-bluesky#bluesky\">Admin.md — Bluesky</a>, and the\n<a href=\"/docs/atproto-live\">live-host verification guide</a>.</p>\n<h2 id=\"nextcloud-services\">Nextcloud services</h2>\n<ul>\n<li><strong>Calendar:</strong> import a supported event into a local writable calendar. This\ncreates a calendar copy; it does not announce attendance to Gancio, Mobilizon\nor another event service. See <a href=\"/docs/events\">Events.md</a>.</li>\n<li><strong>Background jobs:</strong> delivery, remote profile imports, feed synchronization,\nscheduled posts, retention and media processing rely on Nextcloud cron.</li>\n<li><strong>Files:</strong> supported replies can be exposed as comments through the existing\nNextcloud Files integration. This does not change who can read the social\npost itself.</li>\n</ul>\n","toc":[{"id":"activitypub","text":"ActivityPub","level":2},{"id":"mastodon-compatible-clients","text":"Mastodon-compatible clients","level":2},{"id":"bluesky-and-at-protocol","text":"Bluesky and AT Protocol","level":2},{"id":"nextcloud-services","text":"Nextcloud services","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Integrations.md","sections":null,"anchor":"protocol-boundaries","manual":false,"prev":{"path":"/docs/integrations-at-a-glance","title":"At a glance"},"next":{"path":"/docs/integrations-what-supported-means","title":"What “supported” means"},"parent":null},{"slug":"integrations-what-supported-means","path":"/docs/integrations-what-supported-means","title":"What “supported” means","description":"Use the API reference for exact routes and parameters. For implementation details, consult Architecture.md; for operator setup, use Admin.md. If a reported failure may be environmental…","group":"integrations","html":"<p>The table distinguishes four things that are easy to confuse:</p>\n<ol>\n<li><strong>Protocol support</strong> means Aloha Social implements a local ActivityPub or\nAT Protocol path.</li>\n<li><strong>Client compatibility</strong> means a third-party app can use an API surface;\nit does not imply every client feature works.</li>\n<li><strong>Remote-service proxying</strong> means a request is forwarded to that service;\nit does not make the service part of this installation.</li>\n<li><strong>Live interoperability</strong> requires a successful exchange with a real remote\nserver. Unit tests and HTTP 200 responses alone do not establish that.</li>\n</ol>\n<p>Use the API reference for exact routes and parameters. For implementation\ndetails, consult <a href=\"/docs/architecture\">Architecture.md</a>; for operator setup, use\n<a href=\"/docs/admin\">Admin.md</a>. If a reported failure may be environmental, record the\nrequest URL, status and response body, then compare that evidence with the\nrelevant integration&#39;s diagnostics before concluding that a code path is\nmissing.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Integrations.md","sections":null,"anchor":"what-supported-means","manual":false,"prev":{"path":"/docs/integrations-protocol-boundaries","title":"Protocol boundaries"},"next":null,"parent":null},{"slug":"events","path":"/docs/events","title":"Federated event cards and Calendar copies","description":"ActivityStreams Events reuse the ordinary post permissions, sanitized description, attachments and author header. The dedicated card adds the event title, venue, start/end time, lifecycle…","group":"events","html":"<p>ActivityStreams Events reuse the ordinary post permissions, sanitized description,\nattachments and author header. The dedicated card adds the event title, venue,\nstart/end time, lifecycle status and original event link. It remains behind content\nwarnings, keyword filters and sensitive-content covers, including its Calendar\ncontrols. A cancelled event remains visible as cancelled; it is not a deleted post.</p>\n<p>Times use the signed-in reader&#39;s Nextcloud timezone and locale. Guests use the\nbrowser timezone. An invalid stored timezone falls back safely to the browser.\nUpcoming, ongoing and past are derived from validated dates and the shared app\nclock. Without an end time the card says Started rather than assuming the event\nhas ended. A post update is identified separately from these time states.</p>\n<p>Recognized <code>ical:status</code> values are CONFIRMED, TENTATIVE and CANCELLED. Schema.org\nEventCancelled/EventScheduled URLs are also normalized. Unknown statuses are\nignored. The API exposes the optional lowercase <code>event.status</code>; ActivityPub export\nretains <code>ical:status</code>. ICS exports preserve the status and valid LAST-MODIFIED.\nMobilizon documents its iCalendar extension in its\n<a href=\"https://docs.mobilizon.org/5.%20Interoperability/1.activity_pub/\">ActivityPub vocabulary</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Events.md","sections":[{"path":"/docs/events-import-is-not-attendance","title":"Import is not attendance","description":"The existing authenticated Calendar import uses a writable calendar and a stable UID to avoid duplicate imports, including repeated requests. The UI reports success only when the backend…","parent":false},{"path":"/docs/events-remaining-scope","title":"Remaining scope","description":"The publishing ActivityPub actor is not necessarily the real-world organizer. Gancio may publish all events through an instance actor. Explicit organizer metadata still needs a validated…","parent":false},{"path":"/docs/events-verification","title":"Verification","description":"Focused component tests cover warning/filter covers, import confirmation and failures, download availability, safe source links, timezone and clock transitions. PHP tests cover date…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/events-import-is-not-attendance","title":"Import is not attendance"},"parent":null},{"slug":"events-import-is-not-attendance","path":"/docs/events-import-is-not-attendance","title":"Import is not attendance","description":"The existing authenticated Calendar import uses a writable calendar and a stable UID to avoid duplicate imports, including repeated requests. The UI reports success only when the backend…","group":"events","html":"<p>The existing authenticated Calendar import uses a writable calendar and a stable\nUID to avoid duplicate imports, including repeated requests. The UI reports success\nonly when the backend explicitly confirms <code>imported: true</code>. Missing calendars,\npermission failures and expired sessions produce persistent recovery feedback.\nThe ICS download remains available before and after import. Guests receive the\ndownload action only. Original links allow only HTTP(S) without URL credentials.</p>\n<p>A calendar entry is a <strong>copy</strong>, not a subscription or RSVP. Re-import currently\nrecognizes the existing UID without overwriting the user&#39;s entry. Changes and\ncancellations therefore do not automatically update an imported copy. Downloading\nthe current ICS makes the source revision available; handling that file is up to\nthe chosen calendar client. There are no unsupported attendance buttons.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Events.md","sections":null,"anchor":"import-is-not-attendance","manual":false,"prev":{"path":"/docs/events","title":"Federated event cards and Calendar copies"},"next":{"path":"/docs/events-remaining-scope","title":"Remaining scope"},"parent":null},{"slug":"events-remaining-scope","path":"/docs/events-remaining-scope","title":"Remaining scope","description":"The publishing ActivityPub actor is not necessarily the real-world organizer. Gancio may publish all events through an instance actor. Explicit organizer metadata still needs a validated…","group":"events","html":"<p>The publishing ActivityPub actor is not necessarily the real-world organizer.\nGancio may publish all events through an instance actor. Explicit organizer\nmetadata still needs a validated mapping; the UI must not invent an organizer from\nthe publishing account. Automatic calendar-copy updates and federated RSVP require\nadditional backend work. These are not claimed as completed by the card changes.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Events.md","sections":null,"anchor":"remaining-scope","manual":false,"prev":{"path":"/docs/events-import-is-not-attendance","title":"Import is not attendance"},"next":{"path":"/docs/events-verification","title":"Verification"},"parent":null},{"slug":"events-verification","path":"/docs/events-verification","title":"Verification","description":"Focused component tests cover warning/filter covers, import confirmation and failures, download availability, safe source links, timezone and clock transitions. PHP tests cover date…","group":"events","html":"<p>Focused component tests cover warning/filter covers, import confirmation and\nfailures, download availability, safe source links, timezone and clock transitions.\nPHP tests cover date validation, status normalization and ActivityPub/ICS export.\nLocal rendering checks do not prove delivery or availability of remote Gancio or\nMobilizon servers.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Events.md","sections":null,"anchor":"verification","manual":false,"prev":{"path":"/docs/events-remaining-scope","title":"Remaining scope"},"next":null,"parent":null},{"slug":"frontend","path":"/docs/frontend","title":"Frontend interoperability and UX work","description":"This is an implementation record for the frontend requirements, not a promise that every remote service has been verified end to end. Changes reuse the Vue, Pinia and Nextcloud…","group":"frontend","html":"<p>This is an implementation record for the frontend requirements, not a promise\nthat every remote service has been verified end to end. Changes reuse the Vue,\nPinia and Nextcloud implementation. The sections below describe shipped UI and\nits boundaries; use the API, integration and operator guides for server-side\nrequirements.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":[{"path":"/docs/frontend-public-profile-presentation-fr-01-fr-02","title":"Public profile presentation (FR-01 / FR-02)","description":"Settings → Public profile layout selects Posts, Photos or Videos as the default, and hides optional navigation tabs. Posts remain available. Existing accounts retain their current default…","parent":false},{"path":"/docs/frontend-shared-composer-and-progressive-entry-fr-03-revised-interaction","title":"Shared composer and progressive entry (FR-03, revised interaction)","description":"The latest requested interaction keeps a compact one-line field on feeds and the owner's profile, plus a compact reply field below a post. These are a mode of the existing Composer, with…","parent":false},{"path":"/docs/frontend-remote-profile-synchronization-fr-04-fr-13","title":"Remote profile synchronization (FR-04 / FR-13)","description":"Cached profile posts remain visible during background synchronization. The shared list/grid parent shows localized pending, failed and taking-longer notices. A failed or overdue read is…","parent":false},{"path":"/docs/frontend-photos-feed-presentation-fr-01-fr-11","title":"Photos feed presentation (FR-01 / FR-11)","description":"The Photos timeline offers Media feed (the existing full post cards, with media before the caption) and Tiles (the existing shared media grid). The reader's choice is remembered per…","parent":false},{"path":"/docs/frontend-continuing-drafts-from-photos","title":"Continuing drafts from Photos","description":"Photos shows Drafts (with a count) beside its media picker when this account has valid saved composer drafts in this browser. The existing account-scoped storage is enumerated without…","parent":false},{"path":"/docs/frontend-composer-attachment-gallery-fr-03-fr-11","title":"Composer attachment gallery (FR-03 / FR-11)","description":"Attachments are reviewed one at a time with previous/next controls and an announced position. The description, filter and focal-point controls belong to the selected attachment. All files…","parent":false},{"path":"/docs/frontend-shorts-playback-fr-11-fr-13","title":"Shorts playback (FR-11 / FR-13)","description":"The existing one-player stack remains shared across scopes, with native scroll snap, sound preference and learning consent intact. Standard Nextcloud controls below the player now expose…","parent":false},{"path":"/docs/frontend-optional-explanatory-and-activity-cards","title":"Optional explanatory and activity cards","description":"Feed explanations and recommendation-coverage hints are localized cards with an explicit close action instead of permanent loose text. Closing remembers the reader's choice in this…","parent":false},{"path":"/docs/frontend-completed-stabilization","title":"Completed stabilization","description":"Shipped web-client behavior and its practical compatibility limits.","parent":false},{"path":"/docs/frontend-remaining-work-and-dependencies","title":"Remaining work and dependencies","description":"Shared media grid, switcher and route history exist. Continue checking loading/failure consistency and transitions across all five views.","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/frontend-public-profile-presentation-fr-01-fr-02","title":"Public profile presentation (FR-01 / FR-02)"},"parent":null},{"slug":"frontend-public-profile-presentation-fr-01-fr-02","path":"/docs/frontend-public-profile-presentation-fr-01-fr-02","title":"Public profile presentation (FR-01 / FR-02)","description":"Settings → Public profile layout selects Posts, Photos or Videos as the default, and hides optional navigation tabs. Posts remain available. Existing accounts retain their current default…","group":"frontend","html":"<p>Settings → Public profile layout selects Posts, Photos or Videos as the default,\nand hides optional navigation tabs. Posts remain available. Existing accounts\nretain their current default and all five tabs until they save a preference.</p>\n<p>The existing profile routes and <code>profileKinds</code> switcher are reused. An unspecified\nprofile URL resolves the owner&#39;s default; an explicit <code>media=posts</code>, <code>image</code> or\n<code>video</code> keeps the reader&#39;s selection, including back navigation from a post.\nThe parent passes the same layout to Posts/Photos/Videos, Tagged and Collections;\nCollections no longer adds an extra horizontal inset. An explicitly opened hidden\ntab remains available in its own navigation for keyboard access.</p>\n<p>These are public presentation preferences, stored per Nextcloud user. They do not\nchange post audiences, authorize a team identity or bypass album/post permission\nchecks. Hiding a tab is not a way to make its posts private. Native ActivityPub\nactors publish the optional <code>profileDefaultTab</code> and <code>profileTabs</code> Social extension;\nother servers may ignore it. The local profile API exposes <code>profile_layout</code>. Public local lookups use the bare username and receive the configured cloud address; aliases such as <code>localhost</code> no longer produce an invented remote handle. Guest profile navigation does not read or write private home read markers.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"public-profile-presentation-fr-01-fr-02","manual":false,"prev":{"path":"/docs/frontend","title":"Frontend interoperability and UX work"},"next":{"path":"/docs/frontend-shared-composer-and-progressive-entry-fr-03-revised-interaction","title":"Shared composer and progressive entry (FR-03, revised interaction)"},"parent":null},{"slug":"frontend-shared-composer-and-progressive-entry-fr-03-revised-interaction","path":"/docs/frontend-shared-composer-and-progressive-entry-fr-03-revised-interaction","title":"Shared composer and progressive entry (FR-03, revised interaction)","description":"The latest requested interaction keeps a compact one-line field on feeds and the owner's profile, plus a compact reply field below a post. These are a mode of the existing Composer, with…","group":"frontend","html":"<p>The latest requested interaction keeps a compact one-line field on feeds and the\nowner&#39;s profile, plus a compact reply field below a post. These are a mode of the\nexisting Composer, with the same validation, default visibility, publisher and\naccount-scoped draft; there is no second sending implementation. Simple text can\nbe sent directly. Expand opens the existing full popup with the same draft.\nRich drafts (media, warnings, polls, events, scheduling, team identities and\nother hidden settings) require review in the popup before sending. This one-line\nentry supersedes the earlier strict modal-only creation requirement.</p>\n<p>The compact instance unmounts while the popup is open, avoiding two editors\nwriting the same draft. Replies, quotes, delete-and-re-draft, Files handoffs,\nvideo uploads and the keyboard shortcut use the shared modal host. Search no\nlonger owns a hidden editor. PostEditForm adapts the same Composer inside that\nmodal for editing supported fields. Stories keep their existing dialog.</p>\n<p>Initial context is supplied before the lazy editor mounts. New posts, replies,\nquotes and re-drafts keep separate drafts. Closing preserves ordinary drafts;\nunfinished uploads and unsaved edits require confirmation. Failed edits retain\ntheir values. Publishing/saving prevents duplicate submissions and unsafe route\nchanges. The Nextcloud dialog provides its focus trap and Escape handling, with\nfocus restored to an available opening control or compact field afterwards.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"shared-composer-and-progressive-entry-fr-03-revised-interaction","manual":false,"prev":{"path":"/docs/frontend-public-profile-presentation-fr-01-fr-02","title":"Public profile presentation (FR-01 / FR-02)"},"next":{"path":"/docs/frontend-remote-profile-synchronization-fr-04-fr-13","title":"Remote profile synchronization (FR-04 / FR-13)"},"parent":null},{"slug":"frontend-remote-profile-synchronization-fr-04-fr-13","path":"/docs/frontend-remote-profile-synchronization-fr-04-fr-13","title":"Remote profile synchronization (FR-04 / FR-13)","description":"Cached profile posts remain visible during background synchronization. The shared list/grid parent shows localized pending, failed and taking-longer notices. A failed or overdue read is…","group":"frontend","html":"<p>Cached profile posts remain visible during background synchronization. The shared\nlist/grid parent shows localized pending, failed and taking-longer notices. A\nfailed or overdue read is never presented as an empty account; recovery checks\nthe first page while preserving the list and deduplicating new posts.</p>\n<p>ActivityPub outbox jobs expose a safe failure state, with a 60-second backoff\nbefore re-queuing. Empty filtered first pages may continue an existing outbox\ncursor, so older photos/videos can be found behind recent non-media items. The\nfrontend also handles failed HTTP polls and bounded polling exhaustion. It\ncancels scheduled checks on navigation and keeps only one scheduled check for\nthe active timeline. Existing Bluesky pending-profile headers receive the same\nbounded waiting UX; detailed AppView failure reporting still belongs to FR-07.</p>\n<p>The API state distinguishes a pending or failed operation from no current\noperation (<code>idle</code>); idle does not promise full remote indexing. Guest reads keep\nthe existing cache-only behavior. Tests cover the local queue/state contracts;\nthis does not certify availability or completeness of every public remote server.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"remote-profile-synchronization-fr-04-fr-13","manual":false,"prev":{"path":"/docs/frontend-shared-composer-and-progressive-entry-fr-03-revised-interaction","title":"Shared composer and progressive entry (FR-03, revised interaction)"},"next":{"path":"/docs/frontend-photos-feed-presentation-fr-01-fr-11","title":"Photos feed presentation (FR-01 / FR-11)"},"parent":null},{"slug":"frontend-photos-feed-presentation-fr-01-fr-11","path":"/docs/frontend-photos-feed-presentation-fr-01-fr-11","title":"Photos feed presentation (FR-01 / FR-11)","description":"The Photos timeline offers Media feed (the existing full post cards, with media before the caption) and Tiles (the existing shared media grid). The reader's choice is remembered per…","group":"frontend","html":"<p>The Photos timeline offers Media feed (the existing full post cards, with media\nbefore the caption) and Tiles (the existing shared media grid). The reader&#39;s\nchoice is remembered per account in browser storage; unavailable storage does not\nprevent switching. Changing the layout does not reset the feed scope, cursor or\nloaded post index. Profile Photos tabs retain their separate image-only grid.</p>\n<p>The Photos page uses a compact Share photos or a video picker instead of a plain\ntext field. It reuses the Videos entry component and hands the selected files to\nthe one existing modal composer, preserving drafts, alt text and publishing\nvalidation. Dismissing the picker does not open another editor.</p>\n<p>Both timeline presentations request the same visual feed: images, videos and\nanimated images, including native PeerTube Video objects. Text-only, audio-only\nand document-only posts are excluded by the database <strong>before pagination</strong>. The\nordinary timeline remains unrestricted. For You uses its existing combined visual\nmedia filter; legacy candidate and trend fallback queries follow the same rule.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"photos-feed-presentation-fr-01-fr-11","manual":false,"prev":{"path":"/docs/frontend-remote-profile-synchronization-fr-04-fr-13","title":"Remote profile synchronization (FR-04 / FR-13)"},"next":{"path":"/docs/frontend-continuing-drafts-from-photos","title":"Continuing drafts from Photos"},"parent":null},{"slug":"frontend-continuing-drafts-from-photos","path":"/docs/frontend-continuing-drafts-from-photos","title":"Continuing drafts from Photos","description":"Photos shows Drafts (with a count) beside its media picker when this account has valid saved composer drafts in this browser. The existing account-scoped storage is enumerated without…","group":"frontend","html":"<p>Photos shows Drafts (with a count) beside its media picker when this account has\nvalid saved composer drafts in this browser. The existing account-scoped storage\nis enumerated without adopting unscoped legacy drafts or other readers&#39; entries.\nThe list includes new-post, reply, quote and re-draft contexts, sorted by save time;\nexisting validation and seven-day expiry still apply. This is not server-side or\ncross-device draft synchronization, nor a separate draft archive.</p>\n<p>Selecting a draft reuses the shared modal. Replies and quotes first reload their\noriginal post through the current viewer&#39;s status API; unavailable or inaccessible\ntargets leave the draft intact and show a retryable error instead of converting it\ninto a standalone post. Re-drafts retain their original storage slot even after\nthe deleted source post is gone. Draft selection does not publish or delete it.\nExisting attachment revalidation, team permissions and unsaved-content protection\nremain authoritative. The button refreshes after composing, tab focus and storage\nchanges, and disappears when no drafts remain.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"continuing-drafts-from-photos","manual":false,"prev":{"path":"/docs/frontend-photos-feed-presentation-fr-01-fr-11","title":"Photos feed presentation (FR-01 / FR-11)"},"next":{"path":"/docs/frontend-composer-attachment-gallery-fr-03-fr-11","title":"Composer attachment gallery (FR-03 / FR-11)"},"parent":null},{"slug":"frontend-composer-attachment-gallery-fr-03-fr-11","path":"/docs/frontend-composer-attachment-gallery-fr-03-fr-11","title":"Composer attachment gallery (FR-03 / FR-11)","description":"Attachments are reviewed one at a time with previous/next controls and an announced position. The description, filter and focal-point controls belong to the selected attachment. All files…","group":"frontend","html":"<p>Attachments are reviewed one at a time with previous/next controls and an announced\nposition. The description, filter and focal-point controls belong to the selected\nattachment. All files and descriptions remain in the existing composer state;\nchanging slides does not replace the post text or lose an upload. Removal keeps a\nvalid selected attachment. The full image source is used instead of a potentially\ncropped thumbnail. The preview frame follows decoded image dimensions within the\nmodal height limit and uses contain, so portrait images are shown completely.\nFocal-point coordinates continue to use the full image frame. Original file and\npublishing crop settings are unchanged. Published media-first posts now page from\ntwo attachments onwards as well. Their gallery indicators paint small circular\nmarkers inside explicit 24px targets, rather than letting Nextcloud&#39;s global\nbutton minimum stretch them into large bars. Previous/next arrows keep 44px touch\ntargets; the compact counter and keyboard navigation remain available.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"composer-attachment-gallery-fr-03-fr-11","manual":false,"prev":{"path":"/docs/frontend-continuing-drafts-from-photos","title":"Continuing drafts from Photos"},"next":{"path":"/docs/frontend-shorts-playback-fr-11-fr-13","title":"Shorts playback (FR-11 / FR-13)"},"parent":null},{"slug":"frontend-shorts-playback-fr-11-fr-13","path":"/docs/frontend-shorts-playback-fr-11-fr-13","title":"Shorts playback (FR-11 / FR-13)","description":"The existing one-player stack remains shared across scopes, with native scroll snap, sound preference and learning consent intact. Standard Nextcloud controls below the player now expose…","group":"frontend","html":"<p>The existing one-player stack remains shared across scopes, with native scroll\nsnap, sound preference and learning consent intact. Standard Nextcloud controls\nbelow the player now expose previous, play/pause and next, plus the current\nposition/loading state. Their space is reserved in the responsive player sizing,\nincluding dynamic mobile viewport height. The same controls work for held\n24-hour pictures. Opening creation holds the current picture/video.</p>\n<p>Paging failures retain the current clip and expose retry outside the video frame;\nplayer network/decoding failures offer a separate retry without removing the post.\nRecommendation feedback uses an icon-only menu with an accessible label, rather than a wide named button over the video. A public reader is not offered a creation action. Keyboard shortcuts no longer\nintercept keys intended for buttons, links, forms or menus. Next waits for a new\npage when necessary and discards navigation after a scope/current-clip change.</p>\n<p>Long descriptions can be expanded inside the current slide, in a bounded,\nkeyboard-scrollable text area. Opening the description pauses playback; closing\nit does not resume unexpectedly. Changing to another short resets the expander.\nThe existing Open the post link remains available for the complete post.\nLong display names/handles truncate within the author row rather than covering\ncontrols. Scope links, sound and like controls have at least 44 px touch targets.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"shorts-playback-fr-11-fr-13","manual":false,"prev":{"path":"/docs/frontend-composer-attachment-gallery-fr-03-fr-11","title":"Composer attachment gallery (FR-03 / FR-11)"},"next":{"path":"/docs/frontend-optional-explanatory-and-activity-cards","title":"Optional explanatory and activity cards"},"parent":null},{"slug":"frontend-optional-explanatory-and-activity-cards","path":"/docs/frontend-optional-explanatory-and-activity-cards","title":"Optional explanatory and activity cards","description":"Feed explanations and recommendation-coverage hints are localized cards with an explicit close action instead of permanent loose text. Closing remembers the reader's choice in this…","group":"frontend","html":"<p>Feed explanations and recommendation-coverage hints are localized cards with an\nexplicit close action instead of permanent loose text. Closing remembers the\nreader&#39;s choice in this browser, separately for their Nextcloud account and card\ncontext; an unavailable browser store still permits closing for the current app\nsession. Cards do not vanish while someone is reading them. Existing one-time\nlearning notices and daily/weekly recap dismissal keep their established behavior.</p>\n<p>The profile posting-activity chart uses the same card, independently dismissible\nper viewed profile. This changes only the reader&#39;s presentation, not the profile\nowner&#39;s data. Explanations attached to recommended posts remain part of the feed\nsnapshot; they are not temporary popups or timed hints. Error/retry notices remain\noperation states rather than educational cards.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"optional-explanatory-and-activity-cards","manual":false,"prev":{"path":"/docs/frontend-shorts-playback-fr-11-fr-13","title":"Shorts playback (FR-11 / FR-13)"},"next":{"path":"/docs/frontend-completed-stabilization","title":"Completed stabilization"},"parent":null},{"slug":"frontend-completed-stabilization","path":"/docs/frontend-completed-stabilization","title":"Completed stabilization","description":"Shipped web-client behavior and its practical compatibility limits.","group":"frontend","html":"<ul>\n<li>Author-only view counts are text on the post detail page. There is no eye icon\nin the floating post action menu.</li>\n<li>Repeated empty thread-context responses no longer scroll back to the main\npost. Initial ancestor loading avoids interrupting a focused text input and\nrespects reduced motion.</li>\n<li>Production runtime autoloading and local recovery are documented in Admin.md.</li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"completed-stabilization","manual":false,"prev":{"path":"/docs/frontend-optional-explanatory-and-activity-cards","title":"Optional explanatory and activity cards"},"next":{"path":"/docs/frontend-remaining-work-and-dependencies","title":"Remaining work and dependencies"},"parent":null},{"slug":"frontend-remaining-work-and-dependencies","path":"/docs/frontend-remaining-work-and-dependencies","title":"Remaining work and dependencies","description":"Shared media grid, switcher and route history exist. Continue checking loading/failure consistency and transitions across all five views.","group":"frontend","html":"<h2 id=\"fr-01\">FR-01</h2>\n<p>Shared media grid, switcher and route history exist. Continue checking loading/failure consistency and transitions across all five views.</p>\n<h2 id=\"fr-02\">FR-02</h2>\n<p>Public default and optional-tab preferences are implemented in this stack; direct links keep normal access checks.</p>\n<h2 id=\"fr-03\">FR-03</h2>\n<p>Shared Composer: compact one-line sending plus the existing full modal, as subsequently requested. Draft contexts, pending-save protection and dirty-edit confirmation are covered.</p>\n<h2 id=\"fr-04\">FR-04</h2>\n<p>Cached posts stay visible with pending/failure/overdue notices and a deduplicating first-page recheck. Outbox failures, retry backoff and empty filtered-page continuation are implemented; live remote availability is separate.</p>\n<h2 id=\"fr-05\">FR-05</h2>\n<p>Existing Event, poll, video, audio and link components remain the rendering foundation; audit safe fallback and original-source actions.</p>\n<h2 id=\"fr-06\">FR-06</h2>\n<p>Event metadata, Calendar import with stable-UID deduplication and ICS download exist. Status/timezone and warning-cover improvements are documented in Events.md. Imported copies are not automatically updated; organizer enrichment remains to be completed. RSVP remains backend-dependent and must not be presented as Calendar import.</p>\n<h2 id=\"fr-07\">FR-07</h2>\n<p>Network badges, ordered profile links, feeds/lists/starter packs and moderation exist; improve discoverability and failure feedback.</p>\n<h2 id=\"fr-08\">FR-08</h2>\n<p>Recommendation explanations such as “Based on your interests” now belong to the feed snapshot and survive ordinary status/count refreshes, including explicit <code>interest: null</code>. They appear only in personalized feeds, are reset on a fresh feed and are pruned with the bounded navigation history. Optional explicit interests are now authorized as an additional ranking signal. No compulsory topic setup; behavioral learning and discovery must still work without selections. Existing feedback/consent controls remain authoritative.</p>\n<h2 id=\"fr-09\">FR-09</h2>\n<p>Existing Group/organization/community metadata and thread views need clearer presentation; do not invent unsupported moderation or membership actions.</p>\n<h2 id=\"fr-10\">FR-10</h2>\n<p>Reuse existing team identities and permission checks; improve selected-identity clarity and prevent accidental identity changes.</p>\n<h2 id=\"fr-11\">FR-11</h2>\n<p>Reuse media grids, lightbox, alt text and album management. Photo albums and account recommendation collections have different semantics.</p>\n<h2 id=\"fr-12\">FR-12</h2>\n<p>Improve real asynchronous outcome and notification feedback using the existing API error handling.</p>\n<h2 id=\"fr-13\">FR-13</h2>\n<p>Reuse synchronization and identity health state; user-facing messages must not expose credentials or sensitive server diagnostics.</p>\n<p>New controls must be localized, keyboard reachable and responsive. Each major\nblock includes focused regression coverage; browser evidence and backend/service\navailability are reported separately. This table is a work list, not a claim\nthat every requirement is finished.</p>\n<h2 id=\"shared-published-post-editor\">Shared published-post editor</h2>\n<p>The Edit action now opens the same <code>Composer</code> used for new posts, inside the\nexisting modal host. Text, mention/emoji tools, content warnings, the attachment\ncarousel and descriptions, and supported event fields share the creation UI.\n<code>PostEditForm</code> only adapts save/cancel events and unsaved-change/upload guards.\nEditing never reads, replaces or clears a creation/reply draft.</p>\n<p>Save sends text, explicit warning/sensitive values, language, the full replacement\nattachment list and descriptions through the existing status-update API. Media\ndescriptions remain local until Save, including an explicitly empty description.\nA failed save keeps the editor and changes available; pending saves and uploads\nblock another submission. Escape/cancel asks before discarding changes.</p>\n<p>Published-post editing does not offer creation-only settings that the update API\ncannot apply: audience/identity changes, polls, scheduling, new event creation,\nlocation, video metadata, image filters and focal-point writes. Existing event\ndates and location remain editable. Existing polls and other untouched metadata\nare preserved by omitting them from the update request. This is UI/API reuse, not\na new publication path or a claim of remote server edit propagation.</p>\n","toc":[{"id":"fr-01","text":"FR-01","level":2},{"id":"fr-02","text":"FR-02","level":2},{"id":"fr-03","text":"FR-03","level":2},{"id":"fr-04","text":"FR-04","level":2},{"id":"fr-05","text":"FR-05","level":2},{"id":"fr-06","text":"FR-06","level":2},{"id":"fr-07","text":"FR-07","level":2},{"id":"fr-08","text":"FR-08","level":2},{"id":"fr-09","text":"FR-09","level":2},{"id":"fr-10","text":"FR-10","level":2},{"id":"fr-11","text":"FR-11","level":2},{"id":"fr-12","text":"FR-12","level":2},{"id":"fr-13","text":"FR-13","level":2},{"id":"shared-published-post-editor","text":"Shared published-post editor","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Frontend-UX.md","sections":null,"anchor":"remaining-work-and-dependencies","manual":false,"prev":{"path":"/docs/frontend-completed-stabilization","title":"Completed stabilization"},"next":null,"parent":null},{"slug":"atproto-live","path":"/docs/atproto-live","title":"Bluesky on a live host: the test","description":"The interop job (.github/workflows/interop-atproto.yml) proves the protocol against Bluesky's own software, run in CI: its PLC directory, PDS, AppView and relay. It cannot prove the real…","group":"atproto-live","html":"<p>The interop job (<code>.github/workflows/interop-atproto.yml</code>) proves the protocol\nagainst Bluesky&#39;s own software, run in CI: its PLC directory, PDS, AppView and\nrelay. It cannot prove the real network. The real <code>plc.directory</code>, the\n<code>bsky.network</code> relay, the public AppView&#39;s handle checks, Bluesky&#39;s chat service,\nits trends and its verifiers all come into play only once a public HTTPS host\ntakes part. Devel is plain HTTP and can never be a PDS. This document is the run\non such a host, by hand, in the order that makes each step&#39;s failure easy to\nread.</p>\n<p>Use <strong>test accounts only</strong>. A DID registered with <code>plc.directory</code> stays there.\nA post that reached the relay has been copied by everybody who reads it. Nothing\nhere can be taken back from the network, only deleted or deactivated.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Live-Test.md","sections":[{"path":"/docs/atproto-live-before","title":"Before","description":"Distinguish local protocol support from public relay and AppView visibility.","parent":false},{"path":"/docs/atproto-live-from-outside-the-probe","title":"From outside: the probe","description":"Run it from a machine outside the host's network. It only reads: GET requests and one WebSocket handshake. Each FAIL line says what is missing. The exit status is the number of failures.","parent":false},{"path":"/docs/atproto-live-by-hand","title":"By hand","description":"Tick each line, and note the time of any failure, so the server log can be read beside it.","parent":false},{"path":"/docs/atproto-live-afterwards","title":"Afterwards","description":"Distinguish local protocol support from public relay and AppView visibility.","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/atproto-live-before","title":"Before"},"parent":null},{"slug":"atproto-live-before","path":"/docs/atproto-live-before","title":"Before","description":"Distinguish local protocol support from public relay and AppView visibility.","group":"atproto-live","html":"<ul>\n<li>The host meets <a href=\"/docs/atproto\">§14.1 of the specification</a>:<ul>\n<li>HTTPS on the host;</li>\n<li>a wildcard DNS record <code>*.&lt;host&gt;</code> and a wildcard certificate;</li>\n<li>the root rules from <code>contrib/webserver</code>, including the firehose proxy;</li>\n<li><code>occ social:atproto:serve</code> under systemd;</li>\n<li>cron, and PHP <code>gmp</code> and <code>sodium</code>.</li>\n</ul>\n</li>\n<li><code>occ social:check:install</code> passes, and the admin page&#39;s Bluesky section shows no failing check.</li>\n<li>Bluesky is switched on, and the relay is told: <code>occ social:atproto:crawl</code>.</li>\n<li>Two Nextcloud test accounts (here: <code>alice</code> and <code>bob</code>), each of which has opened Social once, so each has a Bluesky identity.</li>\n<li>A Bluesky account made at bsky.app, used from the Bluesky phone app or the web app (here: <code>@tester.bsky.social</code>). It is the other side of every exchange below.</li>\n<li>A backup of the database, per <a href=\"/docs/admin\">docs/Admin.md</a>.</li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Live-Test.md","sections":null,"anchor":"before","manual":false,"prev":{"path":"/docs/atproto-live","title":"Bluesky on a live host: the test"},"next":{"path":"/docs/atproto-live-from-outside-the-probe","title":"From outside: the probe"},"parent":null},{"slug":"atproto-live-from-outside-the-probe","path":"/docs/atproto-live-from-outside-the-probe","title":"From outside: the probe","description":"Run it from a machine outside the host's network. It only reads: GET requests and one WebSocket handshake. Each FAIL line says what is missing. The exit status is the number of failures.","group":"atproto-live","html":"<pre><code class=\"language-sh\">contrib/atproto-live-probe.sh &lt;host&gt; alice.&lt;host&gt;\n</code></pre>\n<p>Run it from a machine outside the host&#39;s network. It only reads: GET requests and one WebSocket handshake. Each <code>FAIL</code> line says what is missing. The exit status is the number of failures.</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Failing check</th>\n<th>Usual cause</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>_health</code>, <code>describeServer</code>, <code>did.json</code></td>\n<td>the root rules for <code>/xrpc/</code> and <code>/.well-known/did.json</code> are not in the web server</td>\n</tr>\n<tr>\n<td><code>atproto-did</code> on the handle</td>\n<td>the wildcard DNS record, the wildcard certificate, or the wildcard-host rule</td>\n</tr>\n<tr>\n<td>the DID document&#39;s handle or PDS</td>\n<td><code>occ social:atproto:plc &lt;did&gt;</code> shows the log; <code>--repair</code> sends every operation the directory never confirmed</td>\n</tr>\n<tr>\n<td>the firehose is not 101</td>\n<td>the daemon is not running, or the proxy rule for <code>subscribeRepos</code> is missing</td>\n</tr>\n<tr>\n<td>the relay does not know the DID</td>\n<td><code>occ social:atproto:crawl</code>, then wait a minute</td>\n</tr>\n<tr>\n<td>the AppView shows <code>handle.invalid</code></td>\n<td>the AppView could not fetch <code>https://&lt;handle&gt;/.well-known/atproto-did</code>; check from outside with curl</td>\n</tr>\n<tr>\n<td>the relay throttles the host</td>\n<td>the relay limits how many accounts and events a new data server may have; ask its operator to raise the limit for the host. The admin card&#39;s &quot;Relays carry this server&quot; check says the same</td>\n</tr>\n<tr>\n<td>the chat service does not answer</td>\n<td>direct messages with Bluesky cannot work; the card&#39;s chat service setting, or Bluesky&#39;s service is down</td>\n</tr>\n</tbody></table></div>\n<p>Run the probe again after the first public post (§3.2). Its last checks need one.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Live-Test.md","sections":null,"anchor":"from-outside-the-probe","manual":false,"prev":{"path":"/docs/atproto-live-before","title":"Before"},"next":{"path":"/docs/atproto-live-by-hand","title":"By hand"},"parent":null},{"slug":"atproto-live-by-hand","path":"/docs/atproto-live-by-hand","title":"By hand","description":"Tick each line, and note the time of any failure, so the server log can be read beside it.","group":"atproto-live","html":"<p>Tick each line, and note the time of any failure, so the server log can be read beside it.</p>\n<h2 id=\"3-1-identity\">3.1 Identity</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> <code>@alice.&lt;host&gt;</code> is found by search in the Bluesky app, shows her name, bio, avatar and banner, and has no &quot;invalid handle&quot; warning.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice changes her avatar in Nextcloud. Within minutes the new one is shown on Bluesky, and on a Mastodon account that follows her.</li>\n<li><input disabled=\"\" type=\"checkbox\"> A custom handle, if a test domain is available: set it in Settings → Bluesky → Handle. The Bluesky app then shows the new handle, and <code>alice.&lt;host&gt;</code> still resolves to her.</li>\n</ul>\n<h2 id=\"3-2-posting\">3.2 Posting</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> Each of these, posted publicly by alice, appears in her Bluesky profile looking as it does here:<ul>\n<li>a text post with a link, a hashtag and a mention of <code>@tester.bsky.social</code>;</li>\n<li>a post with three pictures and alt text;</li>\n<li>a video (it plays in the Bluesky app);</li>\n<li>a post longer than 300 characters (cut, with a link back).</li>\n</ul>\n</li>\n<li><input disabled=\"\" type=\"checkbox\"> The link card shows its picture.</li>\n<li><input disabled=\"\" type=\"checkbox\"> An edit within the first minutes replaces the post on Bluesky. A delete removes it.</li>\n<li><input disabled=\"\" type=\"checkbox\"> A reply to the tester&#39;s post appears in that thread. A quote of it shows the quoted post.</li>\n</ul>\n<h2 id=\"3-3-who-may-reply-who-may-quote\">3.3 Who may reply, who may quote</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> Alice posts with &quot;Who can reply: People who follow me&quot;. The Bluesky app shows that replies are limited. The tester, who does not follow alice, cannot reply there.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice changes it to &quot;Nobody&quot;, then to &quot;Anybody&quot;, from the post&#39;s menu. The Bluesky app follows each change after a reload.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice sets &quot;Who may quote it: Nobody but me&quot;. The Bluesky app shows quoting as disabled.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Bob, here, cannot reply to alice&#39;s &quot;Nobody&quot; post. The reason is shown.</li>\n<li><input disabled=\"\" type=\"checkbox\"> The tester closes one of their posts to replies and another to quotes, in the Bluesky app. Alice&#39;s reply and alice&#39;s quote are each refused, with the reason.</li>\n</ul>\n<h2 id=\"3-4-what-comes-in\">3.4 What comes in</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> The tester follows alice. Alice&#39;s Activities show the follow, and her followers list shows the tester.</li>\n<li><input disabled=\"\" type=\"checkbox\"> The tester likes, reposts, replies to and quotes alice&#39;s post, and mentions her. Each one reaches alice&#39;s Activities.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice follows the tester. The tester&#39;s new post appears in alice&#39;s home timeline.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice rings the bell on the tester&#39;s profile. The tester&#39;s next post reaches her notifications.</li>\n</ul>\n<h2 id=\"3-5-reading-bluesky\">3.5 Reading Bluesky</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> With a Jetstream endpoint set and <code>occ social:atproto:listen</code> running, a new post by an account alice follows appears in her home timeline within seconds. The card&#39;s &quot;Jetstream listener&quot; line says it is connected.</li>\n<li><input disabled=\"\" type=\"checkbox\"> A custom feed (&quot;Discover&quot;, or any feed) opens as a timeline. A list does too.</li>\n<li><input disabled=\"\" type=\"checkbox\"> A starter pack link (<code>https://bsky.app/starter-pack/...</code>), pasted into search, opens here, and &quot;Follow all&quot; follows everybody in it.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Discover shows Bluesky&#39;s trending topics and suggested accounts. The real AppView answers both; the dev one answers neither.</li>\n<li><input disabled=\"\" type=\"checkbox\"> A Bluesky account with Bluesky&#39;s blue check shows the check here.</li>\n<li><input disabled=\"\" type=\"checkbox\"> A link to a Bluesky feed, list or starter pack in a post shows as a card.</li>\n</ul>\n<h2 id=\"3-6-bluesky-apps-signed-in-here\">3.6 Bluesky apps signed in here</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> Alice makes an app password in Settings → Bluesky. In the Bluesky app, signing in with hosting provider <code>https://&lt;host&gt;</code>, the handle <code>alice.&lt;host&gt;</code> and that password works. Posting from there shows up here.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Signing in with OAuth works the same way (the app&#39;s sign-in without a password).</li>\n<li><input disabled=\"\" type=\"checkbox\"> With an app password made with &quot;Allow direct messages&quot;, the Bluesky app&#39;s chat opens, and a message to the tester arrives.</li>\n</ul>\n<h2 id=\"3-6a-direct-messages-here\">3.6a Direct messages here</h2>\n<p>The development network has no chat service, so these lines are the only test of the chat bridge against Bluesky&#39;s.</p>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> The tester follows alice and alice follows the tester. Alice writes the tester a direct message from Messages here. It arrives in the tester&#39;s Bluesky chat, without the <code>@</code> address, its link clickable.</li>\n<li><input disabled=\"\" type=\"checkbox\"> The tester answers in the Bluesky app. Within two minutes the answer is in alice&#39;s Messages, in the same conversation, with a notification.</li>\n<li><input disabled=\"\" type=\"checkbox\"> The tester deletes a message in the Bluesky app. It is gone here after the next read.</li>\n<li><input disabled=\"\" type=\"checkbox\"> The tester follows bob. Bob, here, writes one message to the tester and to a Mastodon account. The tester gets it on Bluesky, the Mastodon account over ActivityPub.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice, signed in to a Bluesky app here, writes the tester from that app. Within two minutes the message is in alice&#39;s Messages here, as hers, in the same conversation, and the tester gets it once.</li>\n<li><input disabled=\"\" type=\"checkbox\"> The tester writes alice; alice opens the conversation here. In alice&#39;s Bluesky app it shows read. The tester writes again; alice reads it in the Bluesky app; it is read here after the next read.</li>\n<li><input disabled=\"\" type=\"checkbox\"> With &quot;Who may send you direct messages&quot; at Everybody, a Bluesky account alice does not follow writes her. It is among the requests in her Bluesky app, and in her Messages here. Alice answers it here: the conversation is accepted in her Bluesky app.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice sets the setting to People you follow. That stranger writes again in the old conversation: here the message is in Messages but does not notify, and the stranger waits among her requests.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Another stranger writes alice; she dismisses them from the requests here. The request is gone from her Bluesky app.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice sets &quot;Who may send you direct messages&quot; to Nobody here. Her Bluesky app&#39;s chat settings show &quot;No one&quot;; a stranger on Bluesky cannot write her. She sets &quot;Everyone&quot; in the Bluesky app; the setting here says Everybody.</li>\n</ul>\n<h2 id=\"3-7-blocks\">3.7 Blocks</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> Alice blocks the tester here, with &quot;Publish my blocks of Bluesky accounts&quot; off. The tester notices nothing.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice turns the switch on. The tester can no longer reply to or quote alice in the Bluesky app.</li>\n<li><input disabled=\"\" type=\"checkbox\"> Alice unblocks the tester. Both work again.</li>\n</ul>\n<h2 id=\"3-8-staying-in-step\">3.8 Staying in step</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> After a day, the admin page shows the relay connected, with a lag of seconds.</li>\n<li><input disabled=\"\" type=\"checkbox\"> The probe still passes, with the relay at the same rev as the PDS, or one behind just after a post.</li>\n<li><input disabled=\"\" type=\"checkbox\"> The daemon is restarted. Posts made while it was down reach Bluesky afterwards.</li>\n</ul>\n<h2 id=\"3-9-what-only-the-real-network-can-answer\">3.9 What only the real network can answer</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> <strong>Push.</strong> Alice signs in to the Bluesky phone app here (§3.6) and allows notifications. The tester likes one of her posts: the phone shows a push notification. (The app registers through this server, <code>app.bsky.notification.registerPush</code>, passed on to the AppView.)</li>\n<li><input disabled=\"\" type=\"checkbox\"> <strong>Age assurance.</strong> In a region where Bluesky asks for it, the Bluesky app signed in here shows Bluesky&#39;s age check and not an error. (<code>app.bsky.ageassurance.*</code> is passed on to the AppView like any <code>app.bsky.*</code> call; note what the app shows.)</li>\n<li><input disabled=\"\" type=\"checkbox\"> <strong>Limits.</strong> Alice writes 30 short public posts within a few minutes. All 30 are on her Bluesky profile within ten minutes, and the probe&#39;s relay line still says <code>active</code>. Note the relay&#39;s <code>accountCount</code> beside the number of identities (<code>occ social:atproto:identities --list | wc -l</code>): a relay counts only accounts it has seen events from.</li>\n<li><input disabled=\"\" type=\"checkbox\"> After a day, the admin card&#39;s &quot;Relays carry this server&quot; check is green.</li>\n</ul>\n<h2 id=\"3-10-moving-last-and-with-throwaway-accounts-only\">3.10 Moving, last and with throwaway accounts only</h2>\n<ul>\n<li><input disabled=\"\" type=\"checkbox\"> A throwaway Bluesky account moves here: Migration → &quot;Bring your Bluesky account here&quot;, signed in as a fresh Nextcloud account. Its followers on Bluesky still follow it, and its posts are in its timeline.</li>\n<li><input disabled=\"\" type=\"checkbox\"> It moves away again, to bsky.social, from the Migration page.</li>\n</ul>\n","toc":[{"id":"3-1-identity","text":"3.1 Identity","level":2},{"id":"3-2-posting","text":"3.2 Posting","level":2},{"id":"3-3-who-may-reply-who-may-quote","text":"3.3 Who may reply, who may quote","level":2},{"id":"3-4-what-comes-in","text":"3.4 What comes in","level":2},{"id":"3-5-reading-bluesky","text":"3.5 Reading Bluesky","level":2},{"id":"3-6-bluesky-apps-signed-in-here","text":"3.6 Bluesky apps signed in here","level":2},{"id":"3-6a-direct-messages-here","text":"3.6a Direct messages here","level":2},{"id":"3-7-blocks","text":"3.7 Blocks","level":2},{"id":"3-8-staying-in-step","text":"3.8 Staying in step","level":2},{"id":"3-9-what-only-the-real-network-can-answer","text":"3.9 What only the real network can answer","level":2},{"id":"3-10-moving-last-and-with-throwaway-accounts-only","text":"3.10 Moving, last and with throwaway accounts only","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Live-Test.md","sections":null,"anchor":"by-hand","manual":false,"prev":{"path":"/docs/atproto-live-from-outside-the-probe","title":"From outside: the probe"},"next":{"path":"/docs/atproto-live-afterwards","title":"Afterwards"},"parent":null},{"slug":"atproto-live-afterwards","path":"/docs/atproto-live-afterwards","title":"Afterwards","description":"Distinguish local protocol support from public relay and AppView visibility.","group":"atproto-live","html":"<ul>\n<li>Write down:<ul>\n<li>the probe&#39;s output;</li>\n<li>the server version and the app version;</li>\n<li>every unticked line, with the time, a screenshot and <code>nextcloud.log</code> from around then.</li>\n</ul>\n</li>\n<li>A finding is an issue in the app&#39;s repository, one per finding. A security finding is not an issue: report it as the security policy says.</li>\n<li>To end the test: switch Bluesky off on the admin page. The test accounts&#39; DIDs stay in <code>plc.directory</code> and their repositories stop being served. Deactivate the Bluesky test account at bsky.app as well.</li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Atproto-Live-Test.md","sections":null,"anchor":"afterwards","manual":false,"prev":{"path":"/docs/atproto-live-by-hand","title":"By hand"},"next":null,"parent":null},{"slug":"evaluation","path":"/docs/evaluation","title":"For You offline evaluation","description":"The offline evaluator compares deterministic feed baselines against the current For You ranker. It does not read user data, send network requests, collect impressions, alter serving…","group":"evaluation","html":"<p>The offline evaluator compares deterministic feed baselines against the current\nFor You ranker. It does not read user data, send network requests, collect\nimpressions, alter serving weights, or enable recommendation features.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/ForYouEvaluation.md","sections":[{"path":"/docs/evaluation-run-it","title":"Run it","description":"The committed synthetic-v1.json fixture contains 12 synthetic reader scenarios and 33 synthetic posts spanning ActivityPub and ATProto sources, languages, formats, follow-graph sizes and…","parent":false},{"path":"/docs/evaluation-compared-variants-and-metrics","title":"Compared variants and metrics","description":"The report compares the legacy hashtag ordering, chronological followed feed, pure topic match, topic plus follow prior, balanced H0 ranker, and H0 with the existing diversity re-ranker.…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/evaluation-run-it","title":"Run it"},"parent":null},{"slug":"evaluation-run-it","path":"/docs/evaluation-run-it","title":"Run it","description":"The committed synthetic-v1.json fixture contains 12 synthetic reader scenarios and 33 synthetic posts spanning ActivityPub and ATProto sources, languages, formats, follow-graph sizes and…","group":"evaluation","html":"<p>From the app root:</p>\n<pre><code class=\"language-sh\">composer run recommendations:evaluate\n</code></pre>\n<p>To evaluate another JSON fixture and write the report to a file:</p>\n<pre><code class=\"language-sh\">php tools/recommendations/evaluate.php path/to/dataset.json report.json\n</code></pre>\n<p>The committed <code>synthetic-v1.json</code> fixture contains 12 synthetic reader\nscenarios and 33 synthetic posts spanning ActivityPub and ATProto sources,\nlanguages, formats, follow-graph sizes and sparse provider availability. It\nincludes hidden, unlisted, followers-only, deleted and language-ineligible\nrecords to exercise hard controls. Example post text and people are not copied\nfrom live accounts. The Nextcloud and open-source reader scenario includes a\nfour-post release-story cluster alongside separate PHP-security, migration,\nand Linux-desktop stories, so its story metrics measure whether the ranker\nuses available alternatives rather than only measuring repetition within one\nstory.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/ForYouEvaluation.md","sections":null,"anchor":"run-it","manual":false,"prev":{"path":"/docs/evaluation","title":"For You offline evaluation"},"next":{"path":"/docs/evaluation-compared-variants-and-metrics","title":"Compared variants and metrics"},"parent":null},{"slug":"evaluation-compared-variants-and-metrics","path":"/docs/evaluation-compared-variants-and-metrics","title":"Compared variants and metrics","description":"The report compares the legacy hashtag ordering, chronological followed feed, pure topic match, topic plus follow prior, balanced H0 ranker, and H0 with the existing diversity re-ranker.…","group":"evaluation","html":"<p>The report compares the legacy hashtag ordering, chronological followed feed,\npure topic match, topic plus follow prior, balanced H0 ranker, and H0 with the\nexisting diversity re-ranker. It also reports the following and discovery\nweight profiles, both before and after page re-ranking. Each uses the same\neligible candidate pool.</p>\n<p>For each variant, the report includes NDCG@20, relevant results returned,\ncandidate count and corpus coverage, effective and unique topic diversity,\nunique story clusters, the number and rate of repeated story posts, and the\nshare occupied by the largest story cluster, hard-control compliance,\nduplicate rate, and local evaluator runtime median and p95. Story metrics\ninclude only posts with enough text terms to identify a story;\n<code>story_identifiable_posts_at_20</code> reports that denominator. Candidate source\nrecall is reported once for the retrieval fixture,\nincluding a breakdown by protocol; it is separate from ranking quality.\nThe dataset summary also gives aggregate counts by primary candidate exclusion\nreason (privacy, discoverability, visibility, hidden topic, language, or source\navailability). These mutually exclusive profile-post counts contain no post\ncontent or profile identifiers.\nPaired profile-cluster bootstrap intervals compare each variant with pure\ntopic match. The fixed seed makes those intervals reproducible.</p>\n<p>The fixture labels are synthetic scenario judgements authored by one\ncontributor. They are not multi-rater human judgements, real-user satisfaction,\nor statistically representative data. Bootstrap intervals describe variation\nacross these profiles only. Runtime numbers measure this local PHP process and\nare not production-serving latency. Optional embeddings are intentionally not\nincluded; they remain gated on F1-F6 evidence.</p>\n<p>Do not promote weights or describe a model as better from this report alone.\nUse it to catch regressions, expose hard-control failures, compare approaches\non explicit scenarios, and decide which variants need independent human review\nand a larger consent-reviewed dataset.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/ForYouEvaluation.md","sections":null,"anchor":"compared-variants-and-metrics","manual":false,"prev":{"path":"/docs/evaluation-run-it","title":"Run it"},"next":null,"parent":null},{"slug":"releasing","path":"/docs/releasing","title":"Releasing Aloha Social","description":"How a version of this app gets from main to the Nextcloud App Store, and what has to be in place before the first time. Everything here is run by a person; the workflows do the building…","group":"releasing","html":"<p>How a version of this app gets from <code>main</code> to the Nextcloud App Store, and\nwhat has to be in place before the first time. Everything here is run by a\nperson; the workflows do the building, signing and uploading, and one of them\nwaits for that person&#39;s approval before anything leaves GitHub.</p>\n<p><strong>Where the version lives.</strong> <code>appinfo/info.xml</code> is the release version. The\nsame number has to be in <code>package.json</code>, <code>package-lock.json</code>, <code>composer.json</code>\nand the &quot;App version&quot; line of <a href=\"/docs/architecture\">Architecture.md</a>;\n<code>tests/DocumentationTest.php</code> fails when they disagree, and so does the\nrelease workflow. Releases are tagged <code>vX.Y.Z</code>; the App Store takes the\nnumber without the <code>v</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Releasing.md","sections":[{"path":"/docs/releasing-once-before-the-first-release","title":"Once, before the first release","description":"Versioning, build, signing and App Store release workflow.","parent":false},{"path":"/docs/releasing-every-release","title":"Every release","description":"Versioning, build, signing and App Store release workflow.","parent":false},{"path":"/docs/releasing-what-the-release-changes-elsewhere","title":"What the release changes elsewhere","description":"Versioning, build, signing and App Store release workflow.","parent":false},{"path":"/docs/releasing-when-it-goes-wrong","title":"When it goes wrong","description":"Versioning, build, signing and App Store release workflow.","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/releasing-once-before-the-first-release","title":"Once, before the first release"},"parent":null},{"slug":"releasing-once-before-the-first-release","path":"/docs/releasing-once-before-the-first-release","title":"Once, before the first release","description":"Versioning, build, signing and App Store release workflow.","group":"releasing","html":"<ol>\n<li><strong>The signing key.</strong> The repository secret <code>APP_PRIVATE_KEY</code> holds the\nprivate key whose certificate is registered for the app id <code>social</code> in\n<a href=\"https://github.com/nextcloud/app-certificate-requests/tree/master/social\">nextcloud/app-certificate-requests</a>.\nBoth workflows below refuse a key that does not match that certificate.</li>\n<li><strong>The environment <code>nextcloud-appstore</code></strong>, under <em>Settings → Environments</em>\nof the repository, with <strong>Required reviewers</strong> set to the people who may\npublish. The publish job of <code>appstore-build-publish.yml</code> names this\nenvironment; GitHub creates an environment it does not know <strong>without\nreviewers</strong>, and an environment without reviewers pauses nothing — the\nupload would go out the moment the build finished.</li>\n<li><strong>The App Store token</strong> as the environment secret <code>APPSTORE_TOKEN</code> of\n<code>nextcloud-appstore</code>: the API token of an apps.nextcloud.com account that\nowns the app <code>social</code>. A repository secret of the same name works too,\nbut the environment keeps it behind the reviewers.</li>\n<li><strong>git-cliff</strong> on the machine that cuts the release, for the changelog:\n<code>brew install git-cliff</code>, <code>cargo install git-cliff</code>, or the binary from\n<a href=\"https://git-cliff.org/docs/installation\">git-cliff.org</a>. The dry run\ninstalls its own copy and checks the result, so a missing local install\nonly means the dry run says so.</li>\n</ol>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Releasing.md","sections":null,"anchor":"once-before-the-first-release","manual":false,"prev":{"path":"/docs/releasing","title":"Releasing Aloha Social"},"next":{"path":"/docs/releasing-every-release","title":"Every release"},"parent":null},{"slug":"releasing-every-release","path":"/docs/releasing-every-release","title":"Every release","description":"Versioning, build, signing and App Store release workflow.","group":"releasing","html":"<ol>\n<li><p><strong>Green <code>main</code>.</strong> The pull request and push workflows are green on the\ncommit to be released, and the open <code>nightly-failure</code> issues are either\nclosed or understood.</p>\n</li>\n<li><p><strong>The changelog.</strong> <code>make changelog</code> regenerates <code>CHANGELOG.md</code> from the\nconventional commits since <code>v0.24.1</code> (<code>changelog_since</code> in the Makefile;\nwhat came before is the hand-written history <code>cliff.toml</code> carries as its\nfooter), labelled with the version in <code>appinfo/info.xml</code>. Commit it as\n<code>docs(changelog): X.Y.Z</code>. Only <code>feat</code>, <code>fix</code>, <code>perf</code> and <code>docs</code> commits\nbecome entries; <code>cliff.toml</code> says which types are left out.</p>\n</li>\n<li><p><strong>The dry run.</strong> Dispatch <em>Test App Store Release (Dry Run)</em>\n(<code>test-release.yml</code>) on <code>main</code>. It is the release workflow without the\npublishing: it checks that the five version places agree, that\n<code>CHANGELOG.md</code> is what <code>make changelog</code> produces (an error on a tag, a\nwarning on a branch), runs the unit, lint and type checks on the PHP\nversion <code>appinfo/info.xml</code> declares as the floor, builds the tarball with\n<code>make appstore</code>, signs it with <code>APP_PRIVATE_KEY</code> against the registered\ncertificate, and leaves the signed archive as a three-day Actions\nartifact. Nothing is published. A red dry run is fixed on <code>main</code> and\ndispatched again; do not tag over it.</p>\n</li>\n<li><p><strong>The tag and the GitHub release.</strong> On the dry-run commit:</p>\n<pre><code class=\"language-bash\">git tag -s vX.Y.Z -m &#39;vX.Y.Z&#39;\ngit push origin vX.Y.Z\ngh release create vX.Y.Z --title &#39;vX.Y.Z&#39; --notes-from-tag\n</code></pre>\n<p>or create the release in the GitHub interface from the tag. Publishing the\nrelease is what starts <code>appstore-build-publish.yml</code> (<code>release: published</code>); a draft starts nothing. A pre-release tag (<code>vX.Y.Z-beta.1</code>)\nis accepted by both workflows.</p>\n</li>\n<li><p><strong>The build job</strong> (<em>Test, build, sign and attach release</em>) repeats the dry\nrun on the tag, refuses a tag that disagrees with the version files, and\nattaches <code>social-vX.Y.Z.tar.gz</code> to the GitHub release. The App Store\nserves that file; the upgrade workflow installs it (below).</p>\n</li>\n<li><p><strong>The approval.</strong> The publish job (<em>Publish to Nextcloud App Store</em>)\nwaits in the <code>nextcloud-appstore</code> environment until a required reviewer\napproves it on the run&#39;s page. Check the attached tarball first — install\nit on a Nextcloud if in doubt. Rejecting leaves the GitHub release\nstanding with its tarball and sends nothing to the App Store.</p>\n</li>\n<li><p><strong>After approval</strong> the job uploads the release to apps.nextcloud.com with\n<code>APPSTORE_TOKEN</code> and the download URL of the attached tarball. The App\nStore fetches the archive, verifies the signature against the registered\ncertificate and lists the version within a few minutes; a refusal is in\nthe job&#39;s log.</p>\n</li>\n</ol>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Releasing.md","sections":null,"anchor":"every-release","manual":false,"prev":{"path":"/docs/releasing-once-before-the-first-release","title":"Once, before the first release"},"next":{"path":"/docs/releasing-what-the-release-changes-elsewhere","title":"What the release changes elsewhere"},"parent":null},{"slug":"releasing-what-the-release-changes-elsewhere","path":"/docs/releasing-what-the-release-changes-elsewhere","title":"What the release changes elsewhere","description":"Versioning, build, signing and App Store release workflow.","group":"releasing","html":"<ul>\n<li><strong>The upgrade workflow.</strong> <code>upgrade.yml</code>&#39;s &quot;latest&quot; legs (<code>Upgrade on sqlite</code>, <code>Upgrade on pgsql</code>) install whatever GitHub marks as the latest\nrelease — the attached tarball, or the tag&#39;s source when a release has\nnone — seed it with data, replace it with the checkout and run <code>occ upgrade</code>, then compare the schema with a fresh install&#39;s and run the\nintegration suite. From the night after the release, the migrations are\ntested against that version&#39;s schema; the <code>v0.10.0</code> legs keep covering the\noldest schema the squash has to bring up.</li>\n<li><strong>The changelog check.</strong> <code>DocumentationTest</code> requires the top heading of\n<code>CHANGELOG.md</code> to be at or after the newest <code>v*</code> tag wherever git can list\nthe tags, so a tag cut without step 2 fails the unit suite on every full\ncheckout.</li>\n<li><strong>The version bumps</strong> continue on <code>main</code> as before; the next release&#39;s\nchangelog section covers everything since <code>v0.24.1</code> until a tag after that\nexists, and from the next tag on, everything since that tag.</li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Releasing.md","sections":null,"anchor":"what-the-release-changes-elsewhere","manual":false,"prev":{"path":"/docs/releasing-every-release","title":"Every release"},"next":{"path":"/docs/releasing-when-it-goes-wrong","title":"When it goes wrong"},"parent":null},{"slug":"releasing-when-it-goes-wrong","path":"/docs/releasing-when-it-goes-wrong","title":"When it goes wrong","description":"Versioning, build, signing and App Store release workflow.","group":"releasing","html":"<ul>\n<li><em>The build job failed after the release was published.</em> Fix on <code>main</code>,\ndelete the GitHub release and the tag (<code>gh release delete vX.Y.Z --cleanup-tag</code>), bump the version and release again. Nothing reached the\nApp Store: the publish job never ran.</li>\n<li><em>The upload was refused.</em> The job log carries the App Store&#39;s answer —\nusually a signature that does not match the registered certificate, a\nversion already published, or a <code>max-version</code> the App Store does not know.\nThe GitHub release stays; fix, bump and release again rather than editing\nthe release in place, because the App Store keys on the version number.</li>\n<li><em>A published version is broken.</em> The App Store has no &quot;unpublish&quot;; release\na fix with a higher version number.</li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Releasing.md","sections":null,"anchor":"when-it-goes-wrong","manual":false,"prev":{"path":"/docs/releasing-what-the-release-changes-elsewhere","title":"What the release changes elsewhere"},"next":null,"parent":null},{"slug":"api","path":"/docs/api","title":"Aloha Social API Reference","description":"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…","group":"api","html":"<blockquote>\n<p>This document is written by hand but mechanically checked: <code>tests/DocumentationTest.php</code> 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 <code>#[FrontpageRoute]</code> attributes on the controller methods, plus what is left in <code>appinfo/routes.php</code>. Every route below appears in a table row with its URL exactly as written in the attribute. Paths that are <em>not</em> routes of this app (the <code>.well-known</code> discovery documents handled by the Nextcloud WellKnown API) are deliberately written without code spans so that check stays exact.</p>\n</blockquote>\n<p><strong>Rate-limit headers.</strong> Every response from a route that carries a rate limit\nalso carries <code>X-RateLimit-Limit</code>, <code>X-RateLimit-Remaining</code> and\n<code>X-RateLimit-Reset</code> (seconds since the epoch, at the end of the window this\nrequest fell in), so a client can pace itself rather than hammer until it is\nrefused. The refusal itself is Nextcloud&#39;s and is a <strong>429</strong>; the count in the\nheader is this app&#39;s own and is advisory. A route with no limit carries no\nheaders, and an instance with <strong>no memcache configured</strong> carries <code>Limit</code>\nwithout <code>Remaining</code> or <code>Reset</code> — there is nowhere to keep a counter, and a\nnumber that was never measured is worse than no number.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":[{"path":"/docs/api-contents","title":"Contents","description":"The route-by-route reference for the app's registered API.","parent":false},{"path":"/docs/api-overview","title":"Overview","description":"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).","parent":false},{"path":"/docs/api-authentication","title":"Authentication","description":"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…","parent":false},{"path":"/docs/api-mastodon-compatible-api","title":"Mastodon-compatible API","description":"The route-by-route reference for the app's registered API.","parent":false},{"path":"/docs/api-instance-and-app-metadata","title":"Instance and app metadata","description":"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…","parent":true},{"path":"/docs/api-accounts","title":"Accounts","description":"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…","parent":true},{"path":"/docs/api-search-mastodon-v2","title":"Search (Mastodon v2)","description":"Auth: public, no-csrf (viewer required) · Parameters: q (required), type, limit (20, capped at 40), resolve, account_id, offset, max_id, min_id","parent":true},{"path":"/docs/api-statuses","title":"Statuses","description":"Auth: public, no-csrf (viewer required, write scope) · Parameters: Body (JSON or form-encoded): status, visibility, media_ids (array), in_reply_to_id, quote_id, spoiler_text, sensitive…","parent":true},{"path":"/docs/api-scheduled-statuses","title":"Scheduled statuses","description":"Auth: public, no-csrf (viewer required) · Parameters: limit (20, capped at 40), max_id (0), min_id (0), since_id (0)","parent":true},{"path":"/docs/api-lists","title":"Lists","description":"Auth: public, no-csrf (viewer required, read:lists scope) · Parameters: —","parent":true},{"path":"/docs/api-pixelfeds-own-routes","title":"Pixelfed's own routes","description":"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…","parent":true},{"path":"/docs/api-starter-packs","title":"Starter packs","description":"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…","parent":true},{"path":"/docs/api-finding-people-in-other-servers-directories","title":"Finding people in other servers' directories","description":"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…","parent":true},{"path":"/docs/api-collections","title":"Collections","description":"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…","parent":true},{"path":"/docs/api-places","title":"Places","description":"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…","parent":true},{"path":"/docs/api-stories","title":"Stories","description":"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…","parent":true},{"path":"/docs/api-conversations","title":"Conversations","description":"Auth: public, no-csrf (viewer required, read:statuses or read scope) · Parameters: limit (20, capped at 40), max_id (0), min_id (0), since_id (0)","parent":true},{"path":"/docs/api-keyword-filters","title":"Keyword filters","description":"Auth: public, no-csrf (viewer required, read:filters or read scope) · Parameters: —","parent":true},{"path":"/docs/api-discovery-trends-and-relationships","title":"Discovery, trends and relationships","description":"Auth: public, no-csrf · Parameters: limit (20, capped at 40), offset (0), period (1h, 12h, 1d — the default —, 3d, 10d)","parent":true},{"path":"/docs/api-announcements","title":"Announcements","description":"Auth: public, no-csrf (viewer required, any token — no scope) · Parameters: —","parent":true},{"path":"/docs/api-timelines-and-notifications","title":"Timelines and notifications","description":"Auth: public, no-csrf · Parameters: 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)","parent":true},{"path":"/docs/api-followed-hashtags","title":"Followed hashtags","description":"Auth: public, no-csrf (viewer required, read:follows or read scope) · Parameters: limit (20, capped at 50), max_id (0), min_id (0)","parent":true},{"path":"/docs/api-for-you","title":"For you","description":"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…","parent":true},{"path":"/docs/api-polls","title":"Polls","description":"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…","parent":true},{"path":"/docs/api-link-previews","title":"Link previews","description":"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…","parent":true},{"path":"/docs/api-reports","title":"Reports","description":"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…","parent":true},{"path":"/docs/api-admin-api-mastodon","title":"Admin API (Mastodon)","description":"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…","parent":true},{"path":"/docs/api-media","title":"Media","description":"Auth: public, no-csrf (viewer required, write scope) · Parameters: Multipart: file (required, read from $_FILES['file']), description (the alt text), thumbnail (an image, for a video only)","parent":true},{"path":"/docs/api-search-mastodon-adjacent-app-specific-shapes","title":"Search (Mastodon-adjacent, app-specific shapes)","description":"{\"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…","parent":true},{"path":"/docs/api-pagination","title":"Pagination","description":"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…","parent":true},{"path":"/docs/api-peertubes-own-routes","title":"PeerTube's own routes","description":"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…","parent":true},{"path":"/docs/api-custom-local-api","title":"Custom Local API","description":"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…","parent":false},{"path":"/docs/api-posts","title":"Posts","description":"Auth: user · Parameters: content (''), to (array), type (default public), replyTo (''), attachments (mixed, default []), hashtags (array), poll (object, optional), spoilerText ('', the…","parent":true},{"path":"/docs/api-current-user","title":"Current user","description":"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.…","parent":true},{"path":"/docs/api-account-info","title":"Account info","description":"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…","parent":true},{"path":"/docs/api-banner","title":"Banner","description":"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…","parent":true},{"path":"/docs/api-migration","title":"Migration","description":"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…","parent":true},{"path":"/docs/api-channels","title":"Channels","description":"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\"…","parent":true},{"path":"/docs/api-posts-held-for-review","title":"Posts held for review","description":"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…","parent":true},{"path":"/docs/api-statistics","title":"Statistics","description":"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…","parent":true},{"path":"/docs/api-pixelfeds-administration-routes","title":"Pixelfed's administration routes","description":"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…","parent":true},{"path":"/docs/api-config-and-system","title":"Config and system","description":"{\"result\": {\"version\": \"<installed_version>\", \"setup\": <bool>}, \"status\": 1}.","parent":true},{"path":"/docs/api-moderation-moderators-only","title":"Moderation (moderators only)","description":"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)…","parent":true},{"path":"/docs/api-external-users","title":"External users","description":"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…","parent":true},{"path":"/docs/api-oauth","title":"OAuth","description":"A partial, Mastodon-shaped OAuth 2 flow (OAuthController, ClientService).","parent":false},{"path":"/docs/api-activitypub-federation","title":"ActivityPub Federation","description":"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…","parent":false},{"path":"/docs/api-legacy-ostatus","title":"Legacy OStatus","description":"Auth: user, no-csrf · Parameters: uri (required; an address, an acct: URI or an actor id)","parent":false},{"path":"/docs/api-frontend-document-serving","title":"Frontend / Document serving","description":"These serve HTML or files for the app's own UI; they are not client API endpoints.","parent":false},{"path":"/docs/api-async-queue","title":"Async Queue","description":"Auth: public, no-csrf, signed · Parameters: token (path); header X-Social-Async-Signature","parent":false},{"path":"/docs/api-error-responses","title":"Error Responses","description":"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…","parent":false},{"path":"/docs/api-numeric-status-identifiers","title":"Numeric status identifiers","description":"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…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/api-contents","title":"Contents"},"parent":null},{"slug":"api-contents","path":"/docs/api-contents","title":"Contents","description":"The route-by-route reference for the app's registered API.","group":"api","html":"<ul>\n<li><a href=\"/docs/api-overview#overview\">Overview</a></li>\n<li><a href=\"/docs/api-authentication#authentication\">Authentication</a></li>\n<li><a href=\"/docs/api-mastodon-compatible-api#mastodon-compatible-api\">Mastodon-compatible API</a></li>\n<li><a href=\"/docs/api-custom-local-api#custom-local-api\">Custom Local API</a></li>\n<li><a href=\"/docs/api-oauth#oauth\">OAuth</a></li>\n<li><a href=\"/docs/api-activitypub-federation#activitypub-federation\">ActivityPub Federation</a></li>\n<li><a href=\"/docs/api-legacy-ostatus#legacy-ostatus\">Legacy OStatus</a></li>\n<li><a href=\"/docs/api\">Frontend / Document serving</a></li>\n<li><a href=\"/docs/api-async-queue#async-queue\">Async Queue</a></li>\n<li><a href=\"/docs/api-error-responses#error-responses\">Error Responses</a></li>\n</ul>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"contents","manual":false,"prev":{"path":"/docs/api","title":"Aloha Social API Reference"},"next":{"path":"/docs/api-overview","title":"Overview"},"parent":null},{"slug":"api-overview","path":"/docs/api-overview","title":"Overview","description":"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).","group":"api","html":"<p>The Aloha Social app exposes four groups of endpoints. Each is registered as a <code>#[FrontpageRoute]</code> attribute on the controller method that answers it, with one exception noted at the end of this section:</p>\n<ul>\n<li><strong>Mastodon-compatible REST API</strong> (the controllers built on <code>MastodonApiController</code> — <code>AccountApiController</code>, <code>StatusApiController</code>, <code>TimelineApiController</code>, <code>MediaApiController</code>, <code>InstanceApiController</code>, <code>ScheduledStatusApiController</code>, <code>AnnualReportApiController</code> and <code>ApiController</code> — plus <code>TagController</code> and <code>OAuthController</code>) — a partial implementation of the Mastodon client API. Several endpoints are stubs; each is marked below.</li>\n<li><strong>Custom Local API</strong> (<code>LocalController</code>, <code>ConfigController</code>) — the endpoints the app&#39;s own Vue frontend calls. They are not Mastodon-compatible and their response envelope differs (see Error Responses).</li>\n<li><strong>ActivityPub Federation API</strong> (<code>ActivityPubController</code>, <code>SocialPubController</code>) — server-to-server ActivityPub, plus the HTML profile/post pages served on the same URLs.</li>\n<li><strong>Frontend, document, OStatus and queue endpoints</strong> (<code>NavigationController</code>, <code>OStatusController</code>, <code>QueueController</code>) — HTML pages and internal plumbing.</li>\n</ul>\n<p>All URLs are relative to the app&#39;s route base, i.e. index.php/apps/social + the URL from the route table (for example, index.php/apps/social/api/v1/statuses).</p>\n<p><strong>Conditional GETs.</strong> The home timeline and the unread counts carry an <code>ETag</code> built from the newest id the viewer can see; the routes a page load reads for its sidebar — <code>/api/v1/custom_emojis</code>, <code>/api/v1/trends/tags</code>, <code>/api/v1/instance/</code>, <code>/api/v2/instance</code>, <code>/api/v1/lists</code> and <code>/api/v1/followed_tags</code> — carry one built from the answer itself. All of them go out with <code>Cache-Control: private, no-cache</code>, and a request whose <code>If-None-Match</code> names the current tag is answered <code>304</code> with no body.</p>\n<p>None of these are OCS routes: <code>#[ApiRoute]</code> would put them under <code>/ocsapp</code>, which is not where any of these paths are published.</p>\n<p><code>GET /api/v1/accounts/{id}</code> is the one route still declared in <code>appinfo/routes.php</code>. Its <code>{id}</code> accepts slashes, so it also matches <code>/api/v1/accounts/{account}/lists</code> and <code>/api/v1/accounts/{account}/featured_tags</code>, 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.</p>\n<h2 id=\"removed-the-superseded-half-of-the-custom-local-api\">Removed: the superseded half of the Custom Local API</h2>\n<p>The Custom Local API predates the Mastodon-compatible one, and the frontend\nmoved off most of it. Nineteen of <code>LocalController</code>&#39;s thirty-one routes had no\ncaller anywhere in <code>src/</code> and were documented here as deprecated for a release;\n<strong>as of 0.19.39 they are gone</strong>, and with them the <code>getStream*()</code> /\n<code>getTimeline*_dep()</code> query layer that only they used. A caller of one of these\ngets a 404 and should move to the Mastodon route beside it:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Removed</th>\n<th>Use instead</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /api/v1/stream/home</code></td>\n<td><code>GET /api/v1/timelines/home</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/stream/timeline</code></td>\n<td><code>GET /api/v1/timelines/public?local=true</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/stream/federated</code></td>\n<td><code>GET /api/v1/timelines/public</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/stream/tag/{hashtag}/</code></td>\n<td><code>GET /api/v1/timelines/tag/{hashtag}</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/stream/direct</code></td>\n<td><code>GET /api/v1/conversations</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/stream/liked</code></td>\n<td><code>GET /api/v1/favourites</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/stream/notifications</code></td>\n<td><code>GET /api/v1/notifications</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/account/{username}/stream</code></td>\n<td><code>GET /api/v1/accounts/{account}/statuses</code></td>\n</tr>\n<tr>\n<td><code>GET /local/v1/post</code>, <code>GET /local/v1/post/replies</code></td>\n<td><code>GET /api/v1/statuses/{nid}</code>, <code>…/context</code></td>\n</tr>\n<tr>\n<td><code>POST</code>/<code>DELETE /api/v1/post/like</code></td>\n<td><code>POST /api/v1/statuses/{nid}/favourite</code>, <code>…/unfavourite</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/current/info</code></td>\n<td><code>GET /api/v1/accounts/verify_credentials</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/current/followers</code>, <code>…/following</code></td>\n<td><code>GET /api/v1/accounts/{account}/followers</code>, <code>…/following</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/global/actor/info</code></td>\n<td><code>GET /api/v1/accounts/{account}</code></td>\n</tr>\n<tr>\n<td><code>GET /api/v1/global/actor/header</code></td>\n<td>the <code>header</code> field of the Account entity</td>\n</tr>\n<tr>\n<td><code>PUT /api/v1/account/summary</code></td>\n<td><code>PATCH /api/v1/accounts/update_credentials</code></td>\n</tr>\n<tr>\n<td><code>GET /local/v1/search</code></td>\n<td><code>GET /api/v2/search</code></td>\n</tr>\n</tbody></table></div>\n<p>The twelve that the frontend still uses -- the banner uploads, the\n<code>global/account</code> and <code>global/tags</code> searches, the profile field and avatar\nendpoints, <code>POST</code>/<code>DELETE /api/v1/post</code> and <code>/api/v1/current/follow</code> -- have no\nMastodon equivalent yet and stay.</p>\n<hr>\n","toc":[{"id":"removed-the-superseded-half-of-the-custom-local-api","text":"Removed: the superseded half of the Custom Local API","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"overview","manual":false,"prev":{"path":"/docs/api-contents","title":"Contents"},"next":{"path":"/docs/api-authentication","title":"Authentication"},"parent":null},{"slug":"api-authentication","path":"/docs/api-authentication","title":"Authentication","description":"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…","group":"api","html":"<p>Two mechanisms exist, and which one applies depends on the controller:</p>\n<ol>\n<li><strong>OAuth Bearer token</strong> — <code>MastodonApiController</code> and <code>TagController</code> read it. The constructor parses the <code>Authorization</code> header, accepts a <code>bearer</code> auth type, and resolves the token through <code>ClientService::getFromToken()</code>. If no bearer token is present it falls back to the logged-in Nextcloud session user. Both declare their routes <code>#[PublicPage]</code> with <code>#[NoCSRFRequired]</code> and then require a viewer inside the handler: a Mastodon client has no Nextcloud session and no CSRF token, so <code>#[NoAdminRequired]</code> would refuse every real caller before the handler ran.</li>\n<li><strong>Nextcloud session</strong> — <code>LocalController</code>, <code>ConfigController</code>, <code>NavigationController</code>, <code>OAuthController</code> (authorize/authorizing) and <code>OStatusController</code> use the session <code>userId</code> only. They do <strong>not</strong> honour bearer tokens, so the Custom Local API is effectively usable only from the app&#39;s own frontend (or with a Nextcloud session cookie / app password + <code>OCS-APIRequest</code>).</li>\n</ol>\n<p>Access control is declared with <strong>PHP attributes</strong> (<code>#[PublicPage]</code>, <code>#[NoCSRFRequired]</code>, <code>#[NoAdminRequired]</code>, and <code>#[BruteForceProtection]</code> on the OAuth token/revoke endpoints); the legacy PHPDoc annotations are gone. The &quot;Auth&quot; column in the tables below records these attributes:</p>\n<ul>\n<li><code>public</code> — <code>#[PublicPage]</code>: reachable without a Nextcloud login (an endpoint may still fail later if it needs a viewer).</li>\n<li><code>user</code> — <code>#[NoAdminRequired]</code>: any logged-in user.</li>\n<li><code>admin</code> — no attribute at all: Nextcloud requires an admin session.</li>\n<li><code>no-csrf</code> — <code>#[NoCSRFRequired]</code>: no CSRF token needed, which matters for non-browser clients.</li>\n</ul>\n<p>The account pages a client app shows — memories, statistics, video channels, the migration exports, imports and move-in, and the authorized apps — are <code>ClientApiController</code> routes like the Mastodon ones: the bearer token a client got from this app&#39;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 <code>OCS-APIRequest: true</code>.</p>\n<h2 id=\"which-credentials-a-route-takes\">Which credentials a route takes</h2>\n<p>One rule decides which sign-in a client sends, so that it is not a choice per route:</p>\n<ul>\n<li><strong>A route that reads or writes the person&#39;s Nextcloud files takes the Nextcloud session</strong>, never this app&#39;s OAuth token: the web app&#39;s session with its CSRF token, or a client&#39;s <strong>Nextcloud app password</strong> (from Login Flow v2) sent as HTTP Basic <strong>together with <code>OCS-APIRequest: true</code></strong>. A bearer token is a <strong>403</strong> whatever its scopes. Without the <code>OCS-APIRequest</code> header Nextcloud holds the request to its CSRF check, which a client cannot pass, and the answer is a <strong>401</strong>. Files are Nextcloud&#39;s business: a client offering them needs the app password for WebDAV and previews anyway.</li>\n<li><strong>Every other route is Social&#39;s own data and takes the Social OAuth token</strong>, 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.</li>\n</ul>\n<p>The Nextcloud-session routes today — <code>tests/DocumentationTest.php</code> holds this table to the routes that refuse every bearer token (<code>WEB_SESSION_ONLY</code> in <code>tests/AppInfo/RouteAuthMatrixTest.php</code>):</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Method</th>\n<th>URL</th>\n<th>Why it takes the Nextcloud session</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>POST</td>\n<td><code>/api/v1/media/from-file</code></td>\n<td>Copies any of the person&#39;s own files into an attachment</td>\n</tr>\n<tr>\n<td>POST</td>\n<td><code>/api/v1/statuses/{nid}/calendar/import</code></td>\n<td>Imports a visible Fediverse event into the signed-in user&#39;s writable Nextcloud calendar; bearer tokens are refused</td>\n</tr>\n</tbody></table></div>\n<p>A route added later that touches the person&#39;s files belongs in this table and in <code>WEB_SESSION_ONLY</code>. Nextcloud&#39;s own APIs — WebDAV (remote.php/dav/files/…), previews, the capabilities, app passwords and push registration through the notifications app — take Nextcloud&#39;s credentials by nature and are not this app&#39;s routes.</p>\n<p>One token route reaches further with the session: <code>DELETE /api/v1/authorized_apps/{id}</code> lets a bearer token revoke only its own authorization, and signing <em>another</em> app out takes the Nextcloud session.</p>\n<p>Note that many client API endpoints are annotated <code>@PublicPage</code> but call <code>initViewer(true)</code> internally, which throws when there is neither a session nor a valid bearer token; those return HTTP 401 with <code>{&quot;error&quot;: &quot;the access_token was revoked&quot;}</code>.</p>\n<p><strong>A Nextcloud user who has not set up their account here.</strong> Accounts are made when the person chooses a username — on the app&#39;s setup page, or on the sign-in page an app opens (<a href=\"/docs/api-oauth#oauth\">OAuth</a>). Until then, every client route that acts for an account and is reached with that person&#39;s Nextcloud session or app password (<code>OCS-APIRequest: true</code>) answers <strong>403</strong> with</p>\n<pre><code class=\"language-json\">{&quot;error&quot;: &quot;Your account is not set up yet. Open Aloha Social in a web browser and choose your username, then try again.&quot;, &quot;code&quot;: &quot;account-not-set-up&quot;, &quot;setup_url&quot;: &quot;https://cloud.example/index.php/apps/social/&quot;}\n</code></pre>\n<p><code>setup_url</code> is the absolute address of the app&#39;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&#39;s language (<code>src/utils/serverError.js</code>). 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 (<code>client_credentials</code>) still answers 401 <code>this token belongs to an app and names no account</code> where a route acts for an account. The admin API needs no account of the administrator&#39;s, and the Bluesky XRPC sign-in takes a Bluesky identity and an app password from the account&#39;s settings, neither of which exists before the account.</p>\n<p><strong>Cross-origin requests (CORS).</strong> A browser client served from another origin (Elk, Phanpy, Pinafore and the like) can call the bearer-token API, as on Mastodon: <code>ClientApiCorsMiddleware</code> answers the <code>/api/</code> routes of <code>MastodonApiController</code>, <code>ClientApiController</code> and <code>AdminApiControllerBase</code>, <code>POST /api/v1/apps</code>, <code>POST /oauth/token</code>, <code>POST /oauth/revoke</code>, <code>GET /oauth/userinfo</code> and the NodeInfo documents with <code>Access-Control-Allow-Origin: *</code>, <code>Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS</code>, <code>Access-Control-Allow-Headers: Authorization, Content-Type, Idempotency-Key</code> and <code>Access-Control-Expose-Headers: Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset</code> — errors included, so a client can read why it was refused. <code>OPTIONS /api/{path}</code> answers the preflight with <strong>204</strong> and the same headers, without authentication, and an endpoint this server does not have is a <strong>404</strong> with them; <code>OPTIONS /oauth/token</code> and <code>/oauth/revoke</code> are answered by the Bluesky preflights below, which allow the same methods and headers a Mastodon client sends. <code>Access-Control-Allow-Credentials</code> 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&#39;s own session routes (<code>LocalController</code>, <code>ConfigController</code> and the other controllers outside the three API bases) answer no other origin.</p>\n<hr>\n","toc":[{"id":"which-credentials-a-route-takes","text":"Which credentials a route takes","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"authentication","manual":false,"prev":{"path":"/docs/api-overview","title":"Overview"},"next":{"path":"/docs/api-mastodon-compatible-api","title":"Mastodon-compatible API"},"parent":null},{"slug":"api-mastodon-compatible-api","path":"/docs/api-mastodon-compatible-api","title":"Mastodon-compatible API","description":"The route-by-route reference for the app's registered API.","group":"api","html":"","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":[{"path":"/docs/api-instance-and-app-metadata","title":"Instance and app metadata","description":"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…","parent":true},{"path":"/docs/api-accounts","title":"Accounts","description":"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…","parent":true},{"path":"/docs/api-search-mastodon-v2","title":"Search (Mastodon v2)","description":"Auth: public, no-csrf (viewer required) · Parameters: q (required), type, limit (20, capped at 40), resolve, account_id, offset, max_id, min_id","parent":true},{"path":"/docs/api-statuses","title":"Statuses","description":"Auth: public, no-csrf (viewer required, write scope) · Parameters: Body (JSON or form-encoded): status, visibility, media_ids (array), in_reply_to_id, quote_id, spoiler_text, sensitive…","parent":true},{"path":"/docs/api-scheduled-statuses","title":"Scheduled statuses","description":"Auth: public, no-csrf (viewer required) · Parameters: limit (20, capped at 40), max_id (0), min_id (0), since_id (0)","parent":true},{"path":"/docs/api-lists","title":"Lists","description":"Auth: public, no-csrf (viewer required, read:lists scope) · Parameters: —","parent":true},{"path":"/docs/api-pixelfeds-own-routes","title":"Pixelfed's own routes","description":"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…","parent":true},{"path":"/docs/api-starter-packs","title":"Starter packs","description":"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…","parent":true},{"path":"/docs/api-finding-people-in-other-servers-directories","title":"Finding people in other servers' directories","description":"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…","parent":true},{"path":"/docs/api-collections","title":"Collections","description":"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…","parent":true},{"path":"/docs/api-places","title":"Places","description":"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…","parent":true},{"path":"/docs/api-stories","title":"Stories","description":"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…","parent":true},{"path":"/docs/api-conversations","title":"Conversations","description":"Auth: public, no-csrf (viewer required, read:statuses or read scope) · Parameters: limit (20, capped at 40), max_id (0), min_id (0), since_id (0)","parent":true},{"path":"/docs/api-keyword-filters","title":"Keyword filters","description":"Auth: public, no-csrf (viewer required, read:filters or read scope) · Parameters: —","parent":true},{"path":"/docs/api-discovery-trends-and-relationships","title":"Discovery, trends and relationships","description":"Auth: public, no-csrf · Parameters: limit (20, capped at 40), offset (0), period (1h, 12h, 1d — the default —, 3d, 10d)","parent":true},{"path":"/docs/api-announcements","title":"Announcements","description":"Auth: public, no-csrf (viewer required, any token — no scope) · Parameters: —","parent":true},{"path":"/docs/api-timelines-and-notifications","title":"Timelines and notifications","description":"Auth: public, no-csrf · Parameters: 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)","parent":true},{"path":"/docs/api-followed-hashtags","title":"Followed hashtags","description":"Auth: public, no-csrf (viewer required, read:follows or read scope) · Parameters: limit (20, capped at 50), max_id (0), min_id (0)","parent":true},{"path":"/docs/api-for-you","title":"For you","description":"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…","parent":true},{"path":"/docs/api-polls","title":"Polls","description":"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…","parent":true},{"path":"/docs/api-link-previews","title":"Link previews","description":"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…","parent":true},{"path":"/docs/api-reports","title":"Reports","description":"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…","parent":true},{"path":"/docs/api-admin-api-mastodon","title":"Admin API (Mastodon)","description":"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…","parent":true},{"path":"/docs/api-media","title":"Media","description":"Auth: public, no-csrf (viewer required, write scope) · Parameters: Multipart: file (required, read from $_FILES['file']), description (the alt text), thumbnail (an image, for a video only)","parent":true},{"path":"/docs/api-search-mastodon-adjacent-app-specific-shapes","title":"Search (Mastodon-adjacent, app-specific shapes)","description":"{\"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…","parent":true},{"path":"/docs/api-pagination","title":"Pagination","description":"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…","parent":true},{"path":"/docs/api-peertubes-own-routes","title":"PeerTube's own routes","description":"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…","parent":true}],"anchor":"mastodon-compatible-api","manual":false,"prev":{"path":"/docs/api-authentication","title":"Authentication"},"next":{"path":"/docs/api-instance-and-app-metadata","title":"Instance and app metadata"},"parent":null},{"slug":"api-instance-and-app-metadata","path":"/docs/api-instance-and-app-metadata","title":"Instance and app metadata","description":"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…","group":"api","html":"<h2 id=\"options-api-path\">OPTIONS /api/{path}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The CORS preflight of any client-API call from another origin: <strong>204</strong> with the headers described under <strong>Cross-origin requests (CORS)</strong>, 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 <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code> or <code>DELETE</code> the same address is a <strong>404</strong> <code>{&quot;error&quot;: &quot;Not found&quot;}</code> 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 <code>appinfo/routes.php</code>, after every other route, and answer only what no route takes.</p>\n<h2 id=\"get-api-v1-instance\">GET /api/v1/instance/</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Mastodon&#39;s <code>V1::Instance</code> entity, built by <code>InstanceService::getLocal()</code> from the live configuration on every request (the stored row is written once at install and only marks that the instance exists). Carries <code>uri</code>, <code>title</code>, <code>version</code>, <code>short_description</code>, <code>description</code>, <code>email</code>, <code>urls</code>, <code>vapid_key</code>, <code>stats</code>, <code>thumbnail</code>, <code>languages</code>, <code>registrations</code> (always <code>false</code> — the client API cannot create an account), <code>approval_required</code>, <code>invites_enabled</code>, <code>configuration</code>, <code>rules</code> and <code>contact_account</code>. <code>vapid_key</code> is the stable instance VAPID public key for older Mastodon clients; newer clients can read the same key from <code>configuration.vapid.public_key</code>. <code>urls.streaming_api</code> is <code>wss://&lt;host&gt;</code>; 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. <code>thumbnail</code> 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. <code>urls</code>, <code>stats</code> and <code>configuration</code> are always JSON <strong>objects</strong>, never <code>[]</code>. <code>configuration</code> reports <code>statuses</code> (<code>max_characters</code> 5000, <code>max_media_attachments</code>, <code>characters_reserved_per_url</code>), <code>media_attachments</code> (<code>supported_mime_types</code>, asked of <code>CacheDocumentService::filterMimeTypes()</code> so it cannot drift from what an upload is actually allowed to be, plus <code>image_size_limit</code> (<code>max_size</code>) and <code>video_size_limit</code> (<code>max_video_size</code>), in bytes, each lowered to PHP&#39;s own upload limit (<code>\\OCP\\Util::uploadLimit()</code>, the smaller of <code>upload_max_filesize</code> and <code>post_max_size</code>) when that is smaller, since PHP refuses a larger file before the app sees it — and the pixel/frame-rate ceilings), <code>polls</code> (<code>max_options</code>, <code>max_characters_per_option</code>, the expiry bounds), <code>accounts.max_featured_tags</code> and <code>vapid.public_key</code> (the same stable public key). Clients can fall back to polling when the streaming daemon is unavailable. <code>stats.status_count</code> and <code>stats.domain_count</code> are counted from the database and memoised for a few minutes (<code>InstanceService::countedStats()</code>); <code>user_count</code> 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. <code>rules</code> comes from one line per rule in the <code>rules</code> app value. The <code>version</code> field is Pleroma-style — <code>4.3.0 (compatible; Aloha Social &lt;app version&gt;)</code>, from <code>Instance::COMPAT_VERSION</code> — because clients gate features on it; NodeInfo keeps reporting the real app version. <code>configuration.translation.enabled</code> is <code>true</code> only where this Nextcloud has a translation provider (<code>TranslationService</code>).</p>\n<h2 id=\"get-api-v1-instance-rules\">GET /api/v1/instance/rules</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The instance&#39;s rules, as Mastodon&#39;s <code>Rule</code> entities. They were already served <em>inside</em> the instance entity, out of the <code>rules</code> app value (<code>occ config:app:set social rules --value &quot;...&quot;</code>), so the data was here and the route a client reads it from was a 404. An instance that has set none answers <code>[]</code>, which is the truthful answer rather than an error.</p>\n<h2 id=\"get-api-v1-instance-domain-blocks\">GET /api/v1/instance/domain_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The instances this one has decided not to federate with, as <code>{domain, digest, severity, comment}</code>. <strong><code>[]</code> unless an admin opts in</strong> with <code>occ config:app:set social publish_blocks --value 1</code>: Mastodon publishes the list so somebody choosing a server can see who it will not talk to, and whether <em>this</em> 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 <em>does</em> talk to, and publishing that as a block list would be exactly backwards, so that mode answers <code>[]</code> too. <code>severity</code> is always <code>suspend</code> (the only one this list has) and <code>comment</code> always <code>&quot;&quot;</code> (not stored).</p>\n<h2 id=\"get-api-v1-instance-extended-description\">GET /api/v1/instance/extended_description</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The long form of what this instance is, as <code>{updated_at, content}</code>, from the <code>extended_description</code> 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.</p>\n<h2 id=\"get-api-v1-instance-translation-languages\">GET /api/v1/instance/translation_languages</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>For each language this server can translate <em>from</em>, the languages it can translate <em>to</em>, as Mastodon&#39;s <code>{&quot;de&quot;: [&quot;en&quot;, …]}</code>. Read from the translation provider Nextcloud has, so it is this server&#39;s truth rather than a list written here; a server with no provider answers <code>{}</code>, which is the same thing <code>configuration.translation.enabled: false</code> says.</p>\n<h2 id=\"get-api-v1-instance-privacy-policy\">GET /api/v1/instance/privacy_policy</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The server&#39;s privacy policy as <code>{updated_at, content}</code>. Nextcloud&#39;s own, from Theming&#39;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&#39;s entity carries text, so the content is that link. <strong>404</strong> where the administrator has published none.</p>\n<h2 id=\"get-api-v1-instance-terms-of-service\">GET /api/v1/instance/terms_of_service</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The same, from Theming&#39;s legal notice link. <strong>404</strong> where none is set.</p>\n<h2 id=\"get-api-oembed\">GET /api/oembed</h2>\n<p><strong>Auth: </strong>public, no-csrf, rate-limited · <strong>Parameters: </strong><code>url</code> (required), <code>format</code> (<code>json</code>)</p>\n<p>Rich oEmbed for one of this server&#39;s own <strong>public</strong> posts. Its iframe targets <code>/@{username}/{token}/embed</code>, a minimal page whose only framing exception is scoped to that endpoint. Unlisted, followers-only and remote posts are a <strong>404</strong>; a <code>format</code> other than <code>json</code> is a <strong>501</strong>, as oEmbed prescribes.</p>\n<h2 id=\"get-api-v2-instance\">GET /api/v2/instance</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The same facts as Mastodon&#39;s <code>V2::Instance</code>: <code>uri</code> becomes <code>domain</code>, <code>thumbnail</code> an object (null when there is no picture, never <code>{&quot;url&quot;: &quot;&quot;}</code>), <code>urls.streaming_api</code> becomes <code>configuration.urls.streaming</code>, and the flat contact/registration fields move under <code>contact</code> and <code>registrations</code>. It also adds <code>source_url</code>, <code>usage</code> and <code>api_versions</code> — <code>{&quot;mastodon&quot;: 3, &quot;aloha_social&quot;: 1}</code>, the second being this app&#39;s own generation (1: <code>/api/v2/search</code> honours <code>account_id</code> and pages <code>statuses</code>) — and folds <code>urls</code> and a <code>translation</code> block into <code>configuration</code>, whose <code>media_attachments</code> size limits are v1&#39;s, PHP&#39;s upload limit included. Newer clients ask for this one first and only fall back to v1 on a 404.</p>\n<h2 id=\"get-api-v1-instance-peers\">GET /api/v1/instance/peers</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The hostnames of every instance this one has heard of, as a bare JSON array — what instance browsers and &quot;about this server&quot; pages read. Derived from the accounts of the cached remote actors, and from the same walk <code>stats.domain_count</code> uses, so the list and its size cannot disagree. Public, as Mastodon&#39;s is: it says who this instance federates with, not who its users are. Rate-limited per anonymous caller.</p>\n<h2 id=\"get-api-v1-instance-activity\">GET /api/v1/instance/activity</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Twelve weeks of activity, newest first, in Mastodon&#39;s shape — every value a string, each week keyed by the unix time its Monday began. <code>statuses</code> is counted from the database. <code>logins</code> and <code>registrations</code> are always <code>&quot;0&quot;</code> 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.</p>\n<h2 id=\"get-api-v1-preferences\">GET /api/v1/preferences</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s posting defaults, as Mastodon&#39;s Preferences entity: <code>posting:default:visibility</code> (the account&#39;s <code>source[privacy]</code>), <code>posting:default:sensitive</code>, <code>posting:default:language</code> (null when unset), and the two reading preferences. <code>reading:expand:media</code> is <strong>real</strong>: it is this account&#39;s choice about media somebody marked sensitive, or what the instance does for somebody who has not chosen (<code>nsfw_policy</code>). Its three values are PeerTube&#39;s three NSFW policies under the names Mastodon already has for the same three states — <code>show_all</code> is PeerTube&#39;s <em>display</em>, <code>default</code> its <em>blur</em> (covered, blurhash showing, one press away) and <code>hide_all</code> its <em>hide</em> (not drawn, and no button to draw it: opening the post is what it takes). <code>reading:expand:spoilers</code> is still Mastodon&#39;s <code>false</code> — 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. <strong>Nextcloud extension:</strong> <code>notifications:delivery</code> echoes the account&#39;s notification delivery setting, the same object <code>GET /api/v1/social/notification_delivery</code> answers; read-only here, written there. <code>reading:hide:ai</code> (bool) echoes whether the account hides posts made with AI, the switch <code>GET /api/v1/social/ai_content</code> answers and <code>PATCH</code> sets; read-only here too. <code>reading:hide:counts</code> (bool) echoes whether the like, boost and follower numbers are hidden (<code>/api/v1/social/counts</code>), read-only here as well.</p>\n<h2 id=\"put-api-v1-preferences\">PUT /api/v1/preferences</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>expand_media</code> (<code>show_all</code>, <code>default</code>, <code>hide_all</code>, or <code>&#39;&#39;</code>)</p>\n<p><strong>Nextcloud extension, not a Mastodon route</strong> — Mastodon has no write for preferences and sets its own reading preferences on its web front end. The values are Mastodon&#39;s all the same, so a client that reads the route above and one that writes here agree about what the three words mean. <code>&#39;&#39;</code> is a fourth thing and not a fourth policy: it puts the account back to <em>following the instance</em>, 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 <code>choice</code> behind it (<code>&#39;&#39;</code> for following the instance) and the <code>instance</code> default. Anything else is a <strong>422</strong>.</p>\n<h2 id=\"get-api-v1-apps-verify-credentials\">GET /api/v1/apps/verify_credentials</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p><code>{&quot;name&quot;, &quot;website&quot;, &quot;scopes&quot;, &quot;redirect_uris&quot;, &quot;vapid_key&quot;}</code> of the client behind the bearer token (<code>scopes</code> and <code>redirect_uris</code> are lists, as on Mastodon 4.3); falls back to <code>{&quot;name&quot;: &quot;Aloha Social&quot;, &quot;website&quot;: &quot;https://github.com/alohasocial/social/&quot;}</code> when the caller is the app&#39;s own session. <code>vapid_key</code> is the instance&#39;s stable public VAPID key. A missing or revoked token is a 401.</p>\n<h2 id=\"get-api-v1-push-subscription\">GET /api/v1/push/subscription</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>push</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The subscription for the caller&#39;s bearer token as <code>{id, endpoint, standard, alerts, server_key, policy}</code>. A token without a subscription receives 404.</p>\n<h2 id=\"post-api-v1-push-subscription\">POST /api/v1/push/subscription</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>push</code> scope) · <strong>Parameters: </strong><code>subscription.endpoint</code>, <code>subscription.keys.p256dh</code>, <code>subscription.keys.auth</code>, optional <code>subscription.standard</code>; <code>data.alerts</code>, <code>data.policy</code></p>\n<p>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 <code>server_key</code> and <code>policy</code>; the bearer token is never returned.</p>\n<h2 id=\"put-api-v1-push-subscription\">PUT /api/v1/push/subscription</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>push</code> scope) · <strong>Parameters: </strong><code>data.alerts</code>, <code>data.policy</code></p>\n<p>Updates only alert preferences and policy for the caller&#39;s existing subscription. A token without a subscription receives 404.</p>\n<h2 id=\"delete-api-v1-push-subscription\">DELETE /api/v1/push/subscription</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>push</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes the caller&#39;s subscription and returns <code>{}</code>; deleting an absent subscription is also successful.</p>\n<h2 id=\"get-api-v1-custom-emojis\">GET /api/v1/custom_emojis</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The emoji this instance publishes, as Mastodon&#39;s <code>CustomEmoji</code>: <code>shortcode</code>, <code>url</code>, <code>static_url</code>, <code>visible_in_picker</code>, and <code>category</code> 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. <code>static_url</code> is the same URL as <code>url</code>: a second, still rendering of every upload does not exist, and a <code>static_url</code> pointing at nothing would be worse than one pointing at the picture. Managed with <code>occ social:emoji</code>. <em>Remote</em> custom emoji are unaffected and always worked: <code>Emoji</code> tags on incoming statuses and actors are served in the <code>emojis</code> field of the status and account entities.</p>\n<h2 id=\"get-emoji-shortcode\">GET /emoji/{shortcode}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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 <code>/media/{uuid}</code> is: this is what a remote server dereferences out of an <code>Emoji</code> 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 <strong>404</strong>.</p>\n<h2 id=\"get-api-v1-trends-tags\">GET /api/v1/trends/tags</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (10, capped at 20), <code>period</code> (<code>1h</code>, <code>12h</code>, <code>1d</code> — the default —, <code>3d</code>, <code>10d</code>; anything else falls back to the default)</p>\n<p>The hashtags used most on this instance in that window, as Mastodon <code>Tag</code> entities. The counts are the ones the cron job already keeps for every hashtag (<code>HashtagService::manageHashtags()</code>), so this is a read of stored data rather than a query over the stream — specifically the sortable <code>trend_*</code> columns, which <code>Version1000Date20260910000003</code> backfills on upgrade because the cron alone would never have filled them for hashtags whose counts had stopped moving. <code>history</code> carries a single bucket for the window that was asked for, and <code>accounts</code> in it is always <code>0</code>: this instance counts uses, not distinct accounts. Hashtags unused in the window are left out.</p>\n<h2 id=\"get-api-saved-searches-list-json\">GET /api/saved_searches/list.json</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p><strong>Not implemented.</strong> Initialises the viewer, then always returns <code>[]</code>.</p>\n<h2 id=\"get-well-known-nodeinfo-2-0\">GET /.well-known/nodeinfo/2.0</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>NodeInfo 2.0 document: <code>version</code>, <code>software.name</code> (<code>nextcloud-social</code>), <code>software.version</code>, <code>protocols: [&quot;activitypub&quot;]</code>, <code>services</code>, <code>usage</code> (<code>users.total</code>, <code>localPosts</code>), <code>openRegistrations</code> and <code>metadata</code> (<code>nodeName</code>, the instance title, and <code>nodeDescription</code>). Falls back to node name <code>Aloha Social</code>, the installed app version and <code>usage: {&quot;users&quot;: {}}</code> — an object, as the schema requires — if no local instance row exists.</p>\n<h2 id=\"get-well-known-nodeinfo-2-1\">GET /.well-known/nodeinfo/2.1</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The same document under the 2.1 schema, which adds <code>software.repository</code> and <code>software.homepage</code> (both the app&#39;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.</p>\n","toc":[{"id":"options-api-path","text":"OPTIONS /api/{path}","level":2},{"id":"get-api-v1-instance","text":"GET /api/v1/instance/","level":2},{"id":"get-api-v1-instance-rules","text":"GET /api/v1/instance/rules","level":2},{"id":"get-api-v1-instance-domain-blocks","text":"GET /api/v1/instance/domain_blocks","level":2},{"id":"get-api-v1-instance-extended-description","text":"GET /api/v1/instance/extended_description","level":2},{"id":"get-api-v1-instance-translation-languages","text":"GET /api/v1/instance/translation_languages","level":2},{"id":"get-api-v1-instance-privacy-policy","text":"GET /api/v1/instance/privacy_policy","level":2},{"id":"get-api-v1-instance-terms-of-service","text":"GET /api/v1/instance/terms_of_service","level":2},{"id":"get-api-oembed","text":"GET /api/oembed","level":2},{"id":"get-api-v2-instance","text":"GET /api/v2/instance","level":2},{"id":"get-api-v1-instance-peers","text":"GET /api/v1/instance/peers","level":2},{"id":"get-api-v1-instance-activity","text":"GET /api/v1/instance/activity","level":2},{"id":"get-api-v1-preferences","text":"GET /api/v1/preferences","level":2},{"id":"put-api-v1-preferences","text":"PUT /api/v1/preferences","level":2},{"id":"get-api-v1-apps-verify-credentials","text":"GET /api/v1/apps/verify_credentials","level":2},{"id":"get-api-v1-push-subscription","text":"GET /api/v1/push/subscription","level":2},{"id":"post-api-v1-push-subscription","text":"POST /api/v1/push/subscription","level":2},{"id":"put-api-v1-push-subscription","text":"PUT /api/v1/push/subscription","level":2},{"id":"delete-api-v1-push-subscription","text":"DELETE /api/v1/push/subscription","level":2},{"id":"get-api-v1-custom-emojis","text":"GET /api/v1/custom_emojis","level":2},{"id":"get-emoji-shortcode","text":"GET /emoji/{shortcode}","level":2},{"id":"get-api-v1-trends-tags","text":"GET /api/v1/trends/tags","level":2},{"id":"get-api-saved-searches-list-json","text":"GET /api/saved_searches/list.json","level":2},{"id":"get-well-known-nodeinfo-2-0","text":"GET /.well-known/nodeinfo/2.0","level":2},{"id":"get-well-known-nodeinfo-2-1","text":"GET /.well-known/nodeinfo/2.1","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"instance-and-app-metadata","manual":false,"prev":{"path":"/docs/api-mastodon-compatible-api","title":"Mastodon-compatible API"},"next":{"path":"/docs/api-accounts","title":"Accounts"},"parent":"api-mastodon-compatible-api"},{"slug":"api-accounts","path":"/docs/api-accounts","title":"Accounts","description":"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…","group":"api","html":"<p>A Status entity carries <strong><code>view_count</code></strong> — how many accounts here have opened that post&#39;s own page — on the <strong>author&#39;s own copy only</strong>, and <code>null</code> on everybody else&#39;s: how many people read a post is the author&#39;s business. What is counted is narrow on purpose: a post&#39;s own page (<code>GET /api/v1/statuses/{nid}</code>), 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&#39;s readers added to this one&#39;s, meaning neither.</p>\n<p>A Status entity&#39;s <strong><code>uri</code> and <code>url</code> are two different things</strong>, as they are in Mastodon&#39;s: <code>uri</code> is the ActivityPub object, <code>url</code> is the page a person can open. They used to be the same value here, which sent &quot;open original&quot; to a JSON document for every remote post. Loops makes the difference plain — its ids live under <code>/ap/</code> and a video is only watchable at <code>loops.video/v/&lt;id&gt;</code> — but Mastodon, Pixelfed and PeerTube all send a distinct <code>url</code> too. It is read off the wire, kept in the row&#39;s <code>details</code> (<code>social_stream</code> has no column for it), and falls back to the id, so a local post — whose id <em>is</em> its page — is unchanged. Only <code>http</code>/<code>https</code> count: <code>AS_URL</code> used to validate with <code>parse_url()</code>, which parses <code>javascript:alert(1)</code> into a scheme and a path quite happily, and this field is rendered as a link by every client that reads it.</p>\n<p>An incoming <strong><code>interactionPolicy.canQuote</code></strong> is honoured. GoToSocial defined the field, Mastodon 4.5 reads it and Loops publishes it on every video; <code>automaticApproval</code> naming the public collection means anyone may quote, anything narrower is treated as &quot;ask the author&quot; 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. <strong><code>canReply</code>, <code>canAnnounce</code> and <code>canLike</code> are honoured too</strong>, by the same rule and for the same reason, except that a narrower list is still a yes for whom it names: <code>automaticApproval</code> naming the public collection means anyone may; naming the reader, the author&#39;s followers collection when the reader follows the author, or the author&#39;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 &quot;ask the author&quot;, 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 <code>interaction_policy</code> — <code>{&quot;reply&quot;: true, &quot;like&quot;: false}</code> — so a client can leave a button out rather than draw one that will fail. It is <strong>absent</strong> for a local post, where the policy is this instance&#39;s to apply when the interaction arrives, and for the many servers that publish no policy at all: an absent key means &quot;the author said nothing&quot;, which means yes. Taking an interaction back is never refused, whatever the policy says now — an <code>Undo</code> is how this instance stops having sent one.</p>\n<p>A Status entity also carries <strong><code>archived</code></strong>, which is true only on the author&#39;s own archived posts — nobody else is ever handed one, because no list this server builds contains one.</p>\n<p>A Status entity also carries <strong><code>video_card</code></strong> — <strong>Aloha Social&#39;s own</strong>, the same few facts about every video post whatever it arrived as, which is what the web interface&#39;s Videos page draws its cards from. <code>null</code> on every post that is not a video; a video is a post that arrived as a PeerTube <code>Video</code> (it has a <code>video</code> block) or carries an attachment served as <code>video/*</code>, the same rule the dislike button follows. On a boost it is on the boosted post in <code>reblog</code>. Every key is always present:</p>\n<h2 id=\"title\">title</h2>\n<p><strong>Type: </strong>string</p>\n<p>The video&#39;s own title (<code>video.title</code>); 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. <code>&#39;&#39;</code> for a post with no words at all.</p>\n<h2 id=\"duration\">duration</h2>\n<p><strong>Type: </strong>integer or null</p>\n<p>How long it runs, in whole seconds: <code>video.duration</code>, else the video attachment&#39;s <code>meta.duration</code>. <code>null</code> when neither says.</p>\n<h2 id=\"thumbnail\">thumbnail</h2>\n<p><strong>Type: </strong>string or null</p>\n<p>A picture of it: the video attachment&#39;s <code>preview_url</code> — the poster frame of an upload here, the thumbnail a PeerTube video publishes. <code>null</code> when there is none, including when <code>preview_url</code> is the video file itself, as it is for an older upload with no poster.</p>\n<h2 id=\"views\">views</h2>\n<p><strong>Type: </strong>integer or null</p>\n<p>How many times it was watched. For a video posted here, this server&#39;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 (<code>POST /api/v1/statuses/{nid}/view</code>), the author not counted; <code>0</code> when nobody has watched it yet. For a video from elsewhere, as its origin counts it (<code>video.views</code>). <code>null</code> when nobody counted — never invented, and never this instance&#39;s <code>view_count</code>, which only the author is told — and <code>null</code> for a reader who hides the numbers (<code>/api/v1/social/counts</code>).</p>\n<h2 id=\"live\">live</h2>\n<p><strong>Type: </strong>boolean</p>\n<p>A live broadcast (<code>video.live</code>).</p>\n<h2 id=\"category\">category</h2>\n<p><strong>Type: </strong>string or null</p>\n<p>Its category, as its origin names it (<code>video.category</code>); <code>null</code> when it has none.</p>\n<h2 id=\"published\">published</h2>\n<p><strong>Type: </strong>string</p>\n<p>When the video was published, in <code>created_at</code>&#39;s format: <code>video.originally_published_at</code> where it is there and can be read, else <code>created_at</code>.</p>\n<p>The channel is the status&#39;s own <code>account</code> and is not repeated. The attachment that is the video is the first of <code>type</code> <code>video</code> in <code>media_attachments</code>, else the first served as <code>video/*</code>; <code>duration</code> and <code>thumbnail</code> 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.</p>\n<p>A Status entity also carries <strong><code>watch_progress</code></strong> — <strong>Aloha Social&#39;s own</strong> — <code>{position, duration, updated_at}</code>: where in a video the reader stopped, in seconds, out of how many, and when it was last moved (in <code>created_at</code>&#39;s format, or <code>null</code>). On the statuses <code>GET /api/v1/videos/continue</code> answers, and on a video read on its own with <code>GET /api/v1/statuses/{nid}</code> by a signed-in reader who began it, which is where a player starts it again; <code>null</code> on every other list. It is the reader&#39;s own and is never federated.</p>\n<p>The <strong><code>video</code></strong> block — what a post that arrived as a PeerTube <code>Video</code> (or was posted here with a video title) says about the video, <code>null</code> on every other post — carries two things that are this server&#39;s rather than the origin&#39;s. On a video posted here, <code>views</code> is the count described under <code>video_card</code> above. And each of its subtitle tracks, <code>captions: [{language, url}]</code>, has as its <code>url</code> this server&#39;s <code>/media/captions/{nid}/{index}.vtt</code>, never the origin&#39;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 <code>views</code>.</p>\n<p>A Status entity&#39;s <strong><code>muted</code></strong> is real and per viewer: <code>true</code> when the viewer muted the conversation the post belongs to (<code>POST /api/v1/statuses/{nid}/mute</code>, below), else <code>false</code>; anonymous readers always get <code>false</code>. It used to be hard-coded <code>false</code>, so no client could show or toggle the state. It is computed for a whole page in one pass by <code>StreamRequestBuilder::markMutedConversations()</code>: the page&#39;s reply chains are walked up to their roots and compared with the viewer&#39;s muted roots in <code>social_convo_state</code>. Those roots are memoised for the request, and every mute or unmute drops the memo first (<code>ConversationsRequest::setMuted()</code>), so the status a mute answers with already says <code>muted: true</code>.</p>\n<p><strong>Two of the four profile fields are also sent as their own keys.</strong> An Account\nentity carries <code>pronouns</code> and <code>support_link</code> beside <code>fields</code>. Neither is a\nfield of its own and deliberately so: a pronoun row is what people already\nwrite, it federates as a <code>PropertyValue</code> that every other network shows, and a\nproperty only this app understood would be a pronoun nobody else could read.\nWhat this app adds is <em>recognising</em> the row — matched case-insensitively\nagainst the spellings people use (<code>Pronouns</code>, <code>Pronomen</code>, <code>pronoms</code>, … and\n<code>Support</code>, <code>Donate</code>, <code>Sponsor</code>, …) — so that a client can draw the pronouns\nbeside the name and the support address as a button without knowing any of\nthem. <code>pronouns</code> is <code>&#39;&#39;</code> when the value is longer than 40 characters (a\nsentence in the wrong row), and <code>support_link</code> is <code>&#39;&#39;</code> unless the value is an\n<code>https://</code> URL, because it is drawn as a button.</p>\n<p><strong>An Account entity says where it is on Bluesky.</strong> <code>bluesky</code> is <code>null</code> for\nan account that is not on Bluesky; for a Bluesky account read here it is\n<code>{handle, did, url, native: true, verified, verified_by, verified_by_bluesky, trusted_verifier}</code> — whether Bluesky shows the account as verified (a\ntrusted verifier vouched for it and the AppView judges that valid), the DIDs\nof the verifiers, whether Bluesky&#39;s own account is one of them, and whether\nthe account is a trusted verifier itself. A local account&#39;s carries its own\nhandle and DID where the controllers that know them attach them.</p>\n<p><strong>An Account entity says whether this instance verified it.</strong>\n<code>verification</code> is <code>null</code> for an account the instance did not verify; for one\nit did (<code>VerificationService</code>), it is <code>{by, issuer, created_at}</code>: the name\nthe check is given in (the administrator&#39;s verifying account, or the\ninstance&#39;s own name when none is chosen), the DID that issued the published\n<code>app.bsky.graph.verification</code> record (<code>&#39;&#39;</code> when none was: no verifying\naccount, Bluesky off, or the account has no DID), and when. The app draws one\ncheck beside the name of an account verified either way — by this instance\nor by the verifiers Bluesky trusts (<code>bluesky.verified</code>) — labelled with who\nverified it.</p>\n<p><strong>An Account entity says whether its pictures are placeholders.</strong>\n<code>avatar_default</code> and <code>header_default</code> are <code>true</code> when <code>avatar</code> or <code>header</code> is\na placeholder rather than a picture the account set: Nextcloud&#39;s own avatar\nroute for a local account without an uploaded picture, the app icon for a\nremote account whose picture is missing or not cached yet, and\n<code>img/header-missing.png</code> (a plain 1500×500 PNG, as Mastodon&#39;s <code>missing.png</code>)\nfor an account without a banner. They are on every Account entity,\n<code>verify_credentials</code> and <code>update_credentials</code> included; <code>avatar</code> and <code>header</code>\nstay URLs, so a client that does not know the keys draws what it drew before.</p>\n<p><strong>An Account entity names the Nextcloud user of a local account.</strong>\n<code>nextcloud_user</code> is the user id a local account belongs to, which its username\nneed not be: the username is chosen when the account is made. The web app\ndraws the account&#39;s face and links its Nextcloud profile page (<code>/u/{uid}</code>) by\nit. It is <code>null</code> for a remote account, a team account and a channel, and, for a\nreader who is not signed in, for an account whose username is not its user id,\nso an account named apart from its login does not give the login away. For the\nsame reason a local account&#39;s <code>avatar</code> — and the <code>icon</code> of its actor document —\nis this app&#39;s avatar route of the username, <code>/apps/social/avatar/{username}/128</code>\n(with <code>?v={version}</code> once the picture is cached), never Nextcloud&#39;s own\n<code>/avatar/{user id}/…</code>; an icon stored before under Nextcloud&#39;s route is\npublished under this one, keeping its version.\nWithout them a client could only guess from the shape of the URL, which\ndepends on URL rewriting, the app folder and the size argument. A local\naccount&#39;s header that is its own avatar — what the header used to fall back\nto, kept by the cached copy — counts as no header and is removed from the\ncache by the <code>ClearAvatarHeaders</code> repair step.</p>\n<h2 id=\"get-api-v1-accounts-verify-credentials\">GET /api/v1/accounts/verify_credentials</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s <code>Person</code> actor serialised in local format, with <code>source</code> and Mastodon&#39;s <code>role</code> (see <a href=\"/docs/api-admin-api-mastodon#admin-api-mastodon\">Admin API</a> for what the role says). 401 <code>{&quot;error&quot;: ...}</code> when unauthenticated.</p>\n<h2 id=\"patch-api-v1-accounts-update-credentials\">PATCH /api/v1/accounts/update_credentials</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>JSON, form or multipart body; <code>display_name</code>, <code>note</code>, <code>locked</code>, <code>discoverable</code>, <code>indexable</code>, <code>bot</code>, <code>source[privacy]</code>, <code>fields_attributes</code>, and <code>avatar</code> / <code>header</code> (multipart)</p>\n<p>Sets the display name, the bio (<code>note</code>, at most 500 characters, stored as plain text and rendered to HTML on the way out — an absent <code>note</code> leaves the stored one alone rather than clearing it), the profile picture and banner, whether new followers need manual approval (<code>manuallyApprovesFollowers</code>), whether the account may be listed in directories and indexed for search, whether it is automated (<code>bot</code>, which also decides whether the actor document says <code>Service</code> or <code>Person</code>), 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 <code>[]</code> 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. <strong><code>display_name</code>, <code>avatar</code> and <code>bot</code> used to be accepted and dropped</strong>, 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 <strong>422</strong> 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 (<code>MultipartBodyService</code>); 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, <code>the avatar is larger than this server accepts (2 MB)</code> — or cut off), are a <strong>422</strong>; a picture the server itself could not receive (no temporary directory, a failed disk write) is a <strong>500</strong> naming that problem; in each case nothing else in the request is written. <strong>A save is all or nothing, or a 200 with what it stored</strong>: everything that can be refused — the pictures&#39; arrival, an avatar that is not a JPEG, PNG, GIF or WebP, a name or avatar the backend owns, an unknown <code>source[privacy]</code> — 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, <code>locked</code>, 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&#39;s own profile listener failing after the backend stored it — core re-validates the profile&#39;s <code>fediverse</code> property on every change by fetching that handle&#39;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 <code>verify_credentials</code> that carries <code>source</code>.</p>\n<h2 id=\"delete-api-v1-profile-avatar\">DELETE /api/v1/profile/avatar</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes the account&#39;s picture, leaving Nextcloud&#39;s generated initials, and answers the refreshed account entity. A local account&#39;s picture is this app&#39;s avatar route of the username with the avatar&#39;s version in the address (<code>…/apps/social/avatar/{username}/128?v={version}</code>), 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 <code>Update</code>, whether it was made here or in Nextcloud&#39;s own settings. (A remote account whose picture is not cached yet shows the app icon.) <code>update_credentials</code> can only replace one picture with another — multipart has no way to send &quot;none&quot; — so without this a client can offer &quot;change picture&quot; and not &quot;remove picture&quot;. The avatar is the Nextcloud account&#39;s, so a backend that owns it (LDAP, SAML) makes this a <strong>422</strong> rather than a silent success. Removing a picture that was never set is not an error.</p>\n<h2 id=\"delete-api-v1-profile-header\">DELETE /api/v1/profile/header</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes the banner and federates the actor <code>Update</code>, 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.</p>\n<h2 id=\"get-api-v1-follow-requests\">GET /api/v1/follow_requests</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>limit</code> (default 40, at most 80), <code>max_id</code>, <code>min_id</code></p>\n<p>Accounts with a pending follow request towards the viewer, newest request first, serialised in local format. Paged as Mastodon pages it, with a <code>Link</code> header (<code>rel=&quot;next&quot;</code> while a page came back full, <code>rel=&quot;prev&quot;</code>); as in Mastodon the cursor is the follow request&#39;s, not the account&#39;s, and is to be taken from that header. It is the request&#39;s place in the order — its creation second and the row&#39;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.</p>\n<h2 id=\"post-api-v1-follow-requests-id-authorize\">POST /api/v1/follow_requests/{id}/authorize</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>follow</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Accepts the pending follow request from account <code>{id}</code> (numeric id or full actor id; accepts slashes): federates the <code>Accept</code> and marks the follow accepted. Returns the updated relationship entity; 404 when no request is pending.</p>\n<h2 id=\"post-api-v1-follow-requests-id-reject\">POST /api/v1/follow_requests/{id}/reject</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>follow</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Rejects the pending follow request from account <code>{id}</code>: federates a <code>Reject</code> and deletes the follow row. Returns the updated relationship entity; 404 when no request is pending.</p>\n<h2 id=\"post-api-v1-accounts-id-remove-from-followers\">POST /api/v1/accounts/{id}/remove_from_followers</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:follows</code> or <code>follow</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes account <code>{id}</code> from the viewer&#39;s followers (numeric id, actor id or handle; accepts slashes): federates a <code>Reject</code> 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 <strong>not</strong> a block and <strong>not</strong> 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.</p>\n<h2 id=\"get-api-v1-blocks\">GET /api/v1/blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>limit</code> (40, capped at 50)</p>\n<p>Accounts the viewer has blocked. One page, and <strong>no <code>Link</code> header</strong>: neither route takes a cursor, so the &quot;next&quot; page a header advertised was the page just sent, and a client paging on it scrolled the same block of accounts for ever.</p>\n<h2 id=\"get-api-v1-mutes\">GET /api/v1/mutes</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>limit</code> (40, capped at 50)</p>\n<p>Accounts the viewer has muted. Same shape, and no <code>Link</code> header, for the same reason.</p>\n<h2 id=\"get-api-v1-accounts-relationships\">GET /api/v1/accounts/relationships</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>id</code> (array, default <code>[]</code>)</p>\n<p>Relationship entries from <code>FollowService::getRelationships()</code>. Sent as <code>id[]=…</code> on the wire. The parameter carries a default because the dispatcher fills it in before the handler&#39;s own error handling can run: a request with no <code>id[]</code> at all used to produce a Nextcloud HTML page instead of <code>{&quot;error&quot;: …}</code>. With none given the answer is an empty list.</p>\n<h2 id=\"post-api-v1-accounts-id-follow\">POST /api/v1/accounts/{id}/follow</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>follow</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>notify</code>, <code>reblogs</code></p>\n<p>Follows the account (<code>{id}</code> is the numeric id or a full actor id; accepts slashes). A locked target leaves the relationship in <code>requested</code> until they decide. <code>notify</code> is the bell on a profile — a subscription separate from the follow, so that every post by that account raises a <code>status</code> notification; <strong>absent means &quot;leave it as it is&quot;</strong>, because a client re-following to change something else must not silently turn the bell off. It is reported back as <code>notifying</code> on the relationship, which was hardcoded <code>false</code> 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 &quot;tell me when they post&quot;, and a thread somebody else started is not that. <code>reblogs</code> is the other switch Mastodon sends with a follow — <code>false</code> keeps that account&#39;s <strong>boosts</strong> out of the home and list timelines while leaving their own posts where they are (&quot;I want to read you, not what you pass on&quot;), and it too is left alone when absent. It is reported back as <code>showing_reblogs</code>, which was hardcoded <code>true</code> before, so a client that had turned the boosts off was told they were on. Stored as a row in <code>social_actor_relation</code> only when the answer is <em>no</em>, and applied as a predicate of the timeline query rather than by dropping rows after the page was read. Returns the updated relationship entity.</p>\n<h2 id=\"post-api-v1-accounts-id-unfollow\">POST /api/v1/accounts/{id}/unfollow</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>follow</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Unfollows (federates <code>Undo{Follow}</code>). Returns the updated relationship entity.</p>\n<h2 id=\"post-api-v1-accounts-id-block\">POST /api/v1/accounts/{id}/block</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p>Blocks the account (<code>{id}</code> is the numeric id or a full actor id; accepts slashes). Severs the follow relationship in both directions and, unless <code>federate_blocks</code> is <code>0</code>, sends a <code>Block</code> activity to the account&#39;s server. Returns the updated relationship entity.</p>\n<h2 id=\"post-api-v1-accounts-id-unblock\">POST /api/v1/accounts/{id}/unblock</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p>Lifts a block (federates <code>Undo{Block}</code> under the same setting). Returns the updated relationship entity.</p>\n<h2 id=\"post-api-v1-accounts-id-mute\">POST /api/v1/accounts/{id}/mute</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>notifications</code> (true), <code>duration</code> (0)</p>\n<p>Mutes the account — purely local, never federated. With <code>notifications=true</code> (default) the account&#39;s notifications are hidden too. <code>duration</code> is seconds until the mute lifts itself; <code>0</code> is &quot;until it is lifted by hand&quot;, and re-muting with <code>0</code> drops the expiry a previous timed mute left behind. Returns the updated relationship entity, whose <code>mute_expires_at</code> says when a timed mute runs out.</p>\n<h2 id=\"post-api-v1-accounts-id-unmute\">POST /api/v1/accounts/{id}/unmute</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p>Lifts a mute. Returns the updated relationship entity.</p>\n<h2 id=\"get-api-v1-accounts-familiar-followers\">GET /api/v1/accounts/familiar_followers</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>id</code> (one or more account ids)</p>\n<p>For each named account, which of the people the viewer follows also follow it — the &quot;followed by X and 3 others you know&quot; line on a profile. Answers <code>[{id, accounts}]</code> with at most ten accounts each, and at most twenty ids per call (Mastodon&#39;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&#39;s own profile answers an empty list, as Mastodon&#39;s does.</p>\n<h2 id=\"get-api-v1-accounts-search\">GET /api/v1/accounts/search</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>q</code> (required), <code>limit</code> (40, capped at 80), <code>resolve</code> (false), <code>following</code> (false)</p>\n<p>Mastodon&#39;s account search — what a composer calls to complete a <code>@handle</code> as somebody types. <code>/api/v2/search</code> 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 <code>resolve</code> it also asks the address or handle&#39;s own server, which is what makes completing a handle from another instance work at all, and adds the Bluesky accounts the AppView&#39;s typeahead finds for a dotted name, each stored so it has an id. Without <code>resolve</code>, as in Mastodon, no other server is asked: a client&#39;s autocomplete sends it once per keystroke. A whole <code>user@host</code> that is not held here is then queued for a background lookup, and a later search finds it. <code>following=true</code> 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&#39;s direct-message recipient box asks for the people it lists first. The search itself is narrowed, so <code>limit</code> counts followed accounts, and no unknown handle is fetched from its server for it; what <code>resolve</code> finds is kept only when the viewer follows it. An empty <code>q</code> is an empty list, not an error. Registered <strong>before</strong> <code>/api/v1/accounts/{id}</code>, which accepts slashes and would otherwise swallow it. Rate-limited per user and per anonymous caller.</p>\n<h2 id=\"get-api-v1-accounts-id\">GET /api/v1/accounts/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>One account, by the numeric id every API entity emits, an <code>@user</code> / <code>user@host</code> handle, a bare local username, or the actor&#39;s ActivityPub id — all resolved through <code>resolveTargetAccount()</code>. Returns the account entity in local format; an unknown reference is a 404. <code>{id}</code> accepts slashes (<code>requirements: .+</code>), so this route is registered <strong>last</strong> of the /api/v1/accounts routes and must stay there — otherwise it swallows <code>lookup</code>, <code>relationships</code>, <code>verify_credentials</code> and the <code>{account}</code> sub-routes. Rate-limited per user and per anonymous caller.</p>\n<h2 id=\"get-api-v1-accounts-lookup\">GET /api/v1/accounts/lookup</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>acct</code> (required)</p>\n<p>The account behind a handle, from what is already cached — this route never fetches from another server. A leading <code>@</code> is stripped. 404 when the handle is unknown here, 422 when <code>acct</code> is missing. Rate-limited per user and per anonymous caller.</p>\n<h2 id=\"get-api-v1-accounts-account-statuses\">GET /api/v1/accounts/{account}/statuses</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0), <code>pinned</code> (false), <code>only_media</code> (false), <code>media_type</code> (&#39;&#39;), <code>only_short</code> (false), <code>exclude_reblogs</code> (false), <code>exclude_replies</code> (false), <code>tagged</code> (&#39;&#39;)</p>\n<p>Statuses of <code>{account}</code>, which may be the numeric id or a handle, answered from what is stored here: its posts and, as on Mastodon, its <strong>boosts</strong>, each a status by the account whose <code>reblog</code> is the boosted post, in the order the account made them and paged with them. <code>exclude_reblogs=true</code> leaves the boosts out; so does any narrowing to a kind of post (<code>only_media</code>, <code>media_type</code>, <code>only_short</code>, <code>only_video</code>, <code>only_news</code>) and <code>tagged</code> — 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. <code>exclude_replies=true</code> leaves out the account&#39;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. <code>tagged</code> keeps the account&#39;s posts carrying that hashtag (with or without <code>#</code>, any case). Both narrow the page query, so pages stay full and <code>max_id</code> walks the narrowed list. The <strong>first page</strong> (no <code>max_id</code>, <code>min_id</code> or <code>since_id</code>) asked by a signed-in caller also queues a background sync of a remote account&#39;s outbox (<code>Cron\\SyncRemoteTimeline</code>, 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 <code>X-Social-Filling: 1</code>, <code>X-Social-Profile-Filling: 1</code> and <code>X-Social-Remote-Profile-Filling: 1</code>; 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 <code>X-Social-Filling: 1</code> and <code>X-Social-Profile-Filling: 1</code> so the web app retries from the saved AppView cursor at a steady two-second cadence. <code>{account}</code> accepts slashes (<code>requirements: .+</code>). With <code>pinned=true</code> it returns that account&#39;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 <code>#[PublicPage]</code>, and reading them unfiltered served a pinned followers-only post in full to the internet. A page with remote counts still due carries <code>X-Social-Filling: 1</code>; the web app fetches the page again until the background count refresh stamps it. <code>only_media</code> is Mastodon&#39;s own parameter and keeps just the posts carrying an attachment; <code>media_type</code> (<code>image</code>, <code>video</code>, <code>audio</code>) is a <strong>Aloha Social extension</strong> narrowing that to one kind, which is what the Photos and Videos tabs of a profile ask. It implies <code>only_media</code>, and anything that is not one of the three kinds an attachment can be is read as no preference. <code>only_short</code> keeps the account&#39;s short videos, as on the timelines (see <code>/api/v1/timelines/{timeline}/</code>), and wins over the other two. Sends a <code>Link</code> header.</p>\n<h2 id=\"get-api-v1-accounts-account-followers\">GET /api/v1/accounts/{account}/followers</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0; <code>since</code> is accepted for it too)</p>\n<p>Followers of <code>{account}</code> (numeric id or handle). The accounts this server knows follow it come first, paged by their ids with a <code>Link</code> 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&#39;s <code>followers</code> collection as its server describes it (a few pages), or, for an account on Bluesky, what the AppView lists — read in the background (<code>FollowListService</code>, 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 <code>max_id</code> of its last account (its <code>Link</code> header has only <code>next</code>, and none at the end). While that read was just asked for, the answer carries <strong><code>X-Social-Filling: 1</code></strong> (this app&#39;s own); the web app looks again a few seconds later. An account whose server keeps the list to itself (Mastodon&#39;s &quot;hide your social graph&quot;: the collection&#39;s pages are refused, or only its size is given) has an empty list here too. An anonymous caller gets what is known here.</p>\n<h2 id=\"get-api-v1-accounts-account-following\">GET /api/v1/accounts/{account}/following</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0; <code>since</code> is accepted for it too)</p>\n<p>Same as above for the accounts <code>{account}</code> follows: its <code>following</code> collection, or what Bluesky lists it as following; <code>X-Social-Filling: 1</code> the same way.</p>\n<p>A <code>Relationship</code> carries <code>id</code> as a <strong>string</strong>, like every other id on the wire: a client that declares <code>id: String</code> (Ivory, Mona, anything built on Swift&#39;s Codable) could not decode the integer this used to be, so follow/block/mute button state broke after every action that returns one. <code>note</code>, <code>languages</code> (always <code>null</code> — there is no per-account language filter) and <code>requested_by</code> are also present; <code>requested_by</code> reports a pending incoming follow — the same rows <code>/api/v1/follow_requests</code> lists — and <code>showing_reblogs</code> is <code>true</code>, which is what the home timeline actually does. <code>note</code> carries the viewer&#39;s private note about the account, written through <code>POST /api/v1/accounts/{id}/note</code> (see below) and readable by nobody else. <code>mute_expires_at</code> is this app&#39;s own addition: an ISO-8601 date while a timed mute is running, <code>null</code> otherwise. Mastodon carries it on the <em>account</em> entities of <code>GET /api/v1/mutes</code> 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 <code>note</code> on an <em>Account</em>, which is the bio and is implemented (see <code>update_credentials</code> above).</p>\n","toc":[{"id":"title","text":"title","level":2},{"id":"duration","text":"duration","level":2},{"id":"thumbnail","text":"thumbnail","level":2},{"id":"views","text":"views","level":2},{"id":"live","text":"live","level":2},{"id":"category","text":"category","level":2},{"id":"published","text":"published","level":2},{"id":"get-api-v1-accounts-verify-credentials","text":"GET /api/v1/accounts/verify_credentials","level":2},{"id":"patch-api-v1-accounts-update-credentials","text":"PATCH /api/v1/accounts/update_credentials","level":2},{"id":"delete-api-v1-profile-avatar","text":"DELETE /api/v1/profile/avatar","level":2},{"id":"delete-api-v1-profile-header","text":"DELETE /api/v1/profile/header","level":2},{"id":"get-api-v1-follow-requests","text":"GET /api/v1/follow_requests","level":2},{"id":"post-api-v1-follow-requests-id-authorize","text":"POST /api/v1/follow_requests/{id}/authorize","level":2},{"id":"post-api-v1-follow-requests-id-reject","text":"POST /api/v1/follow_requests/{id}/reject","level":2},{"id":"post-api-v1-accounts-id-remove-from-followers","text":"POST /api/v1/accounts/{id}/remove_from_followers","level":2},{"id":"get-api-v1-blocks","text":"GET /api/v1/blocks","level":2},{"id":"get-api-v1-mutes","text":"GET /api/v1/mutes","level":2},{"id":"get-api-v1-accounts-relationships","text":"GET /api/v1/accounts/relationships","level":2},{"id":"post-api-v1-accounts-id-follow","text":"POST /api/v1/accounts/{id}/follow","level":2},{"id":"post-api-v1-accounts-id-unfollow","text":"POST /api/v1/accounts/{id}/unfollow","level":2},{"id":"post-api-v1-accounts-id-block","text":"POST /api/v1/accounts/{id}/block","level":2},{"id":"post-api-v1-accounts-id-unblock","text":"POST /api/v1/accounts/{id}/unblock","level":2},{"id":"post-api-v1-accounts-id-mute","text":"POST /api/v1/accounts/{id}/mute","level":2},{"id":"post-api-v1-accounts-id-unmute","text":"POST /api/v1/accounts/{id}/unmute","level":2},{"id":"get-api-v1-accounts-familiar-followers","text":"GET /api/v1/accounts/familiar_followers","level":2},{"id":"get-api-v1-accounts-search","text":"GET /api/v1/accounts/search","level":2},{"id":"get-api-v1-accounts-id","text":"GET /api/v1/accounts/{id}","level":2},{"id":"get-api-v1-accounts-lookup","text":"GET /api/v1/accounts/lookup","level":2},{"id":"get-api-v1-accounts-account-statuses","text":"GET /api/v1/accounts/{account}/statuses","level":2},{"id":"get-api-v1-accounts-account-followers","text":"GET /api/v1/accounts/{account}/followers","level":2},{"id":"get-api-v1-accounts-account-following","text":"GET /api/v1/accounts/{account}/following","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"accounts","manual":false,"prev":{"path":"/docs/api-instance-and-app-metadata","title":"Instance and app metadata"},"next":{"path":"/docs/api-search-mastodon-v2","title":"Search (Mastodon v2)"},"parent":"api-mastodon-compatible-api"},{"slug":"api-search-mastodon-v2","path":"/docs/api-search-mastodon-v2","title":"Search (Mastodon v2)","description":"Auth: public, no-csrf (viewer required) · Parameters: q (required), type, limit (20, capped at 40), resolve, account_id, offset, max_id, min_id","group":"api","html":"<h2 id=\"get-api-v1-search\">GET /api/v1/search</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>q</code> (required), <code>type</code>, <code>limit</code> (20, capped at 40), <code>resolve</code>, <code>account_id</code>, <code>offset</code>, <code>max_id</code>, <code>min_id</code></p>\n<p>Mastodon&#39;s v1 search; identical to <code>/api/v2/search</code>, which it delegates to. This path used to be the app&#39;s own web-UI search, which answered a client with a Nextcloud envelope and a <code>content</code> key — a 200 a client could make nothing of. That search moved to <code>GET /local/v1/search</code>.</p>\n<h2 id=\"get-api-v2-search\">GET /api/v2/search</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>q</code> (required), <code>type</code> (<code>accounts</code>/<code>statuses</code>/<code>hashtags</code>, empty = all), <code>limit</code> (20, capped at 40), <code>resolve</code>, <code>account_id</code>, <code>offset</code>, <code>max_id</code>, <code>min_id</code></p>\n<p>Mastodon&#39;s search entity: <code>accounts</code> (URI + name search over cached actors; with <code>resolve</code>, an address or handle this instance has never seen is looked up on its server and Bluesky&#39;s typeahead adds what it finds, without it nothing is asked of another server and an unknown address or whole <code>user@host</code> is queued for a background lookup that a later search finds), <code>statuses</code> (the viewer-bounded full-text search: every word of <code>q</code> must be in the post and the last may be the beginning of a word, matched case-insensitively against the post&#39;s text without its markup), <code>hashtags</code> (Tag entities with an empty <code>history</code>; a hashtag of a public post can be found as soon as the post is stored, before the trends cron has counted it). <code>resolve</code> 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 <code>q</code> that is an <code>http(s)</code> 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 <code>Note</code> or a <code>Question</code>, 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. <code>account_id</code> (the numeric id, a handle or an actor URL of an account this instance holds; nothing is fetched) narrows <code>statuses</code> to that account&#39;s posts, still within what the viewer may see; <code>accounts</code> and <code>hashtags</code> are unaffected, as in Mastodon, so a client that wants the posts alone sends <code>type=statuses</code> as well. An <code>account_id</code> this instance does not know answers with no posts rather than an error. <code>offset</code>, <code>max_id</code> and <code>min_id</code> page <code>statuses</code>, narrowed or not: <code>offset</code> skips that many answers and reaches 400 deep (a page past that is empty), <code>max_id</code>/<code>min_id</code> keep the posts whose id is below/above them, and the order stays newest first; one that is not a number is ignored. <code>accounts</code> and <code>hashtags</code> are not paged. <code>resolve</code> fetches only on the first page of a search that is not narrowed to an account. Clients detect this behaviour by <code>api_versions.aloha_social &gt;= 1</code> on <code>/api/v2/instance</code>. 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 (<code>PostDiscoveryService</code>, at most every ten minutes per term and reader): Bluesky&#39;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 <strong><code>X-Social-Filling: 1</code></strong> while that read is new, and the web app asks once more a few seconds later. Rate-limited per user and per anonymous caller.</p>\n","toc":[{"id":"get-api-v1-search","text":"GET /api/v1/search","level":2},{"id":"get-api-v2-search","text":"GET /api/v2/search","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"search-mastodon-v2","manual":false,"prev":{"path":"/docs/api-accounts","title":"Accounts"},"next":{"path":"/docs/api-statuses","title":"Statuses"},"parent":"api-mastodon-compatible-api"},{"slug":"api-statuses","path":"/docs/api-statuses","title":"Statuses","description":"Auth: public, no-csrf (viewer required, write scope) · Parameters: Body (JSON or form-encoded): status, visibility, media_ids (array), in_reply_to_id, quote_id, spoiler_text, sensitive…","group":"api","html":"<h2 id=\"post-api-v1-statuses\">POST /api/v1/statuses</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>Body (JSON or form-encoded): <code>status</code>, <code>visibility</code>, <code>media_ids</code> (array), <code>in_reply_to_id</code>, <code>quote_id</code>, <code>spoiler_text</code>, <code>sensitive</code>, <code>post_as</code>, <code>reply_policy</code>; Aloha Social extension <code>event</code> (<code>name</code>, <code>start_time</code>, optional <code>end_time</code>, optional <code>location</code>). Header: <code>Idempotency-Key</code></p>\n<p>Creates a post. The body is read from <code>php://input</code> and parsed by <code>Content-Type</code>; a body that declares itself JSON and is not valid JSON is a <strong>422</strong>, not the HTML error page a <code>TypeError</code> used to produce. An <code>event</code> creates an ActivityStreams <code>Event</code> with a required title and valid start time; it cannot be combined with a poll and is preserved when scheduled or held for moderation. <code>start_time</code> and <code>end_time</code> are ISO 8601 values normalised to UTC. Only <code>status</code>, <code>visibility</code>, <code>media_ids</code>, <code>in_reply_to_id</code>, <code>quote_id</code>, <code>poll</code>, <code>spoiler_text</code> and <code>sensitive</code> affect the created post — <code>sensitive</code> is stored in its own column and read back (a non-empty <code>spoiler_text</code> also reads as sensitive); <code>spoiler_text</code> is stored as plain text, so a warning containing an apostrophe stays an apostrophe on the wire. A <code>poll</code> is held to the limits <code>configuration.polls</code> announces, as on Mastodon: blank options are left out, and fewer than two options, more than <code>max_options</code> or an option longer than <code>max_characters_per_option</code> is a <strong>422</strong> rather than a poll cut down to what fits. <code>visibility</code> maps to the stream type (<code>public</code>, <code>unlisted</code>, <code>followers</code>/<code>private</code>, <code>direct</code>); <strong>omitting it takes the account&#39;s default</strong> (<code>source[privacy]</code>, public unless the account set otherwise), and a value this app does not know is a <strong>422</strong> rather than a post silently addressed to nobody. A reply to a <code>direct</code> post is <code>direct</code> whatever <code>visibility</code> says, as on Mastodon — the conversation was addressed to named people — and its attachments stay private with it. An <code>in_reply_to_id</code> that names a post the writer may not read is answered as one that names nothing: <strong>404</strong> <code>The post you are trying to reply to does not appear to exist.</code>, as on Mastodon, and nothing is posted. <code>quote_id</code> quotes another post: the id is resolved the same way <code>in_reply_to_id</code> is, and the post is published immediately while the quoted author&#39;s server is asked for permission in the background (see <strong>Quote posts</strong> in <code>docs/Architecture.md</code>) — so a quote starts out <code>pending</code> and becomes <code>accepted</code> only when the approval arrives. A status whose text and content warning together run past the instance&#39;s <code>max_characters</code> is a <strong>422</strong>, counted in characters rather than bytes and the way Mastodon counts them: every URL in the text as 23 characters (<code>characters_reserved_per_url</code>) whatever its length, and a mention of an account on another server as its <code>@name</code> alone. An <code>Idempotency-Key</code> 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 <code>public</code> or <code>unlisted</code>. <code>scheduled_at</code> (ISO 8601) publishes the post later instead of now: the answer is a <strong>ScheduledStatus</strong> entity — <code>id</code>, <code>scheduled_at</code>, <code>params</code>, <code>media_attachments</code>, and no <code>content</code>, <code>account</code> or <code>created_at</code> — and nothing is posted until <code>Cron\\ScheduledPosts</code> picks it up. It must be at least <strong>5 minutes</strong> in the future; sooner is a <strong>422</strong>, 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 <strong>422</strong>. The visibility is resolved when the post is scheduled and stored resolved, so changing <code>source[privacy]</code> afterwards cannot move the audience of a post that is already waiting. <code>Idempotency-Key</code> does not apply — a scheduled post creates no status to remember. Rate-limited per user.</p>\n<h2 id=\"get-api-v1-statuses-nid\">GET /api/v1/statuses/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>Query: <code>force_counts=true</code> (optional)</p>\n<p>One status by numeric id, local export format, with the same <code>reactions</code> (<code>me</code> for the reader), <code>place</code>, <code>tagged_people</code> and <code>card</code> a timeline gives the same post; so do the statuses the create, edit, action, react and <code>interaction_policy</code> routes answer with. A boost asked for by its own id carries the boosted status in <code>reblog</code>, with the reader&#39;s <code>favourited</code>, <code>reblogged</code> and <code>bookmarked</code> on it, as a timeline shows it; a boost of a status the reader may not see is a <strong>404</strong>, as on Mastodon. <strong>Aloha Social extension:</strong> <code>force_counts=true</code> 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. <code>X-Social-Filling: 1</code> says counts are still being fetched or queued; a client that reads it asks again a few seconds later.</p>\n<h2 id=\"get-api-v1-statuses-nid-calendar\">GET /api/v1/statuses/{nid}/calendar</h2>\n<p><strong>Auth: </strong>public, no-csrf, <code>read:statuses</code> · <strong>Parameters: </strong><code>nid</code></p>\n<p>Downloads a visible ActivityStreams <code>Event</code> with a valid <code>startTime</code> as an iCalendar <code>.ics</code> file. The status entity carries an app-local <code>event</code> 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.</p>\n<h2 id=\"post-api-v1-statuses-nid-calendar-import\">POST /api/v1/statuses/{nid}/calendar/import</h2>\n<p><strong>Auth: </strong>user, session only, CSRF protected · <strong>Parameters: </strong><code>nid</code></p>\n<p>Imports a visible ActivityStreams <code>Event</code> directly into a writable calendar owned by the signed-in Nextcloud user. Repeated imports are detected by the stable iCalendar UID.</p>\n<h2 id=\"put-api-v1-statuses-nid\">PUT /api/v1/statuses/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>Body: <code>status</code>, <code>spoiler_text</code>, <code>sensitive</code>, <code>event</code>, <code>media_ids</code>, <code>media_attributes</code></p>\n<p>Edits an own post via <code>PostService::editPost()</code>. <code>media_ids</code>, 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&#39;s maximum attachment count. <code>media_attributes</code> (<code>id</code> plus <code>description</code> and/or <code>focus</code> per entry, as a JSON list or as <code>media_attributes[][id]=…&amp;media_attributes[][description]=…</code>, which is grouped back per attachment because PHP splits every <code>[]</code> into an entry of its own) changes the alt text and focal point of attachments the post carries: the upload is updated, the post&#39;s own copy is rebuilt from it, and the Update carries the new words. An id the post does not carry is ignored. Omitting <code>spoiler_text</code> or <code>sensitive</code> leaves that value unchanged; sending an empty <code>spoiler_text</code> explicitly removes the content warning. <code>event</code> updates the event details, and <code>null</code> removes the event from a post. Editing keeps the original <code>published</code> time and advances <code>updated</code>, which is used for <code>edited_at</code>.</p>\n<h2 id=\"delete-api-v1-statuses-nid\">DELETE /api/v1/statuses/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Deletes one of the viewer&#39;s own statuses and answers with the status that was removed, which is what a client&#39;s &quot;delete &amp; redraft&quot; puts back in the composer. Somebody else&#39;s status is a 404, the same answer an unknown id gets.</p>\n<h2 id=\"get-api-v1-statuses-nid-delivery\">GET /api/v1/statuses/{nid}/delivery</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p><strong>This app&#39;s own route.</strong> Where one of the viewer&#39;s own posts got to, read from the delivery queue: <code>delivered</code>, <code>sending</code>, <code>waiting</code>, <code>failing</code> and <code>abandoned</code> counts, <code>total</code>, and <code>instances</code> — one <code>{host, state, tries, last}</code> per server, the ones that need the author&#39;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&#39;s post is a <strong>404</strong>, the same 404 as a post that does not exist. Only as good as the retention: a delivered or abandoned request is kept for <code>retention</code> 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.</p>\n<h2 id=\"get-api-v1-statuses-nid-source\">GET /api/v1/statuses/{nid}/source</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p>Mastodon&#39;s <code>StatusSource</code>: <code>{&quot;id&quot;, &quot;text&quot;, &quot;spoiler_text&quot;}</code> for one of the viewer&#39;s own statuses. The stored content is the HTML rendered from the original text, so it is turned back — <code>&lt;br&gt;</code> 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 <code>PUT /api/v1/statuses/{nid}</code> has always worked.</p>\n<h2 id=\"get-api-v1-statuses-nid-card\">GET /api/v1/statuses/{nid}/card</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The link preview of one status, as Mastodon&#39;s <code>PreviewCard</code>. The card is already inlined in the status entity, which is what most clients read; this route was a <strong>405</strong> rather than a 404, because the path matched the POST-only action route and nothing answered a GET. A status with no link answers <code>{}</code> — Mastodon&#39;s own answer, and not an error, since most statuses have no card.</p>\n<h2 id=\"get-api-v1-statuses-nid-context\">GET /api/v1/statuses/{nid}/context</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Ancestors/descendants of the status, as this server holds them, each with the <code>reactions</code>, <code>place</code>, <code>tagged_people</code> and <code>card</code> a timeline gives it. Opening a conversation also has the rest of it read from wherever it lives (<code>ThreadService</code>, 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&#39;s. When that read was just asked for, the answer carries the header <strong><code>X-Social-Thread-Filling: 1</code></strong> — this app&#39;s own; the web app asks once more a few seconds later and adds what came in. The replies the author of the conversation&#39;s first post hid (<code>hide_reply</code>) are left out, and counted in <strong><code>X-Social-Hidden-Replies</code></strong>; <code>with_hidden=true</code> includes them. In a conversation every reply carries <code>hidden_by_author</code> and <code>can_hide</code> (whether the reader is that author) — this app&#39;s own keys, <code>null</code> on a status read anywhere else.</p>\n<h2 id=\"get-api-v1-statuses-nid-favourited-by\">GET /api/v1/statuses/{nid}/favourited_by</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer optional) · <strong>Parameters: </strong><code>limit</code> (40, capped at 80)</p>\n<p>The accounts that favourited the status, newest first, as <code>Account</code> entities. The status is resolved through the visibility filter first, so one the caller may not read is a <strong>404</strong> 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 <code>likes</code> collection (many list only the number), and the ones Bluesky lists for a post that is there — read in the background (<code>InteractionService</code>, 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 <strong><code>X-Social-Filling: 1</code></strong> (this app&#39;s own); the web app looks again a few seconds later. No <code>Link</code> header.</p>\n<h2 id=\"post-api-v1-statuses-nid-react\">POST /api/v1/statuses/{nid}/react</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>emoji</code> (required)</p>\n<p>Reacts to a status with an emoji and answers the status, its <code>reactions</code> rebuilt, so a client redraws the card from one response. Sends an <code>EmojiReact</code> to the author&#39;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. <strong>Unicode emoji only</strong>: <code>:shortcode:</code> custom emoji are refused with a <strong>400</strong>, because accepting one means drawing a picture from somebody else&#39;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.</p>\n<h2 id=\"post-api-v1-statuses-nid-unreact\">POST /api/v1/statuses/{nid}/unreact</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>emoji</code> (required)</p>\n<p>Takes a reaction back and answers the status. The row goes whether or not the <code>Undo</code> 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.</p>\n<h2 id=\"get-api-v1-statuses-nid-reactions\">GET /api/v1/statuses/{nid}/reactions</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer optional) · <strong>Parameters: </strong>—</p>\n<p>The reactions on a status: <code>{name, count, me}</code> 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 <strong>404</strong> and none of its reactions is looked at — who reacted to a post is as private as the post. <code>me</code> is false for an anonymous caller.</p>\n<h2 id=\"get-api-v1-gifs\">GET /api/v1/gifs</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>q</code>, <code>limit</code> (24, max 200), <code>offset</code></p>\n<p>The pictures the composer offers: what an administrator added here first, then the 881 shipped animated emoji. Answers <code>{gifs, total, attribution}</code>, each entry <code>{slug, title, url, media_type}</code>. Paged, because a grid of 881 is 881 pictures the instance would fetch because somebody opened a menu. <code>q</code> matches a title or slug for the instance&#39;s own, and for the shipped emoji also every other name Google gives one and its category, so &quot;sad&quot; or &quot;food&quot; 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 <code>LIKE &#39;%…%&#39;</code> — a leading wildcard is a scan on all three databases this app supports, and the shipped set is a file rather than rows.</p>\n<h2 id=\"get-gif-slug\">GET /gif/{slug}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The bytes behind a slug, cached for a day. Unauthenticated, like <code>/emoji/{shortcode}</code>: 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 <code>noto-…</code> slug is one of the shipped animated emoji: if this instance has not served it before, <em>this</em> is the request that fetches it from Google, once, and stores it in appdata — which is why the reader&#39;s browser never talks to anybody but their own Nextcloud.</p>\n<h2 id=\"post-api-v1-media-from-gif\">POST /api/v1/media/from-gif</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>slug</code> (required), <code>description</code></p>\n<p>Attaches a library picture to a post being written, and answers the <code>MediaAttachment</code> the composer holds on to. A copy, through the same <code>storeAttachment()</code> 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 <code>/api/v1/media/from-file</code> 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 <code>description</code> the picture&#39;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.</p>\n<h2 id=\"get-api-v1-statuses-nid-reblogged-by\">GET /api/v1/statuses/{nid}/reblogged_by</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer optional) · <strong>Parameters: </strong><code>limit</code> (40, capped at 80)</p>\n<p>The accounts that boosted the status, newest first. Same rules as <code>favourited_by</code>, with the <code>shares</code> collection and Bluesky&#39;s reposts.</p>\n<h2 id=\"get-api-v1-statuses-nid-quotes\">GET /api/v1/statuses/{nid}/quotes</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer optional) · <strong>Parameters: </strong><code>limit</code> (20, max 40), <code>max_id</code></p>\n<p><strong>The posts that quote this one</strong>, newest first — Mastodon 4.5&#39;s. What comes back is what this server <em>holds</em>: a local quote, a remote one that reached somebody here, and — read in the background when the list is asked for, <code>X-Social-Filling: 1</code> — 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&#39;s own answer has the same edge. Read as the viewer, so a quote inside somebody&#39;s followers-only post is not handed to a reader by a list about their own post.</p>\n<h2 id=\"put-api-v1-statuses-nid-interaction-policy\">PUT /api/v1/statuses/{nid}/interaction_policy</h2>\n<p><strong>Auth: </strong>public, no-csrf (bearer <code>write:statuses</code>) · <strong>Parameters: </strong><code>quote_approval_policy</code>: <code>public</code>, <code>followers</code> or <code>nobody</code>; <code>reply_policy</code>: <code>everyone</code>, <code>nobody</code>, or a combination of <code>followers</code>, <code>following</code>, <code>mentioned</code> and up to five <code>list:&lt;id&gt;</code> of the caller&#39;s own lists, comma-separated (<code>followers,mentioned</code>)</p>\n<p><strong>Who may reply</strong> (<code>reply_policy</code>, this app&#39;s own field): written onto the post, said to peers as <code>interactionPolicy.canReply.automaticApproval</code> (the union of what each part names: the author&#39;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&#39;s threadgate (a rule for each part; a list as the Bluesky list it is published as, <code>app.bsky.graph.list</code> 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 (<strong>422</strong>) and not kept when it arrives from elsewhere. The author always may. From now on only: replies already made stay. A body with <code>reply_policy</code> alone leaves who may quote as it was. <strong>Who may quote one of the caller&#39;s own posts.</strong> Written onto the post (<code>social_stream.quote_policy</code>) and advertised on its ActivityPub document as <code>interactionPolicy.canQuote.automaticApproval</code>, which is what Mastodon 4.5 reads before it offers a quote button. It decides what happens to <code>QuoteRequest</code>s that arrive <strong>from now on</strong>; 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&#39;s post is a <strong>404</strong>, the same answer an id that does not exist gets.</p>\n<h2 id=\"post-api-v1-statuses-nid-quotes-quoting-revoke\">POST /api/v1/statuses/{nid}/quotes/{quoting}/revoke</h2>\n<p><strong>Auth: </strong>public, no-csrf (bearer <code>write:statuses</code>) · <strong>Parameters: </strong><code>nid</code> the quoted post, <code>quoting</code> the post to detach</p>\n<p><strong>Takes one quote of the caller&#39;s own post back.</strong> A <code>Reject</code> naming the <code>QuoteRequest</code> that was accepted goes to the quoting server — FEP-044f&#39;s way of withdrawing a permission, and what <code>social_quote_grant</code> 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 <em>revoked</em> rather than refused, which is what this app does with an incoming one. A <strong>local</strong> quoting post is withdrawn here directly, because there is nobody to tell. A <strong>Bluesky</strong> quoting post has no request to refuse, since Bluesky asks nobody&#39;s permission: it is listed in the quoted post&#39;s <code>app.bsky.feed.postgate</code> as <code>detachedEmbeddingUris</code> (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&#39;s, is a <strong>404</strong>.</p>\n<h2 id=\"post-api-v1-statuses-nid-translate\">POST /api/v1/statuses/{nid}/translate</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>lang</code> (the language to translate into; defaults to the reader&#39;s Nextcloud language)</p>\n<p>One status in the reader&#39;s language, as Mastodon&#39;s <strong><code>Translation</code></strong> entity — <code>{content, spoiler_text, media_attachments, poll, detected_source_language, provider}</code>, not a <code>Status</code>: 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 <code>{act}</code>, which would otherwise match this path. Translated by whatever translation provider this Nextcloud has; a server with none answers <strong>503</strong> and says so in <code>configuration.translation.enabled</code>. 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 (<code>TranslationService::MAX_TEXTS</code>, 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.</p>\n<h2 id=\"post-api-v1-statuses-nid-act\">POST /api/v1/statuses/{nid}/{act}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>act</code> (path)</p>\n<p>Performs an action on a status — see the action table below.</p>\n<p><code>{act}</code> is validated against <code>ActionService::$availableStatusAction</code>. Accepted values are <code>favourite</code>, <code>unfavourite</code>, <code>reblog</code>, <code>unreblog</code>, <code>bookmark</code>, <code>unbookmark</code>, <code>hide_reply</code>, <code>unhide_reply</code>, <code>mute</code>, <code>unmute</code>, <code>pin</code>, <code>unpin</code>, <code>dislike</code>, <code>undislike</code>; anything else throws <code>InvalidActionException</code>:</p>\n<h2 id=\"favourite-unfavourite\">favourite, unfavourite</h2>\n<p>Creates/deletes a Like (<code>LikeService</code>). A poll (a <code>Question</code>) is a status to its readers and is liked like a note (<code>Stream::STATUS_TYPES</code>); anything else — a boost, an activity — is a 404.</p>\n<h2 id=\"reblog-unreblog\">reblog, unreblog</h2>\n<p>Creates/deletes an Announce (<code>BoostService</code>), of a note or a poll. The Mastodon-ish names <code>boost</code> and <code>unboost</code> are <strong>not</strong> accepted.</p>\n<h2 id=\"hide-reply-unhide-reply\">hide_reply, unhide_reply</h2>\n<p>Hides a reply from the conversation of one of the caller&#39;s own posts, or shows it again — any reply in the thread, wherever it was written (<code>HiddenReplyService</code>). Kept on the thread&#39;s first post; a thread that is on Bluesky lists it in its threadgate (<code>hiddenReplies</code>), which every AppView honours. Anybody but the author of the thread&#39;s first post is refused.</p>\n<h2 id=\"bookmark-unbookmark\">bookmark, unbookmark</h2>\n<p>Toggles the viewer&#39;s bookmark flag (<code>social_stream_act.bookmarked</code>). Never federated; the bookmarked posts are served by <code>/api/v1/bookmarks</code>. A post that is on Bluesky is bookmarked there too, privately (<code>app.bsky.bookmark.createBookmark</code>, as the viewer), so a Bluesky app signed in here shows the same bookmark.</p>\n<h2 id=\"pin-unpin\">pin, unpin</h2>\n<p>Pins/unpins one of <strong>your own local, public or unlisted posts</strong> to your profile (<code>PinService</code>), and tells the followers with an <code>Add</code> or <code>Remove</code> naming the actor&#39;s <code>featured</code> collection — a peer has nothing else to prompt it to re-read that collection. At most 5 pins; pinning somebody else&#39;s post, a remote post, a followers-only or direct post, or exceeding the limit raises <code>InvalidActionException</code> (a 422). The visibility rule is Mastodon&#39;s pinnable set, and it exists because the <code>featured</code> collection is served to anonymous callers. A pin is stored as a <code>Pin</code> row in <code>social_action</code> and published in the actor&#39;s <code>featured</code> collection — it is never federated as an activity of its own.</p>\n<h2 id=\"dislike-undislike\">dislike, undislike</h2>\n<p>Sends a <code>Dislike</code> to the video&#39;s author, or an <code>Undo</code> of one, and records it against the viewer (<code>social_stream_act.disliked</code>). <strong>Only a video can be disliked</strong> — a post with a video file on it, or one that arrived as a <code>Video</code> — 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&#39;s viewers. The count comes back on the status as <code>dislikes_count</code>, with <code>disliked</code> for the viewer&#39;s own; both are <code>null</code> on anything that is not a video.</p>\n<h2 id=\"mute-unmute\">mute, unmute</h2>\n<p>Mutes the <strong>conversation</strong> the status belongs to, for the viewer. Mastodon&#39;s conversation mute is about being <em>told</em>: the thread&#39;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&#39;s <strong>root</strong> (<code>social_convo_state.muted</code>), 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 <strong>raises nothing</strong> — no Nextcloud notification, so no bell, push or mail, and no Activity entry (<code>NotificationService::emit()</code>) — and is left out of <code>/api/v1/notifications</code>, the unread counts and the digest. Unmuting lists again what arrived meanwhile, without raising anything for it. The answer&#39;s <code>muted</code> says which state the conversation is in now.</p>\n<p>The response is the status itself in local format.</p>\n<p>In that format, <code>in_reply_to_id</code> and <code>in_reply_to_account_id</code> carry the parent status&#39;s numeric id and its author&#39;s, resolved from the stored ActivityPub id (memoised per request, so a thread&#39;s replies are one lookup). Both are <code>null</code> for a post that is not a reply and for a parent this instance has never seen. <code>application</code> (null: which app wrote a post is not recorded), <code>filtered</code> (<code>[]</code> until a filter matched, see Filters) and <code>text</code> (null; the source is answered by <code>/api/v1/statuses/{id}/source</code> and by a delete) are always present, as Mastodon sends them. <code>tags</code> is Mastodon&#39;s <code>[{name, url}]</code>; <code>Note::jsonSerialize()</code> still emits the app&#39;s own <code>hashtags: [&quot;foo&quot;]</code> alongside it when the status is exported with complete details. <code>edited_at</code> is when the post was last edited, or <code>null</code>. <code>quotes_count</code> is Mastodon 4.5&#39;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 (<code>/api/v1/social/counts</code>). <code>quote</code> is Mastodon 4.5&#39;s Quote entity — <code>{state, quoted_status}</code> — or <code>null</code> for a post that quotes nothing. <code>state</code> comes from the quoted author&#39;s approval, not from whether this instance holds the post: <code>pending</code> until they answer, then <code>accepted</code>, <code>rejected</code>, or <code>revoked</code> if they take it back. A quote made on Bluesky, or of a Bluesky post, needs no approval — Bluesky asks nobody — and is <code>accepted</code> until its quoted author detaches it, then <code>revoked</code>. <code>quoted_status</code> carries the quoted post inline only when the quote is accepted <strong>and</strong> the viewer may read it — an accepted quote of a post this reader may not see is <code>accepted</code> with a null <code>quoted_status</code>, so a quote never becomes a way of reading somebody&#39;s followers-only post. Mention ids are strings even when the handle could not be resolved. <code>delivery</code> is an <strong>Aloha Social extension</strong> and the entity&#39;s one key that is absent rather than <code>null</code>: it is <code>&quot;held&quot;</code> on the author&#39;s own copy of a post whose deliveries are waiting for its video to be converted (see <code>VideoDeliveryHold</code>), and absent on every other status and on the same post once it has gone out. Computed for the reader&#39;s own local posts only — the attachments decide first, so a post without a video costs no query. <code>attachment</code> — an ActivityPub-named duplicate of <code>media_attachments</code> — is no longer part of the client format. <code>ai_generated</code> (bool, always present) is an <strong>Aloha Social extension</strong> too: whether the post <em>says</em> it was made with AI — one of its hashtags is in the labelling set (<code>AiContentService::DEFAULT_TAGS</code> plus the administrator&#39;s <code>ai_tags</code>), 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 <em>Hide posts made with AI</em> (<code>/api/v1/social/ai_content</code>) never receives such a status at all, and everybody else can be shown a quiet mark. Each <code>MediaAttachment</code> carries two keys beyond Mastodon&#39;s: <code>media_type</code>, the full mime (<code>image/png</code>), which is what the ActivityPub <code>Document</code> the post is served as states; and <code>ai_generated</code> (bool), whether the picture&#39;s metadata stated IPTC <code>DigitalSourceType</code> <code>trainedAlgorithmicMedia</code> or <code>compositeWithTrainedAlgorithmicMedia</code> 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.</p>\n","toc":[{"id":"post-api-v1-statuses","text":"POST /api/v1/statuses","level":2},{"id":"get-api-v1-statuses-nid","text":"GET /api/v1/statuses/{nid}","level":2},{"id":"get-api-v1-statuses-nid-calendar","text":"GET /api/v1/statuses/{nid}/calendar","level":2},{"id":"post-api-v1-statuses-nid-calendar-import","text":"POST /api/v1/statuses/{nid}/calendar/import","level":2},{"id":"put-api-v1-statuses-nid","text":"PUT /api/v1/statuses/{nid}","level":2},{"id":"delete-api-v1-statuses-nid","text":"DELETE /api/v1/statuses/{nid}","level":2},{"id":"get-api-v1-statuses-nid-delivery","text":"GET /api/v1/statuses/{nid}/delivery","level":2},{"id":"get-api-v1-statuses-nid-source","text":"GET /api/v1/statuses/{nid}/source","level":2},{"id":"get-api-v1-statuses-nid-card","text":"GET /api/v1/statuses/{nid}/card","level":2},{"id":"get-api-v1-statuses-nid-context","text":"GET /api/v1/statuses/{nid}/context","level":2},{"id":"get-api-v1-statuses-nid-favourited-by","text":"GET /api/v1/statuses/{nid}/favourited_by","level":2},{"id":"post-api-v1-statuses-nid-react","text":"POST /api/v1/statuses/{nid}/react","level":2},{"id":"post-api-v1-statuses-nid-unreact","text":"POST /api/v1/statuses/{nid}/unreact","level":2},{"id":"get-api-v1-statuses-nid-reactions","text":"GET /api/v1/statuses/{nid}/reactions","level":2},{"id":"get-api-v1-gifs","text":"GET /api/v1/gifs","level":2},{"id":"get-gif-slug","text":"GET /gif/{slug}","level":2},{"id":"post-api-v1-media-from-gif","text":"POST /api/v1/media/from-gif","level":2},{"id":"get-api-v1-statuses-nid-reblogged-by","text":"GET /api/v1/statuses/{nid}/reblogged_by","level":2},{"id":"get-api-v1-statuses-nid-quotes","text":"GET /api/v1/statuses/{nid}/quotes","level":2},{"id":"put-api-v1-statuses-nid-interaction-policy","text":"PUT /api/v1/statuses/{nid}/interaction_policy","level":2},{"id":"post-api-v1-statuses-nid-quotes-quoting-revoke","text":"POST /api/v1/statuses/{nid}/quotes/{quoting}/revoke","level":2},{"id":"post-api-v1-statuses-nid-translate","text":"POST /api/v1/statuses/{nid}/translate","level":2},{"id":"post-api-v1-statuses-nid-act","text":"POST /api/v1/statuses/{nid}/{act}","level":2},{"id":"favourite-unfavourite","text":"favourite, unfavourite","level":2},{"id":"reblog-unreblog","text":"reblog, unreblog","level":2},{"id":"hide-reply-unhide-reply","text":"hide_reply, unhide_reply","level":2},{"id":"bookmark-unbookmark","text":"bookmark, unbookmark","level":2},{"id":"pin-unpin","text":"pin, unpin","level":2},{"id":"dislike-undislike","text":"dislike, undislike","level":2},{"id":"mute-unmute","text":"mute, unmute","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"statuses","manual":false,"prev":{"path":"/docs/api-search-mastodon-v2","title":"Search (Mastodon v2)"},"next":{"path":"/docs/api-scheduled-statuses","title":"Scheduled statuses"},"parent":"api-mastodon-compatible-api"},{"slug":"api-scheduled-statuses","path":"/docs/api-scheduled-statuses","title":"Scheduled statuses","description":"Auth: public, no-csrf (viewer required) · Parameters: limit (20, capped at 40), max_id (0), min_id (0), since_id (0)","group":"api","html":"<h2 id=\"get-api-v1-scheduled-statuses\">GET /api/v1/scheduled_statuses</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>limit</code> (20, capped at 40), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0)</p>\n<p>The viewer&#39;s waiting posts, soonest first, as ScheduledStatus entities with their attachments already expanded. Sends <strong>no <code>Link</code> header</strong> — 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 <strong>the place that row holds in the order above</strong>, not as a number to compare: an id is creation order, <code>scheduled_at</code> is publication order, and <code>PUT /api/v1/scheduled_statuses/{id}</code> 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 <code>(scheduled_at, id)</code> pair it stands for and the comparison is made on the pair. <code>min_id</code> and <code>since_id</code> ask for what comes after that place; <code>max_id</code> asks for what comes before it and answers the page <strong>ending at</strong> 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.</p>\n<h2 id=\"get-api-v1-scheduled-statuses-id\">GET /api/v1/scheduled_statuses/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p>One waiting post. One that is not the viewer&#39;s is a <strong>404</strong>, which is also the answer for one that does not exist.</p>\n<h2 id=\"put-api-v1-scheduled-statuses-id\">PUT /api/v1/scheduled_statuses/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>Body (JSON or form-encoded): <code>scheduled_at</code> (required)</p>\n<p>Moves a waiting post to another time. The five-minute minimum applies again; a missing or unparseable <code>scheduled_at</code> is a <strong>422</strong>, somebody else&#39;s post a <strong>404</strong>. Moving a post inside the day it is already in is not counted against that day&#39;s cap; moving it into another day that already holds 25 is a <strong>422</strong>.</p>\n<h2 id=\"delete-api-v1-scheduled-statuses-id\">DELETE /api/v1/scheduled_statuses/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Cancels a waiting post and answers <code>{}</code>. Cancelling one that is gone, or one that is not the viewer&#39;s, is a <strong>404</strong>.</p>\n<p>A due post is published by <code>Cron\\ScheduledPosts</code> down the same path an immediate post takes (<code>PostService::createPost()</code>), with the request replayed from <code>params</code>. The row is deleted before the post is attempted, so exactly one worker publishes it; a post that cannot be published is logged at <code>warning</code> and not retried, because the alternative federates it twice.</p>\n","toc":[{"id":"get-api-v1-scheduled-statuses","text":"GET /api/v1/scheduled_statuses","level":2},{"id":"get-api-v1-scheduled-statuses-id","text":"GET /api/v1/scheduled_statuses/{id}","level":2},{"id":"put-api-v1-scheduled-statuses-id","text":"PUT /api/v1/scheduled_statuses/{id}","level":2},{"id":"delete-api-v1-scheduled-statuses-id","text":"DELETE /api/v1/scheduled_statuses/{id}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"scheduled-statuses","manual":false,"prev":{"path":"/docs/api-statuses","title":"Statuses"},"next":{"path":"/docs/api-lists","title":"Lists"},"parent":"api-mastodon-compatible-api"},{"slug":"api-lists","path":"/docs/api-lists","title":"Lists","description":"Auth: public, no-csrf (viewer required, read:lists scope) · Parameters: —","group":"api","html":"<h2 id=\"get-api-v1-lists\">GET /api/v1/lists</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:lists</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Every list the viewer owns, oldest first, as Mastodon <code>List</code> entities. Unpaged, as Mastodon&#39;s is: a client draws the whole sidebar from one call. Asking is also what makes the <strong>group lists</strong> 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.</p>\n<h2 id=\"post-api-v1-lists\">POST /api/v1/lists</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:lists</code> scope) · <strong>Parameters: </strong><code>title</code> (required), <code>replies_policy</code> (<code>list</code>), <code>exclusive</code> (false), <code>public</code> (false)</p>\n<p>Creates a list and returns it; a public one is published (see <strong>Public lists</strong> below). A blank or whitespace-only title is a <strong>422</strong>, and a <code>replies_policy</code> outside <code>followed</code>/<code>list</code>/<code>none</code> is a <strong>422</strong> rather than quietly stored as the default. Titles are not unique: two lists called &quot;Friends&quot; are two lists, as on Mastodon.</p>\n<h2 id=\"get-api-v1-lists-id\">GET /api/v1/lists/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:lists</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One <code>List</code>. A list that is not there and a list that is somebody else&#39;s are the same <strong>404</strong>: telling them apart would say whether an id exists.</p>\n<h2 id=\"put-api-v1-lists-id\">PUT /api/v1/lists/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:lists</code> scope) · <strong>Parameters: </strong><code>title</code> (required), <code>replies_policy</code>, <code>exclusive</code>, <code>public</code></p>\n<p>Updates the list and returns it. <code>title</code> is required on an update as on a create, so an absent one is a 422 rather than &quot;keep what is there&quot;. Omitted <code>replies_policy</code>/<code>exclusive</code>/<code>public</code> are left alone. <code>public: true</code> on a group list is a <strong>422</strong>.</p>\n<h2 id=\"delete-api-v1-lists-id\">DELETE /api/v1/lists/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:lists</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Deletes the list and its memberships, and answers <code>{}</code>.</p>\n<h2 id=\"get-api-v1-lists-id-accounts\">GET /api/v1/lists/{id}/accounts</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:lists</code> scope) · <strong>Parameters: </strong><code>limit</code> (40, capped at 500), <code>max_id</code> (0), <code>min_id</code> (0)</p>\n<p>The list&#39;s members as <code>Account</code> entities, newest addition first. Sends a <code>Link</code> header whose cursor is the <code>social_list_member</code> 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. <strong><code>limit=0</code> is not accepted</strong>, although Mastodon documents it as &quot;all accounts without pagination&quot;: Nextcloud&#39;s dispatcher applies a range of 1–500 to every parameter named <code>limit</code> (<code>Dispatcher::ensureParameterValueSatisfiesRange</code>) and throws before the route is reached, so a 0 comes back as a <strong>500</strong> and an HTML error page rather than JSON. That is true of every <code>limit</code> this app takes, on this endpoint and any other. Ask for 500 instead.</p>\n<h2 id=\"post-api-v1-lists-id-accounts\">POST /api/v1/lists/{id}/accounts</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:lists</code> scope) · <strong>Parameters: </strong><code>account_ids[]</code> (required; a bare <code>account_ids</code> is accepted too)</p>\n<p>Adds accounts and answers <code>{}</code>. 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 <strong>404</strong> — Mastodon&#39;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.</p>\n<h2 id=\"delete-api-v1-lists-id-accounts\">DELETE /api/v1/lists/{id}/accounts</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:lists</code> scope) · <strong>Parameters: </strong><code>account_ids[]</code> (required)</p>\n<p>Removes accounts and answers <code>{}</code>. 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.</p>\n<h2 id=\"get-api-v1-accounts-account-lists\">GET /api/v1/accounts/{account}/lists</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:lists</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Which of <strong>the viewer&#39;s own</strong> lists <code>{account}</code> is in. Never anybody else&#39;s: which lists a stranger put somebody in is not a thing either of them may read.</p>\n<p><strong>Group lists.</strong> Every Nextcloud group the viewer is in is a list of theirs, made on their behalf and kept in step with the group. The <code>List</code> entity carries two keys beyond Mastodon&#39;s four: <code>nextcloud_group</code>, the group&#39;s id, or <code>null</code> for a list made by hand — a Mastodon client ignores it; this app&#39;s own client draws the group icon from it — and <code>public</code> (below). A group list&#39;s title is the group&#39;s display name and its members are the group&#39;s members who have an Aloha Social account, so <code>DELETE /api/v1/lists/{id}</code>, <code>POST /api/v1/lists/{id}/accounts</code> and <code>DELETE /api/v1/lists/{id}/accounts</code> on one are a <strong>422</strong> naming the group; <code>PUT /api/v1/lists/{id}</code> keeps the title and applies <code>replies_policy</code> and <code>exclusive</code>. Leaving the group is what removes the list. Groups larger than 500 members get no list.</p>\n<p><strong>Public lists.</strong> A list is private to its owner, as on Mastodon, unless they make it public: <code>public</code> on the <code>List</code> entity (<code>false</code> by default), set with <code>public</code> on <code>POST</code>/<code>PUT /api/v1/lists[/{id}]</code>. 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&#39;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&#39;s alone; what is public is the Bluesky list. A group list cannot be made public.</p>\n<p>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 <code>ListsRequest::getOwnedById()</code>, which carries the owner as a predicate of the SQL statement rather than as a check made after the row was read.</p>\n<p><code>replies_policy</code> and <code>exclusive</code> are stored and handed back faithfully, and <strong>neither yet changes which posts a timeline selects</strong>: <code>exclusive</code> does not remove members from the home timeline, and <code>replies_policy</code> does not filter replies out of the list timeline.</p>\n","toc":[{"id":"get-api-v1-lists","text":"GET /api/v1/lists","level":2},{"id":"post-api-v1-lists","text":"POST /api/v1/lists","level":2},{"id":"get-api-v1-lists-id","text":"GET /api/v1/lists/{id}","level":2},{"id":"put-api-v1-lists-id","text":"PUT /api/v1/lists/{id}","level":2},{"id":"delete-api-v1-lists-id","text":"DELETE /api/v1/lists/{id}","level":2},{"id":"get-api-v1-lists-id-accounts","text":"GET /api/v1/lists/{id}/accounts","level":2},{"id":"post-api-v1-lists-id-accounts","text":"POST /api/v1/lists/{id}/accounts","level":2},{"id":"delete-api-v1-lists-id-accounts","text":"DELETE /api/v1/lists/{id}/accounts","level":2},{"id":"get-api-v1-accounts-account-lists","text":"GET /api/v1/accounts/{account}/lists","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"lists","manual":false,"prev":{"path":"/docs/api-scheduled-statuses","title":"Scheduled statuses"},"next":{"path":"/docs/api-pixelfeds-own-routes","title":"Pixelfed's own routes"},"parent":"api-mastodon-compatible-api"},{"slug":"api-pixelfeds-own-routes","path":"/docs/api-pixelfeds-own-routes","title":"Pixelfed's own routes","description":"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…","group":"api","html":"<p>Pixelfed speaks the Mastodon client API for almost everything; what follows is the small surface that is its own. <strong>This is not all of Pixelfed&#39;s <code>v1.1</code></strong> — 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.</p>\n<p>Nothing here ranks or selects anything of its own: discover is the same <code>TrendService</code> the Mastodon trend routes use and the same <code>SuggestionService</code> behind <code>/api/v2/suggestions</code>, so a post or an account cannot be popular on one route and absent from the other.</p>\n<p>Suggestions come from three places, each filling only the slots the one before it left empty: the follow graph (<code>friends_of_friends</code>), the <strong><code>fediverse</code> field of this Nextcloud&#39;s own profiles</strong> (<code>featured</code> — the handles the people here wrote down, honoured with the field&#39;s own visibility and never the ones marked private), and the local accounts that opted in to the directory (<code>most_interactions</code>). An account this app creates has its handle written into that field when the field is empty; a value already there is the person&#39;s own and is left alone.</p>\n<p><strong>Two spellings, one route.</strong> Pixelfed serves most of this surface at both <code>/api/v1.1/…</code> and <code>/api/pixelfed/v1/…</code>, 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&#39;s app calls are <strong>not</strong> served, because Pixelfed does not serve them either: <code>GET /api/v2/media</code> (its <code>v2</code> media route is a POST upload, and a GET there is a <strong>405</strong> here as it is there) and <code>api/pixelfed/v2/discover/posts/trending</code> (there is no <code>v2</code> under the <code>pixelfed</code> prefix; the trending route is the <code>v1</code> one below).</p>\n<h2 id=\"get-api-v2-config\">GET /api/v2/config</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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. <strong>Every value is derived, never restated</strong>: the ceilings come from the constants the server enforces and the mime list is asked of <code>CacheDocumentService::filterMimeTypes()</code>, so the client cannot be told a limit the server does not keep. <code>open_registration</code> is always <code>false</code> — an account here exists because a Nextcloud user does. The <code>features</code> block says what <em>this</em> app does, including the things it does not (<code>live_streaming</code>, <code>push_notifications</code>, <code>circles</code> are <code>false</code>): announcing a screen that is not there is worse than not announcing it. <code>features.shorts</code> is <code>true</code> where the timelines take <code>only_short</code>, and <code>limits.short_max_duration</code> (seconds) and <code>limits.short_max_aspect_ratio</code> (width ÷ height) are the rule they apply, read from <code>Stream::SHORT_MAX_SECONDS</code> and <code>Stream::SHORT_MAX_ASPECT</code>.</p>\n<h2 id=\"get-api-v1-1-teams\">GET /api/v1.1/teams</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The team accounts the viewer may post as right now, as Account entities: <code>{&quot;teams&quot;: [Account, …]}</code>. Asked of Nextcloud&#39;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.</p>\n<h2 id=\"get-api-v1-1-portfolio\">GET /api/v1.1/portfolio</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s own page of work, published or not, with the pictures it would show — <strong>as the internet will see them</strong>, 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 <strong>404</strong>: there is nothing to find, and this is what lets an editor render without a &quot;create it first&quot; step nobody needs.</p>\n<h2 id=\"post-api-v1-1-portfolio\">POST /api/v1.1/portfolio</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> scope) · <strong>Parameters: </strong><code>active</code>, <code>title</code> (128), <code>intro</code> (500), <code>layout</code> (<code>grid</code> or <code>rows</code>), <code>source</code> (<code>recent</code> or <code>collection</code>), <code>collection_id</code>, <code>show_captions</code>, <code>show_places</code>, <code>show_dates</code>, <code>show_avatar</code></p>\n<p>Writes it. <code>active</code> is the moment its owner decides the internet may read it; a row without it is a draft. <code>source: collection</code> with a collection that is not the viewer&#39;s own is a <strong>422</strong>, checked when it is asked for rather than rendered as an empty page afterwards. Returns the page as the GET above would.</p>\n<h2 id=\"get-api-v1-1-portfolio-handle\">GET /api/v1.1/portfolio/{handle}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Somebody&#39;s published page, as the internet reads it: the account, the title, the sentence, the display switches, and up to 60 posts. <strong>No viewer is resolved at all</strong>, 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 <strong>404</strong>, not an empty page with their name on it, and so is a handle this server does not know.</p>\n<h2 id=\"post-api-v1-1-compose-tag\">POST /api/v1.1/compose/tag</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong><code>status_id</code> (required), <code>accounts</code> (a list of handles or ids)</p>\n<p>Names the people in one of the viewer&#39;s own photographs — Pixelfed&#39;s <code>MediaTag</code>, and a staple of every photo network there has been. <code>accounts</code> is the <strong>whole list</strong> 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&#39;s author may name anybody in it; anybody else asking gets the <strong>404</strong> a post that does not exist gets. A post with no picture is a <strong>422</strong>, 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 <code>Mention</code> and the post is re-sent as an <code>Update</code>, which is what makes a remote account&#39;s own server tell them; it does <strong>not</strong> widen who may see the post. Returns <code>{&quot;tagged_people&quot;: [Account, …]}</code>.</p>\n<h2 id=\"post-api-pixelfed-v1-compose-tag\">POST /api/pixelfed/v1/compose/tag</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong><code>status_id</code> (required), <code>accounts</code> (a list of handles or ids)</p>\n<p>The second spelling of the tagging route above, onto the same method: the same whole-list rule, the same <strong>404</strong> for a post that is not the viewer&#39;s and the same <strong>422</strong> for a post without a picture or a list past twenty. Returns <code>{&quot;tagged_people&quot;: [Account, …]}</code>.</p>\n<h2 id=\"post-api-v1-1-compose-tag-untagme\">POST /api/v1.1/compose/tag/untagme</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong><code>status_id</code> (required)</p>\n<p>Takes the viewer&#39;s own name off a photograph, which is Pixelfed&#39;s whole remedy for being named in somebody else&#39;s picture: being in one is not something to need their permission to leave. The post&#39;s author may also take a name off, and does so through the same route with the post as theirs. <code>{&quot;untagged&quot;: true}</code>, or <code>false</code> when there was no such name.</p>\n<h2 id=\"post-api-pixelfed-v1-compose-tag-untagme\">POST /api/pixelfed/v1/compose/tag/untagme</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong><code>status_id</code> (required)</p>\n<p>The second spelling of untagging: takes the viewer&#39;s own name off the post and answers <code>{&quot;untagged&quot;: true}</code>, or <code>false</code> when there was no such name.</p>\n<h2 id=\"get-api-v1-1-accounts-account-id-tagged\">GET /api/v1.1/accounts/{account_id}/tagged</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> scope) · <strong>Parameters: </strong><code>limit</code> (20, max 40), <code>max_id</code></p>\n<p>&quot;Photos of you&quot;, for anybody: the posts that account is named in, newest first, as Status entities. Which of them the reader may see is <strong>not</strong> 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 <strong>short without being the last</strong>: whether there is another is said by a <code>Link: &lt;…?max_id=…&gt;; rel=&quot;next&quot;</code> 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.</p>\n<h2 id=\"get-api-pixelfed-v1-accounts-account-id-tagged\">GET /api/pixelfed/v1/accounts/{account_id}/tagged</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> scope) · <strong>Parameters: </strong><code>limit</code> (20, max 40), <code>max_id</code></p>\n<p>&quot;Photos of you&quot; 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 <code>Link</code> header carrying the next cursor.</p>\n<h2 id=\"get-api-v1-1-discover-categories\">GET /api/v1.1/discover/categories</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The subjects this instance says it is about, in the order an administrator put them in: <code>{&quot;categories&quot;: [{&quot;id&quot;, &quot;name&quot;, &quot;hashtags&quot;: [&quot;brutalism&quot;, …]}]}</code>. <strong>Curated, not counted</strong> — every other route in this section ranks something, and this one is the instance&#39;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 (<code>[]</code>) until somebody names one, which is why the page renders nothing rather than an empty shelf. Pixelfed&#39;s own <code>DiscoverCategory</code>, minus its per-category cover picture.</p>\n<h2 id=\"get-api-v1-1-discover-accounts-popular\">GET /api/v1.1/discover/accounts/popular</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (20, max 20)</p>\n<p>The same suggestions <code>/api/v2/suggestions</code> answers, unwrapped — Mastodon wraps each account in a <code>{source, account}</code> suggestion and Pixelfed sends the accounts themselves. Needs a viewer, as the Mastodon route does: there is no anonymous &quot;accounts you might follow&quot;.</p>\n<h2 id=\"get-api-pixelfed-v1-discover-accounts-popular\">GET /api/pixelfed/v1/discover/accounts/popular</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (20, max 20)</p>\n<p>The same suggested accounts under the second prefix: a bare list of Account entities, and a <strong>401</strong> without a viewer.</p>\n<h2 id=\"get-api-v1-1-discover-posts\">GET /api/v1.1/discover/posts</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20, max 20), <code>offset</code> (0), <code>period</code></p>\n<p>The same answer as <code>/api/v2/discover/posts</code>, at the path the app asks for — a second route onto one implementation, not a second implementation.</p>\n<h2 id=\"get-api-v1-1-discover-posts-hashtags\">GET /api/v1.1/discover/posts/hashtags</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20, max 20), <code>period</code></p>\n<p>The trending tags <code>/api/v1/trends/tags</code> answers, for the row of tags above the discover grid.</p>\n<h2 id=\"get-api-pixelfed-v1-discover-posts-hashtags\">GET /api/pixelfed/v1/discover/posts/hashtags</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20, max 20), <code>period</code></p>\n<p>The same trending tags under the second prefix, in the same shape. No viewer is needed; one is honoured when a token is sent.</p>\n<h2 id=\"get-api-v1-1-discover-posts-trending\">GET /api/v1.1/discover/posts/trending</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>range</code> (<code>daily</code>, <code>monthly</code>, <code>yearly</code>), <code>limit</code> (20, max 20), <code>offset</code></p>\n<p>The path the app&#39;s Discover screen actually calls, onto the same implementation as <code>/api/v1.1/discover/posts</code>. <code>daily</code> is this app&#39;s one-day trend window, <code>monthly</code> and <code>yearly</code> its ten-day one — the counters run no further back.</p>\n<h2 id=\"get-api-pixelfed-v1-discover-posts-trending\">GET /api/pixelfed/v1/discover/posts/trending</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>range</code> (<code>daily</code>, <code>monthly</code>, <code>yearly</code>), <code>limit</code> (20, max 20), <code>offset</code></p>\n<p>The same trending grid under the second prefix: public Status entities, most interacted with first in the window <code>range</code> names, with link previews and places attached. No viewer is needed; one is honoured when a token is sent.</p>\n<h2 id=\"get-api-v1-1-discover-posts-network-trending\">GET /api/v1.1/discover/posts/network/trending</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>range</code>, <code>limit</code>, <code>offset</code></p>\n<p>Pixelfed&#39;s &quot;trending across the network&quot;. The same answer as above: what this server knows of the network <em>is</em> what it has cached, and the trend counters already cover it.</p>\n<h2 id=\"get-api-v1-2-stories-carousel\">GET /api/v1.2/stories/carousel</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:stories</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The same stories <code>/api/v1/stories/carousel</code> answers, in the shape the app&#39;s story bar draws: <code>{self, nodes}</code>, one node per account (<code>id</code>, <code>user</code>, <code>nodes</code>, <code>url</code>, <code>seen</code>), each story a node of <code>id</code>, <code>pid</code>, <code>type</code> (<code>photo</code>/<code>video</code>), <code>src</code>, <code>duration</code>, <code>seen</code>, <code>created_at</code>.</p>\n<h2 id=\"get-api-pixelfed-v1-stories-carousel\">GET /api/pixelfed/v1/stories/carousel</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:stories</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The same story bar under the second prefix: <code>{self, nodes}</code>, the viewer&#39;s own stories first and then those of the accounts they follow, each node shaped as the row above lists.</p>\n<h2 id=\"post-api-v1-1-stories-seen\">POST /api/v1.1/stories/seen</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p><code>POST /api/v1/stories/{id}/seen</code> with the id in the body, which is where the app puts it. Answers <code>{&quot;code&quot;: 200}</code>.</p>\n<h2 id=\"post-api-pixelfed-v1-stories-seen\">POST /api/pixelfed/v1/stories/seen</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>Marks the story seen for this viewer under the second prefix; a repeat is a no-op rather than a second view. Answers <code>{&quot;code&quot;: 200}</code>. Rate-limited to 300 a minute.</p>\n<h2 id=\"post-api-v1-1-stories-self-expire-id\">POST /api/v1.1/stories/self-expire/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong>—</p>\n<p><code>DELETE /api/v1/stories/{id}</code> under the name the app uses. Answers <code>{&quot;code&quot;: 200, &quot;msg&quot;: …}</code>.</p>\n<h2 id=\"post-api-pixelfed-v1-stories-self-expire-id\">POST /api/pixelfed/v1/stories/self-expire/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes one of the viewer&#39;s own stories early, with the record of who saw it; somebody else&#39;s is a <strong>404</strong>. Answers <code>{&quot;code&quot;: 200, &quot;msg&quot;: …}</code>.</p>\n<h2 id=\"get-api-v1-2-stories-viewers\">GET /api/v1.2/stories/viewers</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:stories</code> scope) · <strong>Parameters: </strong><code>sid</code> (required)</p>\n<p>Who watched one of the viewer&#39;s <strong>own</strong> stories, newest viewer first, as Account entities. Somebody else&#39;s story is the same <strong>404</strong> as one that does not exist: who watched is told to the poster and to nobody else, like the view count.</p>\n<h2 id=\"get-api-pixelfed-v1-stories-viewers\">GET /api/pixelfed/v1/stories/viewers</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:stories</code> scope) · <strong>Parameters: </strong><code>sid</code> (required)</p>\n<p>Who watched one of the viewer&#39;s own stories, newest viewer first, as Account entities; somebody else&#39;s story is the same <strong>404</strong> as one that does not exist.</p>\n<h2 id=\"post-api-v1-2-stories-react\">POST /api/v1.2/stories/react</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong><code>sid</code> (required), <code>reaction</code> (required, at most 20 characters)</p>\n<p>An emoji sent back to whoever posted a story. Only somebody who <strong>follows</strong> 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 <strong>404</strong> as one that does not exist. At most five answers to one story from one account (Pixelfed&#39;s own number) — past that a <strong>422</strong>, 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 <code>Story:Reaction</code>; one to a story posted here notifies its author and goes nowhere else.</p>\n<h2 id=\"post-api-pixelfed-v1-stories-react\">POST /api/pixelfed/v1/stories/react</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong><code>sid</code> (required), <code>reaction</code> (required, at most 20 characters)</p>\n<p>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.</p>\n<h2 id=\"post-api-v1-2-stories-comment\">POST /api/v1.2/stories/comment</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong><code>sid</code> (required), <code>caption</code> (required, at most 500 characters)</p>\n<p>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. <strong>It is not a post</strong>: there is no <code>social_stream</code> 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 <code>Story:Reply</code>.</p>\n<h2 id=\"post-api-pixelfed-v1-stories-comment\">POST /api/pixelfed/v1/stories/comment</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong><code>sid</code> (required), <code>caption</code> (required, at most 500 characters)</p>\n<p>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 <code>Story:Reply</code>. Answers with the reply in the shape the reactions list uses. Rate-limited to 60 a minute.</p>\n<h2 id=\"get-api-v1-2-stories-reactions\">GET /api/v1.2/stories/reactions</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:stories</code> scope) · <strong>Parameters: </strong><code>sid</code> (required)</p>\n<p>What has been said about one of the viewer&#39;s <strong>own</strong> stories, oldest first: <code>{&quot;reactions&quot;: [{&quot;id&quot;, &quot;story_id&quot;, &quot;type&quot;: </code>reaction<code> or </code>reply<code>, &quot;content&quot;, &quot;created_at&quot;, &quot;account&quot;}]}</code>. Somebody else&#39;s story is a <strong>404</strong>, like the viewer list and the view count: who answered is the poster&#39;s business.</p>\n<h2 id=\"get-api-pixelfed-v1-stories-reactions\">GET /api/pixelfed/v1/stories/reactions</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:stories</code> scope) · <strong>Parameters: </strong><code>sid</code> (required)</p>\n<p>What has been said about one of the viewer&#39;s own stories, oldest first, as <code>{&quot;reactions&quot;: […]}</code> in the shape the row above lists; somebody else&#39;s story is a <strong>404</strong>.</p>\n<h2 id=\"get-api-v1-2-stories-mention-autocomplete\">GET /api/v1.2/stories/mention-autocomplete</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong><code>q</code> (required)</p>\n<p>The accounts a <code>@</code> in a caption could mean — the same search <code>/api/v1/accounts/search</code> runs without <code>resolve</code>, capped at 24.</p>\n<h2 id=\"get-api-v1-1-collections-self\">GET /api/v1.1/collections/self</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:collections</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s collections in Pixelfed&#39;s shape: <code>id</code>, <code>pid</code>, <code>visibility</code> (<code>public</code>, or <code>private</code> for followers-only), <code>title</code>, <code>description</code>, <code>thumb</code> (the first picture of the first post), <code>url</code> (this app&#39;s own page for it), <code>post_count</code>, <code>published_at</code>, <code>created_at</code>, <code>updated_at</code>.</p>\n<h2 id=\"get-api-pixelfed-v1-collections-self\">GET /api/pixelfed/v1/collections/self</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:collections</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s collections in Pixelfed&#39;s shape under the second prefix — the same rows as above, down to <code>thumb</code> and <code>post_count</code>.</p>\n<h2 id=\"get-api-v1-1-accounts-username-username\">GET /api/v1.1/accounts/username/{username}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>An Account by its username — bare for a local account, <code>name@host</code> for a remote one this server already knows, an actor URL or a client id. Nothing is fetched from elsewhere: <code>/api/v1/accounts/lookup</code> with the name in the path.</p>\n<h2 id=\"get-api-v1-1-accounts-mutuals-id\">GET /api/v1.1/accounts/mutuals/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The accounts the viewer follows that also follow <code>{id}</code> — which is exactly Mastodon&#39;s <code>familiar_followers</code>, unwrapped, capped at 24.</p>\n<h2 id=\"delete-api-v1-1-accounts-avatar\">DELETE /api/v1.1/accounts/avatar</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> scope) · <strong>Parameters: </strong>—</p>\n<p><code>DELETE /api/v1/profile/avatar</code> under the app&#39;s name: removes the picture and answers with the account as it now is.</p>\n<h2 id=\"delete-api-pixelfed-v1-accounts-avatar\">DELETE /api/pixelfed/v1/accounts/avatar</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes the viewer&#39;s picture under the second prefix and answers with the account as it now is.</p>\n<h2 id=\"post-api-v1-1-report\">POST /api/v1.1/report</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:reports</code> scope) · <strong>Parameters: </strong><code>report_type</code> (required: <code>spam</code>, <code>sensitive</code>, <code>abusive</code>, <code>underage</code>, <code>violence</code>, <code>copyright</code>, <code>impersonation</code>, <code>scam</code>, <code>terrorism</code>), <code>object_id</code> (required), <code>object_type</code> (required: <code>post</code>, <code>user</code>, <code>story</code>), <code>message</code></p>\n<p>A report as the app files one, kept as the report this server keeps. The reason becomes Mastodon&#39;s category (<code>spam</code> → <code>spam</code>, <code>copyright</code> → <code>legal</code>, <code>abusive</code>/<code>underage</code>/<code>violence</code>/<code>terrorism</code> → <code>violation</code>, the rest → <code>other</code>) and is kept in the comment as well, because <code>violation</code> says less than <code>underage</code> did. A post is reported against its author and carried with the report; a story against its owner alone. Reporting yourself is a <strong>422</strong>. Answers <code>{&quot;msg&quot;, &quot;code&quot;: 200}</code>. Rate-limited to 30 an hour, per address and per account.</p>\n<h2 id=\"post-api-pixelfed-v1-report\">POST /api/pixelfed/v1/report</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:reports</code> scope) · <strong>Parameters: </strong><code>report_type</code> (required), <code>object_id</code> (required), <code>object_type</code> (required: <code>post</code>, <code>user</code>, <code>story</code>), <code>message</code></p>\n<p>The report route under the second prefix: the same nine reasons, the same mapping onto a Mastodon category, the same <strong>422</strong> for reporting yourself. Answers <code>{&quot;msg&quot;, &quot;code&quot;: 200}</code>. Thirty an hour per account.</p>\n<h2 id=\"get-api-v1-1-compose-settings\">GET /api/v1.1/compose/settings</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>What the app&#39;s composer reads first: <code>allowed_media_types</code>, <code>max_caption_length</code>, <code>default_license</code> (1, all rights reserved — the only licence a post here carries), <code>media_descriptions</code> (<code>false</code>: alt text is asked for, not demanded), <code>max_file_size</code>, <code>max_media_attachments</code>, <code>max_altext_length</code>, <code>default_scope</code> (the viewer&#39;s posting default, in Pixelfed&#39;s words).</p>\n<h2 id=\"get-api-pixelfed-v1-compose-settings\">GET /api/pixelfed/v1/compose/settings</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The composer&#39;s ceilings and defaults under the second prefix — the same eight keys as the row above, <code>default_scope</code> being the viewer&#39;s own posting default.</p>\n<h2 id=\"post-api-pixelfed-v1-archive-add-id\">POST /api/pixelfed/v1/archive/add/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>Puts one of the caller&#39;s own posts away.</strong> It leaves this server&#39;s profile, timelines, hashtag pages, search and outbox — every list this server builds — and is <em>not</em> deleted and <em>not</em> federated: the post is still on every server that received it, and taking it back from them is what <code>DELETE /api/v1/statuses/{id}</code> is for. Reversible, which is the point. A post that is not the caller&#39;s own, or not this server&#39;s, is a <strong>404</strong>. <code>{&quot;code&quot;: 200}</code>.</p>\n<h2 id=\"post-api-pixelfed-v1-archive-remove-id\">POST /api/pixelfed/v1/archive/remove/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Puts it back. Same 404.</p>\n<h2 id=\"get-api-pixelfed-v1-archive-list\">GET /api/pixelfed/v1/archive/list</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> scope) · <strong>Parameters: </strong><code>limit</code> (50, max 50), <code>max_id</code></p>\n<p>The caller&#39;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 (<code>StreamRequestBuilder::hideArchived()</code>), so a list written later shows none until somebody decides it should.</p>\n<h2 id=\"get-api-pixelfed-v1-app-settings\">GET /api/pixelfed/v1/app/settings</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The Pixelfed app&#39;s own switches, kept on the server so that a reinstall finds the app as it was left: <code>timelines</code> (<code>show_public</code>, <code>show_network</code>, <code>hide_likes_shares</code>), <code>media</code> (<code>hide_public_behind_cw</code>, <code>always_show_cw</code>, <code>show_alt_text</code>) and <code>appearance</code> (<code>links_use_in_app_browser</code>, <code>theme</code> — <code>light</code>, <code>dark</code> or <code>system</code>). Answered as <code>{id, username, updated_at, common}</code>, with Pixelfed&#39;s own defaults and <code>updated_at: null</code> until the account has saved them once, which is how the app tells &quot;never set&quot; from &quot;set to the defaults&quot;. <strong>Not one of them is a setting of this app</strong>: they decide what that client draws, and the server&#39;s part is to remember rather than to interpret.</p>\n<h2 id=\"post-api-pixelfed-v1-app-settings\">POST /api/pixelfed/v1/app/settings</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> scope to store, <code>read</code> without <code>common</code>) · <strong>Parameters: </strong><code>common</code></p>\n<p>Stores the switches and answers the same <code>{id, username, updated_at, common}</code>. Storing needs <code>write:accounts</code> (or <code>write</code>): the switches are the account&#39;s, and a token that may only read must not be able to turn content warnings off in somebody&#39;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&#39;s account. A POST with no <code>common</code> is a read.</p>\n<h2 id=\"get-api-v1-1-nag-state\">GET /api/v1.1/nag/state</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p><code>{&quot;active&quot;: false}</code>. Pixelfed&#39;s nag is a banner its server raises when it wants something of the user; this one never does.</p>\n<h2 id=\"get-api-v1-1-push-state\">GET /api/v1.1/push/state</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The legacy Pixelfed-compatible push settings route is disabled: <code>notify_enabled</code>, <code>has_token</code> and all <code>notify_*</code> values are <code>false</code>. This route is separate from Mastodon&#39;s working Web Push subscription API at <code>/api/v1/push/subscription</code>.</p>\n<h2 id=\"post-api-v1-1-push-disable\">POST /api/v1.1/push/disable</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>push</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The same state as above. Disabling what is already off changes nothing.</p>\n<h2 id=\"post-api-v1-1-push-update\">POST /api/v1.1/push/update</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>push</code> scope) · <strong>Parameters: </strong>—</p>\n<p>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.</p>\n<h2 id=\"post-api-v1-1-push-compare\">POST /api/v1.1/push/compare</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong><code>expo_token</code></p>\n<p><code>match: false</code>, <code>has_existing: false</code> — there is no token here to compare against.</p>\n<h2 id=\"get-api-v1-tags-hashtag-related\">GET /api/v1/tags/{hashtag}/related</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20, max 40)</p>\n<p>The tags that travel with one — those on the same <strong>public</strong> 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&#39;s route; Mastodon has no equivalent.</p>\n<h2 id=\"get-api-v1-1-direct-thread\">GET /api/v1.1/direct/thread</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> scope) · <strong>Parameters: </strong><code>pid</code> (required), <code>max_id</code>, <code>min_id</code></p>\n<p>One direct-message thread as the app&#39;s chat screen draws it: the other party on top (<code>id</code>, <code>name</code>, <code>username</code>, <code>avatar</code>, <code>url</code>, <code>isLocal</code>, <code>domain</code>, <code>lastMessage</code>, <code>timeAgo</code>) and <code>messages</code>, oldest first, twenty a page — each <code>id</code>, <code>isAuthor</code>, <code>type</code> (<code>text</code>, <code>photo</code>, <code>video</code>), <code>text</code> (the post without its markup), <code>media</code>, <code>carousel</code>, <code>created_at</code>, <code>timeAgo</code>, <code>seen</code>, <code>reportId</code>. The messages are this app&#39;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.</p>\n<h2 id=\"get-api-pixelfed-v1-direct-thread\">GET /api/pixelfed/v1/direct/thread</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> scope) · <strong>Parameters: </strong><code>pid</code> (required), <code>max_id</code>, <code>min_id</code></p>\n<p>The chat screen under the second prefix: the other party on top and <code>messages</code>, oldest first, twenty a page, in the shape the row above lists.</p>\n<h2 id=\"post-api-v1-1-direct-thread-send\">POST /api/v1.1/direct/thread/send</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong><code>to_id</code> (required), <code>message</code> (required, 1–500), <code>type</code> (<code>text</code>, <code>emoji</code>)</p>\n<p>Sends one message: a direct post to the account, through the same path the composer&#39;s own direct messages take, with the recipient&#39;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 <strong>422</strong>. Rate-limited to 60 a minute.</p>\n<h2 id=\"post-api-pixelfed-v1-direct-thread-send\">POST /api/pixelfed/v1/direct/thread/send</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong><code>to_id</code> (required), <code>message</code> (required, 1–500), <code>type</code> (<code>text</code>, <code>emoji</code>)</p>\n<p>Sends one direct message under the second prefix and answers with it as the thread shows it. Sending to yourself is a <strong>422</strong>. Rate-limited to 60 a minute.</p>\n<h2 id=\"delete-api-v1-1-direct-thread-message\">DELETE /api/v1.1/direct/thread/message</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>Takes one of the viewer&#39;s own messages back — <code>DELETE /api/v1/statuses/{id}</code> under the app&#39;s name. Somebody else&#39;s is the same <strong>404</strong> as one that never existed. Answers <code>[200]</code>, as Pixelfed does.</p>\n<h2 id=\"delete-api-pixelfed-v1-direct-thread-message\">DELETE /api/pixelfed/v1/direct/thread/message</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>Takes one of the viewer&#39;s own messages back under the second prefix; somebody else&#39;s is the same <strong>404</strong> as one that never existed. Answers <code>[200]</code>.</p>\n<h2 id=\"get-api-v1-1-direct-compose-mutuals\">GET /api/v1.1/direct/compose/mutuals</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Who the app&#39;s &quot;new message&quot; 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.</p>\n","toc":[{"id":"get-api-v2-config","text":"GET /api/v2/config","level":2},{"id":"get-api-v1-1-teams","text":"GET /api/v1.1/teams","level":2},{"id":"get-api-v1-1-portfolio","text":"GET /api/v1.1/portfolio","level":2},{"id":"post-api-v1-1-portfolio","text":"POST /api/v1.1/portfolio","level":2},{"id":"get-api-v1-1-portfolio-handle","text":"GET /api/v1.1/portfolio/{handle}","level":2},{"id":"post-api-v1-1-compose-tag","text":"POST /api/v1.1/compose/tag","level":2},{"id":"post-api-pixelfed-v1-compose-tag","text":"POST /api/pixelfed/v1/compose/tag","level":2},{"id":"post-api-v1-1-compose-tag-untagme","text":"POST /api/v1.1/compose/tag/untagme","level":2},{"id":"post-api-pixelfed-v1-compose-tag-untagme","text":"POST /api/pixelfed/v1/compose/tag/untagme","level":2},{"id":"get-api-v1-1-accounts-account-id-tagged","text":"GET /api/v1.1/accounts/{account_id}/tagged","level":2},{"id":"get-api-pixelfed-v1-accounts-account-id-tagged","text":"GET /api/pixelfed/v1/accounts/{account_id}/tagged","level":2},{"id":"get-api-v1-1-discover-categories","text":"GET /api/v1.1/discover/categories","level":2},{"id":"get-api-v1-1-discover-accounts-popular","text":"GET /api/v1.1/discover/accounts/popular","level":2},{"id":"get-api-pixelfed-v1-discover-accounts-popular","text":"GET /api/pixelfed/v1/discover/accounts/popular","level":2},{"id":"get-api-v1-1-discover-posts","text":"GET /api/v1.1/discover/posts","level":2},{"id":"get-api-v1-1-discover-posts-hashtags","text":"GET /api/v1.1/discover/posts/hashtags","level":2},{"id":"get-api-pixelfed-v1-discover-posts-hashtags","text":"GET /api/pixelfed/v1/discover/posts/hashtags","level":2},{"id":"get-api-v1-1-discover-posts-trending","text":"GET /api/v1.1/discover/posts/trending","level":2},{"id":"get-api-pixelfed-v1-discover-posts-trending","text":"GET /api/pixelfed/v1/discover/posts/trending","level":2},{"id":"get-api-v1-1-discover-posts-network-trending","text":"GET /api/v1.1/discover/posts/network/trending","level":2},{"id":"get-api-v1-2-stories-carousel","text":"GET /api/v1.2/stories/carousel","level":2},{"id":"get-api-pixelfed-v1-stories-carousel","text":"GET /api/pixelfed/v1/stories/carousel","level":2},{"id":"post-api-v1-1-stories-seen","text":"POST /api/v1.1/stories/seen","level":2},{"id":"post-api-pixelfed-v1-stories-seen","text":"POST /api/pixelfed/v1/stories/seen","level":2},{"id":"post-api-v1-1-stories-self-expire-id","text":"POST /api/v1.1/stories/self-expire/{id}","level":2},{"id":"post-api-pixelfed-v1-stories-self-expire-id","text":"POST /api/pixelfed/v1/stories/self-expire/{id}","level":2},{"id":"get-api-v1-2-stories-viewers","text":"GET /api/v1.2/stories/viewers","level":2},{"id":"get-api-pixelfed-v1-stories-viewers","text":"GET /api/pixelfed/v1/stories/viewers","level":2},{"id":"post-api-v1-2-stories-react","text":"POST /api/v1.2/stories/react","level":2},{"id":"post-api-pixelfed-v1-stories-react","text":"POST /api/pixelfed/v1/stories/react","level":2},{"id":"post-api-v1-2-stories-comment","text":"POST /api/v1.2/stories/comment","level":2},{"id":"post-api-pixelfed-v1-stories-comment","text":"POST /api/pixelfed/v1/stories/comment","level":2},{"id":"get-api-v1-2-stories-reactions","text":"GET /api/v1.2/stories/reactions","level":2},{"id":"get-api-pixelfed-v1-stories-reactions","text":"GET /api/pixelfed/v1/stories/reactions","level":2},{"id":"get-api-v1-2-stories-mention-autocomplete","text":"GET /api/v1.2/stories/mention-autocomplete","level":2},{"id":"get-api-v1-1-collections-self","text":"GET /api/v1.1/collections/self","level":2},{"id":"get-api-pixelfed-v1-collections-self","text":"GET /api/pixelfed/v1/collections/self","level":2},{"id":"get-api-v1-1-accounts-username-username","text":"GET /api/v1.1/accounts/username/{username}","level":2},{"id":"get-api-v1-1-accounts-mutuals-id","text":"GET /api/v1.1/accounts/mutuals/{id}","level":2},{"id":"delete-api-v1-1-accounts-avatar","text":"DELETE /api/v1.1/accounts/avatar","level":2},{"id":"delete-api-pixelfed-v1-accounts-avatar","text":"DELETE /api/pixelfed/v1/accounts/avatar","level":2},{"id":"post-api-v1-1-report","text":"POST /api/v1.1/report","level":2},{"id":"post-api-pixelfed-v1-report","text":"POST /api/pixelfed/v1/report","level":2},{"id":"get-api-v1-1-compose-settings","text":"GET /api/v1.1/compose/settings","level":2},{"id":"get-api-pixelfed-v1-compose-settings","text":"GET /api/pixelfed/v1/compose/settings","level":2},{"id":"post-api-pixelfed-v1-archive-add-id","text":"POST /api/pixelfed/v1/archive/add/{id}","level":2},{"id":"post-api-pixelfed-v1-archive-remove-id","text":"POST /api/pixelfed/v1/archive/remove/{id}","level":2},{"id":"get-api-pixelfed-v1-archive-list","text":"GET /api/pixelfed/v1/archive/list","level":2},{"id":"get-api-pixelfed-v1-app-settings","text":"GET /api/pixelfed/v1/app/settings","level":2},{"id":"post-api-pixelfed-v1-app-settings","text":"POST /api/pixelfed/v1/app/settings","level":2},{"id":"get-api-v1-1-nag-state","text":"GET /api/v1.1/nag/state","level":2},{"id":"get-api-v1-1-push-state","text":"GET /api/v1.1/push/state","level":2},{"id":"post-api-v1-1-push-disable","text":"POST /api/v1.1/push/disable","level":2},{"id":"post-api-v1-1-push-update","text":"POST /api/v1.1/push/update","level":2},{"id":"post-api-v1-1-push-compare","text":"POST /api/v1.1/push/compare","level":2},{"id":"get-api-v1-tags-hashtag-related","text":"GET /api/v1/tags/{hashtag}/related","level":2},{"id":"get-api-v1-1-direct-thread","text":"GET /api/v1.1/direct/thread","level":2},{"id":"get-api-pixelfed-v1-direct-thread","text":"GET /api/pixelfed/v1/direct/thread","level":2},{"id":"post-api-v1-1-direct-thread-send","text":"POST /api/v1.1/direct/thread/send","level":2},{"id":"post-api-pixelfed-v1-direct-thread-send","text":"POST /api/pixelfed/v1/direct/thread/send","level":2},{"id":"delete-api-v1-1-direct-thread-message","text":"DELETE /api/v1.1/direct/thread/message","level":2},{"id":"delete-api-pixelfed-v1-direct-thread-message","text":"DELETE /api/pixelfed/v1/direct/thread/message","level":2},{"id":"get-api-v1-1-direct-compose-mutuals","text":"GET /api/v1.1/direct/compose/mutuals","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"pixelfeds-own-routes","manual":false,"prev":{"path":"/docs/api-lists","title":"Lists"},"next":{"path":"/docs/api-starter-packs","title":"Starter packs"},"parent":"api-mastodon-compatible-api"},{"slug":"api-starter-packs","path":"/docs/api-starter-packs","title":"Starter packs","description":"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…","group":"api","html":"<p>A named handful of accounts worth following. They answer the one question a new account has that no algorithm here can: <code>SuggestionService</code> 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.</p>\n<p>A pack is a list of <code>user@host</code> handles and nothing else. No table: the accounts are not this instance&#39;s to own, and the handles are the only durable reference to them. The exception is a pack read in from another server: see <em>Collections from other servers</em> below.</p>\n<h2 id=\"get-api-v1-starter-packs\">GET /api/v1/starter_packs</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Every pack, <strong>resolving nobody</strong>: 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.</p>\n<h2 id=\"get-api-v1-starter-packs-slug\">GET /api/v1/starter_packs/{slug}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>One pack with its handles resolved to Mastodon <code>Account</code> entities — the same shape <code>/api/v1/suggestions</code> 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 <code>unresolved</code> and is queued to be fetched in the background (<code>Cron\\ResolveActor</code>), 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&#39;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. <strong>404</strong> for an unknown slug, and for a pack read in whose curator this instance&#39;s moderation keeps out.</p>\n<h2 id=\"post-api-v1-starter-packs-slug-follow\">POST /api/v1/starter_packs/{slug}/follow</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:follows</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Follows everyone in the pack who can be reached, and answers with <code>followed</code>: 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&#39;s own account is skipped, and so is an account the pack would not offer.</p>\n<p><strong>The shipped packs are an editorial choice and a deliberately narrow one</strong>: 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.</p>\n<p>An administrator replaces or extends them with the <code>starter_packs</code> app value — a JSON array of <code>{slug, name, description, handles}</code>. Three states, deliberately distinguishable: <strong>unset</strong> is whatever ships; <strong><code>[]</code></strong> is no packs at all, which is the right answer for an instance that would rather suggest nobody; <strong>a list</strong> 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 <em>object</em> decodes to an array too, so each entry is checked as well as the whole.)</p>\n<p><strong>Collections from other servers.</strong> Mastodon 4.6 lets an account publish Collections — named lists of up to 25 accounts it recommends — and federates them as FEP-7aa9 <code>FeaturedCollection</code>s, linked from the curator&#39;s actor as <code>featuredCollections</code>. Once a day (<code>Cron\\StarterPackSources</code>, or now with <code>occ social:starter-packs:refresh</code>) <code>CollectionPackService</code> reads the collections of the curators the <code>starter_pack_sources</code> app value names — unset, the curated collections on mastodon.social — and keeps them in <code>social_starter_pack</code>. Only a collection marked discoverable and not sensitive is kept, and only the members whose own server serves a <code>FeatureAuthorization</code> naming them and this collection, as the FEP requires a reader to check — the first 50 this instance&#39;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&#39;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; <code>starter_packs</code> set to <code>[]</code> hides them too.</p>\n<p><strong>Bluesky&#39;s suggested starter packs</strong> are read with them, the same day and into the same table, while Bluesky is on and <code>bluesky:suggested</code> is among the sources (it is by default): <code>SuggestedStarterPacks</code> asks the AppView, signed out, for <code>app.bsky.unspecced.getSuggestedStarterPacks</code> and each pack&#39;s list, keeping at most 50 members a pack, and leaving out any account this instance blocks or Bluesky&#39;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&#39;s members are.</p>\n<p>Such a pack answers like the others, with <code>source</code> <code>fediverse</code> (or <code>bluesky</code>) and four fields the others leave <code>null</code>: <code>curator</code> (who published it, <code>user@host</code>), <code>url</code> (where it can be seen on the curator&#39;s server), <code>topic</code> (its hashtag, without <code>#</code>) and <code>language</code>. 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&#39; servers, and <em>follow</em> follows each as the actor it is, on whichever network. In the index its <code>size</code> is the stored member count, at most 50. <code>{slug}</code> is the collection&#39;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.</p>\n","toc":[{"id":"get-api-v1-starter-packs","text":"GET /api/v1/starter_packs","level":2},{"id":"get-api-v1-starter-packs-slug","text":"GET /api/v1/starter_packs/{slug}","level":2},{"id":"post-api-v1-starter-packs-slug-follow","text":"POST /api/v1/starter_packs/{slug}/follow","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"starter-packs","manual":false,"prev":{"path":"/docs/api-pixelfeds-own-routes","title":"Pixelfed's own routes"},"next":{"path":"/docs/api-finding-people-in-other-servers-directories","title":"Finding people in other servers' directories"},"parent":"api-mastodon-compatible-api"},{"slug":"api-finding-people-in-other-servers-directories","path":"/docs/api-finding-people-in-other-servers-directories","title":"Finding people in other servers' directories","description":"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…","group":"api","html":"<p>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 &quot;who is out there&quot;, which is what a directory is for — so these ask several of them at once.</p>\n<p>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. <strong>Nothing is aggregated</strong>: 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.</p>\n<h2 id=\"get-api-v1-follow-graph\">GET /api/v1/follow_graph</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (20, capped at 40)</p>\n<p><strong>Who the people you follow follow.</strong> For each of at most 20 accounts the viewer follows, their <code>following</code> 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 <code>{suggestions, asked, needs}</code>, where a suggestion carries the <code>account</code>, <code>followed_by</code> (how many) and <code>via</code> (a few of the handles that do) — Mastodon&#39;s Suggestion entity has nowhere to put the count, and the count is the whole reason to believe a graph suggestion. <code>asked</code> is how many collections actually answered: many servers do not publish one, Mastodon has a &quot;hide your social graph&quot; setting, and a server that will not say is not an error. <code>needs</code> is how many more follows it would take to be worth asking, so a page can say <em>follow one more account</em> instead of <em>nothing found</em>. Costs one outgoing request per account followed, so it is a route of its own rather than part of <code>/api/v2/suggestions</code>, and is rate-limited to 10 per five minutes, per address and per account. An answer is kept for half an hour.</p>\n<h2 id=\"get-api-v1-follow-graph-status\">GET /api/v1/follow_graph/status</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Whether that walk is worth making: <code>{suggestions: [], asked: 0, needs}</code>. Reads this instance&#39;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.</p>\n<h2 id=\"get-api-v1-directories\">GET /api/v1/directories</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The sources that will be asked, in the order they are asked, this instance first. Each is <code>{host, kind, label}</code>. Published rather than left for the client to assume: which servers get asked is an administrator&#39;s decision, and a reader is entitled to see whose directory they are searching before they search it.</p>\n<h2 id=\"get-api-v1-directories-hashtags\">GET /api/v1/directories/hashtags</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>q</code> (&#39;&#39;), <code>source</code> (&#39;&#39;), <code>limit</code> (20, capped at 40)</p>\n<p><strong>What other servers are talking about.</strong> With <code>q</code> empty, each asked server&#39;s own trending hashtags; with <code>q</code> set, that tag wherever those servers know it. Answers <code>{tags, sources}</code> with the same <code>sources</code> reporting as the search above. Ranked by <strong>how many servers named a tag</strong>, not by their counts added together: instances differ in size by four orders of magnitude, so a sum ranks the biggest server&#39;s opinion as everybody&#39;s, while &quot;busy on four servers&quot; 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.</p>\n<h2 id=\"get-api-v1-directories-search\">GET /api/v1/directories/search</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong><code>q</code> (&#39;&#39;), <code>source</code> (&#39;&#39;), <code>limit</code> (20, capped at 40)</p>\n<p>People matching <code>q</code>, merged from every source — or from one, with <code>source</code> naming its host. Answers <code>{accounts, sources}</code>. A viewer is required, unlike the local directory beside it: this route makes requests to other servers on the caller&#39;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.</p>\n<p>A <code>tags</code> row is <code>{name, servers, servers_count, uses, local}</code>. <code>name</code> is the tag as this instance spells it — lower-cased, without the <code>#</code>, 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. <code>servers</code> names them in the order they were asked, <code>local</code> says whether this instance has seen the tag as well, and <code>uses</code> 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.</p>\n<p><strong>Which servers can answer what is a fact about their APIs, not a choice here.</strong> A <code>mastodon</code> source is asked <code>/api/v1/trends/tags</code>, which is public; it has no public tag search, since <code>/api/v2/search</code> needs a token exactly as it does for accounts, so a search matches <code>q</code> against that same trending page and finds a tag that is busy there and nothing else. A <code>misskey</code> source is asked <code>hashtags/trend</code> and, for a search, <code>hashtags/search</code> — both public, so Misskey answers a search properly. <code>lemmy</code> and <code>wordpress</code> sources are not asked at all and are reported as <code>unsupported</code>: Lemmy organises by community and the curated directory lists people, so neither has the question.</p>\n<p><code>accounts</code> are <strong>not</strong> Mastodon <code>Account</code> entities and deliberately do not look like them. An <code>Account</code> carries an <code>id</code> a client hands straight back to this instance&#39;s API, and the id in a remote directory&#39;s answer is a row number in somebody else&#39;s database — the same string means a different person here. These carry <code>acct</code> (always a full <code>user@host</code>), <code>username</code>, <code>host</code>, <code>display_name</code>, <code>note</code> (<strong>text</strong>, with markup stripped: a bio arrives as HTML on Mastodon and as plain text on Misskey), <code>avatar</code>, <code>url</code>, <code>followers_count</code>, <code>statuses_count</code> (<code>-1</code> where the directory did not say), <code>bot</code>, <code>known</code> (whether this instance already holds the actor, so a client can offer the local profile instead of a stranger&#39;s website), <code>source</code> and <code>source_kind</code>. The handle is the durable reference and the only thing a client should act on — <code>POST /api/v1/current/follow?account=…</code> takes exactly that.</p>\n<p><code>sources</code> reports every source with a <code>status</code>: <code>ok</code>, <code>failed</code> (it did not answer) or <code>skipped</code> (the fan-out&#39;s ten-second budget ran out first). <strong>A client is expected to show it.</strong> &quot;Nobody by that name&quot; and &quot;that server did not answer&quot; are different answers, and a reader deciding whether to try another spelling needs to know which one they got.</p>\n<p>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&#39;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.</p>\n<ul>\n<li><strong><code>local</code></strong> — this instance&#39;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.</li>\n<li><strong><code>mastodon</code></strong> — <code>/api/v1/directory</code> and <code>/api/v1/accounts/lookup</code>, which is also what Pixelfed, Hometown, Glitch and most forks serve. Mastodon has <strong>no public search</strong> (<code>/api/v2/search</code> needs a token), which is a fact about Mastodon rather than an omission here: the lookup answers &quot;is there a <code>nextcloud</code> on that server&quot; exactly, the directory page answers &quot;who is active there&quot;, and the query is applied to that page by this app. One page of 80, not a walk of somebody else&#39;s user list.</li>\n<li><strong><code>misskey</code></strong> — <code>users/search</code>, a real substring search. A user&#39;s <code>host</code> is <code>null</code> when they are that server&#39;s own, which is the one thing that makes a Misskey handle ambiguous if taken at face value.</li>\n<li><strong><code>lemmy</code></strong> — <code>search</code> with <code>type_=Users</code>. Lemmy hands over the full <code>actor_id</code>, 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.</li>\n<li><strong><code>wordpress</code></strong> — a directory somebody keeps by hand, published as a WordPress site and asked through <code>/wp-json/wp/v2/posts?search=</code>. It is the only kind that answers a <strong>subject</strong>: every other source can say whether there is an <code>alice</code> 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&#39;s own text is read — nothing follows the links in it, so an entry cannot make this instance fetch an address somebody else chose. <code>fedi.directory</code> is the one that ships.</li>\n</ul>\n<p>Nobody on a domain this instance will not federate with is offered, silenced domains included. The fetch is already guarded — <code>CurlService</code> refuses a host the access list excludes — but that guards the server being <em>asked</em>; 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.</p>\n<p>An administrator sets the sources with the <code>directories</code> app value — a JSON array of <code>{host, kind, label?}</code>. The same three states as the starter packs, and for the same reasons: <strong>unset</strong> is what ships; <strong><code>[]</code></strong> is this instance alone; <strong>a list</strong> replaces the shipped sources entirely. A host written as a URL is read as a host, an unknown <code>kind</code> is read as <code>mastodon</code> rather than dropped, and <code>local</code> cannot be claimed by a remote entry. What ships is <code>fedi.directory</code> and the largest public instance of each software family whose purpose is people posting to people — <code>mastodon.social</code>, <code>misskey.io</code>, <code>lemmy.world</code>, <code>pixelfed.social</code>. None was chosen because somebody here likes it, and this instance publishes its own directory to them on exactly the same terms.</p>\n<p>Two more kinds of source are not configured at all, and each entry says which it is in its <code>origin</code> (<code>configured</code>, <code>federation</code>, <code>discovered</code>), because a reader is entitled to know how their Nextcloud came to be asking a stranger&#39;s server about people:</p>\n<ul>\n<li><strong>The servers this instance already federates with</strong>, most-known first — ranked by how many of their accounts are cached here, which is the strongest available signal for &quot;we deal with them a lot&quot;. An editorial list is somebody else&#39;s idea of where people are; this is the instance&#39;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 <code>Cron\\Cache</code> and never by the request, and the answer — including &quot;runs something none of these APIs fit&quot;, which leaves it out rather than asking it in a language it does not answer — is kept for a week in the <code>directory_known</code> 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 <code>directory_peers</code> app value, default 4; <code>0</code> asks none.</li>\n<li><strong>Servers named by a directory of servers</strong> — <code>fediverse.info</code>, which publishes a curated list with each server&#39;s software, so nothing has to be sniffed. The weakest of the three, being somebody else&#39;s editorial choice about servers this instance has never spoken to, so it comes last and contributes at most three. <code>Cron\\Cache</code> 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 <code>fediverse.info</code> — on a fresh install there are no discovered servers until the cron has run. Set the <code>directory_discovery</code> app value to <code>0</code> to ask nobody.</li>\n</ul>\n<p>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&#39;s own entry is never relabelled by a directory.</p>\n<p><code>communitywiki.org/trunk</code> is <strong>not</strong> 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.</p>\n","toc":[{"id":"get-api-v1-follow-graph","text":"GET /api/v1/follow_graph","level":2},{"id":"get-api-v1-follow-graph-status","text":"GET /api/v1/follow_graph/status","level":2},{"id":"get-api-v1-directories","text":"GET /api/v1/directories","level":2},{"id":"get-api-v1-directories-hashtags","text":"GET /api/v1/directories/hashtags","level":2},{"id":"get-api-v1-directories-search","text":"GET /api/v1/directories/search","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"finding-people-in-other-servers-directories","manual":false,"prev":{"path":"/docs/api-starter-packs","title":"Starter packs"},"next":{"path":"/docs/api-collections","title":"Collections"},"parent":"api-mastodon-compatible-api"},{"slug":"api-collections","path":"/docs/api-collections","title":"Collections","description":"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…","group":"api","html":"<p>Pixelfed&#39;s albums: a set of the owner&#39;s own posts, in an order the owner chooses. Mastodon defines nothing equivalent, so these are Pixelfed&#39;s route shapes — a client that knows Pixelfed finds them where it expects them. Every collection answered by these routes carries its owner as <code>account</code> (a Mastodon Account entity), so a page for one has somebody to head it with and can tell whether the reader may manage it.</p>\n<h2 id=\"get-api-v1-collections\">GET /api/v1/collections</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:collections</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Every collection the viewer owns, newest first, each with its first three posts as a cover.</p>\n<h2 id=\"post-api-v1-collections\">POST /api/v1/collections</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:collections</code> scope) · <strong>Parameters: </strong><code>title</code> (required), <code>description</code>, <code>visibility</code> (<code>public</code>)</p>\n<p>Creates a collection and returns it. A blank or whitespace-only title is a <strong>422</strong>. A <code>visibility</code> outside <code>public</code>/<code>followers</code> is stored as <code>public</code> rather than refused — there are only two meaningful values and neither is destructive. An account may hold 200 collections.</p>\n<h2 id=\"get-api-v1-collections-id\">GET /api/v1/collections/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>One collection with its cover. A public one is answered to a signed-out visitor, which is the point of publishing one; a <code>followers</code> one is answered to its owner and to accounts that follow them, and is a <strong>404</strong> to everybody else — the same 404 as an id that does not exist.</p>\n<h2 id=\"put-api-v1-collections-id\">PUT /api/v1/collections/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:collections</code> scope) · <strong>Parameters: </strong><code>title</code>, <code>description</code>, <code>visibility</code></p>\n<p>Updates only the fields that are sent, and returns the collection. Somebody else&#39;s collection is a <strong>404</strong>.</p>\n<h2 id=\"delete-api-v1-collections-id\">DELETE /api/v1/collections/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:collections</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes the collection and its contents. The posts themselves are untouched.</p>\n<h2 id=\"get-api-v1-collections-id-items\">GET /api/v1/collections/{id}/items</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (40, max 40), <code>offset</code> (0)</p>\n<p>The posts of a collection in the owner&#39;s order, as <code>Status</code> 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.</p>\n<h2 id=\"post-api-v1-collections-id-items\">POST /api/v1/collections/{id}/items</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:collections</code> scope) · <strong>Parameters: </strong><code>status_id</code> (required)</p>\n<p>Adds one of the viewer&#39;s <strong>own</strong> 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.</p>\n<h2 id=\"delete-api-v1-collections-id-items-status-id\">DELETE /api/v1/collections/{id}/items/{status_id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:collections</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Takes a post out. Removing one that is not in the collection is a no-op.</p>\n<h2 id=\"get-api-v1-accounts-account-id-collections\">GET /api/v1/accounts/{account_id}/collections</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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.</p>\n<p>A collection may only hold posts its <strong>owner wrote</strong>. A collection of other people&#39;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.</p>\n<p>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.</p>\n<p>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.</p>\n","toc":[{"id":"get-api-v1-collections","text":"GET /api/v1/collections","level":2},{"id":"post-api-v1-collections","text":"POST /api/v1/collections","level":2},{"id":"get-api-v1-collections-id","text":"GET /api/v1/collections/{id}","level":2},{"id":"put-api-v1-collections-id","text":"PUT /api/v1/collections/{id}","level":2},{"id":"delete-api-v1-collections-id","text":"DELETE /api/v1/collections/{id}","level":2},{"id":"get-api-v1-collections-id-items","text":"GET /api/v1/collections/{id}/items","level":2},{"id":"post-api-v1-collections-id-items","text":"POST /api/v1/collections/{id}/items","level":2},{"id":"delete-api-v1-collections-id-items-status-id","text":"DELETE /api/v1/collections/{id}/items/{status_id}","level":2},{"id":"get-api-v1-accounts-account-id-collections","text":"GET /api/v1/accounts/{account_id}/collections","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"collections","manual":false,"prev":{"path":"/docs/api-finding-people-in-other-servers-directories","title":"Finding people in other servers' directories"},"next":{"path":"/docs/api-places","title":"Places"},"parent":"api-mastodon-compatible-api"},{"slug":"api-places","path":"/docs/api-places","title":"Places","description":"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…","group":"api","html":"<p>Where a post was taken. <strong>Nothing here geocodes anything</strong> — no call goes to Nominatim, Google or anyone else. Sending somebody&#39;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.</p>\n<p>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 <code>social_place</code>, which holds one row per distinct place anyone here has posted from.</p>\n<h2 id=\"get-api-v1-places-search\">GET /api/v1/places/search</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong><code>q</code> (required), <code>limit</code> (20, max 20)</p>\n<p>Places whose name <strong>begins with</strong> <code>q</code>. A prefix match, not a substring one: <code>LIKE &#39;%term%&#39;</code> 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.</p>\n<h2 id=\"get-api-v1-places-id\">GET /api/v1/places/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One place.</p>\n<h2 id=\"get-api-v1-places-id-statuses\">GET /api/v1/places/{id}/statuses</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20, max 40), <code>max_id</code></p>\n<p>The <strong>public</strong> posts taken at a place, newest first, keyset-paged on the post id — what the place&#39;s page draws. Public only whoever asks: the page is a public page, and a followers-only post&#39;s location is as private as the post. Replies are left out, being fragments of somebody else&#39;s thread rather than pictures of the place. An unknown place is a <strong>404</strong> before any post is read. A viewer is optional and only marks the reader&#39;s own bookmarks and favourites on the posts.</p>\n<p>A post carries one by sending either <code>place_id</code> (from the search route) or <code>place_name</code> with optional <code>place_country</code>, <code>place_lat</code> and <code>place_long</code> to <code>POST /api/v1/statuses</code>. A <code>place_id</code> that no longer exists means &quot;nowhere&quot; 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 <code>place_country</code> that is not two letters is dropped, because a country column holding &quot;United Kingdom&quot; in one row and &quot;GB&quot; in another cannot group anything.</p>\n<p>The <code>Status</code> entity gains <code>place</code>, which is <code>null</code> 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.</p>\n<p>Places are local and are not federated: a peer sees the post, not where it was taken.</p>\n","toc":[{"id":"get-api-v1-places-search","text":"GET /api/v1/places/search","level":2},{"id":"get-api-v1-places-id","text":"GET /api/v1/places/{id}","level":2},{"id":"get-api-v1-places-id-statuses","text":"GET /api/v1/places/{id}/statuses","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"places","manual":false,"prev":{"path":"/docs/api-collections","title":"Collections"},"next":{"path":"/docs/api-stories","title":"Stories"},"parent":"api-mastodon-compatible-api"},{"slug":"api-stories","path":"/docs/api-stories","title":"Stories","description":"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…","group":"api","html":"<p><strong>In the API and on the wire, a 24-hour short is a story.</strong> The web client presents one feature, Shorts, with two lifetimes: a <em>kept</em> short is an ordinary status with a video, made and read through the status and timeline routes; a <em>24-hour</em> short is a story, made, read, seen, answered and deleted through the routes below, with the <code>read:stories</code>/<code>write:stories</code> scopes, and federated as Pixelfed&#39;s <code>Story</code> object (fetched through a bearcap, answered with <code>View</code>, <code>Story:Reaction</code> and <code>Story:Reply</code>). The web client&#39;s Shorts bar and the first part of its Shorts stack are drawn from the carousel; its composer posts a 24-hour short through <code>POST /api/v1/stories</code>. Route names, scopes and fields keep the word story, as Pixelfed&#39;s app expects them to.</p>\n<p>Pixelfed&#39;s stories: one picture, video or text card (drawn into a picture) that stops existing after a day. A story has no <code>social_stream</code> 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&#39;s followers as an <code>Add</code> whose object is a <code>Story</code>, and is withdrawn with a <code>Delete</code>: Pixelfed&#39;s verbs, and the ones its inbox handles. A <code>Create</code> would put it where posts go, and a server that does not know the type ignores the activity, which is the right outcome.</p>\n<p>An arriving story is kept only when somebody on this instance follows its author, and no longer than a day whatever the sender&#39;s <code>expiresAt</code> 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&#39;s promise about its own copy is one it can keep.</p>\n<p>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 <em>has</em> a story up is told only to its followers — which is why &quot;not yours to see&quot; and &quot;there are none&quot; are the same <strong>404</strong>.</p>\n<h2 id=\"get-api-v1-stories-carousel\">GET /api/v1/stories/carousel</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:stories</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s own live stories, then those of the accounts they follow, oldest first — the order a carousel plays them in. Each carries <code>seen</code> for this viewer.</p>\n<h2 id=\"get-api-v1-stories-self\">GET /api/v1/stories/self</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:stories</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s own live stories. Only here and in the carousel is <code>view_count</code> filled in: how many accounts watched is told to the poster and to nobody else.</p>\n<h2 id=\"post-api-v1-stories\">POST /api/v1/stories</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong><code>media_id</code> (required), <code>caption</code>, <code>duration</code> (5)</p>\n<p>Posts one of the viewer&#39;s own uploads. <code>duration</code> is clamped to 3–30 seconds and <code>caption</code> to 500 characters. An account may have 40 live at once. An unknown or someone else&#39;s <code>media_id</code> is a <strong>422</strong>.</p>\n<h2 id=\"delete-api-v1-stories-id\">DELETE /api/v1/stories/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes it early, with the record of who saw it. Somebody else&#39;s is a <strong>404</strong>.</p>\n<h2 id=\"post-api-v1-stories-id-seen\">POST /api/v1/stories/{id}/seen</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:stories</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Marks it seen. Called as a client scrolls, so a repeat is a no-op rather than a second view.</p>\n<h2 id=\"get-api-v1-accounts-account-id-stories\">GET /api/v1/accounts/{account_id}/stories</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:stories</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The live stories of one account: its own, or those of somebody the viewer follows. Anything else is a <strong>404</strong>.</p>\n<p><strong>The shape on the wire is Pixelfed&#39;s, because Pixelfed is the only network that has stories.</strong> Its inbox does not read a story out of the activity that carries it: <code>StoryFetch</code> requires <code>object.object</code>, decodes it as a <strong>bearcap</strong> (<code>bear:?t=…&amp;u=…</code>, FEP-d8c2) and fetches what it names with the token. An <code>Add</code> without one is dropped without a word. So a published story carries the capability beside the fields themselves — the fields for this app&#39;s own inbox and anything else that would rather read than fetch, the capability for Pixelfed — its <code>attachment</code> is <strong>one object typed <code>Image</code> or <code>Video</code></strong> rather than a list of <code>Document</code>s, and it states <code>published</code>, an <code>expiresAt</code> after it, and <code>can_reply</code>/<code>can_react</code> as <code>false</code>. Each of those is a gate in <code>StoryFetch::validatePayload()</code>; every one of them was measured against Pixelfed&#39;s source rather than guessed at.</p>\n<p>One thing this cannot fix from here: Pixelfed fans its own stories out with <code>FollowerService::softwareAudience($id, &#39;pixelfed&#39;)</code>, so it sends them <strong>only to instances it has identified as Pixelfed</strong>. 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.</p>\n<p>Stories from followed remote accounts appear in the carousel beside local ones; a story of the viewer&#39;s own is always local, since this instance is where they post.</p>\n<p>The expiry is enforced twice, by design. Every read filters on <code>expires_at</code>, and <code>Cron\\ExpiredStories</code> 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, &quot;what you can see&quot; and &quot;what is stored&quot; have to be the same statement.</p>\n","toc":[{"id":"get-api-v1-stories-carousel","text":"GET /api/v1/stories/carousel","level":2},{"id":"get-api-v1-stories-self","text":"GET /api/v1/stories/self","level":2},{"id":"post-api-v1-stories","text":"POST /api/v1/stories","level":2},{"id":"delete-api-v1-stories-id","text":"DELETE /api/v1/stories/{id}","level":2},{"id":"post-api-v1-stories-id-seen","text":"POST /api/v1/stories/{id}/seen","level":2},{"id":"get-api-v1-accounts-account-id-stories","text":"GET /api/v1/accounts/{account_id}/stories","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"stories","manual":false,"prev":{"path":"/docs/api-places","title":"Places"},"next":{"path":"/docs/api-conversations","title":"Conversations"},"parent":"api-mastodon-compatible-api"},{"slug":"api-conversations","path":"/docs/api-conversations","title":"Conversations","description":"Auth: public, no-csrf (viewer required, read:statuses or read scope) · Parameters: limit (20, capped at 40), max_id (0), min_id (0), since_id (0)","group":"api","html":"<h2 id=\"get-api-v1-conversations\">GET /api/v1/conversations</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> or <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (20, capped at 40), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0)</p>\n<p>The viewer&#39;s direct messages grouped into threads, as Mastodon <code>Conversation</code> entities — <code>{id, unread, accounts, last_status}</code> — newest message first. This is the screen Tusky, Ivory, Ice Cubes and Phanpy read direct messages from. <code>accounts</code> are the other participants and never the viewer, so a note to self has an empty <code>accounts</code>; <code>last_status</code> is nullable, as Mastodon declares it. Sends a <code>Link</code> header whose cursor is a <strong>message</strong> 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.</p>\n<h2 id=\"get-api-v1-conversations-unread-count\">GET /api/v1/conversations/unread_count</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p><code>{count}</code>: how many conversations hold something the account has not read. This app&#39;s own route — Mastodon has none, because its clients count the <code>unread</code> 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 <code>ETag</code> and answers <code>304</code> while nothing that changes the count — a direct message, a conversation marked read or dismissed, a block or mute — has changed.</p>\n<h2 id=\"post-api-v1-conversations-read-all\">POST /api/v1/conversations/read_all</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:conversations</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Marks every unread conversation read, up to its newest message; answers <code>{count}</code> 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.</p>\n<h2 id=\"post-api-v1-conversations-id-read\">POST /api/v1/conversations/{id}/read</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:conversations</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Marks the conversation read up to its newest message and answers with the <code>Conversation</code>. 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 (<code>chat.bsky.convo.updateRead</code>; for <code>read_all</code>, <code>updateAllRead</code>), and one read in a Bluesky app is read here (ATProto chat synchronization).</p>\n<h2 id=\"delete-api-v1-conversations-id\">DELETE /api/v1/conversations/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:conversations</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes the conversation from the list and answers <code>{}</code>. 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 (<code>leaveConvo</code>), never accepted (ATProto chat synchronization).</p>\n<p>A conversation here is <strong>derived</strong>, 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 <code>in_reply_to</code>. 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.</p>\n<p>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 <code>last_status</code>; a client keys on <code>id</code> and updates the row rather than growing a second one.</p>\n<p>What an account has <em>done</em> with a thread is stored, since it cannot be derived: <code>social_convo_state</code> 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. <code>unread</code> is false for a message the viewer sent themselves: writing a message is having read the conversation, as on Mastodon.</p>\n<p>A conversation the viewer is no part of, and one that does not exist, are the same <strong>404</strong>: membership is decided by the <code>dm</code> rows in <code>social_stream_dest</code> — 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.</p>\n","toc":[{"id":"get-api-v1-conversations","text":"GET /api/v1/conversations","level":2},{"id":"get-api-v1-conversations-unread-count","text":"GET /api/v1/conversations/unread_count","level":2},{"id":"post-api-v1-conversations-read-all","text":"POST /api/v1/conversations/read_all","level":2},{"id":"post-api-v1-conversations-id-read","text":"POST /api/v1/conversations/{id}/read","level":2},{"id":"delete-api-v1-conversations-id","text":"DELETE /api/v1/conversations/{id}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"conversations","manual":false,"prev":{"path":"/docs/api-stories","title":"Stories"},"next":{"path":"/docs/api-keyword-filters","title":"Keyword filters"},"parent":"api-mastodon-compatible-api"},{"slug":"api-keyword-filters","path":"/docs/api-keyword-filters","title":"Keyword filters","description":"Auth: public, no-csrf (viewer required, read:filters or read scope) · Parameters: —","group":"api","html":"<h2 id=\"get-api-v2-filters\">GET /api/v2/filters</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Every keyword filter of the viewer, newest first, as Mastodon v2 <code>Filter</code> 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. <code>statuses</code> carries the posts the filter covers by name, as <code>FilterStatus</code> entities.</p>\n<h2 id=\"post-api-v2-filters\">POST /api/v2/filters</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>title</code>, <code>context[]</code> (<code>home</code>, <code>notifications</code>, <code>public</code>, <code>thread</code>, <code>account</code>), <code>filter_action</code> (<code>warn</code> default, or <code>hide</code>), <code>expires_in</code> (seconds; absent means never), <code>keywords_attributes[][keyword]</code>, <code>[][whole_word]</code></p>\n<p>Creates a filter and answers with it. A missing <code>title</code>, a <code>context</code> naming none of the five, an unknown <code>filter_action</code> and an empty keyword are each a <strong>422</strong>: a filter with no context applies nowhere, and one with an empty keyword would match every status there is.</p>\n<h2 id=\"get-api-v2-filters-id\">GET /api/v2/filters/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One filter of the viewer. Somebody else&#39;s is a <strong>404</strong>, not a 403: whether another account has a filter is not this route&#39;s to tell.</p>\n<h2 id=\"put-api-v2-filters-id\">PUT /api/v2/filters/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>title</code>, <code>context[]</code>, <code>filter_action</code>, <code>expires_in</code>, <code>keywords_attributes[][id]</code>, <code>[][keyword]</code>, <code>[][whole_word]</code>, <code>[][_destroy]</code></p>\n<p>Changes a filter. What is not named is left as it is, so a client sending only <code>title</code> does not thereby clear the contexts, the expiry or the keywords. <code>keywords_attributes</code> edits in place: an entry with an <code>id</code> changes that keyword, one with <code>_destroy</code> removes it, one without an id adds it. A keyword id belonging to another filter — the viewer&#39;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.</p>\n<h2 id=\"delete-api-v2-filters-id\">DELETE /api/v2/filters/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Deletes the filter and its keywords, and answers <code>{}</code>.</p>\n<h2 id=\"get-api-v2-filters-id-keywords\">GET /api/v2/filters/{id}/keywords</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The <code>FilterKeyword</code> entities of that filter.</p>\n<h2 id=\"post-api-v2-filters-id-keywords\">POST /api/v2/filters/{id}/keywords</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>keyword</code>, <code>whole_word</code></p>\n<p>Adds one keyword and answers with it.</p>\n<h2 id=\"get-api-v2-filters-keywords-id\">GET /api/v2/filters/keywords/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One keyword of one of the viewer&#39;s filters; anybody else&#39;s is a 404.</p>\n<h2 id=\"put-api-v2-filters-keywords-id\">PUT /api/v2/filters/keywords/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>keyword</code>, <code>whole_word</code></p>\n<p>Changes it. What is not named is left as it is.</p>\n<h2 id=\"delete-api-v2-filters-keywords-id\">DELETE /api/v2/filters/keywords/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Removes the keyword; the filter stays. Answers <code>{}</code>.</p>\n<h2 id=\"get-api-v2-filters-id-statuses\">GET /api/v2/filters/{id}/statuses</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The posts that filter covers by name, as <code>FilterStatus</code> entities.</p>\n<h2 id=\"post-api-v2-filters-id-statuses\">POST /api/v2/filters/{id}/statuses</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>status_id</code></p>\n<p>Adds one post to the filter — a client&#39;s &quot;filter this post&quot; — and answers with the entry. The post is <strong>not</strong> looked up: a filter is the reader&#39;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 <code>status_id</code> is a <strong>422</strong>. Adding the same post twice makes a second entry, each with its own id, as it does on Mastodon.</p>\n<h2 id=\"get-api-v2-filters-statuses-id\">GET /api/v2/filters/statuses/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One entry of one of the viewer&#39;s filters; anybody else&#39;s is a 404.</p>\n<h2 id=\"delete-api-v2-filters-statuses-id\">DELETE /api/v2/filters/statuses/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Stops the filter covering that post; the filter stays. Answers <code>{}</code>.</p>\n<h2 id=\"get-api-v1-filters\">GET /api/v1/filters</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Mastodon&#39;s <strong>v1</strong> filters, served over the v2 ones. v1 has no notion of a filter with several keywords — a filter <em>is</em> a phrase — so a v1 filter here is a v2 <strong>keyword</strong>, carrying its parent&#39;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 <code>{id, phrase, context, whole_word, expires_at, irreversible}</code>, where <code>irreversible</code> is v1&#39;s name for <code>filter_action: hide</code>.</p>\n<h2 id=\"post-api-v1-filters\">POST /api/v1/filters</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>phrase</code>, <code>context[]</code>, <code>irreversible</code>, <code>whole_word</code>, <code>expires_in</code></p>\n<p>Creates a v2 filter whose title is the phrase, holding that one keyword, and answers with the v1 entity.</p>\n<h2 id=\"get-api-v1-filters-id\">GET /api/v1/filters/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One v1 filter — one keyword of one of the viewer&#39;s filters. Anybody else&#39;s is a <strong>404</strong>.</p>\n<h2 id=\"put-api-v1-filters-id\">PUT /api/v1/filters/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>phrase</code>, <code>context[]</code>, <code>irreversible</code>, <code>whole_word</code>, <code>expires_in</code></p>\n<p>Changes it; what is not named is left as it is.</p>\n<h2 id=\"delete-api-v1-filters-id\">DELETE /api/v1/filters/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>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 <code>{}</code>.</p>\n<h2 id=\"get-api-v1-social-ai-content\">GET /api/v1/social/ai_content</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>Aloha Social&#39;s own route.</strong> Whether the viewer hides posts made with AI: <code>{&quot;hide&quot;: false}</code> 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, <code>FilterService::apply()</code> — in <strong>every</strong> context at once, lists and notifications included, and whatever contexts the keyword filters name. What counts as made with AI is a <em>label the post carries</em>: one of the specific hashtags in <code>AiContentService::DEFAULT_TAGS</code> (<code>#aigenerated</code>, <code>#aigeneratedart</code>, <code>#midjourney</code>, <code>#stablediffusion</code>, …) plus whatever the administrator added with the <code>ai_tags</code> app value, compared case-insensitively and without the <code>#</code> (<code>#ai</code> by itself is always ignored); or an attachment whose picture states machine-generation provenance in its metadata (IPTC <code>DigitalSourceType</code> of <code>trainedAlgorithmicMedia</code> or <code>compositeWithTrainedAlgorithmicMedia</code>, 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 <code>Status</code> and <code>MediaAttachment</code> entity carries <code>ai_generated</code> (bool) whatever this switch says, so a client can draw a quiet label instead.</p>\n<h2 id=\"patch-api-v1-social-ai-content\">PATCH /api/v1/social/ai_content</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>hide</code> (required; <code>true</code>/<code>false</code>, <code>1</code>/<code>0</code>, <code>on</code>/<code>off</code>, <code>yes</code>/<code>no</code>)</p>\n<p>Turns the switch and answers with the same object. <code>hide</code> missing, empty or anything that is not one of those spellings is a <strong>422</strong> — a request that is unclear about a switch must not flip it. The change moves the timelines&#39; ETag like every other write here.</p>\n<h2 id=\"get-api-v1-social-counts\">GET /api/v1/social/counts</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>Aloha Social&#39;s own route.</strong> Whether the viewer hides how many likes, dislikes, boosts, replies and followers things have: <code>{&quot;hide&quot;: true}</code> unless they turned the numbers on — <strong>hidden is the default</strong>, for every account, stored the other way round (<code>show_counts</code>) so no migration was needed. While hidden, <strong>every client-API answer to this viewer</strong> carries <code>favourites_count</code>, <code>reblogs_count</code>, <code>replies_count</code> and <code>dislikes_count</code> (where it is not null) as <code>0</code> 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 (<code>HideCountsMiddleware</code>). 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: <code>video_card.views</code> is <code>null</code> and <code>video</code> has no <code>views</code>, which is how those two say nobody counted. An account&#39;s <code>followers_count</code>, <code>following_count</code> and <code>statuses_count</code> are <strong>always the real numbers</strong>, the viewer&#39;s own and anybody else&#39;s: a client told <code>0</code> shows &quot;0 followers&quot; as a fact, and the followers list and Statistics count the same people. The web app leaves other people&#39;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.</p>\n<h2 id=\"patch-api-v1-social-counts\">PATCH /api/v1/social/counts</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>hide</code> (required; <code>true</code>/<code>false</code>, <code>1</code>/<code>0</code>, <code>on</code>/<code>off</code>, <code>yes</code>/<code>no</code>)</p>\n<p>Turns the switch and answers with the state, <code>{&quot;hide&quot;: …}</code>. Anything that is not a boolean is a <strong>422</strong> and leaves the switch as it was.</p>\n<h2 id=\"get-api-v1-social-feed-preferences\">GET /api/v1/social/feed_preferences</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:filters</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>Aloha Social&#39;s own route.</strong> Whether reply posts are hidden as standalone cards in the viewer&#39;s home, public and hashtag feeds, plus <code>thread_sort</code>, read from the linked account&#39;s saved Bluesky <code>threadViewPref</code> (defaults to <code>oldest</code>). Social applies <code>oldest</code>, <code>newest</code>, <code>most-likes</code> and <code>random</code>; <code>hotness</code> currently falls back to <code>oldest</code>. The replies remain available inside their conversations.</p>\n<h2 id=\"patch-api-v1-social-feed-preferences\">PATCH /api/v1/social/feed_preferences</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:filters</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>hide_replies</code> (required; <code>true</code>/<code>false</code>, <code>1</code>/<code>0</code>, <code>on</code>/<code>off</code>, <code>yes</code>/<code>no</code>)</p>\n<p>Turns the reply-card switch and answers with the state, including the read-only <code>thread_sort</code>. Anything that is not a boolean is a <strong>422</strong> and leaves the preference as it was.</p>\n<h2 id=\"get-api-v1-social-files-comments\">GET /api/v1/social/files_comments</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>Aloha Social&#39;s own route.</strong> Whether replies to the viewer&#39;s posts made from Files are shown as comments on those files: <code>{&quot;enabled&quot;: true}</code> unless turned off — <strong>on is the default</strong>, stored as <code>files_comments</code> = <code>0</code> only once somebody turns it off. While on, a picture or video attached through <code>POST /api/v1/media/from-file</code> remembers its file; when the post it is attached to is published public or unlisted, the post is linked to the file. Every <strong>public or unlisted</strong> 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 (<code>actor_type</code> <code>social_fediverse</code>), with a content warning shown in place of the text and the reply&#39;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, <strong>only the post&#39;s author</strong> speaks for the post: a comment they write on the file goes out as their reply, with the post&#39;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&#39;s comment on the file stays on this server. Needs the Comments app.</p>\n<h2 id=\"patch-api-v1-social-files-comments\">PATCH /api/v1/social/files_comments</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>enabled</code> (required; <code>true</code>/<code>false</code>, <code>1</code>/<code>0</code>, <code>on</code>/<code>off</code>, <code>yes</code>/<code>no</code>)</p>\n<p>Turns the switch and answers with the state, <code>{&quot;enabled&quot;: …}</code>. Anything that is not a boolean is a <strong>422</strong> and leaves the switch as it was. Turning it off stops new links, new copies and new replies; comments already on a file stay.</p>\n<h2 id=\"patch-api-v1-social-keyboard-shortcuts\">PATCH /api/v1/social/keyboard_shortcuts</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>enabled</code> (required; <code>true</code>/<code>false</code>, <code>1</code>/<code>0</code>, <code>on</code>/<code>off</code>, <code>yes</code>/<code>no</code>)</p>\n<p><strong>Aloha Social&#39;s own route.</strong> Whether the web app&#39;s one-key shortcuts (<code>j</code>, <code>k</code>, <code>l</code>, <code>b</code> and the rest) are on for the viewer, stored as <code>keyboard_shortcuts</code> = <code>0</code> once somebody turns them off — <strong>on is the default</strong>. Answers with the state, <code>{&quot;enabled&quot;: …}</code>. The web app reads it from the page (<code>serverData.keyboardShortcuts</code>), so there is no GET. Anything that is not a boolean is a <strong>422</strong> and leaves the switch as it was.</p>\n<h2 id=\"get-api-v1-social-direct-messages\">GET /api/v1/social/direct_messages</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>Aloha Social&#39;s own route.</strong> Who may send the viewer direct messages: <code>{&quot;from&quot;: &quot;all&quot;}</code> (everybody), <code>&quot;following&quot;</code> (the people they follow) or <code>&quot;none&quot;</code> (nobody). It is the notification policy&#39;s <code>for_private_mentions</code> seen from the other side — <code>accept</code> is <code>all</code>, <code>filter</code> or <code>drop</code> is <code>following</code> — plus a stored <code>none</code>, 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 (<code>/api/v1/notifications/requests</code>). An account created here starts at <code>following</code>; one that never stored a policy is at <code>all</code>. On Bluesky the same answer is the <code>chat.bsky.actor.declaration</code> record, which its chat service goes by (ATProto chat synchronization).</p>\n<h2 id=\"patch-api-v1-social-direct-messages\">PATCH /api/v1/social/direct_messages</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>from</code> (required; <code>all</code>, <code>following</code> or <code>none</code>)</p>\n<p>Changes who may, and answers <code>{&quot;from&quot;: …}</code>. <code>all</code> sets <code>for_private_mentions</code> to <code>accept</code>; <code>following</code> and <code>none</code> set it to <code>filter</code> unless it is <code>drop</code> already. A change is written to the viewer&#39;s Bluesky repository as <code>chat.bsky.actor.declaration</code> when they have a Bluesky identity. Anything else is a <strong>422</strong> and changes nothing.</p>\n<p>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 <strong>the status it boosts</strong>, which is the only reading under which a filter cannot be escaped by boosting. <code>whole_word</code> puts a word boundary on each side of the keyword, but only on a side that starts or ends with a word character — <code>\\b</code> before a <code>#</code> can never hold, and anchoring it blindly would make <code>#spoiler</code> match nothing at all. Comparison is case-insensitive and Unicode-aware, and a keyword is never run as a pattern.</p>\n<p>A filter stops applying the moment its <code>expires_at</code> 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.</p>\n<p>Where each context is applied, since a filter that names a timeline nothing reads it in is a filter its owner believes is working: <code>home</code> on <code>/api/v1/timelines/home</code>, <code>public</code> on <code>/api/v1/timelines/public</code> and <code>/api/v1/timelines/tag/{hashtag}</code>, <code>account</code> on <code>/api/v1/accounts/{account}/statuses</code>, <code>thread</code> on <code>/api/v1/statuses/{nid}/context</code>, and <code>notifications</code> on <code>/api/v1/notifications</code>. <code>/api/v1/favourites/</code>, <code>/api/v1/bookmarks</code> and the direct timeline are read in no context — their statuses carry an empty <code>filtered</code>, because its absence is an answer of its own — and so is <code>/api/v1/statuses/{nid}</code>, which is one status a client asked for by id rather than a timeline. <strong><code>/api/v1/timelines/list/{id}</code> applies no filter at all</strong>, though <code>home</code> is documented by Mastodon as covering lists: the route is <code>ListController</code>&#39;s and never reaches <code>FilterService</code>, so a <code>home</code> filter narrows the home timeline and not the list timelines drawn from it.</p>\n<p>The web client edits these through the v2 routes only (<code>src/components/FiltersSettings.vue</code>); v1 is left for clients that have not moved. It also <em>draws</em> <code>filtered</code>: a status carrying one is folded behind the names of the filters that matched (<code>TimelinePost.vue</code>, <code>.post-filtered</code>) and its body is not rendered at all until the reader presses &quot;Show anyway&quot;, the same treatment a content warning gets. Two places a <code>warn</code> filter therefore does nothing visible, both because the key never arrives rather than because the client ignores it: <code>/api/v1/timelines/list/{id}</code>, which applies no filter, and <code>/api/v1/notifications</code>, where <code>Stream::exportAsNotification()</code> serialises the nested status without <code>filtered</code> — there a <code>hide</code> filter drops the notification and a <code>warn</code> filter is inert.</p>\n","toc":[{"id":"get-api-v2-filters","text":"GET /api/v2/filters","level":2},{"id":"post-api-v2-filters","text":"POST /api/v2/filters","level":2},{"id":"get-api-v2-filters-id","text":"GET /api/v2/filters/{id}","level":2},{"id":"put-api-v2-filters-id","text":"PUT /api/v2/filters/{id}","level":2},{"id":"delete-api-v2-filters-id","text":"DELETE /api/v2/filters/{id}","level":2},{"id":"get-api-v2-filters-id-keywords","text":"GET /api/v2/filters/{id}/keywords","level":2},{"id":"post-api-v2-filters-id-keywords","text":"POST /api/v2/filters/{id}/keywords","level":2},{"id":"get-api-v2-filters-keywords-id","text":"GET /api/v2/filters/keywords/{id}","level":2},{"id":"put-api-v2-filters-keywords-id","text":"PUT /api/v2/filters/keywords/{id}","level":2},{"id":"delete-api-v2-filters-keywords-id","text":"DELETE /api/v2/filters/keywords/{id}","level":2},{"id":"get-api-v2-filters-id-statuses","text":"GET /api/v2/filters/{id}/statuses","level":2},{"id":"post-api-v2-filters-id-statuses","text":"POST /api/v2/filters/{id}/statuses","level":2},{"id":"get-api-v2-filters-statuses-id","text":"GET /api/v2/filters/statuses/{id}","level":2},{"id":"delete-api-v2-filters-statuses-id","text":"DELETE /api/v2/filters/statuses/{id}","level":2},{"id":"get-api-v1-filters","text":"GET /api/v1/filters","level":2},{"id":"post-api-v1-filters","text":"POST /api/v1/filters","level":2},{"id":"get-api-v1-filters-id","text":"GET /api/v1/filters/{id}","level":2},{"id":"put-api-v1-filters-id","text":"PUT /api/v1/filters/{id}","level":2},{"id":"delete-api-v1-filters-id","text":"DELETE /api/v1/filters/{id}","level":2},{"id":"get-api-v1-social-ai-content","text":"GET /api/v1/social/ai_content","level":2},{"id":"patch-api-v1-social-ai-content","text":"PATCH /api/v1/social/ai_content","level":2},{"id":"get-api-v1-social-counts","text":"GET /api/v1/social/counts","level":2},{"id":"patch-api-v1-social-counts","text":"PATCH /api/v1/social/counts","level":2},{"id":"get-api-v1-social-feed-preferences","text":"GET /api/v1/social/feed_preferences","level":2},{"id":"patch-api-v1-social-feed-preferences","text":"PATCH /api/v1/social/feed_preferences","level":2},{"id":"get-api-v1-social-files-comments","text":"GET /api/v1/social/files_comments","level":2},{"id":"patch-api-v1-social-files-comments","text":"PATCH /api/v1/social/files_comments","level":2},{"id":"patch-api-v1-social-keyboard-shortcuts","text":"PATCH /api/v1/social/keyboard_shortcuts","level":2},{"id":"get-api-v1-social-direct-messages","text":"GET /api/v1/social/direct_messages","level":2},{"id":"patch-api-v1-social-direct-messages","text":"PATCH /api/v1/social/direct_messages","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"keyword-filters","manual":false,"prev":{"path":"/docs/api-conversations","title":"Conversations"},"next":{"path":"/docs/api-discovery-trends-and-relationships","title":"Discovery, trends and relationships"},"parent":"api-mastodon-compatible-api"},{"slug":"api-discovery-trends-and-relationships","path":"/docs/api-discovery-trends-and-relationships","title":"Discovery, trends and relationships","description":"Auth: public, no-csrf · Parameters: limit (20, capped at 40), offset (0), period (1h, 12h, 1d — the default —, 3d, 10d)","group":"api","html":"<h2 id=\"get-api-v1-trends-statuses\">GET /api/v1/trends/statuses</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20, capped at 40), <code>offset</code> (0), <code>period</code> (<code>1h</code>, <code>12h</code>, <code>1d</code> — the default —, <code>3d</code>, <code>10d</code>)</p>\n<p>The public statuses interacted with most in that window, most interactions first, with their link previews attached. Counted live from <code>social_action</code> — 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 <code>Note</code>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. <code>period</code> is this app&#39;s own parameter, shared with <code>/api/v1/trends/tags</code> so a discover page sees one stretch of time; Mastodon has none and gets the default.</p>\n<h2 id=\"get-api-v1-timelines-link\">GET /api/v1/timelines/link</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>url</code> (required), <code>limit</code> (20, capped at 40), <code>max_id</code> (0), <code>min_id</code> (0)</p>\n<p>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 <code>/api/v1/trends/links</code>, so the data was here and the timeline that reads it was not. The url is matched <strong>exactly</strong> 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 <code>url</code> is an empty timeline, not an error — the link a client holds may be one nobody here has posted since.</p>\n<h2 id=\"get-api-v2-discover-posts\">GET /api/v2/discover/posts</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code>, <code>offset</code> (0), <code>period</code></p>\n<p>Pixelfed&#39;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 <em>same</em> ranking as <code>/api/v1/trends/statuses</code>, not a second one, so a post cannot trend there and not here. Public statuses only.</p>\n<h2 id=\"get-api-v1-trends-links\">GET /api/v1/trends/links</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20, capped at 40), <code>offset</code> (0), <code>period</code> (as above)</p>\n<p>The links most often attached to a public status in that window, as Mastodon <code>Trends::Link</code> 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. <code>history</code> carries a single bucket and <code>accounts</code> in it is always <code>0</code>: this instance counts uses, not distinct accounts.</p>\n<h2 id=\"get-api-v1-directory\">GET /api/v1/directory</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>offset</code> (0), <code>limit</code> (40, capped at 80), <code>order</code> (<code>active</code> default, or <code>new</code>), <code>local</code> (accepted, no effect)</p>\n<p>The local profile directory: the accounts that set <code>discoverable</code>. <strong>Opt-in, and that is the whole access rule</strong> — the flag has been stored and federated since <code>Version1000Date20260911000002</code> 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. <code>active</code> orders by when the account last posted in public, accounts that never have at the end; <code>new</code> 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 <code>local</code> makes no difference.</p>\n<h2 id=\"get-api-v2-suggestions\">GET /api/v2/suggestions</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (40, capped at 80)</p>\n<p>Accounts to follow, as Mastodon <code>Suggestion</code> 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 (<code>friends_of_friends</code>), 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 <code>source</code> field is sent beside <code>sources</code>, because clients in the wild read one or the other. Never the viewer, an account they already follow <strong>or have a pending request to</strong>, 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.</p>\n<h2 id=\"get-api-v1-suggestions\">GET /api/v1/suggestions</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (40, capped at 80)</p>\n<p>The same list in Mastodon&#39;s v1 shape: bare <code>Account</code> 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 &quot;who to follow&quot; panel.</p>\n<h2 id=\"delete-api-v1-suggestions-id\">DELETE /api/v1/suggestions/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>&quot;Stop suggesting this account&quot;, 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 <code>{}</code> 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.</p>\n<h2 id=\"get-api-v1-featured-tags\">GET /api/v1/featured_tags</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s own featured tags — the hashtags they pin to their profile. Unpaged, as Mastodon&#39;s is. <code>statuses_count</code> and <code>last_status_at</code> are counted at read time over the account&#39;s public and unlisted posts, not stored, so they cannot disagree with the tag timeline a visitor gets by clicking through; <code>last_status_at</code> is a date and is <code>null</code>, not <code>&quot;&quot;</code>, for a tag nothing has been posted with.</p>\n<h2 id=\"post-api-v1-featured-tags\">POST /api/v1/featured_tags</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>name</code> (required)</p>\n<p>Pins a hashtag and answers with it. The name is stored as posts are tagged — no leading <code>#</code>, lowercased, at most 127 characters — and a name that is not a hashtag at all is a <strong>422</strong> rather than a row nobody can post with. Featuring one that is already featured answers the existing entity. One past <code>configuration.accounts.max_featured_tags</code> is a <strong>422</strong>.</p>\n<h2 id=\"delete-api-v1-featured-tags-id\">DELETE /api/v1/featured_tags/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Unpins a tag and answers <code>{}</code>. A tag that is not there and a tag that is somebody else&#39;s are the same <strong>404</strong>.</p>\n<h2 id=\"get-api-v1-featured-tags-suggestions\">GET /api/v1/featured_tags/suggestions</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>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.</p>\n<h2 id=\"get-api-v1-accounts-account-featured-tags\">GET /api/v1/accounts/{account}/featured_tags</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Somebody&#39;s featured tags. Public, as the profile they are drawn on is, and the counts come from public and unlisted posts only.</p>\n<h2 id=\"get-api-v1-accounts-account-highlights\">GET /api/v1/accounts/{account}/highlights</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The shape of somebody&#39;s posting history, for the top of their profile: <code>since</code> (when the account was created, as a unix time), <code>weeks</code> (how many public posts fell in each of the last twelve weeks, oldest first), <code>week_starts</code> (the unix time the first bucket begins at) and <code>hashtags</code> (the three tags they have used most over the last year, <code>{name, count}</code>, 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. <strong>A remote account answers <code>available: false</code> with empty arrays</strong>, and a client should then draw nothing: this instance holds a remote account&#39;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.</p>\n<h2 id=\"get-api-v1-statuses-nid-history\">GET /api/v1/statuses/{nid}/history</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer optional, <code>read:statuses</code> or <code>read</code> scope when a token is sent) · <strong>Parameters: </strong>—</p>\n<p>Every version the status has been through, oldest first, as Mastodon <code>StatusEdit</code> 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 <code>GET /api/v1/statuses/{nid}</code> itself: the status is resolved through the visibility filter first, so one the caller may not read is a <strong>404</strong> and no revision is looked at. A token that <em>is</em> presented still has its scope checked — too little is a <strong>403</strong>, not a silent downgrade to an anonymous read. <code>media_attachments</code> are the attachments as they were in that version — the same <code>MediaAttachment</code> entity a status carries, with <code>id</code>, <code>type</code>, <code>url</code>, <code>preview_url</code>, <code>description</code> and <code>meta.focus</code> — so an edit that only changed a description or a focal point through <code>media_attributes</code> shows as one; a revision recorded before the attachments were kept with it has <code>[]</code>. <code>poll</code> and <code>emojis</code> are always <code>null</code>/<code>[]</code>: 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.</p>\n<h2 id=\"post-api-v1-accounts-id-note\">POST /api/v1/accounts/{id}/note</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> scope) · <strong>Parameters: </strong><code>comment</code> (empty clears)</p>\n<p>Keeps the viewer&#39;s private note about the account and returns the updated relationship, whose <code>note</code> 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.</p>\n<h2 id=\"post-api-v1-accounts-id-pin\">POST /api/v1/accounts/{id}/pin</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Features the account on the viewer&#39;s profile; <code>endorsed</code> becomes true. An account the viewer does not follow is a <strong>422</strong>, 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.</p>\n<h2 id=\"post-api-v1-accounts-id-unpin\">POST /api/v1/accounts/{id}/unpin</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Stops featuring it. Unfeaturing one that was not featured is not an error.</p>\n<h2 id=\"get-api-v1-endorsements\">GET /api/v1/endorsements</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> scope) · <strong>Parameters: </strong><code>limit</code> (40, capped at 80)</p>\n<p>The accounts the viewer features, newest first. The viewer&#39;s own and nobody else&#39;s.</p>\n<h2 id=\"get-api-v1-domain-blocks\">GET /api/v1/domain_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:blocks</code> scope) · <strong>Parameters: </strong><code>limit</code> (100, capped at 200)</p>\n<p>The instances the viewer has blocked <strong>for themselves</strong>, newest first, as a flat list of domain strings — which is what Mastodon answers here, not entities. Not the admin&#39;s instance-wide access list (<code>occ social:fediverse</code>), which applies to everybody at once.</p>\n<h2 id=\"post-api-v1-domain-blocks\">POST /api/v1/domain_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:blocks</code> scope) · <strong>Parameters: </strong><code>domain</code> (required)</p>\n<p>Blocks every account on that instance for the viewer. What is sent is normalised to the host it names — <code>Example.COM</code>, <code>@user@example.com</code> and <code>https://example.com/@user</code> are one instance. Anything outside <code>a-z0-9.-</code> is a <strong>422</strong> rather than a stored pattern, because the comparison is a <code>LIKE</code> and a stored <code>%</code> would be a block that quietly matched other instances; this instance&#39;s own domain is a 422 too. The instance&#39;s posts stop reaching every timeline, thread and notification list, matched on the host of the author&#39;s actor id — including posts boosted into view by somebody else. Nothing is federated and the instance is never told.</p>\n<h2 id=\"delete-api-v1-domain-blocks\">DELETE /api/v1/domain_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:blocks</code> scope) · <strong>Parameters: </strong><code>domain</code> (required)</p>\n<p>Lifts the block and answers <code>{}</code>. 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.</p>\n","toc":[{"id":"get-api-v1-trends-statuses","text":"GET /api/v1/trends/statuses","level":2},{"id":"get-api-v1-timelines-link","text":"GET /api/v1/timelines/link","level":2},{"id":"get-api-v2-discover-posts","text":"GET /api/v2/discover/posts","level":2},{"id":"get-api-v1-trends-links","text":"GET /api/v1/trends/links","level":2},{"id":"get-api-v1-directory","text":"GET /api/v1/directory","level":2},{"id":"get-api-v2-suggestions","text":"GET /api/v2/suggestions","level":2},{"id":"get-api-v1-suggestions","text":"GET /api/v1/suggestions","level":2},{"id":"delete-api-v1-suggestions-id","text":"DELETE /api/v1/suggestions/{id}","level":2},{"id":"get-api-v1-featured-tags","text":"GET /api/v1/featured_tags","level":2},{"id":"post-api-v1-featured-tags","text":"POST /api/v1/featured_tags","level":2},{"id":"delete-api-v1-featured-tags-id","text":"DELETE /api/v1/featured_tags/{id}","level":2},{"id":"get-api-v1-featured-tags-suggestions","text":"GET /api/v1/featured_tags/suggestions","level":2},{"id":"get-api-v1-accounts-account-featured-tags","text":"GET /api/v1/accounts/{account}/featured_tags","level":2},{"id":"get-api-v1-accounts-account-highlights","text":"GET /api/v1/accounts/{account}/highlights","level":2},{"id":"get-api-v1-statuses-nid-history","text":"GET /api/v1/statuses/{nid}/history","level":2},{"id":"post-api-v1-accounts-id-note","text":"POST /api/v1/accounts/{id}/note","level":2},{"id":"post-api-v1-accounts-id-pin","text":"POST /api/v1/accounts/{id}/pin","level":2},{"id":"post-api-v1-accounts-id-unpin","text":"POST /api/v1/accounts/{id}/unpin","level":2},{"id":"get-api-v1-endorsements","text":"GET /api/v1/endorsements","level":2},{"id":"get-api-v1-domain-blocks","text":"GET /api/v1/domain_blocks","level":2},{"id":"post-api-v1-domain-blocks","text":"POST /api/v1/domain_blocks","level":2},{"id":"delete-api-v1-domain-blocks","text":"DELETE /api/v1/domain_blocks","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"discovery-trends-and-relationships","manual":false,"prev":{"path":"/docs/api-keyword-filters","title":"Keyword filters"},"next":{"path":"/docs/api-announcements","title":"Announcements"},"parent":"api-mastodon-compatible-api"},{"slug":"api-announcements","path":"/docs/api-announcements","title":"Announcements","description":"Auth: public, no-csrf (viewer required, any token — no scope) · Parameters: —","group":"api","html":"<h2 id=\"get-api-v1-announcements\">GET /api/v1/announcements</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, any token — no scope) · <strong>Parameters: </strong>—</p>\n<p>The announcements that apply right now, oldest effective first, as Mastodon <code>Announcement</code> entities, each carrying <code>read</code> for the viewer. Unpaged, as Mastodon&#39;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 <strong>only between them</strong>, 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. <code>mentions</code>, <code>statuses</code>, <code>tags</code> and <code>emojis</code> are always <code>[]</code> — 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. <code>reactions</code> carries what accounts have put on it: most-reacted first, alphabetical within a tie so a redraw is stable, each with <code>name</code>, <code>count</code>, <code>me</code> for the viewer, and — only when the name is a custom emoji this instance publishes — <code>url</code> and <code>static_url</code>, which is how a client tells a picture to fetch from a character to render. <code>content</code> is HTML built from what the admin typed, escaped, one paragraph per blank line.</p>\n<h2 id=\"put-api-v1-announcements-id-reactions-name\">PUT /api/v1/announcements/{id}/reactions/{name}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:favourites</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Puts one emoji on the announcement for the viewer and answers <code>{}</code>. <code>{name}</code> is a single emoji or the shortcode of one <code>occ social:emoji</code> publishes — the same two things Mastodon accepts, and anything else is a <strong>422</strong>: 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 <strong>8</strong> 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 <strong>404</strong>.</p>\n<h2 id=\"delete-api-v1-announcements-id-reactions-name\">DELETE /api/v1/announcements/{id}/reactions/{name}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:favourites</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Takes it back and answers <code>{}</code>. 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&#39;s reaction is neither changed nor removable. An id that names nothing is a <strong>404</strong>.</p>\n<h2 id=\"post-api-v1-announcements-id-dismiss\">POST /api/v1/announcements/{id}/dismiss</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Marks it read for the viewer and answers <code>{}</code>. Per account: another account&#39;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 <strong>404</strong>.</p>\n","toc":[{"id":"get-api-v1-announcements","text":"GET /api/v1/announcements","level":2},{"id":"put-api-v1-announcements-id-reactions-name","text":"PUT /api/v1/announcements/{id}/reactions/{name}","level":2},{"id":"delete-api-v1-announcements-id-reactions-name","text":"DELETE /api/v1/announcements/{id}/reactions/{name}","level":2},{"id":"post-api-v1-announcements-id-dismiss","text":"POST /api/v1/announcements/{id}/dismiss","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"announcements","manual":false,"prev":{"path":"/docs/api-discovery-trends-and-relationships","title":"Discovery, trends and relationships"},"next":{"path":"/docs/api-timelines-and-notifications","title":"Timelines and notifications"},"parent":"api-mastodon-compatible-api"},{"slug":"api-timelines-and-notifications","path":"/docs/api-timelines-and-notifications","title":"Timelines and notifications","description":"Auth: public, no-csrf · Parameters: 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)","group":"api","html":"<h2 id=\"get-api-v1-timelines-timeline\">GET /api/v1/timelines/{timeline}/</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>local</code> (false), <code>limit</code> (20), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0), <code>only_media</code> (false), <code>only_video</code> (false), <code>only_short</code> (false), <code>only_news</code> (false)</p>\n<p>One of <code>home</code>, <code>account</code>, <code>public</code>, <code>direct</code>, <code>favourites</code> (case-insensitive); anything else is a 422 (<code>UnknownProbeException</code>). <code>only_media</code> keeps just the posts that carry an attachment, which is what the <strong>Photos</strong> view asks of <code>home</code>, or of <code>public</code> with and without <code>local</code> 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; &quot;no media&quot; has three spellings in the stored column (NULL, <code>&#39;&#39;</code> and <code>&#39;[]&#39;</code>) and all three are excluded. <code>only_video</code> is <strong>this app&#39;s own, not Mastodon&#39;s</strong>, and is what the <strong>Videos</strong> 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 <code>type</code> is <code>video</code>, <em>or</em> that arrived as a PeerTube <code>Video</code> — 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. <code>only_short</code> is <strong>this app&#39;s own</strong> too, and narrower still: a post whose <strong>only attachment is a <code>video</code> of at most 180 seconds that is upright or square</strong> (width ÷ height at most 1), both read from the attachment&#39;s <code>meta</code> — <code>duration</code>, and <code>original.width</code>/<code>original.height</code> (or the top-level ones, or <code>aspect</code>). It wins over <code>only_media</code>, <code>only_video</code> and <code>media_type</code>. 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 <code>Stream::shortKindOf()</code>, decided on the write and kept in <code>social_stream.short_kind</code> (indexed with <code>nid</code>), 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 <code>/api/v2/config</code> (<code>limits.short_max_duration</code>, <code>limits.short_max_aspect_ratio</code>) beside <code>features.shorts</code>, which says the parameter is there. <code>only_news</code> is <strong>this app&#39;s own</strong> as well, and is what the <strong>News</strong> view asks those same three feeds. It is not a narrowing of <code>only_media</code> and does not imply it: a post is news when it arrived as an <code>Article</code> or a <code>Page</code> — 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 <code>only_media</code> and <code>only_news</code> gets the posts that are both. The answer is decided on the write and kept in <code>social_stream.news_kind</code>, so a post stored before that column existed is not news until the backfill reaches it. <code>public</code> is readable without a token, as Mastodon&#39;s is — a client asks for it before it has one — though a token that <em>was</em> presented still has to be a good one. Every other timeline needs a viewer. A page with remote counts still due carries <code>X-Social-Filling: 1</code>; the web app fetches a fresh page again until the background count refresh stamps it. Sends a <code>Link</code> header. Rate-limited per user and per anonymous caller.</p>\n<h2 id=\"get-api-v1-timelines-tag-hashtag\">GET /api/v1/timelines/tag/{hashtag}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0), <code>local</code> (false), <code>only_media</code> (false), <code>only_video</code> (false), <code>only_short</code> (false), <code>only_news</code> (false)</p>\n<p>Posts carrying <code>{hashtag}</code> that are addressed <strong>to</strong> the public collection. An unlisted post carries the tag and anybody may read it, but it names the public collection only in <code>cc</code> 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 <code>local</code> also has the hashtag&#39;s posts beyond this server read in the background (<code>PostDiscoveryService</code>, 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&#39;s posts with the hashtag. They are stored, so the timeline has them the next time; the answer says <strong><code>X-Social-Filling: 1</code></strong> while that read is new or while counts on the page are still due.</p>\n<h2 id=\"get-api-v1-timelines-list-id\">GET /api/v1/timelines/list/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:lists</code> scope) · <strong>Parameters: </strong><code>limit</code> (20, capped at 50), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0), <code>only_media</code> (false), <code>only_video</code> (false), <code>only_short</code> (false), <code>only_news</code> (false)</p>\n<p>The list&#39;s timeline: the home timeline narrowed to the list&#39;s members. A route of its own rather than a name in <code>/api/v1/timelines/{timeline}/</code>, because a list timeline is a name <em>and an id</em>. 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. <code>only_media</code>, <code>only_video</code>, <code>only_short</code> and <code>only_news</code> narrow it in the query that picks the page, as on the other timelines. A list that is not theirs is a <strong>404</strong>. A page with remote counts still due carries <code>X-Social-Filling: 1</code>; the web app fetches a fresh page again until the background count refresh stamps it. Sends a <code>Link</code> header.</p>\n<h2 id=\"get-api-v1-favourites\">GET /api/v1/favourites/</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0)</p>\n<p>The viewer&#39;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&#39;s own id (<code>social_stream_act.liked_nid</code>): the cursors in <code>Link</code> name the favourite, not the post, and a client follows them as it would Mastodon&#39;s.</p>\n<h2 id=\"get-api-v1-bookmarks\">GET /api/v1/bookmarks</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0)</p>\n<p>The viewer&#39;s bookmarked posts, among those the viewer may read now, ordered and paged on the bookmark (<code>bookmarked_nid</code>) as <code>/api/v1/favourites/</code> is on the favourite.</p>\n<h2 id=\"get-api-v1-notifications\">GET /api/v1/notifications</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>limit</code> (20), <code>max_id</code> (0), <code>min_id</code> (0), <code>since_id</code> (0), <code>types</code> (array), <code>exclude_types</code> (array), <code>account_id</code> (the notifications from one account, by its id, handle or actor id)</p>\n<p>Notification stream for the viewer. <code>types</code>/<code>exclude_types</code> keep or drop notification kinds. Nine are served: <code>mention</code>, <code>reblog</code>, <code>favourite</code>, <code>update</code>, <code>follow</code>, <code>follow_request</code>, and — added with the conversation-mute work — <code>poll</code> (a poll you voted in, or ran, has closed; its <code>status</code> carries the closed poll with its final counts), <code>status</code> (an account whose bell you turned on has posted), <code>moderation_warning</code> (a moderator acted on your account) and <code>severed_relationships</code> (a domain block cut your follows). Eight more are this app&#39;s own (<code>Stream::FIRST_PARTY_NOTIFICATION_TYPES</code>): <code>story:react</code> and <code>story:comment</code> (a reaction or a reply to your story), <code>tagged</code> (you were tagged in a photo), and five for what only Bluesky tells: <code>bluesky:repost_liked</code> and <code>bluesky:repost_reposted</code> (somebody liked or reposted your repost; <code>status</code> is the post you reposted), <code>bluesky:verified</code> and <code>bluesky:unverified</code> (a trusted verifier verified your account on Bluesky, or no longer does) and <code>bluesky:starterpack_joined</code> (somebody joined Bluesky with your starter pack). <strong>These eight are served to the web app (the Nextcloud session) and to a client that names them in <code>types[]</code>; a request with a bearer token that does not name them has them excluded in the query</strong>, so its page stays full — Mastodon&#39;s set of types is closed, and a client with a closed enum shows an unknown type as an &quot;unknown notification&quot; row or fails to decode the page. Notifications the account&#39;s <strong>notification policy</strong> holds back are not on this list, and neither are those about a post in a conversation the viewer muted; see <code>/api/v1/notifications/policy</code> and <code>/api/v1/notifications/requests</code>. A <code>types</code> 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 <code>type</code>. <code>admin.sign_up</code>, <code>admin.report</code> and <code>annual_report</code> 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&#39;s own notifications instead. Sends a <code>Link</code> header.</p>\n<h2 id=\"get-api-v1-notifications-unread-count\">GET /api/v1/notifications/unread_count</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p><code>{&quot;count&quot;: n}</code> — notifications newer than the viewer&#39;s <code>notifications</code> marker that the list shows: neither held by the notification policy (those are counted as requests, <code>summary.pending_requests_count</code> on the policy, so a client adding the two counts nobody twice) nor from a muted conversation. Notifications <strong>released by accepting a request</strong> count as unread even where the marker had already moved past them while they were hidden, until the viewer next sets the <code>notifications</code> marker (<code>POST /api/v1/markers</code>, moving or not). Counted up to 99; past that the answer is 100, which is all a badge shows. Carries an <code>ETag</code> and answers <code>304</code> 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.</p>\n<h2 id=\"get-api-v1-notifications-id\">GET /api/v1/notifications/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One notification, as <code>/api/v1/notifications</code> serves it. Read through the notification timeline itself, so one that is not the viewer&#39;s is a <strong>404</strong> 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.</p>\n<h2 id=\"post-api-v1-notifications-id-dismiss\">POST /api/v1/notifications/{id}/dismiss</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Dismisses one notification and answers <code>{}</code>. 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 <strong>200</strong> — the client is asking for a state that holds. The Nextcloud notification raised from the same row is withdrawn with it.</p>\n<h2 id=\"get-api-v2-notifications\">GET /api/v2/notifications</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (40), <code>max_id</code>, <code>min_id</code>, <code>since_id</code>, <code>types[]</code>, <code>exclude_types[]</code>, <code>grouped_types[]</code>, <code>account_id</code></p>\n<p>Mastodon 4.3&#39;s <strong>grouped</strong> notifications: the same list (and, as on v1, this app&#39;s own eight types only for the web app or a client naming them in <code>types[]</code>), as <code>GroupedNotificationsResults</code> — <code>notification_groups</code> plus the <code>accounts</code> and <code>statuses</code> 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 <code>ungrouped-{id}</code> as Mastodon keys them. The <code>group_key</code> is built from what the group <em>is</em> (<code>favourite-{status id}</code>, <code>follow-all</code>) and never from the ids in it, so it still names the same group after more arrive. <code>page_min_id</code>/<code>page_max_id</code> bound the group <strong>on this page</strong>, which is what makes paging work.</p>\n<h2 id=\"get-api-v2-notifications-unread-count\">GET /api/v2/notifications/unread_count</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (100, the cap), <code>types[]</code>, <code>exclude_types[]</code>, <code>account_id</code>, <code>grouped_types[]</code></p>\n<p>How many <em>groups</em> 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&#39;s <code>notifications</code> marker, as Mastodon counts it, plus what accepting a request released behind it, as the v1 count has it; the groups are those <code>/api/v2/notifications</code> would draw for the same parameters. Counted up to <code>limit</code> (at most 399). Carries the v1 count&#39;s <code>ETag</code> and answers <code>304</code> on the same terms.</p>\n<h2 id=\"get-api-v2-notifications-group-key\">GET /api/v2/notifications/{group_key}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One group, in the same shape the list serves. A key nothing matches is a <strong>404</strong>.</p>\n<h2 id=\"get-api-v2-notifications-group-key-accounts\">GET /api/v2/notifications/{group_key}/accounts</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Everybody in the group, not only the eight the group samples — this is what &quot;and 34 others&quot; opens.</p>\n<h2 id=\"post-api-v2-notifications-group-key-dismiss\">POST /api/v2/notifications/{group_key}/dismiss</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>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.</p>\n<h2 id=\"get-api-v1-notifications-policy\">GET /api/v1/notifications/policy</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>What this account does with notifications from people it has no relationship with: <code>for_not_following</code>, <code>for_not_followers</code>, <code>for_new_accounts</code>, <code>for_private_mentions</code>, <code>for_limited_accounts</code>, each <code>accept</code>, <code>filter</code> or <code>drop</code>, plus a <code>summary</code> with the two counts a client draws the badge from — exactly the senders and notifications <code>/api/v1/notifications/requests</code> lists, counted from who sent what rather than from the notifications read whole. The <code>GET</code> carries an <code>ETag</code> and answers <code>304</code> 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 <strong>created</strong> here is given a stored policy at creation — the administrator&#39;s choice for new accounts (<code>/admin/notification-policy</code>), by default the <em>calm</em> one: <code>for_not_following</code> <code>filter</code>, <code>for_not_followers</code> <code>accept</code>, <code>for_new_accounts</code> <code>filter</code>, <code>for_private_mentions</code> <code>filter</code>, <code>for_limited_accounts</code> <code>filter</code>. An account with no stored policy — every account from before new ones started calm — answers <code>accept</code> for all five, as it always did, until its owner chooses. <strong>Nextcloud extension:</strong> <code>notice</code> (bool) is <code>true</code> exactly for such an account that has neither stored a policy nor dismissed the pointer to it (<code>POST /api/v1/social/notifications/policy/notice/dismiss</code>); 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 <strong>raises nothing</strong>: 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 (<code>NotificationService::emit()</code>) as where the list is read. A sender the viewer accepted is never held.</p>\n<h2 id=\"patch-api-v1-notifications-policy\">PATCH /api/v1/notifications/policy</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>any of the five keys</p>\n<p>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. <strong><code>drop</code> behaves as <code>filter</code></strong>: 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. <strong><code>drop</code> is API-only:</strong> it stays available for Mastodon apps, but the web app offers <em>Allow</em> (<code>accept</code>) and <em>Hold for review</em> (<code>filter</code>) only, shows a stored <code>drop</code> as hold-for-review with a note, and never writes it. Saving puts away the one-time <code>notice</code>.</p>\n<h2 id=\"get-api-v2-notifications-policy\">GET /api/v2/notifications/policy</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>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 <code>summary</code>, from one method behind both spellings. Declared ahead of the group routes, so the word policy is never taken for a group key.</p>\n<h2 id=\"patch-api-v2-notifications-policy\">PATCH /api/v2/notifications/policy</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>any of the five keys</p>\n<p>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 <code>drop</code> behaves as <code>filter</code>, as the v1 row explains. A change of <code>for_not_following</code> is also a Bluesky app&#39;s &quot;who may notify you&quot; (<code>include</code> on its notification settings): it is told to the AppView, as the person, and the app&#39;s own change of it becomes this one.</p>\n<h2 id=\"get-api-v1-social-notification-delivery\">GET /api/v1/social/notification_delivery</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>Nextcloud extension, not a Mastodon route.</strong> <em>When</em> this account&#39;s Nextcloud notifications are raised, as opposed to the policy&#39;s <em>whether</em>: <code>{&quot;mode&quot;: &quot;instant&quot;|&quot;digest&quot;, &quot;times&quot;: [&quot;08:00&quot;, &quot;18:00&quot;], &quot;passthrough&quot;: {&quot;direct&quot;: true, &quot;mentions_from_followed&quot;: true}, &quot;quiet&quot;: {&quot;from&quot;: &quot;&quot;, &quot;to&quot;: &quot;&quot;}}</code>. <code>instant</code> is what every account had before this existed. In <code>digest</code> the bell is held and rung once per time in <code>times</code> (one to four local times, in the zone Nextcloud&#39;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&#39;s message ends with &quot;{count} people are waiting to reach you&quot;; 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, <code>/api/v1/notifications</code> and the markers are unaffected — the stored rows are the hold. Defaults as shown.</p>\n<h2 id=\"patch-api-v1-social-notification-delivery\">PATCH /api/v1/social/notification_delivery</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>any subset of <code>mode</code>, <code>times</code> (array), <code>passthrough</code> (<code>direct</code>, <code>mentions_from_followed</code>), <code>quiet</code> (<code>from</code>, <code>to</code>); JSON or form</p>\n<p>Changes the setting and answers the whole of it. What is not named is left as it is. Validation refuses the whole change with <strong>422</strong> <code>{&quot;error&quot;: &quot;…&quot;}</code>: <code>mode</code> is <code>instant</code> or <code>digest</code>; <code>times</code> lists one to four distinct <code>HH:MM</code> (24-hour, zero-padded) and is sorted on save; <code>quiet.from</code> and <code>quiet.to</code> are both <code>HH:MM</code> and different, or both empty; the pass-throughs are booleans (<code>true</code>/<code>false</code>, <code>1</code>/<code>0</code>, or those as strings). Switching to <code>digest</code> 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.</p>\n<h2 id=\"get-api-v1-notifications-requests\">GET /api/v1/notifications/requests</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (40, capped at 80)</p>\n<p>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 <em>sender</em> 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 <code>NotificationPolicyService::LOOKBACK</code> of them. The <code>id</code> is the sender&#39;s account id, since that is the only stable name a derived row has.</p>\n<h2 id=\"get-api-v1-notifications-requests-id\">GET /api/v1/notifications/requests/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One of those rows; an account that is not being held is a <strong>404</strong>.</p>\n<h2 id=\"post-api-v1-notifications-requests-id-accept\">POST /api/v1/notifications/requests/{id}/accept</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>&quot;Show me this account&#39;s notifications after all.&quot; The decision is about the account, so it settles what they have sent and what they send later: the sender is <strong>always allowed</strong> from then on, whatever the policy says, until <code>DELETE /api/v1/social/notifications/allowed/{account_id}</code>. What they sent while held joins the list <strong>without raising anything now</strong> — it is old news — and counts as unread in <code>/api/v1/notifications/unread_count</code>, 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).</p>\n<h2 id=\"post-api-v1-notifications-requests-id-dismiss\">POST /api/v1/notifications/requests/{id}/dismiss</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>&quot;Stop asking me about this account.&quot; 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 (<code>leaveConvo</code>), never accepted (ATProto chat synchronization).</p>\n<h2 id=\"get-api-v1-social-notifications-allowed\">GET /api/v1/social/notifications/allowed</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (40, capped at 80)</p>\n<p><strong>Nextcloud extension, not a Mastodon route.</strong> The senders this account accepted from its requests — <em>always allowed</em> — as Account entities, the most recently accepted first. No <code>Link</code> header.</p>\n<h2 id=\"delete-api-v1-social-notifications-allowed-account-id\">DELETE /api/v1/social/notifications/allowed/{account_id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>Nextcloud extension.</strong> Stops always allowing that sender (<code>account_id</code> is the account&#39;s id): their next notification is judged by the policy again, as if nobody had decided about them. Answers <code>{}</code>; an id naming nobody, or a sender that was not allowed, is the state asked for already and answers <code>{}</code> too.</p>\n<h2 id=\"post-api-v1-social-notifications-policy-notice-dismiss\">POST /api/v1/social/notifications/policy/notice/dismiss</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>Nextcloud extension.</strong> Puts away the one-time pointer to the policy for good (the user value <code>notification_policy_notice_dismissed</code>) and answers the policy, whose <code>notice</code> is then <code>false</code>. Changes no decision.</p>\n<h2 id=\"post-api-v1-notifications-requests-accept\">POST /api/v1/notifications/requests/accept</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>id[]</code></p>\n<p>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.</p>\n<h2 id=\"post-api-v1-notifications-requests-dismiss\">POST /api/v1/notifications/requests/dismiss</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>id[]</code></p>\n<p>The same, dismissing.</p>\n<h2 id=\"get-api-v1-notifications-requests-merged\">GET /api/v1/notifications/requests/merged</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:notifications</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Always <code>{&quot;merged&quot;: true}</code>. Mastodon answers <code>false</code> 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.</p>\n<h2 id=\"post-api-v1-notifications-clear\">POST /api/v1/notifications/clear</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:notifications</code> or <code>write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Dismisses every notification the viewer has and answers <code>{}</code>.</p>\n<h2 id=\"get-api-v1-markers\">GET /api/v1/markers</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>timeline</code> (array of <code>home</code>, <code>notifications</code>; all of them when omitted)</p>\n<p>How far through each timeline the viewer has read: <code>{&quot;notifications&quot;: {&quot;last_read_id&quot;: &quot;42&quot;, &quot;version&quot;: 3, &quot;updated_at&quot;: &quot;…&quot;}}</code>. Always a JSON object, <code>{}</code> for an account with no markers yet — never <code>[]</code>. Absent timelines have no marker yet. The web client itself draws the line on My Feed from <code>home</code> and the New/Earlier headings on Activities from <code>notifications</code>.</p>\n<h2 id=\"post-api-v1-markers\">POST /api/v1/markers</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>Body (JSON or form-encoded): <code>home[last_read_id]</code>, <code>notifications[last_read_id]</code></p>\n<p>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.</p>\n<h2 id=\"get-api-v1-annual-reports\">GET /api/v1/annual_reports</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p><strong>The year an account had</strong>, Mastodon&#39;s <code>#Wrapstodon</code> — one report per year the account wrote anything in, newest first, in Mastodon&#39;s <code>WrappedAnnualReports</code> shape (<code>annual_reports</code>, <code>accounts</code>, <code>statuses</code>). Each report carries <code>archetype</code> (<code>lurker</code>, <code>booster</code>, <code>pollster</code>, <code>replier</code> or <code>oracle</code>), a <code>time_series</code> of twelve months with what was posted and who arrived, the <code>top_hashtags</code> used, and <code>top_statuses</code> by boosts, replies and favourites. <strong>Computed on demand and never stored</strong>: 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. <code>share_url</code> is <strong>null</strong> — Mastodon&#39;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&#39;s post. <code>schema_version</code> is 1, the shape Mastodon 4.3 defined. At most 10000 posts and 5000 followers are walked.</p>\n<h2 id=\"get-api-v1-annual-reports-year\">GET /api/v1/annual_reports/{year}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>year</code></p>\n<p>The one year, in the same wrapper. A year the account wrote nothing in answers with an empty wrapper rather than twelve empty months.</p>\n<h2 id=\"get-api-v1-annual-reports-year-state\">GET /api/v1/annual_reports/{year}/state</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>year</code></p>\n<p><code>{&quot;state&quot;: &quot;available&quot;}</code> or <code>&quot;ineligible&quot;</code>. <strong><code>generating</code> never comes back</strong>: the report is a query rather than a job, so there is nothing to wait for. A future year is <code>ineligible</code>.</p>\n<h2 id=\"post-api-v1-annual-reports-year-read\">POST /api/v1/annual_reports/{year}/read</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>year</code></p>\n<p>Marks one read, so a client stops offering it. Kept as a per-account preference (<code>annual_reports_read</code>), because that is all it is: a note about a report that is not stored either.</p>\n<h2 id=\"post-api-v1-annual-reports-year-generate\">POST /api/v1/annual_reports/{year}/generate</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>year</code></p>\n<p>A <strong>no-op that answers 200</strong>. 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.</p>\n<p>All four return a bare JSON array of statuses (no envelope) together with a <code>Link</code> header — see Pagination.</p>\n<p>The home timeline is two pages, not one query. A post belongs there if the viewer follows its <strong>author</strong> or follows one of its <strong>hashtags</strong> and the post is public; each half is a query over <code>social_stream.nid</code>, and they are merged, deduplicated and cut to <code>limit</code> 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 <code>limit</code>, so anything belonging in the top <code>limit</code> of the union is in the top <code>limit</code> 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.</p>\n","toc":[{"id":"get-api-v1-timelines-timeline","text":"GET /api/v1/timelines/{timeline}/","level":2},{"id":"get-api-v1-timelines-tag-hashtag","text":"GET /api/v1/timelines/tag/{hashtag}","level":2},{"id":"get-api-v1-timelines-list-id","text":"GET /api/v1/timelines/list/{id}","level":2},{"id":"get-api-v1-favourites","text":"GET /api/v1/favourites/","level":2},{"id":"get-api-v1-bookmarks","text":"GET /api/v1/bookmarks","level":2},{"id":"get-api-v1-notifications","text":"GET /api/v1/notifications","level":2},{"id":"get-api-v1-notifications-unread-count","text":"GET /api/v1/notifications/unread_count","level":2},{"id":"get-api-v1-notifications-id","text":"GET /api/v1/notifications/{id}","level":2},{"id":"post-api-v1-notifications-id-dismiss","text":"POST /api/v1/notifications/{id}/dismiss","level":2},{"id":"get-api-v2-notifications","text":"GET /api/v2/notifications","level":2},{"id":"get-api-v2-notifications-unread-count","text":"GET /api/v2/notifications/unread_count","level":2},{"id":"get-api-v2-notifications-group-key","text":"GET /api/v2/notifications/{group_key}","level":2},{"id":"get-api-v2-notifications-group-key-accounts","text":"GET /api/v2/notifications/{group_key}/accounts","level":2},{"id":"post-api-v2-notifications-group-key-dismiss","text":"POST /api/v2/notifications/{group_key}/dismiss","level":2},{"id":"get-api-v1-notifications-policy","text":"GET /api/v1/notifications/policy","level":2},{"id":"patch-api-v1-notifications-policy","text":"PATCH /api/v1/notifications/policy","level":2},{"id":"get-api-v2-notifications-policy","text":"GET /api/v2/notifications/policy","level":2},{"id":"patch-api-v2-notifications-policy","text":"PATCH /api/v2/notifications/policy","level":2},{"id":"get-api-v1-social-notification-delivery","text":"GET /api/v1/social/notification_delivery","level":2},{"id":"patch-api-v1-social-notification-delivery","text":"PATCH /api/v1/social/notification_delivery","level":2},{"id":"get-api-v1-notifications-requests","text":"GET /api/v1/notifications/requests","level":2},{"id":"get-api-v1-notifications-requests-id","text":"GET /api/v1/notifications/requests/{id}","level":2},{"id":"post-api-v1-notifications-requests-id-accept","text":"POST /api/v1/notifications/requests/{id}/accept","level":2},{"id":"post-api-v1-notifications-requests-id-dismiss","text":"POST /api/v1/notifications/requests/{id}/dismiss","level":2},{"id":"get-api-v1-social-notifications-allowed","text":"GET /api/v1/social/notifications/allowed","level":2},{"id":"delete-api-v1-social-notifications-allowed-account-id","text":"DELETE /api/v1/social/notifications/allowed/{account_id}","level":2},{"id":"post-api-v1-social-notifications-policy-notice-dismiss","text":"POST /api/v1/social/notifications/policy/notice/dismiss","level":2},{"id":"post-api-v1-notifications-requests-accept","text":"POST /api/v1/notifications/requests/accept","level":2},{"id":"post-api-v1-notifications-requests-dismiss","text":"POST /api/v1/notifications/requests/dismiss","level":2},{"id":"get-api-v1-notifications-requests-merged","text":"GET /api/v1/notifications/requests/merged","level":2},{"id":"post-api-v1-notifications-clear","text":"POST /api/v1/notifications/clear","level":2},{"id":"get-api-v1-markers","text":"GET /api/v1/markers","level":2},{"id":"post-api-v1-markers","text":"POST /api/v1/markers","level":2},{"id":"get-api-v1-annual-reports","text":"GET /api/v1/annual_reports","level":2},{"id":"get-api-v1-annual-reports-year","text":"GET /api/v1/annual_reports/{year}","level":2},{"id":"get-api-v1-annual-reports-year-state","text":"GET /api/v1/annual_reports/{year}/state","level":2},{"id":"post-api-v1-annual-reports-year-read","text":"POST /api/v1/annual_reports/{year}/read","level":2},{"id":"post-api-v1-annual-reports-year-generate","text":"POST /api/v1/annual_reports/{year}/generate","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"timelines-and-notifications","manual":false,"prev":{"path":"/docs/api-announcements","title":"Announcements"},"next":{"path":"/docs/api-followed-hashtags","title":"Followed hashtags"},"parent":"api-mastodon-compatible-api"},{"slug":"api-followed-hashtags","path":"/docs/api-followed-hashtags","title":"Followed hashtags","description":"Auth: public, no-csrf (viewer required, read:follows or read scope) · Parameters: limit (20, capped at 50), max_id (0), min_id (0)","group":"api","html":"<h2 id=\"get-api-v1-followed-tags\">GET /api/v1/followed_tags</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:follows</code> or <code>read</code> scope) · <strong>Parameters: </strong><code>limit</code> (20, capped at 50), <code>max_id</code> (0), <code>min_id</code> (0)</p>\n<p>The hashtags the viewer follows, as Mastodon <code>Tag</code> entities with <code>following: true</code>. Newest follow first. Sends a <code>Link</code> header whose cursor is the <code>social_followed_tag</code> 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.</p>\n<h2 id=\"get-api-v1-tags-hashtag\">GET /api/v1/tags/{hashtag}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:follows</code>, <code>read:statuses</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One <code>Tag</code> entity — <code>name</code>, <code>url</code>, <code>history</code>, <code>following</code> — for <code>{hashtag}</code>, with or without its leading <code>#</code>. A tag nobody has posted is not a 404: it is a real tag with an empty <code>history</code> and <code>following: false</code>.</p>\n<h2 id=\"post-api-v1-tags-hashtag-follow\">POST /api/v1/tags/{hashtag}/follow</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:follows</code>, <code>write</code> or <code>follow</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Follows the hashtag and returns the <code>Tag</code> with <code>following: true</code>. 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&#39;s new posts beyond this server are read in the background every quarter of an hour (<code>Cron\\FillFollowedTags</code>, at most 20 a network, none older than two days) and reach the home timeline like any public post carrying it.</p>\n<h2 id=\"post-api-v1-tags-hashtag-unfollow\">POST /api/v1/tags/{hashtag}/unfollow</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:follows</code>, <code>write</code> or <code>follow</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Unfollows it and returns the <code>Tag</code> with <code>following: false</code>. Unfollowing what was never followed is not an error either.</p>\n<p>Following a hashtag is what puts its <strong>public</strong> posts into the viewer&#39;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.</p>\n<p>A hashtag is stored and compared in one form: the tag with no leading <code>#</code>, trimmed, lowercased, and cut to the 127 characters <code>social_stream_tag.hashtag</code> holds (<code>FollowedTagsRequest::normalise()</code>). So <code>#NextCloud</code> and <code>nextcloud</code> are one tag to follow, one tag to look up and one tag to unfollow. A post&#39;s tags are stored in the same form, so <code>/api/v1/timelines/tag/{hashtag}</code> normalises <code>{hashtag}</code> the same way and compares it with the stored tag exactly, which the <code>social_st_ht</code> index can answer. Something that normalises to nothing — <code>#</code>, or spaces — is a <strong>422</strong>, not a stored row that no post could ever match.</p>\n<p>The <code>history</code> of a <code>Tag</code> from any of these routes is the one the trends endpoint sends: a single bucket for the default window (<code>1d</code>), <code>uses</code> from the counts the cron keeps, and <code>accounts</code> always <code>0</code> because this instance counts uses rather than distinct accounts. A hashtag nobody has posted has an empty <code>history</code> rather than a zeroed bucket, because a zero would be a claim about a day. <code>following</code> is present on every <code>Tag</code> these routes return and absent from <code>/api/v1/trends/tags</code>, which is a public route with no viewer to answer it for.</p>\n","toc":[{"id":"get-api-v1-followed-tags","text":"GET /api/v1/followed_tags","level":2},{"id":"get-api-v1-tags-hashtag","text":"GET /api/v1/tags/{hashtag}","level":2},{"id":"post-api-v1-tags-hashtag-follow","text":"POST /api/v1/tags/{hashtag}/follow","level":2},{"id":"post-api-v1-tags-hashtag-unfollow","text":"POST /api/v1/tags/{hashtag}/unfollow","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"followed-hashtags","manual":false,"prev":{"path":"/docs/api-timelines-and-notifications","title":"Timelines and notifications"},"next":{"path":"/docs/api-for-you","title":"For you"},"parent":"api-mastodon-compatible-api"},{"slug":"api-for-you","path":"/docs/api-for-you","title":"For you","description":"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…","group":"api","html":"<h2 id=\"for-you-recommendation-preferences\">For You recommendation preferences</h2>\n<p>These additive routes are controlled by the separate instance-wide <code>rec_v4_enabled</code> 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 <strong>409</strong> with the current owner state.</p>\n<h2 id=\"get-api-v1-recommendations-preferences\">GET /api/v1/recommendations/preferences</h2>\n<p><strong>Parameters: </strong><code>read:accounts</code></p>\n<h2 id=\"put-api-v1-recommendations-learning\">PUT /api/v1/recommendations/learning</h2>\n<p><strong>Parameters: </strong><code>write:accounts</code>; <code>if_revision</code>, <code>mode</code> (<code>off</code>, <code>on</code>, <code>paused</code>)</p>\n<h2 id=\"post-api-v1-recommendations-signals\">POST /api/v1/recommendations/signals</h2>\n<p><strong>Parameters: </strong><code>write:statuses</code>; at most 100 events with UUID <code>event_id</code> and integer current <code>generation</code></p>\n<h2 id=\"post-api-v1-recommendations-reset\">POST /api/v1/recommendations/reset</h2>\n<p><strong>Parameters: </strong><code>write:accounts</code>; <code>if_revision</code>, optional <code>scope</code> (<code>learning</code>, <code>all</code>)</p>\n<h2 id=\"post-api-v1-recommendations-feedback\">POST /api/v1/recommendations/feedback</h2>\n<p><strong>Parameters: </strong><code>write:statuses</code>; <code>event_id</code>, visible <code>post_id</code>, <code>kind</code></p>\n<h2 id=\"delete-api-v1-recommendations-feedback-feedbackid\">DELETE /api/v1/recommendations/feedback/{feedbackId}</h2>\n<p><strong>Parameters: </strong><code>write:statuses</code></p>\n<h2 id=\"get-api-v1-recommendations-context-postid\">GET /api/v1/recommendations/context/{postId}</h2>\n<p><strong>Parameters: </strong><code>read:statuses</code></p>\n<h2 id=\"get-api-v1-recommendations-export\">GET /api/v1/recommendations/export</h2>\n<p><strong>Parameters: </strong><code>read:accounts</code></p>\n<h2 id=\"get-api-v1-recommendations-timeline\">GET /api/v1/recommendations/timeline</h2>\n<p><strong>Parameters: </strong><code>read:statuses</code>; optional <code>limit</code> (1–50), opaque <code>cursor</code>, and <code>media</code> (<code>photos</code>, <code>videos</code>, <code>shorts</code>, <code>media</code>)</p>\n<h2 id=\"get-put-admin-recommendations\">GET/PUT /admin/recommendations</h2>\n<p><strong>Parameters: </strong>administrator, CSRF; PUT accepts any subset of <code>enabled</code>, <code>remoteDiscoveryPaused</code>, <code>learningPaused</code>, <code>forceLegacyFeed</code></p>\n<h2 id=\"get-admin-recommendations-discovery\">GET /admin/recommendations/discovery</h2>\n<p><strong>Parameters: </strong>administrator, CSRF; optional <code>hours</code> (1–168, defaults to 24)</p>\n<p>An ancestor <code>HIDE</code> 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.</p>\n<p>For ranked timeline statuses, <code>interest.explanation</code> 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.</p>\n<p>Legacy hashtag-interest routes remain available to the web client. They expose the reader&#39;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 <code>/api/v1/recommendations/</code> routes above.</p>\n<h2 id=\"get-api-v1-interests\">GET /api/v1/interests</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The reader&#39;s learning settings, ranked hashtag interests, nearby candidates, thin-profile flag, and configured cap.</p>\n<h2 id=\"post-api-v1-interests-reset\">POST /api/v1/interests/reset</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Clears the reader&#39;s learned hashtag profile and reading baseline, then returns the current state.</p>\n<h2 id=\"put-api-v1-interests-settings\">PUT /api/v1/interests/settings</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> scope) · <strong>Parameters: </strong>Any of <code>learning</code>, <code>paused</code>, <code>languages</code> (up to 20 language codes), <code>noticeAcknowledged</code></p>\n<p>Saves only the named settings and returns the current state, including <code>instancePaused</code> when the administrator has globally stopped behavioral learning.</p>\n<h2 id=\"post-api-v1-interests-signals\">POST /api/v1/interests/signals</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope), 30 a minute · <strong>Parameters: </strong>Up to 100 <code>{status_id, kind, ms, context}</code> events</p>\n<p>Records eligible reading signals from posts the viewer can see. The server reads hashtags from the stored post; the client cannot supply them. Answers <strong>204</strong>, including when learning is paused.</p>\n<h2 id=\"post-api-v1-interests-less-nid\">POST /api/v1/interests/less/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Hides a visible post from the legacy interest feed and reduces its hashtags&#39; learned weight. Answers <code>{}</code>.</p>\n<h2 id=\"delete-api-v1-interests-less-nid\">DELETE /api/v1/interests/less/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:statuses</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Undoes a recorded “less like this” action and restores its learned weight. Repeating the undo is safe. Answers <code>{}</code>.</p>\n<h2 id=\"get-api-v1-timelines-interests\">GET /api/v1/timelines/interests</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> scope), 300 a minute · <strong>Parameters: </strong><code>limit</code>, <code>max_id</code>, <code>offset</code>, <code>media</code>, <code>only_media</code>, <code>only_short</code></p>\n<p>The compatibility timeline ranked from learned interests and existing fallback sources. Visibility, mute, block, language and keyword filters apply as on other timelines.</p>\n<p><strong>Paging a ranked feed.</strong> 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. <code>max_id</code> is the last post of the previous page, which is what every Mastodon client sends, and the <code>Link</code> header&#39;s <code>next</code> names it; there is no <code>prev</code>. 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.</p>\n<p><strong>Learning from actions.</strong> A favourite, a boost, a bookmark and a reply teach the reader&#39;s interests wherever they come from, a Mastodon app included (<code>ActionService</code>, <code>PostService</code>). Reading-time signals come from the web interface.</p>\n","toc":[{"id":"for-you-recommendation-preferences","text":"For You recommendation preferences","level":2},{"id":"get-api-v1-recommendations-preferences","text":"GET /api/v1/recommendations/preferences","level":2},{"id":"put-api-v1-recommendations-learning","text":"PUT /api/v1/recommendations/learning","level":2},{"id":"post-api-v1-recommendations-signals","text":"POST /api/v1/recommendations/signals","level":2},{"id":"post-api-v1-recommendations-reset","text":"POST /api/v1/recommendations/reset","level":2},{"id":"post-api-v1-recommendations-feedback","text":"POST /api/v1/recommendations/feedback","level":2},{"id":"delete-api-v1-recommendations-feedback-feedbackid","text":"DELETE /api/v1/recommendations/feedback/{feedbackId}","level":2},{"id":"get-api-v1-recommendations-context-postid","text":"GET /api/v1/recommendations/context/{postId}","level":2},{"id":"get-api-v1-recommendations-export","text":"GET /api/v1/recommendations/export","level":2},{"id":"get-api-v1-recommendations-timeline","text":"GET /api/v1/recommendations/timeline","level":2},{"id":"get-put-admin-recommendations","text":"GET/PUT /admin/recommendations","level":2},{"id":"get-admin-recommendations-discovery","text":"GET /admin/recommendations/discovery","level":2},{"id":"get-api-v1-interests","text":"GET /api/v1/interests","level":2},{"id":"post-api-v1-interests-reset","text":"POST /api/v1/interests/reset","level":2},{"id":"put-api-v1-interests-settings","text":"PUT /api/v1/interests/settings","level":2},{"id":"post-api-v1-interests-signals","text":"POST /api/v1/interests/signals","level":2},{"id":"post-api-v1-interests-less-nid","text":"POST /api/v1/interests/less/{nid}","level":2},{"id":"delete-api-v1-interests-less-nid","text":"DELETE /api/v1/interests/less/{nid}","level":2},{"id":"get-api-v1-timelines-interests","text":"GET /api/v1/timelines/interests","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"for-you","manual":false,"prev":{"path":"/docs/api-followed-hashtags","title":"Followed hashtags"},"next":{"path":"/docs/api-polls","title":"Polls"},"parent":"api-mastodon-compatible-api"},{"slug":"api-polls","path":"/docs/api-polls","title":"Polls","description":"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…","group":"api","html":"<h2 id=\"get-api-v1-polls-nid\">GET /api/v1/polls/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p>The Mastodon <code>Poll</code> entity of the status <code>{nid}</code>: options with vote counts, <code>expires_at</code>/<code>expired</code> (true from <code>expires_at</code> itself on: the sweep that tells the voters runs on that second, and a vote taken on it would change results already announced), <code>multiple</code>, <code>voters_count</code>, and the viewer&#39;s <code>voted</code>/<code>own_votes</code>. 404 when the status is not a poll.</p>\n<h2 id=\"post-api-v1-polls-nid-votes\">POST /api/v1/polls/{nid}/votes</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>choices</code> (array of option indices)</p>\n<p>Votes on a <em>federated</em> poll: each choice is delivered to the poll&#39;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 <code>Update{Question}</code> from the origin. 422 on invalid or duplicate votes and on expired polls. A vote on a <strong>local</strong> 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 <code>poll</code> to <code>POST /api/v1/statuses</code>.</p>\n<p>Incoming federated polls (<code>Question</code> objects) are stored like notes, appear in every timeline, and carry the <code>poll</code> entity in their status export; a remote <code>Update{Question}</code> refreshes the counts, and one that changes nothing but the counts is not an edit: no new version in the history, no <code>update</code> notification.</p>\n","toc":[{"id":"get-api-v1-polls-nid","text":"GET /api/v1/polls/{nid}","level":2},{"id":"post-api-v1-polls-nid-votes","text":"POST /api/v1/polls/{nid}/votes","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"polls","manual":false,"prev":{"path":"/docs/api-for-you","title":"For you"},"next":{"path":"/docs/api-link-previews","title":"Link previews"},"parent":"api-mastodon-compatible-api"},{"slug":"api-link-previews","path":"/docs/api-link-previews","title":"Link previews","description":"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…","group":"api","html":"<p>Statuses carry Mastodon&#39;s <code>card</code> entity: <code>url</code>, <code>title</code>, <code>description</code>, <code>type</code> (always <code>link</code>), <code>provider_name</code>, <code>image</code>, and the fields this app cannot fill (<code>author_name</code>, <code>html</code>, <code>width</code>/<code>height</code>, <code>embed_url</code>, <code>blurhash</code>) as empty values so that clients reading them blindly keep working. It is <code>null</code> for a post that links nowhere.</p>\n<p>There is no endpoint for cards — they are derived data, never federated, and every instance reads the linked page itself:</p>\n<ul>\n<li>The first plain link of a post is what gets previewed; mentions and hashtags are skipped, and only <code>http(s)</code> links count.</li>\n<li>The page is read by a background job (a <code>LinkPreview</code> item in the stream queue, drained by cron or <code>occ social:queue:process</code>), so posting and inbox delivery never wait for a stranger&#39;s web server. A post therefore gains its card shortly <em>after</em> it appears.</li>\n<li>The fetch goes through <code>CurlService</code>, which means: <code>http(s)</code> only on the request and on every redirect, no local addresses, a download size cap, a 5 s timeout, and <strong>the instance access list</strong> — with an allow-list configured, previews only come from listed hosts.</li>\n<li>The card is read from <code>OpenGraph</code>, then Twitter-card tags, then the plain <code>&lt;title&gt;</code> and <code>&lt;meta name=&quot;description&quot;&gt;</code>. Title and description are length-capped and stored as text, never as markup; a preview image must itself be an <code>http(s)</code> URL.</li>\n<li>Cards live in <code>social_stream_card</code>, keyed by the post, and are deleted with it (including by the retention job).</li>\n</ul>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"link-previews","manual":false,"prev":{"path":"/docs/api-polls","title":"Polls"},"next":{"path":"/docs/api-reports","title":"Reports"},"parent":"api-mastodon-compatible-api"},{"slug":"api-reports","path":"/docs/api-reports","title":"Reports","description":"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…","group":"api","html":"<h2 id=\"post-api-v1-accounts\">POST /api/v1/accounts</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p><strong>403</strong> in Mastodon&#39;s registration-error shape (<code>error</code> plus <code>details.base[].error</code>/<code>description</code>), 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&#39;s own registration page when the <code>registration</code> app is enabled, and otherwise that an administrator creates accounts. A 404 was the wrong way to say this: a client reads it as &quot;this server is broken&quot; and shows a person nothing they can act on, while a 403 like this is decoded and displayed. <code>registrations: false</code> 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&#39;s for the same reason, and this app has no route for any of them.</p>\n<h2 id=\"post-api-v1-reports\">POST /api/v1/reports</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>account_id</code> (required), <code>status_ids</code> (array), <code>comment</code>, <code>category</code> (<code>spam</code>, <code>legal</code>, <code>violation</code> or <code>other</code>; anything else becomes <code>other</code>), <code>forward</code></p>\n<p>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 <code>account_id</code> too. With <code>forward</code> set and the account on another instance, the report is also delivered there as a <code>Flag</code> — <strong>anonymised</strong>: the activity names this instance&#39;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 <code>Report</code> entity (<code>action_taken</code>, <code>category</code>, <code>comment</code>, <code>status_ids</code>, <code>target_account</code>, …); <code>forwarded</code> is <code>true</code> only once the remote inbox has accepted the <code>Flag</code>, so a forward that could not be delivered reads <code>false</code> and the report still stands. Rate-limited to 30 an hour, per address and per account: every report notifies the moderators.</p>\n<p>Incoming federated reports (<code>Flag</code> 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&#39;s author. A report that arrived that way is never forwarded on: passing it along would put this instance&#39;s name on somebody else&#39;s complaint, and two instances doing that to each other is a loop.</p>\n","toc":[{"id":"post-api-v1-accounts","text":"POST /api/v1/accounts","level":2},{"id":"post-api-v1-reports","text":"POST /api/v1/reports","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"reports","manual":false,"prev":{"path":"/docs/api-link-previews","title":"Link previews"},"next":{"path":"/docs/api-admin-api-mastodon","title":"Admin API (Mastodon)"},"parent":"api-mastodon-compatible-api"},{"slug":"api-admin-api-mastodon","path":"/docs/api-admin-api-mastodon","title":"Admin API (Mastodon)","description":"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…","group":"api","html":"<p>Mastodon&#39;s <code>/api/v1/admin/*</code>, over the moderation the admin panel has always\nhad. Every route requires a <strong>moderator</strong>: the user behind the bearer token (or\nbehind the session) is resolved first and asked of\n<code>AdminApiService::isAdministrator()</code>, and anyone else is a <strong>403</strong> having had\nnothing done on their behalf. A moderator is a Nextcloud administrator, or\nsomebody an administrator has handed the <strong>Aloha Social</strong> settings section to under\n<em>Administration privileges</em> — Nextcloud&#39;s own settings delegation\n(<code>IManager::getAllowedAdminSettings()</code>), which is the same gate the admin panel\nand its buttons sit behind, so the two cannot disagree about who may act.\nModerating otherwise meant administering the whole server, which is a great\ndeal of power to hand somebody so they can act on a report. Nothing is\ndelegated by default, so out of the box only administrators pass. A scope is <em>not</em> that check and cannot be — this app&#39;s\nOAuth registration stores whatever scope string a client asks for, so\n<code>admin:write</code> on a token says only that some client asked for it. The scope is\nrequired in addition, as Mastodon requires it: a bearer token needs\n<code>admin:read</code> (or the broad <code>admin</code>) to read and <code>admin:write</code> to write, and\nthe <code>read</code>/<code>write</code> every timeline client holds satisfies neither. An\nadministrator&#39;s own browser session (with its CSRF token) needs no scope,\nhaving no token to carry one.</p>\n<p>Every write about one account (<code>action</code>, <code>unsilence</code>, <code>unsuspend</code>,\n<code>unsensitive</code>, <code>DELETE</code>, and Pixelfed&#39;s <code>/api/admin/users/action</code>) is a <strong>403</strong>\nwith nothing done when it names the caller&#39;s own account, or a Nextcloud\nadministrator&#39;s account and the caller is only a delegate\n(<code>AdminApiService::assertMayActOn()</code>).</p>\n<p>A client finds out whether to offer moderation at all from the <code>role</code> of the\nCredentialAccount — <code>verify_credentials</code>, <code>update_credentials</code> and the two\n<code>/api/v1/profile/*</code> deletions — so it can ask for <code>admin:read admin:write</code> only\nfrom somebody who can use them. <code>AdminApiService::credentialRole()</code> works it out\non every request, from the same checks as the gate above:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Who</th>\n<th><code>id</code></th>\n<th><code>name</code></th>\n<th><code>permissions</code></th>\n<th><code>highlighted</code></th>\n</tr>\n</thead>\n<tbody><tr>\n<td>A Nextcloud administrator</td>\n<td><code>&quot;3&quot;</code></td>\n<td><code>Admin</code></td>\n<td>every Mastodon flag (<code>&quot;8388607&quot;</code>), as Mastodon reports a role with the administrator bit</td>\n<td><code>true</code></td>\n</tr>\n<tr>\n<td>A user the section is delegated to</td>\n<td><code>&quot;1&quot;</code></td>\n<td><code>Moderator</code></td>\n<td><code>&quot;591288&quot;</code>: invite users, view dashboard, manage reports, federation, blocks, taxonomies and users, delete user data — what the admin API lets them do</td>\n<td><code>true</code></td>\n</tr>\n<tr>\n<td>Anyone else</td>\n<td><code>&quot;-99&quot;</code></td>\n<td><code>&quot;&quot;</code></td>\n<td><code>&quot;65536&quot;</code>, Mastodon&#39;s default role</td>\n<td><code>false</code></td>\n</tr>\n</tbody></table></div>\n<p><code>color</code> is always <code>&quot;&quot;</code>. A non-moderator is refused with <strong>403</strong> and no\n<code>WWW-Authenticate</code> header — see <a href=\"/docs/api-error-responses#client-api-status-codes\">Client API status codes</a>\nfor why the header would turn it into a 401.</p>\n<p>Entities carry every key Mastodon documents. Where this app has nothing behind\none it is sent as the empty value of its type rather than omitted, because a\nclient that declares a field non-optional cannot decode the entity otherwise:\non <code>Admin::Account</code> that is <code>email</code> (<code>&quot;&quot;</code> — the address belongs to the\nNextcloud account and is not republished here), <code>ip</code> (<code>null</code>), <code>ips</code> (<code>[]</code>),\n<code>locale</code> (<code>&quot;&quot;</code>), <code>invite_request</code> (<code>null</code>), <code>role</code> (<code>null</code> — the role is reported to the\nsigned-in user on their own CredentialAccount, and Mastodon also sends <code>null</code>\nfor an account it holds no user of),\n<code>disabled</code> and <code>sensitized</code> (always <code>false</code>, no state here corresponds to\neither), <code>created_by_application_id</code> and <code>invited_by_account_id</code> (<code>null</code>).\n<code>confirmed</code> and <code>approved</code> are <code>true</code> for a local account and <code>false</code> for a\nremote one, as on Mastodon: both describe a user of <em>this</em> instance.</p>\n<h2 id=\"get-api-v1-admin-accounts\">GET /api/v1/admin/accounts</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>origin</code> (<code>local</code> or <code>remote</code>), <code>status</code> (<code>active</code>, <code>silenced</code>, <code>suspended</code>, <code>pending</code>, <code>disabled</code>), <code>username</code>, <code>display_name</code>, <code>by_domain</code>, <code>email</code>, <code>ip</code>, <code>limit</code> (40, capped at 200), <code>max_id</code> (0), <code>min_id</code> (0)</p>\n<p>A page of accounts as <code>Admin::Account</code>, newest first, with a <code>Link</code> header. <code>origin</code> outside <code>local</code> and <code>remote</code> is a <strong>422</strong> rather than an unfiltered page. <code>status=silenced</code> and <code>status=suspended</code> are read from the instance&#39;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 <code>limit</code>, are not paged further, and carry no <code>Link</code> header. <code>pending</code> and <code>disabled</code> are states this app does not have (nothing awaits approval, and a fediverse account has no login to disable) and answer with <strong>no accounts</strong>, as do <code>email</code> and <code>ip</code> — 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.</p>\n<h2 id=\"get-api-v2-admin-accounts\">GET /api/v2/admin/accounts</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>the same filters and cursors as the v1 row</p>\n<p>The same page of <code>Admin::Account</code> 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.</p>\n<h2 id=\"get-api-v1-admin-accounts-id\">GET /api/v1/admin/accounts/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One <code>Admin::Account</code>. <code>{id}</code> is the numeric id, the account&#39;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 <code>id</code> the entity itself reports for such an account. Nothing is ever fetched from another server to answer this. Unknown is a <strong>404</strong>.</p>\n<h2 id=\"post-api-v1-admin-accounts-id-action\">POST /api/v1/admin/accounts/{id}/action</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>type</code> (<code>silence</code>, <code>suspend</code>, <code>sensitive</code>, <code>none</code>), <code>text</code>, <code>report_id</code></p>\n<p>Applies the decision through <code>ModerationService</code>, which is the same call the admin panel makes: <strong>silence</strong> takes the account out of the public and global timelines and changes no data; <strong>suspend</strong> deletes what it has posted here, drops its cached actor and refuses what it sends afterwards. <code>none</code> is Mastodon&#39;s own &quot;warn and take no action&quot;: it records a warning, tells the account if it is local, and leaves whatever stands standing — lifting is what the <code>unsilence</code> and <code>unsuspend</code> 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 <code>text</code> and <code>report_id</code>, in a history a lift does not empty. <code>text</code> is kept as the comment on a decision that stands. <strong><code>sensitive</code></strong> 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 <code>unsensitive</code> below. It was a <strong>422</strong> by name until this app had the tier, and the refusal outlived the gap by a wave. <code>disable</code> is still a <strong>422</strong>: it turns off a <em>login</em>, and on this server a login belongs to Nextcloud. With <code>report_id</code> the report is resolved in the same call, so the decision and the report it came from cannot disagree; a <code>report_id</code> that is not a report about this account is a <strong>404</strong> with nothing done, so an unrelated report cannot be closed as a side effect. Answers <code>{}</code>.</p>\n<h2 id=\"post-api-v1-admin-accounts-id-enable\">POST /api/v1/admin/accounts/{id}/enable</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Answers the <code>Admin::Account</code> and <strong>changes nothing</strong>: 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 &quot;no such account&quot;.</p>\n<h2 id=\"post-api-v1-admin-accounts-id-unsilence\">POST /api/v1/admin/accounts/{id}/unsilence</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>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 <code>Admin::Account</code>.</p>\n<h2 id=\"post-api-v1-admin-accounts-id-unsensitive\">POST /api/v1/admin/accounts/{id}/unsensitive</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Lifts &quot;everything this account posts is sensitive&quot;, and only that. The counterpart of <code>action</code> with <code>sensitive</code>, 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.</p>\n<h2 id=\"delete-api-v1-admin-accounts-id\">DELETE /api/v1/admin/accounts/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Deletes what the account posted <strong>here</strong>, leaving the account itself. Mastodon&#39;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&#39;s destructive half without the refusal: the posts go, the cached actor goes, and a local account&#39;s deletion is federated as a <code>Delete</code>. <strong>Irreversible</strong>, which is why it is its own verb rather than a severity inside <code>action</code>.</p>\n<h2 id=\"post-api-v1-admin-accounts-id-unsuspend\">POST /api/v1/admin/accounts/{id}/unsuspend</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>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 <code>Admin::Account</code>.</p>\n<h2 id=\"get-api-v1-admin-reports\">GET /api/v1/admin/reports</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>resolved</code> (absent = the open queue), <code>account_id</code> (the reporter), <code>target_account_id</code>, <code>limit</code> (40, capped at 200), <code>max_id</code> (0), <code>min_id</code> (0)</p>\n<p>A page of <code>Admin::Report</code>, newest first, with a <code>Link</code> header. The two account filters take the same references <code>{id}</code> does; one this instance has never heard of matches <strong>nothing</strong> rather than falling off the query. Each report carries the reporter and the reported account as <code>Admin::Account</code> — 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 <code>Status</code> entities (one no longer here is left out, the commonest reason being that a moderator already took it down), <code>rules</code> always <code>[]</code> (a report here carries a category, never a rule id) and <code>forwarded</code> always <code>false</code> (nothing forwards a report to the reported account&#39;s own instance).</p>\n<h2 id=\"get-api-v1-admin-reports-id\">GET /api/v1/admin/reports/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One <code>Admin::Report</code>; unknown is a <strong>404</strong>.</p>\n<h2 id=\"put-api-v1-admin-reports-id\">PUT /api/v1/admin/reports/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>category</code> (<code>spam</code>, <code>legal</code>, <code>violation</code> or <code>other</code>), <code>rule_ids</code></p>\n<p>Files a report under a different category. A moderator reading one often finds it under the wrong one — <code>spam</code> 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 <strong>422</strong>; an unknown id is a <strong>404</strong>, because the report is read before anything is written rather than updated blind. <code>rule_ids</code> is accepted and ignored, exactly as it is on <code>POST /api/v1/reports</code>: 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.</p>\n<h2 id=\"post-api-v1-admin-reports-id-resolve\">POST /api/v1/admin/reports/{id}/resolve</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Marks the report handled through <code>ReportService</code> — the same write the admin panel makes — and records the administrator who did it and when, which is what <code>action_taken_by_account</code> and <code>action_taken_at</code> report.</p>\n<h2 id=\"post-api-v1-admin-reports-id-reopen\">POST /api/v1/admin/reports/{id}/reopen</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Puts the report back in the queue and clears the record of who acted on it: it described a decision that no longer stands.</p>\n<h2 id=\"post-api-v1-admin-reports-id-assign-to-self\">POST /api/v1/admin/reports/{id}/assign_to_self</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Takes the report, so a second administrator can see it is being worked on — <code>assigned_account</code>. Stored on the report row by <code>Version1000Date20260911000013</code>; 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 <code>null</code> rather than as a failure).</p>\n<h2 id=\"post-api-v1-admin-reports-id-unassign\">POST /api/v1/admin/reports/{id}/unassign</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Gives the report back to the queue.</p>\n<h2 id=\"post-api-v1-admin-measures\">POST /api/v1/admin/measures</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>keys</code> (array, required), <code>start_at</code>, <code>end_at</code>, <code>instance</code>, <code>id</code></p>\n<p>One <code>Admin::Measure</code> per key: <code>key</code>, <code>unit</code> (<code>null</code>), <code>total</code>, <code>previous_total</code> and <code>data</code>, one point <strong>per day of the window whether or not anything happened on it</strong> — a chart with holes in it is a chart nobody can read. <code>previous_total</code> 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 <strong>370</strong> days. The keys this instance can answer: <code>active_users</code> (distinct local accounts that <strong>posted</strong> that day — this app has no session of its own to count), <code>new_users</code>, <code>interactions</code> (likes and boosts), <code>opened_reports</code>, <code>resolved_reports</code>, and, with the instance named in <code>instance</code>, <code>instance_accounts</code>, <code>instance_statuses</code> and <code>instance_reports</code>; with a hashtag in <code>id</code>, <code>tag_uses</code> and <code>tag_accounts</code>. <strong>Any other key is a 422 naming the ones that work</strong>, rather than a row of zeroes: the rest of Mastodon&#39;s keys describe a sign-up, an invite system, an email address or a media store this app does not own, and answering <code>0</code> to &quot;how many accounts signed up through an invite&quot; reads as &quot;none did&quot;, which is a different claim an admin would act on.</p>\n<h2 id=\"post-api-v1-admin-dimensions\">POST /api/v1/admin/dimensions</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>keys</code> (array, required), <code>start_at</code>, <code>end_at</code>, <code>limit</code> (10, capped at 100), <code>id</code></p>\n<p>One <code>Admin::Dimension</code> per key, each <code>{key, data: [{key, human_key, value}]}</code>. Answerable here: <code>servers</code> (the instances whose accounts posted most in the window — the host is read off the author&#39;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), <code>tag_servers</code> (the same for one hashtag, named in <code>id</code>) and <code>software_versions</code> (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 <strong>422</strong>, on the same reasoning as <code>measures</code>.</p>\n<h2 id=\"post-api-v1-admin-retention\">POST /api/v1/admin/retention</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>start_at</code>, <code>end_at</code></p>\n<p><code>Admin::Cohort</code> rows: one per month of local sign-ups in the window, each carrying one value per month since — how many of that month&#39;s accounts posted in it, and that over the size of the cohort as <code>rate</code>. An account that never posted is in its cohort and in none of its buckets. Always monthly, whatever <code>frequency</code> 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.</p>\n<h2 id=\"get-api-v1-admin-trends-tags\">GET /api/v1/admin/trends/tags</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>limit</code> (10, capped at 100)</p>\n<p>The trending hashtags, exactly as <code>/api/v1/trends/tags</code> answers them. On Mastodon these carry a moderator&#39;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 &quot;this server has no trends&quot;.</p>\n<h2 id=\"get-api-v1-admin-trends-statuses\">GET /api/v1/admin/trends/statuses</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>limit</code> (10, capped at 100), <code>offset</code> (0)</p>\n<p>The trending statuses, as <code>/api/v1/trends/statuses</code> answers them.</p>\n<h2 id=\"post-api-v1-admin-trends-tags-id-approve\">POST /api/v1/admin/trends/tags/{id}/approve</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Records that a moderator has looked at a hashtag and is content for it to trend. <strong>Grants nothing</strong>: 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. <code>{id}</code> is the hashtag, with or without its <code>#</code>.</p>\n<h2 id=\"post-api-v1-admin-trends-tags-id-reject\">POST /api/v1/admin/trends/tags/{id}/reject</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>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.</p>\n<h2 id=\"post-api-v1-admin-trends-links-id-approve\">POST /api/v1/admin/trends/links/{id}/approve</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The same for a trending link, named by its URL.</p>\n<h2 id=\"post-api-v1-admin-trends-links-id-reject\">POST /api/v1/admin/trends/links/{id}/reject</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Keeps a link out of the trending links.</p>\n<h2 id=\"post-api-v1-admin-trends-statuses-id-approve\">POST /api/v1/admin/trends/statuses/{id}/approve</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The same for a trending post, named by its ActivityPub id.</p>\n<h2 id=\"post-api-v1-admin-trends-statuses-id-reject\">POST /api/v1/admin/trends/statuses/{id}/reject</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Keeps a post out of the trending statuses, and out of the discover grid that reads the same ranking. It is <strong>not</strong> a takedown: the post stays where its author put it and everybody who follows them still sees it.</p>\n<h2 id=\"get-api-v1-admin-tags\">GET /api/v1/admin/tags</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>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 <code>/api/v1/admin/trends/tags</code>.</p>\n<h2 id=\"get-api-v1-admin-tags-id\">GET /api/v1/admin/tags/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One hashtag as Mastodon&#39;s <code>Admin::Tag</code>: <code>trendable</code> is the one field that means anything here. <code>usable</code> and <code>listable</code> are always <code>true</code> — they describe a tag row that can be disabled for <em>posting</em> and for <em>search</em>, and this app has no equivalent, since a hashtag here is written by whoever types it and exists because a post carries it. Saying <code>true</code> is the honest answer to &quot;may this be used&quot;, not a placeholder.</p>\n<h2 id=\"put-api-v1-admin-tags-id\">PUT /api/v1/admin/tags/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>trendable</code></p>\n<p>Sets whether the hashtag may trend. <code>usable</code> and <code>listable</code> are accepted and ignored, for the same reason <code>rule_ids</code> is on a report: a client sending all three should not have the one that works refused along with the two that do not.</p>\n<h2 id=\"get-api-v1-admin-trends-links\">GET /api/v1/admin/trends/links</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>limit</code> (10, capped at 100), <code>offset</code> (0)</p>\n<p>The trending links, as <code>/api/v1/trends/links</code> answers them.</p>\n<h2 id=\"get-api-v1-admin-ip-blocks\">GET /api/v1/admin/ip_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The addresses this instance answers nothing from, newest first, as <code>Admin::IpBlock</code>: <code>ip</code> (always a CIDR range — a bare address is stored as the range holding only itself, so there is one shape to match against), <code>severity</code>, <code>comment</code>, <code>created_at</code>, <code>expires_at</code> (<code>null</code> when it does not lift itself).</p>\n<h2 id=\"post-api-v1-admin-ip-blocks\">POST /api/v1/admin/ip_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>ip</code> (required), <code>severity</code> (<code>no_access</code>), <code>comment</code>, <code>expires_in</code> (seconds from now)</p>\n<p>Refuses an address or range <strong>everything this app serves</strong> — enforced in one middleware rather than per route, because &quot;no access&quot; 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 <strong>403</strong>, so a peer stops redelivering rather than queueing for days. <code>severity</code> may only be <code>no_access</code>: Mastodon&#39;s <code>sign_up_block</code> and <code>sign_up_requires_approval</code> 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 <strong>422</strong> rather than a row nothing will ever read, since an admin told their rule was stored would believe it was being enforced. A <code>ip</code> that is not an address or range is a <strong>422</strong>. Blocking a range already blocked replaces it.</p>\n<h2 id=\"get-api-v1-admin-ip-blocks-id\">GET /api/v1/admin/ip_blocks/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One <code>Admin::IpBlock</code>. Unknown is a <strong>404</strong>.</p>\n<h2 id=\"put-api-v1-admin-ip-blocks-id\">PUT /api/v1/admin/ip_blocks/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>severity</code> (<code>no_access</code>), <code>comment</code>, <code>expires_in</code></p>\n<p>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.</p>\n<h2 id=\"delete-api-v1-admin-ip-blocks-id\">DELETE /api/v1/admin/ip_blocks/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Lifts it and answers <code>{}</code>. Unknown is a <strong>404</strong>.</p>\n<h2 id=\"get-api-v1-admin-email-domain-blocks\">GET /api/v1/admin/email_domain_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The email domains this instance gives no fediverse account to, newest first, as <code>Admin::EmailDomainBlock</code>: <code>domain</code>, <code>created_at</code>, and <code>history</code> always <code>[]</code> — 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.</p>\n<h2 id=\"post-api-v1-admin-email-domain-blocks\">POST /api/v1/admin/email_domain_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>domain</code> (required)</p>\n<p>Refuses a fediverse identity to Nextcloud accounts whose email is at that domain, checked in <code>AccountService::createActor()</code>, 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 <strong>no</strong> 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 <strong>422</strong>.</p>\n<h2 id=\"get-api-v1-admin-email-domain-blocks-id\">GET /api/v1/admin/email_domain_blocks/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One <code>Admin::EmailDomainBlock</code>. Unknown is a <strong>404</strong>.</p>\n<h2 id=\"delete-api-v1-admin-email-domain-blocks-id\">DELETE /api/v1/admin/email_domain_blocks/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Lifts it and answers <code>{}</code>. Unknown is a <strong>404</strong>.</p>\n<h2 id=\"get-api-v1-admin-domain-allows\">GET /api/v1/admin/domain_allows</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The instances this server will talk to at all, as <code>Admin::DomainAllow</code> entities. The other half of <code>domain_blocks</code>, and it means something only while <code>access_type</code> is <code>none_but</code> — <strong>allowlist federation</strong>, 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. <code>id</code> 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&#39;s benefit alone; every route here takes the domain itself as well. <code>created_at</code> is the epoch, the list holding no timestamps. <strong>While the instance federates by a block list every route in this group is a 422</strong> — the mirror of the rule on <code>domain_blocks</code>, 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 &quot;disallow&quot; it would have unblocked it.</p>\n<h2 id=\"get-api-v1-admin-domain-allows-id\">GET /api/v1/admin/domain_allows/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One of them, by the derived id or by the domain itself.</p>\n<h2 id=\"post-api-v1-admin-domain-allows\">POST /api/v1/admin/domain_allows</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>domain</code> (required)</p>\n<p>Adds a domain to the allow list.</p>\n<h2 id=\"delete-api-v1-admin-domain-allows-id\">DELETE /api/v1/admin/domain_allows/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Takes one off it.</p>\n<h2 id=\"get-api-v1-admin-domain-blocks\">GET /api/v1/admin/domain_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Every domain this instance holds at arm&#39;s length, at whichever tier, as <code>Admin::DomainBlock</code> entities: the <strong>deny list</strong> — the one <code>occ social:fediverse</code> and the admin panel manage — as <code>severity: suspend</code>, and the <strong>silenced list</strong> as <code>severity: silence</code>. Not to be confused with <code>/api/v1/domain_blocks</code>, which is one user hiding a server from themselves. A suspension refuses the domain outright, so <code>reject_media</code> and <code>reject_reports</code> are <code>true</code>; a silence refuses nothing and only takes the domain&#39;s accounts out of the public timelines, so both are <code>false</code>. A domain on both lists is reported as suspended — the stronger tier is the one in force. <code>private_comment</code> and <code>public_comment</code> are <code>null</code> (the lists have no room for a reason), <code>obfuscate</code> is <code>false</code> (this instance publishes no list of what it blocks), and <code>created_at</code> is the epoch — the lists store no timestamps, and that is how this API says so rather than inventing a date. <code>id</code> 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 <strong>allow list</strong> (<code>none_but</code>) every route in this group is a <strong>422</strong>: 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 &quot;blocked&quot; a domain would have added it to the list of the allowed.</p>\n<h2 id=\"post-api-v1-admin-domain-blocks\">POST /api/v1/admin/domain_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>domain</code> (required), <code>severity</code> (<code>suspend</code> or <code>silence</code>; <code>suspend</code> when absent)</p>\n<p>Blocks a domain at the tier named and returns the entry. An address no hostname could be is a <strong>422</strong>, and so is Mastodon&#39;s third severity, <code>noop</code>, 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. <code>reject_media</code>, <code>reject_reports</code>, <code>obfuscate</code> and the two comments are accepted and ignored — the lists have no room for any of them.</p>\n<h2 id=\"get-api-v1-admin-domain-blocks-id\">GET /api/v1/admin/domain_blocks/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>One entry, by the derived id or by the domain; unknown is a <strong>404</strong>.</p>\n<h2 id=\"put-api-v1-admin-domain-blocks-id\">PUT /api/v1/admin/domain_blocks/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>severity</code> (<code>suspend</code> or <code>silence</code>)</p>\n<p>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 <code>noop</code> is the same <strong>422</strong> as above. Answers with the entry as it now stands.</p>\n<h2 id=\"delete-api-v1-admin-domain-blocks-id\">DELETE /api/v1/admin/domain_blocks/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Lifts the block at whichever tier it was, and answers with the entry that was lifted.</p>\n","toc":[{"id":"get-api-v1-admin-accounts","text":"GET /api/v1/admin/accounts","level":2},{"id":"get-api-v2-admin-accounts","text":"GET /api/v2/admin/accounts","level":2},{"id":"get-api-v1-admin-accounts-id","text":"GET /api/v1/admin/accounts/{id}","level":2},{"id":"post-api-v1-admin-accounts-id-action","text":"POST /api/v1/admin/accounts/{id}/action","level":2},{"id":"post-api-v1-admin-accounts-id-enable","text":"POST /api/v1/admin/accounts/{id}/enable","level":2},{"id":"post-api-v1-admin-accounts-id-unsilence","text":"POST /api/v1/admin/accounts/{id}/unsilence","level":2},{"id":"post-api-v1-admin-accounts-id-unsensitive","text":"POST /api/v1/admin/accounts/{id}/unsensitive","level":2},{"id":"delete-api-v1-admin-accounts-id","text":"DELETE /api/v1/admin/accounts/{id}","level":2},{"id":"post-api-v1-admin-accounts-id-unsuspend","text":"POST /api/v1/admin/accounts/{id}/unsuspend","level":2},{"id":"get-api-v1-admin-reports","text":"GET /api/v1/admin/reports","level":2},{"id":"get-api-v1-admin-reports-id","text":"GET /api/v1/admin/reports/{id}","level":2},{"id":"put-api-v1-admin-reports-id","text":"PUT /api/v1/admin/reports/{id}","level":2},{"id":"post-api-v1-admin-reports-id-resolve","text":"POST /api/v1/admin/reports/{id}/resolve","level":2},{"id":"post-api-v1-admin-reports-id-reopen","text":"POST /api/v1/admin/reports/{id}/reopen","level":2},{"id":"post-api-v1-admin-reports-id-assign-to-self","text":"POST /api/v1/admin/reports/{id}/assign_to_self","level":2},{"id":"post-api-v1-admin-reports-id-unassign","text":"POST /api/v1/admin/reports/{id}/unassign","level":2},{"id":"post-api-v1-admin-measures","text":"POST /api/v1/admin/measures","level":2},{"id":"post-api-v1-admin-dimensions","text":"POST /api/v1/admin/dimensions","level":2},{"id":"post-api-v1-admin-retention","text":"POST /api/v1/admin/retention","level":2},{"id":"get-api-v1-admin-trends-tags","text":"GET /api/v1/admin/trends/tags","level":2},{"id":"get-api-v1-admin-trends-statuses","text":"GET /api/v1/admin/trends/statuses","level":2},{"id":"post-api-v1-admin-trends-tags-id-approve","text":"POST /api/v1/admin/trends/tags/{id}/approve","level":2},{"id":"post-api-v1-admin-trends-tags-id-reject","text":"POST /api/v1/admin/trends/tags/{id}/reject","level":2},{"id":"post-api-v1-admin-trends-links-id-approve","text":"POST /api/v1/admin/trends/links/{id}/approve","level":2},{"id":"post-api-v1-admin-trends-links-id-reject","text":"POST /api/v1/admin/trends/links/{id}/reject","level":2},{"id":"post-api-v1-admin-trends-statuses-id-approve","text":"POST /api/v1/admin/trends/statuses/{id}/approve","level":2},{"id":"post-api-v1-admin-trends-statuses-id-reject","text":"POST /api/v1/admin/trends/statuses/{id}/reject","level":2},{"id":"get-api-v1-admin-tags","text":"GET /api/v1/admin/tags","level":2},{"id":"get-api-v1-admin-tags-id","text":"GET /api/v1/admin/tags/{id}","level":2},{"id":"put-api-v1-admin-tags-id","text":"PUT /api/v1/admin/tags/{id}","level":2},{"id":"get-api-v1-admin-trends-links","text":"GET /api/v1/admin/trends/links","level":2},{"id":"get-api-v1-admin-ip-blocks","text":"GET /api/v1/admin/ip_blocks","level":2},{"id":"post-api-v1-admin-ip-blocks","text":"POST /api/v1/admin/ip_blocks","level":2},{"id":"get-api-v1-admin-ip-blocks-id","text":"GET /api/v1/admin/ip_blocks/{id}","level":2},{"id":"put-api-v1-admin-ip-blocks-id","text":"PUT /api/v1/admin/ip_blocks/{id}","level":2},{"id":"delete-api-v1-admin-ip-blocks-id","text":"DELETE /api/v1/admin/ip_blocks/{id}","level":2},{"id":"get-api-v1-admin-email-domain-blocks","text":"GET /api/v1/admin/email_domain_blocks","level":2},{"id":"post-api-v1-admin-email-domain-blocks","text":"POST /api/v1/admin/email_domain_blocks","level":2},{"id":"get-api-v1-admin-email-domain-blocks-id","text":"GET /api/v1/admin/email_domain_blocks/{id}","level":2},{"id":"delete-api-v1-admin-email-domain-blocks-id","text":"DELETE /api/v1/admin/email_domain_blocks/{id}","level":2},{"id":"get-api-v1-admin-domain-allows","text":"GET /api/v1/admin/domain_allows","level":2},{"id":"get-api-v1-admin-domain-allows-id","text":"GET /api/v1/admin/domain_allows/{id}","level":2},{"id":"post-api-v1-admin-domain-allows","text":"POST /api/v1/admin/domain_allows","level":2},{"id":"delete-api-v1-admin-domain-allows-id","text":"DELETE /api/v1/admin/domain_allows/{id}","level":2},{"id":"get-api-v1-admin-domain-blocks","text":"GET /api/v1/admin/domain_blocks","level":2},{"id":"post-api-v1-admin-domain-blocks","text":"POST /api/v1/admin/domain_blocks","level":2},{"id":"get-api-v1-admin-domain-blocks-id","text":"GET /api/v1/admin/domain_blocks/{id}","level":2},{"id":"put-api-v1-admin-domain-blocks-id","text":"PUT /api/v1/admin/domain_blocks/{id}","level":2},{"id":"delete-api-v1-admin-domain-blocks-id","text":"DELETE /api/v1/admin/domain_blocks/{id}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"admin-api-mastodon","manual":false,"prev":{"path":"/docs/api-reports","title":"Reports"},"next":{"path":"/docs/api-media","title":"Media"},"parent":"api-mastodon-compatible-api"},{"slug":"api-media","path":"/docs/api-media","title":"Media","description":"Auth: public, no-csrf (viewer required, write scope) · Parameters: Multipart: file (required, read from $_FILES['file']), description (the alt text), thumbnail (an image, for a video only)","group":"api","html":"<h2 id=\"post-api-v1-media\">POST /api/v1/media</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>Multipart: <code>file</code> (required, read from <code>$_FILES[&#39;file&#39;]</code>), <code>description</code> (the alt text), <code>thumbnail</code> (an image, for a video only)</p>\n<p>Stores an upload and returns the <code>MediaAttachment</code> (images get a resized preview and blurhash; video/audio are stored as-is with the media itself as <code>preview_url</code>). Refuses a mime type outside <code>CacheDocumentService::filterMimeTypes()</code> — images, video, audio and the document kinds in <code>DOCUMENT_MIME_TYPES</code> (PDF, text, Markdown, CSV, ZIP, EPUB, ODF, Office), which come back as <code>type: &quot;unknown&quot;</code> with no <code>preview_url</code> and, when no <code>description</code> was sent, the upload&#39;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 <code>upload_max_filesize</code> or the form&#39;s <code>MAX_FILE_SIZE</code> is a 422 naming the advertised limit for the declared type (<code>the file is larger than this server accepts (2 MB)</code>); an empty <code>$_FILES</code> under a <code>Content-Length</code> over <code>post_max_size</code> — PHP drops such a body whole — is the same 422 naming PHP&#39;s limit, not <code>no media found</code>; an interrupted upload is a 422 <code>the file upload was interrupted, try again</code>; no temporary directory, a failed disk write or an extension stopping the upload is a <strong>500</strong> naming the server problem, since nothing is wrong with the file. Each is logged at warning level with the PHP limits in force. <strong>Two ceilings</strong>: <code>max_size</code> (10 MB by default) for everything, and <code>max_video_size</code> (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 <em>client</em> 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 <strong>not</strong> public: <code>public</code> is set later, when a post attaches the media and that post is <code>public</code> or <code>unlisted</code>, and what it decides is whether a <em>shared</em> cache may keep the bytes — not whether <code>/media/{uuid}</code> will serve them, which it does for any uuid it is given. <code>focus</code> is accepted and not stored. <code>thumbnail</code> is Mastodon&#39;s field for a video&#39;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.</p>\n<h2 id=\"post-api-v2-media\">POST /api/v2/media</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong>Same as v1</p>\n<p>The same upload; modern clients POST v2 and only fall back to v1 on a 404.</p>\n<h2 id=\"post-api-v1-media-from-file\">POST /api/v1/media/from-file</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>the Nextcloud session only</strong>: the web app&#39;s with its CSRF token, or a Nextcloud app password over Basic with <code>OCS-APIRequest: true</code>; a bearer token is a <strong>403</strong> whatever its scopes) · <strong>Parameters: </strong>Body (JSON or form-encoded): <code>path</code> (required, relative to the viewer&#39;s own files), <code>description</code> (the alt text)</p>\n<p><strong>Nextcloud extension, not a Mastodon route.</strong> 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&#39;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&#39;s files does (<a href=\"/docs/api-authentication#which-credentials-a-route-takes\">Which credentials a route takes</a>) — the web app&#39;s file picker sends it with its session, and a client with a Nextcloud app password. The path is resolved inside the viewer&#39;s own user folder and nowhere else — a share they can read is fair game, a traversal is a 422 <code>no such file</code>, 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 <code>MediaAttachment</code>, 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 (<code>/api/v1/social/files_comments</code>). Rate-limited per user.</p>\n<h2 id=\"get-api-v1-media-nid\">GET /api/v1/media/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>nid</code> (path), <code>preview</code> (default <code>&#39;&#39;</code>, ignored)</p>\n<p>One of the viewer&#39;s own attachments, by the id the upload returned. 404 for an unknown id or someone else&#39;s attachment.</p>\n<h2 id=\"put-api-v1-media-nid\">PUT /api/v1/media/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>Body: <code>description</code>, <code>focus</code></p>\n<p>Updates the alt text or the focal point of the viewer&#39;s own upload and returns it. Only before it is posted: an upload one of the viewer&#39;s posts carries is a <strong>422</strong> that names <code>media_attributes</code> 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&#39;s attachment. Rate-limited to 30 a minute, the same ceiling the upload beside it carries.</p>\n<h2 id=\"get-media-uuid\">GET /media/{uuid}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>uuid</code> (path, may carry a <code>.ext</code> suffix); the request&#39;s own <code>Range</code> header is honoured</p>\n<p>Streams a cached document by UUID. Either of a document&#39;s copies resolves it — the full one that <code>url</code> names and the resized one that <code>preview_url</code> names. <strong>Range-capable</strong>: answers <code>Accept-Ranges: bytes</code> always, and a <code>Range</code> request with <code>206</code> and a <code>Content-Range</code> (a suffix range is the last N bytes, an open range runs to the end, one past the end is a <strong>416</strong> 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 <code>Content-Type</code> is the media type sniffed from the content at ingest, except for the <strong>resized copy of a video</strong>, which is its poster frame and is served as <code>image/jpeg</code> — a browser with <code>nosniff</code> on, which is every Nextcloud, refuses to draw an image served as <code>video/mp4</code>. The extension in the URL is ignored. <strong>Any local copy is served to whoever holds its uuid</strong>, public or not: the uuid is a v4 from <code>random_bytes()</code>, 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 <code>public</code>, as it once did, only meant a broken image under every followers-only and direct post carrying one. What <code>public</code> still decides is <strong>caching</strong>: the bytes may be kept for ever either way, but only a public row&#39;s may be kept by a <em>shared</em> cache, since a proxy in front of the instance would otherwise answer the same URL to anybody. <strong>404</strong> 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&#39;s pictures arrives as one anonymous address. It caps the unbounded case rather than controlling bandwidth, which belongs in front of the server.</p>\n<h2 id=\"get-media-stream-nid\">GET /media/stream/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>nid</code> (path); the request&#39;s own <code>Range</code> header is forwarded</p>\n<p><strong>Nextcloud extension, not a Mastodon route.</strong> A federated video, passed through from the instance that holds it — a PeerTube <code>Video</code> is referenced rather than mirrored (see <a href=\"/docs/architecture-peertube-and-federated-video#peertube-and-federated-video\">Architecture.md</a>), so there is no local copy to serve and the bytes come from the origin as they are played. The page cannot point a <code>&lt;video&gt;</code> at that origin directly: Nextcloud&#39;s content security policy says <code>media-src &#39;self&#39;</code>, 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 <strong>row id, not a URL</strong>, and only a <code>social_cache_doc</code> row this app itself wrote as streamed answers — anything with a local copy is served by <code>/media/{uuid}</code> and is a <strong>404</strong> here. Answers <code>206</code> with <code>Content-Range</code> when the caller sent a <code>Range</code> and the origin honoured it, <code>Accept-Ranges: bytes</code> either way; nothing is stored, in either direction. <strong>404</strong> for an unknown or non-streamed row, <strong>502</strong> when the origin cannot be reached.</p>\n<h2 id=\"get-media-playlist-nid\">GET /media/playlist/{nid}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>nid</code></p>\n<p><strong>An HLS playlist, with every URI in it pointed back through this server.</strong> A PeerTube transcoding to HLS — the default, and what a public instance federates — publishes a <code>.m3u8</code> 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 <em>relative to itself</em>, so handing one over verbatim would have every segment fetched straight from the origin — which is what <code>/media/stream/{nid}</code> exists to prevent, and worse, because it is one request per few seconds of video. Both plain URI lines and <code>URI=&quot;…&quot;</code> attributes (the encryption keys among them) are rewritten, because a player follows both. Read whole, up to 2 MB. 60 an hour anonymous.</p>\n<h2 id=\"get-media-playlist-nid-file\">GET /media/playlist/{nid}/file</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>nid</code>, <code>u</code> (the file&#39;s address)</p>\n<p>One file out of such a playlist — a segment, a key, or a nested playlist — fetched from the origin and streamed on with <code>Range</code> support. <strong><code>u</code> is not trusted</strong>: it has to be on the same host, scheme and port as the playlist <code>nid</code> names, which is the property <code>/media/stream/{nid}</code> has by taking a row id rather than a url, one level further in. Generous limits, because a film is hundreds of segments.</p>\n<h2 id=\"get-media-captions-nid-index-vtt\">GET /media/captions/{nid}/{index}.vtt</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>nid</code> (the status), <code>index</code> (the track&#39;s place in its <code>video.captions</code>)</p>\n<p><strong>Nextcloud extension, not a Mastodon route.</strong> One of a video&#39;s subtitle tracks, passed through from where it was published as <code>text/vtt</code>, stored nowhere — the address <code>video.captions[].url</code> carries. Keyed on the post and the track&#39;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 <code>WEBVTT</code>). <strong>404</strong> 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.</p>\n<h2 id=\"get-media-hls-uuid-master-m3u8\">GET /media/hls/{uuid}/master.m3u8</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>uuid</code> (path)</p>\n<p><strong>Nextcloud extension, not a Mastodon route.</strong> The master playlist of a <em>local</em> video&#39;s ladder: which sizes it exists at. Keyed on the <strong>uuid</strong>, the same handle <code>/media/{uuid}</code> 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&#39;s video findable by counting. <strong>404 when the video has no ladder</strong>, 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 <code>application/vnd.apple.mpegurl</code>. 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 <code>Content-Type</code>, but ffmpeg&#39;s HLS demuxer checks the <strong>extension</strong> of every segment URI and refuses one it does not recognise.</p>\n<h2 id=\"get-media-hls-uuid-height-index-m3u8\">GET /media/hls/{uuid}/{height}/index.m3u8</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>uuid</code>, <code>height</code> (path)</p>\n<p>One rung&#39;s playlist: where each segment is inside that rung&#39;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. <strong>404</strong> for a height this video has no rung at.</p>\n<h2 id=\"get-media-hls-uuid-height-video-mp4\">GET /media/hls/{uuid}/{height}/video.mp4</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>uuid</code>, <code>height</code> (path); the request&#39;s own <code>Range</code> header is honoured</p>\n<p>One rung&#39;s fragmented MP4, whole, with ranges. Every segment of a rung is a byte range into this one file (<code>-hls_flags single_file</code>), so a player watching a ten-minute video asks this a few hundred times with a different <code>Range</code> each time — hence the generous limits. Cached on the same terms as the video itself: for ever in the reader&#39;s own cache, and in a shared one only where the post is public.</p>\n<h2 id=\"post-api-v1-statuses-nid-watched\">POST /api/v1/statuses/{nid}/watched</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>position</code>, <code>duration</code> (seconds)</p>\n<p><strong>Remembers where the reader got to in a video.</strong> A two-hour talk watched in three sittings is three sittings of finding the place again. A fact about the <em>reader</em>: never federated, never shown to anybody else, never counted into anything, one row per (post, viewer). A video watched to past 95% is <strong>forgotten</strong> rather than bookmarked at the credits, because a &quot;continue watching&quot; row that offers back a finished video is one nobody presses twice. Answers <code>{&quot;stored&quot;: bool}</code>: <code>false</code> 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.</p>\n<h2 id=\"delete-api-v1-statuses-nid-watched\">DELETE /api/v1/statuses/{nid}/watched</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>nid</code></p>\n<p>Takes a video off the reader&#39;s own list.</p>\n<h2 id=\"post-api-v1-statuses-nid-view\">POST /api/v1/statuses/{nid}/view</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>nid</code></p>\n<p><strong>Counts a view of a video posted here</strong>, which is what <code>video_card.views</code> 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&#39;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 (<code>VideoViewService</code>). Answers <code>{&quot;counted&quot;: bool}</code>, which is nothing to act on: a view not counted is not an error. A post the caller may not see is a <strong>404</strong>. 60 an hour anonymous, 600 for an account.</p>\n<h2 id=\"get-api-v1-videos-continue\">GET /api/v1/videos/continue</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong><code>limit</code> (20, max 40)</p>\n<p>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 <code>watch_progress</code>, where the reader stopped in it.</p>\n<p><code>POST /api/v1/media</code> and <code>POST /api/v2/media</code> are both served by <code>MediaApiController::mediaNew()</code>, and it and <code>mediaFromFile()</code> share the storing half (<code>storeAttachment()</code>) 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&#39;s alt text travels as the ActivityPub <code>name</code>, both incoming and outgoing.</p>\n<p>Every key of a <code>MediaAttachment</code> is always present, <code>null</code> when there is nothing to put in it (<code>url</code>, <code>preview_url</code>, <code>remote_url</code>, <code>meta</code>, <code>description</code>, <code>blurhash</code>). <code>meta</code> is an object, never a list.</p>\n<p><code>url</code> is <code>null</code> where this instance holds no copy of the file — the cache refused it, or has not fetched it yet. It used to name <code>/media/</code> with an empty id in it, which 404s for every client that follows it and is indistinguishable from an attachment that is merely slow. <code>remote_url</code> still says where the file came from and <code>cache_error</code> why there is no copy (<code>1</code> size, <code>2</code> type, <code>3</code> unreachable, <code>4</code> unreadable), which is what a reader is shown. The origin is deliberately <strong>not</strong> offered as a fallback: loading it in the reader&#39;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 <code>Document</code> 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.</p>\n<p><code>hls_url</code> is a key of this app&#39;s own, alongside Mastodon&#39;s. Where an\nadministrator has turned the ladder on (<code>video_ladder</code>) and the background job\nhas been over a video, it is the address of that video&#39;s master playlist — the\nsame video at two or three sizes, so a player can pick the one that fits the\nconnection. <code>null</code> everywhere else, which is every video on an instance that has\nnot turned it on, and a client that does not know the key plays <code>url</code> and gets\nthe same video at one size. It is not a <em>replacement</em> for <code>url</code>: the whole file\nis always there beside it, and the bundled player falls back to it if the ladder\ncannot be loaded.</p>\n","toc":[{"id":"post-api-v1-media","text":"POST /api/v1/media","level":2},{"id":"post-api-v2-media","text":"POST /api/v2/media","level":2},{"id":"post-api-v1-media-from-file","text":"POST /api/v1/media/from-file","level":2},{"id":"get-api-v1-media-nid","text":"GET /api/v1/media/{nid}","level":2},{"id":"put-api-v1-media-nid","text":"PUT /api/v1/media/{nid}","level":2},{"id":"get-media-uuid","text":"GET /media/{uuid}","level":2},{"id":"get-media-stream-nid","text":"GET /media/stream/{nid}","level":2},{"id":"get-media-playlist-nid","text":"GET /media/playlist/{nid}","level":2},{"id":"get-media-playlist-nid-file","text":"GET /media/playlist/{nid}/file","level":2},{"id":"get-media-captions-nid-index-vtt","text":"GET /media/captions/{nid}/{index}.vtt","level":2},{"id":"get-media-hls-uuid-master-m3u8","text":"GET /media/hls/{uuid}/master.m3u8","level":2},{"id":"get-media-hls-uuid-height-index-m3u8","text":"GET /media/hls/{uuid}/{height}/index.m3u8","level":2},{"id":"get-media-hls-uuid-height-video-mp4","text":"GET /media/hls/{uuid}/{height}/video.mp4","level":2},{"id":"post-api-v1-statuses-nid-watched","text":"POST /api/v1/statuses/{nid}/watched","level":2},{"id":"delete-api-v1-statuses-nid-watched","text":"DELETE /api/v1/statuses/{nid}/watched","level":2},{"id":"post-api-v1-statuses-nid-view","text":"POST /api/v1/statuses/{nid}/view","level":2},{"id":"get-api-v1-videos-continue","text":"GET /api/v1/videos/continue","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"media","manual":false,"prev":{"path":"/docs/api-admin-api-mastodon","title":"Admin API (Mastodon)"},"next":{"path":"/docs/api-search-mastodon-adjacent-app-specific-shapes","title":"Search (Mastodon-adjacent, app-specific shapes)"},"parent":"api-mastodon-compatible-api"},{"slug":"api-search-mastodon-adjacent-app-specific-shapes","path":"/docs/api-search-mastodon-adjacent-app-specific-shapes","title":"Search (Mastodon-adjacent, app-specific shapes)","description":"{\"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…","group":"api","html":"<h2 id=\"get-api-v1-global-accounts-search\">GET /api/v1/global/accounts/search</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>search</code> (required)</p>\n<p><code>{&quot;result&quot;: {&quot;accounts&quot;: [...], &quot;exact&quot;: &lt;account or null&gt;}, &quot;status&quot;: 1}</code>, each a Mastodon <code>Account</code> entity (a remote bio sanitised, no copy of the cached actor document). A leading <code>@</code> is stripped; an empty query returns empty lists. Nothing is fetched from another server for <code>exact</code>. A dotted name also gets the accounts Bluesky&#39;s typeahead finds; one not stored here is offered as the AppView described it, with id <code>0</code>, and is stored once it is mentioned, opened or followed. The typeahead&#39;s answer to a query is reused for a minute.</p>\n<h2 id=\"get-api-v1-global-tags-search\">GET /api/v1/global/tags/search</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>search</code> (required)</p>\n<p><code>{&quot;result&quot;: {&quot;tags&quot;: [...], &quot;exact&quot;: &lt;tag or null&gt;}, &quot;status&quot;: 1}</code>. A leading <code>#</code> is stripped.</p>\n","toc":[{"id":"get-api-v1-global-accounts-search","text":"GET /api/v1/global/accounts/search","level":2},{"id":"get-api-v1-global-tags-search","text":"GET /api/v1/global/tags/search","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"search-mastodon-adjacent-app-specific-shapes","manual":false,"prev":{"path":"/docs/api-media","title":"Media"},"next":{"path":"/docs/api-pagination","title":"Pagination"},"parent":"api-mastodon-compatible-api"},{"slug":"api-pagination","path":"/docs/api-pagination","title":"Pagination","description":"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…","group":"api","html":"<p>Client API list endpoints accept the cursor parameters shown per route above (<code>limit</code>, <code>max_id</code>, <code>min_id</code>, and either <code>since_id</code> or <code>since</code>), all integers defaulting to <code>0</code> except <code>limit</code> (20 — 40 on <code>/api/v1/blocks</code> and <code>/api/v1/mutes</code> — capped at 50).</p>\n<p>Every paged client API route except <code>/api/v1/blocks</code>, <code>/api/v1/mutes</code> and <code>/api/v1/scheduled_statuses</code> also sends a <code>Link</code> header in Mastodon&#39;s form, which is the only cursor masto.js — and therefore Elk and Phanpy — reads:</p>\n<pre><code>Link: &lt;https://cloud.example/index.php/apps/social/api/v1/timelines/home?limit=20&amp;max_id=41&gt;; rel=&quot;next&quot;,\n      &lt;https://cloud.example/index.php/apps/social/api/v1/timelines/home?limit=20&amp;min_id=60&gt;; rel=&quot;prev&quot;\n</code></pre>\n<p><code>next</code> points below the lowest id on the page and is sent only while a further page may exist (a page shorter than <code>limit</code> is the last one); <code>prev</code> 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 <code>/api/v1/timelines/{timeline}/</code>, <code>/api/v1/timelines/tag/{hashtag}</code>, <code>/api/v1/notifications</code>, <code>/api/v1/favourites/</code>, <code>/api/v1/bookmarks</code>, <code>/api/v1/followed_tags</code>, <code>/api/v1/accounts/{account}/statuses</code>, <code>/api/v1/accounts/{account}/followers</code> and <code>/api/v1/accounts/{account}/following</code>. <code>/api/v1/followed_tags</code> takes no <code>since_id</code> 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&#39;s network lists carries only <code>next</code>, pointing after its last account. <code>/api/v1/blocks</code> and <code>/api/v1/mutes</code> send none because they take no cursor to page with, and <code>/api/v1/scheduled_statuses</code> sends none because a ScheduledStatus carries no status nid for the header to point at.</p>\n<p>&quot;A page shorter than <code>limit</code> is the last one&quot; is decided on what the <em>query</em> returned, not on what survived any filtering the controller then did. <code>/api/v1/notifications</code> 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.</p>\n<p><code>LocalController</code> stream endpoints use a different pair: <code>since</code> (a numeric cursor, default <code>0</code>) and <code>limit</code> (default <strong>5</strong>, not 20), and send no <code>Link</code> header.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"pagination","manual":false,"prev":{"path":"/docs/api-search-mastodon-adjacent-app-specific-shapes","title":"Search (Mastodon-adjacent, app-specific shapes)"},"next":{"path":"/docs/api-peertubes-own-routes","title":"PeerTube's own routes"},"parent":"api-mastodon-compatible-api"},{"slug":"api-peertubes-own-routes","path":"/docs/api-peertubes-own-routes","title":"PeerTube's own routes","description":"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…","group":"api","html":"<p>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&#39;s API is <strong>not</strong> Mastodon&#39;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 <code>PeerTubeApiService</code>.</p>\n<p><strong>Read the two caveats before judging this by what is missing.</strong></p>\n<p>It is <strong>read-only</strong>. PeerTube&#39;s upload is a resumable protocol with a transcoding state machine behind it, and a half-built one that took somebody&#39;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.</p>\n<p>And it is <strong>gated on the domain root</strong>. No PeerTube client will ask under <code>/apps/social/</code>: they all build <code>https://&lt;host&gt;/api/v1/…</code> from the address a person types. Every route here is correct and <strong>none of them is reachable by a real client</strong> until this instance answers at its own root, which is item 1 of <a href=\"/docs/mastodon\">Mastodon-Compatibility.md</a> and a decision for whoever runs the server rather than something this app can do to a Nextcloud. Until then these serve <code>curl</code>, the interop harness, and anybody willing to configure a rewrite.</p>\n<p>Every list answers PeerTube&#39;s <code>{total, data}</code>. <strong><code>total</code> is the size of this page</strong>, not of everything there is: this app&#39;s timelines are keyed on a cursor and have no count to give, and a number invented for the shape&#39;s sake is one a client would draw a pager from.</p>\n<h2 id=\"get-api-v1-config\">GET /api/v1/config</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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 <strong>true here</strong> rather than PeerTube&#39;s default: <code>signup.allowed</code> is <code>false</code> (an account here is a Nextcloud account and is not made through this API), the import and upload switches are <code>false</code> (nothing here writes), <code>transcoding.hls</code> and <code>enabledResolutions</code> are the real state of <code>video_ladder</code>, and <code>user.videoQuota</code> is the real <code>video_quota</code> in <strong>bytes</strong> with <code>-1</code> for no quota, which is PeerTube&#39;s own way of saying it. <code>instance.defaultNSFWPolicy</code> is this instance&#39;s <code>nsfw_policy</code> translated back into PeerTube&#39;s three words (<code>display</code>, <code>blur</code>, <code>do_not_list</code>). <code>serverVersion</code> is the PeerTube version whose API this answers; a <code>software</code> object beside it says what is <strong>actually</strong> running, so a client that reports a version to its user is not told this server runs PeerTube.</p>\n<h2 id=\"get-api-v1-oauth-clients-local\">GET /api/v1/oauth-clients/local</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The client id and secret to log in with. PeerTube hands out <strong>one pair per instance</strong>, the same one to everybody for ever; this app mints a pair per client and <strong>hashes the secret</strong>, deliberately and as a fix to a real problem, so there is no stored plaintext to hand back a second time. A <strong>fresh registration</strong> 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 <code>/api/v1/apps</code>. Registered with the out-of-band redirect urn and <code>read write follow</code>. 10 an hour.</p>\n<h2 id=\"get-api-v1-videos\">GET /api/v1/videos</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>start</code> (default 0), <code>count</code> (default 20, max 100)</p>\n<p>The videos this instance has, newest first: the public timeline narrowed with the same <code>only_video</code> the app&#39;s own Videos timeline uses, so the two cannot come to disagree about what a video is. <strong>Paging is by cursor here and by offset there</strong>, so <code>start</code> 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.</p>\n<h2 id=\"get-api-v1-videos-id\">GET /api/v1/videos/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>id</code> (<strong>numeric only</strong>)</p>\n<p>One video, with its description, tags, support line, files and streaming playlist. <strong>Not addressable by uuid</strong>, although the listing carries one: that uuid is derived from the post&#39;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 <code>\\d+</code> requirement is also what keeps this from swallowing <code>/api/v1/videos/continue</code>, this app&#39;s own &quot;continue watching&quot; route at the same depth.</p>\n<h2 id=\"get-api-v1-videos-id-comment-threads\">GET /api/v1/videos/{id}/comment-threads</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>id</code> (numeric), <code>count</code> (default 20, max 100)</p>\n<p>The replies to one video, out of the same thread the app&#39;s own status context is drawn from — so a reply a client sees here is one the web page shows too. <code>totalReplies</code> on each is <code>0</code> 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.</p>\n<h2 id=\"get-api-v1-video-channels\">GET /api/v1/video-channels</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>count</code> (default 20, max 100)</p>\n<p>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.</p>\n<h2 id=\"get-api-v1-video-channels-handle\">GET /api/v1/video-channels/{handle}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>handle</code> (<code>alice_channel</code>, or <code>alice_channel@host</code> — the host half is dropped)</p>\n<p>One channel with its description, owner and follower count. A handle is an actor&#39;s <code>preferredUsername</code> 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 <strong>not a channel</strong>, rather than a channel nobody can find. 404 otherwise.</p>\n<h2 id=\"get-api-v1-users-me\">GET /api/v1/users/me</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required) · <strong>Parameters: </strong>—</p>\n<p>The signed-in account as PeerTube&#39;s <code>User</code>, with its channels, its NSFW policy (in PeerTube&#39;s words) and its video quota and usage in bytes. <strong>The email is <code>null</code></strong>: PeerTube&#39;s own answer carries one, and a Nextcloud account&#39;s address is not this API&#39;s to hand to whatever client holds a token — nothing a video client does needs it, and an absent field reads as &quot;this server does not say&quot; rather than as a wrong address. 401 without credentials.</p>\n<h2 id=\"get-api-v1-search-videos\">GET /api/v1/search/videos</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>search</code>, <code>count</code> (default 20, max 100)</p>\n<p>Videos matching a word, from the same <code>SearchService</code> 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 <code>search</code> is an empty page rather than everything.</p>\n<p>Ids: a video&#39;s <code>id</code> is the post&#39;s <code>nid</code>, which is what this app&#39;s own API gives a client; its <code>uuid</code> and <code>shortUUID</code> are both the uuid <code>PeerTubeService::uuidFor()</code> mints and already publishes on the wire, so a video seen through this API and the same video seen over ActivityPub carry <strong>one</strong> uuid rather than two nothing can tell apart. <code>category</code>, <code>licence</code> and <code>language</code> are <code>{id: 0, label}</code>: PeerTube&#39;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.</p>\n<hr>\n<hr>\n","toc":[{"id":"get-api-v1-config","text":"GET /api/v1/config","level":2},{"id":"get-api-v1-oauth-clients-local","text":"GET /api/v1/oauth-clients/local","level":2},{"id":"get-api-v1-videos","text":"GET /api/v1/videos","level":2},{"id":"get-api-v1-videos-id","text":"GET /api/v1/videos/{id}","level":2},{"id":"get-api-v1-videos-id-comment-threads","text":"GET /api/v1/videos/{id}/comment-threads","level":2},{"id":"get-api-v1-video-channels","text":"GET /api/v1/video-channels","level":2},{"id":"get-api-v1-video-channels-handle","text":"GET /api/v1/video-channels/{handle}","level":2},{"id":"get-api-v1-users-me","text":"GET /api/v1/users/me","level":2},{"id":"get-api-v1-search-videos","text":"GET /api/v1/search/videos","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"peertubes-own-routes","manual":false,"prev":{"path":"/docs/api-pagination","title":"Pagination"},"next":{"path":"/docs/api-custom-local-api","title":"Custom Local API"},"parent":"api-mastodon-compatible-api"},{"slug":"api-custom-local-api","path":"/docs/api-custom-local-api","title":"Custom Local API","description":"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…","group":"api","html":"<p>These endpoints exist to serve the app&#39;s own Vue frontend. They are session-authenticated only, mostly wrap their payload in the <code>{&quot;result&quot;: …, &quot;status&quot;: 1}</code> envelope, and are not part of any Mastodon client contract.</p>\n<p>A failure on the routes of <code>LocalController</code>, <code>NavigationController</code> and <code>OStatusController</code> answers <code>{&quot;status&quot;: -1, &quot;error&quot;: &quot;request failed&quot;}</code> with a status that says whose failure it is: <strong>404</strong> for a post, account or document that does not exist, <strong>422</strong> for a request that cannot be carried out as asked (somebody else&#39;s post, a malformed handle, following yourself), <strong>403</strong> where another instance&#39;s policy refuses it, <strong>429</strong> over the follow limit and <strong>502</strong> when another server could not be reached or answered nonsense. Only what is left, a failure of this server&#39;s own, is a <strong>500</strong>, and only that is logged.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":[{"path":"/docs/api-posts","title":"Posts","description":"Auth: user · Parameters: content (''), to (array), type (default public), replyTo (''), attachments (mixed, default []), hashtags (array), poll (object, optional), spoilerText ('', the…","parent":true},{"path":"/docs/api-current-user","title":"Current user","description":"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.…","parent":true},{"path":"/docs/api-account-info","title":"Account info","description":"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…","parent":true},{"path":"/docs/api-banner","title":"Banner","description":"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…","parent":true},{"path":"/docs/api-migration","title":"Migration","description":"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…","parent":true},{"path":"/docs/api-channels","title":"Channels","description":"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\"…","parent":true},{"path":"/docs/api-posts-held-for-review","title":"Posts held for review","description":"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…","parent":true},{"path":"/docs/api-statistics","title":"Statistics","description":"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…","parent":true},{"path":"/docs/api-pixelfeds-administration-routes","title":"Pixelfed's administration routes","description":"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…","parent":true},{"path":"/docs/api-config-and-system","title":"Config and system","description":"{\"result\": {\"version\": \"<installed_version>\", \"setup\": <bool>}, \"status\": 1}.","parent":true},{"path":"/docs/api-moderation-moderators-only","title":"Moderation (moderators only)","description":"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)…","parent":true},{"path":"/docs/api-external-users","title":"External users","description":"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…","parent":true}],"anchor":"custom-local-api","manual":false,"prev":{"path":"/docs/api-peertubes-own-routes","title":"PeerTube's own routes"},"next":{"path":"/docs/api-posts","title":"Posts"},"parent":null},{"slug":"api-posts","path":"/docs/api-posts","title":"Posts","description":"Auth: user · Parameters: content (''), to (array), type (default public), replyTo (''), attachments (mixed, default []), hashtags (array), poll (object, optional), spoilerText ('', the…","group":"api","html":"<h2 id=\"post-api-v1-post\">POST /api/v1/post</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>content</code> (<code>&#39;&#39;</code>), <code>to</code> (array), <code>type</code> (default <code>public</code>), <code>replyTo</code> (<code>&#39;&#39;</code>), <code>attachments</code> (mixed, default <code>[]</code>), <code>hashtags</code> (array), <code>poll</code> (object, optional), <code>spoilerText</code> (<code>&#39;&#39;</code>, the content warning)</p>\n<p>Creates a post. A <code>replyTo</code> naming a post the writer may not read is a <strong>404</strong>, as one naming nothing is. Returns <code>{&quot;result&quot;: {&quot;post&quot;: &lt;object&gt;, &quot;token&quot;: &quot;&lt;request token&gt;&quot;}, &quot;status&quot;: 1}</code>.</p>\n<h2 id=\"delete-api-v1-post\">DELETE /api/v1/post</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>Deletes an own post; <code>{&quot;result&quot;: [], &quot;status&quot;: 1}</code>. An unknown id is a <strong>404</strong>, a post not attributed to the caller a <strong>422</strong>.</p>\n<p>Boosting from a client goes through <code>POST /api/v1/statuses/{nid}/{act}</code> with <code>reblog</code>.</p>\n","toc":[{"id":"post-api-v1-post","text":"POST /api/v1/post","level":2},{"id":"delete-api-v1-post","text":"DELETE /api/v1/post","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"posts","manual":false,"prev":{"path":"/docs/api-custom-local-api","title":"Custom Local API"},"next":{"path":"/docs/api-current-user","title":"Current user"},"parent":"api-custom-local-api"},{"slug":"api-current-user","path":"/docs/api-current-user","title":"Current user","description":"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.…","group":"api","html":"<h2 id=\"put-api-v1-account-profile-layout\">PUT /api/v1/account/profile-layout</h2>\n<p><strong>Auth: </strong>user, CSRF · <strong>Parameters: </strong><code>layout</code>: <code>{default_tab, tabs}</code></p>\n<p>Saves the personal account&#39;s public profile presentation. Defaults: <code>posts</code>, all five tabs. The default can be <code>posts</code>, <code>photos</code> or <code>videos</code> and must remain visible; Posts cannot be hidden. Invalid values are rejected. Returns <code>{&quot;status&quot;: 1, &quot;result&quot;: {&quot;layout&quot;: {...}}}</code>. Does not change post audiences or grant access.</p>\n<h2 id=\"put-api-v1-account-fields\">PUT /api/v1/account/fields</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>fields</code> (list of <code>{name, value}</code>)</p>\n<p>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 <code>PropertyValue</code> 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. <code>{&quot;result&quot;: {&quot;account&quot;: &lt;Person&gt;}, &quot;status&quot;: 1}</code>.</p>\n<h2 id=\"put-api-v1-current-follow\">PUT /api/v1/current/follow</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>account</code> (required)</p>\n<p>Follows an account; <code>{&quot;result&quot;: [], &quot;status&quot;: 1}</code>.</p>\n<h2 id=\"post-api-v1-account-create\">POST /api/v1/account/create</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>username</code> (the handle; empty takes the one derived from the user id)</p>\n<p>Creates the reader&#39;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 (<code>AccountService::assertHandleAvailable()</code>: the pattern, not another Nextcloud user&#39;s id, not a handle an actor holds); a refused handle is a <strong>422</strong> whose <code>error</code> says why. <code>{&quot;result&quot;: {&quot;account&quot;: &lt;Account&gt;}, &quot;status&quot;: 1}</code>.</p>\n<h2 id=\"post-api-v1-account-link\">POST /api/v1/account/link</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>handle</code> (<code>user@server.example</code>, a leading <code>@</code> is fine)</p>\n<p>Writes an account the reader already has elsewhere into the <code>fediverse</code> field of their Nextcloud profile, where Discover&#39;s colleague suggestions read it, and creates nothing here. An address on this server, or anything that is not <code>user@host</code>, is a <strong>422</strong> with the reason. <code>{&quot;result&quot;: {&quot;handle&quot;: &quot;…&quot;}, &quot;status&quot;: 1}</code>.</p>\n<h2 id=\"post-api-v1-account-delete\">POST /api/v1/account/delete</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>confirm</code> (required: the handle being deleted, with or without a leading <code>@</code>, either <code>name</code> or <code>name@host</code>, case-insensitive)</p>\n<p><strong>Deletes the caller&#39;s own Aloha Social account</strong>, and only theirs. The same deletion <code>occ social:account:delete</code> performs: the posts go, the follows go, and a <code>Delete</code> 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 <strong>not</strong> a password: an account signed in through SSO has none to give. A confirmation that does not name this account is a <strong>422</strong> whose message says what to type. The handle is held for the retention hour (<code>AccountService::TIME_RETENTION</code>) so nobody else can take it at once; a new account under a different handle can be created straight away, because <code>ActorsRequest::getFromUserId()</code> skips deleted rows. Every app signed in to the account is signed out with it, because <code>verify_credentials</code> creates an actor for a user who has none and a phone left running would otherwise re-make the account a minute later. <strong>It cannot be undone.</strong> Rate-limited to 3 an hour. The channels the account runs are deleted with it, each as an account of its own.</p>\n<h2 id=\"post-api-v1-introduction-dismiss\">POST /api/v1/introduction/dismiss</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong>—</p>\n<p>Records that the signed-in reader has completed or skipped the first-run introduction.</p>\n<h2 id=\"delete-api-v1-current-follow\">DELETE /api/v1/current/follow</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>account</code> (required)</p>\n<p>Unfollows an account; <code>{&quot;result&quot;: [], &quot;status&quot;: 1}</code>.</p>\n<h2 id=\"get-api-v1-social-moderation-lists\">GET /api/v1/social/moderation_lists</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The shared lists of accounts to mute or block that the viewer subscribes to, each <code>uri</code>, <code>name</code>, <code>kind</code> (<code>mute</code> or <code>block</code>) and <code>accounts</code>: how many accounts the list mutes or blocks here, not counting the ones the viewer had muted or blocked already. Today these are Bluesky&#39;s moderation lists, the one network that publishes them; a subscriber reads one list whichever network its members are on.</p>\n<h2 id=\"post-api-v1-social-moderation-lists\">POST /api/v1/social/moderation_lists</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>url</code> (required: the list&#39;s bsky.app link, <code>https://bsky.app/profile/&lt;handle or did&gt;/lists/&lt;rkey&gt;</code>, or its <code>at://</code> URI), <code>kind</code> (<code>mute</code>, the default, or <code>block</code>)</p>\n<p>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 (<code>Cron\\ModerationLists</code>). A mute list is also muted at the AppView (<code>app.bsky.graph.muteActorList</code>), so a Bluesky app signed in here hides the same accounts. A block list is published as an <code>app.bsky.graph.listblock</code> 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 <code>kind</code> or a 21st list is a <strong>422</strong>.</p>\n<h2 id=\"delete-api-v1-social-moderation-lists\">DELETE /api/v1/social/moderation_lists</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>uri</code> (required)</p>\n<p>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 <code>listblock</code> record goes too. Answers the remaining lists.</p>\n","toc":[{"id":"put-api-v1-account-profile-layout","text":"PUT /api/v1/account/profile-layout","level":2},{"id":"put-api-v1-account-fields","text":"PUT /api/v1/account/fields","level":2},{"id":"put-api-v1-current-follow","text":"PUT /api/v1/current/follow","level":2},{"id":"post-api-v1-account-create","text":"POST /api/v1/account/create","level":2},{"id":"post-api-v1-account-link","text":"POST /api/v1/account/link","level":2},{"id":"post-api-v1-account-delete","text":"POST /api/v1/account/delete","level":2},{"id":"post-api-v1-introduction-dismiss","text":"POST /api/v1/introduction/dismiss","level":2},{"id":"delete-api-v1-current-follow","text":"DELETE /api/v1/current/follow","level":2},{"id":"get-api-v1-social-moderation-lists","text":"GET /api/v1/social/moderation_lists","level":2},{"id":"post-api-v1-social-moderation-lists","text":"POST /api/v1/social/moderation_lists","level":2},{"id":"delete-api-v1-social-moderation-lists","text":"DELETE /api/v1/social/moderation_lists","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"current-user","manual":false,"prev":{"path":"/docs/api-posts","title":"Posts"},"next":{"path":"/docs/api-account-info","title":"Account info"},"parent":"api-custom-local-api"},{"slug":"api-account-info","path":"/docs/api-account-info","title":"Account info","description":"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…","group":"api","html":"<h2 id=\"get-api-v1-account-username-info\">GET /api/v1/account/{username}/info</h2>\n<p><strong>Auth: </strong>user, public · <strong>Parameters: </strong>—</p>\n<p>Local account with complete details, returned <strong>unwrapped</strong> as a <code>Person</code>; 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&#39;s ceiling below, but bounded: a name that is held here and a name that is not answer differently.</p>\n<h2 id=\"get-api-v1-global-account-info\">GET /api/v1/global/account/info</h2>\n<p><strong>Auth: </strong>user, public · <strong>Parameters: </strong><code>account</code> (required, e.g. <code>user</code> or <code>user@domain</code>)</p>\n<p>Local or remote account, returned <strong>unwrapped</strong>. A leading <code>@</code> is stripped; remote accounts get follower/following/post counts fetched. <strong>No actor is created here</strong>, not even the viewer&#39;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 (<code>POST /api/v1/account/create</code>) and <code>occ social:account:create</code>. 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&#39;s session, so other servers are asked — an unknown account resolved, a remote account&#39;s counts fetched — only for a request that passes the CSRF check (the web app&#39;s, which sends its request token, on a public page too) or carries <code>Authorization: Bearer</code>; any other request is answered from what this server holds, and an account it does not hold is a 404.</p>\n<h2 id=\"get-api-v1-global-actor-avatar\">GET /api/v1/global/actor/avatar</h2>\n<p><strong>Auth: </strong>user, public, no-csrf · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>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 <code>/media/{uuid}</code> carries, generous because a timeline draws dozens at once.</p>\n<h2 id=\"get-avatar-username-size\">GET /avatar/{username}/{size}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>username</code> (path), <code>size</code> (path, digits; at most 64 is the small picture, anything larger the large one, as Nextcloud&#39;s own route rounds it), <code>v</code> (the version, ignored but part of the address)</p>\n<p>The avatar of a local account by its username: the icon of its actor and the <code>avatar</code> of its Account entity. Serves what Nextcloud&#39;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&#39;s scope keeps the picture off the actor. Cached for a day, privately and <code>immutable</code>, 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 <code>/media/{uuid}</code>.</p>\n<p>The followers and following lists of an arbitrary account are reachable through the Mastodon-compatible <code>/api/v1/accounts/{account}/followers</code> and <code>/api/v1/accounts/{account}/following</code>.</p>\n","toc":[{"id":"get-api-v1-account-username-info","text":"GET /api/v1/account/{username}/info","level":2},{"id":"get-api-v1-global-account-info","text":"GET /api/v1/global/account/info","level":2},{"id":"get-api-v1-global-actor-avatar","text":"GET /api/v1/global/actor/avatar","level":2},{"id":"get-avatar-username-size","text":"GET /avatar/{username}/{size}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"account-info","manual":false,"prev":{"path":"/docs/api-current-user","title":"Current user"},"next":{"path":"/docs/api-banner","title":"Banner"},"parent":"api-custom-local-api"},{"slug":"api-banner","path":"/docs/api-banner","title":"Banner","description":"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…","group":"api","html":"<h2 id=\"post-api-v1-banner\">POST /api/v1/banner</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>)</p>\n<p>Stores the upload as the current user&#39;s header image, updates the actor cache and federates an Update. Returns <code>{&quot;result&quot;: {&quot;url&quot;, &quot;id&quot;}, &quot;status&quot;: 1}</code>. A file that is not a readable image, is of a refused type, or is over the ceiling is a <strong>400</strong>: 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.</p>\n<h2 id=\"post-api-v1-banner-url\">POST /api/v1/banner/url</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong><code>url</code> (string, default <code>&#39;&#39;</code>, required in practice)</p>\n<p>Downloads the image at the given <code>url</code> with cURL (follows up to 5 redirects, 30 s timeout, user agent <code>Nextcloud-Social/0.10</code>) and stores it as the current user&#39;s header image. Same response shape. An empty <code>url</code>, or a non-2xx response, fails.</p>\n","toc":[{"id":"post-api-v1-banner","text":"POST /api/v1/banner","level":2},{"id":"post-api-v1-banner-url","text":"POST /api/v1/banner/url","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"banner","manual":false,"prev":{"path":"/docs/api-account-info","title":"Account info"},"next":{"path":"/docs/api-migration","title":"Migration"},"parent":"api-custom-local-api"},{"slug":"api-migration","path":"/docs/api-migration","title":"Migration","description":"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…","group":"api","html":"<p>The Migration page&#39;s three buttons: take a copy of the account&#39;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 <code>read</code> — 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 <code>write</code>. Moving away and undoing it, the move-in callback, the aliases and the switch wizard&#39;s helpers stay session routes with CSRF: the move is behind Nextcloud&#39;s password confirmation, which a token cannot give.</p>\n<p>Every error answer of these routes is <code>{&quot;error&quot;: &quot;…&quot;, &quot;code&quot;: &quot;&lt;slug&gt;&quot;}</code>: the code is stable and the page explains it in the person&#39;s language, with what they can do next (<code>src/utils/serverError.js</code>); the English sentence is for logs and older clients, and the page keeps it behind <em>Details</em>. Anything that is not one of the refusals in <a href=\"#migration-error-codes\">Migration error codes</a> is logged and answered <strong>500</strong> <code>server-error</code> with the fixed sentence <code>Something went wrong on this server</code>, never with the exception&#39;s own message. A token the route does not accept is answered as on the Mastodon routes.</p>\n<h2 id=\"get-api-v1-migration-export\">GET /api/v1/migration/export</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The account&#39;s Aloha Social data as a zip: <code>social/actor.json</code>, <code>social/following_accounts.csv</code>, <code>social/followers.csv</code>, <code>social/blocked_accounts.csv</code>, <code>social/muted_accounts.csv</code>, <code>social/lists.csv</code>, <code>social/blocked_domains.csv</code>, <code>social/bookmarks.csv</code>, <code>social/likes.csv</code>, <code>social/outbox.json</code>, the Bluesky account under <code>social/bluesky/</code> where the account has one hosted here (see <code>GET /api/v1/social/bluesky/archive</code>), plus a <code>social/export.json</code> manifest naming the app version, the account and the migrator version. Written by the same <code>SocialMigrator</code> Nextcloud&#39;s whole-account export uses, so the two archives hold the same files at the same paths. The <strong>private key is never in it</strong> — see the class comment on <code>SocialMigrator</code> — so an archive cannot be used to sign as the account it came from. Downloads as <code>social-&lt;uid&gt;-&lt;date&gt;.zip</code>. Rate-limited to 6 an hour.</p>\n<h2 id=\"post-api-v1-migration-import\">POST /api/v1/migration/import</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>, ≤ 100 MB)</p>\n<p>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 <code>/api/v1/migration/lists</code>), the blocked domains, the bookmarks and the favourites. <strong>Additive</strong> — nothing is deleted, and the posts in <code>outbox.json</code> are reported rather than re-published. An archive with no <code>social/actor.json</code> is a <strong>400</strong> <code>archive-not-social</code>, a file that is not a zip <strong>400</strong> <code>archive-unreadable</code>. Returns <code>{&quot;imported&quot;: true, &quot;log&quot;: [...]}</code>, the migrator&#39;s own account of what it did. Rate-limited to 6 an hour.</p>\n<h2 id=\"post-api-v1-migration-follows\">POST /api/v1/migration/follows</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>)</p>\n<p><strong>Queued</strong> (see <code>/api/v1/migration/imports</code>): the upload is kept and the import runs in the background; answers <strong>202</strong> with <code>{&quot;import&quot;: {...}}</code> as queued, <strong>409</strong> while one of this kind is still running, <strong>413</strong> over 100 MB. 30 an hour. A follows export — Mastodon&#39;s, GoToSocial&#39;s or Akkoma&#39;s <code>following_accounts.csv</code>, <strong>Pixelfed&#39;s <code>pixelfed-following.json</code></strong> (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 <code>url</code>/<code>acct</code>/<code>account</code>/<code>id</code>, and the array may sit under <code>following</code> or <code>orderedItems</code>. 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 <code>{&quot;followed&quot;, &quot;skipped&quot;, &quot;failed&quot;}</code>, where <code>failed</code> maps a handle to the reason. Rate-limited to 4 an hour.</p>\n<h2 id=\"post-api-v1-migration-people\">POST /api/v1/migration/people</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>)</p>\n<p>The accounts an <strong>Instagram</strong> archive says you followed, as fediverse handles worth trying: <code>{&quot;handles&quot;: [&quot;name@threads.net&quot;, …]}</code>. Instagram exports no fediverse names because it has none, but Threads federates and a Threads handle is the Instagram one at <code>threads.net</code>. The archive is searched for the <em>shape</em> Instagram writes (<code>string_list_data[].value</code>) 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.</p>\n<h2 id=\"post-api-v1-migration-people-find\">POST /api/v1/migration/people/find</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>handles</code> (array)</p>\n<p>Which of those accounts exist, <strong>one batch at a time</strong>: <code>{&quot;checked&quot;: n, &quot;found&quot;: [{&quot;handle&quot;, &quot;name&quot;, &quot;url&quot;, &quot;avatar&quot;}]}</code>. Each name is a webfinger against another server, so at most <code>SwitchService::PROBE_BATCH</code> (25) are looked up per request. <code>checked</code> is how many were <em>looked at</em>, not how many were there — a client&#39;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.</p>\n<h2 id=\"get-api-v1-migration-announcement\">GET /api/v1/migration/announcement</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The handle and address to leave behind on the network being left: <code>{&quot;handle&quot;: &quot;@alice@cloud.example&quot;, &quot;url&quot;, &quot;text&quot;}</code>. 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. <strong>403</strong> <code>account-not-set-up</code> when the caller has no account here yet.</p>\n<h2 id=\"post-api-v1-migration-posts\">POST /api/v1/migration/posts</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>), <code>fetch_media</code> (<code>1</code>)</p>\n<p><strong>Queued</strong> (see <code>/api/v1/migration/imports</code>): the upload is kept and the import runs in the background; answers <strong>202</strong> with <code>{&quot;import&quot;: {...}}</code> as queued, <strong>409</strong> while one of this kind is still running, <strong>413</strong> over 100 MB. 30 an hour. <strong>An account&#39;s own posts, brought over from the server it wrote them on</strong> — the one thing a <code>Move</code> has never carried. Reads this app&#39;s own archive (<code>social/outbox.json</code> in the zip, with the files under <code>media_attachments/</code>), Mastodon&#39;s and GoToSocial&#39;s (<code>outbox.json</code> at the root, the layout ours copied), an <code>outbox.json</code> on its own, Pixelfed&#39;s <code>pixelfed-statuses.json</code>, <strong>PeerTube&#39;s</strong> (the one its own My account → Import/Export offers), or <strong>Instagram&#39;s</strong> &quot;Download your information&quot; archive — <code>content/posts_*.json</code> (both the current <code>your_instagram_activity/content/</code> layout and the older one) plus <code>reels.json</code>, <code>igtv_videos.json</code> and <code>other_content.json</code>, with the pictures out of the archive&#39;s own <code>media/</code> 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 <strong>importing account&#39;s own default visibility</strong> 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. <code>stories.json</code>, <code>archived_posts.json</code> and <code>recently_deleted_content.json</code> are deliberately not read. Instagram&#39;s <strong>HTML</strong> download is refused with the sentence that says to ask for JSON. A PeerTube export is read from <code>peertube/videos.json</code> rather than the <code>activity-pub/outbox.json</code> beside it: the ActivityPub half names each video&#39;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 &quot;the people who had the password&quot;), so are lives, and so is any video whose file is not in the archive. An export taken <strong>without</strong> its video files is refused by name, because the JSON alone is a catalogue and the run would otherwise report &quot;nothing imported&quot; about a perfectly valid archive that is simply not the one to ask for. View, like and dislike counts are <strong>not</strong> carried over: they are numbers about the old instance&#39;s readers. Each post is written as a <strong>new local post of the importing account</strong>, 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 <code>fetch_media</code> is <code>0</code>. <strong>Nothing is federated</strong>: not one delivery is queued, because re-publishing somebody&#39;s five years of posts would put five years of posts into every follower&#39;s timeline in one afternoon. Boosts and direct messages are skipped — the first is somebody else&#39;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 <code>{&quot;imported&quot;, &quot;skipped&quot;, &quot;already&quot;, &quot;media&quot;, &quot;failed&quot;, &quot;total&quot;, &quot;capped&quot;}</code>; a repeat of the same file imports nothing, because <code>social_import_post</code> remembers what each post became. At most 2000 posts a run — <code>capped</code> 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 <code>occ social:account:import-posts</code>.</p>\n<h2 id=\"post-api-v1-migration-video\">POST /api/v1/migration/video</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>url</code> (required), <code>fetch_media</code> (<code>1</code>)</p>\n<p><strong>One video, by its address</strong> — 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 <code>Video</code> that <strong>names the address it was fetched from</strong> among its own <code>url</code> links — the same evidence <code>resolveStatus()</code> 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&#39;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 <strong>no-op</strong>, and it is written as a new local post of the caller, keeping its title, running time, category and licence. Refuses a video <strong>already on this server</strong> (bringing a neighbour&#39;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 <em>cannot</em> check is whether the video is yours — neither can PeerTube&#39;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 <strong>10 an hour</strong>, producing an ordinary post that moderation and reporting reach like any other. Answers the same tally. A refusal is a <strong>422</strong> whose <code>code</code> says which one it was: <code>video-address-invalid</code>, <code>video-here-already</code>, <code>video-unreachable</code> or <code>video-unsupported</code>.</p>\n<h2 id=\"post-api-v1-migration-blocks\">POST /api/v1/migration/blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>)</p>\n<p><strong>Queued</strong> (see <code>/api/v1/migration/imports</code>): the upload is kept and the import runs in the background; answers <strong>202</strong> with <code>{&quot;import&quot;: {...}}</code> as queued, <strong>409</strong> while one of this kind is still running, <strong>413</strong> over 100 MB. 30 an hour. The accounts an export blocks — Mastodon&#39;s <code>blocked_accounts.csv</code>, a bare list of handles, and the same file the archive above holds. A block is this account&#39;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 <code>Block</code> exactly as blocking somebody from the web client does. Its own route rather than a <code>kind</code> 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 <code>failed</code> rather than dropped. Returns <code>{&quot;blocked&quot;, &quot;skipped&quot;, &quot;failed&quot;}</code>. Rate-limited to 4 an hour.</p>\n<h2 id=\"post-api-v1-migration-mutes\">POST /api/v1/migration/mutes</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>)</p>\n<p><strong>Queued</strong> (see <code>/api/v1/migration/imports</code>): the upload is kept and the import runs in the background; answers <strong>202</strong> with <code>{&quot;import&quot;: {...}}</code> as queued, <strong>409</strong> while one of this kind is still running, <strong>413</strong> over 100 MB. 30 an hour. The accounts an export mutes — Mastodon&#39;s <code>muted_accounts.csv</code>, whose <code>Hide notifications</code> column is the one thing a mute stores besides its target and is honoured here. A mute federates nothing. Returns <code>{&quot;muted&quot;, &quot;skipped&quot;, &quot;failed&quot;}</code>. Rate-limited to 4 an hour.</p>\n<h2 id=\"post-api-v1-migration-lists\">POST /api/v1/migration/lists</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>)</p>\n<p><strong>Queued</strong> (see <code>/api/v1/migration/imports</code>): the upload is kept and the import runs in the background; answers <strong>202</strong> with <code>{&quot;import&quot;: {...}}</code> as queued, <strong>409</strong> while one of this kind is still running, <strong>413</strong> over 100 MB. 30 an hour. The lists an export names — Mastodon&#39;s <code>lists.csv</code>, one <code>list name,account address</code> per row, with no header (one is skipped where it is there). <strong>Run it after the follows</strong>: a list here holds accounts this one follows, as Mastodon&#39;s do, so an account not followed yet is counted in <code>skipped</code> 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&#39;s. Returns <code>{&quot;lists&quot;, &quot;added&quot;, &quot;skipped&quot;, &quot;failed&quot;}</code>, where <code>failed</code> maps <code>list/handle</code> to the reason. Rate-limited to 4 an hour.</p>\n<h2 id=\"post-api-v1-migration-bookmarks\">POST /api/v1/migration/bookmarks</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>)</p>\n<p><strong>Queued</strong> (see <code>/api/v1/migration/imports</code>), as the other uploads: <strong>202</strong> with <code>{&quot;import&quot;: {...}}</code>, <strong>409</strong> while one of this kind runs, <strong>413</strong> over 100 MB, 30 an hour. The posts an export bookmarked — Mastodon&#39;s <code>bookmarks.csv</code>, one post address a line. Each address is fetched from the server it lives on (<code>SearchService::resolveStatus()</code>, 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&#39;s bookmarks are mostly other people&#39;s posts elsewhere. <code>report.failed</code> 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.</p>\n<h2 id=\"post-api-v1-migration-domain-blocks\">POST /api/v1/migration/domain_blocks</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>file</code> (multipart, <code>$_FILES[&#39;file&#39;]</code>)</p>\n<p><strong>Queued</strong>, as above. The servers an export blocks — Mastodon&#39;s <code>blocked_domains.csv</code>, one domain a line, a <code>#domain</code> header tolerated. Each is blocked through <code>DomainBlockService::block()</code>, the same as <code>POST /api/v1/domain_blocks</code>; the instance itself cannot be blocked and is reported under <code>report.failed</code>. Federates nothing.</p>\n<h2 id=\"get-api-v1-migration-export-kind\">GET /api/v1/migration/export/{kind}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, the scope of the list: <code>read:follows</code> for <code>following</code> and <code>followers</code>, <code>read:blocks</code> for <code>blocks</code> and <code>domain_blocks</code>, <code>read:mutes</code>, <code>read:lists</code>, <code>read:bookmarks</code>; any other <code>kind</code> <code>read</code>; or the broad <code>read</code>) · <strong>Parameters: </strong><code>kind</code>: <code>following</code>, <code>followers</code>, <code>blocks</code>, <code>mutes</code>, <code>lists</code>, <code>bookmarks</code> or <code>domain_blocks</code></p>\n<p>One of those lists as a single CSV, written the way Mastodon writes it — <code>following_accounts.csv</code>, <code>followers.csv</code>, <code>blocked_accounts.csv</code>, <code>muted_accounts.csv</code>, <code>lists.csv</code>, <code>bookmarks.csv</code> (post addresses, newest first) or <code>blocked_domains.csv</code> — so another server&#39;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&#39;s own handle — every local actor holds a loopback follow of itself, and a <code>following_accounts.csv</code> naming you is a row Mastodon&#39;s importer tries to follow you with. A handle or list name that a spreadsheet would run as a formula (starting with <code>=</code>, <code>+</code>, <code>-</code>, <code>@</code>, a tab or a carriage return) is written with a leading <code>&#39;</code>, and the importers here take it off again. At most 5000 rows a file. Any other <code>kind</code> is a <strong>404</strong> <code>list-unknown</code>. Rate-limited to 30 an hour.</p>\n<h2 id=\"post-api-v1-migration-move-in-inspect\">POST /api/v1/migration/move-in/inspect</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>handle</code> (required: <code>@you@old.example</code>, or the actor id)</p>\n<p>The old account, and what its server lets this one read off it: <code>{&quot;account&quot;: {&quot;id&quot;, &quot;acct&quot;, &quot;name&quot;, &quot;url&quot;, &quot;avatar&quot;, &quot;following&quot;: {&quot;total&quot;, &quot;readable&quot;}, &quot;posts&quot;: {&quot;total&quot;, &quot;readable&quot;}}}</code>. <code>readable</code> is false for a collection the server answers with a count and no page — Mastodon&#39;s &quot;hide your social graph&quot;, Pixelfed always — which is when the file import is the way instead; the page says so before anything is started. <strong>422</strong> with the reason when the handle names nobody: <code>account-address-invalid</code>, <code>account-not-found</code>, or <code>account-not-verifiable</code> for a server that answers only servers it can verify and could not verify this one. 30 an hour.</p>\n<h2 id=\"post-api-v1-migration-move-in\">POST /api/v1/migration/move-in</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>handle</code> (required), <code>follows</code> (<code>1</code>), <code>posts</code> (<code>1</code>), <code>fetch_media</code> (<code>1</code>)</p>\n<p><strong>Moving here from the old account, from nothing but its handle.</strong> Sets the alias at once (the half the old server asks for, and which federates nothing), then queues a <code>move_in</code> import that follows everyone the old account follows, from its public <code>following</code> collection, and writes its public and unlisted posts here as this account&#39;s own, from its public <code>outbox</code>, through the same <code>FollowService</code> and <code>PostImportService</code> 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 <strong>202</strong> <code>{&quot;import&quot;: {...}}</code>; the import&#39;s <code>report</code> ends with <code>followed</code>/<code>skipped</code>/<code>failed</code>/<code>failures</code>, <code>imported</code>/<code>already</code>/<code>posts_skipped</code>/<code>posts_failed</code>/<code>media</code>, and <code>following_readable</code>/<code>posts_readable</code>. The followers themselves are the old server&#39;s <code>Move</code>, which the page points at once this has run. <strong>409</strong> <code>import-running</code> while a move is already running, <strong>422</strong> when the handle names nobody (as for inspect) or names this account (<code>alias-self</code>). 10 an hour.</p>\n<h2 id=\"post-api-v1-migration-move-in-finish\">POST /api/v1/migration/move-in/finish</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>handle</code> (the old account), <code>bluesky</code> (what becomes of the old account&#39;s Bluesky identity, passed on to the old server; <code>deactivate</code> by default)</p>\n<p><strong>Finishing the move from here, when the old server is this app too.</strong> Mastodon has no API for a move, so a person moving from Mastodon always ends in Mastodon&#39;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 <code>write:migration</code> (<code>MoveFinishService::start()</code>), keeps the client credentials and a random <code>state</code> on the user (<code>move_finish</code>, 15 minutes), and answers <code>{&quot;authorize_url&quot;}</code> — the old instance&#39;s consent page, where the person logs in to their <em>old</em> Nextcloud and agrees. <strong>422</strong> <code>finish-not-possible</code> when the old server is not this app (<code>FediverseDirectoryService::softwareName()</code> of its host), <code>old-server-refused</code> when it will not register us, and the codes of inspect when the handle names nobody. 10 an hour.</p>\n<h2 id=\"get-api-v1-migration-move-in-finish\">GET /api/v1/migration/move-in/finish</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Where a finish started from here stands: <code>{&quot;status&quot;: &quot;none&quot;|&quot;pending&quot;|&quot;done&quot;|&quot;failed&quot;, &quot;acct&quot;, &quot;at&quot;, &quot;error&quot;}</code>. A <code>pending</code> older than 15 minutes reads as <code>failed</code>.</p>\n<h2 id=\"get-migration-move-in-callback\">GET /migration/move-in/callback</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong><code>code</code>, <code>state</code> (or <code>error</code>)</p>\n<p>Where the old server sends the person back. The code is exchanged at the old instance&#39;s <code>/oauth/token</code> with the kept credentials and the same redirect URI, and with the token the old instance&#39;s <code>POST /api/v1/migration/move/authorized</code> is called naming this account (<code>MoveFinishService::finish()</code>); the outcome is kept for the page. A wrong or missing <code>state</code>, an expired start or a refusal by the old server are recorded as <code>failed</code> with the reason. Always redirects to the Migration page, which reads the status.</p>\n<h2 id=\"post-api-v1-migration-move-authorized\">POST /api/v1/migration/move/authorized</h2>\n<p><strong>Auth: </strong>public, no-csrf (token with <strong>exactly</strong> <code>write:migration</code>) · <strong>Parameters: </strong><code>target</code> (handle or actor id), <code>bluesky</code> (as for <code>POST /api/v1/migration/move</code>)</p>\n<p>The same move as <code>POST /api/v1/migration/move</code> — <code>MigrationService::move()</code>, cooldown included — for a token the account&#39;s owner granted to their new instance by consenting there. The scope has to be spelled out on the token: the broad <code>write</code> every phone app holds is refused with <strong>403</strong>, as is a session without a token (the button, with its password step, is for sessions). <code>MigrationApiController</code>. <strong>422</strong> with the reason when the move is refused (cooldown, target does not name this account).</p>\n<h2 id=\"get-api-v1-migration-move\">GET /api/v1/migration/move</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>Where this account stands: <code>{&quot;moved_to&quot;, &quot;moved_at&quot;, &quot;can_move_at&quot;}</code> — the actor it moved to (<code>&quot;&quot;</code> when it has not), when, and when it may move (again): <code>moved_at + 30 days</code>, Mastodon&#39;s cooldown, or <code>0</code> for an account that never moved.</p>\n<h2 id=\"post-api-v1-migration-move\">POST /api/v1/migration/move</h2>\n<p><strong>Auth: </strong>user, <strong>password confirmation</strong> · <strong>Parameters: </strong><code>target</code> (required: <code>@you@new.example</code> or the actor id), <code>confirm</code> (required: this account&#39;s own handle, typed back), <code>bluesky</code> (<code>deactivate</code>, the default, <code>keep</code> or <code>move</code>)</p>\n<p><strong>Moves this account away</strong>: every follower&#39;s server is told to follow <code>target</code> instead and this account is marked as moved — what <code>occ social:account:move</code> does, now the person&#39;s own to do. Three things stand in front of it: Nextcloud&#39;s password confirmation, the handle typed back as <code>confirm</code> (case and the leading <code>@</code> do not matter; <strong>422</strong> naming the handle otherwise), and <code>target</code> already listing this account in its <code>alsoKnownAs</code>, which the service checks against a fresh fetch (<strong>422</strong> with what to do otherwise). A move within thirty days of the last is a <strong>422</strong> saying when the next may happen; the <code>occ</code> command may skip that, the button may not. Answers the status above plus <code>target: {acct, url}</code>. Afterwards the account may not post or follow from here (<strong>403</strong> on those routes), its profile and the sidebar say where it went, and <code>verify_credentials</code> carries <code>moved</code>. <code>bluesky</code> says what becomes of the account&#39;s Bluesky identity: <code>deactivate</code> announces it inactive on Bluesky (<code>IdentityService::deactivate()</code>; Settings can switch it on again), <code>keep</code> leaves it, <code>move</code> is only taken while or after its own move away runs (<strong>422</strong> <code>bluesky-move-first</code> before anything moves). Every <strong>422</strong> carries a <code>code</code>: <code>confirm-handle</code>, <code>move-cooldown</code>, <code>alias-missing</code>, <code>move-onto-self</code>, <code>bluesky-move-first</code>, <code>bluesky-choice-invalid</code>, or the codes of inspect for a target that names nobody; anything else is a <strong>500</strong> <code>server-error</code>. 5 an hour.</p>\n<h2 id=\"delete-api-v1-migration-move\">DELETE /api/v1/migration/move</h2>\n<p><strong>Auth: </strong>user, <strong>password confirmation</strong> · <strong>Parameters: </strong>—</p>\n<p>Takes the redirect off: clears <code>movedTo</code>, 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.</p>\n<h2 id=\"get-api-v1-migration-imports\">GET /api/v1/migration/imports</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The imports this account asked for, newest first, at most 20: <code>{&quot;imports&quot;: [{&quot;id&quot;, &quot;kind&quot; (</code>follows<code>, </code>blocks<code>, </code>mutes<code>, </code>lists<code>, </code>posts<code>, </code>move_in<code>, </code>bluesky_follows<code>), &quot;status&quot; (</code>queued<code>, </code>running<code>, </code>done<code>, </code>failed<code>), &quot;total&quot;, &quot;done&quot;, &quot;skipped&quot;, &quot;failed&quot;, &quot;report&quot;, &quot;options&quot;, &quot;created_at&quot;, &quot;updated_at&quot;}]}</code>. While one is <code>running</code>, <code>done</code>/<code>total</code> move as it goes, written every ten items or two seconds; afterwards <code>done</code>, <code>skipped</code> and <code>failed</code> are the outcome and <code>report</code> carries the detail — the failed handles by name with the reason (<code>failed</code>, the first 50) for the account lists, <code>failures</code> for the follows and <code>post_failures</code> for the posts of a move-in (the first 20 each, post URL → reason; also <code>failures</code> on a posts import), the importer&#39;s tally for the posts, <code>error</code> 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&#39;s timeout and the rate limit then kept the person from trying again for an hour.</p>\n<h2 id=\"delete-api-v1-migration-imports-id\">DELETE /api/v1/migration/imports/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope) · <strong>Parameters: </strong><code>id</code></p>\n<p>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 <strong>404</strong> <code>import-not-found</code>, as does somebody else&#39;s.</p>\n<h2 id=\"get-api-v1-migration-aliases\">GET /api/v1/migration/aliases</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The accounts this one also answers to — its <code>alsoKnownAs</code>. <code>{&quot;aliases&quot;: [...]}</code>.</p>\n<h2 id=\"post-api-v1-migration-aliases\">POST /api/v1/migration/aliases</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>alias</code> (required: a <code>@user@host</code> handle, resolved through WebFinger, or an actor id)</p>\n<p>Adds one. <strong>This federates nothing</strong>: it is a statement this server makes about an account it owns, and it is what the <em>old</em> server demands before it will accept a <code>Move</code> pointing here — so it is the person&#39;s own to make rather than an administrator&#39;s. Idempotent. An address that is not an actor id (a hostname, a handle nobody answers to, this account&#39;s own id) is a <strong>422</strong> naming the reason, with the codes of inspect or <code>alias-self</code>. 30 an hour.</p>\n<h2 id=\"delete-api-v1-migration-aliases\">DELETE /api/v1/migration/aliases</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>alias</code> (required)</p>\n<p>Stops answering to it. Idempotent, and answers with the list as it now stands. 30 an hour.</p>\n<h2 id=\"migration-error-codes\">Migration error codes</h2>\n<p>The codes of the routes above, beside the English sentence. A move away that asks for <code>bluesky: move</code> too early answers the codes of the ATProto move error codes (<code>bluesky-move-first</code>, <code>bluesky-choice-invalid</code>).</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Code</th>\n<th>When</th>\n<th>What the person can do</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>not-signed-in</code></td>\n<td>A session route without a signed-in user (<strong>401</strong>)</td>\n<td>Sign in again</td>\n</tr>\n<tr>\n<td><code>no-file</code></td>\n<td>An upload route without a file, or with an upload that did not arrive whole (<strong>400</strong>)</td>\n<td>Pick the file again</td>\n</tr>\n<tr>\n<td><code>file-too-large</code></td>\n<td>The upload is over 100 MB (<strong>413</strong>); the sentence names the limit</td>\n<td>Ask the administrator; <code>occ social:account:import-posts</code> takes a larger posts archive</td>\n</tr>\n<tr>\n<td><code>file-unreadable</code></td>\n<td>The uploaded file could not be read (<strong>400</strong>)</td>\n<td>Pick the file again</td>\n</tr>\n<tr>\n<td><code>archive-unreadable</code></td>\n<td>The archive import was given something that is not a zip (<strong>400</strong>)</td>\n<td>Pick the archive the export made</td>\n</tr>\n<tr>\n<td><code>archive-not-social</code></td>\n<td>The zip holds no <code>social/actor.json</code> (<strong>400</strong>)</td>\n<td>Pick the archive the export made</td>\n</tr>\n<tr>\n<td><code>import-running</code></td>\n<td>An import of the kind, or a move here, is running already (<strong>409</strong>)</td>\n<td>Wait for it on the imports list</td>\n</tr>\n<tr>\n<td><code>import-not-found</code></td>\n<td>Dismissing an import that is not a finished one of the caller&#39;s (<strong>404</strong>)</td>\n<td>Reload the list</td>\n</tr>\n<tr>\n<td><code>list-unknown</code></td>\n<td>A CSV export of a <code>kind</code> that names no list (<strong>404</strong>)</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>account-address-invalid</code></td>\n<td>What was typed is neither a <code>@user@host</code> handle nor an <code>https://</code> address</td>\n<td>Check the address</td>\n</tr>\n<tr>\n<td><code>account-not-found</code></td>\n<td>No account answers to the handle or at the address</td>\n<td>Check the address</td>\n</tr>\n<tr>\n<td><code>account-not-verifiable</code></td>\n<td>That server answers only servers it can verify (a 401 or 403 to the fetch), and could not verify this one</td>\n<td>Ask the administrator to make this server reachable from the internet over https</td>\n</tr>\n<tr>\n<td><code>alias-self</code></td>\n<td>The alias names this account itself</td>\n<td>Name the other account</td>\n</tr>\n<tr>\n<td><code>confirm-handle</code></td>\n<td>Moving away without this account&#39;s own handle typed back</td>\n<td>Type it</td>\n</tr>\n<tr>\n<td><code>move-cooldown</code></td>\n<td>Moving away within 30 days of the last move; the sentence names the day</td>\n<td>Wait until then</td>\n</tr>\n<tr>\n<td><code>move-onto-self</code></td>\n<td>Moving away onto this account itself</td>\n<td>Name the new account</td>\n</tr>\n<tr>\n<td><code>alias-missing</code></td>\n<td>The new account does not list this one in its <code>alsoKnownAs</code></td>\n<td>Add the alias on the new account first</td>\n</tr>\n<tr>\n<td><code>finish-not-possible</code></td>\n<td>Finishing from here when the old server is not this app</td>\n<td>Finish the move on the old server</td>\n</tr>\n<tr>\n<td><code>old-server-refused</code></td>\n<td>The old server would not register this one, or answered a step with an error</td>\n<td>Try again later, or finish there</td>\n</tr>\n<tr>\n<td><code>video-address-invalid</code></td>\n<td>The video address is not <code>http(s)://</code></td>\n<td>Copy the video page&#39;s address</td>\n</tr>\n<tr>\n<td><code>video-here-already</code></td>\n<td>The video is on this server already</td>\n<td>Nothing to bring over</td>\n</tr>\n<tr>\n<td><code>video-unreachable</code></td>\n<td>The video address could not be read</td>\n<td>Check it, or try again later</td>\n</tr>\n<tr>\n<td><code>video-unsupported</code></td>\n<td>The address is not a video that can be brought over</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>server-error</code></td>\n<td>Anything else; logged, and answered <strong>500</strong> with a fixed sentence</td>\n<td>Try again; ask the administrator if it repeats</td>\n</tr>\n</tbody></table></div>\n<h2 id=\"other-refusal-codes\">Other refusal codes</h2>\n<p>Routes elsewhere whose refusal is advice — a limit, the field to change — carry a code too, beside the English <code>error</code> (or <code>message</code>) 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&#39;s language (<code>src/utils/serverError.js</code>). A route not listed here answers its refusals with the sentence alone.</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Code</th>\n<th>Route</th>\n<th>When</th>\n<th>Beside it</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>featured-tags-full</code></td>\n<td><code>POST /api/v1/featured_tags</code> (<strong>422</strong>)</td>\n<td>One past <code>max_featured_tags</code></td>\n<td><code>limit</code></td>\n</tr>\n<tr>\n<td><code>shorts-full</code></td>\n<td><code>POST /api/v1/stories</code> (<strong>422</strong>)</td>\n<td>The account has as many live 24-hour shorts as it may</td>\n<td><code>limit</code></td>\n</tr>\n<tr>\n<td><code>handle-length</code></td>\n<td><code>POST /api/v1/account/create</code> (<strong>422</strong>)</td>\n<td>The handle is empty or longer than allowed</td>\n<td><code>max</code></td>\n</tr>\n<tr>\n<td><code>handle-characters</code></td>\n<td><code>POST /api/v1/account/create</code> (<strong>422</strong>)</td>\n<td>The handle has characters other than letters, digits and <code>_</code>, with <code>.</code> and <code>-</code> inside</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>handle-other-user</code></td>\n<td><code>POST /api/v1/account/create</code> (<strong>422</strong>)</td>\n<td>The handle is another Nextcloud user&#39;s id</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>handle-in-use-here</code></td>\n<td><code>POST /api/v1/account/create</code> (<strong>422</strong>)</td>\n<td>An actor here holds the handle</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>handle-held</code></td>\n<td><code>POST /api/v1/account/create</code> (<strong>422</strong>)</td>\n<td>The handle belonged to an account deleted within the retention time</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>account-exists</code></td>\n<td><code>POST /api/v1/account/create</code> (<strong>422</strong>)</td>\n<td>The user has an account already</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>email-domain-refused</code></td>\n<td><code>POST /api/v1/account/create</code> (<strong>422</strong>)</td>\n<td>The user&#39;s email address is at a domain this server makes no accounts for</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>linked-handle-invalid</code></td>\n<td><code>POST /api/v1/account/link</code> (<strong>422</strong>)</td>\n<td>What was typed is not <code>user@server.example</code></td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>linked-handle-local</code></td>\n<td><code>POST /api/v1/account/link</code> (<strong>422</strong>)</td>\n<td>The address is on this server</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>no-file</code></td>\n<td><code>POST /api/v1/banner</code> (<strong>400</strong>)</td>\n<td>No file arrived</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>upload-interrupted</code></td>\n<td><code>POST /api/v1/banner</code> (<strong>400</strong>)</td>\n<td>The upload did not finish</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>banner-too-large</code></td>\n<td><code>POST /api/v1/banner</code> (<strong>400</strong>)</td>\n<td>The picture is over the smallest of <code>upload_max_filesize</code>, <code>post_max_size</code> and the instance&#39;s ceiling</td>\n<td><code>limit</code> (as people read it, e.g. <code>10 MB</code>)</td>\n</tr>\n<tr>\n<td><code>push-auth-required</code></td>\n<td><code>POST /api/v1/push/subscription</code> (<strong>422</strong>)</td>\n<td>The subscription store was called without an account or app token</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>push-endpoint-unreachable</code></td>\n<td><code>POST /api/v1/push/subscription</code> (<strong>422</strong>)</td>\n<td>The push distributor URL is not a reachable public HTTPS endpoint</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>push-keys-invalid</code></td>\n<td><code>POST /api/v1/push/subscription</code> (<strong>422</strong>)</td>\n<td>The Web Push subscription keys are absent or invalid</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>push-policy-invalid</code></td>\n<td><code>POST</code>, <code>PUT /api/v1/push/subscription</code> (<strong>422</strong>)</td>\n<td>The notification policy is not supported</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>push-alerts-invalid</code></td>\n<td><code>POST</code>, <code>PUT /api/v1/push/subscription</code> (<strong>422</strong>)</td>\n<td>A push alert preference has an invalid value</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>push-standard-invalid</code></td>\n<td><code>POST /api/v1/push/subscription</code> (<strong>422</strong>)</td>\n<td>The standard-format flag is not a boolean value</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>push-subscriptions-full</code></td>\n<td><code>POST /api/v1/push/subscription</code> (<strong>422</strong>)</td>\n<td>The account already has the maximum number of subscriptions</td>\n<td><code>limit</code></td>\n</tr>\n<tr>\n<td><code>push-subscription-invalid</code></td>\n<td><code>POST /api/v1/push/subscription</code> (<strong>422</strong>)</td>\n<td><code>subscription</code> is not an object</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>push-data-invalid</code></td>\n<td><code>POST</code>, <code>PUT /api/v1/push/subscription</code> (<strong>422</strong>)</td>\n<td><code>data</code> is not an object</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>banner-unusable</code></td>\n<td><code>POST /api/v1/banner</code> (<strong>400</strong>)</td>\n<td>Not a picture, or one of a type refused</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>setting-not-email</code></td>\n<td><code>POST /admin/server</code> (<strong>422</strong>)</td>\n<td>The field is not an email address</td>\n<td><code>field</code></td>\n</tr>\n<tr>\n<td><code>setting-too-long</code></td>\n<td><code>POST /admin/server</code> (<strong>422</strong>)</td>\n<td>The field is longer than allowed</td>\n<td><code>field</code>, <code>max</code></td>\n</tr>\n<tr>\n<td><code>setting-not-local-account</code></td>\n<td><code>POST /admin/server</code> (<strong>422</strong>)</td>\n<td>The field does not name a local account</td>\n<td><code>field</code></td>\n</tr>\n<tr>\n<td><code>setting-out-of-range</code></td>\n<td><code>POST /admin/server</code> (<strong>422</strong>), <code>POST /admin/interests</code> (<strong>400</strong>)</td>\n<td>The number is outside its range</td>\n<td><code>field</code>, <code>min</code>, <code>max</code></td>\n</tr>\n<tr>\n<td><code>setting-zero-or-range</code></td>\n<td><code>POST /admin/server</code> (<strong>422</strong>)</td>\n<td>The number is neither 0 nor in its range</td>\n<td><code>field</code>, <code>min</code>, <code>max</code></td>\n</tr>\n<tr>\n<td><code>setting-heights</code></td>\n<td><code>POST /admin/server</code> (<strong>422</strong>)</td>\n<td>The list of heights has none in range</td>\n<td><code>field</code>, <code>min</code>, <code>max</code></td>\n</tr>\n<tr>\n<td><code>setting-not-choice</code></td>\n<td><code>POST /admin/server</code> (<strong>422</strong>)</td>\n<td>The value is not one of the choices</td>\n<td><code>field</code>, <code>choices</code></td>\n</tr>\n<tr>\n<td><code>group-unknown</code></td>\n<td><code>POST /admin/sections</code> (<strong>400</strong>)</td>\n<td>A group id names no group</td>\n<td><code>group</code></td>\n</tr>\n<tr>\n<td><code>groups-too-many</code></td>\n<td><code>POST /admin/sections</code> (<strong>400</strong>)</td>\n<td>More groups than may become lists</td>\n<td><code>max</code></td>\n</tr>\n<tr>\n<td><code>account-not-found</code></td>\n<td><code>POST</code>/<code>DELETE /moderation/verifications</code> (<strong>404</strong>)</td>\n<td>No account goes by the name</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>account-not-set-up</code></td>\n<td>Every client route that acts for an account, reached with a Nextcloud session or app password (<strong>403</strong>, see <a href=\"/docs/api-authentication#authentication\">Authentication</a>): the client-API bases, the web app&#39;s own routes (the Bluesky settings, feeds and recovery routes, held posts, shared moderation lists, moving away and its announcement included), and <code>POST /oauth/authorize</code></td>\n<td>The signed-in Nextcloud user has not set up their account here yet</td>\n<td><code>setup_url</code></td>\n</tr>\n</tbody></table></div>\n<p><code>field</code> is the parameter&#39;s name as the server spells it (<code>contact_email</code>, <code>halfLife</code>); the page puts its own label for the field in its place.</p>\n","toc":[{"id":"get-api-v1-migration-export","text":"GET /api/v1/migration/export","level":2},{"id":"post-api-v1-migration-import","text":"POST /api/v1/migration/import","level":2},{"id":"post-api-v1-migration-follows","text":"POST /api/v1/migration/follows","level":2},{"id":"post-api-v1-migration-people","text":"POST /api/v1/migration/people","level":2},{"id":"post-api-v1-migration-people-find","text":"POST /api/v1/migration/people/find","level":2},{"id":"get-api-v1-migration-announcement","text":"GET /api/v1/migration/announcement","level":2},{"id":"post-api-v1-migration-posts","text":"POST /api/v1/migration/posts","level":2},{"id":"post-api-v1-migration-video","text":"POST /api/v1/migration/video","level":2},{"id":"post-api-v1-migration-blocks","text":"POST /api/v1/migration/blocks","level":2},{"id":"post-api-v1-migration-mutes","text":"POST /api/v1/migration/mutes","level":2},{"id":"post-api-v1-migration-lists","text":"POST /api/v1/migration/lists","level":2},{"id":"post-api-v1-migration-bookmarks","text":"POST /api/v1/migration/bookmarks","level":2},{"id":"post-api-v1-migration-domain-blocks","text":"POST /api/v1/migration/domain_blocks","level":2},{"id":"get-api-v1-migration-export-kind","text":"GET /api/v1/migration/export/{kind}","level":2},{"id":"post-api-v1-migration-move-in-inspect","text":"POST /api/v1/migration/move-in/inspect","level":2},{"id":"post-api-v1-migration-move-in","text":"POST /api/v1/migration/move-in","level":2},{"id":"post-api-v1-migration-move-in-finish","text":"POST /api/v1/migration/move-in/finish","level":2},{"id":"get-api-v1-migration-move-in-finish","text":"GET /api/v1/migration/move-in/finish","level":2},{"id":"get-migration-move-in-callback","text":"GET /migration/move-in/callback","level":2},{"id":"post-api-v1-migration-move-authorized","text":"POST /api/v1/migration/move/authorized","level":2},{"id":"get-api-v1-migration-move","text":"GET /api/v1/migration/move","level":2},{"id":"post-api-v1-migration-move","text":"POST /api/v1/migration/move","level":2},{"id":"delete-api-v1-migration-move","text":"DELETE /api/v1/migration/move","level":2},{"id":"get-api-v1-migration-imports","text":"GET /api/v1/migration/imports","level":2},{"id":"delete-api-v1-migration-imports-id","text":"DELETE /api/v1/migration/imports/{id}","level":2},{"id":"get-api-v1-migration-aliases","text":"GET /api/v1/migration/aliases","level":2},{"id":"post-api-v1-migration-aliases","text":"POST /api/v1/migration/aliases","level":2},{"id":"delete-api-v1-migration-aliases","text":"DELETE /api/v1/migration/aliases","level":2},{"id":"migration-error-codes","text":"Migration error codes","level":2},{"id":"other-refusal-codes","text":"Other refusal codes","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"migration","manual":false,"prev":{"path":"/docs/api-banner","title":"Banner"},"next":{"path":"/docs/api-channels","title":"Channels"},"parent":"api-custom-local-api"},{"slug":"api-channels","path":"/docs/api-channels","title":"Channels","description":"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\"…","group":"api","html":"<p>The <code>Group</code> actor a video is published under. PeerTube resolves a video&#39;s channel by looking for a <code>Group</code> in its <code>attributedTo</code> and refuses the video with <em>&quot;Cannot find associated video channel&quot;</em> when there is none — so before these existed, every <code>Video</code> this app published was thrown away on arrival, silently and in PeerTube&#39;s log rather than ours. One is made for an account the first time it posts a video (<code>PostService::createPost()</code>), 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 <code>read:accounts</code>, and making or changing one for <code>write:accounts</code> — 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&#39;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&#39;s followers, who have not followed the author.</p>\n<h2 id=\"get-api-v1-channels\">GET /api/v1/channels</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:accounts</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Every channel this account has, oldest first: <code>{&quot;channels&quot;: [{&quot;id&quot;, &quot;actor_id&quot;, &quot;handle&quot;, &quot;name&quot;, &quot;description&quot;, &quot;default&quot;}]}</code>.</p>\n<h2 id=\"post-api-v1-channels\">POST /api/v1/channels</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>handle</code> (required), <code>name</code>, <code>description</code></p>\n<p>Makes one, with a <code>Group</code> 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 <strong>422</strong> naming the reason. At most 20 channels an account. 5 an hour.</p>\n<h2 id=\"put-api-v1-channels-id\">PUT /api/v1/channels/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>id</code>, <code>name</code>, <code>description</code></p>\n<p>Renames one, or changes what it says it is about — on the row and on the actor document both. Somebody else&#39;s channel is a <strong>422</strong>, the same answer an id that does not exist gets. 30 an hour.</p>\n<p>The dangerous direction is deliberately not here. <code>Move</code> tells every server that knows you to follow somebody else instead, cannot be taken back, and stays <code>occ social:account:move</code>.</p>\n","toc":[{"id":"get-api-v1-channels","text":"GET /api/v1/channels","level":2},{"id":"post-api-v1-channels","text":"POST /api/v1/channels","level":2},{"id":"put-api-v1-channels-id","text":"PUT /api/v1/channels/{id}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"channels","manual":false,"prev":{"path":"/docs/api-migration","title":"Migration"},"next":{"path":"/docs/api-posts-held-for-review","title":"Posts held for review"},"parent":"api-custom-local-api"},{"slug":"api-posts-held-for-review","path":"/docs/api-posts-held-for-review","title":"Posts held for review","description":"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…","group":"api","html":"<p>The other end of the review queue: what of the <strong>caller&#39;s own</strong> is waiting, and a way to take one back. Session routes with CSRF — unpublished text of the caller&#39;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.</p>\n<p>A held post is <strong>not</strong> in <code>social_stream</code>. 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&#39;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.</p>\n<h2 id=\"get-api-v1-review\">GET /api/v1/review</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The caller&#39;s own held posts, newest first: <code>{&quot;held&quot;: [{&quot;id&quot;, &quot;account_id&quot;, &quot;reason&quot;, &quot;text&quot;, &quot;spoiler_text&quot;, &quot;visibility&quot;, &quot;media_count&quot;, &quot;created_at&quot;}], &quot;reasons&quot;: [...]}</code>, where <code>reasons</code> is the same list in a sentence a person reads.</p>\n<h2 id=\"delete-api-v1-review-id\">DELETE /api/v1/review/{id}</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>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&#39;s, and one that does not exist, are the same <strong>404</strong>.</p>\n<p>What happens at the moment of posting is on <code>POST /api/v1/statuses</code>: a held post answers <strong>422</strong> with <code>held_for_review: true</code>, the rule under <code>reason</code>, and the held post itself — the vocabulary Mastodon&#39;s API has for &quot;this did not become a status&quot;, with enough beside it for a client to say something better than &quot;failed&quot;. The request has been kept, so writing it again only finds the first one: the queue is unique on (account, text).</p>\n","toc":[{"id":"get-api-v1-review","text":"GET /api/v1/review","level":2},{"id":"delete-api-v1-review-id","text":"DELETE /api/v1/review/{id}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"posts-held-for-review","manual":false,"prev":{"path":"/docs/api-channels","title":"Channels"},"next":{"path":"/docs/api-statistics","title":"Statistics"},"parent":"api-custom-local-api"},{"slug":"api-statistics","path":"/docs/api-statistics","title":"Statistics","description":"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…","group":"api","html":"<p>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 <code>read:statuses</code>: the figures and the memories are the caller&#39;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 <code>write:accounts</code>. There is no account parameter — they only ever answer about the caller.</p>\n<h2 id=\"get-api-v1-statistics\">GET /api/v1/statistics</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> or <code>read</code> scope) · <strong>Parameters: </strong><code>days</code> (0, 30, 90, 365), <code>fresh</code> (false)</p>\n<p>Everything the Statistics page shows, counted from this instance&#39;s rows at the moment it is asked for: nothing is stored and no cron precomputes it. See the shape below. <code>days</code> is the window — <code>0</code> is as far back as the cap allows — and the answer says which one it used and which are on offer. The result is <strong>cached per account and window for fifteen minutes</strong>; <code>fresh=true</code> counts again, and <code>window.cached</code> 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: <strong><code>network</code></strong> — <code>{servers, accounts, active, posts, peers, measured, source, source_url}</code> — 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&#39;s survey rather than something this instance can check. <code>peers</code> beside it <em>is</em> counted here: the servers this one federates with, the same number as <code>stats.domain_count</code> on <code>/api/v1/instance</code>, remembered for five minutes like it. The block is <strong>null</strong> when the <code>network_stats</code> app value is <code>0</code> or the survey did not answer, and the page then leaves the section out rather than drawing zeros.</p>\n<h2 id=\"get-api-v1-statistics-export\">GET /api/v1/statistics/export</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> or <code>read</code> scope) · <strong>Parameters: </strong><code>days</code> (0, 30, 90, 365), <code>format</code> (<code>csv</code>, <code>json</code>)</p>\n<p>The same figures as a file to keep: <code>social-statistics-&lt;date&gt;.csv</code> or <code>.json</code>. The CSV is flattened to <code>section,name,value</code> — 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 <code>=</code>, <code>+</code>, <code>-</code>, <code>@</code>, a tab or a carriage return, as an account name or a server name another server chose can — is written with a leading <code>&#39;</code>, 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&#39;s numbers is the one somebody takes. Rate-limited to 30 an hour.</p>\n<h2 id=\"get-api-v1-memories-on-this-day\">GET /api/v1/memories/on_this_day</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The caller&#39;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&#39;s followers-only and direct posts as well as their public ones, which is what <code>read:statuses</code> grants on the caller&#39;s own timelines. <strong>There is no account parameter and there must never be one</strong> — 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&#39;s own timezone rather than as &quot;about a year ago&quot;, 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.</p>\n<h2 id=\"get-api-v1-memories-recap\">GET /api/v1/memories/recap</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>read:statuses</code> or <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>How the caller&#39;s week went: <code>enabled</code>, <code>this_week</code> and <code>last_week</code>. <strong>Off until the reader switches it on</strong>, and then it answers <code>enabled: false</code> 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 <code>/api/v1/accounts/{account}/highlights</code> draws, so one place decides what a week is and the recap cannot disagree with the reader&#39;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.</p>\n<h2 id=\"post-api-v1-memories-recap\">POST /api/v1/memories/recap</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write:accounts</code> or <code>write</code> scope) · <strong>Parameters: </strong><code>enabled</code> (required, bool)</p>\n<p>Turns the weekly recap on or off for the caller and answers <code>{enabled}</code>.</p>\n<p>The answer:</p>\n<h2 id=\"account\">account</h2>\n<p><code>acct</code>, <code>display_name</code>, <code>created_at</code>, <code>followers</code>, <code>following</code></p>\n<h2 id=\"posts\">posts</h2>\n<p><code>total</code>, <code>originals</code>, <code>replies</code>, <code>boosts</code>, <code>with_media</code>, <code>sensitive</code></p>\n<h2 id=\"engagement\">engagement</h2>\n<p><code>likes</code>, <code>boosts</code>, <code>replies</code>, <code>quotes</code> and a <code>*_per_post</code> for each. A quote counts as engagement like the other three, in every total, rate and score below</p>\n<h2 id=\"rates\">rates</h2>\n<p><code>total</code> engagement and <code>per_post</code>; <code>applause</code>, <code>amplification</code> and <code>conversation</code> (likes, boosts and replies per post, under the names an agency reports them under); <code>per_follower</code>, engagement per post against the follower count as a percentage; <code>median</code> and <code>best</code>, because a mean is one viral post away from meaningless; <code>silent</code> and <code>silent_share</code>, the posts that got no answer at all</p>\n<h2 id=\"visibility\">visibility</h2>\n<p>how many posts went to each audience</p>\n<h2 id=\"by-month-engagement-by-month\">by_month, engagement_by_month</h2>\n<p>twelve months of posts, and of what they collected</p>\n<h2 id=\"by-hour\">by_hour</h2>\n<p>twenty-four hours of posts</p>\n<h2 id=\"by-weekday\">by_weekday</h2>\n<p>seven days, each with <code>posts</code>, <code>engagement</code> and the <code>average</code> — 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</p>\n<h2 id=\"best-hour\">best_hour</h2>\n<p><code>{hour, average, posts}</code>, or <code>hour: null</code> where no hour holds three posts yet: one lucky post is not a time of day that works</p>\n<h2 id=\"content\">content</h2>\n<p>one row per kind of post (<code>with_media</code>/<code>text_only</code>, <code>with_hashtag</code>/<code>no_hashtag</code>, <code>original</code>/<code>reply</code>, <code>visibility_*</code>), each with <code>posts</code>, <code>engagement</code> and <code>average</code>. A kind with no posts is absent rather than reported as zero</p>\n<h2 id=\"hashtags-hashtag-performance\">hashtags, hashtag_performance</h2>\n<p>the tags used most, and separately the tags whose posts average best — the second only counts tags used twice or more</p>\n<h2 id=\"audience\">audience</h2>\n<p><code>by_month</code> followers gained, <code>instances</code> the servers they are on, <code>local_share</code> the percentage on this server, <code>counted</code> and <code>capped</code>, and <code>starter_pack_joins</code>: how many accounts followed after joining through one of the account&#39;s starter packs in the window. A follower&#39;s server is the host of its id, except where its network knows better: a Bluesky account is on its PDS, with Bluesky&#39;s own <code>*.bsky.network</code> hosts as one <code>bsky.social</code>, and so is an account whose PDS is unknown or not a valid hostname</p>\n<h2 id=\"engagement-sources\">engagement_sources</h2>\n<p>where the likes, boosts and replies came from: <code>servers</code>, at most six with <code>host</code> and <code>count</code>, by the server of whoever made them as <code>audience</code> names it; <code>local_share</code>, the percentage made from this server; <code>counted</code>. The account&#39;s replies to itself are left out</p>\n<h2 id=\"best\">best</h2>\n<p>the three most-answered posts, each with an <code>excerpt</code>, its counts and its <code>score</code></p>\n<h2 id=\"periods\">periods</h2>\n<p>the last <code>days</code> (30) beside the 30 before them: <code>current</code> and <code>previous</code>, each with <code>from</code>, <code>until</code>, <code>posts</code>, <code>reach</code>, <code>interactions</code>, <code>likes</code>, <code>boosts</code>, <code>replies</code> and a <code>series</code> of 30 daily buckets for reach, interactions, likes and boosts; plus <code>change</code>, the percentage each moved by, or <code>null</code> where the earlier window held nothing — everything is infinitely more than nothing</p>\n<h2 id=\"timeline\">timeline</h2>\n<p>every post of the current window, newest first and at most 100, each with <code>id</code>, <code>url</code>, <code>published_at</code>, <code>excerpt</code>, <code>likes</code>, <code>boosts</code>, <code>replies</code>, <code>quotes</code>, <code>score</code>, <code>media</code>, <code>visibility</code> and <code>reach</code></p>\n<h2 id=\"reach\">reach</h2>\n<p><code>followers</code>, and <code>known_boosters</code>/<code>unknown_boosters</code>: 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 <code>instances</code>, the number of servers the window&#39;s posts were actually addressed to, which is measured rather than modelled <code>networks</code> lists the other networks the window&#39;s posts also went out on, which no instance path records, each with <code>network</code> and how many <code>posts</code>: a post published to Bluesky is a record in its author&#39;s repository, read from there rather than delivered</p>\n<h2 id=\"activity\">activity</h2>\n<p><code>originals</code>, <code>replies</code> and <code>boosts</code>, twelve months each: what the account <em>did</em>, beside the twelve months of what came back. A quiet month in <code>by_month</code> can mean either, and until this block there was no way to tell which</p>\n<h2 id=\"consistency\">consistency</h2>\n<p><code>active_days</code>, <code>span_days</code>, <code>share</code>, <code>streak</code> and <code>longest_gap</code>: the days posted on out of the days counted, the longest run and the longest silence</p>\n<h2 id=\"media\">media</h2>\n<p><code>images</code>, <code>described</code> and <code>described_share</code>: how many pictures were posted and how many of them carry alt text</p>\n<h2 id=\"languages-domains\">languages, domains</h2>\n<p>the languages posted in, and the hosts linked to, each with a count</p>\n<h2 id=\"partners\">partners</h2>\n<p><code>inbound</code> (who replies to this account) and <code>outbound</code> (who it replies to), at most ten each with <code>account</code>, <code>replies</code> and <code>followed</code>; plus <code>not_followed_share</code>, 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</p>\n<h2 id=\"window\">window</h2>\n<p><code>days</code> and the <code>choices</code> on offer, <code>cached</code>, <code>counted</code>, <code>capped</code>, <code>max</code>, <code>first_at</code>, <code>last_at</code>, <code>followers_counted</code></p>\n<p><code>reach</code> is an estimate and the page says so: an account&#39;s own followers today plus the followers of everybody who boosted the post, as the boosters&#39; 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 <code>unknown_boosters</code> 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 <em>when</em> 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.</p>\n<p>Every engagement figure is a post&#39;s <code>details</code> — 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 <code>per_follower</code> is against the follower count and says so on the page. A boost the account made is counted under <code>posts.boosts</code> 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 <code>window</code> and <code>audience</code> each say whether they stopped early.</p>\n","toc":[{"id":"get-api-v1-statistics","text":"GET /api/v1/statistics","level":2},{"id":"get-api-v1-statistics-export","text":"GET /api/v1/statistics/export","level":2},{"id":"get-api-v1-memories-on-this-day","text":"GET /api/v1/memories/on_this_day","level":2},{"id":"get-api-v1-memories-recap","text":"GET /api/v1/memories/recap","level":2},{"id":"post-api-v1-memories-recap","text":"POST /api/v1/memories/recap","level":2},{"id":"account","text":"account","level":2},{"id":"posts","text":"posts","level":2},{"id":"engagement","text":"engagement","level":2},{"id":"rates","text":"rates","level":2},{"id":"visibility","text":"visibility","level":2},{"id":"by-month-engagement-by-month","text":"by_month, engagement_by_month","level":2},{"id":"by-hour","text":"by_hour","level":2},{"id":"by-weekday","text":"by_weekday","level":2},{"id":"best-hour","text":"best_hour","level":2},{"id":"content","text":"content","level":2},{"id":"hashtags-hashtag-performance","text":"hashtags, hashtag_performance","level":2},{"id":"audience","text":"audience","level":2},{"id":"engagement-sources","text":"engagement_sources","level":2},{"id":"best","text":"best","level":2},{"id":"periods","text":"periods","level":2},{"id":"timeline","text":"timeline","level":2},{"id":"reach","text":"reach","level":2},{"id":"activity","text":"activity","level":2},{"id":"consistency","text":"consistency","level":2},{"id":"media","text":"media","level":2},{"id":"languages-domains","text":"languages, domains","level":2},{"id":"partners","text":"partners","level":2},{"id":"window","text":"window","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"statistics","manual":false,"prev":{"path":"/docs/api-posts-held-for-review","title":"Posts held for review"},"next":{"path":"/docs/api-pixelfeds-administration-routes","title":"Pixelfed's administration routes"},"parent":"api-custom-local-api"},{"slug":"api-pixelfeds-administration-routes","path":"/docs/api-pixelfeds-administration-routes","title":"Pixelfed's administration routes","description":"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…","group":"api","html":"<p>Pixelfed&#39;s app shows its administration screens to anybody the server calls an administrator, and they call Pixelfed&#39;s own <code>/api/admin/*</code> routes — not Mastodon&#39;s <code>/api/v1/admin/*</code>. They stand behind the <strong>same gate</strong> (<code>AdminApiControllerBase</code>: a Nextcloud administrator, or a group the Aloha Social section has been delegated to under <em>Administration privileges</em>, with a session and CSRF token or a bearer token carrying <code>admin:read</code>/<code>admin:write</code>) and are answered by the <strong>same service</strong>, 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 <strong>422</strong> that says why — never as a 200 that changed nothing. Every failure is worded as in the Mastodon admin API: <strong>401</strong> without credentials, <strong>403</strong> for a non-administrator (the same answer whether the user exists or not), <strong>404</strong> for an unknown thing, <strong>422</strong> for what this instance does not have.</p>\n<h2 id=\"get-api-admin-stats\">GET /api/admin/stats</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The four numbers on the app&#39;s admin home: <code>users_count</code>, <code>posts_count</code> and <code>instances_count</code> are this instance&#39;s own counts (the ones <code>/api/v2/instance</code> carries), <code>autospam_count</code> is <code>0</code> because there is no autospam queue here, and <code>cached_at</code> is now.</p>\n<h2 id=\"get-api-admin-config\">GET /api/admin/config</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>Pixelfed&#39;s five instance switches (<code>federation.activitypub.enabled</code>, <code>pixelfed.open_registration</code>, <code>instance.stories.enabled</code>, <code>pixelfed.enforce_email_verification</code>, <code>pixelfed.bouncer.enabled</code>), each with the state that is actually true of this instance, so the screen describes this server rather than a Pixelfed one.</p>\n<h2 id=\"post-api-admin-config-update\">POST /api/admin/config/update</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>key</code>, <code>value</code></p>\n<p>Always a <strong>422</strong> 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.</p>\n<h2 id=\"get-api-admin-users-list\">GET /api/admin/users/list</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>q</code> (a username prefix), <code>sort</code> (<code>asc</code>/<code>desc</code> by creation, <code>desc</code> when absent)</p>\n<p>The local accounts as the app&#39;s user browser lists them, fifty at most, each <code>id</code>, <code>username</code>, <code>email</code> (always <code>&#39;&#39;</code> — the address is the Nextcloud account&#39;s, which this app does not read out to a client), <code>created_at</code>, <code>is_admin</code> (whether the user may administer <em>this</em> instance) and <code>status</code> (<code>disabled</code> for a suspended account, <code>null</code> otherwise).</p>\n<h2 id=\"get-api-admin-users-get\">GET /api/admin/users/get</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>user_id</code> (required; a client id or a username)</p>\n<p>One account: the row above under <code>data</code>, and under <code>meta</code> the Account entity, <code>report_count</code> (reports filed against it), and the three per-account flags Pixelfed has and this instance does not (<code>unlisted</code>, <code>cw</code>, <code>no_autolink</code>), all <code>false</code>. <code>dms_sent</code> and <code>remote_report_count</code> are <code>0</code>: nobody here counts direct messages sent, and a remote report is a report like any other.</p>\n<h2 id=\"post-api-admin-users-action\">POST /api/admin/users/action</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>id</code> (required), <code>action</code> (required), <code>value</code></p>\n<p><code>delete</code> — the app&#39;s word for removing an account — <strong>suspends</strong> it, which takes its posts down here and sends the same <code>Delete</code> to every peer that the account&#39;s own deletion would. <code>unlisted</code> is this instance&#39;s <strong>silence</strong> tier and <code>cw</code> 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. <code>no_autolink</code> is a state an account does not have here, and <code>verify_email</code> and <code>refresh_stats</code> are the server&#39;s: each a <strong>422</strong> that says so.</p>\n<h2 id=\"get-api-admin-mod-reports-list\">GET /api/admin/mod-reports/list</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>The open reports as the app&#39;s queue draws them: <code>id</code>, <code>type</code> (<code>post</code> when the report carries one, <code>user</code> otherwise), <code>message</code> (the reporter&#39;s comment, with the reason in front of it when it came from the app&#39;s own report route), <code>object_id</code>, <code>object_type</code> (<code>App\\\\Status</code> or <code>App\\\\Profile</code>, Pixelfed&#39;s class names), <code>created_at</code>, <code>reported_by_account</code>, <code>reported_account</code>, <code>status</code> (the first reported post) and <code>parent</code> (<code>null</code>).</p>\n<h2 id=\"post-api-admin-mod-reports-handle\">POST /api/admin/mod-reports/handle</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>id</code> (required), <code>action</code> (required)</p>\n<p><code>ignore</code> resolves the report, in the signed-in moderator&#39;s name, and answers <code>{&quot;success&quot;: true}</code>. <code>cw</code> and <code>unlist</code> would apply a per-post flag this instance does not have and are a <strong>422</strong>: a post here is taken down or left.</p>\n<h2 id=\"get-api-admin-autospam-list\">GET /api/admin/autospam/list</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong>—</p>\n<p>This instance&#39;s <strong>review queue</strong>, fifty at most: the posts held because their author had published nothing here yet, or because one of the spam rules tripped. Each carries <code>id</code>, <code>status_id</code> (the same id — a held post has no status), <code>account_id</code>, <code>username</code>, <code>content</code>, <code>is_nsfw</code>, <code>scope</code>, <code>created_at</code>, and the rule that held it as both <code>reason</code> and <code>reason_text</code>. Pixelfed&#39;s screen shows a score here; a rule is what a moderator can act on and a score is not.</p>\n<h2 id=\"post-api-admin-autospam-handle\">POST /api/admin/autospam/handle</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>id</code> (required), <code>action</code> (required)</p>\n<p><code>approve</code> (Pixelfed&#39;s &quot;not spam&quot;, also <code>not_spam</code>) publishes the post as its author; <code>delete</code> (also <code>spam</code>) refuses it, which tells the author and is recorded against them as a strike. Anything else is a <strong>422</strong>. <code>{&quot;success&quot;: true}</code>.</p>\n<h2 id=\"get-api-admin-instances-list\">GET /api/admin/instances/list</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>q</code> (a domain fragment), <code>sort</code> (<code>asc</code>/<code>desc</code>), <code>sort_by</code> (<code>id</code>, <code>user_count</code>, <code>status_count</code>, <code>domain</code>), <code>filter</code> (<code>all</code>, <code>unlisted</code>, <code>banned</code>, <code>auto_cw</code>)</p>\n<p>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&#39;s words: <code>unlisted</code> is this app&#39;s <strong>silence</strong>, <code>banned</code> a <strong>deny-list</strong> entry, <code>auto_cw</code> a flag this instance does not have and always <code>false</code>. <code>user_count</code> is how many of the host&#39;s accounts are cached here; <code>status_count</code> is <code>0</code>, because nothing here counts posts per host and a guess would be worse than a zero the docs explain. <code>id</code> is the same derived id the domain-block routes use, so an instance and its block name the same thing.</p>\n<h2 id=\"get-api-admin-instances-get\">GET /api/admin/instances/get</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:read</code> scope) · <strong>Parameters: </strong><code>id</code> (required; the derived id or the domain)</p>\n<p>One instance, as above; unknown is a <strong>404</strong>.</p>\n<h2 id=\"post-api-admin-instances-moderate\">POST /api/admin/instances/moderate</h2>\n<p><strong>Auth: </strong>public, no-csrf (<strong>admin required</strong>, <code>admin:write</code> scope) · <strong>Parameters: </strong><code>id</code> (required), <code>key</code> (<code>unlisted</code>, <code>banned</code>, <code>auto_cw</code>), <code>value</code> (a boolean)</p>\n<p>Writes the list the Pixelfed word names: <code>unlisted</code> silences or unsilences the domain, <code>banned</code> puts it on the deny list or takes it off. On an instance that federates by an <strong>allow list</strong>, <code>banned</code> is a <strong>422</strong> — the same reason the domain-block routes refuse there — and <code>auto_cw</code> is a <strong>422</strong> everywhere. Answers with the instance as it now stands.</p>\n","toc":[{"id":"get-api-admin-stats","text":"GET /api/admin/stats","level":2},{"id":"get-api-admin-config","text":"GET /api/admin/config","level":2},{"id":"post-api-admin-config-update","text":"POST /api/admin/config/update","level":2},{"id":"get-api-admin-users-list","text":"GET /api/admin/users/list","level":2},{"id":"get-api-admin-users-get","text":"GET /api/admin/users/get","level":2},{"id":"post-api-admin-users-action","text":"POST /api/admin/users/action","level":2},{"id":"get-api-admin-mod-reports-list","text":"GET /api/admin/mod-reports/list","level":2},{"id":"post-api-admin-mod-reports-handle","text":"POST /api/admin/mod-reports/handle","level":2},{"id":"get-api-admin-autospam-list","text":"GET /api/admin/autospam/list","level":2},{"id":"post-api-admin-autospam-handle","text":"POST /api/admin/autospam/handle","level":2},{"id":"get-api-admin-instances-list","text":"GET /api/admin/instances/list","level":2},{"id":"get-api-admin-instances-get","text":"GET /api/admin/instances/get","level":2},{"id":"post-api-admin-instances-moderate","text":"POST /api/admin/instances/moderate","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"pixelfeds-administration-routes","manual":false,"prev":{"path":"/docs/api-statistics","title":"Statistics"},"next":{"path":"/docs/api-config-and-system","title":"Config and system"},"parent":"api-custom-local-api"},{"slug":"api-config-and-system","path":"/docs/api-config-and-system","title":"Config and system","description":"{\"result\": {\"version\": \"<installed_version>\", \"setup\": <bool>}, \"status\": 1}.","group":"api","html":"<h2 id=\"post-api-v1-config-cloudaddress\">POST /api/v1/config/cloudAddress</h2>\n<p><strong>Auth: </strong>admin · <strong>Parameters: </strong><code>cloudAddress</code> (required)</p>\n<p>Sets the app&#39;s cloud base URL. Returns a bare <code>[]</code>.</p>\n<h2 id=\"get-local\">GET /local/</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p><code>{&quot;result&quot;: {&quot;version&quot;: &quot;&lt;installed_version&gt;&quot;, &quot;setup&quot;: &lt;bool&gt;}, &quot;status&quot;: 1}</code>.</p>\n<h2 id=\"get-test-account\">GET /test/{account}/</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>account</code> (path)</p>\n<p>WebFinger self-test. Only active when the <code>social.tests</code> system value is set — otherwise it returns exactly the same payload as <code>/local/</code>. On failure it returns the error envelope with HTTP <strong>200</strong> and a <code>result</code> key holding the test data.</p>\n","toc":[{"id":"post-api-v1-config-cloudaddress","text":"POST /api/v1/config/cloudAddress","level":2},{"id":"get-local","text":"GET /local/","level":2},{"id":"get-test-account","text":"GET /test/{account}/","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"config-and-system","manual":false,"prev":{"path":"/docs/api-pixelfeds-administration-routes","title":"Pixelfed's administration routes"},"next":{"path":"/docs/api-moderation-moderators-only","title":"Moderation (moderators only)"},"parent":"api-custom-local-api"},{"slug":"api-moderation-moderators-only","path":"/docs/api-moderation-moderators-only","title":"Moderation (moderators only)","description":"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)…","group":"api","html":"<p>Backing routes of the Aloha Social section in the administration settings. All of them require a session <strong>and</strong> a CSRF token (they are deliberately not part of the bearer-token client API), and every one of them carries <code>#[AuthorizedAdminSetting(settings: AdminSettings::class)]</code>: a Nextcloud administrator passes, and so does a group the administrator has handed the Aloha Social section to under <em>Administration privileges</em>. That is the same gate core puts on the page itself, so whoever can open it can use the buttons on it.</p>\n<h2 id=\"get-moderation-reports\">GET /moderation/reports</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>resolved</code> (false), <code>page</code> (1)</p>\n<p>One page of 50 reports, newest first — the open ones, or with <code>resolved=true</code> the ones already dealt with. <code>{&quot;reports&quot;: [{&quot;id&quot;, &quot;account_id&quot;, &quot;account&quot;, &quot;reporter&quot;, &quot;local&quot;, &quot;category&quot;, &quot;comment&quot;, &quot;status_ids&quot;, &quot;creation&quot;, &quot;resolved&quot;, &quot;level&quot;}], &quot;total&quot;, &quot;page&quot;, &quot;perPage&quot;}</code>. <code>level</code> is what stands against the reported account <em>now</em> (<code>silence</code>, <code>suspend</code> or <code>&quot;&quot;</code>), 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 &quot;Show more&quot; button and the folded-away resolved section read. A <code>page</code> past the end answers with no reports and the same <code>total</code>.</p>\n<h2 id=\"post-moderation-reports-id-resolve\">POST /moderation/reports/{id}/resolve</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>resolved</code> (true)</p>\n<p>Marks the report resolved (or reopens it with <code>resolved=false</code>). Returns the report entity; 404 for an unknown id.</p>\n<h2 id=\"get-moderation-review\">GET /moderation/review</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>page</code> (1)</p>\n<p>One page of 50 held posts, <strong>oldest first</strong> — the order the queue should be drained in. <code>{&quot;held&quot;: [{&quot;id&quot;, &quot;account_id&quot;, &quot;reason&quot;, &quot;text&quot;, &quot;spoiler_text&quot;, &quot;visibility&quot;, &quot;media_count&quot;, &quot;created_at&quot;}], &quot;total&quot;, &quot;page&quot;, &quot;perPage&quot;, &quot;reviewFirstPost&quot;, &quot;autospam&quot;}</code>. 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.</p>\n<h2 id=\"post-moderation-review-id-approve\">POST /moderation/review/{id}/approve</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong>—</p>\n<p>Publishes it, as its author, down the path an immediate post takes — dated <strong>now</strong>, because that is when it became a post. <code>{&quot;approved&quot;: &quot;&lt;id&gt;&quot;}</code>; an id that is not waiting is a 404.</p>\n<h2 id=\"post-moderation-review-id-reject\">POST /moderation/review/{id}/reject</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>comment</code></p>\n<p>Refuses it. The request is deleted, the author is told through the same notification a takedown uses, and a <code>delete_statuses</code> 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. <code>{&quot;rejected&quot;: &quot;&lt;id&gt;&quot;}</code>.</p>\n<h2 id=\"post-moderation-review-settings\">POST /moderation/review/settings</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>reviewFirstPost</code> (required), <code>autospam</code> (required)</p>\n<p>Turns first-post review and the spam rules on and off (<code>review_first_post</code>, <code>autospam</code>; both <code>1</code> by default). Both are sent together because the section draws them together. Answers with both as they now stand.</p>\n<h2 id=\"post-moderation-accounts-sensitive\">POST /moderation/accounts/sensitive</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>actorId</code> (required), <code>sensitive</code> (true)</p>\n<p>Marks <strong>everything this account posts</strong> 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 (<code>StreamRequest::save()</code>), so it covers a local post, one that arrived in the inbox and one the importer restored alike — and it applies from the <strong>next</strong> post: rewriting somebody&#39;s old posts is a different and much larger decision. Pixelfed&#39;s app calls this <code>cw</code>.</p>\n<h2 id=\"get-moderation-media-blocks\">GET /moderation/media/blocks</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>maxId</code></p>\n<p>The pictures this instance refuses, by sha256 of the file as it arrived, a page of 100 at a time, newest first: <code>{&quot;blocks&quot;: [{&quot;id&quot;, &quot;hash&quot;, &quot;reason&quot;, &quot;moderator&quot;, &quot;blocked&quot;, &quot;creation&quot;}], &quot;next&quot;, &quot;total&quot;}</code>, where <code>blocked</code> is how many times that file has since been turned away. Pages are cut on the row <code>id</code>: <code>next</code> is the <code>maxId</code> that asks for the page after this one, <code>null</code> on the last, and <code>total</code> is how many files are refused in all.</p>\n<h2 id=\"post-moderation-media-blocks\">POST /moderation/media/blocks</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>hash</code> (required, sha256 hex), <code>reason</code></p>\n<p>Adds one. Every other tool here acts on an account, and none of them stops a <strong>file</strong> 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 <code>CacheDocumentService::saveFromTempToCache()</code>, 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 &quot;this exact file, again&quot;, and does not claim to answer &quot;a picture that looks like this one&quot;. Anything that is not a sha256 is a <strong>422</strong>.</p>\n<h2 id=\"delete-moderation-media-blocks\">DELETE /moderation/media/blocks</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>hash</code> (required)</p>\n<p>Removes one, whichever page it is on. It and <code>POST</code> both answer with the first page, in the shape <code>GET</code> does.</p>\n<h2 id=\"get-moderation-trends\">GET /moderation/trends</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong>—</p>\n<p>What is being kept out of Explore, and what is currently trending to choose from: <code>{&quot;tags&quot;, &quot;links&quot;, &quot;statuses&quot;, &quot;trending&quot;}</code>, each decision carrying who made it and when.</p>\n<h2 id=\"post-moderation-trends\">POST /moderation/trends</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>kind</code> (<code>tag</code>, <code>link</code> or <code>status</code>), <code>ref</code> (the hashtag, URL or post id)</p>\n<p>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 <strong>422</strong>.</p>\n<h2 id=\"delete-moderation-trends\">DELETE /moderation/trends</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>kind</code>, <code>ref</code></p>\n<p>Lets it back in.</p>\n<h2 id=\"get-moderation-emojis\">GET /moderation/emojis</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong>—</p>\n<p>The instance&#39;s own custom emoji, which could only be managed with <code>occ social:emoji</code> until now.</p>\n<h2 id=\"post-moderation-emojis\">POST /moderation/emojis</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>shortcode</code>, <code>category</code>, and a <code>picture</code> upload</p>\n<p>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 <strong>422</strong> with the reason.</p>\n<h2 id=\"delete-moderation-emojis\">DELETE /moderation/emojis</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>shortcode</code></p>\n<p>Removes one. An unknown shortcode is a <strong>404</strong>.</p>\n<h2 id=\"get-moderation-rules\">GET /moderation/rules</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong>—</p>\n<p>The rules this instance asks people to follow, as the one-per-line text they are stored as.</p>\n<h2 id=\"post-moderation-rules\">POST /moderation/rules</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>rules</code></p>\n<p>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 <code>/api/v1/instance/rules</code> serves and what every client shows on sign-up; before this they could only be set with <code>occ config:app:set social rules</code>.</p>\n<h2 id=\"get-moderation-discover-categories\">GET /moderation/discover/categories</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong>—</p>\n<p>The subjects named so far, the same list the public route hands out: <code>{&quot;categories&quot;: [{&quot;id&quot;, &quot;name&quot;, &quot;hashtags&quot;}]}</code>.</p>\n<h2 id=\"post-moderation-discover-categories\">POST /moderation/discover/categories</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>name</code> (required, at most 64 characters), <code>hashtags</code></p>\n<p>Names one. <code>hashtags</code> is written the way somebody pastes it — separated by spaces or commas, with or without the <code>#</code> — 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 <strong>422</strong> with the reason. Returns the whole list, so the caller never has to ask again.</p>\n<h2 id=\"delete-moderation-discover-categories\">DELETE /moderation/discover/categories</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>Removes one. Returns the whole list.</p>\n<h2 id=\"post-moderation-fediverse-add\">POST /moderation/fediverse/add</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>address</code> (required)</p>\n<p>Adds an instance to the Fediverse access list (the list <code>occ social:fediverse</code> manages). Invalid addresses are a 422. Returns <code>{&quot;list&quot;: [...]}</code>.</p>\n<h2 id=\"post-moderation-fediverse-remove\">POST /moderation/fediverse/remove</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>address</code> (required)</p>\n<p>Removes an instance from the access list. Returns <code>{&quot;list&quot;: [...]}</code>.</p>\n<h2 id=\"post-moderation-fediverse-access\">POST /moderation/fediverse/access</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>type</code> (required)</p>\n<p>Switches the access mode: <code>all_but</code> (blocklist) or <code>none_but</code> (allowlist). Anything else is a 422. Returns <code>{&quot;accessType&quot;: &quot;...&quot;}</code>.</p>\n<h2 id=\"post-moderation-fediverse-blocklist-preview\">POST /moderation/fediverse/blocklist/preview</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>csv</code> (required)</p>\n<p>Reads an uploaded block list and says what applying it would do, changing nothing: <code>{&quot;blocked&quot;, &quot;silenced&quot;, &quot;alreadyBlocked&quot;, &quot;alreadySilenced&quot;, &quot;entries&quot;: [{&quot;domain&quot;, &quot;severity&quot;}], &quot;rejected&quot;: [...], &quot;skipped&quot;}</code>. A Mastodon-style CSV — a <code>#domain</code> column, optionally <code>#severity</code> — or one domain a line. <code>severity</code> is <code>suspend</code> (block) or <code>silence</code>; a row with no severity is a block. <code>rejected</code> names rows that describe no instance the list may hold: a single label (<code>com</code>, 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.</p>\n<h2 id=\"post-moderation-fediverse-blocklist-import\">POST /moderation/fediverse/blocklist/import</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>csv</code> (required)</p>\n<p>Applies the same list. Fail-closed: any rejected row is a <strong>422</strong> naming them and nothing is applied, because this is a file the administrator chose. Returns the counts plus <code>{&quot;list&quot;: [...]}</code>. Importing into an allow list is a 422.</p>\n<h2 id=\"get-moderation-fediverse-blocklist-sources\">GET /moderation/fediverse/blocklist/sources</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong>—</p>\n<p>The published lists this instance can follow, as <code>{&quot;sources&quot;: [{&quot;id&quot;, &quot;label&quot;, &quot;url&quot;, &quot;format&quot;, &quot;enabled&quot;, &quot;lastRun&quot;, &quot;lastResult&quot;}]}</code>. Two are offered — <code>mastodon.social</code> and <code>thebad.space</code> — and both are off until an administrator turns one on. Mastodon answers <code>/api/v1/instance/domain_blocks</code> only where its administrators turned publishing on, so a source can be re-pointed at another server that does.</p>\n<h2 id=\"post-moderation-fediverse-blocklist-sources\">POST /moderation/fediverse/blocklist/sources</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>id</code> (required), <code>enabled</code> (required), <code>url</code></p>\n<p>Follows a published list, or stops. <code>url</code> 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.</p>\n<h2 id=\"post-moderation-fediverse-blocklist-fetch\">POST /moderation/fediverse/blocklist/fetch</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>id</code> (required), <code>dryRun</code> (false)</p>\n<p>Reads one source now instead of waiting for the daily job. <code>dryRun</code> 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 <code>{&quot;error&quot;: &quot;that server did not hand over a list&quot;}</code> rather than failing. Returns <code>{&quot;result&quot;, &quot;sources&quot;, &quot;list&quot;}</code>.</p>\n<h2 id=\"get-moderation-accounts\">GET /moderation/accounts</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>query</code>, <code>origin</code> (<code>local</code>, <code>remote</code>, or empty for both), <code>status</code> (<code>active</code>, <code>silenced</code>, <code>suspended</code>), <code>maxId</code> (0)</p>\n<p>A page of up to 40 accounts for the browser on the settings page, as <code>{&quot;accounts&quot;: [{&quot;actor_id&quot;, &quot;handle&quot;, &quot;username&quot;, &quot;domain&quot;, &quot;local&quot;, &quot;level&quot;, &quot;strikes&quot;}], &quot;cursors&quot;: [nid, …]}</code>. <code>strikes</code> is how many decisions have ever been taken about the account, counted for the whole page in one query. <code>query</code> is tried as all three of the things a moderator types: <code>bob@instance.example</code> (and <code>@bob@instance.example</code>) is an account on an instance, <code>instance.example</code> is the instance, and a bare <code>bob</code> is a username anywhere. Pass the last cursor back as <code>maxId</code> for the next page. An <code>origin</code> that is neither <code>local</code> nor <code>remote</code> means both, and a <code>status</code> outside the three above is passed on to the same reader the Mastodon admin API uses — so <code>pending</code> and <code>disabled</code> answer with no accounts, as they do there.</p>\n<h2 id=\"get-moderation-accounts-history\">GET /moderation/accounts/history</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>actorId</code> (required)</p>\n<p>What has been decided about one account before now, newest first, as <code>{&quot;strikes&quot;: [{&quot;action&quot;, &quot;text&quot;, &quot;moderator&quot;, &quot;report_id&quot;, &quot;creation&quot;}]}</code> — up to 50. <code>action</code> is <code>none</code> for a warning, otherwise <code>silence</code> or <code>suspend</code>. <code>moderator</code> is the Nextcloud user who took it, or <code>&quot;&quot;</code> for one taken by a command or a job. A missing <code>actorId</code> is a <strong>400</strong>.</p>\n<h2 id=\"post-moderation-accounts\">POST /moderation/accounts</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>actorId</code> (required), <code>level</code> (<code>silence</code>, <code>suspend</code>, or empty to lift), <code>comment</code></p>\n<p>The instance&#39;s own decision about an account, as opposed to one user&#39;s block. <strong>Silence</strong> 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. <strong>Suspend</strong> 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 <code>{&quot;actor_id&quot;: …, &quot;level&quot;: &quot;&quot;}</code> when lifted.</p>\n<h2 id=\"get-moderation-verifications\">GET /moderation/verifications</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong>—</p>\n<p>The accounts this instance verified, newest first, and the verifying account: <code>{&quot;verifier&quot;: {&quot;actor_id&quot;, &quot;account&quot;, &quot;name&quot;, &quot;did&quot;} or null, &quot;publishing&quot;, &quot;verifications&quot;: [{&quot;actor_id&quot;, &quot;account&quot;, &quot;name&quot;, &quot;did&quot;, &quot;local&quot;, &quot;verified_by&quot;, &quot;created_at&quot;}]}</code>. <code>publishing</code> is whether verifications are published (Bluesky on, and a verifying account with a DID); <code>did</code> is <code>&#39;&#39;</code> for an account verified here only; <code>verified_by</code> is the moderator&#39;s user id.</p>\n<h2 id=\"post-moderation-verifications\">POST /moderation/verifications</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>account</code> (required: a handle, a numeric account id or an actor id)</p>\n<p>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 <code>app.bsky.graph.verification</code> record. Answers <code>{&quot;actor_id&quot;, &quot;verification&quot;}</code>, the entity&#39;s new <code>verification</code>. An account nobody can find is a <strong>404</strong>.</p>\n<h2 id=\"delete-moderation-verifications\">DELETE /moderation/verifications</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>account</code> (required, as above)</p>\n<p>Takes the verification back, and its published record. Answers <code>{&quot;actor_id&quot;, &quot;verification&quot;: null}</code>; an account that is not verified is a <strong>404</strong>.</p>\n<h2 id=\"post-moderation-statuses-remove\">POST /moderation/statuses/remove</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>streamId</code> (required)</p>\n<p>Deletes one post, whoever wrote it. Returns <code>{&quot;stream_id&quot;: …}</code>. Reached from the <strong>Take down</strong> 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.</p>\n<h2 id=\"get-admin-announcements\">GET /admin/announcements</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong>—</p>\n<p>Every announcement, newest first, as the administration page shows one: <code>id</code>, <code>text</code> (as typed, not HTML), <code>starts_at</code>, <code>ends_at</code>, <code>all_day</code>, <code>published_at</code> and <code>active</code> — 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.</p>\n<h2 id=\"post-admin-announcements\">POST /admin/announcements</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>text</code> (required), <code>starts_at</code>, <code>ends_at</code>, <code>all_day</code> (false)</p>\n<p>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&#39;s own rule) and an end not after its start are each a <strong>422</strong>. <code>all_day</code> 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.</p>\n<h2 id=\"delete-admin-announcements-id\">DELETE /admin/announcements/{id}</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong>—</p>\n<p>Removes the announcement and every dismissal of it, for everybody, read or not, and answers with what is left. An unknown id is a <strong>404</strong>.</p>\n<h2 id=\"post-admin-server\">POST /admin/server</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>contactEmail</code>, <code>contactAccount</code> (empty), <code>extendedDescription</code>, <code>maxSize</code> (10), <code>maxVideoSize</code> (2048), <code>inboxThrottle</code> (300), <code>secureMode</code> (false), <code>publishBlocks</code> (false), <code>allowSelfSigned</code> (false)</p>\n<p>The Server card of the settings page: the instance-wide settings that had no interface at all and could only be set with <code>occ config:app:set social</code>. Writes all of them or none, and answers with what stands afterwards — the same shape the page is rendered from. <code>contactAccount</code> accepts a local Aloha Social username (with or without a leading <code>@</code>) 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 <strong>422</strong>. A refusal names the field: <code>contactEmail</code> must be an address (or empty) and at most 255 characters, <code>extendedDescription</code> at most 10000, <code>maxSize</code> 1–10240 MB, <code>maxVideoSize</code> 1–102400 MB, <code>inboxThrottle</code> 0–100000 requests per instance per minute (0 disables it). Unlike every other route in this table this one is <strong>not</strong> delegated: it carries no <code>AuthorizedAdminSetting</code>, 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 <code>imageMaxEdge</code> (0, or 480–16384 pixels — the longest edge a <strong>stored</strong> picture may have; <code>0</code> keeps every upload exactly as it arrived, which is the default and the only value that loses nothing) and <code>imageQuality</code> (40–100), consulted only when the first is set.</p>\n<h2 id=\"get-admin-notification-policy\">GET /admin/notification-policy</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>—</p>\n<p>What the notification policy of an account <strong>created from now on</strong> starts as: the five keys of <code>/api/v1/notifications/policy</code>, each <code>accept</code> or <code>filter</code>. Until an administrator chooses it is the calm policy (<code>for_not_following</code>, <code>for_new_accounts</code>, <code>for_private_mentions</code>, <code>for_limited_accounts</code> <code>filter</code>; <code>for_not_followers</code> <code>accept</code>). Stored as the app value <code>notification_policy_defaults</code> (JSON). Not delegated, like <code>/admin/server</code>.</p>\n<h2 id=\"post-admin-notification-policy\">POST /admin/notification-policy</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>any of the five keys</p>\n<p>Changes it and answers all five. A key with any value but <code>accept</code> or <code>filter</code> refuses the whole change with <strong>422</strong> <code>{&quot;error&quot;: &quot;…&quot;}</code> and nothing is written: an administrator decides whether something waits for review, never that it is discarded for somebody who has not chosen that. <strong>Existing accounts are never touched</strong>; each keeps the policy it has.</p>\n<h2 id=\"post-admin-sections\">POST /admin/sections</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>stories</code> (true), <code>photos</code> (true), <code>videos</code> (true), <code>groupLists</code> (<code>[]</code>)</p>\n<p>The Features section of the administration page: what this instance offers the people using it. The three switches decide whether stories (the web client&#39;s 24-hour shorts) are taken at all and whether the Photos and Videos timelines appear in the sidebar; all three are <strong>on</strong> by default, and turning one off hides the section without touching a single post. <code>groupLists</code> is the Nextcloud groups whose members each get a list for the group — <strong>empty by default</strong>, 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 <strong>400</strong> naming what it would not take: a group id that names no group, or more than 100 groups. Not delegated, for the same reason <code>/admin/server</code> is not: it is a decision about the instance rather than about a report.</p>\n<h2 id=\"post-admin-interests\">POST /admin/interests</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>enabled</code> (true), <code>learningDefault</code> (true), <code>halfLife</code> (30), <code>threshold</code> (3), <code>cap</code> (30), <code>window</code> (7)</p>\n<p>The For you card. <code>enabled</code> 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. <code>learningDefault</code> 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. <code>halfLife</code> (7–180 days) is how long a learned score takes to halve, <code>threshold</code> (0.5–20) the score a learned tag needs to be listed, <code>cap</code> (5–100) how many interests are listed, and <code>window</code> (1–30 days) how far back the feed looks. Writes all of it or none; a value out of range is a <strong>400</strong> naming it.</p>\n<h2 id=\"get-admin-relays\">GET /admin/relays</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>—</p>\n<p><strong>The relays this instance subscribes to</strong>, newest first: <code>{&quot;id&quot;, &quot;actor_id&quot;, &quot;host&quot;, &quot;inbox&quot;, &quot;status&quot;, &quot;error&quot;, &quot;created_at&quot;, &quot;last_update&quot;}</code>. <code>status</code> is <code>pending</code> (the <code>Follow</code> has gone out), <code>accepted</code> (posts flow both ways) or <code>rejected</code> (the relay said no, or could not be reached — <code>error</code> says which).</p>\n<h2 id=\"post-admin-relays\">POST /admin/relays</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>address</code> (the relay actor, e.g. <code>https://relay.example/actor</code>)</p>\n<p>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 <strong>422</strong> saying so. A <code>Follow{object: as:Public}</code> — what Mastodon sends and what relay software reads as &quot;subscribe me&quot; — is then signed by the <strong>instance actor</strong> and delivered inline, because the delivery queue resolves its signing key from <code>social_actor</code> and the instance actor is deliberately not a row there. Answers with the row, which will say <code>pending</code>: the relay answers in its own time. Subscribing twice is the same row.</p>\n<h2 id=\"post-admin-verifications-verifier\">POST /admin/verifications/verifier</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>account</code> (a local username, or empty for none)</p>\n<p>Chooses the local account the instance verifies in the name of: its name is the <code>by</code> 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 <code>{&quot;verifier&quot;, &quot;publishing&quot;}</code> as above; an account that is not local, or not found, is a <strong>422</strong>.</p>\n<h2 id=\"get-admin-bluesky\">GET /admin/bluesky</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>—</p>\n<p>The Bluesky card: the settings (<code>enabled</code>, <code>relays</code>, <code>plc_directory</code>, <code>appview</code>, <code>jetstream</code>, <code>chat</code>, <code>sync_ceiling</code>), the numbers (identities, repositories, events in the replay window, the head sequence number, the daemon&#39;s last report, the rotation key&#39;s age) and the requirement checks, run fresh.</p>\n<h2 id=\"post-admin-bluesky\">POST /admin/bluesky</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>any of <code>enabled</code>, <code>relays</code> (a list of origins), <code>plc_directory</code>, <code>appview</code>, <code>jetstream</code>, <code>chat</code> (Bluesky&#39;s chat service, an https origin, or empty to turn direct messages off), <code>sync_ceiling</code></p>\n<p>Saves what is sent. Switching on needs every requirement check to pass — https, <code>*.&lt;host&gt;</code> in <code>trusted_domains</code>, the root rules, the handle host, the daemon, the firehose proxy — and answers <strong>422</strong> with the card and an <code>error</code> otherwise; switching off always works.</p>\n<h2 id=\"get-admin-bluesky-figures\">GET /admin/bluesky/figures</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>—</p>\n<p>The <em>Bluesky figures</em> section, counted from this server&#39;s own tables and app values with no request elsewhere, and cached for a minute. While Bluesky is switched off it answers only <code>{&quot;enabled&quot;: false}</code>. Otherwise <code>enabled</code>, <code>computed</code> (when it was counted), <code>accounts</code> (<code>identities</code>, the local accounts with a Bluesky identity, and <code>off</code>, those whose owners switched their presence there off), <code>posts</code> (<code>day</code>, <code>week</code>: post records written to the local repositories in the last 24 hours and 7 days, not counting the records a moved-in repository brought), <code>repositories</code> (<code>count</code>, <code>records</code>, <code>blob_bytes</code>, summed from the repository heads), <code>reader</code> (<code>watched</code>, the Bluesky accounts read; <code>jetstream</code>, whether an endpoint is set; <code>jetstream_lag</code>, seconds between now and the stored Jetstream cursor, <code>null</code> without one) and <code>firehose</code> (<code>running</code>; <code>subscribers</code> as the daemon last reported them, <code>null</code> while it is not running; <code>head_seq</code> and <code>head_time</code> of the newest event; <code>events_kept</code>, the events in the replay window).</p>\n<h2 id=\"post-admin-bluesky-crawl\">POST /admin/bluesky/crawl</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>—</p>\n<p>Sends <code>com.atproto.sync.requestCrawl</code> to every configured relay now; answers <code>results</code>, relay → <code>ok</code> or the reason.</p>\n<h2 id=\"get-admin-bluesky-blocks\">GET /admin/bluesky/blocks</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>—</p>\n<p>The Bluesky block list: <code>blocks</code>, each <code>kind</code> (<code>did</code> or <code>host</code>), <code>value</code>, <code>reason</code>, <code>creation</code></p>\n<h2 id=\"post-admin-bluesky-blocks\">POST /admin/bluesky/blocks</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>target</code> (a DID or a PDS host), <code>reason</code></p>\n<p>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 <code>purged</code>. 422 for a target that is neither a DID nor a host</p>\n<h2 id=\"delete-admin-bluesky-blocks\">DELETE /admin/bluesky/blocks</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>target</code></p>\n<p>Takes it off the list; answers the list</p>\n<h2 id=\"get-api-v1-social-bluesky-identity\">GET /api/v1/social/bluesky/identity</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s own Bluesky identity — <code>handle</code>, <code>did</code>, <code>url</code> (the bsky.app profile), <code>state</code>, <code>active</code> (false while the viewer has switched their presence on Bluesky off), whether a <code>recovery_key</code> was issued — made now when there is none yet, and the profile record written while it is on. <strong>404</strong> when Bluesky is off. On this and the other <code>bluesky/*</code> account routes, a key of this server that the instance secret no longer opens is <strong>503</strong> <code>{&quot;error&quot;: &quot;This server&#39;s keys need to be re-sealed by an administrator (occ social:atproto:keys:reseal)&quot;, &quot;code&quot;: &quot;keys-sealed&quot;}</code>.</p>\n<h2 id=\"post-api-v1-social-bluesky-recovery\">POST /api/v1/social/bluesky/recovery</h2>\n<p><strong>Auth: </strong>user, csrf, password confirmation · <strong>Parameters: </strong>—</p>\n<p>Issues a recovery phrase: twelve words that are the private half of a key listed second, after the instance&#39;s, on the account&#39;s DID. Answers <code>phrase</code>, <code>key</code> — the same key as other atproto tools take it: <code>multibase</code> (<code>z…</code>, what <code>goat plc sign --plc-signing-key</code> reads), <code>hex</code>, and the public <code>did_key</code> — and the identity. Shown once and never stored; a second call issues a new key and the old words stop working.</p>\n<h2 id=\"get-bluesky-recovery\">GET /bluesky-recovery</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The offline recovery tool: one HTML page, its script inline (allowed by its CSP hash; <code>connect-src https:</code>), its strings in the viewer&#39;s language and the BIP-39 word list. It moves a DID to another server with the person&#39;s recovery key — see Moving.md &quot;If this server goes away&quot;. <strong>503</strong> <code>tool-missing</code> when the app&#39;s JavaScript is not built</p>\n<h2 id=\"get-bluesky-recovery-download\">GET /bluesky-recovery/download</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The same page as a file to keep, <code>bluesky-recovery-tool.html</code></p>\n<h2 id=\"get-api-v1-social-bluesky-control\">GET /api/v1/social/bluesky/control</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>Who controls the viewer&#39;s DID, read from the PLC directory&#39;s audit log (kept a minute, and asked again at once after this server confirmed an operation): <code>rotation_keys</code> (highest first, each <code>{key, role}</code>, <code>role</code> one of <code>server</code>, <code>server-retired</code>, <code>recovery</code>, <code>unknown</code>), <code>state</code> (<code>active</code>, <code>tombstoned</code>), <code>last_operation</code> (<code>cid</code>, <code>created_at</code>, <code>signed_by</code>), and <code>undo</code> — <code>{until, by}</code> while a key ranking above the one that signed the latest operation can still nullify it (72 hours), else <code>null</code>. Times are unix seconds. <strong>404</strong> <code>no-identity</code> or <code>did-not-found</code>, <strong>503</strong> <code>directory-unreachable</code></p>\n<h2 id=\"get-api-v1-social-bluesky-archive\">GET /api/v1/social/bluesky/archive</h2>\n<p><strong>Auth: </strong>user, no-csrf (a download the browser navigates to), password confirmation, 3 per hour per user · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s Bluesky account as a zip, sent while it is written — the files stored, not compressed, with no <code>Content-Length</code> — so the first bytes go out at once and nothing of it is kept on disk: <code>bluesky/repo.car</code> (the repository, as <code>getRepo</code> streams it), <code>bluesky/blobs/&lt;cid&gt;</code> (every blob that still reads; the ones that do not are named in the README), <code>bluesky/plc-log.json</code> (the PLC directory&#39;s audit log, or the operations this server confirmed when the directory cannot be asked), <code>bluesky/did.json</code>, <code>bluesky/recovery/recovery-key.py</code> with the BIP-39 word list it reads, <code>bluesky/recovery/bluesky-recovery-tool.html</code> (the recovery tool, where the JavaScript is built), and <code>bluesky/README.txt</code> (what each file is, and the goat steps to move the account with the recovery phrase). Downloads as <code>bluesky-&lt;handle&gt;-&lt;date&gt;.zip</code>. <strong>404</strong> <code>no-identity</code> 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.</p>\n<h2 id=\"post-api-v1-social-bluesky-publish-blocks\">POST /api/v1/social/bluesky/publish-blocks</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>publish</code> (bool)</p>\n<p>Whether the viewer&#39;s blocks of Bluesky accounts go to Bluesky as <code>app.bsky.graph.block</code> 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 <code>publish_blocks</code>; <code>GET …/identity</code> carries it too. Off unless the viewer turns it on. <strong>404</strong> without a Bluesky identity</p>\n<h2 id=\"post-api-v1-social-bluesky-state\">POST /api/v1/social/bluesky/state</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>active</code> (bool)</p>\n<p>Switches the viewer&#39;s own presence on Bluesky off or on (&quot;Be on Bluesky&quot;, spec §4.6). Off, the account is deactivated there: announced inactive on the firehose and by <code>getRepoStatus</code>, 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 <code>GET …/identity</code> does, <code>active</code> included, with <code>publish_blocks</code>; 404 when there is no identity here to switch.</p>\n<h2 id=\"post-api-v1-social-bluesky-handle\">POST /api/v1/social/bluesky/handle</h2>\n<p><strong>Auth: </strong>user, csrf, password confirmation · <strong>Parameters: </strong><code>handle</code></p>\n<p>Makes a domain the viewer owns their Bluesky handle, once <code>_atproto.&lt;domain&gt;</code> (TXT <code>did=&lt;DID&gt;</code>) or <code>https://&lt;domain&gt;/.well-known/atproto-did</code> names their DID: the DID document is updated and the firehose tells the network. <strong>422</strong> with a sentence and a <code>code</code> (the ATProto identity error codes) when the domain does not name the DID yet (<code>handle-not-verified</code>), is not a domain name (<code>handle-domain-invalid</code>), is under this server&#39;s handle host (<code>handle-reserved</code>), or is another account&#39;s (<code>handle-in-use</code>), or the account is switched off (<code>identity-inactive</code>). Answers the identity, now with <code>assigned_handle</code>, <code>custom_handle</code> and <code>custom_handle_broken</code> (the daily check no longer finds the record)</p>\n<h2 id=\"delete-api-v1-social-bluesky-handle\">DELETE /api/v1/social/bluesky/handle</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong>—</p>\n<p>The handle this server assigned, again; answers the identity</p>\n<h2 id=\"get-api-v1-social-bluesky-move\">GET /api/v1/social/bluesky/move</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s latest move of their Bluesky account, or <code>null</code>: <code>direction</code> (<code>away</code>, <code>in</code>, <code>inbound</code>), <code>pds</code>, <code>handle</code> (there), <code>step</code> (<code>repo</code>, <code>blobs</code>, <code>prefs</code>, <code>identity</code>, <code>activate</code>, <code>follows</code>, <code>code</code>, <code>invited</code>, <code>posts</code>, <code>done</code>), <code>state</code> (<code>running</code>, <code>waiting</code>, <code>needs_decision</code>, <code>failed</code>, <code>cancelled</code>, <code>done</code>), <code>progress</code> (<code>progress.missing</code>, the pictures and videos that did not arrive, and <code>progress.missing_records</code>, the first 20 records that lose them, each <code>collection</code>, <code>rkey</code>, <code>created_at</code>, <code>text</code> (a post&#39;s first 120 characters) and <code>url</code> (the post here, else its address on Bluesky; &#39;&#39; for the profile); for a move away <code>progress.stage</code>: <code>account_created</code>, <code>repo_copied</code>, <code>identity_switched</code>, <code>activated</code>, <code>done</code>; and <code>progress.code</code> once it stopped), <code>error</code>. <code>posts_on_bluesky</code>: how many of the viewer&#39;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 <code>move</code>, who controls the account once it moved away: <code>has_recovery_key</code>, <code>rotation_keys</code> (the handover&#39;s rotation keys by role, never the keys: <code>[&quot;recovery&quot;, &quot;new_server&quot;]</code>, or <code>[&quot;new_server&quot;]</code> without a recovery key — this server keeps none) and <code>new_host</code> (the other server&#39;s host once a move away is done, else <code>null</code>)</p>\n<h2 id=\"post-api-v1-social-bluesky-move\">POST /api/v1/social/bluesky/move</h2>\n<p><strong>Auth: </strong>user, csrf, password confirmation, 3 per hour per user · <strong>Parameters: </strong><code>pds</code>, <code>handle</code>, <code>email</code>, <code>password</code>, <code>inviteCode</code>, <code>without_recovery</code>, <code>announce</code></p>\n<p>Moves the viewer&#39;s Bluesky account to another PDS. <code>announce</code> (<code>post</code>, <code>profile</code> or <code>none</code>, the default) says where the account went once the move is done: one public post, or a profile field &quot;Also at&quot; with the new address (<code>progress.announced</code>, and <code>progress.announce_code</code> when it could not be written); <strong>422</strong> <code>announce-invalid</code> for anything else. Without a recovery key the request has to say <code>without_recovery: true</code> (only the other server controls the account afterwards), else <strong>422</strong> <code>recovery-key-missing</code>: 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. <strong>422</strong> with the other server&#39;s reason when it refuses, or when another move is under way. Every error carries a <code>code</code> beside the sentence (the ATProto identity error codes), and a stopped move keeps it as <code>progress.code</code></p>\n<h2 id=\"delete-api-v1-social-bluesky-move\">DELETE /api/v1/social/bluesky/move</h2>\n<p><strong>Auth: </strong>user, csrf, password confirmation · <strong>Parameters: </strong>—</p>\n<p>Calls off a move away before the DID moved (<code>state</code> <code>cancelled</code>). The account made on the other server stays there, deactivated — deleting it takes a code that server e-mails — so the answer says so: <code>{&quot;move&quot;, &quot;code&quot;: &quot;target-account-left&quot;, &quot;host&quot;}</code>. <strong>422</strong> <code>move-past-switch</code> once the DID points at the other server (&quot;Try again&quot; finishes the move from where it stopped; a move that failed handing the DID over is asked of the directory first), <code>move-switching</code> while it is being pointed there, <code>plc-unreachable</code> while the directory cannot be asked whether it took the handover, <code>no-move-to-call-off</code></p>\n<h2 id=\"post-api-v1-social-bluesky-move-continue\">POST /api/v1/social/bluesky/move/continue</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>without_missing</code></p>\n<p>Goes on with a move away that stopped before the DID moved for the viewer to decide (<code>state</code> <code>needs_decision</code>, <code>progress.code</code> <code>blobs-missing</code> with <code>progress.missing</code>, or <code>repo-incomplete</code>): with <code>without_missing: true</code> the DID moves now without what is missing, else the blobs (or the repository) are copied again and checked again. <strong>422</strong> <code>no-decision-pending</code></p>\n<h2 id=\"post-api-v1-social-bluesky-follow-from\">POST /api/v1/social/bluesky/follow-from</h2>\n<p><strong>Auth: </strong>user, csrf, 5 per hour per user · <strong>Parameters: </strong><code>account</code> (a Bluesky handle or DID)</p>\n<p>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 <code>bluesky_follows</code> import reads its public follow records (<code>com.atproto.repo.listRecords</code>, no password, at most 5000 accounts and 100 pages) and follows each from the viewer&#39;s account through the ordinary follow path; one already followed is skipped. Answers <strong>202</strong> <code>{&quot;import&quot;, &quot;account&quot;: {&quot;did&quot;, &quot;pds&quot;, &quot;handle&quot;}}</code>; <code>GET /api/v1/migration/imports</code> is where it gets to (<code>report.failed</code>: DID → reason). Only a move brings followers. <strong>422</strong> with a <code>code</code>: <code>handle-invalid</code>, <code>handle-not-found</code>, <code>did-not-supported</code> (not a <code>did:plc</code>), <code>did-not-found</code>, <code>plc-unreachable</code>, <code>pds-address-invalid</code>, <code>import-in-progress</code>; <strong>404</strong> <code>bluesky-off</code></p>\n<h2 id=\"get-api-v1-social-bluesky-move-target\">GET /api/v1/social/bluesky/move/target</h2>\n<p><strong>Auth: </strong>user, 30 per hour per user · <strong>Parameters: </strong><code>pds</code></p>\n<p>What a PDS the viewer may move to says of itself (<code>describeServer</code>, asked through the outbound guard that refuses local addresses): <code>{&quot;pds&quot;, &quot;did&quot;, &quot;availableUserDomains&quot;, &quot;inviteCodeRequired&quot;}</code>, so the form can offer the handle domains before anything starts. <strong>422</strong> with a <code>code</code> when it cannot be asked (<code>pds-unreachable</code>, also for an address this server does not send requests to, <code>pds-unknown</code>, …), <strong>404</strong> <code>no-identity</code></p>\n<h2 id=\"post-api-v1-social-bluesky-move-retry\">POST /api/v1/social/bluesky/move/retry</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong>—</p>\n<p>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; <strong>422</strong> when there is none (<code>no-failed-move</code>), <code>plc-unreachable</code> while the directory cannot be asked whether it took the handover</p>\n<h2 id=\"get-api-v1-social-bluesky-bridgy-twin\">GET /api/v1/social/bluesky/bridgy-twin</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>search</code> (<code>1</code> to ask Bluesky&#39;s search)</p>\n<p><code>{&quot;twin&quot;: {&quot;handle&quot;, &quot;did&quot;}}</code> when Bridgy Fed bridges the viewer&#39;s Fediverse account to Bluesky — the handle Bridgy gives it (<code>alice.social.example.com.ap.brid.gy</code>) resolves, through the AppView or its DNS record, to a DID whose PDS is Bridgy&#39;s; with <code>search</code>, Bluesky&#39;s search is given the viewer&#39;s Fediverse address and a result taken only when its DID document names the viewer&#39;s actor — else <code>{&quot;twin&quot;: null}</code>. <code>handle</code> is the twin&#39;s handle now</p>\n<h2 id=\"post-api-v1-social-bluesky-move-invite\">POST /api/v1/social/bluesky/move-invite</h2>\n<p><strong>Auth: </strong>user, csrf, password confirmation, 5 per hour per user · <strong>Parameters: </strong><code>account</code> (handle or DID)</p>\n<p>Invites a Bluesky account to move here driven by the other side (<code>state</code> <code>waiting</code>, <code>step</code> <code>invited</code>, good for a day). For a Bridgy Fed twin the viewer&#39;s account sends Bridgy&#39;s bot the <code>migrate-to</code> command as a direct message; for anything else the answer carries what a migration tool needs: <code>{&quot;move&quot;, &quot;bridgy&quot;, &quot;pds&quot;, &quot;handle&quot;, &quot;email&quot;, &quot;code&quot;}</code> — the one-time code, shown only now, is both the password and the invite code. <strong>422</strong> when the account is here already, another move is under way, or Bridgy could not be sent the message</p>\n<h2 id=\"delete-api-v1-social-bluesky-move-invite\">DELETE /api/v1/social/bluesky/move-invite</h2>\n<p><strong>Auth: </strong>user, csrf, password confirmation · <strong>Parameters: </strong>—</p>\n<p>Calls off an inbound move that has not finished: what arrived of the repository and its blobs is dropped and its session ends. <strong>422</strong> when there is none</p>\n<h2 id=\"post-api-v1-social-bluesky-move-in\">POST /api/v1/social/bluesky/move-in</h2>\n<p><strong>Auth: </strong>user, csrf, password confirmation, 5 per hour per user · <strong>Parameters: </strong><code>handle</code> (or DID), <code>password</code> (the Bluesky account&#39;s own, not an app password, and not kept), <code>authFactorToken</code></p>\n<p>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, <strong>422</strong> <code>rate-limited</code> past that), and the copy of the repository, blobs and preferences follows in the background, until the old PDS e-mails a code (<code>state</code> <code>waiting</code>, <code>step</code> <code>code</code>; <code>progress.code_sent_to</code> is the address it went to, &#39;&#39; when the old PDS does not say). The viewer&#39;s Bluesky account here so far is retired once the move is done; the follows come over after the DID. <strong>422</strong> when the sign-in is refused, the account is here already, or another move is under way</p>\n<h2 id=\"delete-api-v1-social-bluesky-move-in\">DELETE /api/v1/social/bluesky/move-in</h2>\n<p><strong>Auth: </strong>user, csrf, password confirmation · <strong>Parameters: </strong>—</p>\n<p>Calls off the viewer&#39;s move here while the DID has not switched: it ends in <code>state</code> <code>cancelled</code>, the session on the old PDS is ended and dropped, and the copied repository and blobs are deleted. <strong>422</strong> <code>move-past-switch</code> once the PLC operation may have been sent, <code>no-move-to-call-off</code> when there is none</p>\n<h2 id=\"post-api-v1-social-bluesky-move-in-code\">POST /api/v1/social/bluesky/move-in/code</h2>\n<p><strong>Auth: </strong>user, csrf, 3 per hour per user · <strong>Parameters: </strong>—</p>\n<p>Asks the old PDS again to e-mail the code a waiting move needs. Answers the move and <code>sent_to</code>, the address the code went to, &#39;&#39; when the old PDS does not say. <strong>422</strong> <code>no-move-waiting</code> when no move waits for a code</p>\n<h2 id=\"post-api-v1-social-bluesky-move-in-continue\">POST /api/v1/social/bluesky/move-in/continue</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>without_missing</code> (bool, false)</p>\n<p>The viewer&#39;s decision on a move here that stopped in state <code>needs_decision</code> because pictures or videos did not arrive (<code>progress.missing</code>: <code>count</code>, <code>cids</code>): <code>true</code> goes on without them, <code>false</code> copies them again first (from the old PDS, for a move driven by a tool too). Answers the move. <strong>422</strong> <code>no-decision-pending</code> when no move waits for one</p>\n<h2 id=\"post-api-v1-social-bluesky-move-in-republish\">POST /api/v1/social/bluesky/move-in/republish</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong>—</p>\n<p>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&#39;s, <code>progress.republish</code>) again, into the moved repository, in the background. Answers the move. <strong>422</strong> <code>nothing-to-republish</code>, <code>republish-queued</code></p>\n<h2 id=\"post-api-v1-social-bluesky-move-code\">POST /api/v1/social/bluesky/move/code</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>code</code></p>\n<p>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. <strong>422</strong> when no move waits for one</p>\n<h2 id=\"get-api-v1-social-bluesky-labelers\">GET /api/v1/social/bluesky/labelers</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s Bluesky labelers: Bluesky&#39;s own moderation service first (<code>removable</code> false), then the ones subscribed to, each with <code>did</code>, <code>name</code> and <code>labels</code> — every label value it declares with its <code>name</code>, <code>description</code> and the viewer&#39;s <code>setting</code> (<code>ignore</code>, <code>warn</code> or <code>hide</code>; the labeler&#39;s default until changed)</p>\n<h2 id=\"post-api-v1-social-bluesky-labelers\">POST /api/v1/social/bluesky/labelers</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>labeler</code> (a handle or a DID)</p>\n<p>Subscribes the viewer; 422 when it is not a Bluesky labeler. Answers the list</p>\n<h2 id=\"delete-api-v1-social-bluesky-labelers\">DELETE /api/v1/social/bluesky/labelers</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>did</code></p>\n<p>Unsubscribes the viewer; Bluesky&#39;s own cannot be removed. Answers the list</p>\n<h2 id=\"put-api-v1-social-bluesky-labelers-setting\">PUT /api/v1/social/bluesky/labelers/setting</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>did</code>, <code>label</code>, <code>setting</code></p>\n<p>What one label of a subscribed labeler does: <code>ignore</code>, <code>warn</code> (the post carries a filter result naming the label) or <code>hide</code> (the post is left out). Answers the list</p>\n<h2 id=\"get-api-v1-social-bluesky-app-passwords\">GET /api/v1/social/bluesky/app-passwords</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The viewer&#39;s app passwords for Bluesky apps: <code>app_passwords</code>, each <code>id</code>, <code>name</code>, <code>creation</code>, <code>last_used</code> — never the password</p>\n<h2 id=\"post-api-v1-social-bluesky-app-passwords\">POST /api/v1/social/bluesky/app-passwords</h2>\n<p><strong>Auth: </strong>user, csrf, password confirmation · <strong>Parameters: </strong><code>name</code>, <code>privileged</code> (false)</p>\n<p>Makes one: <code>id</code>, <code>name</code>, <code>privileged</code> and the <code>password</code> (four groups of four, as Bluesky&#39;s), the only time it is shown, with the list (each with <code>privileged</code>). A privileged one lets the app reach the account&#39;s Bluesky direct messages, as Bluesky&#39;s privileged app passwords do. <strong>422</strong> with a sentence and a <code>code</code> for an empty or overlong name (<code>app-password-name-invalid</code>), a taken one (<code>app-password-name-taken</code>), or past 25 (<code>app-password-limit</code>)</p>\n<h2 id=\"delete-api-v1-social-bluesky-app-passwords-id\">DELETE /api/v1/social/bluesky/app-passwords/{id}</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong>—</p>\n<p>Revokes it, and every Bluesky app signed in with it; answers the list</p>\n<h2 id=\"get-api-v1-social-bluesky-oauth-sessions\">GET /api/v1/social/bluesky/oauth-sessions</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The Bluesky apps the viewer signed in to with Bluesky sign-in (OAuth): <code>sessions</code>, each <code>id</code>, <code>client_id</code> (the app&#39;s metadata address, the one thing about it that is checked), <code>client</code> (its host), <code>scopes</code>, <code>created</code>, <code>last_used</code></p>\n<h2 id=\"delete-api-v1-social-bluesky-oauth-sessions-id\">DELETE /api/v1/social/bluesky/oauth-sessions/{id}</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong>—</p>\n<p>Signs that app out: its tokens stop working at once; answers the list</p>\n<h2 id=\"get-api-v1-social-bluesky-feeds\">GET /api/v1/social/bluesky/feeds</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The Bluesky custom feeds and lists the viewer keeps — their Bluesky preference <code>savedFeedsPrefV2</code>, the one a Bluesky app signed in here keeps too — pinned first: <code>feeds</code>, each <code>uri</code> (<code>at://</code>), <code>type</code> (<code>feed</code> or <code>list</code>), <code>name</code>, <code>description</code>, <code>avatar</code>, <code>creator</code> (a handle), <code>pinned</code>. One the AppView no longer knows is left out. <strong>404</strong> when Bluesky is off; <strong>422</strong> when the viewer has no Bluesky identity; <strong>502</strong> when the AppView does not answer</p>\n<h2 id=\"post-api-v1-social-bluesky-feeds\">POST /api/v1/social/bluesky/feeds</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>feed</code> (an <code>at://</code> URI, or a bsky.app address of a feed or a list)</p>\n<p>Keeps it, pinned; answers <code>feed</code>. <strong>422</strong> when it is not a feed or list the AppView knows</p>\n<h2 id=\"delete-api-v1-social-bluesky-feeds\">DELETE /api/v1/social/bluesky/feeds</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>uri</code></p>\n<p>Stops keeping it; answers <code>{}</code></p>\n<h2 id=\"get-api-v1-social-bluesky-feeds-suggested\">GET /api/v1/social/bluesky/feeds/suggested</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The feeds Bluesky suggests to the viewer (<code>getSuggestedFeeds</code>), as <code>feeds</code> in the same shape; empty when the AppView does not answer</p>\n<h2 id=\"get-api-v1-social-bluesky-starter-pack\">GET /api/v1/social/bluesky/starter-pack</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>pack</code> (a bsky.app starter-pack address, or its <code>at://</code> URI)</p>\n<p>The starter pack, read from the AppView as the viewer where they are on Bluesky: <code>pack</code> with <code>uri</code>, <code>url</code>, <code>name</code>, <code>description</code>, <code>joined</code> (how many joined with it), <code>creator</code> (<code>did</code>, <code>handle</code>, <code>name</code>, <code>avatar</code>), <code>members</code> (at most 150, each <code>did</code>, <code>handle</code>, <code>name</code>, <code>avatar</code>, <code>description</code>, <code>following</code> — whether the viewer follows them on Bluesky) and <code>feeds</code> (as <code>GET …/feeds</code> describes one). <strong>422</strong> for an address that is not a starter pack&#39;s, or one Bluesky does not know</p>\n<h2 id=\"post-api-v1-social-bluesky-starter-pack-follow\">POST /api/v1/social/bluesky/starter-pack/follow</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>pack</code>, <code>dids</code> (at most 25), <code>feeds</code> (bool, false)</p>\n<p>Follows the members named — only ones in the pack — as any Bluesky account is followed, and with <code>feeds</code> keeps the pack&#39;s feeds. Answers <code>followed</code> and <code>failed</code>, each a list of DIDs. <strong>422</strong> for more than 25 at once</p>\n<h2 id=\"get-api-v1-social-bluesky-trends\">GET /api/v1/social/bluesky/trends</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The topics trending on Bluesky (<code>app.bsky.unspecced.getTrendingTopics</code>), kept ten minutes: <code>trends</code>, each <code>topic</code>, <code>label</code>, and either <code>feed</code> (the <code>at://</code> URI of the custom feed it opens) or <code>search</code> (the text to search for). Empty where the AppView has no trends</p>\n<h2 id=\"get-api-v1-social-bluesky-suggestions\">GET /api/v1/social/bluesky/suggestions</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong>—</p>\n<p>The accounts Bluesky suggests to the viewer (<code>app.bsky.actor.getSuggestions</code>, as the viewer where they are on Bluesky), without ones they follow: <code>accounts</code>, each <code>id</code> (the DID), <code>acct</code> and <code>username</code> (the handle, which follows them here), <code>display_name</code>, <code>avatar</code>, <code>note</code> (the bio, escaped) and <code>url</code></p>\n<h2 id=\"get-api-v1-timelines-bluesky\">GET /api/v1/timelines/bluesky</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>feed</code> (required, the <code>at://</code> URI of a feed or a list), <code>limit</code> (20, at most 100), <code>max_id</code></p>\n<p>A page of the feed or list as statuses, read from the AppView as the viewer (<code>getFeed</code>, <code>getListFeed</code>), in the feed&#39;s own order. The next page is asked with <code>max_id</code> the id of the last status of this one; an empty answer is the end. <strong>422</strong> for a URI that is neither</p>\n<h2 id=\"get-well-known-oauth-protected-resource\">GET /.well-known/oauth-protected-resource</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The protected resource metadata of this PDS (AT Protocol OAuth): <code>resource</code> and <code>authorization_servers</code>, both this instance&#39;s origin. 404 while Bluesky is off. Served at the root through the web-server rules</p>\n<h2 id=\"post-oauth-par\">POST /oauth/par</h2>\n<p><strong>Auth: </strong>public, no-csrf, rate-limited · <strong>Parameters: </strong><code>client_id</code>, <code>response_type=code</code>, <code>code_challenge</code> (S256), <code>state</code>, <code>redirect_uri</code>, <code>scope</code> (with <code>atproto</code>), <code>login_hint</code>, <code>response_mode</code>, and for a confidential client <code>client_assertion_type</code>/<code>client_assertion</code>; a <code>DPoP</code> proof</p>\n<p>A Bluesky app&#39;s pushed authorization request: <strong>201</strong> <code>{request_uri, expires_in}</code>. The client metadata is fetched from the <code>client_id</code> and checked; a proof without this server&#39;s current nonce is answered <strong>400</strong> <code>use_dpop_nonce</code> with a <code>DPoP-Nonce</code> header, as every answer carries one. Errors are <code>{error, error_description}</code></p>\n<h2 id=\"options-oauth-par-oauth-token-oauth-revoke\">OPTIONS /oauth/par, /oauth/token, /oauth/revoke</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The CORS preflights of a Bluesky browser app</p>\n<h2 id=\"get-xrpc-method\">GET /xrpc/{method}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>the method&#39;s parameters</p>\n<p>The AT Protocol query surface of this instance as a PDS, served at the root through the web-server rules in <code>contrib/webserver</code>: <code>com.atproto.server.describeServer</code>; <code>com.atproto.identity.resolveHandle</code> (local and DNS/<code>.well-known</code> handles), <code>resolveDid</code> (local, PLC and <code>did:web</code> DIDs), and <code>resolveIdentity</code> (with a bi-directionally verified handle); <code>com.atproto.sync.getRepo</code> (a CAR), <code>getLatestCommit</code>, <code>getRepoStatus</code>, <code>getRecord</code> (a CAR of commit, tree and record), <code>getBlob</code>, <code>listBlobs</code>, <code>listRepos</code>, <code>com.atproto.repo.describeRepo</code>, <code>getRecord</code>, <code>listRecords</code>, and <code>_health</code>. <code>subscribeRepos</code> on this URL answers <strong>426</strong>: it is the WebSocket <code>occ social:atproto:serve</code> serves. Anything else is <strong>501</strong> <code>MethodNotImplemented</code>; errors are <code>{error, message}</code>.</p>\n<h2 id=\"post-xrpc-method\">POST /xrpc/{method}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>the method&#39;s body</p>\n<p>The procedure surface. <code>createSession</code>, <code>refreshSession</code> and <code>deleteSession</code> sign a Bluesky app in and out with an app password; <code>com.atproto.identity.refreshIdentity</code> re-resolves an identifier and returns its verified identity info without changing account state. With a signed-in session — an app password&#39;s bearer token, or a Bluesky sign-in (OAuth) token with its <code>DPoP</code> proof — <code>com.atproto.identity.updateHandle</code> validates and assigns the account&#39;s handle, including reverting to its assigned <code>alice.&lt;host&gt;</code> handle; OAuth requires <code>identity:handle</code> or <code>identity:*</code>. <code>putRecord</code> 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 <code>recordWithMedia</code>; the older <code>images</code> 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. <code>app.bsky.actor.link</code> records are kept as written, and profile <code>links</code> 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 <code>bluesky.links</code> as <code>{url, title}</code>. Repository writes, <code>uploadBlob</code>, preferences, <code>createReport</code> and the <code>app.bsky.*</code> procedures (passed to the AppView) are answered for the signed-in account; <code>uploadBlob</code> also takes a token the account signed for Bluesky&#39;s video service. Without a session, <strong>401</strong> <code>AuthenticationRequired</code>; without the required scope, <strong>403</strong> <code>InsufficientScope</code>; anything else <strong>501</strong>. <code>createAccount</code> makes an account only for a DID invited to move here, with its one-time code (as <code>password</code> or <code>inviteCode</code>) and a service-auth token the DID signs for this server (<strong>400</strong> <code>InvalidInviteCode</code>, <strong>401</strong> <code>AuthenticationRequired</code>); its session may only move the account: <code>checkAccountStatus</code>, <code>importRepo</code> (a CAR up to 64 MB, checked against the DID&#39;s key), <code>listMissingBlobs</code>, <code>uploadBlob</code> (kept byte for byte), <code>getRecommendedDidCredentials</code>, <code>submitPlcOperation</code> (only an operation naming this server and the recommended key), <code>activateAccount</code> (once the directory names them), preferences, <code>refreshSession</code>; anything else <strong>403</strong> <code>InsufficientScope</code>.</p>\n<h2 id=\"options-xrpc-method\">OPTIONS /xrpc/{method}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The CORS preflight a Bluesky web client sends. It is answered for every origin and allows the XRPC headers <code>Authorization</code>, <code>Content-Type</code>, <code>DPoP</code>, <code>X-Atproto-Session-Id</code>, <code>X-Atproto-Device-Id</code>, <code>X-Atproto-Bsky-Topics</code>, <code>X-Bsky-Topics</code>, <code>atproto-accept-labelers</code> and <code>atproto-proxy</code>; these headers are available on every PDS instance running this app, regardless of its domain. This XRPC policy is separate from the Fediverse <code>/api/</code> CORS policy above.</p>\n<h2 id=\"get-well-known-atproto-did\">GET /.well-known/atproto-did</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>handle</code> (optional; the request&#39;s host otherwise)</p>\n<p>The DID of the handle this request&#39;s host is, as plain text — what <code>https://alice.&lt;host&gt;/.well-known/atproto-did</code> answers once the wildcard host reaches the app. A handle that was never issued is a <strong>404</strong>.</p>\n<h2 id=\"get-well-known-did-json\">GET /.well-known/did.json</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The instance&#39;s own <code>did:web:&lt;host&gt;</code> document: its service key and the PDS endpoint.</p>\n<h2 id=\"delete-admin-relays-id\">DELETE /admin/relays/{id}</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>id</code></p>\n<p>Unsubscribes and forgets it. The <code>Undo{Follow}</code> is sent first and its failure does not stop the row going — an administrator who pressed this wants to stop taking that relay&#39;s posts, and nothing further is taken from it either way, because taking one in needs a row. An unknown id is a <strong>404</strong>.</p>\n<h2 id=\"post-moderation-retention\">POST /moderation/retention</h2>\n<p><strong>Auth: </strong>moderator, csrf · <strong>Parameters: </strong><code>days</code> (required, 0–3650)</p>\n<p>Sets the <code>retention_days</code> app setting: remote statuses older than this that no local user cares about are pruned (0 disables). Returns <code>{&quot;retentionDays&quot;: n}</code>.</p>\n","toc":[{"id":"get-moderation-reports","text":"GET /moderation/reports","level":2},{"id":"post-moderation-reports-id-resolve","text":"POST /moderation/reports/{id}/resolve","level":2},{"id":"get-moderation-review","text":"GET /moderation/review","level":2},{"id":"post-moderation-review-id-approve","text":"POST /moderation/review/{id}/approve","level":2},{"id":"post-moderation-review-id-reject","text":"POST /moderation/review/{id}/reject","level":2},{"id":"post-moderation-review-settings","text":"POST /moderation/review/settings","level":2},{"id":"post-moderation-accounts-sensitive","text":"POST /moderation/accounts/sensitive","level":2},{"id":"get-moderation-media-blocks","text":"GET /moderation/media/blocks","level":2},{"id":"post-moderation-media-blocks","text":"POST /moderation/media/blocks","level":2},{"id":"delete-moderation-media-blocks","text":"DELETE /moderation/media/blocks","level":2},{"id":"get-moderation-trends","text":"GET /moderation/trends","level":2},{"id":"post-moderation-trends","text":"POST /moderation/trends","level":2},{"id":"delete-moderation-trends","text":"DELETE /moderation/trends","level":2},{"id":"get-moderation-emojis","text":"GET /moderation/emojis","level":2},{"id":"post-moderation-emojis","text":"POST /moderation/emojis","level":2},{"id":"delete-moderation-emojis","text":"DELETE /moderation/emojis","level":2},{"id":"get-moderation-rules","text":"GET /moderation/rules","level":2},{"id":"post-moderation-rules","text":"POST /moderation/rules","level":2},{"id":"get-moderation-discover-categories","text":"GET /moderation/discover/categories","level":2},{"id":"post-moderation-discover-categories","text":"POST /moderation/discover/categories","level":2},{"id":"delete-moderation-discover-categories","text":"DELETE /moderation/discover/categories","level":2},{"id":"post-moderation-fediverse-add","text":"POST /moderation/fediverse/add","level":2},{"id":"post-moderation-fediverse-remove","text":"POST /moderation/fediverse/remove","level":2},{"id":"post-moderation-fediverse-access","text":"POST /moderation/fediverse/access","level":2},{"id":"post-moderation-fediverse-blocklist-preview","text":"POST /moderation/fediverse/blocklist/preview","level":2},{"id":"post-moderation-fediverse-blocklist-import","text":"POST /moderation/fediverse/blocklist/import","level":2},{"id":"get-moderation-fediverse-blocklist-sources","text":"GET /moderation/fediverse/blocklist/sources","level":2},{"id":"post-moderation-fediverse-blocklist-sources","text":"POST /moderation/fediverse/blocklist/sources","level":2},{"id":"post-moderation-fediverse-blocklist-fetch","text":"POST /moderation/fediverse/blocklist/fetch","level":2},{"id":"get-moderation-accounts","text":"GET /moderation/accounts","level":2},{"id":"get-moderation-accounts-history","text":"GET /moderation/accounts/history","level":2},{"id":"post-moderation-accounts","text":"POST /moderation/accounts","level":2},{"id":"get-moderation-verifications","text":"GET /moderation/verifications","level":2},{"id":"post-moderation-verifications","text":"POST /moderation/verifications","level":2},{"id":"delete-moderation-verifications","text":"DELETE /moderation/verifications","level":2},{"id":"post-moderation-statuses-remove","text":"POST /moderation/statuses/remove","level":2},{"id":"get-admin-announcements","text":"GET /admin/announcements","level":2},{"id":"post-admin-announcements","text":"POST /admin/announcements","level":2},{"id":"delete-admin-announcements-id","text":"DELETE /admin/announcements/{id}","level":2},{"id":"post-admin-server","text":"POST /admin/server","level":2},{"id":"get-admin-notification-policy","text":"GET /admin/notification-policy","level":2},{"id":"post-admin-notification-policy","text":"POST /admin/notification-policy","level":2},{"id":"post-admin-sections","text":"POST /admin/sections","level":2},{"id":"post-admin-interests","text":"POST /admin/interests","level":2},{"id":"get-admin-relays","text":"GET /admin/relays","level":2},{"id":"post-admin-relays","text":"POST /admin/relays","level":2},{"id":"post-admin-verifications-verifier","text":"POST /admin/verifications/verifier","level":2},{"id":"get-admin-bluesky","text":"GET /admin/bluesky","level":2},{"id":"post-admin-bluesky","text":"POST /admin/bluesky","level":2},{"id":"get-admin-bluesky-figures","text":"GET /admin/bluesky/figures","level":2},{"id":"post-admin-bluesky-crawl","text":"POST /admin/bluesky/crawl","level":2},{"id":"get-admin-bluesky-blocks","text":"GET /admin/bluesky/blocks","level":2},{"id":"post-admin-bluesky-blocks","text":"POST /admin/bluesky/blocks","level":2},{"id":"delete-admin-bluesky-blocks","text":"DELETE /admin/bluesky/blocks","level":2},{"id":"get-api-v1-social-bluesky-identity","text":"GET /api/v1/social/bluesky/identity","level":2},{"id":"post-api-v1-social-bluesky-recovery","text":"POST /api/v1/social/bluesky/recovery","level":2},{"id":"get-bluesky-recovery","text":"GET /bluesky-recovery","level":2},{"id":"get-bluesky-recovery-download","text":"GET /bluesky-recovery/download","level":2},{"id":"get-api-v1-social-bluesky-control","text":"GET /api/v1/social/bluesky/control","level":2},{"id":"get-api-v1-social-bluesky-archive","text":"GET /api/v1/social/bluesky/archive","level":2},{"id":"post-api-v1-social-bluesky-publish-blocks","text":"POST /api/v1/social/bluesky/publish-blocks","level":2},{"id":"post-api-v1-social-bluesky-state","text":"POST /api/v1/social/bluesky/state","level":2},{"id":"post-api-v1-social-bluesky-handle","text":"POST /api/v1/social/bluesky/handle","level":2},{"id":"delete-api-v1-social-bluesky-handle","text":"DELETE /api/v1/social/bluesky/handle","level":2},{"id":"get-api-v1-social-bluesky-move","text":"GET /api/v1/social/bluesky/move","level":2},{"id":"post-api-v1-social-bluesky-move","text":"POST /api/v1/social/bluesky/move","level":2},{"id":"delete-api-v1-social-bluesky-move","text":"DELETE /api/v1/social/bluesky/move","level":2},{"id":"post-api-v1-social-bluesky-move-continue","text":"POST /api/v1/social/bluesky/move/continue","level":2},{"id":"post-api-v1-social-bluesky-follow-from","text":"POST /api/v1/social/bluesky/follow-from","level":2},{"id":"get-api-v1-social-bluesky-move-target","text":"GET /api/v1/social/bluesky/move/target","level":2},{"id":"post-api-v1-social-bluesky-move-retry","text":"POST /api/v1/social/bluesky/move/retry","level":2},{"id":"get-api-v1-social-bluesky-bridgy-twin","text":"GET /api/v1/social/bluesky/bridgy-twin","level":2},{"id":"post-api-v1-social-bluesky-move-invite","text":"POST /api/v1/social/bluesky/move-invite","level":2},{"id":"delete-api-v1-social-bluesky-move-invite","text":"DELETE /api/v1/social/bluesky/move-invite","level":2},{"id":"post-api-v1-social-bluesky-move-in","text":"POST /api/v1/social/bluesky/move-in","level":2},{"id":"delete-api-v1-social-bluesky-move-in","text":"DELETE /api/v1/social/bluesky/move-in","level":2},{"id":"post-api-v1-social-bluesky-move-in-code","text":"POST /api/v1/social/bluesky/move-in/code","level":2},{"id":"post-api-v1-social-bluesky-move-in-continue","text":"POST /api/v1/social/bluesky/move-in/continue","level":2},{"id":"post-api-v1-social-bluesky-move-in-republish","text":"POST /api/v1/social/bluesky/move-in/republish","level":2},{"id":"post-api-v1-social-bluesky-move-code","text":"POST /api/v1/social/bluesky/move/code","level":2},{"id":"get-api-v1-social-bluesky-labelers","text":"GET /api/v1/social/bluesky/labelers","level":2},{"id":"post-api-v1-social-bluesky-labelers","text":"POST /api/v1/social/bluesky/labelers","level":2},{"id":"delete-api-v1-social-bluesky-labelers","text":"DELETE /api/v1/social/bluesky/labelers","level":2},{"id":"put-api-v1-social-bluesky-labelers-setting","text":"PUT /api/v1/social/bluesky/labelers/setting","level":2},{"id":"get-api-v1-social-bluesky-app-passwords","text":"GET /api/v1/social/bluesky/app-passwords","level":2},{"id":"post-api-v1-social-bluesky-app-passwords","text":"POST /api/v1/social/bluesky/app-passwords","level":2},{"id":"delete-api-v1-social-bluesky-app-passwords-id","text":"DELETE /api/v1/social/bluesky/app-passwords/{id}","level":2},{"id":"get-api-v1-social-bluesky-oauth-sessions","text":"GET /api/v1/social/bluesky/oauth-sessions","level":2},{"id":"delete-api-v1-social-bluesky-oauth-sessions-id","text":"DELETE /api/v1/social/bluesky/oauth-sessions/{id}","level":2},{"id":"get-api-v1-social-bluesky-feeds","text":"GET /api/v1/social/bluesky/feeds","level":2},{"id":"post-api-v1-social-bluesky-feeds","text":"POST /api/v1/social/bluesky/feeds","level":2},{"id":"delete-api-v1-social-bluesky-feeds","text":"DELETE /api/v1/social/bluesky/feeds","level":2},{"id":"get-api-v1-social-bluesky-feeds-suggested","text":"GET /api/v1/social/bluesky/feeds/suggested","level":2},{"id":"get-api-v1-social-bluesky-starter-pack","text":"GET /api/v1/social/bluesky/starter-pack","level":2},{"id":"post-api-v1-social-bluesky-starter-pack-follow","text":"POST /api/v1/social/bluesky/starter-pack/follow","level":2},{"id":"get-api-v1-social-bluesky-trends","text":"GET /api/v1/social/bluesky/trends","level":2},{"id":"get-api-v1-social-bluesky-suggestions","text":"GET /api/v1/social/bluesky/suggestions","level":2},{"id":"get-api-v1-timelines-bluesky","text":"GET /api/v1/timelines/bluesky","level":2},{"id":"get-well-known-oauth-protected-resource","text":"GET /.well-known/oauth-protected-resource","level":2},{"id":"post-oauth-par","text":"POST /oauth/par","level":2},{"id":"options-oauth-par-oauth-token-oauth-revoke","text":"OPTIONS /oauth/par, /oauth/token, /oauth/revoke","level":2},{"id":"get-xrpc-method","text":"GET /xrpc/{method}","level":2},{"id":"post-xrpc-method","text":"POST /xrpc/{method}","level":2},{"id":"options-xrpc-method","text":"OPTIONS /xrpc/{method}","level":2},{"id":"get-well-known-atproto-did","text":"GET /.well-known/atproto-did","level":2},{"id":"get-well-known-did-json","text":"GET /.well-known/did.json","level":2},{"id":"delete-admin-relays-id","text":"DELETE /admin/relays/{id}","level":2},{"id":"post-moderation-retention","text":"POST /moderation/retention","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"moderation-moderators-only","manual":false,"prev":{"path":"/docs/api-config-and-system","title":"Config and system"},"next":{"path":"/docs/api-external-users","title":"External users"},"parent":"api-custom-local-api"},{"slug":"api-external-users","path":"/docs/api-external-users","title":"External users","description":"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…","group":"api","html":"<p>Self-registered external users: people without a Nextcloud account who create one that reaches the Aloha Social app only. See the &quot;External users&quot; section of <code>docs/Architecture.md</code> for how the accounts work; these are the routes of the registration page, of the settings page&#39;s External users cards, and of the invitations people may send.</p>\n<p>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 <strong>password</strong> also need a recent password confirmation, which the page asks for.</p>\n<h2 id=\"get-signup\">GET /signup</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>invite</code></p>\n<p>The registration landing page and form, drawn in the guest layout like the login page. Initial state <code>signup</code> includes <code>open</code>, <code>reason</code>, mode, email confirmation, minimum age, server rules, privacy and legal links, the instance&#39;s plain-text <code>signupNotice</code>, and <code>bluesky</code> (<code>enabled</code>, <code>host</code>: whether an account made here gets a Bluesky handle and the host it is issued under, for the page to preview it). An <code>invite</code> token that is valid opens registration in every mode. A logged-in visitor is sent to Aloha Social.</p>\n<h2 id=\"post-signup\">POST /signup</h2>\n<p><strong>Auth: </strong>public, csrf · <strong>Parameters: </strong><code>handle</code>, <code>email</code>, <code>password</code>, <code>rules</code> (false), <code>age</code> (false), <code>invite</code>, <code>website</code></p>\n<p>A registration. Answers <code>{&quot;state&quot;, &quot;handle&quot;}</code>: <code>verify</code> (a confirmation email was sent), <code>approval</code> (it waits for an administrator) or <code>created</code> (the account exists, the person may log in). A refusal is a <strong>422</strong> with <code>{&quot;message&quot;, &quot;field&quot;}</code>, the message translated and fit to show. <code>website</code> 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.</p>\n<h2 id=\"get-signup-verify-token\">GET /signup/verify/{token}</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>token</code></p>\n<p>The link from the confirmation email. Draws the registration page with a <code>result</code>: <code>approval</code>, <code>created</code>, or <code>error</code> with a <code>message</code>. A link is good for 24 hours and once.</p>\n<h2 id=\"get-admin-external\">GET /admin/external</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>—</p>\n<p>Everything the External users cards show: <code>{&quot;settings&quot;, &quot;twoFactor&quot;, &quot;requests&quot;, &quot;invites&quot;, &quot;users&quot;}</code>. Settings include the instance&#39;s plain-text <code>signupNotice</code>. The same shape every administration route below answers with after a change.</p>\n<h2 id=\"post-admin-external\">POST /admin/external</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>enabled</code> (false), <code>max</code> (100), <code>quota</code> (1024), <code>mode</code> (<code>approval</code>), <code>verifyEmail</code> (true), <code>minAge</code> (16), <code>reserved</code> (<code>[]</code>), <code>userInvites</code> (false), <code>signupNotice</code> (empty)</p>\n<p>Writes the settings, all or none, and answers with <code>settings</code>. <code>max</code> is 0 to 1000000 accounts, <code>quota</code> the megabytes of media each may upload (0 is no quota), <code>mode</code> is <code>open</code>, <code>invite</code> or <code>approval</code>, <code>minAge</code> 0 to 99 (0 asks nothing), <code>reserved</code> the handles nobody may register. <code>signupNotice</code> is plain text up to 4000 characters and is shown before registration. A value out of range is a <strong>422</strong> naming it. Switching the feature on where Aloha Social is restricted to groups adds the externals&#39; group to them.</p>\n<h2 id=\"post-admin-external-restriction\">POST /admin/external/restriction</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong>—</p>\n<p>Adds the externals&#39; group, <code>social-external</code>, to the groups Aloha Social is restricted to. Answers with <code>settings</code>.</p>\n<h2 id=\"post-admin-external-two-factor\">POST /admin/external/two-factor</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf, <strong>password</strong> · <strong>Parameters: </strong><code>enforced</code> (false)</p>\n<p>Requires two-factor authentication of external users, or stops requiring it, by changing core&#39;s mandatory two-factor setting for their group. Answers <code>{&quot;enforced&quot;, &quot;everybody&quot;}</code>; <code>everybody</code> is true when core enforces it for everybody, externals included unless excluded.</p>\n<h2 id=\"get-admin-external-users\">GET /admin/external/users</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>search</code>, <code>offset</code> (0)</p>\n<p>A page of 50 external accounts: <code>uid</code>, <code>displayName</code>, <code>email</code>, <code>created</code>, <code>lastLogin</code>, <code>enabled</code>, <code>mediaBytes</code>, <code>origin</code>.</p>\n<h2 id=\"post-admin-external-users-uid-promote\">POST /admin/external/users/{uid}/promote</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf, <strong>password</strong> · <strong>Parameters: </strong><code>uid</code></p>\n<p>Makes the external user an ordinary local user, keeping the user id, the password, two-factor and the Aloha Social account. A <strong>422</strong> when it is not an external user or cannot be promoted.</p>\n<h2 id=\"post-admin-external-users-uid-enabled\">POST /admin/external/users/{uid}/enabled</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>uid</code>, <code>enabled</code> (true)</p>\n<p>Disables the account, or enables it again. Answers <code>{&quot;uid&quot;, &quot;enabled&quot;}</code>; <strong>404</strong> for somebody who is not an external user.</p>\n<h2 id=\"delete-admin-external-users-uid\">DELETE /admin/external/users/{uid}</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf, <strong>password</strong> · <strong>Parameters: </strong><code>uid</code></p>\n<p>Deletes the account, and with it the Aloha Social account and everything it posted, the way deleting any Nextcloud user does. <strong>404</strong> for somebody who is not an external user.</p>\n<h2 id=\"post-admin-external-requests-id\">POST /admin/external/requests/{id}</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>id</code></p>\n<p>Admits a registration that is waiting for approval: the account is created and the person is emailed. A <strong>422</strong> when there is no such registration or the account cannot be created, the server being full among the reasons.</p>\n<h2 id=\"delete-admin-external-requests-id\">DELETE /admin/external/requests/{id}</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>id</code>, <code>reason</code></p>\n<p>Turns a registration down and forgets it. The person is emailed, with <code>reason</code> when there is one. <strong>404</strong> for an unknown id.</p>\n<h2 id=\"post-admin-external-invites\">POST /admin/external/invites</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>note</code>, <code>maxUses</code> (1), <code>days</code> (7)</p>\n<p>An invitation link. <code>maxUses</code> 0 admits any number of registrations and <code>days</code> 0 never expires. Answers with the invitation: <code>{&quot;id&quot;, &quot;url&quot;, &quot;creator&quot;, &quot;note&quot;, &quot;maxUses&quot;, &quot;uses&quot;, &quot;expires&quot;, &quot;created&quot;}</code>.</p>\n<h2 id=\"delete-admin-external-invites-id\">DELETE /admin/external/invites/{id}</h2>\n<p><strong>Auth: </strong><strong>administrator</strong>, csrf · <strong>Parameters: </strong><code>id</code></p>\n<p>Withdraws anybody&#39;s invitation. <strong>404</strong> for an unknown id.</p>\n<h2 id=\"get-invites\">GET /invites</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong>—</p>\n<p>Whether this person may send invitations (<code>allowed</code>, which the administrator switches on) and the ones they sent (<code>invites</code>).</p>\n<h2 id=\"post-invites\">POST /invites</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>note</code></p>\n<p>An invitation from this person: single-use, valid for 7 days, at most 10 open at a time. A <strong>422</strong> when invitations are off or the limit is reached. Rate limited to 20 an hour.</p>\n<h2 id=\"delete-invites-id\">DELETE /invites/{id}</h2>\n<p><strong>Auth: </strong>user, csrf · <strong>Parameters: </strong><code>id</code></p>\n<p>Withdraws one of this person&#39;s own invitations. <strong>404</strong> for anybody else&#39;s.</p>\n<hr>\n","toc":[{"id":"get-signup","text":"GET /signup","level":2},{"id":"post-signup","text":"POST /signup","level":2},{"id":"get-signup-verify-token","text":"GET /signup/verify/{token}","level":2},{"id":"get-admin-external","text":"GET /admin/external","level":2},{"id":"post-admin-external","text":"POST /admin/external","level":2},{"id":"post-admin-external-restriction","text":"POST /admin/external/restriction","level":2},{"id":"post-admin-external-two-factor","text":"POST /admin/external/two-factor","level":2},{"id":"get-admin-external-users","text":"GET /admin/external/users","level":2},{"id":"post-admin-external-users-uid-promote","text":"POST /admin/external/users/{uid}/promote","level":2},{"id":"post-admin-external-users-uid-enabled","text":"POST /admin/external/users/{uid}/enabled","level":2},{"id":"delete-admin-external-users-uid","text":"DELETE /admin/external/users/{uid}","level":2},{"id":"post-admin-external-requests-id","text":"POST /admin/external/requests/{id}","level":2},{"id":"delete-admin-external-requests-id","text":"DELETE /admin/external/requests/{id}","level":2},{"id":"post-admin-external-invites","text":"POST /admin/external/invites","level":2},{"id":"delete-admin-external-invites-id","text":"DELETE /admin/external/invites/{id}","level":2},{"id":"get-invites","text":"GET /invites","level":2},{"id":"post-invites","text":"POST /invites","level":2},{"id":"delete-invites-id","text":"DELETE /invites/{id}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"external-users","manual":false,"prev":{"path":"/docs/api-moderation-moderators-only","title":"Moderation (moderators only)"},"next":{"path":"/docs/api-oauth","title":"OAuth"},"parent":"api-custom-local-api"},{"slug":"api-oauth","path":"/docs/api-oauth","title":"OAuth","description":"A partial, Mastodon-shaped OAuth 2 flow (OAuthController, ClientService).","group":"api","html":"<p>A partial, Mastodon-shaped OAuth 2 flow (<code>OAuthController</code>, <code>ClientService</code>).</p>\n<h2 id=\"post-api-v1-apps\">POST /api/v1/apps</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>client_name</code> (<code>&#39;&#39;</code>), <code>redirect_uris</code> (string or array, <code>&#39;&#39;</code>), <code>website</code> (<code>&#39;&#39;</code>), <code>scopes</code> (<code>&#39;read&#39;</code>)</p>\n<p>Registers a client. Returns <code>{&quot;id&quot;, &quot;name&quot;, &quot;website&quot;, &quot;scopes&quot;, &quot;redirect_uris&quot;, &quot;client_id&quot;, &quot;client_secret&quot;, &quot;redirect_uri&quot;, &quot;vapid_key&quot;}</code>; <code>scopes</code> and <code>redirect_uris</code> are lists, as Mastodon 4.3 sends them, and <code>redirect_uri</code> is the first of the registered URIs. <code>redirect_uris</code> may be an array or, as Mastodon&#39;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 <code>ClientService::confirmData()</code> 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 <code>http</code>/<code>https</code> address with a host, or a native application&#39;s own scheme (<code>tusky://…</code>), written in lower case; a scheme a browser runs rather than follows (<code>javascript</code>, <code>data</code>, <code>vbscript</code>, <code>file</code>), a relative path or anything else is a <strong>422</strong> <code>{&quot;error&quot;: &quot;...&quot;}</code>, 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 <strong>seven days</strong> is removed by <code>Cron\\Cache</code> (<code>ClientService::sweep()</code>); one that was authorized once is kept even after its authorizations expire.</p>\n<h2 id=\"post-oauth-device-authorization\">POST /oauth/device_authorization</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>client_id</code>, <code>client_secret</code> when registered, <code>scope</code> (<code>&#39;read&#39;</code>)</p>\n<p>Starts RFC 8628 device authorization for a registered app. Returns a 43-character one-time <code>device_code</code>, an eight-character <code>user_code</code>, <code>verification_uri</code>, <code>verification_uri_complete</code>, <code>expires_in</code> (600) and <code>interval</code> (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&#39;s registered scopes.</p>\n<h2 id=\"get-oauth-device\">GET /oauth/device</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>user_code</code> (optional, may include its hyphen)</p>\n<p>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.</p>\n<h2 id=\"post-oauth-device\">POST /oauth/device</h2>\n<p><strong>Auth: </strong>user, CSRF-protected, brute-force protected · <strong>Parameters: </strong><code>user_code</code>, <code>decision</code> (<code>allow</code> or <code>deny</code>)</p>\n<p>Records the signed-in account&#39;s one-time decision for a pending device request. A code can only be approved once.</p>\n<h2 id=\"get-well-known-oauth-authorization-server\">GET /.well-known/oauth-authorization-server</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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, <code>scopes_supported</code> (every scope this server understands), <code>response_types_supported: [&quot;code&quot;]</code>, <code>grant_types_supported</code> (including RFC 8628 device authorization) and the two client-authentication methods. <strong>The addresses are this app&#39;s real ones</strong>, under the app&#39;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&#39;s root paths. A client that does not read it looks at the root, finds nothing and is no worse off than before.</p>\n<h2 id=\"get-oauth-userinfo\">GET /oauth/userinfo</h2>\n<p><strong>Auth: </strong>public, no-csrf (bearer token) · <strong>Parameters: </strong>—</p>\n<p>Who the token belongs to, in OpenID Connect&#39;s shape: <code>sub</code>, <code>name</code>, <code>preferred_username</code>, <code>profile</code>, <code>picture</code>. Mastodon 4.3 added it so a client can show &quot;signed in as …&quot; without spending a <code>read:accounts</code> call on <code>verify_credentials</code>, and it needs no scope beyond having a token. <code>sub</code> is the actor&#39;s <strong>ActivityPub id</strong>, 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 <strong>401</strong>.</p>\n<h2 id=\"get-oauth-authorize\">GET /oauth/authorize</h2>\n<p><strong>Auth: </strong>public, no-csrf (redirects a visitor to Nextcloud login) · <strong>Parameters: </strong><code>client_id</code>, <code>redirect_uri</code>, <code>response_type</code> (must be <code>code</code>), <code>scope</code> (<code>&#39;read&#39;</code>), <code>state</code> (<code>&#39;&#39;</code>)</p>\n<p>Renders the <code>oauth2</code> consent template. <code>redirect_uri</code> 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 <code>{&quot;error&quot;: &quot;invalid_request&quot;, &quot;error_description&quot;: &quot;...&quot;}</code>, never a redirect, since the one parameter that is wrong is where the redirect would go. <code>state</code> is carried through to the POST. Anything else wrong with the request — an unknown <code>client_id</code>, a <code>response_type</code> that is not <code>code</code>, a scope the client never registered — is HTTP 400 <code>{&quot;error&quot;: &quot;...&quot;}</code>, the way the POST answers it; these used to escape as a Nextcloud HTML error page. <strong>A reader without an account here</strong> — 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 <code>setup</code> initial state (<code>suggestedHandle</code>, <code>socialAddress</code>, <code>bluesky</code>) instead of <code>account</code>, creates the account through <code>POST /api/v1/account/create</code> with the page&#39;s session, as the app&#39;s own setup page does, and then loads the same address again, which carries the client&#39;s request unchanged and now draws the consent for the new account. A Bluesky app&#39;s pushed request (<code>request_uri</code>) is answered the same way once the request is found good; the account&#39;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 <code>redirect_url</code>, so login returns to the same validated OAuth request before consent. Any other failure is logged and answered HTTP 500 <code>{&quot;error&quot;: &quot;server_error&quot;}</code>, as from <code>/oauth/token</code>, since its message describes the server.</p>\n<h2 id=\"post-oauth-authorize\">POST /oauth/authorize</h2>\n<p><strong>Auth: </strong>user · <strong>Parameters: </strong><code>client_id</code>, <code>redirect_uri</code>, <code>response_type</code>, <code>scope</code> (<code>&#39;read&#39;</code>), <code>state</code> (<code>&#39;&#39;</code>)</p>\n<p>Issues an authorization code. Answers with a redirect to <code>redirect_uri</code> (<code>RedirectResponse</code>, so HTTP <strong>303</strong>) carrying <code>code</code> and, when one was sent, <code>state</code> — appended with <code>http_build_query</code>, so a <code>redirect_uri</code> that already has a query string or a fragment stays valid. <code>state</code> used to be dropped, which a spec-following client rejects and a lax one is open to code injection through. For <code>urn:ietf:wg:oauth:2.0:oob</code> the code (and <code>state</code>) come back as the response body instead. <code>redirect_uri</code> is held to the same rule as the GET — exactly one of the registered URIs, else HTTP 400 <code>{&quot;error&quot;: &quot;invalid_request&quot;, ...}</code> 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 <code>{&quot;error&quot;: &quot;...&quot;}</code> for what is wrong with the request, as for the GET; HTTP 403 <code>account-not-set-up</code> with <code>setup_url</code> (see <a href=\"/docs/api-authentication#authentication\">Authentication</a>) for a reader without an account, checked after the request, and no code is issued — a token always names an account; and HTTP 500 <code>{&quot;error&quot;: &quot;server_error&quot;}</code> for anything else.</p>\n<h2 id=\"post-oauth-token\">POST /oauth/token</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong><code>client_id</code>, <code>client_secret</code> when registered, <code>redirect_uri</code>, <code>grant_type</code> (<code>authorization_code</code>, <code>client_credentials</code> or <code>urn:ietf:params:oauth:grant-type:device_code</code>), <code>scope</code> (<code>&#39;read&#39;</code>), <code>code</code>, <code>code_verifier</code>, <code>device_code</code></p>\n<p>Exchanges an authorization code, app credentials or an approved device code for a bearer token: <code>{&quot;access_token&quot;, &quot;token_type&quot;: &quot;Bearer&quot;, &quot;scope&quot;, &quot;created_at&quot;}</code>. Authorization codes still require the exact <code>redirect_uri</code> they were issued for. Device polling returns RFC 8628&#39;s <code>authorization_pending</code>, <code>slow_down</code> (raising the required interval by five seconds each time), <code>access_denied</code>, <code>expired_token</code>, and a one-time token response; a device code cannot be used twice. Confidential apps must present their registered client secret for device polling. <code>scope</code> reports the scopes the <strong>token</strong> carries — what <code>ApiController::checkTokenScope()</code> enforces — not the scope of this call. Credential failures are brute-force throttled; a server failure is HTTP 500 <code>{&quot;error&quot;: &quot;server_error&quot;}</code> with the cause in the log.</p>\n<h2 id=\"post-oauth-revoke\">POST /oauth/revoke</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong><code>client_id</code>, <code>client_secret</code>, <code>token</code></p>\n<p>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 <code>[]</code>. Wrong client credentials return a throttled HTTP 401.</p>\n<h2 id=\"get-api-v1-authorized-apps\">GET /api/v1/authorized_apps</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, the broad <code>read</code> scope) · <strong>Parameters: </strong>—</p>\n<p><strong>The apps this account has signed in to</strong>, newest first: <code>{&quot;id&quot;, &quot;name&quot;, &quot;website&quot;, &quot;scopes&quot;, &quot;created_at&quot;, &quot;last_used_at&quot;, &quot;expires_at&quot;, &quot;signed_in&quot;}</code> per row. <code>id</code> is the <code>social_client_auth</code> row, <code>created_at</code> is when <em>this account</em> granted it (not when the app registered on the instance), <code>last_used_at</code> is the last request the token made (kept to within five minutes), <code>expires_at</code> is when the token stops working however much it is used — <code>created_at</code> plus <code>token_max_days</code>, or <code>0</code> where that is off — and <code>signed_in</code> 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 <code>read</code>: this is the list of the person&#39;s <em>other</em> 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.</p>\n<h2 id=\"delete-api-v1-authorized-apps-id\">DELETE /api/v1/authorized_apps/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf (viewer required, <code>write</code> scope; a token only its own authorization) · <strong>Parameters: </strong><code>id</code></p>\n<p>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&#39;s own rather than deleted by the id it was handed, so signing a stranger&#39;s device out is impossible rather than unlikely; an id that is not this account&#39;s is a <strong>404</strong>, the same answer an id that does not exist gets. <strong>A bearer token may revoke only its own authorization</strong> (an app signing itself out); any other id is a <strong>403</strong> whether it exists or not, so that answer says nothing either. Signing <em>another</em> app out takes the Nextcloud session — the settings page, or an app password with <code>OCS-APIRequest: true</code>: this route manages other apps&#39; tokens, Mastodon has no API for that at all, and nothing a client was granted is consent to sign the person&#39;s other apps out.</p>\n<p><strong>Grant types:</strong> <code>authorization_code</code>, <code>client_credentials</code> (RFC 6749 §4.4), and <code>urn:ietf:params:oauth:grant-type:device_code</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 <code>/oauth/token</code> at the advertised interval, and the token is issued once to the account that approved the request. The app-only <code>client_credentials</code> token is bound to no account and has <code>read</code> scope only. Device polling errors use RFC names: <code>authorization_pending</code>, <code>slow_down</code>, <code>access_denied</code>, <code>expired_token</code> and <code>invalid_grant</code>.</p>\n<p><strong>Scopes:</strong> <code>SocialClient::getScopesFromString()</code> splits requested scopes on spaces and <code>ClientService::confirmData()</code> checks they are a subset of the scopes registered for the app; the default everywhere is <code>read</code>. Bearer tokens are enforced per endpoint by <code>ApiController::checkTokenScope()</code>: creating, editing and deleting statuses, uploading media and updating its alt text, status actions, poll votes, moving markers, <code>update_credentials</code> and filing reports need <code>write</code>; follow/unfollow, block, mute and authorizing or rejecting follow requests need <code>follow</code> or <code>write</code>; the Web Push subscription routes require <code>push</code>; <code>/api/v1/apps/verify_credentials</code> accepts any valid token; every other <code>/api/</code> route needs <code>read</code>. A granular scope is satisfied by itself or by the broad scope that contains it (<code>write:statuses</code> by <code>write:statuses</code> or <code>write</code>), never by a sibling (<code>write:favourites</code> does not permit posting); the other client-API controllers apply the same rule through <code>ClientApiController</code>. Session-cookie requests are not scope-restricted, but are only accepted together with a valid CSRF token.</p>\n<p><strong>Credential storage:</strong> client secrets, authorization codes and access tokens are stored as <code>sha256:&lt;hex&gt;</code> digests (<code>SecretHasher</code>); rows from before hashing held the bare value and were hashed by migration <code>Version1000Date20261008000100</code> — or, where that failed, deleted, signing that app out — and <strong>a bare stored value is no longer accepted</strong>. 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.</p>\n<p><strong>Token lifetime:</strong> <code>ClientService::TIME_TOKEN_TTL</code> is 30672000 s (~1 year) since last use; a used token&#39;s <code>last_update</code> is refreshed at most once per <code>TIME_TOKEN_REFRESH</code> (300 s).</p>\n<hr>\n","toc":[{"id":"post-api-v1-apps","text":"POST /api/v1/apps","level":2},{"id":"post-oauth-device-authorization","text":"POST /oauth/device_authorization","level":2},{"id":"get-oauth-device","text":"GET /oauth/device","level":2},{"id":"post-oauth-device","text":"POST /oauth/device","level":2},{"id":"get-well-known-oauth-authorization-server","text":"GET /.well-known/oauth-authorization-server","level":2},{"id":"get-oauth-userinfo","text":"GET /oauth/userinfo","level":2},{"id":"get-oauth-authorize","text":"GET /oauth/authorize","level":2},{"id":"post-oauth-authorize","text":"POST /oauth/authorize","level":2},{"id":"post-oauth-token","text":"POST /oauth/token","level":2},{"id":"post-oauth-revoke","text":"POST /oauth/revoke","level":2},{"id":"get-api-v1-authorized-apps","text":"GET /api/v1/authorized_apps","level":2},{"id":"delete-api-v1-authorized-apps-id","text":"DELETE /api/v1/authorized_apps/{id}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"oauth","manual":false,"prev":{"path":"/docs/api-external-users","title":"External users"},"next":{"path":"/docs/api-activitypub-federation","title":"ActivityPub Federation"},"parent":null},{"slug":"api-activitypub-federation","path":"/docs/api-activitypub-federation","title":"ActivityPub Federation","description":"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…","group":"api","html":"<p><code>ActivityPubController</code> decides per request, via <code>checkSourceActivityStreams()</code>, whether the caller is a Fediverse server: it splits the <code>Accept</code> header on commas, trims each entry at the first <code>;</code>, and returns true if any entry equals <code>application/ld+json</code> or <code>application/activity+json</code>. Anything else (a browser) is treated as HTML.</p>\n<p>JSON-LD responses are emitted through <code>activityPubSuccess()</code>, i.e. <code>Content-Type: application/ld+json; profile=&quot;https://www.w3.org/ns/activitystreams&quot;</code>. The controller also registers <code>activity+json</code> and <code>ld+json; …</code> responders for format-based negotiation.</p>\n<h2 id=\"get-actor\">GET /actor</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>This instance&#39;s own <code>Application</code> actor — the identity every outbound signed fetch is made as, and the <code>publicKey.id</code> 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; <code>manuallyApprovesFollowers</code> is true and <code>discoverable</code>/<code>indexable</code> are false, so nothing offers it as somebody to follow or index. <code>inbox</code> and <code>endpoints.sharedInbox</code> both point at the shared <code>/inbox</code>, 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 (<code>instance_actor_public_key</code>, 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 <code>keyId</code> nobody can resolve.</p>\n<h2 id=\"get-users-username\">GET /users/{username}</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>Actor object (with W3C security context). Unknown actor → error envelope with HTTP 404. Without an AP <code>Accept</code> header it delegates to <code>SocialPubController::actor()</code>, which answers a browser: the app for a reader with a session, the public page for a visitor, a <strong>404</strong> for an account this instance does not hold. The client-side router has no view for this path — it owns <code>/@{username}</code> — so a browser sent here lands on the app with nothing in it; the alias below is the address to link.</p>\n<h2 id=\"get-username\">GET /@{username}/</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>Alias that calls <code>actor()</code>. For a browser (<code>Accept</code> without an ActivityPub type) <code>SocialPubController</code> answers: a reader with a session gets the app, the same page as <code>/</code>, 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 <strong>404</strong> — 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.</p>\n<h2 id=\"get-username-collections\">GET /@{username}/collections</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>An account&#39;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.</p>\n<h2 id=\"get-username-portfolio\">GET /@{username}/portfolio</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>An account&#39;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.</p>\n<h2 id=\"post-username-inbox\">POST /@{username}/inbox</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>Per-user inbox. Rate-limited on the source address and read with a <strong>2 MB ceiling</strong> (<code>ActivityPubController::MAX_INBOX_BODY</code>, Mastodon&#39;s figure) before any signature work — a body past it is a <strong>413</strong> and nothing is digested, fetched or verified — then verifies the HTTP signature, checks the Fediverse access list, spends the <em>verified</em> origin&#39;s own looser bucket, requires the local actor to exist, imports the activity, then async-processes the stream cache queue (<code>inbox_throttle</code> app setting, default 300/min, 0 disables; either bucket → HTTP 429). Returns <code>{&quot;result&quot;: [], &quot;status&quot;: 1}</code>; 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 <code>docs/Architecture.md</code>.</p>\n<h2 id=\"get-username-inbox\">GET /@{username}/inbox</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>Empty <code>OrderedCollection</code> (<code>totalItems: 0</code>) for the actor&#39;s inbox; bare <code>[]</code> with HTTP 404 if the actor is unknown.</p>\n<h2 id=\"post-inbox\">POST /inbox</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>Shared inbox, same processing (including both rate limits and the same rejection statuses) without the per-actor check.</p>\n<h2 id=\"get-username-outbox\">GET /@{username}/outbox</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>Outbox collection; with <code>?page=N</code> (or <code>?page=true</code>) one <code>OrderedCollectionPage</code> of the author&#39;s public posts, newest first, as <code>Create</code> activities. A full page&#39;s <code>next</code> is a cursor, <code>?page=true&amp;max_id=&lt;nid of its last post&gt;</code>, read below the cursor rather than at an offset — a numbered page reads and discards every post before it, so only <code>first</code> is numbered; a <code>max_id</code> that is not a nid is an empty page. The HTML fallback is commented out in the source, so browsers get JSON-LD too.</p>\n<h2 id=\"post-username-outbox\">POST /@{username}/outbox</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>Same route handler as the GET, registered as <code>ActivityPub#outbox_post</code>; posting an activity is <strong>not</strong> implemented — the method only returns the outbox collection.</p>\n<h2 id=\"get-username-rss\">GET /@{username}.rss</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p><strong>An account&#39;s public posts as an RSS 2.0 feed.</strong> PeerTube publishes one per channel and Mastodon one per account, and PeerTube&#39;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 <code>&lt;enclosure&gt;</code>, which is what makes such a feed usable in a podcast client at all. Built from an <strong>anonymous</strong> 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&#39;s reader and out of reach for ever, so <code>FeedService</code> refuses a non-public post a second time. Twenty posts, cached ten minutes.</p>\n<h2 id=\"get-username-followers\">GET /@{username}/followers</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>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 <code>?page=N</code> (or <code>?page=true</code>) one <code>OrderedCollectionPage</code> of follower ids, newest follow first; a full page&#39;s <code>next</code> is a cursor, <code>?page=true&amp;max_id=&lt;creation&gt;-&lt;follow prim&gt;</code>, read after the cursor on the <code>social_f_ocr</code> index rather than at an offset. A <code>max_id</code> that is not such a cursor is an empty page. The AP branch is refused with 401 under <code>secure_mode</code> when nothing signed the fetch; the page is not, since a browser has nothing to sign with.</p>\n<h2 id=\"get-username-following\">GET /@{username}/following</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>Following collection, or the page, the same way, paged by the same cursor. The AP branch is refused with 401 under <code>secure_mode</code> the same way.</p>\n<h2 id=\"get-username-collections-featured\">GET /@{username}/collections/featured</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>The actor&#39;s pinned posts as an <code>OrderedCollection</code> whose <code>orderedItems</code> carry the full posts (at most 5). This is where remote servers read pinned posts from; the actor document points at it with <code>featured</code>. The route has no <code>Accept</code> 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 <code>secure_mode</code> when nothing signed the fetch — <code>PinService::pin()</code> 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.</p>\n<h2 id=\"get-username-stories-id\">GET /@{username}/stories/{id}</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>One story as a <code>Story</code> object — and the <strong>capability</strong> the <code>Add</code> carried. Two ways in: a request bearing the story&#39;s own token (<code>Authorization: Bearer …</code>), 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&#39;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 <strong>404</strong>, because whether an account has a story up is told to its followers and to nobody else. <code>{id}</code> is numeric, which is what keeps it out of the way of the <code>/@{username}/{token}</code> catch-all below.</p>\n<h2 id=\"get-username-token\">GET /@{username}/{token}</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>Single post. <code>{token}</code> values <code>outbox</code>, <code>followers</code> and <code>following</code> (case-insensitive) are re-routed to those handlers first. For AP callers the <code>Stream</code> is returned as JSON-LD (HTTP 404 error envelope with a <code>stream</code> key when missing). A browser is answered by <code>SocialPubController::displayPost()</code>: the post is resolved by its address and then, when <code>{token}</code> is all digits, by the numeric id the app itself links with, and is rendered into the page as <code>item</code> 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 <code>/</code>; a visitor gets the public page. Only a local public post advertises the oEmbed endpoint through a <code>Link</code> header. A post that resolves to nothing is a <strong>404</strong>: 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.</p>\n<h2 id=\"get-username-token-embed\">GET /@{username}/{token}/embed</h2>\n<p><strong>Auth: </strong>public, no-csrf, rate-limited</p>\n<p>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&#39;s light/dark preference. Unlisted, followers-only, direct, remote or missing posts all return the same <strong>404</strong>. Only this endpoint allows cross-origin framing; its oEmbed response and the post action menu&#39;s <strong>Copy code</strong> 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.</p>\n<h2 id=\"get-username-token-quote-authorizations-stamp\">GET /@{username}/{token}/quote_authorizations/{stamp}</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>The FEP-044f approval a quote of <code>{token}</code> rests on, as a <code>QuoteAuthorization</code> naming the quoted author (<code>attributedTo</code>), the quoting post (<code>interactingObject</code>) and the quoted post (<code>interactionTarget</code>). <code>{stamp}</code> is the quoting post&#39;s id, base64url-encoded without padding — the same URI this instance put in the <code>Accept</code> that granted the approval. Answered from the quoted post&#39;s current policy where that lets anybody quote it, and otherwise from the grant <code>QuoteRequestInterface::accept()</code> 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 <code>secure_mode</code> when nothing signed the fetch.</p>\n<h2 id=\"get-username-token-replies\">GET /@{username}/{token}/replies</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>The replies to <code>{token}</code>, as an <code>OrderedCollection</code> whose <code>first</code>/<code>last</code> point at <code>?page=N</code>; with <code>?page=N</code> (or Mastodon&#39;s <code>?page=true</code>, which means the first) it answers with an <code>OrderedCollectionPage</code> of at most <code>OrderedCollection::PAGE_SIZE</code> (40) items. A full page&#39;s <code>next</code> is a cursor, <code>?page=true&amp;min_id=&lt;nid of its last reply&gt;</code>, and that page is read after the cursor rather than at an offset; a numbered page also carries <code>prev</code>, a cursor page does not. A <code>min_id</code> that is not a nid is an empty page. The note itself points here with <code>replies</code>. Items are the replies&#39; <strong>ids</strong>, not the replies: a reply is its author&#39;s document, served by their instance, which may since have edited or deleted it. No viewer is set, so only <strong>public</strong> 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 <code>secure_mode</code> when nothing signed the fetch.</p>\n<h2 id=\"get-username-token-likes\">GET /@{username}/{token}/likes</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>How many likes <code>{token}</code> has had, as an <code>OrderedCollection</code> carrying <code>totalItems</code> and nothing else: who liked a post is not published, which is what Mastodon and PeerTube do too. A <code>Video</code> points here with <code>likes</code>. 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. <code>totalItems</code> is stated when it is 0, which every collection here now does. The same 404s and 401 as <code>replies</code>.</p>\n<h2 id=\"get-username-token-dislikes\">GET /@{username}/{token}/dislikes</h2>\n<p><strong>Auth: </strong>public, no-csrf</p>\n<p>The same for dislikes, PeerTube&#39;s other counter; a <code>Video</code> points here with <code>dislikes</code>.</p>\n<h2 id=\"discovery-documents-not-app-routes\">Discovery documents (not app routes)</h2>\n<p>WebFinger, NodeInfo discovery and host-meta are served by <code>lib/WellKnown/WebfingerHandler.php</code>, registered through <code>registerWellKnownHandler()</code> in <code>lib/AppInfo/Application.php</code> — they are Nextcloud-level paths (.well-known/webfinger, .well-known/nodeinfo, .well-known/host-meta), not entries in this app&#39;s route table. Only the NodeInfo 2.0 <em>document</em> itself is an app route (see <code>/.well-known/nodeinfo/2.0</code> above).</p>\n<p>The handler first checks <code>FediverseService::jailed()</code> and passes the previous response through when the instance is not allowed to federate. For <code>webfinger</code> with a <code>resource</code> query parameter (<code>acct:</code> prefix stripped; the raw request URI is parsed as a fallback):</p>\n<ul>\n<li>The app&#39;s own subject gets an extra link added to the existing response, carrying <code>app</code>, <code>name</code> and <code>version</code> properties.</li>\n<li>For a local actor it returns a JRD document whose <code>subject</code> is the requested resource, with aliases for the actor URL and the Nextcloud profile page, a <code>self</code> link of type <code>application/activity+json</code> pointing at the <code>/@{username}/</code> route, an <code>http://webfinger.net/rel/profile-page</code> link (<code>text/html</code>) to the Nextcloud profile page, and an <code>http://ostatus.org/schema/1.0/subscribe</code> link with a <code>template</code> of <code>&lt;social url&gt;ostatus/follow/?uri={uri}</code>.</li>\n<li><code>acct:&lt;host&gt;@&lt;host&gt;</code> — the instance&#39;s own handle, the one Mastodon gives its instance actor — returns a JRD with an alias and a <code>self</code> link (<code>application/activity+json</code>) pointing at <code>/actor</code>. 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.</li>\n<li>A missing or empty <code>resource</code> parameter is an empty JRD with HTTP 400 (RFC 7033 makes the parameter mandatory).</li>\n<li>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).</li>\n</ul>\n<p>The <code>nodeinfo</code> service returns one link per schema the app serves — rel <code>http://nodeinfo.diaspora.software/ns/schema/2.0</code> and <code>…/2.1</code>, pointing at <code>/.well-known/nodeinfo/2.0</code> and <code>/.well-known/nodeinfo/2.1</code>. 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 <code>OAuthController::NODEINFO_SCHEMAS</code>, which is also what the controller serves, so the two cannot drift apart. The <code>nodeinfo</code> answer carries <code>Access-Control-Allow-Origin: *</code>, as the documents it links to do, so a browser client of another origin can read it. <code>host-meta</code> returns XRD (<code>application/xrd+xml</code>) with an <code>lrdd</code> template pointing at the instance&#39;s WebFinger URL.</p>\n<hr>\n","toc":[{"id":"get-actor","text":"GET /actor","level":2},{"id":"get-users-username","text":"GET /users/{username}","level":2},{"id":"get-username","text":"GET /@{username}/","level":2},{"id":"get-username-collections","text":"GET /@{username}/collections","level":2},{"id":"get-username-portfolio","text":"GET /@{username}/portfolio","level":2},{"id":"post-username-inbox","text":"POST /@{username}/inbox","level":2},{"id":"get-username-inbox","text":"GET /@{username}/inbox","level":2},{"id":"post-inbox","text":"POST /inbox","level":2},{"id":"get-username-outbox","text":"GET /@{username}/outbox","level":2},{"id":"post-username-outbox","text":"POST /@{username}/outbox","level":2},{"id":"get-username-rss","text":"GET /@{username}.rss","level":2},{"id":"get-username-followers","text":"GET /@{username}/followers","level":2},{"id":"get-username-following","text":"GET /@{username}/following","level":2},{"id":"get-username-collections-featured","text":"GET /@{username}/collections/featured","level":2},{"id":"get-username-stories-id","text":"GET /@{username}/stories/{id}","level":2},{"id":"get-username-token","text":"GET /@{username}/{token}","level":2},{"id":"get-username-token-embed","text":"GET /@{username}/{token}/embed","level":2},{"id":"get-username-token-quote-authorizations-stamp","text":"GET /@{username}/{token}/quote_authorizations/{stamp}","level":2},{"id":"get-username-token-replies","text":"GET /@{username}/{token}/replies","level":2},{"id":"get-username-token-likes","text":"GET /@{username}/{token}/likes","level":2},{"id":"get-username-token-dislikes","text":"GET /@{username}/{token}/dislikes","level":2},{"id":"discovery-documents-not-app-routes","text":"Discovery documents (not app routes)","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"activitypub-federation","manual":false,"prev":{"path":"/docs/api-oauth","title":"OAuth"},"next":{"path":"/docs/api-legacy-ostatus","title":"Legacy OStatus"},"parent":null},{"slug":"api-legacy-ostatus","path":"/docs/api-legacy-ostatus","title":"Legacy OStatus","description":"Auth: user, no-csrf · Parameters: uri (required; an address, an acct: URI or an actor id)","group":"api","html":"<h2 id=\"get-ostatus-follow\">GET /ostatus/follow/</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong><code>uri</code> (required; an address, an <code>acct:</code> URI or an actor id)</p>\n<p>Renders the Vue app with <code>account</code>, <code>resolve</code> and <code>currentUser</code> in initial state. Anybody can write the link, so the account is looked up only among those this server holds: one it holds is <code>account</code>; one it does not is <code>resolve</code> (<code>account</code> <code>&#39;&#39;</code>), and the page asks no other server until the reader presses <strong>Look up</strong>, which calls the route below. Requires a logged-in user; failures return the error envelope.</p>\n<h2 id=\"post-api-v1-ostatus-resolve\">POST /api/v1/ostatus/resolve</h2>\n<p><strong>Auth: </strong>user (CSRF checked, 30 a minute) · <strong>Parameters: </strong><code>uri</code></p>\n<p>Looks the account <code>uri</code> names up, on its own server where this one does not hold it, and answers <code>{&quot;result&quot;: {&quot;account&quot;: &quot;user@host&quot;}}</code> for the page to load; one nobody has is the error envelope with 404.</p>\n<h2 id=\"get-api-v1-ostatus-followremote-local\">GET /api/v1/ostatus/followRemote/{local}</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Renders the Vue app with the <strong>guest</strong> layout, providing <code>local</code> and <code>account</code> in initial state, so a remote visitor can follow the local account <code>{local}</code>.</p>\n<h2 id=\"get-api-v1-ostatus-link-local-account\">GET /api/v1/ostatus/link/{local}/{account}</h2>\n<p><strong>Auth: </strong>public, user, no-csrf, rate-limited (10/5min per IP) · <strong>Parameters: </strong>—</p>\n<p>WebFingers <code>{account}</code>, extracts its <code>http://ostatus.org/schema/1.0/subscribe</code> link template, substitutes <code>{uri}</code> with <code>{local}</code>&#39;s account, and returns <code>{&quot;result&quot;: {&quot;url&quot;: &quot;&lt;subscribe url&gt;&quot;}, &quot;status&quot;: 1}</code>. A template whose result is not an <code>http(s)</code> URL is a <strong>422</strong>: the browser is sent to the result, and the template is the remote server&#39;s to write.</p>\n<hr>\n","toc":[{"id":"get-ostatus-follow","text":"GET /ostatus/follow/","level":2},{"id":"post-api-v1-ostatus-resolve","text":"POST /api/v1/ostatus/resolve","level":2},{"id":"get-api-v1-ostatus-followremote-local","text":"GET /api/v1/ostatus/followRemote/{local}","level":2},{"id":"get-api-v1-ostatus-link-local-account","text":"GET /api/v1/ostatus/link/{local}/{account}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"legacy-ostatus","manual":false,"prev":{"path":"/docs/api-activitypub-federation","title":"ActivityPub Federation"},"next":{"path":"/docs/api-frontend-document-serving","title":"Frontend / Document serving"},"parent":null},{"slug":"api-frontend-document-serving","path":"/docs/api-frontend-document-serving","title":"Frontend / Document serving","description":"These serve HTML or files for the app's own UI; they are not client API endpoints.","group":"api","html":"<p>These serve HTML or files for the app&#39;s own UI; they are not client API endpoints.</p>\n<h2 id=\"get\">GET /</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong><code>cloudAddress</code> (read from the request during first-run setup, admins only)</p>\n<p>A signed-in reader gets the Vue app and private home feed as before. An anonymous visitor gets <code>PublicTemplateResponse</code> with only public-page state; no actor, cloud setup, current account or private feed is loaded. The client routes guests to the instance&#39;s public local feed.</p>\n<h2 id=\"get-timeline-path\">GET /timeline/{path}</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong><code>path</code> (default <code>&#39;&#39;</code>, <code>requirements: .+</code>)</p>\n<p>Same page. A visitor asking for one of the reader&#39;s own timelines — <code>notifications</code>, <code>direct</code>, <code>favourites</code>, <code>bookmarks</code>, <code>list/…</code>, <code>interests</code> — is sent to Nextcloud&#39;s login with the address as <code>redirect_url</code>, which brings them back once signed in; every other timeline is the public page.</p>\n<h2 id=\"get-follow-requests\">GET /follow_requests</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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. <strong>Signed-in only</strong>: not a public page, so Nextcloud sends a visitor to its login with the address as <code>redirect_url</code>, and back here once signed in.</p>\n<h2 id=\"get-blocked\">GET /blocked</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Same page, for the blocked-and-muted-accounts view (<strong>Settings → Blocking</strong> in the app&#39;s sidebar). <strong>Signed-in only</strong>: not a public page, so Nextcloud sends a visitor to its login with the address as <code>redirect_url</code>, and back here once signed in.</p>\n<h2 id=\"get-discover\">GET /discover</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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.</p>\n<h2 id=\"get-migration\">GET /migration</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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. <strong>Signed-in only</strong>: not a public page, so Nextcloud sends a visitor to its login with the address as <code>redirect_url</code>, and back here once signed in.</p>\n<h2 id=\"get-switch\">GET /switch</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Same page, for the step-by-step way in from another network (<strong>Moving in</strong>, linked from Migration). The client-side router owns the path; this route exists so that reloading or bookmarking it is not a 404. <strong>Signed-in only</strong>: not a public page, so Nextcloud sends a visitor to its login with the address as <code>redirect_url</code>, and back here once signed in.</p>\n<h2 id=\"get-statistics\">GET /statistics</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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. <strong>Signed-in only</strong>: not a public page, so Nextcloud sends a visitor to its login with the address as <code>redirect_url</code>, and back here once signed in.</p>\n<h2 id=\"get-shorts\">GET /shorts</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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.</p>\n<h2 id=\"get-reels\">GET /reels</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>The Shorts stack&#39;s earlier address, kept so that old links and bookmarks still open it: the same page, whose client-side router sends it on to <code>/shorts</code> with the query (<code>?scope=</code>) intact.</p>\n<h2 id=\"get-collections-id\">GET /collections/{id}</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Same page, for the collection view — one album, as a grid of its posts, with the owner&#39;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.</p>\n<h2 id=\"get-places-id\">GET /places/{id}</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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.</p>\n<h2 id=\"get-starter-pack-actor-rkey\">GET /starter-pack/{actor}/{rkey}</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Same page, for a Bluesky starter pack, at the path bsky.app gives it (<code>actor</code> 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.</p>\n<h2 id=\"get-settings\">GET /settings</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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. <strong>Signed-in only</strong>: not a public page, so Nextcloud sends a visitor to its login with the address as <code>redirect_url</code>, and back here once signed in.</p>\n<h2 id=\"get-search\">GET /search</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong>—</p>\n<p>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.</p>\n<h2 id=\"get-search-term\">GET /search/{term}</h2>\n<p><strong>Auth: </strong>public, user, no-csrf · <strong>Parameters: </strong><code>term</code> (accepted and ignored; the client-side router reads it off the address)</p>\n<p>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.</p>\n<h2 id=\"get-account-deleted\">GET /account-deleted</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong>—</p>\n<p>Public farewell page shown after a self-registered Aloha Social-only account and its active session have been removed.</p>\n<h2 id=\"get-document-get\">GET /document/get</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>Streams a cached document with its stored mime type: a picture, video or sound inline, anything else as a sandboxed <code>attachment</code> download. Errors: error envelope, HTTP 500.</p>\n<h2 id=\"get-document-public\">GET /document/public</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>Same for documents marked public.</p>\n<h2 id=\"get-document-get-resized\">GET /document/get/resized</h2>\n<p><strong>Auth: </strong>user, no-csrf · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>Streams the resized/preview variant.</p>\n<h2 id=\"get-document-public-resized\">GET /document/public/resized</h2>\n<p><strong>Auth: </strong>public, no-csrf · <strong>Parameters: </strong><code>id</code> (required)</p>\n<p>Same for public documents.</p>\n<hr>\n","toc":[{"id":"get","text":"GET /","level":2},{"id":"get-timeline-path","text":"GET /timeline/{path}","level":2},{"id":"get-follow-requests","text":"GET /follow_requests","level":2},{"id":"get-blocked","text":"GET /blocked","level":2},{"id":"get-discover","text":"GET /discover","level":2},{"id":"get-migration","text":"GET /migration","level":2},{"id":"get-switch","text":"GET /switch","level":2},{"id":"get-statistics","text":"GET /statistics","level":2},{"id":"get-shorts","text":"GET /shorts","level":2},{"id":"get-reels","text":"GET /reels","level":2},{"id":"get-collections-id","text":"GET /collections/{id}","level":2},{"id":"get-places-id","text":"GET /places/{id}","level":2},{"id":"get-starter-pack-actor-rkey","text":"GET /starter-pack/{actor}/{rkey}","level":2},{"id":"get-settings","text":"GET /settings","level":2},{"id":"get-search","text":"GET /search","level":2},{"id":"get-search-term","text":"GET /search/{term}","level":2},{"id":"get-account-deleted","text":"GET /account-deleted","level":2},{"id":"get-document-get","text":"GET /document/get","level":2},{"id":"get-document-public","text":"GET /document/public","level":2},{"id":"get-document-get-resized","text":"GET /document/get/resized","level":2},{"id":"get-document-public-resized","text":"GET /document/public/resized","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"frontend-document-serving","manual":false,"prev":{"path":"/docs/api-legacy-ostatus","title":"Legacy OStatus"},"next":{"path":"/docs/api-async-queue","title":"Async Queue"},"parent":null},{"slug":"api-async-queue","path":"/docs/api-async-queue","title":"Async Queue","description":"Auth: public, no-csrf, signed · Parameters: token (path); header X-Social-Async-Signature","group":"api","html":"<h2 id=\"post-async-request-token\">POST /async/request/{token}</h2>\n<p><strong>Auth: </strong>public, no-csrf, signed · <strong>Parameters: </strong><code>token</code> (path); header <code>X-Social-Async-Signature</code></p>\n<p>Internal endpoint the app calls against itself to deliver queued federation requests for <code>{token}</code>. The call carries an HMAC of the token under the instance secret (<code>AsyncRequestSigner</code>); without a valid one it is a <strong>403</strong> before the queue is read, counted by Nextcloud&#39;s brute-force protection — failures only, so the server&#39;s own calls are never slowed. With nothing queued it returns an empty HTTP 200. Otherwise it closes the connection (<code>async()</code>) and processes standby requests for at most <code>QueueController::MAX_DURATION</code> (20 s), the first <code>ASYNC_ROWS</code> (40) of them — whatever is left stays standby for the cron — then ends in <code>exit()</code>, since the connection is already gone.</p>\n<hr>\n","toc":[{"id":"post-async-request-token","text":"POST /async/request/{token}","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"async-queue","manual":false,"prev":{"path":"/docs/api-frontend-document-serving","title":"Frontend / Document serving"},"next":{"path":"/docs/api-error-responses","title":"Error Responses"},"parent":null},{"slug":"api-error-responses","path":"/docs/api-error-responses","title":"Error Responses","description":"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…","group":"api","html":"<p>There is no single error format; three shapes exist.</p>\n<p><strong>1. <code>TNCDataResponse</code> envelope</strong> (<code>LocalController</code>, <code>ConfigController</code>, <code>ActivityPubController</code>, <code>OStatusController</code>, <code>NavigationController</code> — everything using the trait):</p>\n<pre><code class=\"language-json\">{&quot;result&quot;: {}, &quot;status&quot;: 1}\n</code></pre>\n<p>on success (<code>success()</code>; <code>more</code> keys are merged in at the top level), and</p>\n<pre><code class=\"language-json\">{&quot;status&quot;: -1, &quot;error&quot;: &quot;request failed&quot;}\n</code></pre>\n<p>on failure (<code>fail()</code>) — 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 <strong>500</strong>, callers also use 404, and <code>Config#remote</code> 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: <code>failFor()</code> answers it <strong>403</strong> <code>{&quot;status&quot;: -1, &quot;error&quot;: &quot;...&quot;, &quot;code&quot;: &quot;account-not-set-up&quot;, &quot;setup_url&quot;: &quot;...&quot;}</code>, not logged. One related helper bypasses the envelope: <code>activityPubSuccess()</code> returns the object as-is with HTTP 200 and <code>Content-Type: application/ld+json; profile=&quot;https://www.w3.org/ns/activitystreams&quot;</code>.</p>\n<p><strong>2. <code>MastodonApiController</code> and <code>TagController</code> errors</strong> — a bare object, never the envelope:</p>\n<pre><code class=\"language-json\">{&quot;error&quot;: &quot;the access_token was revoked&quot;}\n</code></pre>\n<p>from the private <code>error()</code> helper of each, which maps the failure to a status a client can act on — see the table below. <code>TagController</code> maps the same four cases it can raise: 403 for a token whose scope is too narrow, 401 for no or stale credentials (<code>Bearer error=&quot;invalid_token&quot;</code>), 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 (<code>the access_token is invalid</code>, <code>not found</code>, <code>the request could not be processed</code>, <code>request failed</code>) rather than <code>{&quot;error&quot;: &quot;&quot;}</code>. <code>mediaOpen()</code> is the one route that does not go through it: a missing or non-public document is a 404, any other failure a 400.</p>\n<p>Every handler catches <code>Throwable</code>, not <code>Exception</code>. A <code>TypeError</code> — 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.</p>\n<p><strong>3. <code>OAuthController</code> errors</strong> — <code>{&quot;error&quot;: &quot;&lt;RFC 6749 name&gt;&quot;, &quot;error_description&quot;: &quot;...&quot;}</code> with HTTP 400 (<code>unsupported_grant_type</code>, <code>invalid_request</code> for a missing code, <code>invalid_grant</code>) or HTTP 401 (<code>invalid_client</code> for an unknown <code>client_id</code>; a wrong secret or a spent code answers with the reason as <code>error</code>).</p>\n<h2 id=\"client-api-status-codes\">Client API status codes</h2>\n<p><code>MastodonApiController::error()</code> keeps Mastodon&#39;s <code>{&quot;error&quot;: &quot;...&quot;}</code> 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.</p>\n<h2 id=\"401\">401</h2>\n<p>No credential, or one that is no longer valid (<code>ClientNotFoundException</code>, <code>AccountDoesNotExistException</code>). Carries <code>WWW-Authenticate: Bearer error=&quot;invalid_token&quot;</code>.</p>\n<h2 id=\"403\">403</h2>\n<p>A Nextcloud session or app password whose user has not set up their account here (<code>AccountNotSetUpException</code>): <code>{&quot;error&quot;, &quot;code&quot;: &quot;account-not-set-up&quot;, &quot;setup_url&quot;}</code>, see <a href=\"/docs/api-authentication#authentication\">Authentication</a>. An account that moved away, writing or following from here (<code>AccountMovedException</code>): 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 (<code>InsufficientScopeException</code>, tested ahead of the list because it extends <code>ClientException</code>). Sent <strong>without</strong> <code>WWW-Authenticate</code>: PHP rewrites the status of any response carrying that header to 401, so <code>Bearer error=&quot;insufficient_scope&quot;</code> 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 (<code>UnauthorizedFediverseException</code>).</p>\n<h2 id=\"404\">404</h2>\n<p>The thing asked for is not here: <code>StreamNotFoundException</code>, <code>CacheActorDoesNotExistException</code>, <code>ActorDoesNotExistException</code>, <code>ItemNotFoundException</code>, <code>CacheDocumentDoesNotExistException</code>, <code>HashtagDoesNotExistException</code>, <code>ReportNotFoundException</code>, <code>FollowNotFoundException</code>, <code>InstanceDoesNotExistException</code>, <code>OCP\\Files\\NotFoundException</code>, and a remote that answered with nothing (<code>RequestContentException</code>).</p>\n<h2 id=\"422\">422</h2>\n<p>The request was understood and refused, and retrying it unchanged cannot help: <code>InvalidActionException</code> (which now also covers a body that claims to be JSON and is not, and a <code>visibility</code> this app does not know), <code>UnknownProbeException</code>, <code>InvalidResourceException</code>, <code>InvalidResourceEntryException</code>, <code>InvalidHandleException</code>, <code>ItemUnknownException</code>, <code>CacheContentMimeTypeException</code>, <code>ClientException</code>.</p>\n<h2 id=\"429\">429</h2>\n<p><code>TooManyRequestsException</code>, and the <code>#[AnonRateLimit]</code> / <code>#[UserRateLimit]</code> limits on the write, search, account and timeline routes.</p>\n<h2 id=\"502\">502</h2>\n<p>Another server let us down: <code>RequestNetworkException</code>, <code>RequestServerException</code>, <code>RequestResultNotJsonException</code>, <code>RequestResultSizeException</code>.</p>\n<h2 id=\"500\">500</h2>\n<p>Anything unrecognised. The body is always <code>{&quot;error&quot;: &quot;internal server error&quot;}</code> and the real message is logged with its stack trace — these routes are all <code>#[PublicPage]</code>, and echoing <code>getMessage()</code> published whatever the failure happened to name.</p>\n<p>Successful Mastodon-compatible responses are <strong>not</strong> 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 — <code>RedirectResponse</code>&#39;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.</p>\n","toc":[{"id":"client-api-status-codes","text":"Client API status codes","level":2},{"id":"401","text":"401","level":2},{"id":"403","text":"403","level":2},{"id":"404","text":"404","level":2},{"id":"422","text":"422","level":2},{"id":"429","text":"429","level":2},{"id":"502","text":"502","level":2},{"id":"500","text":"500","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"error-responses","manual":false,"prev":{"path":"/docs/api-async-queue","title":"Async Queue"},"next":{"path":"/docs/api-numeric-status-identifiers","title":"Numeric status identifiers"},"parent":null},{"slug":"api-numeric-status-identifiers","path":"/docs/api-numeric-status-identifiers","title":"Numeric status identifiers","description":"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…","group":"api","html":"<p>Status <code>nid</code> 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 <code>PHP_INT_MAX</code>; 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 <code>min_id</code>, <code>max_id</code>, and <code>since_id</code> continue to work as before.</p>\n<h2 id=\"atproto-post-reply-replacement\">ATProto post reply replacement</h2>\n<p><code>com.atproto.repo.putRecord</code> supports replacing or omitting <code>reply</code> on an existing local <code>app.bsky.feed.post</code>. 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 <a href=\"/docs/federation-bluesky-client-writes#editing-reply-targets\">federation compatibility</a>.</p>\n<h2 id=\"remote-profile-synchronization-metadata\">Remote profile synchronization metadata</h2>\n<p>For an authenticated read of <code>GET /api/v1/accounts/{account}/statuses</code> for a\nremote ActivityPub actor, <code>X-Social-Profile-Sync-State</code> is one of <code>pending</code>,\n<code>failed</code> or <code>idle</code>. It describes the background read, not whether the entire\nremote account has been indexed. A failed outbox read or queue write remains\nvisible for a 60-second backoff before normal reads may queue it again. No raw\nremote exception is exposed. <code>X-Social-Profile-Filling</code> and the existing filling\nheaders remain backward compatible. Anonymous requests remain cache-only.</p>\n<p>An empty first page can continue an existing outbox cursor too, including a\nPhotos/Videos filter that has not found matching posts yet. The web frontend\nkeeps cached posts while checking, stops automatic profile polls after their\nbounded window, and offers a first-page recheck without clearing or duplicating\nthose posts. A stalled check is not a declaration that the remote account is empty.</p>\n<h2 id=\"event-card-status-metadata\">Event card status metadata</h2>\n<p>The optional event extension includes lowercase <code>status</code> (<code>confirmed</code>, <code>tentative</code>,\n<code>cancelled</code>) when the source supplied a recognized iCalendar or Schema.org status.\nUnknown values are omitted. ICS downloads include the corresponding STATUS and a\nvalid LAST-MODIFIED when the post has been updated. Calendar import confirms its\noutcome through <code>imported: true</code>; <code>already_imported: true</code> identifies an existing\nstable-UID copy and does not mean that copy was updated. See <a href=\"/docs/events\">Events.md</a>\nfor timezone, content-warning, import and attendance boundaries.</p>\n<h2 id=\"visual-media-timeline-filter\">Visual media timeline filter</h2>\n<p>The Social <code>media_type</code> extension accepts <code>visual</code> in addition to <code>image</code>, <code>video</code>\nand <code>audio</code>. It selects posts with photos, videos or animated images, including\nnative ActivityPub Video objects. It implies media filtering and excludes pure\ntext, audio and documents before pagination. Existing individual media filters\nand unfiltered timeline semantics are unchanged. Photos timeline layouts share\nthis filter; profile Photos tabs continue to request <code>image</code>.</p>\n","toc":[{"id":"atproto-post-reply-replacement","text":"ATProto post reply replacement","level":2},{"id":"remote-profile-synchronization-metadata","text":"Remote profile synchronization metadata","level":2},{"id":"event-card-status-metadata","text":"Event card status metadata","level":2},{"id":"visual-media-timeline-filter","text":"Visual media timeline filter","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/API.md","sections":null,"anchor":"numeric-status-identifiers","manual":false,"prev":{"path":"/docs/api-error-responses","title":"Error Responses"},"next":null,"parent":null},{"slug":"architecture","path":"/docs/architecture","title":"Aloha Social — Architecture Overview","description":"The app's data model, routing, services, federation flows and frontend.","group":"architecture","html":"","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":[{"path":"/docs/architecture-identifier-width-and-php-32-bit-support","title":"Identifier width and PHP 32-bit support","description":"Stream nid values are decimal identifiers stored in the database's BIGINT columns. They are generated from the published timestamp followed by a fixed-width random suffix, so database…","parent":false},{"path":"/docs/architecture-introduction","title":"Introduction","description":"Aloha Social is a federated social networking app built on the W3C ActivityPub standard. It integrates into Nextcloud as an app, providing each user with an ActivityPub identity (Person…","parent":false},{"path":"/docs/architecture-directory-structure","title":"Directory Structure","description":"There is no lib/bootstrap.php; Composer's autoloader is pulled in by lib/AppInfo/Application.php.","parent":false},{"path":"/docs/architecture-http-routing","title":"HTTP routing","description":"The app's routes, apart from the few in appinfo/routes.php, are #[FrontpageRoute] attributes on the controller method that answers the request, next to the #[PublicPage], #[NoCSRFRequired]…","parent":false},{"path":"/docs/architecture-database-schema","title":"Database Schema","description":"Every query in the app is built by one class chain. ExtendedQueryBuilder (lib/Tools/Db/) holds a query builder the server handed it through IDBConnection::getQueryBuilder() and delegates…","parent":false},{"path":"/docs/architecture-key-services","title":"Key Services","description":"The business logic lives in lib/Service/.","parent":false},{"path":"/docs/architecture-account-and-identity","title":"Account & Identity","description":"Creates local actors (generating an RSA key pair via SignatureService) and marks them deleted, refreshes the local actor cache (avatar, display name, follower/following/post counts)…","parent":true},{"path":"/docs/architecture-content-and-timelines","title":"Content & Timelines","description":"Local post edits write a UTC, second-precision ActivityPub updated value strictly later than the previous edit, so peers can order rapid successive Update activities.","parent":true},{"path":"/docs/architecture-federation","title":"Federation","description":"Wraps items in Create/Update/Delete activities, LD-signs them, resolves target inboxes, and drives the delivery queue. A reply whose parent exists only on Bluesky keeps its native…","parent":true},{"path":"/docs/architecture-media","title":"Media","description":"Owns the cached document lifecycle: caching a remote document by id, serving originals and resized copies out of app storage, and caching the local actor's avatar and header. Serving…","parent":true},{"path":"/docs/architecture-system","title":"System","description":"App/user configuration and the derived URLs (cloud URL, social URL, social address, max download size, self-signed toggle), plus ActivityPub id generation. The social URL is derived from…","parent":true},{"path":"/docs/architecture-mastodon-web-push","title":"Mastodon Web Push","description":"VapidService creates one stable instance key pair and seals the private key with PrivateKeyCipher; PushSubscriptionService keeps each access token, endpoint and browser key pair in an…","parent":true},{"path":"/docs/architecture-mastodon-websocket-and-sse-streaming","title":"Mastodon WebSocket and SSE streaming","description":"MastodonStreamingDaemon (occ social:mastodon:stream) serves the user, user:notification, direct, list, public, public:media, public:local, public:local:media, public:remote…","parent":true},{"path":"/docs/architecture-activitypub-federation","title":"ActivityPub Federation","description":"ActivityPub is the federation protocol this app speaks; it is also a Bluesky host (AT Protocol), with every local account a did:plc identity whose repository, firehose and XRPC surface…","parent":false},{"path":"/docs/architecture-resuming-bluesky-synchronization","title":"Resuming Bluesky synchronization","description":"Cron\\AtprotoSync runs once a minute and spends its 45-second budget on notifications before feeds and direct messages, so a slow feed cannot keep likes, reposts and replies to local posts…","parent":true},{"path":"/docs/architecture-actor-identity","title":"Actor Identity","description":"Alongside the per-user actors, the instance has one Application actor of its own at <social url>actor, with its own RSA key pair in app config. It is what signs every outbound ActivityPub…","parent":true},{"path":"/docs/architecture-outgoing-flow","title":"Outgoing Flow","description":"adds a Linked Data Signature — for Create, Update, Delete, Like, Announce and their Undos. Follow, Accept, Reject, Block and Undo{Block} are not LD-signed; they travel with the HTTP…","parent":true},{"path":"/docs/architecture-incoming-flow","title":"Incoming Flow","description":"spends the per-address bucket, before anything is read, and readBody() reads at most 1 MiB of body — refusing more with 413","parent":true},{"path":"/docs/architecture-peertube-and-federated-video","title":"PeerTube and federated video","description":"A Video is one of the note-like types in AP::NOTE_LIKE_TYPES — object types other servers Create into a timeline that this app has no model of its own for — and like the rest of them it is…","parent":true},{"path":"/docs/architecture-reading-a-timeline-at-scale","title":"Reading a timeline at scale","description":"Three things decide whether this app works on an instance with a million accounts and ten million posts, and all three were measured rather than reasoned about — occ social:benchmark seeds…","parent":false},{"path":"/docs/architecture-delivering-at-scale","title":"Delivering at scale","description":"Cron\\Queue used to read 200 rows every twelve minutes and deliver them one after another with a 30-second timeout each inside a 300-second budget: about a thousand deliveries an hour at…","parent":false},{"path":"/docs/architecture-what-a-poll-costs","title":"What a poll costs","description":"A client asks for the home timeline and the unread count every thirty seconds, and the answer is almost always the one it already holds. Both carry an ETag built from the newest id the…","parent":false},{"path":"/docs/architecture-quote-posts","title":"Quote posts","description":"A quote is a post that embeds another post rather than linking to it, and the part that needs agreeing on is not the embedding — it is consent. FEP-044f, and Mastodon 4.5 with it, treats a…","parent":true},{"path":"/docs/architecture-whole-conversations","title":"Whole conversations","description":"Opening a conversation also asks this source inline with a three-second timeout, guarded by a per-post lock. Each returned root and continuation is checked against the requested AT-URI…","parent":true},{"path":"/docs/architecture-who-liked-boosted-or-quoted","title":"Who liked, boosted or quoted","description":"Who reacted is kept an hour in the durable cache's table (DurableCache::setShared(), which the cron and the web server share even where APCu is the only memcache), not as actions: the…","parent":true},{"path":"/docs/architecture-who-follows-an-account-and-whom-it-follows","title":"Who follows an account, and whom it follows","description":"What a network listed is kept an hour in the durable cache's table (DurableCache::setShared(), social.followlists). The routes (AccountApiController::accountFollowers()/accountFollowing())…","parent":true},{"path":"/docs/architecture-counts-where-a-post-lives","title":"Counts where a post lives","description":"CountService::seen() is called with what a page serves — a status (StatusApiController::statusGet()), a conversation (StreamService::getContextByNid()) and every timeline page a client…","parent":true},{"path":"/docs/architecture-hashtags-and-searches-beyond-this-server","title":"Hashtags and searches beyond this server","description":"What is found is stored like any arriving post, indexed for the search as it is stored, so the timeline and the search simply have it the next time. The answers say X-Social-Filling while…","parent":true},{"path":"/docs/architecture-hidden-replies","title":"Hidden replies","description":"The author of a thread's first post may hide any reply in it, wherever it was written (HiddenReplyService, the hide_reply status action). The ids are kept on that first post…","parent":true},{"path":"/docs/architecture-who-may-reply","title":"Who may reply","description":"The author of a post written here says who may reply to it: everybody (the default), nobody, or any combination of their followers, the accounts they follow, the accounts the post mentions…","parent":true},{"path":"/docs/architecture-bluesky-custom-feeds-and-lists","title":"Bluesky custom feeds and lists","description":"Atproto\\Reader\\BlueskyFeeds reads getFeed and getListFeed as the viewer and filters posts they cannot see. An AppView page may contain only hidden posts and still include a continuation…","parent":true},{"path":"/docs/architecture-bookmarks-here-and-on-bluesky","title":"Bookmarks, here and on Bluesky","description":"Atproto\\Publisher\\BlueskyBookmarks keeps a person's bookmarks in step with Bluesky apps signed in here. getBookmarks reads the local bookmark timeline and includes the posts that have a…","parent":true},{"path":"/docs/architecture-direct-messages-with-bluesky","title":"Direct messages with Bluesky","description":"A conversation with somebody on Bluesky is a conversation in Messages like any other. Bluesky keeps direct messages on its chat service, not in repositories, so Atproto\\Chat\\ChatPoller (a…","parent":true},{"path":"/docs/architecture-lists-here-and-on-bluesky","title":"Lists, here and on Bluesky","description":"A person's lists are one set with their Bluesky lists. A list is private unless its owner makes it public (social_list.visibility; public on PUT /api/v1/lists/{id}, a switch in Settings →…","parent":true},{"path":"/docs/architecture-switching-off-bluesky","title":"Switching off Bluesky","description":"A person may switch their own presence on Bluesky off (D23 of the Bluesky specification, §4.6; Settings → Apps and account → Bluesky, POST /api/v1/social/bluesky/state).…","parent":true},{"path":"/docs/architecture-shared-lists-to-mute-or-block","title":"Shared lists to mute or block","description":"A person subscribes to somebody else's list of accounts, to mute or block everybody on it (ModerationListService, Blocking → Shared lists, /api/v1/social/moderation_lists). Each network…","parent":true},{"path":"/docs/architecture-accounts-this-instance-verified","title":"Accounts this instance verified","description":"Moderators verify accounts in the instance's name (VerificationService, VerificationController; Administration → Moderation → Verified accounts and the profile menu, which…","parent":true},{"path":"/docs/architecture-discovery","title":"Discovery","description":"All three return the previous handler's response untouched when FediverseService::jailed() says the instance is in allow-list mode with an empty list.","parent":true},{"path":"/docs/architecture-reading-a-timeline","title":"Reading a timeline","description":"The first decides which posts belong in the page: it carries all the joins and filters (recipients, follows, hidden actors, duplicate suppression) but projects a single column, s.nid. The…","parent":true},{"path":"/docs/architecture-frontend-architecture","title":"Frontend Architecture","description":"The user interface is a Vue 3 front end using Vue Router, Pinia, @nextcloud/vue components, @nextcloud/axios, DOMPurify (via src/utils/sanitizeHtml.js), and the Twemoji pictures of…","parent":false},{"path":"/docs/architecture-entry-bundles","title":"Entry bundles","description":"The OStatus bundle and src/views/OStatus.vue are therefore dead code today: OStatusController::subscribe() and followRemote() both render the main template, so remote-follow lands in the…","parent":true},{"path":"/docs/architecture-store","title":"Store","description":"src/store/ holds six Pinia stores — timeline, account, settings, errors, notifications and instance — and index.js creates the Pinia every entry point installs. Components reach them…","parent":true},{"path":"/docs/architecture-routes-and-views","title":"Routes and views","description":"profile.followers and profile.following render the same ProfileFollowers component; it decides what to load from the route.","parent":true},{"path":"/docs/architecture-components","title":"Components","description":"A post in a list is a row, not a card. TimelineEntry flattens the post it holds (:not(.timeline-entry--direct), so on Activities too): no frame, no shadow, padding taken back to the row, a…","parent":true},{"path":"/docs/architecture-direct-messages","title":"Direct messages","description":"presents the direct timeline as a conversation list beside the selected thread. The list calls the Mastodon-compatible GET /api/v1/conversations route (40 newest conversations per…","parent":true},{"path":"/docs/architecture-integration-points","title":"Integration Points","description":"Recent Aloha Social notifications, rendered client-side; loads social-dashboard","parent":false},{"path":"/docs/architecture-replies-as-comments-in-files","title":"Replies as comments in Files","description":"A picture posted from Files keeps a link to the file it was copied from, and the conversation about it can be read in the file's Comments tab (FileCommentsService, tables social_file_post…","parent":true},{"path":"/docs/architecture-events-this-app-publishes","title":"Events this app publishes","description":"The app listens to Nextcloud's events and, until now, published none of its own — so nothing else on the server could know that somebody had posted. An Activity entry, a Talk message, a…","parent":true},{"path":"/docs/architecture-account-export-and-import","title":"Account export and import","description":"lib/UserMigration/SocialMigrator.php implements the server's OCP\\UserMigration\\IMigrator (and ISizeEstimationMigrator), registered in Application::register(). It is what makes a user's…","parent":false},{"path":"/docs/architecture-external-users","title":"External users","description":"Internal Nextcloud users use Aloha Social as they always have. An administrator can also open Aloha Social to a limited number of external users: people without a Nextcloud account who…","parent":false},{"path":"/docs/architecture-security","title":"Security","description":"a signature on a GET is verified by SignatureService::checkGetRequest() and resolved to the account behind it by AuthorizedFetchService::reader(), so what this instance serves can depend…","parent":false},{"path":"/docs/architecture-supporting-two-nextcloud-versions","title":"Supporting two Nextcloud versions","description":"appinfo/info.xml claims 35 and 36, and both are meant, so a change has to hold on either.","parent":false},{"path":"/docs/architecture-keeping-this-document-in-sync","title":"Keeping this document in sync","description":"This file, docs/API.md and docs/OCC-Commands.md describe the current implementation. They must be updated in the same change as the code they describe.","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/architecture-identifier-width-and-php-32-bit-support","title":"Identifier width and PHP 32-bit support"},"parent":null},{"slug":"architecture-identifier-width-and-php-32-bit-support","path":"/docs/architecture-identifier-width-and-php-32-bit-support","title":"Identifier width and PHP 32-bit support","description":"Stream nid values are decimal identifiers stored in the database's BIGINT columns. They are generated from the published timestamp followed by a fixed-width random suffix, so database…","group":"architecture","html":"<p>Stream <code>nid</code> values are decimal identifiers stored in the database&#39;s <code>BIGINT</code> columns. They are generated from the published timestamp followed by a fixed-width random suffix, so database ordering remains chronological. A <code>nid</code> can exceed <code>PHP_INT_MAX</code> on a 32-bit PHP build even though its timestamp component is representable, and even a 64-bit PHP integer exceeds JavaScript&#39;s exact-integer range. The application therefore keeps stream identifiers as normalized decimal strings from HTTP route and cursor input through models, pagination, database parameters, and JSON output. In particular, local status <code>id</code> and <code>nid</code> fields must be strings so browser clients can round-trip the exact identifier; <code>Tools\\Nid</code> handles comparisons without converting the full value to a PHP integer. Do not cast a stream <code>nid</code>, or bind it as <code>PARAM_INT</code>; bind it as a decimal string. Ordinary counters, timestamps, media sizes, and auto-increment row IDs remain integers.</p>\n<p>Regression coverage includes identifiers above the 32-bit signed integer range and verifies normalization, ordering, and generator shape. Database integration runs against the supported database engines on the normal 64-bit CI runtime; Nextcloud documents 32-bit PHP as supported but recommends 64-bit PHP.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"identifier-width-and-php-32-bit-support","manual":false,"prev":{"path":"/docs/architecture","title":"Aloha Social — Architecture Overview"},"next":{"path":"/docs/architecture-introduction","title":"Introduction"},"parent":null},{"slug":"architecture-introduction","path":"/docs/architecture-introduction","title":"Introduction","description":"Aloha Social is a federated social networking app built on the W3C ActivityPub standard. It integrates into Nextcloud as an app, providing each user with an ActivityPub identity (Person…","group":"architecture","html":"<p>Aloha Social is a federated social networking app built on the W3C ActivityPub standard. It integrates into Nextcloud as an app, providing each user with an ActivityPub identity (Person actor) that can interact with Mastodon, Friendica, and other Fediverse platforms.</p>\n<p><strong>App ID:</strong> <code>social</code>\n<strong>Namespace:</strong> <code>OCA\\Social</code>\n<strong>License:</strong> AGPL-3.0-or-later\n<strong>App version:</strong> 0.26.279\n<strong>Supported Nextcloud versions:</strong> 34 – 36\n<strong>Supported PHP versions:</strong> 8.3 – 8.5</p>\n<p>All of the above come from <code>appinfo/info.xml</code>.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"introduction","manual":false,"prev":{"path":"/docs/architecture-identifier-width-and-php-32-bit-support","title":"Identifier width and PHP 32-bit support"},"next":{"path":"/docs/architecture-directory-structure","title":"Directory Structure"},"parent":null},{"slug":"architecture-directory-structure","path":"/docs/architecture-directory-structure","title":"Directory Structure","description":"There is no lib/bootstrap.php; Composer's autoloader is pulled in by lib/AppInfo/Application.php.","group":"architecture","html":"<pre><code>social/\n├── appinfo/\n│   ├── info.xml                # App metadata, dependencies, cron jobs, occ commands\n│   └── routes.php              # One route; the other 258 are attributes on the controller methods\n├── lib/\n│   ├── AP.php                  # ActivityPub type registry (factory + interface lookup)\n│   ├── AppInfo/\n│   │   └── Application.php     # Bootstrap, integration registration\n│   ├── Command/                # occ CLI commands (+ ExtendedBase, a shared base that registers no command of its own)\n│   ├── Controller/             # HTTP entry points (ActivityPub, Mastodon-ish API, local API, OAuth, OStatus, navigation, queue, config, moderation, public pages)\n│   ├── Cron/                   # Background jobs (Cache, Queue, ScheduledPosts, NotificationDigests, ExpiredStories, InterestHides; DomainPurge, ActorCleanup, TranscodeBeforeDelivery, StreamAuthorHosts and CompactStoredCopies are queued with an argument)\n│   ├── Dashboard/              # Nextcloud Dashboard widgets\n│   ├── Db/                     # Query-builder based repositories (`*Request` + `*RequestBuilder` pairs), on the public `IQueryBuilder`\n│   ├── Exceptions/             # Custom exceptions\n│   ├── Interfaces/             # Per-ActivityPub-type handlers (Activity/, Actor/, Object/, Internal/)\n│   ├── Listeners/              # Event listeners (ProfileSectionListener, UserAccountListener, UserDeletedListener)\n│   ├── Migration/              # Database schema migrations + repair steps\n│   ├── Model/                  # ActivityPub model objects + support models\n│   ├── Notification/           # Nextcloud notification integration (Notifier)\n│   ├── Providers/              # Contacts menu integration\n│   ├── Search/                 # Unified search integration\n│   ├── Service/                # Business logic services\n│   ├── Security/               # Key cipher, secret hasher, HTML sanitizer, outbound-address guard\n│   ├── Settings/               # Admin settings (moderation panel: reports, Fediverse access list, Server card)\n│   ├── SetupChecks/            # The four ISetupCheck classes shown in Administration → Overview\n│   ├── Tools/                  # Vendored helper layer (query builder helpers, traits, exceptions) — see docs/Technical-Debt.md\n│   ├── UserMigration/          # Account export/import (`SocialMigrator`, the Nextcloud user-migration framework)\n│   ├── Traits/                 # TDetails\n│   └── WellKnown/              # WebFinger / NodeInfo / host-meta handler and responses\n├── src/                        # Vue 3 frontend\n│   ├── main.js                 # Main SPA entry\n│   ├── dashboard.js            # Dashboard widget entry\n│   ├── oauth.js                # OAuth authorization page entry\n│   ├── ostatus.js              # OStatus entry (built, but no server route loads it — see below)\n│   ├── profile.js              # Profile-page custom element entry\n│   ├── App.vue                 # Root component of the main SPA\n│   ├── router.js               # Vue Router configuration\n│   ├── store/                  # Pinia stores (index.js + timeline, account, settings, errors, notifications)\n│   ├── views/                  # Route- and entry-level components\n│   ├── components/             # UI components (`.vue`, plus MessageContent.js)\n│   ├── services/               # eventBus, logger, notifications, clock, draft, shortcuts\n│   ├── composables/            # useAccount, useCurrentUser, useServerData, useSoundAutoplay, …\n│   ├── directives/             # focusOnCreate\n│   ├── utils/                  # sanitizeHtml (+ its unit test), dominantColour, emojiCodePoint, instanceIdentity, locale, relativeTime, viewTransition\n│   └── types/                  # JSDoc type definitions (ActivityPub, Mastodon)\n├── templates/                  # PHP templates: main.php (SPA), oauth2.php\n├── l10n/                       # Translations\n└── docs/                       # Documentation\n</code></pre>\n<p>There is no <code>lib/bootstrap.php</code>; Composer&#39;s autoloader is pulled in by <code>lib/AppInfo/Application.php</code>.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"directory-structure","manual":false,"prev":{"path":"/docs/architecture-introduction","title":"Introduction"},"next":{"path":"/docs/architecture-http-routing","title":"HTTP routing"},"parent":null},{"slug":"architecture-http-routing","path":"/docs/architecture-http-routing","title":"HTTP routing","description":"The app's routes, apart from the few in appinfo/routes.php, are #[FrontpageRoute] attributes on the controller method that answers the request, next to the #[PublicPage], #[NoCSRFRequired]…","group":"architecture","html":"<p>The app&#39;s routes, apart from the few in <code>appinfo/routes.php</code>, are\n<code>#[FrontpageRoute]</code> attributes on the controller method that answers the request, next to the <code>#[PublicPage]</code>,\n<code>#[NoCSRFRequired]</code> and rate-limit attributes that decide who may call it — url\nand policy in one place. None are <code>#[ApiRoute]</code>: that is the OCS type, and the\nserver serves OCS routes under <code>/ocsapp</code>, which is not where these paths are\npublished.</p>\n<p>A <code>#[PublicPage]</code> route that carries <code>#[UserRateLimit]</code> carries a matching\n<code>#[AnonRateLimit]</code> as well. A client holding one of this app&#39;s OAuth tokens has\nno Nextcloud session, so Nextcloud counts it as anonymous and applies only the\nanonymous limit, and <code>RateLimitService</code> leaves the app&#39;s default budget off a\nroute that declares a limit of its own: with <code>UserRateLimit</code> alone, a token\nclient would have no limit at all. A route without <code>#[PublicPage]</code> is refused\nto a caller who is not signed in before any limit is read, so <code>UserRateLimit</code>\nalone is enough there. <code>RateLimitAttributesTest</code> holds every controller to it.</p>\n<p>Two things about the order the server reads routes in, because two routes of this\napp can match the same url:</p>\n<ul>\n<li><code>OC\\Route\\Router::getAttributeRoutes()</code> walks <code>lib/Controller</code> with a\n<code>DirectoryIterator</code> and reflects over each <code>*Controller.php</code>, so attributes\nare read in method-declaration order <strong>within</strong> a class, and in whatever order\nthe filesystem lists the files <strong>between</strong> classes. Where a url is ambiguous,\nonly the within-a-class order can be relied on:\n<code>ActivityPubController::displayPost()</code> (<code>/@{username}/{token}</code>) is declared\nafter <code>getInbox()</code>, <code>outbox()</code>, <code>followers()</code> and <code>following()</code> for that\nreason, and has to stay there.</li>\n<li><code>appinfo/routes.php</code> is loaded after every attribute route of the app. That is\nwhy <code>AccountApiController::accountGet()</code> is still declared there: its\n<code>/api/v1/accounts/{id}</code> accepts slashes in <code>{id}</code>, so it also matches\n<code>/api/v1/accounts/{account}/lists</code> and <code>/api/v1/accounts/{account}/featured_tags</code>,\nwhich live in <code>ListController</code> and <code>DiscoveryController</code> — no arrangement of\nattributes can put it after routes of another class.</li>\n<li>A trait&#39;s methods come after the class&#39;s own. <code>statusWatched()</code> once sat in\na trait, so <code>statusAction()</code>&#39;s <code>/api/v1/statuses/{nid}/{act}</code> was offered\nfirst and <code>POST …/watched</code> never reached it; <code>StatusApiController</code> declares\nit, and every other route that path shape also matches, ahead of\n<code>statusAction()</code>. <code>NotificationController::policy()</code> is declared ahead of\n<code>group()</code> for the same reason: <code>/api/v2/notifications/{group_key}</code> matches\n<code>/api/v2/notifications/policy</code>.</li>\n</ul>\n<p><code>tests/AppInfo/RouteOrderTest.php</code> holds all three rules: it reads the routes in\nthe server&#39;s order and fails on any route a path of which is caught by one read\nbefore it — or by one in another controller, whose order is not defined.</p>\n<p>A route&#39;s name is derived, not written: the controller&#39;s short name without the\n<code>Controller</code> suffix, then <code>#</code>, then the method. Two routes on one method\ntherefore share a name unless one carries a <code>postfix</code>, and the later one wins —\nwhich is what <code>NavigationController::navigate()</code> and <code>personal()</code> use <code>postfix</code> for.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"http-routing","manual":false,"prev":{"path":"/docs/architecture-directory-structure","title":"Directory Structure"},"next":{"path":"/docs/architecture-database-schema","title":"Database Schema"},"parent":null},{"slug":"architecture-database-schema","path":"/docs/architecture-database-schema","title":"Database Schema","description":"Every query in the app is built by one class chain. ExtendedQueryBuilder (lib/Tools/Db/) holds a query builder the server handed it through IDBConnection::getQueryBuilder() and delegates…","group":"architecture","html":"<p>Every query in the app is built by one class chain. <code>ExtendedQueryBuilder</code>\n(<code>lib/Tools/Db/</code>) holds a query builder the server handed it through\n<code>IDBConnection::getQueryBuilder()</code> and delegates the whole <code>IQueryBuilder</code>\ninterface to it, adding the <code>limitTo*</code> / <code>searchIn*</code> helpers the <code>lib/Db/</code>\nrepositories are written against. <code>SocialCoreQueryBuilder</code> adds the viewer,\nand <code>SocialCross</code>, <code>SocialLimits</code>, <code>SocialFilters</code> and <code>SocialQueryBuilder</code>\nadd the joins, visibility filters and pagination on top of it.</p>\n<p>It is composition rather than inheritance on purpose: the chain used to extend\n<code>OC\\DB\\QueryBuilder\\QueryBuilder</code> from the server&#39;s <code>lib/private/</code>, which put\nall 68 repository classes on a constructor signature that carries no stability\npromise and broke outright when Nextcloud 35 added a method to the public\ninterface. Nothing in <code>lib/</code> now names a class outside <code>OCP\\</code>.</p>\n<p><code>StreamRequest</code>, the repository of <code>social_stream</code>, is one class spread over\nseveral files: what it reads and writes for one concern is a trait it uses —\n<code>StreamTimelines</code> (every timeline), <code>StreamInterests</code> (For you),\n<code>StreamThreads</code> (replies and the conversation under a post), <code>StreamSearch</code>\n(full-text search), <code>StreamCounters</code> (the reply/like/boost counters),\n<code>StreamMedia</code> (stored attachment copies and <code>social_stream_media</code>),\n<code>StreamStatistics</code> (tallies for the admin, profile and statistics pages) and\n<code>StreamDeletion</code> (removing posts and what hangs off them). A trait rather than\na class because each reaches into <code>StreamRequest</code> for its query builders and\ninjected requests; the header of <code>StreamTimelines</code> says why. Writing and\nreading a single post stays in <code>StreamRequest.php</code>.</p>\n<p>The tables are created by <code>lib/Migration/Version1000Date20221118000002.php</code> — the whole schema in one step — all prefixed with <code>social_</code>:</p>\n<h2 id=\"social-action\">social_action</h2>\n<p>Like/Announce actions as ActivityPub objects (actor → object, with type); a <code>Vote</code> row also carries <code>poll_prim</code>, the md5 of the poll it was cast in (indexed, <code>&#39;&#39;</code> on every other action), so the closed-poll sweep reads the voters of all its polls in one <code>IN</code></p>\n<h2 id=\"social-actor\">social_actor</h2>\n<p>Local user actors (tied to NC accounts, holds the RSA key pair)</p>\n<h2 id=\"social-cache-actor\">social_cache_actor</h2>\n<p>Cached remote federated actors (inbox/outbox URLs, public keys, counts), the refresh bookkeeping <code>sync_attempt</code>/<code>sync_failures</code>, and <code>account_lower</code>, the handle lowercased and indexed (<code>social_ca_al</code>) for the account search and the lookup by handle</p>\n<h2 id=\"social-cache-doc\">social_cache_doc</h2>\n<p>Cached remote and local media attachments. <code>ai_source</code> (SMALLINT, default 0) is the machine-generation provenance the picture&#39;s metadata stated when it was stored — <code>1</code> IPTC&#39;s <code>trainedAlgorithmicMedia</code>, <code>2</code> its <code>compositeWithTrainedAlgorithmicMedia</code> — read by <code>ImageMetadataService::digitalSourceType()</code> <em>before</em> the metadata is stripped, because the stored bytes no longer say it; rows from before the column read as 0</p>\n<h2 id=\"social-client\">social_client</h2>\n<p>OAuth 2.0 client registrations</p>\n<h2 id=\"social-device-auth\">social_device_auth</h2>\n<p>hashed one-time OAuth device codes, short user codes, scope grants, polling interval and expiry; pruned with the OAuth client sweep and removed by the account cascade when the approved Nextcloud user is deleted</p>\n<h2 id=\"social-follow\">social_follow</h2>\n<p>Follow relationships (actor → object, with accepted flag)</p>\n<h2 id=\"social-hashtag\">social_hashtag</h2>\n<p>Hashtag trend data: a JSON <code>trend</code> blob per hashtag, plus one sortable integer column per window (<code>trend_1h</code> … <code>trend_10d</code>). A row is written with zero counts when a public post first carries the hashtag (<code>StreamTagsRequest::generateStreamTags()</code>), so a hashtag search finds it at once; the trends cron fills the counts</p>\n<h2 id=\"social-instance\">social_instance</h2>\n<p>Known federated instances (version, metadata)</p>\n<h2 id=\"social-req-queue\">social_req_queue</h2>\n<p>Outbound ActivityPub delivery queue, indexed for the drain&#39;s own sort on <code>(status, priority, tries, last)</code></p>\n<h2 id=\"social-host-breaker\">social_host_breaker</h2>\n<p>The delivery circuit breaker: one row per peer that failed within the last hour, with its consecutive failures and the moment it is worth asking again, in unix seconds. Read once per drain by <code>ActivityService</code> and by <code>StreamQueueService</code> (<code>HostBreaker</code>), so a row addressed to a dead peer is held back without spending a timeout; cleared when the peer answers, forgotten an hour after its last failure (<code>Cron\\Queue</code>)</p>\n<h2 id=\"social-stream\">social_stream</h2>\n<p>Core content table: posts, notes, activities. Nine JSON-in-TEXT columns (<code>to_array</code>, <code>cc</code>, <code>bcc</code>, <code>hashtags</code>, <code>tags</code>, <code>details</code>, <code>instances</code>, <code>attachments</code>, <code>cache</code>) beside the scalar ones; <code>source</code> holds the ActivityPub wire object verbatim, and <code>archived</code> — a post its author has put away. <code>count_replies</code>, <code>count_likes</code>, <code>count_boosts</code> and <code>count_dislikes</code> (INTEGER, default 0) are the post&#39;s counters, written only by <code>StreamRequest::recount()</code> and laid over the matching <code>details</code> keys on read. <code>poll_ends_at</code> (BIGINT, indexed, NULL on everything but a poll with an end) is a poll&#39;s <code>endTime</code> as a Unix time, copied out on every save and edit, so the closed-poll sweep reads exactly the polls that closed in its window, earliest first. <code>poll_ends_at</code> (BIGINT, indexed, NULL on everything but a poll with an end) is a poll&#39;s <code>endTime</code> as a Unix time, copied out on every save and edit, so the closed-poll sweep reads exactly the polls that closed in its window, earliest first. <code>author_host</code> (VARCHAR 191, indexed) is the lower-cased host of <code>attributed_to</code>, written on every save and author rewrite and backfilled by <code>Cron\\StreamAuthorHosts</code>; NULL on a row the job has not reached, <code>&#39;&#39;</code> for an id with no host. <code>root_prim</code> (VARCHAR 32, indexed) is the prim of the root of a direct message&#39;s thread, written when the message is stored (<code>ConversationsRequest::storeRoot()</code>) and backfilled by <code>Cron\\ThreadRoots</code>; NULL on every other post and on a direct message the job has not reached</p>\n<h2 id=\"social-discover-cat\">social_discover_cat</h2>\n<p>The subjects an instance says Explore is about: a name and the hashtags it means, in the order an administrator put them in</p>\n<h2 id=\"social-trend-review\">social_trend_review</h2>\n<p>What a moderator has decided about something that is trending: one row per rejected (or approved) tag, link or status</p>\n<h2 id=\"social-relay\">social_relay</h2>\n<p>The relays this instance subscribes to: one row per subscription, with the <code>Follow</code> it sent, the inbox to deliver to and whether the relay answered</p>\n<h2 id=\"social-channel\">social_channel</h2>\n<p>The <code>Group</code> actors an account publishes videos under: one row per channel, binding it to the account that owns it. A channel is deleted with the account that owns it, as an account of its own (<code>AccountService::deleteActor()</code>)</p>\n<h2 id=\"social-watch\">social_watch</h2>\n<p>Where a reader stopped watching a video: one row per (post, viewer), never federated</p>\n<h2 id=\"social-video-views\">social_video_views</h2>\n<p>How many times each video posted here was watched: one row per post, unique on it, a counter moved in SQL (<code>VideoViewService</code>), deleted with the post</p>\n<h2 id=\"social-video-seen\">social_video_seen</h2>\n<p>Who has already been counted watching a video today: one row per (post, viewer hash), unique on the pair, where the hash is keyed with the instance secret over (day, post, account or session); the rows of earlier days are deleted by <code>Cron\\Cache</code>, so nothing about who watched outlives the day</p>\n<h2 id=\"social-video-rendition\">social_video_rendition</h2>\n<p>The rungs of a local video&#39;s ladder: one row per (video, height), each naming one fragmented MP4 and the playlist that addresses it</p>\n<h2 id=\"social-file-post\">social_file_post</h2>\n<p>Which Nextcloud file a post was made from: one row per (file, post), written with the attachment&#39;s nid when the file is copied in and given its post when the post is published; a row still without a post after two days is cleared</p>\n<h2 id=\"social-file-comment\">social_file_comment</h2>\n<p>Which comment on a file stands for which reply: one row per (reply, file), marked <code>outbound</code> when the comment was written in Files and went out as the reply</p>\n<h2 id=\"social-quote-grant\">social_quote_grant</h2>\n<p>The permissions this instance has given out to quote its posts: one row per (quoted post, quoting post), with the <code>QuoteRequest</code> it answered so the grant can be taken back</p>\n<h2 id=\"social-team\">social_team</h2>\n<p>The accounts a Nextcloud group posts from: one row per team account, bound to the group whose members may speak as it</p>\n<h2 id=\"social-team-post\">social_team_post</h2>\n<p>Who actually wrote each post from a team account: one row per post, shown to the team and to moderators</p>\n<h2 id=\"social-portfolio\">social_portfolio</h2>\n<p>One page of work per account: whether it is published, what it says, how it is laid out and which pictures it shows</p>\n<h2 id=\"social-media-tag\">social_media_tag</h2>\n<p>Who is named in a post&#39;s pictures: one row per (post, account), deleted with the post</p>\n<h2 id=\"social-story-react\">social_story_react</h2>\n<p>What was said back to a story: one row per reaction or reply, deleted with the story it answers</p>\n<h2 id=\"social-stream-view\">social_stream_view</h2>\n<p>Who has opened a post&#39;s own page: one row per (post, viewer), unique on the pair, so the number the author sees is people rather than visits</p>\n<h2 id=\"social-stream-act\">social_stream_act</h2>\n<p>Per-viewer stream flags (<code>liked</code>, <code>boosted</code>, <code>replied</code>, <code>bookmarked</code>, <code>values</code>) and when the like and the bookmark were set (<code>liked_nid</code>, <code>bookmarked_nid</code>: an id on the post nid&#39;s scale, zero while the mark is not set), which the favourites and bookmarks lists are ordered and paged by</p>\n<h2 id=\"social-stream-dest\">social_stream_dest</h2>\n<p>Stream visibility targets (who sees what)</p>\n<h2 id=\"social-stream-queue\">social_stream_queue</h2>\n<p>Inbound stream processing queue</p>\n<h2 id=\"social-stream-tag\">social_stream_tag</h2>\n<p>Stream-to-hashtag mapping: one row per (post, tag), the tag in the form <code>FollowedTagsRequest::normalise()</code> gives it, so every reader compares it as it stands</p>\n<h2 id=\"social-search-term\">social_search_term</h2>\n<p>The content search&#39;s word index: one row per (word, post) except the function words in <code>SearchTerms::STOP_WORDS</code>, the word as <code>SearchTerms</code> normalises it, unique on (term, nid) — the index every search reads newest-first — indexed on (head, nid) for a search that ends in a word beginning, and on <code>stream_id_prim</code> for the edit and the delete</p>\n<h2 id=\"social-starter-pack\">social_starter_pack</h2>\n<p>The collections other servers publish (FEP-7aa9, Mastodon&#39;s Collections), read in by <code>CollectionPackService</code> and offered as starter packs: one row per collection, unique on the md5 of its id (<code>uri_prim</code>) and on its <code>slug</code>, with the curator (<code>curator</code>, <code>curator_acct</code>), <code>name</code>, <code>summary</code>, <code>topic</code>, <code>language</code>, <code>url</code>, <code>members</code> (the JSON list of the actor ids whose <code>featureAuthorization</code> held, in the curator&#39;s order), <code>member_count</code> (how many, so the index of packs reads no member list; added and counted from <code>members</code> by <code>Version1000Date20261016000030</code>) and when it was read (<code>fetched</code>). A row read again keeps the slug it was first stored with</p>\n<h2 id=\"social-stream-media\">social_stream_media</h2>\n<p>Which cached documents each of this instance&#39;s own posts carries: one row per (document nid, post <code>stream_id_prim</code>), the pair the primary key, with the post indexed on its own. Written when a local post is stored, and rewritten by an edit or by a stored-copy rewrite that swaps a document; a remote post is not linked when it is stored. A finished transcode finds the posts to rewrite here rather than by <code>LIKE</code> on <code>attachments</code>, and the post&#39;s rows go with it in <code>deleteRelatedTo()</code></p>\n<h2 id=\"social-actor-relation\">social_actor_relation</h2>\n<p>Blocks and mutes: one row per (local actor, target actor, <code>block</code>/<code>mute</code>/<code>blocked_by</code>). A <code>blocked_by</code> row written from an incoming <code>Block</code> keeps the md5 of the block&#39;s id in <code>activity_id_prim</code> (indexed; added by <code>Version1000Date20261016100300</code>), so an <code>Undo</code> that names the block by its id alone finds it</p>\n<h2 id=\"social-report\">social_report</h2>\n<p>Moderation reports, local and federated <code>Flag</code> activities, with a <code>resolved</code> flag</p>\n<h2 id=\"social-media-block\">social_media_block</h2>\n<p>Pictures this instance refuses by sha256 of the file, with the reason, who decided it, and how many times it has since been turned away</p>\n<h2 id=\"social-moderation\">social_moderation</h2>\n<p>The decision taken about an account: one row per silenced or suspended actor (<code>level</code>), and <code>force_sensitive</code> — every post by this account marked sensitive</p>\n<h2 id=\"social-strike\">social_strike</h2>\n<p>Every decision ever taken about an account, including the warnings that took none: <code>action</code>, <code>text</code>, who took it and which report it came from</p>\n<h2 id=\"social-client-auth\">social_client_auth</h2>\n<p>One authorization per (app, account): the code, the redirect URI it was sent to, the token, the scopes granted and the account they were granted to. Unique on (client, account)</p>\n<h2 id=\"social-access-block\">social_access_block</h2>\n<p>The blocks that are about an address rather than an account: an IP range this instance answers nothing from, and an email domain it gives no fediverse account to</p>\n<h2 id=\"social-announce-react\">social_announce_react</h2>\n<p>The emoji accounts have put on an announcement, unique on (announcement, account, emoji)</p>\n<h2 id=\"social-emoji\">social_emoji</h2>\n<p>The custom emoji this instance publishes: <code>shortcode</code> (unique), the appdata file behind it, its media type, its picker category and whether a picker offers it</p>\n<h2 id=\"social-stream-card\">social_stream_card</h2>\n<p>The link-preview card of a status (url, title, description, image, provider), one row per stream</p>\n<h2 id=\"social-reaction\">social_reaction</h2>\n<p>Who reacted to which post with which emoji; unique on (actor, post, emoji), so a redelivered <code>EmojiReact</code> is refused rather than counted twice</p>\n<h2 id=\"social-gif\">social_gif</h2>\n<p>The instance&#39;s shared picture library the composer offers, unique on the slug; the bytes live in appdata beside the custom emoji</p>\n<h2 id=\"social-followed-tag\">social_followed_tag</h2>\n<p>The hashtags an account follows: one row per (actor, lowercased tag), unique on the pair; <code>filled</code> is when the tag&#39;s posts were last read from beyond this server (<code>FollowedTagsFill</code>, Unix time, 0 for never), indexed with the tag (<code>Version1000Date20261009000710</code>)</p>\n<h2 id=\"social-interest\">social_interest</h2>\n<p>For you: one row per (reader, lowercased tag), unique on the pair — the score reading earned it, when (<code>scored_at</code>, unix time, so decay is worked out on read), whether the reader added it (<code>manual</code>), the rank they pinned it to (<code>position</code>, null to float) and the score as the current week began (<code>score_week</code>, for the trend arrow)</p>\n<h2 id=\"social-interest-hide\">social_interest_hide</h2>\n<p>The posts a reader said &quot;less like this&quot; about, by <code>stream_nid</code>, unique on (reader, post); forgotten once older than the feed looks back</p>\n<h2 id=\"social-rec-signal-social-rec-event-social-rec-seen\">social_rec_signal, social_rec_event, social_rec_seen</h2>\n<p>For You behavioural learning: owner-scoped fast/slow affinity aggregates (bounded to 300 topics, 400 authors and 20 formats; entries untouched for 180 days can be evicted at capacity), a seven-day event-idempotency ledger, and bounded hashed post/session exposure counts. Learning defaults off; consent generations reject late events.</p>\n<h2 id=\"social-rec-epoch\">social_rec_epoch</h2>\n<p>One instance-wide epoch used with each reader&#39;s local generation to invalidate stale learning events and cursors when an administrator changes the learning switch, without rewriting every reader&#39;s profile row.</p>\n<h2 id=\"social-rec-discovery\">social_rec_discovery</h2>\n<p>Instance-wide hourly ActivityPub/ATProto discovery counters, last attempt/success and batch duration; seven-day retention, with no query terms, topic labels, reader IDs or post IDs.</p>\n<h2 id=\"social-collection\">social_collection</h2>\n<p>Collections: an album an account curates out of its own posts, with its title, description and visibility</p>\n<h2 id=\"social-collection-item\">social_collection_item</h2>\n<p>What is in a collection: one row per (collection, post), unique on the pair, ordered by <code>position</code></p>\n<h2 id=\"social-place\">social_place</h2>\n<p>Places: one row per distinct place this instance has seen, deduplicated on (name, country). No geocoder — see the migration</p>\n<h2 id=\"social-import-post\">social_import_post</h2>\n<p>What an account has brought over from another server: one row per (account, original id), unique on the pair, naming the local post it became</p>\n<h2 id=\"social-import\">social_import</h2>\n<p>The imports an account asked for — a kept upload or a server to pull from — with where the run got to and what it came to; <code>Cron\\RunImport</code> works a row off and the Migration page polls it</p>\n<h2 id=\"social-atproto-identity\">social_atproto_identity</h2>\n<p>One row per local account that is also a Bluesky account: its <code>did:plc</code>, its handle (<code>alice.&lt;host&gt;</code>, stored, never recomputed), a custom handle on the person&#39;s own domain when they set one (<code>custom_handle</code>, with when it was last checked and how many checks in a row failed), its signing key sealed with the instance secret, the public halves, and its state (<code>active</code>, <code>deactivated</code> — switched off by its owner, <code>moved_away</code>, <code>tombstoned</code>)</p>\n<h2 id=\"social-atproto-instance-key\">social_atproto_instance_key</h2>\n<p>The instance&#39;s own keys: the rotation key listed first on every account&#39;s DID and the service key its <code>did:web</code> names, sealed; a rotated rotation key stays, retired, for the PLC&#39;s 72-hour window</p>\n<h2 id=\"social-atproto-repo\">social_atproto_repo</h2>\n<p>Each repository&#39;s signed head: the commit CID and revision, the record count and the blob bytes — written last in a commit, so a failure half-way leaves the previous commit as the repository</p>\n<h2 id=\"social-atproto-record\">social_atproto_record</h2>\n<p>The live records of every repository with their DAG-CBOR bytes, the collection and rkey (unique by the hash of the path), and the Social object each came from (<code>local_id</code>), so a post maps to its record and back in one lookup</p>\n<h2 id=\"social-atproto-block\">social_atproto_block</h2>\n<p>The Merkle search tree nodes and the commits, by CID: what <code>getRepo</code> and the firehose serve. Records are not duplicated here; they are read from their own table</p>\n<h2 id=\"social-atproto-blob\">social_atproto_blob</h2>\n<p>The pictures a repository refers to: a CID naming one of the app&#39;s stored documents, its type and size</p>\n<h2 id=\"social-atproto-event\">social_atproto_event</h2>\n<p>The firehose, one frame per commit, identity or account change or <code>#sync</code>, numbered by the database (<code>seq</code>) and kept for the 72-hour replay window; <code>occ social:atproto:serve</code> reads it</p>\n<h2 id=\"social-atproto-plc-log\">social_atproto_plc_log</h2>\n<p>Every PLC directory operation this instance made, logged before it is sent and marked when the directory took it, so <code>occ social:atproto:plc --repair</code> can resend what never got through</p>\n<h2 id=\"social-atproto-watch\">social_atproto_watch</h2>\n<p>One row per Bluesky author somebody here follows: the author-feed cursor the poller continues from, when it last read and when it is due again (<code>next_sync</code>, backed off after empty pages), failures and the last error</p>\n<h2 id=\"social-atproto-notify-cursor\">social_atproto_notify_cursor</h2>\n<p>The same bookkeeping per local account with a Bluesky identity, for the AppView&#39;s notifications of follows, likes, reposts, replies, mentions and quotes of its records</p>\n<h2 id=\"social-atproto-chat-cursor\">social_atproto_chat_cursor</h2>\n<p>The same bookkeeping per local account with a Bluesky identity, for its direct messages on Bluesky&#39;s chat service (<code>ChatPoller</code>): the chat log&#39;s <code>rev</code> read up to</p>\n<h2 id=\"social-atproto-blocklist\">social_atproto_blocklist</h2>\n<p>The administrator&#39;s Bluesky block list: a PDS host or a DID, with the reason. A blocked account is not resolved, read or heard from; a blocked host blocks every account whose PDS it is</p>\n<h2 id=\"social-atproto-labeler\">social_atproto_labeler</h2>\n<p>The Bluesky labelers each person subscribes to, by DID, with their choice per label value (<code>ignore</code>, <code>warn</code>, <code>hide</code>) as JSON; Bluesky&#39;s own moderation service is always applied and needs no row</p>\n<h2 id=\"social-atproto-app-password\">social_atproto_app_password</h2>\n<p>The app passwords a person made for Bluesky apps, by name, stored as password hashes only — the password is shown once — and whether each is <code>privileged</code>, which lets an app signed in with it reach the Bluesky direct messages. Good for this app&#39;s Bluesky surface and nothing else of Nextcloud</p>\n<h2 id=\"social-atproto-session\">social_atproto_session</h2>\n<p>The sessions Bluesky apps opened with those passwords, by the id of their refresh token, with the password that opened them: refresh consumes the row atomically, and access checks that the password still exists, so ending a session or revoking its password ends its tokens</p>\n<h2 id=\"social-atproto-video\">social_atproto_video</h2>\n<p>A local post&#39;s video on its way through Bluesky&#39;s video service: the post and its video document, the state (<code>queued</code>, <code>processing</code>, <code>done</code>, <code>failed</code>), the service&#39;s job, the blob it stored here, the tries and the reason it failed. The post goes to Bluesky once the row has ended — naming the blob, or as a link — and ended rows are pruned after a week</p>\n<h2 id=\"social-atproto-oauth-request\">social_atproto_oauth_request</h2>\n<p>Bluesky sign-in (OAuth) requests a Bluesky app pushed: the app&#39;s <code>client_id</code>, how it authenticated, what it asked for, the DPoP key it asked with and its PKCE challenge; once the person agreed, who agreed and the hash of the code handed out, and once that code was exchanged, the session it started — so a second exchange ends that session. Kept a day past expiry, so a PKCE challenge is not taken twice</p>\n<h2 id=\"social-atproto-oauth-session\">social_atproto_oauth_session</h2>\n<p>The Bluesky apps signed in through OAuth: account, app, granted scopes, the DPoP key every token is bound to, the hash of the one refresh token that is good and of the one it replaced (presenting that one ends the session), and when it ends — two weeks for a public app, never for a confidential one</p>\n<h2 id=\"social-atproto-oauth-replay\">social_atproto_oauth_replay</h2>\n<p>One-time values that may not be used twice — DPoP proof ids, client assertion ids — by hash, until they could no longer be fresh</p>\n<h2 id=\"social-atproto-move\">social_atproto_move</h2>\n<p>Moves of a Bluesky account between this server and another PDS, either way (<code>direction</code> <code>away</code> or <code>in</code>): the other PDS, the handle there, the step reached (<code>repo</code>, <code>blobs</code>, <code>prefs</code>, <code>follows</code>, <code>code</code>, <code>identity</code>, <code>activate</code>, <code>done</code>), how it ended or that it waits for the person&#39;s e-mailed code, and why it stopped; while it runs, the session on the other PDS — and, moving here, the signing key made for the account and the code — sealed with the instance secret, all dropped once the move is done</p>\n<h2 id=\"social-verification\">social_verification</h2>\n<p>The accounts this instance verified (<code>VerificationService</code>), one row per account, unique on the hash of its id: the moderator who verified it and when, and the DID, handle and display name its published verification record names — the DID <code>&#39;&#39;</code> for an account that has none, verified here only</p>\n<h2 id=\"social-post-hold\">social_post_hold</h2>\n<p>The posts waiting for a moderator: the client&#39;s request, the rule that held it, and the digest the queue is unique on</p>\n<h2 id=\"social-story\">social_story</h2>\n<p>Stories — the web client&#39;s 24-hour shorts: one picture, video or text card that expires after a day, with its caption, hold time, <code>expires_at</code>, the ActivityPub id it travels under (<code>source_id</code>/<code>source_id_prim</code>) and whether this instance wrote it (<code>local</code>)</p>\n<h2 id=\"social-story-view\">social_story_view</h2>\n<p>Who has seen a story: one row per (story, viewer), unique on the pair</p>\n<h2 id=\"social-list\">social_list</h2>\n<p>Mastodon lists: one row per (owner, list), with its title, <code>replies_policy</code> and <code>exclusive</code> flag — <code>group_id</code>, the Nextcloud group a list follows, <code>&#39;&#39;</code> for one made by hand, and <code>visibility</code>, <code>private</code> (the default) or <code>public</code>, a list its owner made public and that is a Bluesky list too (see <strong>Lists, here and on Bluesky</strong>)</p>\n<h2 id=\"social-list-member\">social_list_member</h2>\n<p>Who is in a list: one row per (list, account), unique on the pair</p>\n<h2 id=\"social-filter\">social_filter</h2>\n<p>Keyword filters: one row per (account, filter) with its contexts, action and expiry</p>\n<h2 id=\"social-filter-kw\">social_filter_kw</h2>\n<p>The keywords of a filter: one row per keyword, with its <code>whole_word</code> flag</p>\n<h2 id=\"social-filter-st\">social_filter_st</h2>\n<p>The posts a filter covers by name: one row per (filter, post)</p>\n<h2 id=\"social-convo-state\">social_convo_state</h2>\n<p>What one account has done with one conversation: how far it has read and dismissed the thread, both as a message nid, and whether it has muted it, one row per (account, thread root). The mute is read in three places: <code>StreamRequestBuilder::markMutedConversations()</code> sets each status&#39;s <code>muted</code> for the viewer, a page at a time (reply chains walked to their roots, compared with the viewer&#39;s muted roots — memoised per request, the memo dropped first thing in <code>ConversationsRequest::setMuted()</code>); the notification queries leave a muted thread&#39;s notifications out of the list, the unread count and the digest (<code>filterMutedConversations()</code>); and <code>NotificationService::emit()</code> raises nothing for one (<code>rootOf()</code> against <code>getMutedRoots()</code>, the walk made only for a recipient who muted something)</p>\n<h2 id=\"social-domain-block\">social_domain_block</h2>\n<p>Instances one account has blocked for itself: one row per (account, domain), unique on the pair</p>\n<h2 id=\"social-account-note\">social_account_note</h2>\n<p>The private note one account keeps about another: one row per pair, never federated</p>\n<h2 id=\"social-mute-expiry\">social_mute_expiry</h2>\n<p>When a mute runs out: one row per (muter, muted), and only for a mute that was given a duration</p>\n<h2 id=\"social-stream-rev\">social_stream_rev</h2>\n<p>The versions a status has been through: one row per version including the original, oldest first. <code>media</code> (TEXT, nullable) is the attachments of that version as a JSON list of client <code>MediaAttachment</code> entities, the shape <code>social_stream.attachments</code> stores — kept on the revision because <code>media_attributes</code> rewrites a description or focal point on the attachment itself; null on rows from before the column, which read as no attachments</p>\n<h2 id=\"social-stream-del\">social_stream_del</h2>\n<p>A bounded cursor of public and direct-message deletions: status id, visibility, and for direct messages the original recipient actor hashes; public stream filters are kept only for public statuses, and clients receive ids only</p>\n<h2 id=\"social-featured-tag\">social_featured_tag</h2>\n<p>The hashtags an account pins to its profile: one row per (actor, lowercased tag), unique on the pair</p>\n<h2 id=\"social-announcement\">social_announcement</h2>\n<p>The instance&#39;s announcements: one row per notice, with the text as typed and the window it is served in (both bounds nullable)</p>\n<h2 id=\"social-announce-read\">social_announce_read</h2>\n<p>Who has dismissed which announcement: one row per (account, announcement), unique on the pair</p>\n<h2 id=\"social-scheduled\">social_scheduled</h2>\n<p>Posts asked to be published later: one row per waiting post, with the client&#39;s request as JSON in <code>params</code> and the resolved visibility inside it</p>\n<h2 id=\"social-durable-cache\">social_durable_cache</h2>\n<p><code>DurableCache</code>&#39;s entries on an instance with no memcache: a hashed key, a JSON value and the unix time it expires at, indexed on that for the purge in <code>Cron\\Cache</code>. Wherever a memcache is configured, only what <code>setShared()</code> writes for a background job and a web request to share — such as the Jetstream listener&#39;s cursor and report (<code>JetstreamState</code>)</p>\n<h2 id=\"social-ext-user\">social_ext_user</h2>\n<p>The logins of self-registered external users: the Nextcloud user id, which is also their handle, its lowercase form (unique), the password hash, the display name and how the account came to be (<code>origin</code>). Everything else about the person is where Nextcloud keeps it for any user</p>\n<h2 id=\"social-ext-signup\">social_ext_signup</h2>\n<p>Registrations of external users that are not accounts yet: the handle and email they reserve, the password hash, the SHA-256 of the confirmation token, whether the email is confirmed (<code>verified</code>) and whether an administrator has to decide (<code>approval</code>), the invitation used and a salted hash of the address it came from</p>\n<h2 id=\"social-ext-invite\">social_ext_invite</h2>\n<p>Invitation links for external users: the token as it is sent, who made it, how many registrations it admits (<code>max_uses</code>, 0 for any number), how many it has (<code>uses</code>) and when it expires (<code>expires</code>, unix seconds, 0 for never)</p>\n<p><code>Version1000Date20260927000010</code> adds the three tables of self-registered external users, <code>social_ext_user</code>, <code>social_ext_signup</code> and <code>social_ext_invite</code> — see <a href=\"/docs/architecture-external-users#external-users\">External users</a>.</p>\n<h2 id=\"sessionservice-create\">SessionService::create()</h2>\n<p> resolves a Bluesky login by handle or DID directly. A\nNextcloud email identifier may match several local accounts, so each matching\naccount is checked against its own Bluesky identity and app-password hashes;\nan account without an identity does not prevent a later match from signing in.</p>\n<h2 id=\"version1000date20260611000001\">Version1000Date20260611000001</h2>\n<p> only drops the abandoned <code>social_3_*</code> tables from an earlier prototype. <code>Version1000Date20260907000001</code> adds the timeline indexes and the missing primary keys, <code>Version1000Date20260907000002</code> adds <code>social_actor_relation</code>, <code>Version1000Date20260907000003</code> adds the <code>bookmarked</code> flag to <code>social_stream_act</code>, <code>Version1000Date20260908000001</code> widens <code>social_client.app_client_secret</code> for its hashed value, <code>Version1000Date20260908000002</code> adds the <code>locked</code> flag to <code>social_actor</code>, <code>Version1000Date20260908000003</code> adds <code>social_report</code> (moderation reports), <code>Version1000Date20260908000004</code> adds the <code>fields</code> column to <code>social_actor</code> (the profile metadata fields), <code>Version1000Date20260908000005</code> adds <code>social_stream_card</code> (link previews), <code>Version1000Date20260909000001</code> adds <code>social_moderation</code> (the silence/suspend decisions, indexed on <code>level</code>), <code>Version1000Date20260910000001</code> adds the indexes the hot paths were querying as if they existed (<code>social_cache_doc.id_prim</code> and <code>parent_id_prim</code>, <code>social_stream_act</code> by (actor, flag), <code>social_stream_tag</code> by tag, <code>social_action</code> by (object, type), both queues by <code>status</code>/<code>id</code>, <code>social_client.token</code>, <code>social_stream.creation</code>, <code>social_cache_actor</code> by (local, details_update) and <code>social_follow</code> by (object, actor)) and drops the redundant five-column <code>ipoha</code> unique index on <code>social_stream</code>, <code>Version1000Date20260910000002</code> adds the sortable <code>trend_*</code> counter columns to <code>social_hashtag</code> zeroed (the JSON <code>trend</code> column stays and remains what the API hands back), <code>Version1000Date20260910000003</code> fills those columns in from the JSON, <code>Version1000Date20260911000001</code> adds the <code>sensitive</code> flag to <code>social_stream</code>, and <code>Version1000Date20260911000004</code> adds <code>social_followed_tag</code> (the hashtags an account follows, unique on (actor, tag) — which is also the index the home timeline reads). <code>Version1000Date20260911000005</code> adds <code>social_list</code> and <code>social_list_member</code> — Mastodon&#39;s lists and their membership, the membership table unique on (list, account), which is both what makes adding an account twice a no-op and the index the list timeline joins <code>social_stream.attributed_to_prim</code> on. <code>Version1000Date20260911000006</code> adds <code>social_filter</code> and <code>social_filter_kw</code> — the keyword filters an account mutes posts with, indexed by owner and by filter, which are the two reads there are. <code>Version1000Date20260911000007</code> adds <code>social_convo_state</code>, unique on (account, thread root) — the read and dismissed markers behind <code>/api/v1/conversations</code>. The conversations themselves get no table: a conversation is a thread of <code>social_stream</code> rows derived from <code>in_reply_to</code> at read time, and its id is the nid of the thread root. <code>Version1000Date20260911000008</code> adds <code>social_domain_block</code>, <code>social_account_note</code> and <code>social_mute_expiry</code> — the per-account instance blocks, the private notes and the expiry of a timed mute, each unique on the pair it is keyed by, which is both what makes writing one twice a no-op and the index its read path probes. An endorsement is not among them: it is a row in <code>social_actor_relation</code> with type <code>endorse</code>, which is what that table already holds. <code>Version1000Date20260911000009</code> adds <code>social_stream_rev</code> (the revisions of an edited status, indexed on (status, id), which is the only read there is) and <code>Version1000Date20260911000010</code> adds <code>social_featured_tag</code> (the hashtags an account pins to its profile, unique on (actor, tag)). <code>Version1000Date20260911000011</code> adds <code>social_announcement</code> and <code>social_announce_read</code> — the announcements and their dismissals, the dismissal table unique on (account, announcement), which is both what makes dismissing twice a no-op and the index the client read probes. The announcements table gets no index beyond its key: every read of it is its whole active set, and it holds a handful of rows. <code>Version1000Date20260911000014</code> adds <code>social_scheduled</code> — the posts a client asked to have published later — with two indexes, one per read there is: <code>(actor_id_prim, scheduled_at)</code> for one account&#39;s list and the daily cap, and <code>(scheduled_at)</code> for the cron&#39;s &quot;what is due across every account&quot;, which the first index cannot answer because its leading column is the account. <code>Version1000Date20260911000020</code> adds <code>forwarded</code> to <code>social_report</code>: whether a report was passed on to the instance that hosts the reported account, which the admin API used to answer as a hardcoded <code>false</code>. <code>Version1000Date20260912000001</code> adds the two indexes <code>Version1000Date20260910000001</code> left out: <code>social_actor.user_id</code>, which resolves the logged-in user&#39;s actor on every authenticated request and had no index at all, and the four trend windows of <code>social_hashtag</code> other than <code>trend_1d</code> (<code>trend_1h</code>, <code>trend_12h</code>, <code>trend_3d</code>, <code>trend_10d</code>), each of which <code>getTrending()</code> filters and orders on. <code>Version1000Date20260912000002</code> adds <code>social_actor.bot</code> — whether a local account is automated, which is what Mastodon&#39;s <code>bot</code> reports and what decides whether the actor document says <code>Service</code> or <code>Person</code>; it was accepted from clients and dropped. <code>Version1000Date20260912000003</code> adds <code>social_strike</code> — the history of moderation decisions, indexed on the account, which is the only read there is. <code>Version1000Date20260912000011</code> adds <code>social_convo_state.muted</code> — the thread an account has stopped hearing from, a column rather than a table because that row already records what one account has done with one thread. <code>Version1000Date20260912000010</code> adds <code>social_client_auth</code>, unique on (client, account) with an index on each of the two secrets it is looked up by — and carries the authorization already on each client row across, so a token in use today goes on working. <code>Version1000Date20260912000006</code> adds <code>social_access_block</code>, unique on (type, value) — one table for two lists, because what differs between Mastodon&#39;s two is a severity column and a count, and neither is worth a second table on an instance that holds tens of these rows. <code>Version1000Date20260912000005</code> adds <code>social_announce_react</code>, unique on (announcement, account, emoji) — both what makes reacting twice with the same emoji a no-op and the index its two reads use. <code>Version1000Date20260912000004</code> adds <code>social_emoji</code>, unique on the shortcode — which is both what makes re-adding one a replacement rather than a second row nothing can tell from the first, and the index every read of it uses. <code>Version1000Date20260912000008</code> adds <code>social_collection</code> and <code>social_collection_item</code> — the albums an account curates out of its own posts, the item table unique on (collection, post) so adding one twice is a no-op, with a second index on the post because deleting one has to find every collection holding it. <code>Version1000Date20260912000009</code> adds <code>social_story</code> and <code>social_story_view</code> — a picture that expires after a day and who has seen it, indexed on (account, expiry) for the reads and on expiry alone for the cron that sweeps them, the view table unique on (story, viewer). <code>Version1000Date20260912000012</code> adds <code>social_place</code> and <code>social_stream.place_id</code> — where a post was taken, deduplicated on (name, country) with the name hashed because a unique index on a TEXT column is not portable; no geocoder is involved anywhere, see the migration. <code>Version1000Date20260914000002</code> adds <code>social_list.group_id</code>, indexed — the Nextcloud group a list follows, which is what <code>GroupListService</code> reads when a group changes: every list bound to it, whoever owns it. <code>Version1000Date20260914000001</code> adds <code>social_req_queue.object_id_prim</code>, indexed — the md5 of the id of the object a queued delivery is about, which is what lets a post ask the queue where it got to; empty on rows queued before the column existed, which are at most a few days of retries. <code>Version1000Date20260914000005</code> adds <code>social_gif</code> — the shared pictures the composer offers, unique on the slug, with the bytes in appdata beside the custom emoji: it is the same shape of thing, a small curated set served to everybody that must not break because a file moved in somebody&#39;s Files. <code>Version1000Date20260914000004</code> adds <code>social_reaction</code> — who reacted to which post with which emoji — unique on (actor, post, emoji) and indexed on the post, which is the read it exists for. A table of its own rather than another <code>type</code> in <code>social_action</code>: a like and a boost are a fact about a pair, which is what that table&#39;s key says, while a reaction carries a third thing and one account may react to one post several times over. <code>Version1000Date20260915000001</code> adds <code>social_filter_st</code> — the individual posts a filter covers, beside the keywords it matches, which is the other half of Mastodon&#39;s v2 filters and the only part of that API this app did not serve. The post is named by its <code>nid</code>, the id a client sends, with an index on the filter (how a filter&#39;s entries are read and deleted) and one on the status (not unique: two filters of one account, and two accounts, may each cover the same post). <code>Version1000Date20260915000002</code> adds <code>social_import_post</code> — what an account has brought over from an export, unique on (account, original id). A post written by the importer is a <em>new local post</em>: its original id belongs to the server it was written on and cannot be kept, so without this row nothing would remember where it came from, a second run of the same archive would write every post again, and a reply — which an archive names by its parent&#39;s original id — would have nothing to hang off. Nothing cascades: a post the account later deletes leaves its row, because the row says &quot;this was imported&quot; and importing it again because it was deleted here would undo a decision the account made. <code>Version1000Date20260915000003</code> adds <code>source_id</code>, <code>source_id_prim</code> and <code>local</code> to <code>social_story</code>, unique on the hashed id. A story used to be local by definition — no ActivityPub identity, no recipients — so the row had no way of saying whose network it belonged to; it is published to followers as an <code>Add</code> now and arrives from peers the same way. The unique index is what makes a story delivered twice one row, which matters more here than elsewhere because a fan-out reaches an instance once per follower on it, and <code>local</code> is what decides which stories are published outward and which may be deleted through the API. Existing rows are local and have their id minted on first read rather than in a <code>postSchemaChange</code>: a story lives a day, so within a day of the migration the question has answered itself. <code>Version1000Date20260915000004</code> adds <code>social_post_hold</code> — the review queue. What it stores is the <em>request</em>, the same shape <code>social_scheduled</code> holds, and not a post: a held post that existed as a row in <code>social_stream</code> with a flag on it would be one forgotten predicate away from a timeline, a hashtag page, a profile or an outbox, and this app has shipped exactly that leak before. A post that is not in the table cannot be read out of it by code nobody has written yet. Unique on <code>digest</code>, the md5 of the account and the text: a client told its post was held will be pressed again by its user and the Pixelfed app retries a 422 by itself, so without it one post held once would be twenty identical rows for a moderator to work through. Indexed on (<code>actor_id_prim</code>, <code>id</code>) for the author&#39;s own list and the per-account cap; the queue itself is read in <code>id</code> order off the primary key, because it is drained by people. <code>Version1000Date20260915000005</code> adds <code>social_stream.archived</code> — a post its author has put away. Deleting was the only thing this app offered somebody who no longer wanted a post on their profile, which is a bad answer to a common question: a photograph from four years ago is not something to destroy because it has stopped belonging at the top of a profile. A column rather than a table because it is one fact about one post and every read that must not show one is a read of <code>social_stream</code>; no index, because almost every row is <code>false</code> and always will be, and the queries that filter it are already selected by their own timeline&#39;s index. The filter is <strong>fail-closed</strong>: <code>StreamRequestBuilder::hideArchived()</code> is applied by the two base selects every stream read is built from, and the two reads that should see an archived post — the author&#39;s own list, and a post fetched by its own address — ask for it. A read written later shows none until somebody decides it should, rather than leaking one until somebody notices. Nothing federates: an archived post is still on every server that received it, and taking it back from them is what <code>Delete</code> is for. <code>Version1000Date20260915000006</code> adds <code>social_moderation.force_sensitive</code> and <code>social_media_block</code>. The first is the step between doing nothing and silencing — an account asked to put a content warning on its pictures without being taken out of the timelines, which is Mastodon&#39;s own tier and what Pixelfed calls <code>cw</code> — applied in <code>StreamRequest::save()</code> because a local post, a post that arrived in the inbox and a post the importer restored are the same row and a rule that held for one of them would be a rule nobody could explain. The second is the one thing none of the account-level tools does: stop a <strong>file</strong> coming back. A hash of the bytes as they arrive, checked in <code>CacheDocumentService::saveFromTempToCache()</code> — the one place an upload and a fetched remote attachment both pass through — with the reason and the moderator beside it, and a count of how many times it has been turned away, because a blocklist with no evidence is one nobody dares remove anything from a year later. <code>Version1000Date20260915000007</code> adds <code>social_stream_view</code> — who has opened a post. An author could see three likes and had no way to know whether that was three out of five or three out of four hundred; a story has had a view count since it was written and a post had none. What is counted is deliberately narrow: <strong>a post&#39;s own page, opened by a signed-in account that is not its author</strong>. Not an impression in a timeline — a post scrolled past has not been read, counting it would make the number meaningless, and it would write a row for every post on every page of every timeline. Unique on (post, viewer), so the number is people rather than visits. It is never federated and is on the author&#39;s copy alone: a count that arrived from another server would be a number about that server&#39;s readers added to this one&#39;s, meaning neither. <code>Version1000Date20260916000001</code> adds <code>social_trend_review</code> — what a moderator has decided about something that is trending. Trending is counted and shown with nobody in the loop, so the first ugly hashtag to catch on did so on the Explore page of every account here and the only remedy was to wait for it to fall off; Mastodon has nine admin routes for this and the app had none. <strong>Rejected is what is stored, and everything else trends.</strong> The other arrangement Mastodon offers — nothing trends until it is approved — would empty the Explore page of every instance on upgrade and leave it empty until somebody found the new panel; approval is still recorded, because a moderator wants to see what they have already looked at, but it grants nothing that was not already so. One table for the three kinds rather than three: what differs is a word (a tag is named by its text, a link by its URL, a status by its id) and splitting them would be three identical schemas, three queries to keep in step and three things each trend read would have to know about. The filter is applied where a trend list is <strong>read</strong>, never where the counters are written — a rejected tag keeps being counted, so lifting the decision puts it back with the number it would have had, and a decision that could only be undone by waiting for counters to refill is one nobody would risk making. <code>Version1000Date20260916000004</code> adds <code>social_channel</code>, <code>social_actor.actor_type</code> and <code>social_cache_doc.size</code> — the three things a <code>Video</code> this app publishes needs before a PeerTube will take it. PeerTube has <strong>no video without a channel</strong>: its builder resolves one by looking for a <code>Group</code> in the video&#39;s <code>attributedTo</code> and throws <em>&quot;Cannot find associated video channel&quot;</em> when there is none, then fetches that <code>Group</code> and looks for a <code>Person</code> in <em>its</em> <code>attributedTo</code>. A Aloha Social account is a <code>Person</code> and nothing else, so every <code>Video</code> published from here was refused on arrival — silently, and in PeerTube&#39;s log rather than in ours. A channel is <strong>an actor like any other</strong> — key pair, inbox, outbox, followers, followable, moderatable — which is the same design <code>social_team</code> uses and the reason neither needed the actor machinery written twice; what is new is the type it is served as and who owns it. It is stored under a reserved <code>channel/&lt;handle&gt;</code> user id, which no Nextcloud user can have because a user id may not contain a slash. The owner is the <strong><code>Person</code> actor</strong>, not the Nextcloud user, so a channel points at the same thing the wire does. One is made for an account the first time it posts a video and used unless the person picks another: nobody should have to learn what a channel is in order to post a video, and an account that never posts one never grows an actor it did not ask for. It is made when the <strong>post is written</strong>, never when it is serialised — a serialisation happens once per instance a post is delivered to, and making an actor there would be a write on a read path, forty times over. <code>actor_type</code> is how it is served as a <code>Group</code>. A local actor&#39;s type was derived from one flag (<code>bot</code>, which moves it between <code>Person</code> and <code>Service</code>) and there was nowhere to say anything else; <code>&#39;&#39;</code> means &quot;decide as before&quot;, which is every row written until now. <code>social_cache_doc.size</code> is how many bytes a stored file is. PeerTube&#39;s <code>isRemoteVideoUrlValid()</code> wants <code>size</code> as an integer on every video file link and drops a link without one, so a <code>Video</code> from here arrived with nothing to play; it is recorded when the file is stored rather than measured per serialisation, and the per-account video quota asks the same question. <strong>A post that cannot make a valid <code>Video</code> stays a <code>Note</code></strong>: no poster (<code>icon</code> is mandatory), no duration, or no channel, and the post is published in the shape Mastodon and Pixelfed both read. Sending a <code>Video</code> that is going to be thrown away is strictly worse than sending the one that works. <code>Version1000Date20261004000002</code> adds <code>social_import</code> — the imports an account asked for, run in the background. Every import used to run inside the request that uploaded the file: each follow is a WebFinger lookup, an actor fetch and a delivery, so a few hundred of them ran into the web server&#39;s timeout, and the rate limit that protected the server from that meant a timed-out upload could not be tried again for an hour. A row is one upload (kept in appdata until the run has read it) or one server to pull from, with <code>total</code>/<code>done</code> written as the run goes and the outcome and a <code>report</code> at the end; indexed on (user, id), which is both the page&#39;s read and &quot;is one of this kind already under way&quot;. <code>Version1000Date20261008000400</code> adds <code>social_stream</code> (<code>attributed_to_prim</code>, <code>nid</code>) — a page of one author&#39;s posts filters on the author and pages by nid, and with the author alone indexed the database read and sorted every post that author ever wrote before it could hand over twenty. <code>Version1000Date20261008000401</code> adds <code>social_search_term</code> — the words of each post, so a content search is an indexed equality instead of an <code>ILIKE &#39;%term%&#39;</code> no index can answer — and queues <code>Cron\\SearchIndex</code> to add the posts already stored; the search keeps its bounded scan until that job has reached the newest post. <code>Version1000Date20261013100200</code> adds <code>social_stream_act</code> (<code>liked_nid</code>, <code>bookmarked_nid</code>) — when a like and a bookmark were set, as an id on the post nid&#39;s scale (<code>Nid::now()</code>, the millisecond), so that <code>/api/v1/favourites</code> and <code>/api/v1/bookmarks</code> are ordered and paged on the mark as Mastodon pages them rather than on the post — with an index per list, (<code>actor_id_prim</code>, flag, mark id), which serves the filter and the order as one descending range; the marks already stored are given the id of their post, which keeps them in the order they were listed in until then. <code>Version1000Date20261016100300</code> adds <code>social_actor_relation.activity_id_prim</code>, indexed — the md5 of the id of the <code>Block</code> a <code>blocked_by</code> row came from, which is what an <code>Undo</code> naming the block by its id alone is matched on; rows stored before it have none.</p>\n<h2 id=\"version1000date20260916000003\">Version1000Date20260916000003</h2>\n<p> adds <code>social_stream.quote_policy</code> and <code>social_quote_grant</code> — who may quote a post, and the permissions that have been given out. This app answers a <code>QuoteRequest</code> already (FEP-044f, the mechanism Mastodon 4.5 quotes run on), but the answer was derived from one thing: whether the post was addressed to the public collection. An author who wanted their public post quoted by their followers and nobody else, or by nobody at all, had no way to say so — and Mastodon&#39;s own composer offers exactly that choice on every post. The policy is <code>public</code>, <code>followers</code> or <code>nobody</code>, and <strong>empty for every post written before anybody was asked</strong>, which keeps meaning what it meant: the visibility rule. It lives on the post rather than on the account because it is a decision about <em>this</em> post; a default for new posts is a client preference and belongs with the composer&#39;s other defaults. What it decides is <code>Stream::mayBeQuotedBy()</code>, which is both the rule <code>QuoteRequestInterface</code> applies when a request arrives and the rule <code>quote_approval.current_user</code> reports to a client, so the two cannot drift. It is advertised outward as <code>interactionPolicy.canQuote.automaticApproval</code> — the public collection, the author&#39;s followers collection, or the author alone — which is what Mastodon reads before it offers a quote button at all. A quote of a Bluesky post that its author detaches is noticed by the Bluesky maintenance job (<code>Atproto\\Reader\\DetachedQuoteSweep</code>) and reads as <code>revoked</code>, the same state a fediverse <code>Reject</code> leaves. <code>social_quote_grant</code> is one row per permission given: which post was quoted, which post quotes it, who asked, and <strong>the <code>QuoteRequest</code> the grant answers</strong>. That last column is the reason the table exists — taking a quote back means sending a <code>Reject</code> naming the request that was accepted, and without a row there is nothing to name. Unique on (quoted, quoting), so a request delivered twice (a peer retries) is one row. Changing the policy is deliberately <strong>forward-only</strong>: it does not withdraw permissions already given, because a quote that has been published and read is not undone by a switch being flipped. Taking one back is its own route, which says so and tells the other server.</p>\n<h2 id=\"version1000date20260916000002\">Version1000Date20260916000002</h2>\n<p> adds <code>social_relay</code> — the relays this instance subscribes to. A small instance sees only what the people on it follow, so its federated timeline is empty on the first day and thin for months: there is nobody here yet to have found anybody out there, and nobody out there has heard of this server. A relay breaks that circle by rebroadcasting the public posts of every instance subscribed to it. The row is the <strong>subscription</strong>, not the relay: the <code>Follow</code> this instance sent, the inbox to deliver to, and whether the relay answered — so a relay nobody here subscribed to has no row, and an <code>Announce</code> from a server that merely calls itself one is not treated as a relay&#39;s. <strong>The subscription belongs to the instance</strong>, which is why there is no owner column: the <code>Follow</code> is signed by the instance actor, and what comes back is for everybody&#39;s federated timeline. That also means it cannot go through <code>social_request_queue</code>, which resolves its signing key from <code>social_actor</code> — <code>HttpSignatureService::signAsInstance()</code> signs it and it goes out inline, the same arrangement a forwarded report has. <strong>A relayed <code>Announce</code> is not a boost.</strong> Storing it as one would put &quot;relay.example boosted this&quot; in front of every post and hang it off an actor nobody follows; Mastodon treats it as a pointer and so does this — the post is fetched from the server that wrote it through <code>SearchService::resolveStatus()</code>, with the same guard a reader pasting a link gets, that the document has to claim the address it came from. Outbound, a <strong>local public</strong> activity is delivered to every accepted relay&#39;s inbox beside its followers&#39;: subscribing and sending nothing is taking without giving, and an instance that only reads is invisible to every other instance on the relay. Not local, because forwarding a third party&#39;s activity would put this instance&#39;s name on somebody else&#39;s post and loop where two instances both relay; not public, because a followers-only post has an audience that was chosen and a relay is the opposite of one. Unique on <code>actor_id_prim</code>, so subscribing twice is the same row.</p>\n<h2 id=\"version1000date20260915000013\">Version1000Date20260915000013</h2>\n<p> adds <code>social_team</code> and <code>social_team_post</code> — an account a team posts from. Pixelfed&#39;s answer to &quot;several people, one voice&quot; is its <code>Group*</code> family: twenty models, still beta, and a second social graph beside the one it already has. Nextcloud&#39;s answer is the one it has had all along, a group of people who already work together, and this is that group given an account — the one thing in this comparison Nextcloud can do and Pixelfed cannot, because Pixelfed has no idea who works with whom. A team account is <strong>an actor like any other</strong>: a key pair, a followers collection, an inbox and an outbox, followable from Mastodon and Pixelfed, moderatable and suspendable, none of which needed writing again. It is stored under a reserved <code>team/&lt;group&gt;</code> user id, which no Nextcloud user can have because a user id may not contain a slash, so it never resolves as somebody&#39;s own account on a path that looks one up by user. <strong>No membership is copied</strong>: the Nextcloud group is the membership and it is asked live at the moment somebody tries to post, because a copy of a group is a copy that drifts and the drift is somebody who left the organisation still able to speak for it. <code>social_team_post</code> is about accountability rather than display — outside the team the team speaks with one voice, which is the point of having one, and inside it somebody has to be able to find out which of them wrote the thing everybody is now talking about. A moderator sees it too, because a report about a team account is otherwise a report about nobody. <code>Version1000Date20260915000012</code> adds <code>social_portfolio</code> — a page of somebody&#39;s work, to put on a CV. A profile is a feed: everything somebody posted, newest first, with the follow button and the boosts and the replies around it. A portfolio is the opposite, and it is the feature Pixelfed&#39;s photographers ask for. <strong>One per account</strong>, which the unique index on the account says: a person has one portfolio the way they have one profile, and what would be a second is a collection, which this app already has. <strong>Off until it is turned on</strong> — a row that exists is a draft, <code>active</code> is the moment its owner decides the internet may read it, and a page nobody has activated is a 404 rather than an empty page with their name on it. <strong>Public posts only, always</strong>: the page is readable signed out, so it is built by asking for the account&#39;s posts with <strong>no viewer at all</strong>, and the account query answers an anonymous reader with public posts and nothing else. That rule lives in the query rather than in a switch, because a switch is a thing somebody can get wrong once and leak a followers-only photograph to a search engine for ever. The display switches are Pixelfed&#39;s, minus the two that mean nothing here. <code>Version1000Date20260915000011</code> adds <code>social_cache_doc.transcoded</code> — whether a stored video has been through the transcoder. This app has never re-encoded anything, deliberately, and the cost of that is not theoretical: <strong>Pixelfed&#39;s default <code>media_types</code> accepts <code>video/mp4</code> and nothing else</strong>, so every <code>video/quicktime</code> posted from here, which is every video straight off an iPhone, is dropped by its <code>verifyAttachments()</code> without a word to anybody. A column rather than a queue table, because what has to be remembered is one fact about one stored file and the work to do is a query over the documents themselves: a queue table would have to be filled by every path that stores a video and emptied by every path that deletes one, while a column cannot drift from the row it is on. Four states — nobody has looked, converted, not worth converting, tried and failed — and the last two are what stop the same unconvertible file being read on every run for ever. Existing rows are 0, which is correct for both of the things they might be. No index: the job&#39;s query is narrowed by <code>media_type LIKE &#39;video/%&#39;</code> on a table where a video is a small minority, and it runs once a quarter-hour over one page. <code>Version1000Date20260915000010</code> adds <code>social_media_tag</code> — who is named in a post&#39;s pictures. Pixelfed&#39;s <code>MediaTag</code>, and a staple of every photo network there has been; somebody arriving from Instagram expects it on the first day and this app had nothing. A tag is a fact about a <strong>post</strong> rather than about a rectangle on an image: Pixelfed keys its row on a media id and stores a <code>metadata</code> blob that in practice holds only a version number, and no client of its own draws a box — so the row here names the post, which is what both reads want, and the day a client wants a rectangle is the day to add the two columns for it. Unique on (post, account), which is what makes re-sending the same list a no-op; a second index leads with the tagged account, because that is what &quot;photos of you&quot; selects on and without it the page is a table scan on every profile visit. The post is recorded twice — by the id a client addresses it with, which orders &quot;photos of you&quot;, and by the hash of its ActivityPub id, which is the column <code>StreamRequest::deleteRelatedTo()</code> cascades on, so a deleted post takes its tags with it. A tag is also written onto the post as a <code>Mention</code> and the post is re-sent as an <code>Update</code>: a tag only this instance knew about would notify local accounts and do nothing at all for everybody else. It does not widen who may see the post. <code>Version1000Date20260915000009</code> adds <code>social_story_react</code> — the reactions and replies a story has been answered with. A story could be watched and nothing else: Pixelfed has three ways of answering one and a verb for each (<code>View</code>, <code>Story:Reaction</code>, <code>Story:Reply</code>), and this app sent and understood none of them, so a story posted to Pixelfed followers came back silent. One table for reactions and replies because they are the same row with a different word on it — who, about which story, what they said — which is how Pixelfed keeps them too. A reply is deliberately <strong>not</strong> a post: no <code>social_stream</code> row, so it cannot reach a timeline, a profile or an outbox through a query nobody has written yet, and it is deleted with the story rather than outliving what it was about. Unique on the hash of the activity&#39;s own id, which is what makes a retried delivery one row: an inbox is retried, and a reaction counted twice would be two reactions. Indexed on (story, id) for the one read there is and on (story, account) for the per-account cap. Deleting a story now takes its views and its answers with it in one place — <code>StoriesRequest::deleteRelatedTo()</code> — which also closes a gap: a story withdrawn by its author with a <code>Delete</code> used to leave its view rows behind. <code>Version1000Date20260915000008</code> adds <code>social_discover_cat</code> — the subjects an instance says it is about. Explore is trending, and trending on a small instance is four hashtags and a wedding, which reads as abandoned rather than as somewhere to start. What an instance would <em>like</em> to be known for is a decision its administrators make and not something a counter can arrive at, so this is curated and sits above the counted lists, saying which of the two it is. The hashtags are a JSON array on the row rather than a table of their own: there are a handful of categories on any instance that has them, each naming a handful of tags, nothing joins on them, and the whole set is read at once by the one page that shows it. No index beyond the key, for the same reason. <code>Version1000Date20260914000003</code> adds the two columns the actor-cache refresh needed and the index the queue drain was missing: <code>social_cache_actor.sync_attempt</code> and <code>sync_failures</code> — when this instance last <em>tried</em> to refresh a cached remote actor (unix time, 0 for never) and how many attempts in a row have failed since one worked, indexed together with <code>local</code>, which is the other predicate of the query that orders on them. Integers rather than a datetime so that &quot;never&quot; is 0 and sorts the same on every database, where a NULL datetime does not. And <code>social_req_queue (status, priority, tries, last)</code>: <code>getStandby()</code> selects on <code>status</code> and orders on the other three, 200 rows at a time, and the only index it had was <code>(status, id)</code> — so every drain sorted the whole standby set to pick its window.</p>\n<p><code>Version1000Date20260927000001</code> drops <code>social_feed</code> and <code>social_feed_item</code>, the tables of the feed subscriptions that shipped in 0.26.60 and were removed in 0.26.95; both steps are guarded, so an instance that never had them is left alone.</p>\n<h2 id=\"version1000date20260925000020\">Version1000Date20260925000020</h2>\n<p> adds <code>social_interest</code> and <code>social_interest_hide</code> — For you. A step of its own rather than a paragraph of the squash, because the squash is recorded as run on every instance that existed when it was made: a table added to it would reach fresh installs and nobody else. <code>SquashedSchemaTest</code> holds only the steps older than the squash to &quot;move data or go into the squash&quot;. No index beyond the unique pairs: every read of <code>social_interest</code> is one reader&#39;s whole set — a few hundred rows at most, because <code>InterestService</code> forgets the faintest once there are more — and every read of <code>social_interest_hide</code> is one reader&#39;s recent hides or the daily purge by <code>creation</code>.</p>\n<h2 id=\"version1000date20261023000002\">Version1000Date20261023000002</h2>\n<p> adds the three owner-scoped For You behavioural tables above. Their rows contain only compact scores, event UUIDs and hashed exposure keys; reset and account deletion clear them. <code>Version1000Date20261025000001</code> adds the single-row instance epoch used to invalidate every open learning buffer with one database update.</p>\n<p><code>Version1000Date20261023000003</code> adds the hourly, instance-wide <code>social_rec_discovery</code> table. The administrator health view aggregates these counters by provider and time window; discovery terms and reader or post identifiers are never written.</p>\n<h2 id=\"version1000date20261005000001\">Version1000Date20261005000001</h2>\n<p> adds <code>social_cache_doc.ai_source</code>, the provenance a cached picture stated about itself (see the schema table). A column rather than a flag inside <code>meta</code>: <code>meta</code> is a JSON blob nothing queries, and this one is read on every attachment of every status a client is handed.</p>\n<h2 id=\"version1000date20261016100400\">Version1000Date20261016100400</h2>\n<p> adds <code>social_stream.root_prim</code>, indexed — the root of the thread a direct message belongs to, stored with it: its parent&#39;s stored root, else the topmost post a walk up reaches, else itself; replies that arrived before their parent are moved under its root when it comes. A chat is a chain of replies each to the one before, and the conversations walked it up a query a level on every read and every poll of their badge, and grouped a chat longer than the walk under wherever the walk stopped, so its conversation id moved with every message. Now the page reads the roots of its messages in one statement, and the thread of a conversation is read from its root however deep it is (<code>ConversationsRequest::getThread()</code>); a message without one — stored before the column, until <code>Cron\\ThreadRoots</code> (queued here) reaches it — is walked as before. Posts that are not direct messages keep NULL: the muted-thread and hidden-reply checks walk them as they did.</p>\n<h2 id=\"version1000date20261016103300\">Version1000Date20261016103300</h2>\n<p> adds <code>social_video_views</code> and <code>social_video_seen</code> — the public view count of a video posted here, and the day&#39;s dedupe behind it (see the schema table and <strong>Where somebody stopped watching</strong>). Two tables because they keep different things for different lengths of time: the number for as long as the post exists, the viewers for the day they were counted on.</p>\n<p><code>Version1000Date20261006000010</code> adds <code>social_stream_rev.media</code>, the attachments of each recorded version of a status (see the schema table).</p>\n<h2 id=\"version1000date20261021000001\">Version1000Date20261021000001</h2>\n<p> adds <code>social_stream_del</code>, a cursor of the latest 10,000 status deletions. <code>Version1000Date20261021000002</code> adds visibility and the hashes of original recipients; <code>Version1000Date20261021000003</code> adds the hashed followers collection for unlisted and followers-only posts. The daemon can remove deleted direct messages only from direct streams belonging to original participants, and unlisted/followers-only deletion events only from home and list streams of original recipients or accepted followers of that exact collection, without retaining post content. Private deletion events carry no hashtags and never reach public or hashtag streams.</p>\n<p>Two of those deserve a warning.</p>\n<h2 id=\"version1000date20260907000001\">Version1000Date20260907000001</h2>\n<p> adds an autoincrement <code>BIGINT</code> primary key to <code>social_stream_dest</code> and <code>social_stream_tag</code>, the two highest-cardinality tables. On MySQL/MariaDB that is a full table rebuild, so on a large instance <code>occ upgrade</code> will sit there for a while with the instance in maintenance mode. The change is correct and needed; the cost is not obvious from the migration.</p>\n<h2 id=\"version1000date20260910000001\">Version1000Date20260910000001</h2>\n<p> costs what it looks like — fifteen index statements, no table touched — on MySQL/MariaDB and PostgreSQL only. SQLite cannot change an index in place: Doctrine implements every one of them as a full table rebuild, so the same migration copies ten tables (<code>social_stream</code>, <code>social_cache_actor</code>, <code>social_cache_doc</code>, <code>social_follow</code>, <code>social_action</code>, <code>social_client</code>, both queues and both stream side tables) out, drops them, recreates them and copies the rows back. Plan the window for a rewrite of nearly the whole schema and for peak disk of about twice what those tables occupy. Nothing is at risk — SQLite DDL is transactional — but an operator sizing the outage from the MySQL figure will be wrong by an order of magnitude.</p>\n<h2 id=\"version1000date20260910000003\">Version1000Date20260910000003</h2>\n<p> exists because the step before it was wrong about the cron. <code>manageHashtags()</code> skips a hashtag whose freshly counted trend equals the JSON already stored, which on an instance that has just upgraded is the normal case — so the zeroed counter columns would never have been written, and <code>getTrending()</code> reads nothing else. The backfill pages through <code>social_hashtag</code> on its primary key, leaves rows already in agreement alone, and is a no-op on a fresh install. <code>Version1000Date20261009500100</code> widens <code>social_hashtag.hashtag</code> from 63 to 127 characters, the width of <code>social_stream_tag.hashtag</code> it is counted from, on instances that created the table at 63: the squashed schema creates it at 127 but adds only missing columns to a table that exists, so an upgrade from 0.24.1 kept 63, and on PostgreSQL and MySQL a tag between the two widths fails the trends pass. An instance on a release before 0.23 created its tables before every step the squash replaced, and three of their changes cannot wait for a later step, so the squash makes them on a table that exists: its <code>preSchemaChange()</code> removes duplicate (object, actor) pairs from <code>social_follow</code> — the old unique indexes led with <code>accepted</code>, so a pair could be there pending and accepted, and the accepted row is kept — before <code>social_f_oa_u</code> makes the pair unique; it widens <code>social_client.app_client_secret</code> to 127 before <code>Version1000Date20261008000100</code> hashes the secrets into it; and it makes the <code>id</code> it adds to <code>social_stream_dest</code> and <code>social_stream_tag</code> their primary key, which MySQL requires of an autoincrement column. <code>Version1000Date20261011500100</code> does the rest: it drops the indexes the history dropped (<code>afoa</code>, <code>aoa</code>, <code>social_f_oa</code>, <code>ipoha</code>, <code>ts</code> and the unnamed unique index on <code>social_stream.nid</code> beside its primary key), gives <code>social_cache_doc.account</code> its default, and covers an instance that ran the squash before it did the widening and the keys. <code>UpgradeFromReleasesTest</code> replays the upgrade from the schemas 0.10.0 and 0.24.1 leave, and the upgrade workflow runs it from 0.10.0 on Nextcloud 34, then takes Nextcloud to 35.</p>\n<p>There is no downgrade path, and none is possible: <code>Version1000Date20260611000001</code> drops tables outright.</p>\n<h2 id=\"version1000date20260925000001\">Version1000Date20260925000001</h2>\n<p> brings <code>social_stream_tag.hashtag</code> into that normalised form for the rows written before posts&#39; tags were stored in it: they used to be kept as their author wrote them, compared through <code>LOWER(st.hashtag)</code>, and no index answers a comparison over a function of the column. It pages on the primary key, reads only the rows whose tag is not lowercase where the database&#39;s <code>LOWER()</code> folds Unicode (every row on SQLite, whose does not), and where two tags of one post become the same one deletes the second rather than letting the unique <code>(stream_id, hashtag)</code> index refuse the rewrite.</p>\n<h2 id=\"version1000date20260925000002\">Version1000Date20260925000002</h2>\n<p> adds that <code>account_lower</code> column and fills it in for the rows already cached, paged on the primary key. The account search behind the mention picker, <code>/api/v2/search</code>, <code>/api/v1/accounts/search</code> and the unified search used to match a prefix of <code>account</code> under <code>COLLATE utf8mb4_general_ci</code> on MySQL, and the lookup by handle compared <code>LOWER(account)</code>: an unindexed column either way, so every keystroke read every cached actor. They compare the lowercased copy as it stands now (<code>CacheActorsRequest::searchAccounts()</code>), which MySQL and MariaDB answer as an index range; PostgreSQL and SQLite plan a prefix <code>LIKE</code> as a range only under a C collation or <code>case_sensitive_like</code>, so there the search is still a scan, of one short column, while the lookup by handle is an index lookup everywhere.</p>\n<p>There is no notifications table: in-app notifications are stored in <code>social_stream</code> as <code>SocialAppNotification</code> items. (A <code>TABLE_NOTIFICATION</code> constant naming a <code>social_notif</code> table that no migration ever created used to be declared here; it has been removed.)</p>\n<hr>\n","toc":[{"id":"social-action","text":"social_action","level":2},{"id":"social-actor","text":"social_actor","level":2},{"id":"social-cache-actor","text":"social_cache_actor","level":2},{"id":"social-cache-doc","text":"social_cache_doc","level":2},{"id":"social-client","text":"social_client","level":2},{"id":"social-device-auth","text":"social_device_auth","level":2},{"id":"social-follow","text":"social_follow","level":2},{"id":"social-hashtag","text":"social_hashtag","level":2},{"id":"social-instance","text":"social_instance","level":2},{"id":"social-req-queue","text":"social_req_queue","level":2},{"id":"social-host-breaker","text":"social_host_breaker","level":2},{"id":"social-stream","text":"social_stream","level":2},{"id":"social-discover-cat","text":"social_discover_cat","level":2},{"id":"social-trend-review","text":"social_trend_review","level":2},{"id":"social-relay","text":"social_relay","level":2},{"id":"social-channel","text":"social_channel","level":2},{"id":"social-watch","text":"social_watch","level":2},{"id":"social-video-views","text":"social_video_views","level":2},{"id":"social-video-seen","text":"social_video_seen","level":2},{"id":"social-video-rendition","text":"social_video_rendition","level":2},{"id":"social-file-post","text":"social_file_post","level":2},{"id":"social-file-comment","text":"social_file_comment","level":2},{"id":"social-quote-grant","text":"social_quote_grant","level":2},{"id":"social-team","text":"social_team","level":2},{"id":"social-team-post","text":"social_team_post","level":2},{"id":"social-portfolio","text":"social_portfolio","level":2},{"id":"social-media-tag","text":"social_media_tag","level":2},{"id":"social-story-react","text":"social_story_react","level":2},{"id":"social-stream-view","text":"social_stream_view","level":2},{"id":"social-stream-act","text":"social_stream_act","level":2},{"id":"social-stream-dest","text":"social_stream_dest","level":2},{"id":"social-stream-queue","text":"social_stream_queue","level":2},{"id":"social-stream-tag","text":"social_stream_tag","level":2},{"id":"social-search-term","text":"social_search_term","level":2},{"id":"social-starter-pack","text":"social_starter_pack","level":2},{"id":"social-stream-media","text":"social_stream_media","level":2},{"id":"social-actor-relation","text":"social_actor_relation","level":2},{"id":"social-report","text":"social_report","level":2},{"id":"social-media-block","text":"social_media_block","level":2},{"id":"social-moderation","text":"social_moderation","level":2},{"id":"social-strike","text":"social_strike","level":2},{"id":"social-client-auth","text":"social_client_auth","level":2},{"id":"social-access-block","text":"social_access_block","level":2},{"id":"social-announce-react","text":"social_announce_react","level":2},{"id":"social-emoji","text":"social_emoji","level":2},{"id":"social-stream-card","text":"social_stream_card","level":2},{"id":"social-reaction","text":"social_reaction","level":2},{"id":"social-gif","text":"social_gif","level":2},{"id":"social-followed-tag","text":"social_followed_tag","level":2},{"id":"social-interest","text":"social_interest","level":2},{"id":"social-interest-hide","text":"social_interest_hide","level":2},{"id":"social-rec-signal-social-rec-event-social-rec-seen","text":"social_rec_signal, social_rec_event, social_rec_seen","level":2},{"id":"social-rec-epoch","text":"social_rec_epoch","level":2},{"id":"social-rec-discovery","text":"social_rec_discovery","level":2},{"id":"social-collection","text":"social_collection","level":2},{"id":"social-collection-item","text":"social_collection_item","level":2},{"id":"social-place","text":"social_place","level":2},{"id":"social-import-post","text":"social_import_post","level":2},{"id":"social-import","text":"social_import","level":2},{"id":"social-atproto-identity","text":"social_atproto_identity","level":2},{"id":"social-atproto-instance-key","text":"social_atproto_instance_key","level":2},{"id":"social-atproto-repo","text":"social_atproto_repo","level":2},{"id":"social-atproto-record","text":"social_atproto_record","level":2},{"id":"social-atproto-block","text":"social_atproto_block","level":2},{"id":"social-atproto-blob","text":"social_atproto_blob","level":2},{"id":"social-atproto-event","text":"social_atproto_event","level":2},{"id":"social-atproto-plc-log","text":"social_atproto_plc_log","level":2},{"id":"social-atproto-watch","text":"social_atproto_watch","level":2},{"id":"social-atproto-notify-cursor","text":"social_atproto_notify_cursor","level":2},{"id":"social-atproto-chat-cursor","text":"social_atproto_chat_cursor","level":2},{"id":"social-atproto-blocklist","text":"social_atproto_blocklist","level":2},{"id":"social-atproto-labeler","text":"social_atproto_labeler","level":2},{"id":"social-atproto-app-password","text":"social_atproto_app_password","level":2},{"id":"social-atproto-session","text":"social_atproto_session","level":2},{"id":"social-atproto-video","text":"social_atproto_video","level":2},{"id":"social-atproto-oauth-request","text":"social_atproto_oauth_request","level":2},{"id":"social-atproto-oauth-session","text":"social_atproto_oauth_session","level":2},{"id":"social-atproto-oauth-replay","text":"social_atproto_oauth_replay","level":2},{"id":"social-atproto-move","text":"social_atproto_move","level":2},{"id":"social-verification","text":"social_verification","level":2},{"id":"social-post-hold","text":"social_post_hold","level":2},{"id":"social-story","text":"social_story","level":2},{"id":"social-story-view","text":"social_story_view","level":2},{"id":"social-list","text":"social_list","level":2},{"id":"social-list-member","text":"social_list_member","level":2},{"id":"social-filter","text":"social_filter","level":2},{"id":"social-filter-kw","text":"social_filter_kw","level":2},{"id":"social-filter-st","text":"social_filter_st","level":2},{"id":"social-convo-state","text":"social_convo_state","level":2},{"id":"social-domain-block","text":"social_domain_block","level":2},{"id":"social-account-note","text":"social_account_note","level":2},{"id":"social-mute-expiry","text":"social_mute_expiry","level":2},{"id":"social-stream-rev","text":"social_stream_rev","level":2},{"id":"social-stream-del","text":"social_stream_del","level":2},{"id":"social-featured-tag","text":"social_featured_tag","level":2},{"id":"social-announcement","text":"social_announcement","level":2},{"id":"social-announce-read","text":"social_announce_read","level":2},{"id":"social-scheduled","text":"social_scheduled","level":2},{"id":"social-durable-cache","text":"social_durable_cache","level":2},{"id":"social-ext-user","text":"social_ext_user","level":2},{"id":"social-ext-signup","text":"social_ext_signup","level":2},{"id":"social-ext-invite","text":"social_ext_invite","level":2},{"id":"sessionservice-create","text":"SessionService::create()","level":2},{"id":"version1000date20260611000001","text":"Version1000Date20260611000001","level":2},{"id":"version1000date20260916000003","text":"Version1000Date20260916000003","level":2},{"id":"version1000date20260916000002","text":"Version1000Date20260916000002","level":2},{"id":"version1000date20260915000013","text":"Version1000Date20260915000013","level":2},{"id":"version1000date20260925000020","text":"Version1000Date20260925000020","level":2},{"id":"version1000date20261023000002","text":"Version1000Date20261023000002","level":2},{"id":"version1000date20261005000001","text":"Version1000Date20261005000001","level":2},{"id":"version1000date20261016100400","text":"Version1000Date20261016100400","level":2},{"id":"version1000date20261016103300","text":"Version1000Date20261016103300","level":2},{"id":"version1000date20261021000001","text":"Version1000Date20261021000001","level":2},{"id":"version1000date20260907000001","text":"Version1000Date20260907000001","level":2},{"id":"version1000date20260910000001","text":"Version1000Date20260910000001","level":2},{"id":"version1000date20260910000003","text":"Version1000Date20260910000003","level":2},{"id":"version1000date20260925000001","text":"Version1000Date20260925000001","level":2},{"id":"version1000date20260925000002","text":"Version1000Date20260925000002","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"database-schema","manual":false,"prev":{"path":"/docs/architecture-http-routing","title":"HTTP routing"},"next":{"path":"/docs/architecture-key-services","title":"Key Services"},"parent":null},{"slug":"architecture-key-services","path":"/docs/architecture-key-services","title":"Key Services","description":"The business logic lives in lib/Service/.","group":"architecture","html":"<p>The business logic lives in <code>lib/Service/</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":[{"path":"/docs/architecture-account-and-identity","title":"Account & Identity","description":"Creates local actors (generating an RSA key pair via SignatureService) and marks them deleted, refreshes the local actor cache (avatar, display name, follower/following/post counts)…","parent":true},{"path":"/docs/architecture-content-and-timelines","title":"Content & Timelines","description":"Local post edits write a UTC, second-precision ActivityPub updated value strictly later than the previous edit, so peers can order rapid successive Update activities.","parent":true},{"path":"/docs/architecture-federation","title":"Federation","description":"Wraps items in Create/Update/Delete activities, LD-signs them, resolves target inboxes, and drives the delivery queue. A reply whose parent exists only on Bluesky keeps its native…","parent":true},{"path":"/docs/architecture-media","title":"Media","description":"Owns the cached document lifecycle: caching a remote document by id, serving originals and resized copies out of app storage, and caching the local actor's avatar and header. Serving…","parent":true},{"path":"/docs/architecture-system","title":"System","description":"App/user configuration and the derived URLs (cloud URL, social URL, social address, max download size, self-signed toggle), plus ActivityPub id generation. The social URL is derived from…","parent":true},{"path":"/docs/architecture-mastodon-web-push","title":"Mastodon Web Push","description":"VapidService creates one stable instance key pair and seals the private key with PrivateKeyCipher; PushSubscriptionService keeps each access token, endpoint and browser key pair in an…","parent":true},{"path":"/docs/architecture-mastodon-websocket-and-sse-streaming","title":"Mastodon WebSocket and SSE streaming","description":"MastodonStreamingDaemon (occ social:mastodon:stream) serves the user, user:notification, direct, list, public, public:media, public:local, public:local:media, public:remote…","parent":true}],"anchor":"key-services","manual":false,"prev":{"path":"/docs/architecture-database-schema","title":"Database Schema"},"next":{"path":"/docs/architecture-account-and-identity","title":"Account & Identity"},"parent":null},{"slug":"architecture-account-and-identity","path":"/docs/architecture-account-and-identity","title":"Account & Identity","description":"Creates local actors (generating an RSA key pair via SignatureService) and marks them deleted, refreshes the local actor cache (avatar, display name, follower/following/post counts)…","group":"architecture","html":"<h2 id=\"accountservice\">AccountService</h2>\n<p>Creates local actors (generating an RSA key pair via <code>SignatureService</code>) and marks them deleted, refreshes the local actor cache (avatar, display name, follower/following/post counts), performs &quot;blind key rotation&quot;, and reaps actors past their deletion retention</p>\n<h2 id=\"actorservice\">ActorService</h2>\n<p>Saves/updates cached <code>Person</code> rows and resolves an actor&#39;s cached header image</p>\n<h2 id=\"cacheactorservice\">CacheActorService</h2>\n<p>Central actor cache/resolver. Looks up actors by ActivityPub id or <code>user@host</code>, fetches unknown remote actors over WebFinger + HTTP on a cache miss, and probes their followers/following/outbox counts. The cron refresh (<code>manageCacheRemoteActors()</code>, <code>SYNC_BATCH</code> of 50 per pass) records every attempt in <code>social_cache_actor.sync_attempt</code>/<code>sync_failures</code> and takes the oldest attempt first. It used to select on <code>creation</code> — which for a remote actor is the <code>published</code> date its own instance reports and never moves — with no order and no record of having tried, so fifty rows on a dead instance were the fifty the refresh picked every twelve minutes and no live profile was ever refreshed again. A failure now doubles the wait from an hour (<code>CacheActorsRequest::syncWait()</code>, applied both in SQL by <code>limitToSyncDue()</code> and by the service) and after <code>SYNC_MAX_FAILURES</code> (10, about six weeks) the refresh stops asking. Nothing is deleted by any of that: the row, the follows pointing at it and the posts it wrote stay, an on-demand fetch still goes to the network, and one that works resets the count. <code>getFromId()</code> memoises what it resolved, so a page that names one author five times asks once; the memo holds at most <code>MEMO_LIMIT</code> (500) actors, least recently used out first, and <code>Cron\\Queue</code> (before each delivery batch and the inbound queue), every <code>Cron\\Cache</code> step and <code>social:worker</code> empty it with <code>forgetMemoised()</code>, because cron.php runs every job in one process and an actor held from an earlier batch would hide a key rotation. A fetch on a cache miss that fails is remembered for ten minutes in <code>DurableCache</code> (<code>MISS_NAMESPACE</code>, <code>MISS_SECONDS</code>, the same instance that keeps the <code>social.actoralias</code> addresses): until then <code>getFromId()</code> answers that id with <code>CacheActorDoesNotExistException</code> rather than asking its server again, so a post whose author is gone costs one connect attempt per ten minutes rather than one per like, boost or reply. A Bluesky account the AppView did not give is remembered the same way, unless it has been stored since. A refresh (<code>getFromId($id, true)</code>) is not held back. <code>getCachedFromId()</code> is the same lookup without any fetch — the row, or the row an alias names — which is what the unified search asks</p>\n<h2 id=\"accountservice-asserthandleavailable-linkexternalhandle\">AccountService::assertHandleAvailable() / linkExternalHandle()</h2>\n<p>The setup screen&#39;s two answers. <code>NavigationController::navigate()</code> no longer creates an actor on the first load: a person without one is handed <code>needsAccount</code>, a <code>suggestedHandle</code> (<code>generateHandleFromUserId()</code>) and the <code>linkedHandle</code> their profile already names, and <code>LocalController::accountCreate()</code> makes the actor when they ask, with the handle they chose — refused when it is another Nextcloud user&#39;s id (one person publishing as another) or an actor already holds it. <code>accountLink()</code> writes an account elsewhere into the profile&#39;s <code>fediverse</code> field, which is where <code>ColleagueService</code> looks, and creates nothing. An account created here is written into that field too, when it is empty (<code>publishHandleOnProfile()</code>, from the local-actor cache refresh, after the cached copy that answers WebFinger is written): Nextcloud verifies the field through a WebFinger request over https before storing it and logs every failure as an error, so the write is not attempted on a plain-http address, a refused value is taken back off core&#39;s in-memory account (it would otherwise fail every later write to the account in that process, the display name&#39;s included), and a failure is left alone for a day (<code>HANDLE_PUBLISH_RETRY</code>, kept per user in <code>handle_publish_failed</code>) rather than retried on every profile save and cron pass. <strong>Nothing that reads creates an actor either</strong>: every controller&#39;s <code>initViewer()</code>, <code>/api/v1/global/account/info</code>, <code>/oauth/userinfo</code> and the Bluesky settings and recovery routes look one up without the create flag, through <code>Controller\\OwnAccount</code> where the route acts as the account. They used to set it, so the first request the page made — while the setup screen was still on screen asking — minted the identity, and the answer came back as <em>that handle is taken</em>. The two places that do create are where somebody asks: <code>accountCreate()</code> and <code>occ social:account:create</code>, plus the user-migration import, which is restoring an account that already existed</p>\n<h2 id=\"a-first-visit-from-an-app\">A first visit from an app</h2>\n<p> (alohasocial/social#2455) — Somebody whose first contact with the app is a phone or desktop client signs in on <code>GET /oauth/authorize</code> without an account here. <code>OAuthController::authorize()</code> runs every check of the request first — the response type, the PKCE method, the client, the registered <code>redirect_uri</code>, the scopes — and an invalid request is refused as before, with nothing offered; only then is the account looked up, and where there is none the <code>oauth2</code> page gets a <code>setup</code> initial state (<code>suggestedHandle</code>, <code>socialAddress</code>, <code>bluesky</code>) in place of <code>account</code>. <code>OAuth2Authorize.vue</code> asks for the username with <code>AccountSetupForm.vue</code>, the same component the setup screen uses, posting to the same <code>accountCreate()</code>, and then loads its own address again: the client&#39;s request lives in that address, so the consent drawn the second time is for the new account and the same <code>client_id</code>, <code>redirect_uri</code>, <code>scope</code>, <code>state</code> and challenge, checked again. <code>authorizing()</code> issues no code without an account (403 <code>account-not-set-up</code>), so a bearer token still always names one. A Bluesky app&#39;s pushed request takes the same path: <code>AuthorizationServer::requested()</code> checks the request without an identity, the setup is offered, and on the reload <code>pending()</code> makes the account&#39;s Bluesky identity, as on any first need of one (until the PLC directory has taken it, the sign-in is refused as <code>invalid_request</code> <em>This account has no active Bluesky identity here</em>, as for any account in that state). With Bluesky off, a Bluesky app&#39;s request is refused before any of this, as it always was. Every other client route a Nextcloud session or app password reaches without an account answers 403 <code>{&quot;error&quot;, &quot;code&quot;: &quot;account-not-set-up&quot;, &quot;setup_url&quot;}</code> (<code>AccountNotSetUpException</code>, a <code>ClientNotFoundException</code>, so the routes that hand their credential failures to <code>error()</code> hand this one on too): <code>MastodonApiController::initViewer()</code> and <code>ClientApiController::initViewer()</code> raise it where the session&#39;s user has no actor, a route that also answers anonymous callers (Mastodon&#39;s <code>initViewer()</code> without <code>$exception</code> or with <code>$publicRoute</code>, <code>ClientApiController</code>&#39;s with <code>$required = false</code>) answers such a caller as anybody, and the <code>Controller\\OwnAccount</code> trait (<code>ownAccountOf()</code>, <code>notSetUp()</code>, <code>unlessNotSetUp()</code>) raises and answers it for every route outside those bases that acts as the reader&#39;s own account — <code>LocalController</code> (answered by <code>TNCDataResponse::failFor()</code>, in its envelope), <code>AtprotoAccountController</code>, <code>AtprotoRecoveryController</code>, <code>AtprotoFeedsController</code>, <code>ReviewController</code>, <code>ModerationListController</code> and <code>MigrationController</code>&#39;s session routes; a route that finds no Bluesky identity to act on says <em>not set up</em> where there is no account either. Routes keyed by the Nextcloud user alone (labeler subscriptions, Bluesky app passwords, the list of moderation lists) answer as they did. A bearer token whose account is gone stays a 401: no token is issued without one. <code>AdminApiControllerBase</code> resolves no account at all — moderating needs none — and the XRPC routes sign in with a Bluesky identity and an app password made in the account&#39;s settings, neither of which exists before the account does, so a sign-in there is refused before anything could say <em>not set up</em>, and saying it would tell a stranger which email addresses belong to people here</p>\n<h2 id=\"cacheactorservice-2\">CacheActorService</h2>\n<p>Central actor cache/resolver. Looks up actors by ActivityPub id or <code>user@host</code>, fetches unknown remote actors over WebFinger + HTTP on a cache miss, and probes their followers/following/outbox counts</p>\n<h2 id=\"relationshipservice\">RelationshipService</h2>\n<p>blocking and muting: stores the relation, severs follows in both directions on a block, and federates <code>Block</code>/<code>Undo{Block}</code> unless the <code>federate_blocks</code> app setting is <code>0</code>. Mutes are purely local and never federated.</p>\n","toc":[{"id":"accountservice","text":"AccountService","level":2},{"id":"actorservice","text":"ActorService","level":2},{"id":"cacheactorservice","text":"CacheActorService","level":2},{"id":"accountservice-asserthandleavailable-linkexternalhandle","text":"AccountService::assertHandleAvailable() / linkExternalHandle()","level":2},{"id":"a-first-visit-from-an-app","text":"A first visit from an app","level":2},{"id":"cacheactorservice-2","text":"CacheActorService","level":2},{"id":"relationshipservice","text":"RelationshipService","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"account-and-identity","manual":false,"prev":{"path":"/docs/architecture-key-services","title":"Key Services"},"next":{"path":"/docs/architecture-content-and-timelines","title":"Content & Timelines"},"parent":"architecture-key-services"},{"slug":"architecture-content-and-timelines","path":"/docs/architecture-content-and-timelines","title":"Content & Timelines","description":"Local post edits write a UTC, second-precision ActivityPub updated value strictly later than the previous edit, so peers can order rapid successive Update activities.","group":"architecture","html":"<p>Local post edits write a UTC, second-precision ActivityPub <code>updated</code> value\nstrictly later than the previous edit, so peers can order rapid successive\n<code>Update</code> activities.</p>\n<h2 id=\"streamservice\">StreamService</h2>\n<p>Core stream/timeline engine. Assigns ActivityPub ids, expands recipients (public/unlisted/followers/direct), resolves reply chains, detects stream types, deletes local items, and reads the timelines (home, local, global/federated, tag, account, liked, direct, notifications). Deleting a post takes what belongs to it with it: <code>StreamRequest::deleteRelatedTo()</code> removes the <code>social_stream_dest</code>, <code>social_stream_tag</code>, <code>social_stream_act</code> and <code>social_stream_card</code> rows, the <code>social_action</code> rows pointing at the post, and its cached attachment rows together with the files on disk. The cascade sits in <code>StreamRequest</code>, so every caller gets it rather than retention alone. <code>syncRemoteTimelinePage()</code> processes at most 20 entries per queued request; <code>RemoteOutboxPageReader</code> owns fetching one ActivityPub page, resolving its <code>first</code> and <code>next</code> links, and restricting links to the actor&#39;s host and port. The durable per-account cursor lets a profile request another page only when its locally stored posts run short; a 15-minute refresh of recent posts leaves older-page progress alone. The imported post fields still use the inbox path&#39;s validation helpers. It used to read only the first page, leaving the rest of a remote profile&#39;s history unavailable</p>\n<h2 id=\"postservice\">PostService</h2>\n<p>Creates posts (text, attachments, reply-to, mentions, hashtags, the content warning and the <code>sensitive</code> flag) and edits existing local posts, delegating federation to <code>ActivityService</code>. A visibility a client sent is translated once, in <code>Post::setType()</code>: Mastodon calls a followers-only post <code>private</code> and this app calls it <code>followers</code>, and a visibility the app does not recognise becomes <code>direct</code> rather than being addressed to <code>as:Public</code>. The content warning is stored as plain text on both paths (<code>strip_tags()</code>), because it is read as plain text everywhere it is shown — as the object&#39;s <code>summary</code>, as <code>spoiler_text</code>, and interpolated rather than rendered by this app&#39;s own frontend; entity-encoding it federated <code>Bob&amp;#039;s finale</code> and baked the entities into the next edit. The body takes the opposite path: it is rendered by <code>LinkifyService</code> after the recipients and hashtags are resolved, so the links in the published HTML and the <code>tag</code> array come out of one parse</p>\n<h2 id=\"postreviewservice\">PostReviewService</h2>\n<p>First-post review and the spam rules: which posts a person should see before anybody else does, and what happens to one afterwards. Two switches, both on by default (<code>review_first_post</code>, <code>autospam</code>), and a very short list of rules — the first post of an account that has published nothing here, a wall of links in a short post, and mentions scattered by an account nobody follows and that follows nobody. No wordlist and no score: a queue that says &quot;0.82&quot; tells a moderator nothing they can act on. A <strong>direct message is never held</strong>, because putting private correspondence in front of a moderator who was not written to, for a machine&#39;s reason, is worse than the spam; neither is a post by an account a moderator has already decided about, which is being dealt with by that decision. What is held is the request — <code>StatusAssemblyService</code> turns it back into the <code>Post</code> an immediate one would have been, and approving publishes it dated now, since that is when it became a post. Refusing records a <code>delete_statuses</code> strike, so the author is told and the next moderator can see it happened</p>\n<h2 id=\"statusassemblyservice\">StatusAssemblyService</h2>\n<p>The post a stored request becomes, and the request a client&#39;s <code>Status</code> becomes. Shared by the scheduler and the review queue: a note built by one path and federated by another drifts, because the quote approval, the language fallback and the source snapshot all happen inside <code>PostService::createPost()</code></p>\n<h2 id=\"scheduledstatusservice\">ScheduledStatusService</h2>\n<p><code>POST /api/v1/statuses</code> with a <code>scheduled_at</code>, and the publishing of what it stores. Keeps the client&#39;s request rather than a rendered post, because publishing has to go through <code>PostService::createPost()</code> over a <code>Post</code> assembled exactly as <code>StatusApiController::statusNew()</code> assembles one — a note built by one path and federated by another would drift on the quote approval, the language fallback and the source snapshot. <code>MIN_LEAD_TIME</code> (300 s) is Mastodon&#39;s five-minute minimum and is also what makes the cron interval workable; <code>MAX_PENDING</code> (300) and <code>MAX_PENDING_PER_DAY</code> (25) are Mastodon&#39;s caps, and are needed because a scheduled post is the only thing a client can store unpublished and unbounded where no moderator can find it. The visibility is resolved at scheduling time so a later change of <code>source[privacy]</code> cannot move a waiting post&#39;s audience, and everything <code>createPost()</code> would refuse — length, an unusable poll — is refused while there is still a client to tell. <code>publishDue()</code> claims a row by deleting it before publishing: two workers that read the same due row both try, the database lets one affect it, and only that one posts</p>\n<h2 id=\"pollservice\">PollService</h2>\n<p>Federated polls: serves the Mastodon Poll entity of a stored <code>Question</code> and votes on remote polls (one vote note per choice to the poll&#39;s author; the viewer&#39;s choices are remembered in the per-viewer stream action, authoritative counts arrive as <code>Update{Question}</code>)</p>\n<h2 id=\"followservice\">FollowService</h2>\n<p>Follow/unfollow flows, follower/following collections, and relationship lookups</p>\n<h2 id=\"likeservice\">LikeService</h2>\n<p>Creates and undoes Like activities</p>\n<h2 id=\"streampruneservice\">StreamPruneService</h2>\n<p>Retention: deletes remote statuses older than <code>retention_days</code> (default 0 = disabled) that no local user interacted with, whose author nobody follows, that no local status replies to or boosts, and that are not DMs — together with their dest/action/tag rows and cached attachments. Runs bounded in the Cache cron and unbounded via <code>occ social:stream:prune</code>. The old remote statuses are walked in (<code>creation</code>, <code>id_prim</code>) order, a chunk of 500 candidates at a time off the <code>creation</code> index, and only the candidates are asked the protection rules; where the walk got to is kept as <code>retention_checked</code> (<code>day|creation|id_prim</code>) after every chunk, so the next chunk and the next run carry on from there and a kept post — most of the old table on a real instance — is judged once a day rather than on every chunk of every run. The first run of a new day starts again from the oldest row, so a post that lost its protection goes a day later at most. A cron pass with its ceiling of 5,000 deletions judges at most <code>MAX_CHUNKS</code> (40) chunks. Whatever <code>retention_days</code> says, every pass also purges the queue rows nothing will act on again and the <code>SocialAppNotification</code> rows older than <code>notification_retention_days</code> (default 90): local rows about a local user&#39;s post, read once from the bell and never federated</p>\n<h2 id=\"remotefetchqueue\">RemoteFetchQueue</h2>\n<p>The remote fetches a page would like done and must not wait for. A page shows what is cached here and hands what is missing to this, which queues one background job per piece (<code>IJobList::has()</code> first, so a page asked for a hundred times before cron runs is still one job per argument, and at most <code>MAX_PER_CALL</code>, 20, per call); the next look at the page has it. <code>resolveActors()</code> queues a <code>Cron\\ResolveActor</code> per uncached actor, and <code>resolveAccounts()</code> one per <code>user@host</code> handle (an opened starter pack&#39;s members not held here) — used for the people named in a page&#39;s pictures (<code>PostDecorationService::attachTaggedPeople()</code>, which reads them from the cache in one query and used to fetch each miss over HTTP while the timeline was being built) and for the accounts a remote account&#39;s followers/following collection names (<code>ActivityPubFollowListSource</code>, read in the background; the list used to resolve up to 80 entries one after another at the federation timeout each while the reader waited). <code>fillFollowList()</code> queues that read, a <code>Cron\\FillFollowLists</code>, at most once per <code>FOLLOW_LISTS_INTERVAL</code> (ten minutes) per account and direction (<code>social.followfill</code>). <code>syncTimeline()</code> queues a <code>Cron\\SyncRemoteTimeline</code> for a remote account whose profile&#39;s first page a signed-in reader opened, at most once per <code>TIMELINE_SYNC_INTERVAL</code> (15 minutes) per account, stamped in <code>DurableCache</code> (<code>social.outboxsync</code>) when queued; the profile route used to read the outbox and import up to 20 posts before answering, on every page including each scroll</p>\n<h2 id=\"cacheactorsweepservice\">CacheActorSweepService</h2>\n<p>The other half of retention, for accounts rather than posts: evicts the cached remote actors nothing here refers to any more, with their avatars and headers. A row is written the first time this instance meets an account — a like on a local post, a boost seen in a timeline, a reply in a thread — and until this existed nothing removed one but the account&#39;s own instance sending a <code>Delete</code> (<code>PersonInterface</code>) or a moderator purging its domain (<code>ModerationService</code>), so a year of federating left tens of thousands of rows and a picture each for accounts nobody here has anything to do with. An actor goes when nobody here follows it, it follows nobody here, no post of its is stored, no follow request or block/mute/endorsement names it either way, and it has been neither seen nor tried for <code>cache_actor_days</code> (default 180; 0 disables). Paged like <code>StreamPruneService</code> and bounded per cron pass (<code>Cron\\Cache::SWEEP_BATCH</code>, 500). What is swept is fetched again the moment it is needed, so what is lost is a request and never a relationship or a post. A like or a boost of a local post is deliberately not one of the conditions — the same line <code>tootctl accounts prune</code> draws: the <code>social_action</code> row stays and names the actor, and the profile is fetched again when the list of who liked the post is opened</p>\n<h2 id=\"boostservice\">BoostService</h2>\n<p>Creates and undoes Announce (boost/reblog) activities. One Announce stream row per (post, booster), looked up with <code>StreamRequest::getAnnounceBy()</code>: a second booster gets a row of their own rather than being folded into the first one&#39;s, so the row names who boosted and an Undo names an Announce its signer made; a boost is counted from the per-booster <code>social_action</code> rows. Rows stored before boosts had one row each — attributed to one booster, carrying the others&#39; followers in <code>cc</code> — are left as they are. Two followers boosting the same post are two cards in the home timeline, each naming its booster; <code>filterDuplicate()</code> only hides the viewer&#39;s own boosts</p>\n<h2 id=\"actionservice\">ActionService</h2>\n<p>Dispatcher for the Mastodon-style status actions. favourite/unfavourite create and delete a Like, reblog/unreblog an Announce, and bookmark/unbookmark toggle the viewer&#39;s local <code>bookmarked</code> flag (never federated, served by <code>/api/v1/bookmarks</code>), and pin/unpin hand off to <code>PinService</code>; <code>mute</code>/<code>unmute</code> mute the conversation. <code>translate</code> is deliberately <strong>not</strong> one of these: it used to be, returning the status unchanged, which a client cannot tell from a translation — it is <code>StatusApiController::statusTranslate()</code> now, answering a Translation entity from a real provider</p>\n<h2 id=\"translationservice\">TranslationService</h2>\n<p>One status in the reader&#39;s language, through whatever translation provider this Nextcloud has (<code>OCP\\TaskProcessing</code>, the same one Talk, Mail and the assistant use). There is no translation engine in this app and there should not be one. A server with no provider announces <code>configuration.translation.enabled: false</code> and the route answers 503; it never hands back the original text, which is what the old stub did 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 <code>MAX_TEXTS</code> lasts — each text is a round-trip — and what is past the budget is left out of the entity rather than returned untranslated</p>\n<h2 id=\"notificationgroupservice\">NotificationGroupService</h2>\n<p>Mastodon 4.3&#39;s grouped notifications: favourites and boosts of one post, and follows, become one group with a count and a sample of accounts; mentions never group. The <code>group_key</code> names what the group <em>is</em> (<code>favourite-{status id}</code>), never the notifications in it, so it still names the same group after more arrive and a client&#39;s dismiss still lands</p>\n<h2 id=\"notificationpolicyservice\">NotificationPolicyService</h2>\n<p>The five questions an account may ask about whoever is writing to it (<code>for_not_following</code>, <code>for_not_followers</code>, <code>for_new_accounts</code>, <code>for_private_mentions</code>, <code>for_limited_accounts</code>), and the requests inbox the held notifications are gathered into, one row per sender. Everything starts at <code>accept</code>, and an account that has not touched the policy pays no query for it. <code>drop</code> behaves as <code>filter</code>: the 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 next week can still show what it caught this week. The hold rules (<code>isHeld()</code>) are applied in two places and are one piece of code: <code>partition()</code> for a page when the list is read, and <code>isHeldFor()</code> for one notification as it is stored, which <code>NotificationService::emit()</code> calls before anything is raised. A held notification is stored and raises nothing — no Nextcloud notification (bell, push, mail), no Activity entry — and so never reaches the digest/quiet-hours check either. An accepted sender is never held. A new local account is given a stored policy at creation (<code>startCalm()</code>, called from <code>AccountService::createActor()</code>, the one path every way of creating an account goes through; not for team or channel actors): the administrator&#39;s <code>notification_policy_defaults</code>, else <code>NotificationPolicy::CALM</code>. An account without a stored policy accepts everything, which keeps the accounts from before that unchanged, and its policy carries <code>notice: true</code> until it saves one or dismisses the pointer (<code>notification_policy_notice_dismissed</code>). <code>allowed()</code> / <code>stopAllowing()</code> are the always-allowed list. Accept, dismiss and stop-allowing move the reader&#39;s timeline revision, which tags the unread count</p>\n<h2 id=\"countsservice\">CountsService</h2>\n<p> and <strong><code>Middleware\\HideCountsMiddleware</code></strong> — Whether a reader is shown how many likes, dislikes, boosts and followers things have, hidden unless they turn the numbers on (<code>show_counts</code> user value, stored as <em>showing</em> so the default needs no migration). The numbers ride on every status and every account the client APIs hand out, so they are taken out in one place rather than route by route: the middleware runs after every <code>ClientApiController</code>, <code>MastodonApiController</code> and <code>LocalController</code> route with a 2xx JSON answer (a <code>JSONResponse</code> by then — Nextcloud renders a route&#39;s <code>DataResponse</code> before the after-middlewares run), finds the reader (the token&#39;s account for a bearer request, the session&#39;s otherwise), and for one who hides the numbers re-encodes the body and sets <code>favourites_count</code>/<code>reblogs_count</code>/<code>replies_count</code>/<code>dislikes_count</code> on statuses to 0 at any depth — a status is an object with <code>favourites_count</code> beside <code>reblogs_count</code>. An account&#39;s <code>followers_count</code> is never touched: it describes the account rather than ranks a post, a reader&#39;s own is theirs to know, and a client told 0 shows &quot;0 followers&quot; as a fact. Decoded as objects, not arrays, so <code>{}</code> stays <code>{}</code>. ActivityPub documents are answered to other servers and are not touched. The web app also hides the elements that would draw them (<code>serverData.hideCounts</code>), since it counts optimistically when the reader likes something; on a profile it leaves another account&#39;s follower number off and shows the reader their own. A new account&#39;s counters go into its first cached row (<code>CacheActorsRequest::save()</code> writes the three <code>count_*</code> columns from the counts <code>AccountService::addLocalActorDetailCount()</code> has just taken), so the follows that come in move them from 0 rather than being skipped on a row that was &quot;never counted&quot; (-1) until the cron&#39;s walk</p>\n<h2 id=\"aicontentservice\">AiContentService</h2>\n<p>Whether a post says it was made with AI, and whether a reader wants such posts hidden. Three signals, all of them labels the post carries: a specific hashtag from <code>DEFAULT_TAGS</code> plus the administrator&#39;s <code>ai_tags</code> (the generic <code>#ai</code> tag is always ignored); the author&#39;s own mark, which on the wire is the same <code>#AIgenerated</code> hashtag the composer adds; and a picture whose stored row says its metadata stated machine-generation provenance (<code>social_cache_doc.ai_source</code>, read by <code>ImageMetadataService::digitalSourceType()</code> before the metadata is stripped). Nothing looks at pixels or prose. The per-user switch (<code>hide_ai_content</code>) is applied in <code>FilterService::apply()</code> and <code>applyToNotifications()</code> — every context, lists included — and every <code>Status</code> and <code>MediaAttachment</code> entity carries <code>ai_generated</code> regardless, for clients that label rather than hide</p>\n<h2 id=\"notificationdeliveryservice\">NotificationDeliveryService</h2>\n<p><em>When</em> a Nextcloud user is told, as opposed to the policy&#39;s <em>whether</em>: the per-user <code>NotificationDelivery</code> setting (<code>instant</code>, or <code>digest</code> at one to four local times a day, with direct messages and mentions from followed accounts passing through on their own switches, and optional quiet hours in either mode), stored as one JSON user value. <code>NotificationService::emit()</code> asks it before raising the bell — after the policy and the conversation mute, which raise nothing at all; the stored notification row is written regardless, because it is the hold — the in-app list, <code>/api/v1/notifications</code> and the markers read it as before, and only the Nextcloud notification waits. <code>digestFor()</code> raises one <code>digest</code> notification with the unread rows since the last digest counted per kind (<code>StreamRequest::countNotificationsBySubType()</code>, past the notifications read marker, inside the window, muted conversations left out by the query and what the policy holds subtracted using <code>NotificationInboxService::held()</code>), adds <code>waiting</code> — how many senders are in the requests inbox, which <code>Notifier</code> reads out as a last line — and is never raised for requests alone, takes the older digest off the bell first, and moves the clock to the digest&#39;s cut. Switching a digest on starts the clock at that moment, so the first digest is not a dump of the backlog; switching it off raises what it was holding as one last digest. A flag user value (<code>notification_delivery_scheduled</code>) marks the users the job has to visit, because Nextcloud can find the users holding a given value but not the users holding any value for a key</p>\n<h2 id=\"hashtagservice\">HashtagService</h2>\n<p>Recomputes hashtag trends over 1h/12h/1d/3d/10d windows and searches hashtags</p>\n<h2 id=\"interestservice-interestscorer-interestfeedservice\">InterestService / InterestScorer / InterestFeedService</h2>\n<p>For you. <code>InterestScorer</code> is the arithmetic and nothing else — no database, no clock, every number handed to it: how long a post takes to read at an ordinary pace (1.2 s, 35 ms a character, 1.5 s a picture, at most 20 s), a look judged against the reader&#39;s own usual ratio of looking to reading time (twice it is +1, at it +0.3, less is nothing, a skip −0.2), a signal shared evenly among a post&#39;s hashtags (none past fifteen), a half-life decay worked out on read, and the list: pinned tags at the rank they were pinned to, everything else — manual and followed tags floored at the listing threshold, learned tags above it — filling the free ranks by score up to the cap. <code>InterestService</code> is whose interests they are: it reads the posts a signal names <strong>as the viewer</strong>, through the timelines&#39; visibility filter (<code>StreamRequest::getVisibleByNids()</code>), so a client can neither teach a tag no post carried nor learn the hashtags of a post it may not read; it learns from a favourite, boost and bookmark in <code>ActionService</code> and a reply in <code>PostService</code>, so a Mastodon app&#39;s actions count too; it never throws from those hooks; each (post, kind) counts once a day through a distributed-cache key. No signal is stored — each is folded into its tags&#39; scores as it arrives. <code>InterestFeedService</code> ranks: candidates are one query (<code>StreamRequest::interestCandidates()</code>) over <code>social_stream_tag</code> bounded by the nid of the window&#39;s start, the reader&#39;s tags, the viewer filter, silences, hides and languages; each is scored <code>relevance × 2^(−age/1 day)</code> with relevance the sum of the three best matching rank weights (<code>1/(1+0.15·rank)</code>) plus −0.5 per tag the reader turned away from; then spread — no author twice in any twenty, no hashtag more than eight, the hashtag limit giving way first — with every tenth slot a post carrying a tag that often travels with the reader&#39;s own. The ranking is kept an hour in the distributed cache, under a key that names its kind (<code>feed/{media}/{md5(viewer)}</code>), and paged by the last post&#39;s nid <strong>Media rankings.</strong> <code>page()</code>/<code>rank()</code> take a kind — <code>photos</code>, <code>videos</code>, or <code>media</code> for Mastodon&#39;s <code>only_media</code> — which <code>interestCandidates()</code> turns into the Photos and Videos timelines&#39; own filters (<code>limitToMediaType(&#39;image&#39;)</code>, <code>limitToVideo()</code>, <code>limitToMedia()</code>, all on <code>media_kind</code>); such a ranking looks back <code>MEDIA_WINDOW_FACTOR</code> (2) times the window, and hides are kept that long too. Short of <code>POPULAR_FILL</code> (40) posts it is topped up from <code>TrendService::trendingStatuses()</code> in the same kind — the reader&#39;s own, hidden and already ranked posts left out — each with reason <code>popular</code>. In a <code>shorts</code> signal (or <code>reels</code>, what older bundles send) a dwell is watch time: <code>InterestScorer::classifyWatch()</code> weighs it against the video&#39;s running time (<code>expectedWatchMs()</code>, capped at 30 s) rather than <code>expectedDwellMs()</code>, and leaves the reading pace alone. <code>InterestService::pageState()</code> also says whether a reading pace has been written (<code>profile</code>), which is when the Shorts stack opens on For you.</p>\n<h2 id=\"for-you-candidate-discovery-f1\">For You candidate discovery (F1)</h2>\n<p>the automatic timeline retrieves candidates from the existing stream through <code>StreamRequest::recommendationCandidatesByTerms()</code>: it uses <code>social_search_term</code> when its backfill is complete, otherwise a capped public scan. Candidates are filtered through the same public-recipient, visibility, hidden-actor and duplicate rules as timelines, then hydrated again through viewer-aware reads. Own posts, age, configured languages and internal exclusions are applied before features are emitted. When a reader has no learned topics, the bounded public discovery sample fills otherwise unused topic-retrieval capacity so a cold-start page can still include uncaptioned media. <code>RecommendationFeatureExtractor</code> uses bounded local text and hashtag matching plus stored media/language facts; it intentionally omits sensitive topics and does not build a behavioural profile. Automatic retrieval can ask <code>RemoteFetchQueue::fillPosts()</code> for rate-limited ActivityPub and Bluesky fills; the HTTP request never contacts either protocol.</p>\n<h2 id=\"for-you-ranking-baseline-f2\">For You ranking baseline (F2)</h2>\n<p><code>RecommendationRanker</code> applies one finite, clipped and versioned score to a bounded union of candidates. Automatically learned hashtag relevance and recency from <code>InterestFeedService</code> become the <code>automatic_interest</code> feature; content classification, freshness, follows, explicit post feedback and separately consented behavioral signals contribute to the same score. Reader topic choices are not exposed by the API and do not configure the feed. Coefficients are hypotheses, not validated engagement weights. <code>RecommendationFreshness</code> adds local content-aware decay shared by ActivityPub and ATProto posts. All candidates pass public visibility, language, duplicate and hidden-actor checks. <code>RecommendationReRanker</code> applies a rising concentration cost after three placements of a topic and a two-post story cap within a page, plus author diversity, over a bounded look-ahead. A post yields to topic saturation only when all its classified topics have reached the cap, so a saturated broad parent does not hide a candidate with an unsaturated specific topic. The story cap admits one additional post from a story only when no diverse candidate remains, so small federated candidate pools do not leave the page sparse. It deduplicates canonical keys. The timeline snapshots one final order for an hour; cursors are HMAC signed and bound to the viewer, mode, media kind, profile revision and reset generation. Each page rechecks current visibility and boundedly fills from later snapshot IDs when posts have become unavailable.</p>\n<ul>\n<li>The established hashtag feed uses the same transient story terms while spreading its snapshot. It prefers at most two posts from one story whenever another identifiable story remains, including among related-tag exploration posts, then relaxes that preference by one post only when the alternatives run out. Story terms are never persisted with the cached NID order.</li>\n</ul>\n<h2 id=\"for-you-recommendations-explicit-feedback-f3\">For You recommendations explicit feedback (F3)</h2>\n<p><code>RecommendationFeedbackService</code> accepts only a post the signed-in viewer can currently read. Similarity clusters, authors and formats are derived server-side; clients cannot submit a topic ID or topic-specific action. The separate feedback table stores owner-scoped, event-idempotent actions, caps active scopes at 50, and permits exact Undo for ten minutes. <code>HIDE_POST</code> filters both newly generated candidates and later pages of an existing snapshot; similarity/author/format feedback affects new rankings without moving posts already delivered. Reset and account deletion purge this state, and the endpoints require <code>write:statuses</code> with user rate limits. Legacy topic feedback rows are inert.</p>\n<h2 id=\"for-you-recommendations-behavioural-learning-f4\">For You recommendations behavioural learning (F4)</h2>\n<p><code>RecommendationSignalService</code> accepts bounded, idempotent events only when the account&#39;s separate learning consent is <code>on</code>; pause and off both reject writes. Browser impressions require at least 750 ms of visible time, dwell is capped, video watch ratio is recorded separately from card visibility, and backgrounded tabs stop accumulating time. Likes, saves, follows, profile visits, media opens and reversals update owner-scoped fast/slow topic, author and format aggregates; replies count only as engagement and never as inferred stance. Generation checks invalidate late events after consent transitions and resets. Ranked sessions use learned scores only for consenting owners, and chronological feeds are unchanged. The three recommendation tables contain no post text or raw actor identifiers; reset and account deletion clear their aggregates and event ledger.</p>\n<h2 id=\"for-you-recommendations-discovery-health-and-operational-limits-f5\">For You recommendations discovery health and operational limits (F5)</h2>\n<p><code>PostDiscoveryService</code> records bounded provider call, request, failure, 429, post-seen/stored and duration counters in hourly instance-wide buckets. ActivityPub requests are batched across the configured directory peers, use the shared host circuit breaker and <code>Retry-After</code>, and hydrate each origin post under a short per-request and total budget. All optional remote post-discovery paths reserve from one shared 120-request-per-hour ceiling before making network requests. Each request claims a unique expiring slot in <code>social_durable_cache</code>, so the cap remains shared across processes even when Nextcloud has only local APCu rather than a distributed cache. If the slot store is unavailable or the budget is exhausted, new remote discovery stops while local cached candidates and the legacy timeline remain available. The admin emergency pause is enforced by the shared discovery service and therefore also stops legacy hashtag fills and followed-tag refreshes. Administrators can also pause behavioral learning or force the legacy For You feed. The admin-only health endpoint reports provider state and coverage without query, topic, reader or post identifiers; hourly rows expire after seven days. A metrics-storage failure is logged and never fails discovery.</p>\n<h2 id=\"for-you-recommendations-offline-evaluation-f6\">For You recommendations offline evaluation (F6)</h2>\n<p><code>RecommendationOfflineEvaluator</code> compares legacy hashtag, chronological-following, topic-only, topic-plus-follow, H0 and H0-plus-rerank baselines using synthetic cross-protocol scenarios. It reports NDCG@20, candidate/source coverage, hard-control compliance, topic diversity, duplicate rate, local runtime and profile-cluster uncertainty. Run <code>composer run recommendations:evaluate</code>; see <a href=\"/docs/evaluation\">For You offline evaluation</a>. Fixture labels are explicitly single-author synthetic judgments and do not validate serving weights.</p>\n<h2 id=\"for-you-controls-and-topic-catalog\">For You controls and topic catalog</h2>\n<p><code>RecommendationTopicCatalog</code> is an internal content-classification vocabulary, not a user-facing setup checklist or API. Deterministic post classification maps known narrower matches to their parents, and sensitive entries are excluded. The web presents one feed and one automatically learned profile; legacy topic preferences are not exposed or writable through the API. Learned hashtag interests provide an automatic starting profile, while separately consented activity learning can add more signals.</p>\n<h2 id=\"for-you-explanations-in-the-timeline-store\">For You explanations in the timeline store</h2>\n<p>The timeline response carries a viewer-specific explanation for each recommended post; a normal status refresh can omit that field. <code>indexStatus()</code> keeps the existing explanation when it indexes such a response, so count and reaction refreshes do not make the “why this post” label disappear.</p>\n<h2 id=\"streamactionservice\">StreamActionService</h2>\n<p>Writes the per-viewer flags in <code>social_stream_act</code></p>\n<h2 id=\"pinservice\">PinService</h2>\n<p>Pinned posts: the own posts an account keeps at the top of its profile. A pin is a row in <code>social_action</code> (type <code>Pin</code>), so there is no schema change, and it is never federated as an activity of its own — remote servers read pins from the actor&#39;s <code>featured</code> collection. Only a public or unlisted post can be pinned (<code>pin()</code> refuses the rest with <code>InvalidActionException</code>), and pins are read back through the visibility filter like any other status, so a post that stopped being readable stops being served: both readers of this collection — the <code>featured</code> route and <code>?pinned=true</code> on the account statuses route — are public pages, and reading these unfiltered served a pinned followers-only post in full to the anonymous internet</p>\n<h2 id=\"postdecorationservice\">PostDecorationService</h2>\n<p>What a client is shown on a post that is not part of the stored post: its link preview, its place, its reaction bar (with <code>me</code> for the reader) and the people named in its pictures. Every route that serves posts to a client goes through <code>decorate()</code> — the timelines and For you (<code>StreamService</code>), a single status and the statuses a status route answers with, a thread, a list, a place, a collection, memories, the trends and discover, a Bluesky feed, the photos somebody is in, a portfolio, the archive, the videos to continue and an annual report&#39;s top posts — so a post looks the same wherever it is opened. One query per kind for the whole list. It depends on nothing that depends on <code>StreamService</code> or <code>MediaTagService</code>, which both call it. <code>DELETE /api/v1/statuses/{nid}</code> alone answers an undressed status: a redraft takes the text and media.</p>\n<h2 id=\"linkpreviewservice\">LinkPreviewService</h2>\n<p>Builds the link-preview card of a post from what the linked page says about itself (OpenGraph, falling back to the HTML title/description), fetched once per post from the inbound queue through <code>CurlService</code>. Cards are never federated, so every instance reads the page itself</p>\n<h2 id=\"markerservice\">MarkerService</h2>\n<p>How far through a timeline someone has read (Mastodon&#39;s markers), stored as a per-user config value rather than a table; the unread badge is the only thing the app itself needs one for. <code>markUnread()</code> keeps positions behind the marker counting as unread (user value <code>markers_unread</code>) until the reader next sets that marker: what accepting a request releases sat behind a marker the reader moved while it was hidden</p>\n<h2 id=\"notificationinboxservice\">NotificationInboxService</h2>\n<p>The notification list once the policy has had its say: the page (<code>timeline()</code>, the one query the grouped list, the requests inbox, the unread count and the digest all read), what is held (<code>held()</code>, nothing read at all for an account whose policy holds nothing), the requests inbox (<code>requests()</code>), accepting a sender (<code>release()</code>: records the decision and marks what they sent while held unread, raising nothing), and the unread count (<code>unreadCount()</code>: the database&#39;s count when the policy holds nothing, else the page past the marker less what is held, plus what was released behind the marker). Apart from <code>NotificationService</code> because the digest needs it and the digest is a dependency of that service</p>\n<h2 id=\"searchservice\">SearchService</h2>\n<p>Backing searches for accounts, hashtags, URIs and status content; <code>searchStreamContent()</code> backs the client API search, the local API and the unified search provider. Each search takes an optional row limit, for a caller that pages; without one it returns whatever the query returns. <code>searchUri()</code> and <code>searchAccounts()</code> ask other servers (WebFinger, Bluesky&#39;s typeahead) only when the caller passes Mastodon&#39;s <code>resolve</code>; without it they answer from the cache and queue an unknown address or whole <code>user@host</code> for <code>Cron\\ResolveActor</code>. The unified search provider and the Pixelfed mention autocomplete never pass it, since both are asked once per keystroke</p>\n<ul>\n<li>Every timeline query filters actors the viewer has blocked or muted (and actors who blocked the viewer) through one anti-join, <code>SocialLimitsQueryBuilder::filterHiddenActors()</code> — blocks apply everywhere, mutes to aggregated timelines and threads but not to a muted account&#39;s own profile or a directly opened post, and muted-with-notifications to the notification stream.</li>\n</ul>\n","toc":[{"id":"streamservice","text":"StreamService","level":2},{"id":"postservice","text":"PostService","level":2},{"id":"postreviewservice","text":"PostReviewService","level":2},{"id":"statusassemblyservice","text":"StatusAssemblyService","level":2},{"id":"scheduledstatusservice","text":"ScheduledStatusService","level":2},{"id":"pollservice","text":"PollService","level":2},{"id":"followservice","text":"FollowService","level":2},{"id":"likeservice","text":"LikeService","level":2},{"id":"streampruneservice","text":"StreamPruneService","level":2},{"id":"remotefetchqueue","text":"RemoteFetchQueue","level":2},{"id":"cacheactorsweepservice","text":"CacheActorSweepService","level":2},{"id":"boostservice","text":"BoostService","level":2},{"id":"actionservice","text":"ActionService","level":2},{"id":"translationservice","text":"TranslationService","level":2},{"id":"notificationgroupservice","text":"NotificationGroupService","level":2},{"id":"notificationpolicyservice","text":"NotificationPolicyService","level":2},{"id":"countsservice","text":"CountsService","level":2},{"id":"aicontentservice","text":"AiContentService","level":2},{"id":"notificationdeliveryservice","text":"NotificationDeliveryService","level":2},{"id":"hashtagservice","text":"HashtagService","level":2},{"id":"interestservice-interestscorer-interestfeedservice","text":"InterestService / InterestScorer / InterestFeedService","level":2},{"id":"for-you-candidate-discovery-f1","text":"For You candidate discovery (F1)","level":2},{"id":"for-you-ranking-baseline-f2","text":"For You ranking baseline (F2)","level":2},{"id":"for-you-recommendations-explicit-feedback-f3","text":"For You recommendations explicit feedback (F3)","level":2},{"id":"for-you-recommendations-behavioural-learning-f4","text":"For You recommendations behavioural learning (F4)","level":2},{"id":"for-you-recommendations-discovery-health-and-operational-limits-f5","text":"For You recommendations discovery health and operational limits (F5)","level":2},{"id":"for-you-recommendations-offline-evaluation-f6","text":"For You recommendations offline evaluation (F6)","level":2},{"id":"for-you-controls-and-topic-catalog","text":"For You controls and topic catalog","level":2},{"id":"for-you-explanations-in-the-timeline-store","text":"For You explanations in the timeline store","level":2},{"id":"streamactionservice","text":"StreamActionService","level":2},{"id":"pinservice","text":"PinService","level":2},{"id":"postdecorationservice","text":"PostDecorationService","level":2},{"id":"linkpreviewservice","text":"LinkPreviewService","level":2},{"id":"markerservice","text":"MarkerService","level":2},{"id":"notificationinboxservice","text":"NotificationInboxService","level":2},{"id":"searchservice","text":"SearchService","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"content-and-timelines","manual":false,"prev":{"path":"/docs/architecture-account-and-identity","title":"Account & Identity"},"next":{"path":"/docs/architecture-federation","title":"Federation"},"parent":"architecture-key-services"},{"slug":"architecture-federation","path":"/docs/architecture-federation","title":"Federation","description":"Wraps items in Create/Update/Delete activities, LD-signs them, resolves target inboxes, and drives the delivery queue. A reply whose parent exists only on Bluesky keeps its native…","group":"architecture","html":"<h2 id=\"activityservice\">ActivityService</h2>\n<p>Wraps items in Create/Update/Delete activities, LD-signs them, resolves target inboxes, and drives the delivery queue. A reply whose parent exists only on Bluesky keeps its native <code>inReplyTo</code> on the stored stream for ATProto, while the ActivityPub copy is standalone, links the Bluesky post, and drops the synthetic Bluesky actor and its delivery path. Create, Update and rebuilt held deliveries use the same adaptation. <code>request()</code> sends the single highest-priority entry synchronously and kicks off an async request for the rest</p>\n<h2 id=\"importservice\">ImportService</h2>\n<p>Parses incoming ActivityPub JSON into typed model objects (<code>AP::getItemFromData()</code>) and dispatches to the matching handler in <code>lib/Interfaces/</code></p>\n<h2 id=\"signatureservice\">SignatureService</h2>\n<p>RSA-2048 key generation, HTTP Signature verification (checking <code>date</code> freshness, then the body against <code>Content-Length</code> if the sender sent one and against <code>Digest</code>/<code>Content-Digest</code>, before the signature itself) and RsaSignature2017 Linked Data signatures. The signing itself is delegated to <code>HttpSignatureService</code>. Fetching a signing key this instance does not already hold is bounded — <code>UNKNOWN_KEY_CONNECT_TIMEOUT</code> (5 s) for DNS, TCP and TLS within <code>UNKNOWN_KEY_TIMEOUT</code> (10 s) overall, what Mastodon allows a peer of its own — and a fetch that failed is remembered so a burst naming the same unknown key costs one fetch and not one each: 300 s (<code>KEY_FAILURE_TTL</code>) when the peer answered and the answer was not a usable actor, 30 s (<code>KEY_UNREACHABLE_TTL</code>) when it never answered, because that says the peer was having a bad minute rather than anything about the key</p>\n<h2 id=\"httpsignatureservice\">HttpSignatureService</h2>\n<p>The one place an outbound HTTP signature is produced. Both entry points take the URL the request will actually be sent to and the body it will actually carry, and answer with the headers to send: <code>(request-target)</code> is the path and query of that very URL and <code>host</code> its authority, so the signature and the request cannot drift apart. A delivery is signed by its own author over <code>(request-target) content-length date host digest</code>; an ActivityPub GET is signed over <code>(request-target) host date</code> by <code>signFetch()</code>, as the instance&#39;s own <code>Application</code> actor. Never as a person: the owner of a signing key is dereferenced by every peer that checks it, so a borrowed account would appear in every peer&#39;s logs as this instance&#39;s reader and a block or suspension of it anywhere would stop every signed fetch from here — and an instance whose users have no Aloha Social accounts yet would have nobody to borrow. A key that cannot sign raises rather than sending an empty signature, and an instance that cannot produce one at all fetches unsigned, which is what the request was until now</p>\n<h2 id=\"instanceactorservice\">InstanceActorService</h2>\n<p>The instance&#39;s own actor and its key pair, served at <code>/actor</code>, discoverable as <code>acct:&lt;host&gt;@&lt;host&gt;</code>. The key pair lives in two app config values rather than in <code>oc_social_actor</code>: a row there is a local account — listed by the directory, resolved by webfinger, offered to the client API, counted in the statistics, handed a followers collection and an outbox — and the instance actor is none of those, so every one of those places would have needed a clause excluding it. The private half is sealed with the instance secret the way an actor&#39;s is, so a config dump alone is not enough to sign as this server. Generated on first use; when two requests race, both adopt whichever pair was written last, because that is the one the actor document publishes</p>\n<h2 id=\"linkifyservice\">LinkifyService</h2>\n<p>The plain text somebody types, turned into the HTML every other implementation publishes: <code>&lt;p&gt;</code> paragraphs, <code>&lt;br /&gt;</code>, and links for URLs, mentions (<code>u-url mention</code>) and hashtags (<code>mention hashtag</code>, <code>rel=&quot;tag&quot;</code>). Content used to leave as <code>nl2br(htmlentities(…))</code>, and peers render <code>content</code> without looking for anything to linkify, so every link, mention and hashtag written here arrived everywhere as dead text. The text is escaped first and markup is only ever built around the escaped pieces — nothing is un-escaped and no markup is assembled by interpolating input. The entities are found once, and that same list is what <code>PostService</code> addresses the post from and what <code>StreamService</code> builds the <code>tag</code> array out of, so the markup can never link somebody the <code>tag</code> array does not name — which is the list a receiving instance checks a mention against before it notifies anybody</p>\n<h2 id=\"forwardservice\">ForwardService</h2>\n<p>Inbox forwarding (ActivityPub §7.1.2); see below</p>\n<h2 id=\"followgraphservice\">FollowGraphService</h2>\n<p>&quot;Whom to follow&quot;, asked of the fediverse instead of this database. <code>SuggestionService</code> answers the same question from <code>social_follow</code>, which on a small instance is nearly empty because the only follows it holds are the ones that happened here; this fetches the <code>following</code> collection of each account the viewer follows (at most <code>SAMPLE</code>, one page each, inside a <code>BUDGET</code>) and counts the names in them. A suggestion carries <code>followed_by</code> and a few of the handles behind it, because a count somebody can check beats a ranking they cannot. Exclusions are <code>SuggestionService::excludedPrims()</code> rather than a second copy — one list, or a blocked account eventually gets recommended. Below <code>MINIMUM_FOLLOWS</code> it walks nothing and answers <code>needs</code>, which is what the page shows a new account instead of an empty list; <code>probe()</code> answers that without touching the network, and is what the page asks on open</p>\n<h2 id=\"profilelinkverifier\">ProfileLinkVerifier</h2>\n<p>The tick next to a profile link: the page a field names is fetched (through the guarded client, http(s) only, no local hosts unless allowed, <code>MAX_SCAN</code> of it read) and has to link back to the actor id or profile URL with <code>rel=&quot;me&quot;</code>. Verdicts live in the cached actor&#39;s details (<code>fields_verified</code> keyed by the field value, <code>fields_checked</code> for when), which <code>Person::exportAsLocal()</code> reads as <code>verified_at</code>; a verdict stands <code>RECHECK_SECONDS</code> (a day) before the page is asked again. Local accounts are checked by <code>Cron\\Cache</code> (<code>verifyLocalActors()</code>, <code>LOCAL_BATCH</code> per pass, walking only the accounts whose fields contain <code>http</code> a page at a time from the <code>profile_link_cursor</code> the last pass left; the deleted-account reaper likewise asks for <code>getDeletedBefore()</code> rows only, never the whole table), remote ones with their details refresh in <code>CacheActorService::manageDetailsRemoteActors()</code></p>\n<h2 id=\"featuredcollection-refresh\">FeaturedCollection::refresh()</h2>\n<p>Reads a remote actor&#39;s <code>featured</code> collection (the first page of a paged one) with its details refresh and makes the stored pins match: known posts are pinned, an embedded Note by the actor is stored first when this instance does not hold it, pins no longer in the collection come down. Before this an <code>Add</code>/<code>Remove</code> was applied when it arrived and nothing asked for the pins an account already had</p>\n<h2 id=\"pinservice\">PinService</h2>\n<p>Pinned posts, and the <code>Add</code>/<code>Remove</code> that tell the fediverse about one. A pin is not an activity of its own on the wire: what travels names the actor&#39;s <code>featured</code> collection as its <code>target</code>. Without that pair a pin was visible only to a peer that re-read the collection, which nothing prompts it to do — so a pin appeared elsewhere late or never, and an unpin never at all. The row is stored first and a failure to federate is logged rather than raised: the profile here is right either way, and a pin is not worth failing a request over</p>\n<h2 id=\"reportforwardservice\">ReportForwardService</h2>\n<p>Passes a local report on to the instance that hosts the reported account, as a <code>Flag</code>. Anonymised: the activity names this instance&#39;s <code>Application</code> actor and is signed with its key, so the receiving moderators see the server and not the person who filed it — which is the point, since that person is reporting an account on the instance being told. Delivered inline rather than through <code>social_req_queue</code>, because a queued delivery is signed by <code>HttpSignatureService::signDelivery()</code> from <code>oc_social_actor</code> by the queue row&#39;s author, and the instance actor is deliberately not a row there. One report is one POST with a 3-second timeout; a failure costs the forward and nothing else, and <code>social_report.forwarded</code> is set only when the remote inbox accepted it</p>\n<h2 id=\"domainpurgeservice\">DomainPurgeService</h2>\n<p>Removes what a blocked instance already sent: its cached accounts, their posts, the follows in both directions, the notifications they caused and the deliveries still queued towards them. A block on its own only ever stopped the <em>next</em> request. Bounded (50 accounts per step, every underlying delete already batched, no transaction held open), idempotent (each step asks what of the domain is still stored rather than counting off an offset, so an interrupted purge resumes and a repeat is free) and terminating (a step that deletes nothing stops rather than spins). Reuses <code>ModerationService::purgeActor()</code>, so a domain purge detaches exactly what a suspension detaches. What it deletes is gone — unblocking the domain lets the instance reach us again but restores nothing. Matches the exact host, not subdomains, even though <code>isListed()</code> widens a block to cover them: refusing traffic from one instance too many is undone by editing the list, and deleting one is not</p>\n<h2 id=\"inboxlimiter\">InboxLimiter</h2>\n<p>Per-minute rate limits on the inbox routes, one spent before the signature is checked and one after, and the ceiling on how big a delivery may be (<code>readBody()</code>, 1 MiB); see <a href=\"/docs/architecture-security#security\">Security</a></p>\n<h2 id=\"requestqueueservice\">RequestQueueService</h2>\n<p>Manages <code>social_req_queue</code>: creates entries, hands out the priority entry, and re-offers standby entries once they are due. The retry schedule is <code>Backoff::outbound()</code> — Mastodon&#39;s <code>tries^4 + 15</code> seconds — and it and the <code>MAX_TRIES</code> (16) give-up are applied by the query alone (<code>CoreRequestBuilder::limitToQueueDue()</code>, built by <code>Backoff::limitToDue()</code>); <code>RequestQueueService::retryDelay()</code> reads the same object, so the PHP side and the SQL cannot drift apart. Exhausted rows are marked <code>STATUS_ABANDONED</code> (8) before the 200-row window is read — filtered in PHP afterwards, the rows of one dead instance permanently occupied that window and starved every other delivery. A delivered row is kept as <code>STATUS_SUCCESS</code> and an exhausted one as abandoned for <code>RETENTION_SECONDS</code> (seven days), then purged by <code>purgeFinished()</code> on every cron pass and by <code>occ social:stream:prune</code>. A delivered row drops its <code>activity</code> as it is marked (<code>setAsSuccess()</code>): nothing sends it again, and one copy of the signed document per inbox for a week was the bulk of the table. An abandoned row keeps it, because <code>social:queue:retry</code> hands it back to the queue; they used to be deleted the moment they finished, which made the queue a to-do list that could never say where a post had got to. Every row carries <code>object_id_prim</code>, the md5 of the id of the object inside the activity, read off the JSON in <code>objectIdPrimOf()</code> so that forwarded third-party bytes are keyed the same way; <code>DeliveryService</code> reads the rows of one object back for the author (<code>GET /api/v1/statuses/{nid}/delivery</code>). A row whose delivery fails in a way <code>ActivityService</code> does not handle itself — a corrupt signing key, the database going away — is logged and handed back to standby by the caller (<code>Cron\\Queue</code> and <code>QueueController</code>), because it was marked <code>running</code> before the attempt: left that way it was never retried, never counted against <code>MAX_TRIES</code>, and took the rest of the 200-row batch with it</p>\n<h2 id=\"streamqueueservice\">StreamQueueService</h2>\n<p>Manages <code>social_stream_queue</code>, the inbound side. Two queue types are implemented. <code>Cache</code>: for each Note a received stream references (a reply parent, a boosted post), it fetches that Note, caches its author, stores it, and embeds it in the referencing stream&#39;s cache — anything that is not a Note, or whose id does not match the URL it was fetched from, is rejected. <code>LinkPreview</code>: reads the page a post links to, once, and stores the card. Any other type is dropped. This side has the same 200-row batch cap and the same in-query backoff (<code>Backoff::inbound()</code>, <code>floor(tries^4 / 3)</code> seconds), give-up (<code>MAX_TRIES</code>, 10 here) and delete-on-success as the outbound queue; it used to keep one permanent row per activity ever cached and was never pruned, and it consults the same host circuit breaker (<code>HostBreaker</code>) before it fetches anything</p>\n<h2 id=\"curlservice\">CurlService</h2>\n<p>Outbound HTTP for ActivityPub fetches, WebFinger and host-meta lookups, and the async self-call that drains a delivery token. The transport is the server&#39;s own client (<code>OCP\\Http\\Client\\IClientService</code>), and a caller hands it a method, a URL and at most four options — <code>headers</code>, <code>body</code>, <code>timeout</code>, <code>json_headers</code> — which is what the client itself takes; nothing in between describes an HTTP request a second time. So the CA bundle and the proxy configuration come from the server, and what stays here is federation-specific: the local-address guard and the address pin on every hop (<code>pinReachable()</code>), the protocol fallback (an instance reachable over <code>http</code> only, via <code>doRequestOverUrls()</code>), the signed fetch and its one unsigned retry, the download size ceiling, and the mapping onto the app&#39;s request exceptions. A URL somebody else wrote — an ActivityPub id, a cached-media link, a previewed page — is requested exactly as it is written rather than taken apart and reassembled, which is also what makes the path a signature covers the path the request is sent to. Every outbound request the app makes goes through it — the Bluesky PDS, handle, video-service, setup-check, GIF-pack and block-list fetches included — so the guard, the pin and the access list are applied in one place; <code>federation =&gt; false</code> is for the one URL the app ships itself (the GIF pack source), <code>max_redirects =&gt; 0</code> for a document that must be read where it is (a handle&#39;s <code>atproto-did</code>)</p>\n<h2 id=\"fediverseservice\">FediverseService</h2>\n<p>Instance-level access control; its CSV import batches one validated list write, then records an audit event and queues the normal purge per new domain. Import is explicitly operator-triggered and only applies in block-list mode; see <a href=\"/docs/admin-moderation-and-federation#moderation-and-federation\">Admin.md</a></p>\n<h2 id=\"instanceservice\">InstanceService</h2>\n<p>Builds and returns the local instance&#39;s NodeInfo-style metadata</p>\n","toc":[{"id":"activityservice","text":"ActivityService","level":2},{"id":"importservice","text":"ImportService","level":2},{"id":"signatureservice","text":"SignatureService","level":2},{"id":"httpsignatureservice","text":"HttpSignatureService","level":2},{"id":"instanceactorservice","text":"InstanceActorService","level":2},{"id":"linkifyservice","text":"LinkifyService","level":2},{"id":"forwardservice","text":"ForwardService","level":2},{"id":"followgraphservice","text":"FollowGraphService","level":2},{"id":"profilelinkverifier","text":"ProfileLinkVerifier","level":2},{"id":"featuredcollection-refresh","text":"FeaturedCollection::refresh()","level":2},{"id":"pinservice","text":"PinService","level":2},{"id":"reportforwardservice","text":"ReportForwardService","level":2},{"id":"domainpurgeservice","text":"DomainPurgeService","level":2},{"id":"inboxlimiter","text":"InboxLimiter","level":2},{"id":"requestqueueservice","text":"RequestQueueService","level":2},{"id":"streamqueueservice","text":"StreamQueueService","level":2},{"id":"curlservice","text":"CurlService","level":2},{"id":"fediverseservice","text":"FediverseService","level":2},{"id":"instanceservice","text":"InstanceService","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"federation","manual":false,"prev":{"path":"/docs/architecture-content-and-timelines","title":"Content & Timelines"},"next":{"path":"/docs/architecture-media","title":"Media"},"parent":"architecture-key-services"},{"slug":"architecture-media","path":"/docs/architecture-media","title":"Media","description":"Owns the cached document lifecycle: caching a remote document by id, serving originals and resized copies out of app storage, and caching the local actor's avatar and header. Serving…","group":"architecture","html":"<h2 id=\"documentservice\">DocumentService</h2>\n<p>Owns the cached document lifecycle: caching a remote document by id, serving originals and resized copies out of app storage, and caching the local actor&#39;s avatar and header. Serving applies a viewer bound: a cached attachment is handed to a logged-in user only if it hangs off a post they may read or is their own upload, and the unauthenticated <code>/media/{uuid}</code> route only for a row marked public</p>\n<h2 id=\"cachedocumentservice\">CacheDocumentService</h2>\n<p>Writes uploads, remote downloads and temp files into app storage, filters MIME types against an allow-list, and reads content back out. An image and a video take deliberately different paths: an image is read into a string, because the metadata stripping, the HEIC conversion and the resize all work on one, while a video is streamed to storage a chunk at a time and never held whole — <code>fread()</code> of a two-gigabyte upload is two gigabytes of memory, and PHP&#39;s limit was the only thing that ever stopped it. That split is also why there are two size ceilings (<code>max_size</code>, <code>max_video_size</code>) and why the second is applied again against the <em>sniffed</em> type: the request-time check can only go on what the client declared. An upload is created non-public; it takes the visibility of the post it is attached to when that post is created (<code>StatusApiController::scopeMediaToVisibility()</code>, public for public and unlisted, non-public otherwise), because which post an upload belongs to is only known then</p>\n<h2 id=\"videothumbnailservice\">VideoThumbnailService</h2>\n<p>One frame out of a video, so a timeline of them is not a wall of black rectangles each of which has to be downloaded before it shows anything. ffmpeg where the server has it, skipped silently where it does not (an app that refused uploads without ffmpeg would be worse than one that shows no poster), and <strong>not transcoding</strong>: it decodes one frame and asks ffprobe how long the video runs. The poster becomes the video&#39;s <code>resized_copy</code> — which is what that column means, the small image standing in for the file — and from there the player&#39;s <code>poster</code>, which is what lets a page of videos be scrolled without fetching one. The frame is taken from the bytes as they are written and they are only written once, so a video stored before posters existed (or while the server had no ffmpeg) would never get one: <code>Cron\\VideoPosters</code> is the backfill (<code>VideoPosterBackfill</code>: five videos a run, in nid order from the <code>poster_backfill_cursor</code> app setting, each video once, nothing while the server has no ffmpeg) and <code>occ social:media:posters</code> does all of them at once. Both have to do two things rather than one, because a post keeps its own copy of its attachments. Making the poster changes the <em>document</em>; rewriting the copies the posts carry is what a reader sees</p>\n<h2 id=\"videotranscodeservice-videotranscodingworker-videodeliveryhold\">VideoTranscodeService / VideoTranscodingWorker / VideoDeliveryHold</h2>\n<p>Turning a video uploaded here into H.264 in an MP4, the one format Pixelfed accepts (<code>video/mp4</code> and nothing else) and every browser plays. Local uploads only (<code>getVideosToTranscode()</code> requires a non-empty <code>account</code>, which the upload paths write and a cached remote attachment never has): a peer&#39;s video is that peer&#39;s to encode, and the worker marks one that reaches it anyway as not needed rather than converting it. <code>video_transcode</code> is on by default and a no-op without ffmpeg (<code>isEnabled()</code> is the setting <em>and</em> the binary). What is converted: the types in <code>CONVERTIBLE</code> on their type alone, and a <code>video/mp4</code> whose first video stream ffprobe does not name <code>h264</code> — HEVC, which phones write — including one ffprobe cannot read; an H.264 MP4 is never re-encoded, and without ffprobe an MP4 is left as it is. An upload is probed while its bytes are still on disk (<code>CacheDocumentService::saveMediaFromTemp()</code>), so an H.264 MP4 is written with <code>transcoded = 2</code> and nothing waits for it. The worker writes the converted file, points the row at it (<code>replaceVideo()</code>), rewrites the attachment copy of every local post that carries it (<code>StreamRequest::updateLocalAttachmentCopies()</code>, which finds those posts through <code>social_stream_media</code> by the document&#39;s nid: the copy names the file by its uuid and type, and one left alone 404&#39;d the moment the original was deleted), and deletes the original last. <code>Cron\\Transcode</code> sweeps one video a quarter-hour and reads at most five MP4s&#39; codecs per run; <code>Cron\\TranscodeBeforeDelivery</code> converts the video a new post is waiting on — see <strong>Held for a video</strong> under Outgoing Flow. <code>VideoDeliveryHold</code> decides which posts wait.</p>\n<h2 id=\"storedmediametadataservice\">StoredMediaMetadataService</h2>\n<p><code>occ social:media:strip-metadata</code>: a local video or sound file stored before uploads lost their container metadata is remuxed by <code>VideoTranscodeService::withoutMetadata()</code>, stored under a new uuid (<code>replaceLocalCopy()</code> updates the size and sends a video back to the ladder), the posts carrying it are repointed as the transcoder does and the original is deleted. A document that is a blob in a Bluesky repository or was handed to Bluesky&#39;s video service (<code>AtprotoBlobRequest::hasDocument()</code>, <code>AtprotoVideoRequest::hasDocument()</code>) is left alone, because its CID is the hash of its bytes; so is one whose rewrite is the same bytes or that ffmpeg cannot rewrite.</p>\n<h2 id=\"blurservice\">BlurService</h2>\n<p>Generates a blurhash string from a GD image. The 4×3-component hash is taken from a copy scaled to 32 px on its longest side (<code>SAMPLE_SIZE</code>), not from the resized preview: the encoder holds one PHP array per pixel, and an 800-px preview cost near 200 MB and a second per picture for the same placeholder. Both the picture preview and a video&#39;s poster go through it</p>\n<h2 id=\"gifservice-gifpackservice\">GifService / GifPackService</h2>\n<p>What the composer&#39;s GIF picker offers. Two sources behind one list: the pictures an administrator added here with <code>occ social:gif add</code> (a row in <code>social_gif</code>, the bytes in appdata beside the custom emoji), offered first because somebody put them there on purpose, and then the 881 animated emoji every instance has. The second is the reason Giphy and Tenor were refused and the reason the picker is not simply empty: they are Google&#39;s Noto Animated Emoji, CC BY 4.0, and <strong>only the list ships</strong> — <code>data/noto-animated-emoji.json</code>, 70 KiB, against 642 MiB of pictures at the one size Google publishes. The bytes arrive one at a time, the first time anybody on the instance asks for one, through the instance&#39;s <em>own</em> <code>/gif/{slug}</code>, and stay in appdata from then on. So no search term leaves the instance, no reader&#39;s browser ever talks to a third party, and what an instance ends up storing is what its people actually used. <code>Cron\\GifPack</code> warms the first screenful — the sixty the picker opens on, and no more, because warming all of them would be 440 MiB of appdata on every instance in the world on the chance somebody wants a hedgehog. <code>gif_pack</code> turns the whole thing off and leaves an administrator with their own. <code>/api/v1/gifs</code> is paged for the same reason the warm-up is bounded: a grid of 881 is 881 fetches because somebody opened a menu</p>\n<h2 id=\"announcementservice\">AnnouncementService</h2>\n<p>The instance-wide notices an admin posts. Two reads that are not the same: a client gets the announcements that apply <em>now</em>, each carrying whether that account has dismissed it, and the administration page gets all of them including one that has not started and one that has run out. The window is a predicate of the query, so an announcement starts and stops being served on time on an instance with no working cron — the same rule a timed mute and an expiring filter follow. Dismissal is per account and never hides the announcement: Mastodon keeps serving it and flips <code>read</code>. There is no edit route, because changing a notice under the accounts that have already dismissed it is worse than posting a new one</p>\n<h2 id=\"domainblockservice\">DomainBlockService</h2>\n<p>Per-account blocks of a whole instance, stored as a domain and applied to the host of an account&#39;s actor id. Not <code>FediverseService</code>, which is the admin&#39;s instance-wide access list. Nothing is federated; the timelines enforce it from inside <code>filterHiddenActors()</code>, so a domain block reaches everything a per-account block reaches</p>\n<h2 id=\"accountrelationservice\">AccountRelationService</h2>\n<p>The private note, the endorsement and the mute expiry of one account towards another, and <code>decorate()</code>, which is where <code>FollowService::generateRelationship()</code> fills in <code>domain_blocking</code>, <code>note</code> and a mute that has run out. A timed mute stops applying because the read says so, not because anything ran to delete it</p>\n<h2 id=\"statusrevisionservice\">StatusRevisionService</h2>\n<p>The versions a status has been through. The first edit records the version being replaced as well as the new one, so the first entry of a history is always what was posted</p>\n<h2 id=\"starterpackservice\">StarterPackService</h2>\n<p>Named handfuls of accounts worth following, answering the question <code>SuggestionService</code> structurally cannot: suggestions work off the follow graph, and a new account has none, so the fallback is whoever posted recently — a list of strangers sorted by luck. A pack is a list of <code>user@host</code> handles and nothing else; no table, because the accounts are not this instance&#39;s to own and the handles are the only durable reference to them. The index resolves nobody (a handle costs a WebFinger lookup and an actor fetch) and reads a pack read in by its stored <code>member_count</code>, not its member list. An opened pack is drawn from the actor cache in one lookup and fetches nothing: a handle not held here is <em>reported</em> in <code>unresolved</code> rather than dropped — a pack that quietly shrinks looks like one somebody wrote badly — and queued through <code>RemoteFetchQueue</code> (<code>resolveActors()</code>, <code>resolveAccounts()</code>). <em>Follow all</em> resolves the pack once, fetching what is not held, and follows each account with <code>FollowService::followActor()</code>. An account <code>StarterPackModeration</code> keeps out is neither offered nor followed, and a pack read in whose curator it keeps out is neither listed nor opened. The shipped packs are the official accounts of the projects this app federates with, which is the one editorial line defensible without becoming a directory nobody agreed to be in; the <code>starter_packs</code> app value replaces or extends them, and a configured pack whose slug matches a shipped one replaces it</p>\n<h2 id=\"starterpackmoderation\">StarterPackModeration</h2>\n<p>Which accounts a starter pack may offer: none this instance&#39;s moderation acted on — silenced or suspended here (<code>ModerationRequest::amongAt()</code>, one query a level), on a server the access list blocks or that is silenced, or a Bluesky account blocked here (<code>Atproto\\Moderation\\Blocklist</code>) or limited by Bluesky&#39;s labels. Asked by <code>CollectionPackService</code> when a collection is read, and by <code>StarterPackService</code> when a pack is listed, opened and followed, since a decision may come after the pack was read</p>\n<h2 id=\"collectionpackservice\">CollectionPackService</h2>\n<p>Reads the starter packs other servers publish: Bluesky&#39;s suggested ones through <code>Atproto\\Reader\\SuggestedStarterPacks</code> (<code>origin</code> <code>bluesky</code>, while Bluesky is on and <code>bluesky:suggested</code> is a source; the AppView asked signed out, each pack&#39;s list cut at 50, an account blocked here or limited by Bluesky&#39;s moderation left out), and the collections other servers publish (Mastodon 4.6&#39;s Collections, FEP-7aa9 <code>FeaturedCollection</code>s linked from an actor&#39;s <code>featuredCollections</code>) into <code>social_starter_pack</code>, for <code>StarterPackService</code> to offer as packs with <code>source</code> <code>fediverse</code>. The curators are the <code>starter_pack_sources</code> app value (unset: the curated collections on mastodon.social). A collection is kept only when its curator published it, it is discoverable and not sensitive; a member only when its own server serves a <code>FeatureAuthorization</code> naming it and the collection, which the FEP requires a reader to check, with an actor&#39;s numbered <code>/ap/users/&lt;n&gt;</code> address taken as the same actor as <code>/users/&lt;name&gt;</code>. At most <code>StarterPackService::MAX_HANDLES</code> (50) members a collection are checked, the ones <code>StarterPackModeration</code> admits — an account silenced or suspended here, on a server this instance blocks or silences, or a Bluesky account blocked here or limited by Bluesky is left out, and a curator it keeps out offers no pack. An authorization whose server does not answer (<code>CurlService::retrieveJsonMany()</code> reports it in <code>$failed</code>: no answer, 408, 429, 5xx) is not a refusal: a member it vouched for before stays, and a collection none of whose members could be checked, or whose page could not be read, keeps what was stored. Read once a day by <code>Cron\\StarterPackSources</code> (one run at a time, five minutes at most; what the deadline leaves unread stays as it was) and by <code>occ social:starter-packs:refresh</code>, never on a page; each collection is read and stored on its own, so one that fails does not stop the run, and <code>StarterPacksRequest::save()</code> is an upsert (<code>insertIgnoreConflict</code>) that never throws on a concurrent write or a taken slug. The members not cached yet are queued through <code>RemoteFetchQueue::resolveActors()</code>, so an opened pack draws from the cache. A curator that cannot be reached keeps its packs; a collection a curator no longer lists, or whose source was removed, goes, found in SQL by <code>origin</code> (<code>StarterPacksRequest::staleOf()</code>).</p>\n<h2 id=\"fediversedirectoryservice\">FediverseDirectoryService</h2>\n<p>Looking for somebody to follow when you do not know which server they are on. The app could already resolve a handle you had been given and suggest people out of a follow graph a new account is not part of; neither is how anybody finds anyone. This asks several servers&#39; directories at once, over APIs they serve to strangers without a token — nothing here holds credentials for anyone else&#39;s instance and nothing here can be made to. <strong>It does not aggregate</strong>: no list of people is stored, nothing is indexed, an answer is cached for five minutes so typing is not four requests a keystroke, and the people in it are not this instance&#39;s to hold. What is stored is about servers — the <code>fediverse.info</code> list and each federated peer&#39;s NodeInfo software — written by <code>refresh()</code> from <code>Cron\\Cache</code> into the <code>directory_known</code> app value (not a cache: the cron writes it and a web request reads it, and APCu is not shared between the two), so <code>sources()</code> and the Discover page never wait on a remote host. Four kinds — <code>local</code> (this instance, always first, never a network request), <code>mastodon</code> (<code>/api/v1/directory</code> plus <code>/api/v1/accounts/lookup</code>, which is what Pixelfed and most forks serve too), <code>misskey</code> (<code>users/search</code>) and <code>lemmy</code> (<code>search</code>) — and the kind is configured rather than sniffed, because sniffing is a request before the request for an answer that changes once in a server&#39;s lifetime. Mastodon having no public search is a fact about Mastodon, not an omission here: an exact lookup and one page of the directory is the whole of what it will answer, and the query is applied to that page by this app rather than pretending to be a search. Each source&#39;s outcome is reported with the results, because &quot;nobody by that name&quot; and &quot;that server did not answer&quot; are different answers. Results are <code>DirectoryAccount</code>, deliberately not Mastodon <code>Account</code>: the id in a remote directory&#39;s answer is a row number in somebody else&#39;s database, and giving these the same shape would make that mistake invisible — the handle is the durable reference and the only thing a client acts on. Anybody on a domain this instance will not federate with is dropped from what is offered, which guards a different thing from the fetch guard: that one protects the server being asked, this one keeps the instance from recommending exactly what it refuses to deliver to</p>\n<h2 id=\"peertrendservice\">PeerTrendService</h2>\n<p>What the rest of the fediverse is talking about. <code>HashtagService</code> ranks the tags used on <em>this</em> instance, which on a small server is what the handful of people here posted today and on a new one is nothing; this asks the servers <code>FediverseDirectoryService</code> already keeps the same question, since &quot;which servers do we ask about people&quot; has the same answer as &quot;which servers do we ask about tags&quot;. <strong>Nothing is fetched, ingested or stored</strong> — what comes back is a list of strings, so no post is retrieved and no actor is cached, which is why the route needs no viewer where the people search does. Ranked by <strong>how many servers named a tag</strong> rather than by their counts added together: instances differ in size by four orders of magnitude, so a sum ranks mastodon.social&#39;s opinion as everybody&#39;s, while a count of servers is the model the follow graph already uses and is the one a row can explain. What each kind of server can answer is a fact about its API — <code>mastodon</code> serves <code>/api/v1/trends/tags</code> publicly but has no public tag search, so a search there matches the query against that same trending page; <code>misskey</code> serves both <code>hashtags/trend</code> and <code>hashtags/search</code>; <code>lemmy</code> and the curated directory have no hashtags at all and are reported as <code>unsupported</code> rather than asked. A peer&#39;s answer is held to what a hashtag is here before it is shown, because it is a string this instance is about to display and offer to follow. This instance&#39;s own rejection list is applied to what strangers say: a tag a moderator took off the local trending page has been decided about, and showing it anyway because somebody else&#39;s server likes it would overrule that decision</p>\n<h2 id=\"directoryservice-suggestionservice-trendservice-featuredtagservice\">DirectoryService / SuggestionService / TrendService / FeaturedTagService</h2>\n<p>Discovery. The directory is opt-in through <code>discoverable</code>, applied as a predicate of the deciding query rather than as a filter over rows already read; suggestions are two counted facts (friends of friends, then locally active accounts) rather than a scoring model; trends count from the rows a like, a boost and a link preview already write, so a trend cannot drift from the counts a status reports</p>\n<h2 id=\"bannerservice\">BannerService</h2>\n<p>The banner across the top of a profile. Three routes set one — a picked file, a URL, and <code>header</code> on <code>update_credentials</code> — and all three end in the same work: store the bytes, point the cached actor at them, tell the followers. It is one service so those three cannot drift on the parts that matter, which are the banner being public where an attachment is not, and the <code>Update{Person}</code> that is the only reason anybody else ever sees it. The stored banner&#39;s <code>parent_id</code> is the account, so deleting the account removes it and its files with the rest of the documents hanging off it (<code>ActorCascadeService</code>); <code>Version1000Date20261012507100</code> gave the banners stored before that the account their handle names</p>\n<h2 id=\"avatarservice\">AvatarService</h2>\n<p>The account&#39;s picture, set from an upload, from a file this server holds or from an archive, and removed; every change re-caches the actor&#39;s icon and tells the followers (<code>AccountService::avatarChanged()</code>). Nextcloud numbers the picture&#39;s address (<code>?v=</code>) from its per-process copy of the user&#39;s settings, so the service reloads that copy from the database (<code>IUserConfig::clearCache($userId, true)</code>) before core touches the picture: another process — a web request that drew the initials again after a name change, a cron pass — may have moved the number since this one first read it, and a picture numbered from the stale copy got an address every peer had already seen and never fetched again.</p>\n<h2 id=\"multipartbodyservice\">MultipartBodyService</h2>\n<p>The fields and files of a multipart body PHP left unparsed. PHP fills <code>$_POST</code> and <code>$_FILES</code> for a POST only, and Mastodon clients send <code>update_credentials</code> as a multipart <strong>PATCH</strong> whenever a picture is in it. On PHP 8.4 and later the body goes to <code>request_parse_body()</code>, which has to run before anything reads <code>php://input</code> (afterwards it finds an empty body and says nothing); PHP 8.3 has no such function, so there the service parses the body itself, writes each file to a temporary file, and remembers those paths. <code>isUpload()</code> is what <code>AvatarService</code> asks instead of <code>is_uploaded_file()</code>, so a picture from that fallback is accepted and a path the request did not upload is still refused. A body with content that parses to nothing is an error, never an empty update.</p>\n<h2 id=\"serving-media\">Serving media</h2>\n<p> <code>/media/{uuid}</code> answers byte ranges (<code>RangedFileResponse</code>). Every route that serves a stored file — that one, <code>/document/get</code>, <code>/document/public</code> and their <code>resized</code> variants, and the cached avatar route — goes through <code>RangedFileResponse::guardStoredFile()</code>: <code>nosniff</code> always, and anything that is not a picture, a video or a sound (text, Markdown, CSV, PDF, zip, office files) is a <code>Content-Disposition: attachment</code> download under <code>Content-Security-Policy: sandbox</code>, because it is somebody else&#39;s bytes on this instance&#39;s origin. Remote attachments are stored <code>public = 0</code> whatever the visibility of their post — <code>Document::import()</code> never sets the flag, and only <code>StatusAssemblyService::scopeMediaToVisibility()</code> does, for local posts — so <code>/document/public</code> serves no remote attachment.\n<code>FileDisplayResponse</code>, which it used to use, sends the whole file and says\nnothing about ranges — fine for a picture and wrong for anything with a timeline\nin it: a browser cannot seek a video it can only receive from the beginning, so\nthe scrub bar does nothing, and asking for the duration alone costs the whole\nfile. On a page of twenty videos that was twenty full downloads before anybody\nhad pressed play. The rules are RFC 9110&#39;s, and an unparseable range is answered\nwith the whole file rather than refused, because that is always correct.</p>\n<h2 id=\"posting-a-picture-that-is-already-in-nextcloud\">Posting a picture that is already in Nextcloud</h2>\n<p> <code>MediaApiController::mediaFromFile()</code>\n(<code>POST /api/v1/media/from-file</code>) attaches a file out of the user&#39;s own storage,\nso the one thing this app should never ask of the person running it — download\nyour own photo, then upload it back — is not required. The path is resolved\nthrough <code>IRootFolder::getUserFolder()</code> and checked against that folder again\nafterwards: the route names a file and returns its contents, which is the shape\na mistake here would be exploited in, so the boundary is stated twice. It is\na Nextcloud-session route: <code>requireWebSession()</code> refuses a bearer token with a\n403 whatever its scopes, so only the Nextcloud session reaches it — the web\napp&#39;s, CSRF token and all, or a client&#39;s Nextcloud app password with\n<code>OCS-APIRequest: true</code>. A client allowed to upload media was never allowed to\nread the user&#39;s files; the rule for every such route is in API.md, &quot;Which\ncredentials a route takes&quot;.</p>\n<p>The bytes are <strong>copied, not referenced</strong>. A post keeps the picture it was\npublished with, so moving, renaming or deleting the original cannot empty a post\nthat has already federated, and the attachment can take the post&#39;s visibility\nthe way an upload does. The copy goes through a temp file into\n<code>saveFromTempToCache()</code>, which is the same code an upload takes — so the MIME\nallow-list, the size ceiling, the resizing and the blurhash cannot drift between\nthe two ways a picture gets in. <code>MediaApiController::storeAttachment()</code> is the shared\nhalf that guarantees it.</p>\n<p>Note what this means for where the file lives afterwards: attachments are held\nin <strong>appdata</strong>, not in the user&#39;s file tree. A picture posted from Files has a\ncopy in app storage; the original stays where it was, untouched.</p>\n","toc":[{"id":"documentservice","text":"DocumentService","level":2},{"id":"cachedocumentservice","text":"CacheDocumentService","level":2},{"id":"videothumbnailservice","text":"VideoThumbnailService","level":2},{"id":"videotranscodeservice-videotranscodingworker-videodeliveryhold","text":"VideoTranscodeService / VideoTranscodingWorker / VideoDeliveryHold","level":2},{"id":"storedmediametadataservice","text":"StoredMediaMetadataService","level":2},{"id":"blurservice","text":"BlurService","level":2},{"id":"gifservice-gifpackservice","text":"GifService / GifPackService","level":2},{"id":"announcementservice","text":"AnnouncementService","level":2},{"id":"domainblockservice","text":"DomainBlockService","level":2},{"id":"accountrelationservice","text":"AccountRelationService","level":2},{"id":"statusrevisionservice","text":"StatusRevisionService","level":2},{"id":"starterpackservice","text":"StarterPackService","level":2},{"id":"starterpackmoderation","text":"StarterPackModeration","level":2},{"id":"collectionpackservice","text":"CollectionPackService","level":2},{"id":"fediversedirectoryservice","text":"FediverseDirectoryService","level":2},{"id":"peertrendservice","text":"PeerTrendService","level":2},{"id":"directoryservice-suggestionservice-trendservice-featuredtagservice","text":"DirectoryService / SuggestionService / TrendService / FeaturedTagService","level":2},{"id":"bannerservice","text":"BannerService","level":2},{"id":"avatarservice","text":"AvatarService","level":2},{"id":"multipartbodyservice","text":"MultipartBodyService","level":2},{"id":"serving-media","text":"Serving media","level":2},{"id":"posting-a-picture-that-is-already-in-nextcloud","text":"Posting a picture that is already in Nextcloud","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"media","manual":false,"prev":{"path":"/docs/architecture-federation","title":"Federation"},"next":{"path":"/docs/architecture-system","title":"System"},"parent":"architecture-key-services"},{"slug":"architecture-system","path":"/docs/architecture-system","title":"System","description":"App/user configuration and the derived URLs (cloud URL, social URL, social address, max download size, self-signed toggle), plus ActivityPub id generation. The social URL is derived from…","group":"architecture","html":"<h2 id=\"configservice\">ConfigService</h2>\n<p>App/user configuration and the derived URLs (cloud URL, social URL, social address, max download size, self-signed toggle), plus ActivityPub id generation. The social URL is derived from the stored cloud URL (<code>derivedSocialUrl()</code>), never from the request that happens to find it empty. It also owns the two config-derived parts of every outbound request: <code>requestOptions()</code> (the timeout and connect timeout — reaching a peer gets <code>DEFAULT_CONNECT_TIMEOUT</code>, 4 seconds, unless a caller asks for its own, never more than the request&#39;s timeout, so a dead host fails in seconds rather than after the whole read timeout — whether the peer&#39;s certificate has to check out, whether local addresses may be reached) and <code>activityPubHeaders()</code> (the <code>Accept</code> a federation GET carries and the <code>Content-Type</code> a POST does). <code>withRequestTimeout()</code> bounds everything a call makes, overriding what the caller asked for</p>\n<h2 id=\"checkservice\">CheckService</h2>\n<p>Installation checks (is <code>/.well-known/webfinger</code> reachable) and repair of invalid follow and note rows</p>\n<h2 id=\"indexservice\">IndexService</h2>\n<p>Repairs missing <code>social_stream_dest</code> and <code>social_stream_tag</code> rows 500 streams per <code>Cron\\Index</code> pass. It pages by ascending NID, hydrates each page in one query (<code>StreamRequest::getIndexStreams()</code>, falling back to a stream at a time when that fails), writes the cursor (<code>index_nid</code>) once per page and only past streams whose side indexes succeeded, and leaves existing rows in place so interrupted work resumes safely. It is a one-shot repair: a page that comes back short has reached the newest post — everything after it was indexed by its own save — so the pass sets <code>index_done</code> and from then on costs one config read. A failing row is logged and holds the cursor before it for up to <code>MAX_FAILURES</code> (5) passes (<code>index_failing</code> counts them), then is skipped with a warning so one bad row cannot stop the walk for good; the explicit <code>social:check:install --index</code> remains the administrator&#39;s full rebuild.</p>\n<h2 id=\"clientservice\">ClientService</h2>\n<p>OAuth 2.0 client registration, authorization and token issuing; <code>DeviceAuthorizationService</code> implements RFC 8628 with hashed device codes, single-use account approval, polling backoff and expiry for devices without a keyboard</p>\n<h2 id=\"detailsservice\">DetailsService</h2>\n<p>Computes a <code>StreamDetails</code> object describing which local viewers a stream reaches</p>\n<h2 id=\"miscservice\">MiscService</h2>\n<p>Logging helper and the running Nextcloud major version</p>\n<h2 id=\"reportservice\">ReportService</h2>\n<p>Moderation reports: stores what was filed locally over the client API or arrived from a remote instance as a <code>Flag</code>, and notifies the instance admins. An incoming <code>Flag</code> keeps at most 50 of the ids it names, and they are resolved against the actor cache only: nothing it names is fetched</p>\n<h2 id=\"moderationservice\">ModerationService</h2>\n<p>Acts on a report: silence, suspend, or take one post down. the two levels are described under ActivityPub Federation below</p>\n<h2 id=\"grouplistservice\">GroupListService</h2>\n<p>Nextcloud groups as Aloha Social lists: every group a person is in <strong>that an administrator has chosen</strong> (<code>SectionsService::groupHasList()</code>, empty by default, so nothing until somebody chooses) becomes a list of theirs, holding the group&#39;s members that have an Aloha Social account, kept in step three ways — the lists a viewer is missing are made when they ask for their lists (<code>ensureForViewer()</code>, from <code>GET /api/v1/lists</code>), a group change is applied the moment it happens (<code>GroupListListener</code>, on the four <code>OCP\\Group\\Events</code>), and the cron reconciles every group list against its group (<code>reconcile()</code>, from <code>Cron\\Cache</code>) for what neither saw, such as an account created after the lists were. A group larger than <code>MAX_GROUP_SIZE</code> (500) gets no list, and neither does one the administrator has not chosen — deselecting a group takes its lists away on the next <code>reconcile()</code>, which is the only place that can see it, since <code>ensureForViewer()</code> only ever looks at the groups the viewer is in. A group list is a private list like any other — same table, same timeline, same visibility — whose title and membership are the group&#39;s rather than the owner&#39;s: <code>ListController</code> refuses to delete one or edit its members (422) and keeps its title on an update</p>\n<h2 id=\"sectionsservice\">SectionsService</h2>\n<p>what this instance offers: whether stories (24-hour shorts) are taken, whether the Photos and Videos timelines appear (all three on by default), and which Nextcloud groups become lists (empty by default). Read by <code>NavigationController</code> into <code>serverData</code> so the sidebar is drawn right the first time, by <code>GroupListService</code> before it makes a list, and written by <code>SectionsController</code> (<code>POST /admin/sections</code>, administrators only, all of it or none)</p>\n<h2 id=\"deliveryservice\">DeliveryService</h2>\n<p>What the outbound queue looks like to an author: the rows of one post, counted as delivered / sending / waiting / failing / abandoned and listed per server, the ones that need an eye first. Only as good as the queue&#39;s retention, which the answer carries, so an old post reports nothing rather than reporting wrongly</p>\n<h2 id=\"federationhealthservice\">FederationHealthService</h2>\n<p>What the outbound queue looks like to an administrator: which instances deliveries are failing against, so an instance that has quietly stopped receiving anything is distinguishable from one nobody posted to. Both states, not one: what is still being retried (<code>getFailing()</code>, STANDBY with at least one failure) and what has been <strong>given up on</strong> (<code>getAbandoned()</code>, <code>STATUS_ABANDONED</code>), each grouped per host. The second was reported nowhere — a request on its fifteenth attempt was counted as failing and the moment it was abandoned it left every count, so the queue looked healthiest exactly when a peer had been lost for good. The abandoned figures reach back <code>RequestQueueService::RETENTION_SECONDS</code> (seven days), which is how long a finished row is kept; <code>occ social:queue:status</code>, the admin settings and the dashboard widget all read this one summary, and <code>occ social:queue:retry --instance HOST</code> is what acts on it</p>\n<h2 id=\"atprotofiguresservice\">AtprotoFiguresService</h2>\n<p>The <em>Bluesky figures</em> section of the admin page (<code>GET /admin/bluesky/figures</code>, administrators only): identities and the switched-off ones, post records written in the last day and week, the repository heads&#39; record and blob-byte sums, the watched Bluesky accounts and the stored Jetstream cursor&#39;s lag, and the firehose (the daemon&#39;s reported subscribers, the newest event, the events in the replay window). Every figure is a count over an index or a table of one row per local account, cached a minute in <code>DurableCache</code>; the record table has no index on <code>creation</code>, so the posts are counted from the first id of the window, found by a binary search over the primary key (<code>AtprotoRepoRequest::firstRecordIdSince()</code>). Nothing is counted while Bluesky is off.</p>\n<h2 id=\"testservice\">TestService</h2>\n<p>Backs the WebFinger probe of <code>occ social:check:install</code></p>\n<h2 id=\"durablecache\">DurableCache</h2>\n<p>Short-lived state that has to hold on an instance with no memcache. <code>ICacheFactory::createDistributed()</code> hands such an instance a <code>NullCache</code>, which forgets every write: a counter kept there reads zero for ever and a list of what was already accepted is always empty. This is the distributed cache when <code>isAvailable()</code> says there is one and the <code>social_durable_cache</code> table when there is not, behind the part of <code>ICache</code> a counter or a replay record needs, with the namespace passed on each call: <code>get($ns, $key)</code> (null for a miss), <code>set($ns, $key, $value, $ttl)</code>, <code>inc($ns, $key, $ttl, $step = 1)</code> (returns the new count; the TTL is set when the counter is created and never extended) and <code>remove($ns, $key)</code>. Values are anything <code>json_encode()</code> round-trips; a TTL of 0 is <code>ICache::DEFAULT_TTL</code>, never forever. On the table <code>inc()</code> is read-then-write, which is fine for a ceiling and wrong for anything that must be unique. APCu configured as <code>memcache.local</code> counts as a memcache and is not shared with cron or <code>occ</code>, so state a background job writes for a web request does not belong here. Used by <code>InboxLimiter</code> (namespace <code>social.inbox</code>), <code>SignatureService</code>&#39;s LD-signature and signed-request replay records (<code>social.ldsig</code>, <code>social.httpsig</code>), the <code>Idempotency-Key</code> record of <code>POST /api/v1/statuses</code> (<code>social_idempotency</code>) and <code>StatisticsService</code>&#39;s computed pages (<code>social/statistics</code>); <code>getShared()</code>/<code>setShared()</code> always use the table, for what <code>occ</code> or cron writes and a web request reads, such as the Jetstream listener&#39;s cursor and last report (<code>JetstreamState</code>, <code>social.atproto.jetstream</code>, kept a year and renewed on every write; the older <code>atproto_jetstream_*</code> app-config keys are moved there once, on their first read) and the reconcile pass&#39;s position (<code>social.atproto.reconcile</code>); the <code>MemcacheConfigured</code> setup check says which of the other caches are off without one</p>\n<h2 id=\"pushservice\">PushService</h2>\n<p>on a new stream, resolves the local audience through <code>DetailsService</code> (home + direct viewers) and pushes a <code>social_timeline</code> custom event per user through the notify_push app when it is installed, and on every stored notification (<code>NotificationService::onNotification()</code>, held or not) pushes one to its local recipient; without notify_push every call is a cheap no-op and web clients keep polling. Each push says what arrived, as the body <code>{&quot;kinds&quot;: [...]}</code> — <code>home</code>, <code>direct</code>, <code>notification</code> — and each subscriber names the kinds that can change what it shows (<code>onTimelinePush(handler, kinds)</code>): the direct messages pane hears only of direct messages, the sidebar&#39;s badges of direct messages and notifications, the Activities list and the Dashboard widget of notifications, every other timeline list of posts; a push without a body (an older server or notify_push) is every kind. The web client listens via <code>@nextcloud/notify_push</code> once per page (<code>src/services/timelinePush.js</code>, <code>onTimelinePush()</code>) and drops its 30-second poll to a 5-minute safety net when push is available. A push arrives for every post that reaches the account, so the page gathers them before any subscriber hears of them: a run of pushes is handed on once it has been quiet for three seconds (<code>PUSH_SETTLE_MS</code>), and never more than ten seconds after the first of it (<code>PUSH_MAX_WAIT_MS</code>); a hidden tab hands on nothing and catches up once when it is looked at again; and a subscriber whose last answer is still on its way is run again once that answer is in, not alongside it. The sidebar&#39;s three badge counts, the timeline lists, the direct messages pane and the Dashboard widget all subscribe through it, and a subscriber is told which of its kinds arrived — the sidebar reads only the counts those can change. While the poll&#39;s requests fail the wait between attempts doubles — 60 s, 120 s, 240 s, then five minutes — and the first answer puts it back; a page request still on its way when the reader switches lists is cancelled (<code>AbortController</code>) rather than answered and thrown away</p>\n<hr>\n","toc":[{"id":"configservice","text":"ConfigService","level":2},{"id":"checkservice","text":"CheckService","level":2},{"id":"indexservice","text":"IndexService","level":2},{"id":"clientservice","text":"ClientService","level":2},{"id":"detailsservice","text":"DetailsService","level":2},{"id":"miscservice","text":"MiscService","level":2},{"id":"reportservice","text":"ReportService","level":2},{"id":"moderationservice","text":"ModerationService","level":2},{"id":"grouplistservice","text":"GroupListService","level":2},{"id":"sectionsservice","text":"SectionsService","level":2},{"id":"deliveryservice","text":"DeliveryService","level":2},{"id":"federationhealthservice","text":"FederationHealthService","level":2},{"id":"atprotofiguresservice","text":"AtprotoFiguresService","level":2},{"id":"testservice","text":"TestService","level":2},{"id":"durablecache","text":"DurableCache","level":2},{"id":"pushservice","text":"PushService","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"system","manual":false,"prev":{"path":"/docs/architecture-media","title":"Media"},"next":{"path":"/docs/architecture-mastodon-web-push","title":"Mastodon Web Push"},"parent":"architecture-key-services"},{"slug":"architecture-mastodon-web-push","path":"/docs/architecture-mastodon-web-push","title":"Mastodon Web Push","description":"VapidService creates one stable instance key pair and seals the private key with PrivateKeyCipher; PushSubscriptionService keeps each access token, endpoint and browser key pair in an…","group":"architecture","html":"<p><code>VapidService</code> creates one stable instance key pair and seals the private key with <code>PrivateKeyCipher</code>; <code>PushSubscriptionService</code> keeps each access token, endpoint and browser key pair in an encrypted per-user config value, indexed by the token digest. <code>NotificationService::emit()</code> queues <code>Cron\\MastodonPushNotification</code> only for a locally deliverable notification that passes the notification policy and muted-thread checks. The job rechecks the recipient, applies each subscription&#39;s alert switches and followed/follower policy, and sends a 140-character plain-text content warning or post excerpt (or the followed account&#39;s profile description when no status is attached). It encrypts with the negotiated <code>aes128gcm</code> or legacy <code>aesgcm</code> format and sends through <code>SafeWebPushClient</code>, which delegates to <code>CurlService</code>&#39;s pinned public-address request path without redirects. Expired 404/410 endpoints are removed; transient failures retry per subscription, so a retry does not resend to endpoints that already accepted the notification. The payload contains the bearer token only inside Web Push encryption; queued arguments and logs contain no bearer, endpoint or push keys.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"mastodon-web-push","manual":false,"prev":{"path":"/docs/architecture-system","title":"System"},"next":{"path":"/docs/architecture-mastodon-websocket-and-sse-streaming","title":"Mastodon WebSocket and SSE streaming"},"parent":"architecture-key-services"},{"slug":"architecture-mastodon-websocket-and-sse-streaming","path":"/docs/architecture-mastodon-websocket-and-sse-streaming","title":"Mastodon WebSocket and SSE streaming","description":"MastodonStreamingDaemon (occ social:mastodon:stream) serves the user, user:notification, direct, list, public, public:media, public:local, public:local:media, public:remote…","group":"architecture","html":"<p><code>MastodonStreamingDaemon</code> (<code>occ social:mastodon:stream</code>) serves the <code>user</code>,\n<code>user:notification</code>, <code>direct</code>, <code>list</code>, <code>public</code>, <code>public:media</code>, <code>public:local</code>,\n<code>public:local:media</code>, <code>public:remote</code>, <code>public:remote:media</code>, <code>hashtag</code> and\n<code>hashtag:local</code> WebSocket streams, plus user, public, hashtag, direct and list\nSSE endpoints, on a separate long-running process. It requires a user-authorized token with\n<code>read</code> or <code>read:statuses</code> for public streams; user streams require <code>read</code> or\nboth <code>read:statuses</code> and <code>read:notifications</code>; direct streams require <code>read</code>\nor <code>read:statuses</code>; list streams require <code>read:statuses</code> and owned lists. A\nWebSocket subscriber may keep up to 20 lists active at once; each has its own\ncursor and can be unsubscribed independently.\nOnce per second it reads the\nsame timelines used by the REST API, applies the viewer&#39;s filters, reply\nvisibility and notification policy, and emits Mastodon&#39;s event payloads.\nEvery five seconds it fingerprints each subscribed account&#39;s filters and\nemits <code>filters_changed</code> on that account&#39;s user streams when the set changes;\nthe event carries no payload, as Mastodon specifies.\nIt also compares the account&#39;s active instance announcements every five\nseconds and emits <code>announcement</code>, <code>announcement.reaction</code> and\n<code>announcement.delete</code> when a notice appears, its reaction counts change, or\nit expires or is removed. String event payloads such as deleted ids are sent\nas raw text rather than JSON-quoted strings.\nAccepting a notification request bumps a dedicated per-account revision, which\ncauses subscribed user and notification-only streams to emit\n<code>notifications_merged</code> without confusing other timeline changes with accepted\nrequests.\nFor edits to public posts it reads the append-only status-revision cursor and\nemits one <code>status.update</code> event per changed post on matching public and\nhashtag subscriptions. Home and owned-list streams recheck membership in the\nviewer-scoped timeline before receiving an edit, so a private post only reaches\nreaders whose timeline already includes it.\nThe direct stream resolves an edited message to a conversation visible to\nthat viewer and emits the current <code>conversation</code> entity; a dismissed or\ninaccessible conversation is not emitted.\n<code>WebSocketServer</code> keeps connection and output-buffer bounds for both\ntransports. Status deletions are retained as ids, visibility, and public-stream\nmatching metadata, bounded to the newest 10,000 events. Direct-message events\nalso keep the hashed recipients from the deleted post&#39;s destination rows. The\ndaemon emits Mastodon&#39;s <code>delete</code> event to matching public subscriptions and to\nthe direct stream only for an original participant. Direct-message events\ncarry no hashtag metadata and are never sent to user, list, public, or hashtag\nstreams. Unlisted and followers-only deletions are limited to authorized home/list viewers; the daemon resolves current follow state against the exact cached followers collection saved with the event.\nThe root Apache and Nginx examples proxy the streaming endpoints and health\npath to this daemon.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"mastodon-websocket-and-sse-streaming","manual":false,"prev":{"path":"/docs/architecture-mastodon-web-push","title":"Mastodon Web Push"},"next":{"path":"/docs/architecture-activitypub-federation","title":"ActivityPub Federation"},"parent":"architecture-key-services"},{"slug":"architecture-activitypub-federation","path":"/docs/architecture-activitypub-federation","title":"ActivityPub Federation","description":"ActivityPub is the federation protocol this app speaks; it is also a Bluesky host (AT Protocol), with every local account a did:plc identity whose repository, firehose and XRPC surface…","group":"architecture","html":"<p>ActivityPub is the federation protocol this app speaks; it is also a Bluesky host (AT Protocol), with every local account a <code>did:plc</code> identity whose repository, firehose and XRPC surface live in <code>lib/Atproto/</code> — <a href=\"/docs/atproto\">Atproto-Compatibility.md</a> summarizes the current supported surface and its limits. Reading Bluesky (<code>lib/Atproto/Reader/</code>) goes through the ActivityPub import path: a Bluesky account is a cached actor with id <code>https://bsky.app/profile/&lt;did&gt;</code> and the bare handle as account (<code>BlueskyActorService</code>, <code>ActorMapper</code>), a post read off the public AppView by <code>FeedPoller</code> arrives as the <code>Create</code> of a <code>Note</code> from that actor (<code>PostMapper</code>, <code>FacetRenderer</code>, <code>PostStore</code> — <code>ImportService::parseIncomingRequest()</code> with origin <code>bsky.app</code>; image galleries, video playlists and external link cards are retained), a repost as the reposter&#39;s <code>Announce</code>, and what Bluesky did to a local account — follows, likes, reposts, replies, mentions, quotes — comes from the AppView&#39;s notifications asked for as that user (<code>NotificationPoller</code>, <code>AppViewClient::queryAs()</code> with a token <code>ServiceAuth</code> mints; on <code>BadJwtAudience</code> it retries with the legacy bare AppView DID for older deployments) and arrives as the <code>Follow</code>, <code>Like</code>, <code>Announce</code> or post it stands for. A Bluesky profile&#39;s author feed is fetched on demand through <code>BlueskyFeeds::authorPage()</code> before the ordinary account-status query, authenticated as the current reader when they have a linked Bluesky identity and public otherwise; one post beyond the requested page is fetched to cover posts already ingested by the firehose, and each opaque AppView cursor page is expanded once while local statuses are paged by <code>max_id</code>. An interactive profile request reads at most two cursor pages with a three-second timeout per page; posts beyond them are fetched as scrolling supplies the next <code>max_id</code>. AppView failures leave cached profile posts readable. Bluesky apps signed in here read through the same authenticated AppView, with <code>AppViewProxy</code> applying the same one-time audience fallback. A local follow, like or boost of something that exists on Bluesky is a record in the local repository (<code>BlueskyGraphService</code>, <code>InteractionPublisher</code>, through the queued <code>AtprotoPublish</code>). <code>LocalRecordResolver</code> turns an <code>at://</code> reference to one of this instance&#39;s own records back into the local post or account.</p>\n<p>Outbound Bluesky posts with up to four pictures keep the existing\n<code>app.bsky.embed.images</code> record. Posts with five to ten pictures use\n<code>app.bsky.embed.gallery</code>; each gallery item includes alt text and an aspect\nratio, falling back to a square when image dimensions are unavailable. The\n20-item Lexicon ceiling is not treated as the authoring limit.</p>\n<p>The AT Protocol admin checks compare the public relay and AppView views with a sampled local DID and post. If a relay cannot find the PDS host, the diagnostic distinguishes a crawl that has not happened yet from a private/reserved endpoint that cannot be crawled from a public relay; the latter requires public DNS, HTTPS and an externally reachable web server before retrying.</p>\n<p>The public <code>com.atproto.server.describeServer</code> answer advertises the same\nhandle suffix the instance issues (<code>.&lt;handleHost&gt;</code>) and the upload ceiling\nenforced by <code>ClientXrpc</code> (100,000,000 bytes, the video ceiling). Open registration stays disabled because local\nBluesky identities are Nextcloud accounts; the app page is not advertised as\na privacy policy.</p>\n<p>Signed-in PDS clients manage the same account-scoped records through\n<code>com.atproto.server.createAppPassword</code>, <code>listAppPasswords</code> and\n<code>revokeAppPassword</code>. The password secret is returned only at creation;\nlisting exposes names and creation times without database ids. Creating a\npassword that grants Bluesky chat access requires a session that already\nholds <code>transition:chat.bsky</code>.</p>\n<p>An app&#39;s <code>app.bsky.actor.profile</code> writes update the same local profile the\nFediverse reads. <code>WriteService</code> validates a non-empty website before it\nchanges any account fields or pictures, and normalizes pronouns with the\nprofile lexicon&#39;s grapheme and byte limits before writing the shared field\nrow. <code>RecordMapper</code> uses that same pronoun limit when publishing the local\nprofile back to Bluesky.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":[{"path":"/docs/architecture-resuming-bluesky-synchronization","title":"Resuming Bluesky synchronization","description":"Cron\\AtprotoSync runs once a minute and spends its 45-second budget on notifications before feeds and direct messages, so a slow feed cannot keep likes, reposts and replies to local posts…","parent":true},{"path":"/docs/architecture-actor-identity","title":"Actor Identity","description":"Alongside the per-user actors, the instance has one Application actor of its own at <social url>actor, with its own RSA key pair in app config. It is what signs every outbound ActivityPub…","parent":true},{"path":"/docs/architecture-outgoing-flow","title":"Outgoing Flow","description":"adds a Linked Data Signature — for Create, Update, Delete, Like, Announce and their Undos. Follow, Accept, Reject, Block and Undo{Block} are not LD-signed; they travel with the HTTP…","parent":true},{"path":"/docs/architecture-incoming-flow","title":"Incoming Flow","description":"spends the per-address bucket, before anything is read, and readBody() reads at most 1 MiB of body — refusing more with 413","parent":true},{"path":"/docs/architecture-peertube-and-federated-video","title":"PeerTube and federated video","description":"A Video is one of the note-like types in AP::NOTE_LIKE_TYPES — object types other servers Create into a timeline that this app has no model of its own for — and like the rest of them it is…","parent":true}],"anchor":"activitypub-federation","manual":false,"prev":{"path":"/docs/architecture-mastodon-websocket-and-sse-streaming","title":"Mastodon WebSocket and SSE streaming"},"next":{"path":"/docs/architecture-resuming-bluesky-synchronization","title":"Resuming Bluesky synchronization"},"parent":null},{"slug":"architecture-resuming-bluesky-synchronization","path":"/docs/architecture-resuming-bluesky-synchronization","title":"Resuming Bluesky synchronization","description":"Cron\\AtprotoSync runs once a minute and spends its 45-second budget on notifications before feeds and direct messages, so a slow feed cannot keep likes, reposts and replies to local posts…","group":"architecture","html":"<p><code>Cron\\AtprotoSync</code> runs once a minute and spends its 45-second budget on\nnotifications before feeds and direct messages, so a slow feed cannot keep\nlikes, reposts and replies to local posts waiting behind it. Notification\ncursors stay on that one-minute cadence even when an inbox is empty; the\nempty result is not evidence that the next event will arrive soon. The\neffective delay still depends on how often Nextcloud runs background jobs and\nhow quickly the Bluesky AppView indexes an event. <code>FeedPoller</code> and\n<code>NotificationPoller</code> read at most one AppView page per due account and pass.\nA feed&#39;s first read walks pages to the end, so its cursor\nstarts without a committed timestamp and advances only when the walk finishes;\nnotification polling starts with a snapshot of its newest page. <code>Reader\\PollCursor</code> keeps their committed timestamp separate\nfrom the AppView&#39;s opaque pagination cursor. While walking a backlog, the\nexisting cursor column holds JSON with <code>since</code> (the previous committed\ntimestamp), <code>newest</code> (the newest timestamp seen in this walk) and <code>page</code> (the\nnext AppView cursor). Only reaching <code>since</code> or the end commits <code>newest</code> and\nreturns the column to its legacy timestamp format. AppView timestamps are not\nunique: an event exactly at the committed timestamp is still read, and only\na strictly older event ends the walk. If equal-time events span pages, the\nopaque page cursor carries the walk across them. Re-reading an event at the\nboundary is safe because imports are idempotent. No schema change is needed.\nEmpty intermediate pages still continue, while malformed responses, repeated\ncursors and failed reads retain the existing checkpoint and use failure\nbackoff. A pending walk stays on the ordinary two-minute interval even when\nits current page stores no new rows. The initial feed read is bounded to one\npage per pass and continues until the AppView has no older page.\nPinned feed entries do not participate in chronological synchronization:\n<code>BlueskyPins</code> handles them separately, and an old pin must not end the walk.</p>\n<p>Custom-feed and list timelines (<code>BlueskyFeeds</code>) keep the AppView continuation\nfor one hour, keyed by viewer, feed URI and the last visible post. They use\n<code>DurableCache</code>, including its database fallback on instances without a\nmemcache, so subsequent web requests can read the next page. A cursor from\nanother viewer or feed cannot be reused, and an expired cursor ends the list.</p>\n<p>The app is an ActivityPub <strong>Server</strong> that both produces and consumes ActivityPub messages.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"resuming-bluesky-synchronization","manual":false,"prev":{"path":"/docs/architecture-activitypub-federation","title":"ActivityPub Federation"},"next":{"path":"/docs/architecture-actor-identity","title":"Actor Identity"},"parent":"architecture-activitypub-federation"},{"slug":"architecture-actor-identity","path":"/docs/architecture-actor-identity","title":"Actor Identity","description":"Alongside the per-user actors, the instance has one Application actor of its own at <social url>actor, with its own RSA key pair in app config. It is what signs every outbound ActivityPub…","group":"architecture","html":"<p>Each Nextcloud user that has been given an Aloha Social account gets a Person actor:</p>\n<ul>\n<li><strong>ID:</strong> the configured social URL plus <code>@username</code>, e.g. <code>https://cloud.tld/apps/social/@username</code>. It is derived on every read, while the <code>social_actor</code> row keeps the <code>id_prim</code> of the id it was made under, so after the social URL changes the two differ: the model carries the stored prim (<code>Person::getStoredIdPrim()</code>), every write to the row is keyed on it (<code>ActorsRequest::limitToRow()</code>), and the walks that page the table by <code>id_prim</code> — the local actor refresh, the profile-link check and <code>walk()</code> — carry on from it (<code>ActorsRequest::rowPrimOf()</code>)</li>\n<li><strong>Keys:</strong> RSA 2048-bit key pair, generated per actor by <code>SignatureService::generateKeys()</code></li>\n<li><strong>Endpoints:</strong> <code>/@{user}/inbox</code>, the shared <code>/inbox</code>, <code>/@{user}/outbox</code>, <code>/@{user}/followers</code>, <code>/@{user}/following</code>, <code>/@{user}/collections/featured</code></li>\n<li><strong>Profile fields:</strong> <code>attachment</code> entries of type <code>PropertyValue</code>. A local value is stored as typed and served as the HTML the wire expects: escaped, and an address on its own linked with <code>rel=&quot;me&quot;</code> the way Mastodon&#39;s own fields are, since Mastodon verifies a remote field only from a link in it. A remote actor&#39;s fields are served, to clients and on the wire, with the name as plain text and the value as sanitised HTML</li>\n<li><strong>Media type:</strong> <code>ActivityPubController</code> answers in the type the peer listed first — <code>application/activity+json</code> or <code>application/ld+json; profile=&quot;https://www.w3.org/ns/activitystreams&quot;</code> (GoToSocial asks for the latter first and refuses any other answer). Both responders are built on the framework&#39;s <code>json</code> responder, so a 401, 404 or 410 reaches the peer with its status</li>\n<li><strong>Collections:</strong> followers, following and outbox answer with an <code>OrderedCollection</code> whose <code>first</code> and <code>last</code> point at <code>?page=N</code>, and with <code>?page=N</code> they answer with a real <code>OrderedCollectionPage</code> of <code>OrderedCollection::PAGE_SIZE</code> (40) items linked by <code>next</code>/<code>prev</code>, so a consumer can enumerate them. Followers and following list <code>type = Follow</code> rows only: the accepted <code>Loopback</code> row every actor has on itself, which the home timeline reads (<code>getHomeCollectionPrims()</code>), is not a follow. <code>featured</code> — the actor&#39;s pinned posts, which is how a remote server learns about a pin — is a single unpaged collection. The posts in the outbox and in <code>featured</code> are exported with complete details off, as <code>displayPost()</code> exports one: their rows are read with the author joined, which flags them for this app&#39;s own bookkeeping (<code>source</code>, <code>actor_info</code>, <code>details</code>, <code>cache</code>), and none of that is a peer&#39;s business</li>\n</ul>\n<p>Alongside the per-user actors, the instance has one <code>Application</code> actor of its own at <code>&lt;social url&gt;actor</code>, with its own RSA key pair in app config. It is what signs every outbound ActivityPub GET and what <code>ReportForwardService</code> files a <code>Flag</code> as; it is not an account and appears in no directory, no client API and no statistic. Its <code>inbox</code> is the shared <code>/inbox</code> — anything addressed to the server is addressed there — and it names no outbox, followers, following or featured collection, because an actor document naming a collection no route serves is worse than one that omits it.</p>\n<p><strong>A 24-hour short is a story.</strong> The web client offers one feature, <strong>Shorts</strong>, with two lifetimes: a <em>kept</em> short is an ordinary post with a video, stored in the stream and federated as a <code>Note</code> (or a <code>Video</code>) like any other; a <em>24-hour</em> short is what the client API, the tables (<code>social_story*</code>), the OAuth scopes and the wire call a <strong>story</strong> — Pixelfed&#39;s <code>Story</code> object, fetched through a bearcap and answered with <code>View</code>, <code>Story:Reaction</code> and <code>Story:Reply</code>. Everything below this line, and every route and identifier, keeps the name story; only what a person reads says short.</p>\n<p>A story is the one object here that is neither a post nor a collection. It is published to the author&#39;s followers as an <code>Add</code> whose object is a <code>Story</code> and withdrawn with a <code>Delete</code> — Pixelfed&#39;s verbs, because Pixelfed is the network that has stories — and it resolves at <code>/@{username}/stories/{id}</code> for a peer that would rather fetch it than trust the copy it was handed, under the same rule the client API keeps: the author, or a signed reader who follows them. <code>StoryInterface</code> takes the incoming side and keeps a story only when somebody here follows its author, for no longer than a day whatever the sender&#39;s <code>expiresAt</code> says. The published shape is Pixelfed&#39;s down to the field names, because Pixelfed is the only network that has stories: its <code>StoryFetch</code> reads nothing out of the activity, requiring <code>object.object</code> as a <strong>bearcap</strong> (<code>bear:?t=…&amp;u=…</code>, FEP-d8c2) that it then fetches with the token, so the <code>Add</code> carries the capability beside the fields, <code>attachment</code> is one object typed <code>Image</code>/<code>Video</code> rather than a list, and <code>published</code>, <code>expiresAt</code> and <code>can_reply</code>/<code>can_react</code> are all stated. The token is an HMAC of the story&#39;s address under an instance secret made on first use — derived rather than stored, because a story lives a day and a row per story to write and expire is a table for a value that can be recomputed — and <code>ActivityPubController::story()</code> accepts it as a bearer token beside the signed-follower rule, since a bearcap fetch signs nothing. What cannot be fixed from this side: Pixelfed fans stories out with <code>FollowerService::softwareAudience($id, &#39;pixelfed&#39;)</code>, so it delivers them only to instances it has identified as Pixelfed and none of its stories arrive here whatever this app does. A <code>Create</code> is deliberately not used: it would put a story where posts go, and a server that does not know the type ignores an <code>Add</code> of one, which is the outcome to want.</p>\n<p>Every local note carries a <code>replies</code> collection at <code>&lt;post id&gt;/replies</code>, served paged by <code>ActivityPub#replies</code>. A reply reaches the instances that hold the post it answers and nowhere else, so without it a reader on a third instance sees a post with no replies. It lists the ids of the <strong>public</strong> replies only, and remote notes are not given one: their replies live on the server that holds them.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"actor-identity","manual":false,"prev":{"path":"/docs/architecture-resuming-bluesky-synchronization","title":"Resuming Bluesky synchronization"},"next":{"path":"/docs/architecture-outgoing-flow","title":"Outgoing Flow"},"parent":"architecture-activitypub-federation"},{"slug":"architecture-outgoing-flow","path":"/docs/architecture-outgoing-flow","title":"Outgoing Flow","description":"adds a Linked Data Signature — for Create, Update, Delete, Like, Announce and their Undos. Follow, Accept, Reject, Block and Undo{Block} are not LD-signed; they travel with the HTTP…","group":"architecture","html":"<ol>\n<li>A user action (post, edit, delete, follow, unfollow, like, boost) has a service build the activity</li>\n</ol>\n<h2 id=\"signatureservice-signobject\">SignatureService::signObject()</h2>\n<p> adds a Linked Data Signature — for Create, Update, Delete, Like, Announce and their Undos. Follow, Accept, Reject, Block and <code>Undo{Block}</code> are <strong>not</strong> LD-signed; they travel with the HTTP signature only</p>\n<h2 id=\"activityservice-request\">ActivityService::request()</h2>\n<p> expands the activity&#39;s instance paths into concrete target inboxes. An activity addressed to everybody — an account deletion — goes to one shared inbox per server heard from in the last <code>ALL_SEEN_DAYS</code> (90: a refresh of one of its accounts worked, or one of them was made, inside the window; <code>CacheActorsRequest::getSharedInboxesSeenSince()</code>, grouped on the indexed <code>host</code>), less the servers whose breaker is open, rather than to every shared inbox ever cached</p>\n<ol>\n<li>Targets on this instance are dropped: everyone here already has the item, because recipients are written into <code>social_stream_dest</code> when it is saved, which is what puts it in a local timeline. Posting to our own inbox would only hand us back what we wrote, and it is a request the server has to be able to make to its own public address — behind a reverse proxy, split-horizon DNS or an SSRF guard it often cannot, and the delivery then fails its way to being abandoned while remote instances queue up behind it. This holds only for activities whose effect is already applied when the item is saved. A <strong>Follow</strong> has no such path, so <code>FollowService::followAccount()</code> detects a local target and runs <code>FollowInterface::processIncomingRequest()</code> in process instead — setting the activity&#39;s origin to this host first, because that handler is the inbox&#39;s and checks it. Without that the row stayed <code>accepted = 0</code> for ever and no local follow ever completed</li>\n</ol>\n<h2 id=\"requestqueueservice-generaterequestqueue\">RequestQueueService::generateRequestQueue()</h2>\n<p> writes one <code>social_req_queue</code> row per remaining target — for a post waiting on its video, held until a given time and not delivered by steps 6 and 7 before then (see <strong>Held for a video</strong> below)</p>\n<ol>\n<li>At most one row is delivered inline: <code>RequestQueueService::getPriorityRequest()</code> hands back the first row only when its priority is <code>TOP</code>, or <code>HIGH</code>/<code>MEDIUM</code> under narrow conditions, and otherwise throws <code>NoHighPriorityRequestException</code> so nothing is sent synchronously. If rows remain on standby, <code>CurlService::asyncWithToken()</code> fires a request at the app&#39;s own <code>/async/request/{token}</code> route to drain them, signed with an HMAC of the token and the time of the call under the instance secret (<code>AsyncRequestSigner</code>; a signature older than five minutes is refused, and a failed call logs only a hash prefix of the token) — the route is public, and an unsigned call would otherwise have a worker deliver on anybody&#39;s say-so. That drain is <strong>one bounded wave</strong>: <code>QueueController::drain()</code> delivers the first <code>ASYNC_ROWS</code> (40) of the post&#39;s rows, several servers at a time, for at most <code>MAX_DURATION</code> (20 seconds), and leaves the rest on standby for step 7. Every local post starts one, in a PHP-FPM worker holding a database connection; when the drain took the whole fan-out for up to 90 seconds, a few posts a minute from accounts followed across many servers held enough workers that the web interface and the inbox stopped answering, while the cron would have delivered the same rows in the background</li>\n</ol>\n<h2 id=\"cronqueue\">Cron\\Queue</h2>\n<p> (12-minute interval) retries whatever the query says is due, with the backoff above, after returning rows a dead worker left <code>running</code> to standby</p>\n<ol>\n<li>Every delivery is an HTTP POST to the queue row&#39;s inbox URI. <code>SignatureService::signRequest()</code> is given that URL and the body about to be sent and answers with the signed headers; <code>CurlService::retrieveJson()</code> sends both</li>\n</ol>\n<h2 id=\"federated-events\">Federated events</h2>\n<p> A locally authored event is serialized as an ActivityStreams\n<code>Event</code>, with normalized UTC <code>startTime</code>/<code>endTime</code> and a structured <code>Place</code> when\navailable. Mastodon turns an <code>Event</code> into an ordinary status and uses <code>content</code>\nwhen present, so the serializer appends an escaped title, UTC schedule and\nlocation to the post body while retaining those structured fields. This keeps\nthe event details visible on Mastodon without changing the local/client API\nrepresentation.</p>\n<h2 id=\"held-for-a-video\">Held for a video</h2>\n<p> Pixelfed checks an attachment&#39;s type when the <code>Create</code>\narrives and drops a <code>video/quicktime</code> there and then; nothing re-sends a post\nafter its video is converted. So <code>PostService::createPost()</code> asks\n<code>VideoDeliveryHold::holdUntil()</code> first: for a post carrying a local video that\nhas not been through the transcoder (<code>transcoded = 0</code>) and may need it, on a\nserver where <code>isEnabled()</code>, the answer is now + <code>HOLD_SECONDS</code> (600), and for\nevery other post 0 — a post with no video attachment costs no lookup at all.\n<code>ActivityService::request()</code> with that time writes the rows as usual but with\n<code>last</code> set to it and <code>tries = 0</code> (bound in the same insert, so no drain sees them\ndue for a moment), and delivers nothing inline and starts no async drain.\n<code>last</code> in the future is what <code>limitToQueueDue()</code> already treats as not due —\nthe same hold <code>postponeRequest()</code> puts on a row whose host has an open breaker —\nand <code>QueueController</code> skips such rows too. Then <code>convertSoon()</code> queues\n<code>Cron\\TranscodeBeforeDelivery</code> with <code>{post}</code>, which on the next cron run\nconverts the post&#39;s awaited videos and calls <code>ActivityService::releaseHeld()</code>\n<strong>whatever happened</strong> — converted, not needed, failed, or the setting switched\noff since. <code>releaseHeld()</code> reads the post again, builds each held <code>Create</code> or\n<code>Update</code> afresh from it (re-signed: the linked-data signature covers the\ndocument, so the stored body cannot be patched), writes that body and\n<code>last = NULL</code> onto every row still on standby, and hands each token to the async\ndrain; the activity then names the converted file and <code>video/mp4</code>. While the\nrows wait, the author&#39;s own <code>Status</code> carries <code>delivery: &quot;held&quot;</code>\n(<code>Stream::isDeliveryHeld()</code>, through <code>VideoDeliveryHold::isHeld()</code>): looked up\nfor the reader&#39;s own local posts only, and the attachments are checked before\nthe queue is asked, so a post without a video costs no query; the key is\nabsent on everybody else&#39;s copy and once the post has gone out. If the job\nnever gets that far the rows fall due at the deadline and <code>Cron\\Queue</code> or\n<code>social:worker</code> sends them as they were queued. An <strong>edit</strong> made while a post\nwaits is held the same way (the same job, found already queued) and rebuilt as\nan <code>Update</code> at release, so it cannot overtake the <code>Create</code> or carry the old\nfile. A <strong>delete</strong> drops the post&#39;s held rows first (<code>deleteActivity()</code>); a post\ndeleted before the release is found gone and its held rows are dropped there.\nA <strong>scheduled post</strong> is held when it is published, by then often already\nconverted by the sweep.</p>\n<h2 id=\"an-edit-can-add-recipients\">An edit can add recipients</h2>\n<p> <code>PostService::editPost()</code> reparses the new text,\nadds only newly named actors to the audience, mention tags and inbox paths, and\nthen persists the changed post. <code>StreamRequest::update()</code> writes those paths\nback to <code>social_stream.instances</code> and, for a local edit, regenerates\n<code>social_stream_dest</code> in the same transaction. The <code>Update</code> is built from the\nreloaded post, so a newly mentioned instance is not lost between editing and\nqueueing. The followers path is added only when the post&#39;s visibility reaches\nfollowers; this keeps an edit to a direct message from widening its audience.\nThe client&#39;s <code>mentions</code> follow the new text: a name written in is listed, and a\nname taken out leaves the list while keeping its tag and its place in the\naudience, as Mastodon keeps a silent mention. An <code>Update</code> from another server\nreplaces the stored <code>mentions</code> with those of its tags; <code>update()</code> writes that\none key into <code>details</code> and leaves the rest of the blob as it was.\nIf queue creation fails after the local transaction commits, the Mastodon API\nanswers <code>503</code> with an explicit message that the post was saved locally; clients\nmust not ask the author to submit the edit again merely because remote delivery\nfailed.</p>\n<h2 id=\"reading-edit-history\">Reading edit history</h2>\n<p> <code>PostDetails</code> opens <code>EditHistoryDialog</code> with the\nstatus&#39;s numeric <code>nid</code> and actual <code>edited_at</code> value. The history route resolves\nthat NID through <code>StreamRequest::getStreamByNid()</code> before reading revisions,\nso visibility rules remain the same as for the post. NIDs can exceed both\n32-bit integers and <code>PHP_INT_MAX</code>; <code>ExtendedQueryBuilder::limitToNid()</code> keeps\nthose decimal values as strings when binding the BIGINT predicate. The dialog\naccepts either the Mastodon array response or Nextcloud&#39;s <code>result</code> wrapper,\nreports malformed or failed responses as errors, lets readers retry, and\nignores a slow response when the dialog has switched to another post.</p>\n<p>A delivery is retried when the peer&#39;s answer says it might accept the activity later — 408, 429 and any 5xx — and the row is dropped only on an answer that says it never will, or once <code>MAX_TRIES</code> is reached. A host that has just answered with a transient status is added to the run&#39;s failing set, so the rest of the run does not ask it once per queued activity.</p>\n<h2 id=\"activities-the-app-emits\">Activities the app emits</h2>\n<p> Create, Update, Delete, Follow, Accept, Reject, Like, Announce, Block, Undo. Every <code>Undo</code> embeds the activity it takes back rather than naming it by id — PeerTube decides what is undone by <code>object.type</code> and ignores a bare id; an <code>Undo{Announce}</code> carries a fresh <code>Announce</code> with the id, actor, object and audience of the stored one (<code>BoostService::undoneAnnounce()</code>), not the stored row&#39;s export. An <code>Update</code> is <code>&lt;object id&gt;#updates/&lt;n&gt;</code>, <code>n</code> being the post&#39;s <code>updated</code> as a Unix time (the time in milliseconds for an object without one), so two edits are two activities and a redelivery of one version keeps its id. Its object is always the ActivityPub document: an edit is read back from the database in the client format, whose <code>id</code> is the nid and which carries no <code>type</code> or <code>updated</code>, and wrapped as it was, the Update named no post any peer held, so Mastodon took every edit in with a 202 and dropped it. <code>updateActivity()</code> serialises the object as ActivityPub and hands the caller its post back in the format it came in.</p>\n<p>Reject goes out when a follow request is refused (<code>FollowInterface::rejectFollowRequest()</code>, also used to answer a <code>Follow</code> from a blocked actor) and when an accepted follow is severed by a block. Block and <code>Undo{Block}</code> go out from <code>RelationshipService</code>, unless the <code>federate_blocks</code> app setting is <code>0</code>.</p>\n<p>The app never emits Add, Remove or Move. It can parse all three — <code>AP::getItemFromType()</code> constructs each one for an incoming document — but no service builds one to send: a pin is a local row that remote servers read from the <code>featured</code> collection, and nothing here migrates an account away.</p>\n","toc":[{"id":"signatureservice-signobject","text":"SignatureService::signObject()","level":2},{"id":"activityservice-request","text":"ActivityService::request()","level":2},{"id":"requestqueueservice-generaterequestqueue","text":"RequestQueueService::generateRequestQueue()","level":2},{"id":"cronqueue","text":"Cron\\Queue","level":2},{"id":"federated-events","text":"Federated events","level":2},{"id":"held-for-a-video","text":"Held for a video","level":2},{"id":"an-edit-can-add-recipients","text":"An edit can add recipients","level":2},{"id":"reading-edit-history","text":"Reading edit history","level":2},{"id":"activities-the-app-emits","text":"Activities the app emits","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"outgoing-flow","manual":false,"prev":{"path":"/docs/architecture-actor-identity","title":"Actor Identity"},"next":{"path":"/docs/architecture-incoming-flow","title":"Incoming Flow"},"parent":"architecture-activitypub-federation"},{"slug":"architecture-incoming-flow","path":"/docs/architecture-incoming-flow","title":"Incoming Flow","description":"spends the per-address bucket, before anything is read, and readBody() reads at most 1 MiB of body — refusing more with 413","group":"architecture","html":"<ol>\n<li>A remote instance POSTs to <code>/@{username}/inbox</code> or the shared <code>/inbox</code></li>\n</ol>\n<h2 id=\"inboxlimiter-assertallowed\">InboxLimiter::assertAllowed()</h2>\n<p> spends the per-address bucket, before anything is read, and <code>readBody()</code> reads at most 1 MiB of body — refusing more with <code>413</code></p>\n<h2 id=\"signatureservice-checkrequest\">SignatureService::checkRequest()</h2>\n<p> checks the <code>date</code> header for freshness, that <code>content-length</code> matches the body, that <code>digest</code> matches the body, and then the HTTP signature. It returns the verified origin host, or throws — a request whose signature does not verify never reaches step 4</p>\n<h2 id=\"fediverseservice-authorized\">FediverseService::authorized()</h2>\n<p> is called with that origin, then <code>InboxLimiter::assertOriginAllowed()</code> spends that origin&#39;s own, looser bucket. The per-origin ceiling is spent here rather than at step 2 because before step 3 the origin is only what the sender wrote</p>\n<h2 id=\"importservice-importfromjson\">ImportService::importFromJson()</h2>\n<p> parses the body into a typed object. A property that may be one value or a list (<code>attachment</code>, <code>tag</code>, <code>to</code>, <code>cc</code>, an actor&#39;s <code>alsoKnownAs</code>) is read through <code>ACore::listOf()</code>, so a single object or string counts as a list of one, and in <code>to</code>/<code>cc</code> the short spellings of the public collection, <code>as:Public</code> and <code>Public</code>, are read as its full IRI, and an <code>inReplyTo</code> that embeds the post it answers is read as that post&#39;s id; a document the models still cannot read — a <code>TypeError</code> inside one of them — is an <code>ActivityPubFormatException</code>, answered 400</p>\n<ol>\n<li>If the body carries a valid Linked Data Signature the origin is taken from it, otherwise the HTTP-signature origin is used — and then the key that signed the request has to be the activity&#39;s actor&#39;s own (<code>SignatureService::assertSignerSpeaksFor()</code>). When it is not, the activity is a forward with nothing to vouch for it and is handled by <code>ActivityPubController::acceptForwarded()</code> instead of steps 7–8: see <strong>Receiving a forward</strong> below</li>\n</ol>\n<h2 id=\"importservice-parseincomingrequest\">ImportService::parseIncomingRequest()</h2>\n<p> looks the handler up with <code>AP::getInterfaceForItem()</code> and calls <code>processIncomingRequest()</code>. Every exception from the handler is logged and swallowed</p>\n<ol>\n<li>The controller answers 200 and then drains the inbound stream queue for that request token</li>\n</ol>\n<h2 id=\"what-a-refused-delivery-is-answered-with\">What a refused delivery is answered with</h2>\n<p> The status is the only thing a peer reads to decide what to do next, and Mastodon re-queues a 5xx with backoff for about two days — so answering every rejection 500, which a catch-all used to do, turned one refused delivery into a dozen and made blocking an instance <em>multiply</em> its traffic. <code>ActivityPubController::statusForRejection()</code> maps the failure instead:</p>\n<h2 id=\"401\">401</h2>\n<p>Nothing about the request proves who sent it: no signature, one that does not verify, a replay, a <code>Date</code> outside the window, a <code>Signature</code> header missing its parts, or an activity whose actor is not the origin that signed for it (except a forwarded <code>Create</code>, <code>Update</code>, <code>Delete</code> or <code>Announce</code>, answered 202 — see <strong>Receiving a forward</strong>)</p>\n<h2 id=\"403\">403</h2>\n<p>The instance access list refuses this origin — a decision about who may talk to this instance, not a failure</p>\n<h2 id=\"400\">400</h2>\n<p>The bytes could not be read as an activity, or the <code>Date</code> could not be parsed. Redelivering the same bytes cannot help</p>\n<h2 id=\"404\">404</h2>\n<p>Addressed to a local actor that does not exist</p>\n<h2 id=\"429\">429</h2>\n<p>A rate limit, either bucket</p>\n<h2 id=\"503\">503</h2>\n<p>The signature could not be <em>checked</em>: the host holding the signing key was unreachable, or its last fetch failed recently enough to still be in backoff. This is the one rejection that invites a redelivery</p>\n<h2 id=\"500\">500</h2>\n<p>A fault of this instance&#39;s own, and nothing else</p>\n<p>An activity that is understood but has no handler is still answered 200 (see below), as is one whose signature says the key is gone.</p>\n<h2 id=\"a-delivery-that-arrives-twice\">A delivery that arrives twice</h2>\n<p> The replay guard in step 3 only knows the exact bytes it has seen; a peer&#39;s own retry is signed afresh, so it reaches the handlers, which look the row up before writing it and treat a hit as the delivery already taken in. A retry that overlaps the first copy — a Follow spends seconds between its lookup and its write, fetching the follower and delivering the Accept — passes that lookup too, so the follow, action and stream rows are written with the database&#39;s own &quot;skip if there&quot; insert (<code>insertIgnoreConflict</code>): the second copy finds its row refused, counts and notifies nothing, and for a Follow hears the Accept again.</p>\n<h2 id=\"receiving-a-forward\">Receiving a forward</h2>\n<p> The other end of §7.1.2: Mastodon passes a reply on to the followers of the post it answers, signed with its own user&#39;s key, and a reply written on a server that makes no Linked Data signatures (GoToSocial, Pleroma, Pixelfed, PeerTube, Lemmy and most others) arrives signed by somebody other than its actor with nothing on it to say the actor wrote it. That used to be a 401, which is final for the forwarder, so the reply never reached this copy of the thread. The body is still not believed, and is never stored: a <code>Create</code> or <code>Update</code> whose object is on its actor&#39;s own host — and not on this one — is answered <code>202</code> and the object is queued by its id as a <code>StreamQueue::TYPE_FETCH</code> item under a fresh token, drained inline like any other queue item. <code>StreamQueueService::fetchFromOrigin()</code> fetches it signed through <code>CurlService::retrieveObject()</code>, requires the document to carry the id it was fetched from and to be a post, sets the origin to the URL&#39;s host, and hands it to <code>ImportService::parseIncomingRequest()</code> as a <code>Create</code> of its <code>attributedTo</code> — or an <code>Update</code> when a stored copy exists and the fetched <code>updated</code> differs, and nothing at all when it does not — so the author-on-the-object&#39;s-host checks of <code>NoteInterface</code> apply to what that server served. An unreachable origin is retried by the queue. A forwarded <code>Delete</code> or <code>Announce</code> is answered <code>202</code> and dropped, the way Mastodon drops what it cannot verify; any other activity signed by somebody else is still a 401. The same fetch takes in a <code>Create</code> whose <code>object</code> is only an id, which the vocabulary allows and <code>CreateInterface</code> used to drop: the id is queued when it is on the host the activity came from and its actor is on.</p>\n<p><strong>Incoming activities that are actually acted on:</strong></p>\n<h2 id=\"create-note\">Create (Note)</h2>\n<p>Post is stored in <code>social_stream</code>, notification generated</p>\n<h2 id=\"update-note\">Update (Note)</h2>\n<p>Stored post is updated. It counts as an edit — a revision in <code>social_stream_rev</code>, an &quot;edited a post you boosted&quot; notification for local boosters — only when the text, the content warning, the sensitivity, the attachments or the poll&#39;s options changed: Mastodon sends <code>Update{Question}</code> as votes come in, without <code>updated</code>, and one carrying only new tallies just stores them and keeps the edit time the post had</p>\n<h2 id=\"update-person\">Update (Person)</h2>\n<p>Cached remote actor is refreshed</p>\n<h2 id=\"delete-note-person\">Delete (Note, Person)</h2>\n<p>Item is deleted; also handled when only an object id is given</p>\n<h2 id=\"follow\">Follow</h2>\n<p>Saved and auto-accepted — an <code>Accept</code> is queued straight back</p>\n<h2 id=\"accept-follow\">Accept (Follow)</h2>\n<p>Local follow row marked accepted</p>\n<h2 id=\"reject-follow\">Reject (Follow)</h2>\n<p>Local follow row deleted</p>\n<h2 id=\"undo-follow-like-announce-emojireact-block\">Undo (Follow, Like, Announce, EmojiReact, Block)</h2>\n<p>The wrapped relation or action is deleted. An <code>Undo</code> naming its object by id alone is resolved against what is stored (<code>ActivityObjectResolver</code>): a follow, a post, an action, an emoji reaction (by its id), a block (by the id of the <code>Block</code>, kept in <code>social_actor_relation.activity_id_prim</code>), a cached actor. A block stored before that column existed has no id to be found by, and is lifted only by an <code>Undo</code> that embeds the <code>Block</code></p>\n<h2 id=\"like\">Like</h2>\n<p>Stored as an action, notification generated</p>\n<h2 id=\"announce\">Announce</h2>\n<p>Stored as a boost, notification generated — unless the announced object is one this instance holds and is not public, in which case the activity is dropped. A boost carries the <em>booster&#39;s</em> audience, so storing it would republish a followers-only post to everyone the booster reaches; the local boost path has always refused to create one</p>\n<h2 id=\"quoterequest\">QuoteRequest</h2>\n<p>Somebody asks to quote a local post. Answered with an <code>Accept</code> carrying the approval, or a <code>Reject</code>, according to the post&#39;s own policy — see <strong>Quote posts</strong> below</p>\n<h2 id=\"accept-reject-quoterequest\">Accept / Reject (QuoteRequest)</h2>\n<p>The answer to a request of ours: the approval is written onto the quoting post, or the quote is marked rejected</p>\n<h2 id=\"move\">Move</h2>\n<p>The moving actor&#39;s relationships are repointed to the target actor — its followers, the accounts it follows, and the recipient rows of posts addressed to it or its collections — but only after the target actor (refreshed from its server) lists the moving actor in its <code>alsoKnownAs</code>; a Move whose target does not acknowledge the actor is refused. What the old account did stays its own, as on Mastodon: its posts, likes, boosts, reactions and documents keep their author, so its server can still edit and delete them, and an actor <code>Delete</code> of it removes them. The usual migration has the new account follow and be followed before the Move arrives, so a repointed row can meet one already there: a follow between the two accounts is dropped; for a follower of both, the follow of the new account stays (it is the id that account&#39;s server knows) and is accepted if either was; a follow the new account already made stays as it is, pending included, because its server waits for the Accept only the followed account here sends; a post addressed to both keeps one recipient row. All of it, with the moving actor&#39;s cached document marked <code>movedTo</code> the target (<code>CacheActorsRequest::markMoved()</code>), is one transaction, so a Move that fails leaves nothing half done and a retried one finds nothing left to move. <code>movedTo</code> is what the old profile here shows the redirect from — written from the Move, as Mastodon does, not fetched: the old server keeps serving the pre-move document for minutes (Mastodon caches the rendering for three). Local followers of the old account are then followed over to the new one, unless they already follow it or asked to</p>\n<h2 id=\"oauth-one-authorization-per-account\">OAuth: one authorization per account</h2>\n<p> <code>social_client</code> is the app registration — the name, the redirect URIs, the client id and secret — and nothing else. Everything about <em>who authorized it</em> is a row of <code>social_client_auth</code>: the code, the token, the scopes granted and the account they were granted to, unique on (client, account). Before that, the app row held one <code>auth_user_id</code> and one <code>token</code>, so an app registration belonged to exactly one person at a time and the second person to sign in with Elk or Phanpy — which register one app per instance — signed the first one out, silently. Re-authorizing replaces that account&#39;s row and nobody else&#39;s; revoking takes one authorization, where it used to take the app row&#39;s only token and sign out everybody; and the expiry sweep deletes authorizations rather than the whole <code>social_client</code> row, which used to take the app&#39;s registration with an idle token and make the client register again. A token stops working a year after it was idle (<code>TIME_TOKEN_TTL</code>, refreshed by use) and, however much it is used, <code>token_max_days</code> after it was granted (<code>ClientService::expiresAt()</code>; 365 by default) — use alone kept a token alive for ever. A code is spent in the same statement that writes the token, so two requests arriving together cannot both exchange it, and it is exchangeable only under the <code>redirect_uri</code> it was sent to (RFC 6749 §4.1.3), which <code>Version1000Date20261003000001</code> records on the row. Every read joins the app row, so the rest of the app still sees one <code>SocialClient</code> carrying both halves. A browser arriving from an OAuth app without a Nextcloud session is sent through Nextcloud&#39;s login page and returned to the same authorization URL, preserving the client&#39;s validated request before consent is shown.</p>\n<h2 id=\"notifications-that-are-not-activities\">Notifications that are not activities</h2>\n<p> Six of the nine notification types are an activity somebody sent — a Like, an Announce, a Mention, an Update, a Follow, a follow request — and <code>Stream::NOTIFICATION_TYPES</code> maps each to its Mastodon name. The other four are events this instance raises itself, with no ActivityPub verb behind them, so the subtype is this app&#39;s own name for the event: <code>poll</code> (swept by <code>PollService::announceClosedPolls()</code> from the cron, because a poll closes by its end time passing and nothing happens at the moment it does), <code>status</code> (the bell on a profile — a <code>notify</code> row in <code>social_actor_relation</code>, written by <code>POST /accounts/{id}/follow</code> with <code>notify</code>, and raised for local subscribers only since a remote one is told by their own server), <code>moderation_warning</code> (raised beside the Nextcloud notification a strike already sends, because a Mastodon client cannot see that one) and <code>severed_relationships</code> (raised by <code>DomainPurgeService</code> for the local accounts a block cuts off, counted <em>before</em> the purge because afterwards there is nothing left to count).</p>\n<h2 id=\"who-may-moderate\">Who may moderate</h2>\n<p> Nextcloud&#39;s own settings delegation, and nothing beside\nit. <code>AdminSettings</code> implements <code>IDelegatedSettings</code>, so an administrator can\nhand the Aloha Social section to a group under <em>Administration privileges</em>; the page\nthen opens for that group because core gates it on the delegation, the buttons\non it work because every <code>ModerationController</code> and admin <code>AnnouncementController</code>\nmethod carries <code>#[AuthorizedAdminSetting(settings: AdminSettings::class)]</code>, and\nthe Mastodon admin API agrees because <code>AdminApiService::isAdministrator()</code> asks\n<code>IManager::getAllowedAdminSettings(&#39;social&#39;, $user)</code>. Before this, moderating\nmeant administering the whole server — a great deal of power to hand somebody\nso they can act on a report — and a second list of moderators kept somewhere of\nthis app&#39;s own would have been one more thing to disagree with the page.\n<code>getAuthorizedAppConfig()</code> is deliberately empty: a delegate writes the\nretention period and the access list through the validating routes above, not\nthrough core&#39;s raw app-config endpoint. The check is asked of the <em>user id</em>,\nnever of the token: a scope on an OAuth token says only that some client asked\nfor it, since registration stores whatever scope string arrives.\nBeing a moderator is not being an administrator of the server, and nobody\nmoderates themselves: every write about an account — <code>ModerationController</code>&#39;s\ndecide/lift and forced-sensitive, the Mastodon admin API&#39;s <code>action</code>, <code>unsilence</code>,\n<code>unsuspend</code>, <code>unsensitive</code> and <code>DELETE</code>, and the Pixelfed admin app&#39;s user\nactions — first asks <code>AdminApiService::assertMayActOn()</code>, which refuses (403) an\naction on the caller&#39;s own account, and an action on a Nextcloud administrator&#39;s\naccount unless the caller is one too. A remote account has no Nextcloud user\nbehind it and is never refused there.</p>\n<h2 id=\"setup-checks\">Setup checks</h2>\n<p> The <code>OCP\\SetupCheck\\ISetupCheck</code> classes in <code>lib/SetupChecks/</code>, registered in <code>Application::register()</code> and shown in <strong>Administration → Overview</strong>: <code>WebFingerReachable</code> (the <code>CheckService::checkWellKnown()</code> probe, asked about the oldest live local account rather than about the viewer, who may never have opened Aloha Social), <code>CloudAddressMatches</code> (the stored <code>cloud_url</code> against what the server now reports, and the origin of <code>social_url</code>, which ids are minted from, against <code>cloud_url</code>), <code>CronRanRecently</code> (<code>Cron\\Queue</code>&#39;s last run, read off the job list), <code>OutboundQueueNotStuck</code> (abandoned rows, and standby rows last tried more than a day ago — past anything the retry schedule would wait on purpose), <code>ClientApiAtRoot</code> (whether <code>/api</code> and <code>/oauth</code> at the domain root reach the app), <code>ProxyForwardsTheScheme</code> (whether the proxy in front of those rules tells Nextcloud the scheme), <code>ReachableByStrictPeers</code> (https and a public name, which Pixelfed insists on), <code>UploadLimitsAgree</code> (PHP&#39;s upload ceilings against the app&#39;s own), <code>VideoConverter</code> (a warning when ffmpeg is missing, since iPhone <code>.mov</code> and HEVC videos then play neither on other servers nor in Chrome and Firefox; information when it is there and <code>video_transcode</code> is off) and <code>MemcacheConfigured</code> (what is kept in the database, off or recomputed without a memcache). <code>occ social:check:install</code> runs the first five as the same objects rather than a second copy of the logic, so the console and the settings page cannot drift apart; <code>--offline</code> leaves out the one that goes out on the network. Each links to <a href=\"/docs/admin\">Admin.md</a>, through <code>SetupChecks\\Docs</code> so a moved guide is one edit.</p>\n<h2 id=\"the-server-card\">The Server card</h2>\n<p> <code>ServerSettingsService</code> is the one place that reads and validates the instance-wide settings the page can reach. That includes the contact email and local contact account as well as media limits, inbox throttling, federation policy, and video processing. An account entered as the contact is resolved against the local Aloha Social actors table and stored by its Nextcloud user id; a remote account or a local team actor without a Nextcloud user is refused. <code>InstanceService</code> resolves the saved owner to its cached account on every <code>/api/v1/instance</code> and <code>/api/v2/instance</code> read, so clients see current account details, and a deleted account is omitted rather than breaking instance discovery. <code>ServerSettingsController</code> is deliberately <em>not</em> delegated: it carries no <code>AuthorizedAdminSetting</code>, so a group holding the Aloha Social section is refused, and <code>AdminSettings</code> does not render the card for one.</p>\n<h2 id=\"when-public-posts-have-no-remote-recipient\">When public posts have no remote recipient</h2>\n<p> A Public address is a visibility declaration, not a server-wide broadcast request. Outbound delivery resolves the author&#39;s followers, explicit mentions, and accepted relays; if none resolve to a remote inbox, the queue correctly creates no delivery rows. <code>ActivityService::request()</code> now records a notice with the actor, object, activity, and requested path types for that zero-inbox outcome. The author&#39;s Delivery status panel explains which audiences receive public posts and why a public status is not sent to every known peer. Deletes retain the post&#39;s original saved recipient paths and add the follower and booster/replier destinations, so a retraction follows the same paths that carried the original status. The first resolved remote path on a Delete is promoted for an inline attempt before the remaining fan-out is handed to the detached queue worker; this preserves asynchronous delivery for large audiences while avoiding dependence on self-queue dispatch for every remote copy.</p>\n<h2 id=\"the-audit-trail\">The audit trail</h2>\n<p> <code>AuditService</code> dispatches <code>OCP\\Log\\Audit\\CriticalActionPerformedEvent</code> for the decisions that are worth keeping longer than <code>social.log</code> keeps them: suspend, silence, lift, takedown, and an instance going on or off the access list. It is called from <code>ModerationService</code> and from <code>FediverseService::addAddress()</code>/<code>removeAddress()</code> rather than from the controllers, so the settings page, the Mastodon admin API and <code>occ social:fediverse</code> all record the same thing. A lift and a takedown also write a <code>social_strikes</code> row now (<code>Strike::LIFT</code>, <code>Strike::TAKEDOWN</code>) naming the acting moderator; both used to be an info line and nothing else. <code>Strike::COUNTED</code> is what the browser&#39;s strike column counts, and a lift is not in it.</p>\n<h2 id=\"moderation\">Moderation</h2>\n<p> <code>social_moderation</code> holds what the <em>instance</em> has decided about an account, as against <code>social_actor_relation</code>, which holds what one of its users has. Two levels: <code>silence</code> keeps the account reachable for its followers and drops it from the public and global timelines (<code>StreamRequest::filterSilencedActors()</code>, a small NOT IN rather than a join, because a moderator acts rarely); <code>suspend</code> deletes the account&#39;s streams and cached actor, makes <code>ImportService::parseIncomingRequest()</code> refuse everything it sends afterwards, and — for a local account — stops it acting at all: posting, editing, boosting, liking and following each ask <code>ModerationService::assertNotSuspended()</code> first, so the refusal holds for every entry point rather than for whichever controller was remembered — without that last part a suspension would undo itself the next time the account posted. Lifting removes the record; it cannot undo a deletion, and the admin panel says so before suspending.</p>\n<h2 id=\"admin-metrics\">Admin metrics</h2>\n<p> <code>MetricsService</code> answers Mastodon&#39;s three metric shapes — a measure (one number a day over a window), a dimension (the ranked list behind one number) and retention (how much of each month&#39;s new accounts is still posting later) — plus the three admin trend routes, which answer exactly what the public ones answer because a trend here is what the counts say and there is no review queue to report on. A key this instance cannot answer is <strong>refused with a 422 naming the ones it can</strong>, never answered with zeroes: most of Mastodon&#39;s keys describe a sign-up, an invite system, an email address or a media store this app does not own, and <code>0</code> reads as &quot;none&quot;, which is a different claim and the one an admin acts on. The window is snapped to whole days and capped at 370, because these are full scans of a date range rather than index probes. The SQL lives in the service in <code>protected</code> methods, as <code>AdminApiService</code>&#39;s does and for the same reason: what decides which question gets asked is then testable without a database. <code>active_users</code> counts accounts that <strong>posted</strong>, not accounts that logged in — this app has no session of its own to count.</p>\n<h2 id=\"blocks-that-are-about-an-address\">Blocks that are about an address</h2>\n<p> Mastodon keeps three lists for this — IP blocks, email-domain blocks, canonical email blocks — and all three exist to police a sign-up. This app has none of its own for internal users, whose account is a Nextcloud account the server decided to give them, and an optional one for <a href=\"/docs/architecture-external-users#external-users\">external users</a>. So two of the three are given the only meanings they can honestly have, and the third is not implemented rather than stored and never consulted. An <strong>IP block</strong> at <code>no_access</code> is enforced in <code>AccessBlockMiddleware</code>, which every request this app serves passes through — &quot;no access&quot; is a statement about the whole app, and a block that held on the inbox but not on the API, or on last month&#39;s routes but not on the ones added since, is not what an admin switched on; it answers <strong>403</strong>, so a peer stops redelivering. The two sign-up severities are refused at the API rather than stored. An <strong>email-domain block</strong> is checked in <code>AccountService::createActor()</code>: whether a Nextcloud account gets a fediverse identity at all, which is the same question Mastodon asks one step earlier. For a self-registered external user it is asked at the registration form too (<code>ExternalUserService::assertEmailAvailable()</code>), which is exactly Mastodon&#39;s question. An IP block at <code>no_access</code> covers the registration routes like every other route of this app. A <strong>canonical email block</strong> is a hash of the address of a deleted Mastodon account, kept so the same person cannot sign up again; nothing here holds an account&#39;s address after deletion, because the address is not this app&#39;s to hold. Ranges are matched on packed bytes (<code>inet_pton</code>) rather than on text, which is the only way <code>::1</code> and <code>0:0:0:0:0:0:0:1</code> are the same address and the only way a prefix that falls inside a byte means anything.</p>\n<h2 id=\"the-timeline-switcher\">The timeline switcher</h2>\n<p> <code>TimelineSwitcher.vue</code> sits above the posts on the three timelines that are the same place seen from three distances — the home timeline (<code>My Feed</code>), <code>timeline</code> (Local) and <code>federated</code> (Global) — and on no others: everywhere else it would be a switch between three places the reader is not. It routes rather than fetching, so <code>Timeline.vue</code> and the store go on being the single answer to &quot;which timeline is this&quot;. The values are the route&#39;s own words rather than the labels, because <code>timeline</code> is what the store calls the local one and <code>federated</code> the global one, and a second vocabulary in a component that only routes would be one more place for the two to disagree; <code>home</code> is the route with no <code>type</code> at all, so it is pushed as the bare route rather than as <code>type: &#39;home&#39;</code>, which names a timeline nothing serves. Local and Global have <strong>left the sidebar</strong>: they are scopes of the page the switcher sets rather than places of their own, and two entries that lead to the same list while saying it is somewhere else are two too many. The Home entry stays lit while either is being read — <code>isActive()</code> honours a <code>covers</code> list on a menu entry, which is the set of <code>type</code> params that entry owns — so the sidebar never shows nothing chosen.</p>\n<p>It is built from plain buttons rather than from <code>NcCheckboxRadioSwitch</code>, for the one thing that component cannot do: a single indicator that <em>travels</em> between the three. Three controls that light up tell you where you landed; one pill that slides tells you where you came from, which is what makes a switch feel like a switch. The cost is that the accessibility is hand-written rather than inherited, so it is written in full — a <code>radiogroup</code> of <code>radio</code> buttons, <code>aria-checked</code>, arrow keys in both axes that wrap at the ends, a roving tabindex so the control is one tab stop rather than three, and the focus following the selection the way it does in a radio group. The pill itself is <code>aria-hidden</code>: what it shows is already on the options. The track is 42px — 30 for an option, 3 of padding either side — which is a little under a Nextcloud button, because the control labels a timeline rather than competing with it. An option is as wide as its own words and does not shrink (<code>flex: 0 0 auto</code>); the track sits in a scroll container, so seven translated labels stay readable in a reading column and the edges fade where more options are off screen. The pill is measured off the option it sits under, and the chosen option is scrolled into view as it changes. The compact presentation is a container query on the control&#39;s own width, not the window: below 600px the labels go and the icons stay, so a phone gets it even when the window is wide and the column is not. The states are written as <code>.switcher .switcher__option</code> rather than as one class because the server styles bare <code>button</code> elements and its <code>button:not(.button-vue, [class^=&quot;vs__&quot;]):hover</code> is the more specific selector — left alone, Nextcloud&#39;s hover colour paints over the pill on the option you just chose. The movement — the slide, the overshoot, the kick the chosen icon gives, the turn the globe makes — is all inside <code>@media (prefers-reduced-motion: reduce)</code>, which switches every bit of it off.</p>\n<h2 id=\"what-a-switch-looks-like\">What a switch looks like</h2>\n<p> Changing scope changes the posts and nothing else. The scopes are one page to <code>pageOrder.js</code> (<code>isSamePage()</code>), so the view transition that animates a move between sidebar entries is not run for them: sliding the whole column moved the switcher out from under the pointer that had just used it. Once a scope is on screen, <code>Timeline.vue</code> waits a moment and has the store fetch the first page of each other scope, one after another (<code>prefetchTimeline()</code>); those pages join the remembered lists — five of them, which covers the four scopes and wherever the reader came from — and a switch puts one on screen in the same render, without a request. A page fetched ahead is put back for three minutes; older, the switch asks the server as before, holding the list being left on screen dimmed while it does. Entries that replace a list already on screen appear in place rather than rising in, and the Shorts bar, the weekly recap and the memories are kept alive (<code>&lt;KeepAlive&gt;</code>) while the reader is on another scope, so coming back to My Feed does not draw them from nothing and push the posts down when each one&#39;s request answers; the Shorts bar is read again on the way back only when it is more than a minute old.</p>\n<p>It chooses between whatever it is given rather than between three timelines it knows about: each option carries a <code>value</code>, a label, an icon and the route it stands for, and the component routes and animates. That is why a <strong>profile</strong> carries the same control — Posts, Photos and Videos are the same shape of choice, one account seen three ways rather than three places — and why the words in those routes are the route&#39;s own (<code>timeline</code>, <code>federated</code>, <code>image</code>, <code>video</code>) rather than the labels beside them.</p>\n<h2 id=\"new-post\">New post</h2>\n<p> The one thing in the sidebar that is not a place to go, so it is not a row among rows: an <code>NcButton</code> in the primary colour across the width of the sidebar, above the places. It carries the app&#39;s resting elevation, lifts on hover, presses in, gives its <code>+</code> a disc that kicks the way the switcher&#39;s icons do, and lets one band of light cross it on the way in — all of it inside <code>prefers-reduced-motion: reduce</code>, which switches every bit of it off. It was an <code>NcAppNavigationItem</code> with no <code>to</code>, which renders <code>href=&quot;#&quot;</code> and needed a <code>.prevent</code> to stop the bare fragment becoming a history entry; a button has nowhere to go by construction. <code>NcButton</code> rather than a bare <code>&lt;button&gt;</code> because the server&#39;s own rules for bare buttons all exclude <code>.button-vue</code>: a hand-rolled one has to win an argument with them in every state, and loses the pressed one — Nextcloud&#39;s <code>button:not(.button-vue, [class^=&quot;vs__&quot;]):not(:disabled, .primary):not(.app-navigation-entry-button):active</code> sets the background back to the page colour, and outspecifies anything a single class can say. Its class is <code>navigation__compose</code> rather than <code>new-post</code>, which the composer card already is.</p>\n<h2 id=\"explore\">Explore</h2>\n<p> One <code>NcAppNavigationItem</code> with <code>allowCollapse</code> holding three\nkinds of child: the hashtags the reader follows, their lists, and what the\ninstance is trending. It replaced two captions that each grew without limit —\nsomebody who follows forty tags pushed their own feed off a laptop screen —\nand, since 0.26.70, the trending section that used to sit above it as a caption\nof its own. The three are not equal and the order says so: a followed tag and a\nlist were <em>chosen</em>, a trending tag is merely popular, so trending fills what is\nleft after the chosen ones have their places (<code>chooseEntries()</code> in\n<code>src/utils/explore.js</code>) and never takes a place from them. A trending tag the\nreader already follows is dropped rather than drawn twice under the same name.\nHow many children fit is measured from the rail rather than assumed:\n<code>measureRail()</code> reads the space between where the children start and where the\nrail ends, takes the row pitch from two consecutive rows (<code>offsetHeight</code> misses\nthe margins), and re-measures on a <code>ResizeObserver</code> — so it copes with browser\nzoom, a denser theme and an error entry appearing. <code>entriesThatFit()</code> is the\nanswer for the first paint and for jsdom, before there is anything to measure.\nThe open/closed state is a <code>localStorage</code> key, and the entry carries no icon of\nits own so that the chevron is the only thing before the word and the children\nline up under it.</p>\n<h2 id=\"the-account-at-the-bottom\">The account at the bottom</h2>\n<p> The way out of every app in Nextcloud is the thing at the foot of the sidebar with your face on it, so the Aloha Social sidebar ends the same way: the <strong>More</strong> menu hangs off the reader&#39;s own account — their portrait, and the name they publish under — rather than off the word &quot;More&quot; next to a cog. <code>NcAppNavigationSettings</code> renders that cog from a hard-coded path and offers no slot to replace it, so the picture is handed to the stylesheet as <code>--social-face</code> and set as the icon box&#39;s background with the glyph hidden inside it. The picture comes from the server&#39;s own avatar endpoint rather than from the account&#39;s <code>avatar</code> field, because that endpoint answers for every account — generated initials when nobody has uploaded anything — so the button is never a blank circle, and it is the same face the rest of Nextcloud shows.</p>\n<p>The account used to be a row of its own above the footer. It is not one any more, because it would be the same face twice. <strong>My profile</strong> opens Nextcloud&#39;s native <code>/u/{uid}</code> page, where the Aloha Social posts section uses Nextcloud&#39;s profile layout. <strong>Aloha Social profile</strong> sits immediately below it when the reader has an Aloha Social actor; it opens the app&#39;s own <code>@{acct}</code> profile, whose edit dialog manages the ActivityPub display name, bio, metadata links and banner. Keeping both links makes the native profile experience and the Aloha Social-specific editing controls independently reachable.</p>\n<p>The account used to be a row of its own above the footer. It is not one any more, because it would be the same face twice. <strong>My profile</strong> opens Nextcloud&#39;s native <code>/u/{uid}</code> page, where the Aloha Social posts section uses Nextcloud&#39;s profile layout. <strong>Aloha Social profile</strong> sits immediately below it when the reader has an Aloha Social actor; it opens the app&#39;s own <code>@{acct}</code> profile, whose edit dialog manages the ActivityPub display name, bio, metadata links and banner. Keeping both links makes the native profile experience and the Aloha Social-specific editing controls independently reachable.</p>\n<h2 id=\"migration\">Migration</h2>\n<p> A page of the app&#39;s own, in the menu behind the account, for taking your data out and putting it back. Nextcloud can already export a whole account with <code>SocialMigrator</code> in it, but only if the admin installed the user migration app and only from <code>occ</code> or that app&#39;s page; taking a copy of what you wrote should not depend on either. <code>MigrationArchiveService</code> therefore drives <strong>the same migrator</strong> into a zip a person can download, and reads one back — so what travels, and what deliberately does not (the private key, above all: see the class comment on <code>SocialMigrator</code>), is decided in one place for both. <code>ZipExportDestination</code> and <code>ZipImportSource</code> are the two adapters that make a zip look like the framework&#39;s <code>IExportDestination</code> and <code>IImportSource</code>; they implement what the migrator actually calls and refuse the rest — <code>copyFolder()</code> throws rather than quietly producing an archive that claims to hold files it does not. <code>ZipStreamDestination</code> is a third, for &quot;Download your Bluesky account&quot;: a zip written while it is sent (<code>ZipStreamWriter</code>, through <code>StreamedWriterResponse</code>), so the download starts at once and is never whole on disk or in memory. A file added as a stream is copied to a temporary file and handed to <code>ZipArchive::addFile()</code> rather than read into a string: what arrives that way is as often a video as an outbox, and <code>stream_get_contents()</code> of a two-gigabyte upload is two gigabytes of memory. Reading back is bounded the same way: a file the migrator reads whole (the profile, the lists, <code>outbox.json</code>) is refused past <code>ZipImportSource::MAX_FILE_BYTES</code> (128 MB) before it is read, and a media file is copied out no further than the largest file this instance stores (<code>CacheDocumentService::largestFileBytes()</code>, the video ceiling), so a crafted entry cannot fill memory or the temporary directory. The file names are the migrator&#39;s, so an archive from this page and one from <code>occ user:export</code> are interchangeable; the extra <code>social/export.json</code> names the app version, the account and the migrator version, and an archive that holds the data but no manifest is read as version 1, which is what the server&#39;s own exporter wrote.</p>\n<p>The import is <strong>additive</strong>: the profile, follows, blocks, mutes, bookmarks and favourites are restored alongside what is already there, and the posts in <code>outbox.json</code> are reported rather than re-published, so importing cannot flood the timelines of people who follow you. An archive with no <code>social/actor.json</code> is refused by name, because the likeliest mistake is picking the wrong zip.</p>\n<h2 id=\"every-import-runs-in-the-background\">Every import runs in the background</h2>\n<p> <code>ImportQueueService::queue()</code> copies the upload into appdata, writes a <code>social_import</code> row and adds a <code>Cron\\RunImport</code> for it; the request answers 202 with the row, and the page polls <code>GET /api/v1/migration/imports</code> while anything is <code>queued</code> or <code>running</code>. The job hands the kept file to the very same <code>MigrationService</code> and <code>PostImportService</code> calls the request used to make, now with a progress callback that writes <code>done</code>/<code>total</code> to the row every ten items or two seconds, so what an import does and what it federates is decided where it always was. The posts importer runs uncapped there (<code>$limit = 0</code>): the 2000-a-run cap kept a request within its time limit, and a job has none. One import of a kind at a time per account, so a second press of the same button is a 409 rather than the same file twice; a failure is a status and a reason on the row, never an exception out of a cron job; and the kept upload is deleted once read, whatever happened.</p>\n<h2 id=\"moving-here-from-the-old-handle\">Moving here from the old handle</h2>\n<p> <code>MoveInService</code> is the first thing on the page for somebody arriving from another server, and it starts from the one thing they are sure to know: the handle. <code>inspect()</code> resolves it (<code>MigrationService::resolveActor()</code>, WebFinger or actor id), fetches the old account&#39;s <code>following</code> collection and <code>outbox</code>, and says what each holds and whether it can be read — a server that hides a collection answers a count and no <code>first</code> page, which is Mastodon&#39;s &quot;hide your social graph&quot; and Pixelfed always, and the page then points at the file import instead of letting a run come back empty. <code>prepare()</code> sets the <code>alsoKnownAs</code> alias synchronously, because it federates nothing and is what the old server will demand before it accepts a <code>Move</code>, and hands the queued run its options. The run (<code>ImportQueueService</code> → <code>MoveInService::run()</code>) walks both collections page by page (<code>first</code>, then <code>next</code>, capped at 5000 entries and 500 pages each, keeping what was read when a page stops answering), follows each account through <code>FollowService::followActor()</code> exactly as the CSV import does, and hands the outbox items to <code>PostImportService::importItems()</code> — the archive importer&#39;s own parsing and writes over a collection already in hand, so a boost or a direct message is skipped, a post brought over from an archive earlier is <code>already</code>, and nothing is federated. What the wizard cannot do is move the followers: that is the old server&#39;s <code>Move</code>, and the page names the menu it is in once the run is done.</p>\n<h2 id=\"moving-away-is-the-persons-own-with-what-stands-in-front-of-it\">Moving away is the person&#39;s own, with what stands in front of it</h2>\n<p> <code>POST /api/v1/migration/move</code> is what <code>occ social:account:move</code> does — <code>MigrationService::move()</code>, the <code>Move</code> to every follower&#39;s inbox and <code>movedTo</code> on the actor — behind Nextcloud&#39;s <code>#[PasswordConfirmationRequired]</code>, the own handle typed back, and the target&#39;s <code>alsoKnownAs</code> checked against a fresh fetch. Thirty days between moves (<code>COOLDOWN_SECONDS</code>, Mastodon&#39;s), recorded as the <code>moved_at</code> user value when a move goes out; the command skips the cooldown, since an administrator can judge why, and the button cannot. <strong>A moved account behaves moved</strong>: <code>ModerationService::assertNotMoved()</code> refuses a post, an edit and a follow from a local actor with <code>movedTo</code> set (<code>AccountMovedException</code>, a <strong>403</strong> — the request was fine, the account may not), the sidebar takes the compose button away and says where the account went, and the profile shows the redirect every other server shows, for a local and a remote moved account alike (the account entity&#39;s <code>moved</code>). <code>DELETE /api/v1/migration/move</code> clears <code>movedTo</code> and nothing else: the followers do not come back, because their servers acted on the Move, and the cooldown stays, because the move happened.</p>\n<h2 id=\"between-two-aloha-social-servers-the-last-step-is-done-from-the-new-side\">Between two Aloha Social servers the last step is done from the new side</h2>\n<p> A <code>Move</code> is sent by the old server and Mastodon has no API for it, so a person moving from Mastodon always ends in Mastodon&#39;s own form. Another instance of this app is an OAuth server like any Mastodon, so <code>MoveFinishService</code> has the new instance register itself there as an application (<code>POST /api/v1/apps</code>) asking for <strong>one scope, <code>write:migration</code></strong>, sends the person to the old instance&#39;s consent page (where they log in to their <em>old</em> Nextcloud), and with the code they come back with (<code>GET /migration/move-in/callback</code>, checked against a random <code>state</code> kept on the user for fifteen minutes) exchanges a token at <code>/oauth/token</code> and calls the old instance&#39;s <code>POST /api/v1/migration/move/authorized</code> naming this account. That route (<code>MigrationApiController</code>, a <code>ClientApiController</code>) performs <code>MigrationService::move()</code> exactly as the button does — cooldown, the target&#39;s <code>alsoKnownAs</code> checked — but accepts the scope <strong>spelled out only</strong>: the base class takes the broad <code>write</code> for any <code>write:*</code>, and <code>write</code> is what every phone app holds, so a token that can post must not be a token that can move the account away; a session without a token is refused too, because the button, with its password step, is for sessions. The old server is recognised by its NodeInfo <code>software.name</code> (<code>Application::SOFTWARE_NAME</code>), which <code>MoveInService::inspect()</code> reports as <code>finishable</code> and <code>prepare()</code> keeps with the run, so the finished row can offer the button. The outcome is kept on the user (<code>move_finish</code>) for the page the person lands back on. The HTTP calls go through <code>CurlService</code>, so the federation and local-address guards apply to the old server&#39;s address as to any other.</p>\n<p>The third part of the page is about arriving from somewhere else, and it is deliberately honest about what that means: what travels between servers is the <strong>list of people you follow</strong>, because a follow is a relationship two servers agree on rather than a row in a file. <code>POST /api/v1/migration/follows</code> re-follows each handle in a <code>following_accounts.csv</code> — the file Mastodon, Pixelfed, GoToSocial and Akkoma all export, and the one in this app&#39;s own archive — through the ordinary follow path. The networks that do not federate are named as such rather than promised. Moving a whole account is not a button: a <code>Move</code> federates to every server that knows you and cannot be undone, so the page points at <code>occ social:account:alias</code> and <code>occ social:account:move</code>.</p>\n<p>The fourth part brings the <strong>posts</strong>, which is the thing a <code>Move</code> has never carried, and <code>PostImportService</code> is where the rules of that live: each post is written as a <em>new local post</em> of the importing account (<code>StreamRequest::save()</code>, never the delivery path — not one request is queued, because re-publishing somebody&#39;s five years of posts would put five years of posts into every follower&#39;s timeline in one afternoon), dated when it was written, with its pictures through the ordinary upload path so an imported picture is stripped of its metadata like any other. The original id is remembered in <code>social_import_post</code>, which makes a second run of the same file a no-op and lets a reply find its parent. Five shapes are read: this app&#39;s archive, Mastodon&#39;s and GoToSocial&#39;s, a bare <code>outbox.json</code>, Pixelfed&#39;s <code>pixelfed-statuses.json</code>, and <strong>Instagram&#39;s</strong> &quot;Download your information&quot; — the one most people arrive at Pixelfed by. Instagram&#39;s archive has no ids, no visibility and no hashtags as data, so an id is derived from the file a post carries, the importing account&#39;s <strong>own default visibility</strong> is used for every post in the run, 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, guarded so that a caption genuinely containing an accented character is left alone. <code>stories.json</code>, <code>archived_posts.json</code> and <code>recently_deleted_content.json</code> are deliberately not read: an importer that quietly republished what somebody put away would be worse than one that imported nothing.</p>\n<p>The exports, the imports and moving in are <strong>client-API routes</strong> (<code>ClientApiController</code>), so a client app reaches them with the token it signed in with: the whole archive asks for the broad <code>read</code>, one list as CSV for the scope that reads that list, and every import and the move-in for the broad <code>write</code>. Moving away and undoing it stay session routes, behind Nextcloud&#39;s password confirmation. The export answers with a <code>DataDisplayResponse</code> whose <code>Content-Disposition</code> is set after construction — <code>DataDownloadResponse</code> builds that header through Symfony&#39;s <code>HeaderUtils</code>, a class the server has and this app does not depend on, so the download would work on a server and be untestable here.</p>\n<h2 id=\"writing-a-posts-recipients-once\">Writing a post&#39;s recipients once</h2>\n<p> A post names the same account more than once as a matter of course: <code>Item::getToAll()</code> returns <code>to</code> alongside <code>toArray</code>, the author is appended to the <code>to</code> side, and an account addressed in both <code>to</code> and <code>cc</code> appears in each. The unique index <code>sat</code> is on <code>(stream_id, actor_id, type)</code> <em>without</em> the subtype, so every one of those is the same row. They used to be sent to the database one at a time and refused there. <code>insertIgnoreConflict()</code> keeps a refusal from failing the transaction the save runs in, but InnoDB allocates the auto-increment value before it notices the conflict, so each duplicate burned an id and dirtied the index that was about to reject it — on a development instance <code>social_stream_dest</code> had reached 882,837 ids for 4,976 live rows, with a 20 MB index over 1 MB of data. <code>StreamDestRequest::uniqueRecipients()</code> now names each account once before any of them is written, and the first subtype to name an account wins, which is the row the database kept when the duplicates were still being sent. What is left goes in as one multi-row conflict-skipping insert per post (<code>CoreRequestBuilder::insertIgnoringConflicts()</code>), row by row only on a database other than MySQL/MariaDB, PostgreSQL and SQLite.</p>\n<h2 id=\"reading-a-timeline-in-two-queries\">Reading a timeline in two queries</h2>\n<p> A page is chosen as a list of <code>nid</code>s and the rows are fetched afterwards by id — <code>getStreamNidsSelectSql()</code> then <code>streamsByNids()</code>. The reason is the recipient join: a post can match <code>social_stream_dest</code> more than once, so the page query needs <code>SELECT DISTINCT</code>, and a <code>DISTINCT</code> over the full stream column set makes the database sort or hash several kilobytes a row to deduplicate integers. Two rules keep that honest. First, a page query <strong>joins</strong> the cached actor without selecting it (<code>joinCacheActors()</code>), because it only needs the author to constrain on, never to read. Second, <code>DISTINCT</code> is asked for only where a page can actually duplicate: <code>social_stream_dest</code> is unique on <code>(stream_id, actor_id, type)</code>, so a query that fixes the actor and the type — public, notifications, direct messages, the marked timelines — cannot match a post twice and selects without it. The home timeline does duplicate, by design, and keeps it. <code>getNidsFromRequest()</code> also deduplicates the twenty integers in PHP, which covers the one case the unique index does not: the left join on expired mutes can match twice for a viewer who timed-muted both a booster and the account they boosted.</p>\n<h2 id=\"a-domain-block-is-not-a-join\">A domain block is not a join</h2>\n<p> The viewer&#39;s blocked instances are read once per request (<code>CoreRequestBuilder::blockedDomainsOf()</code>, memoised and dropped when <code>DomainBlockService</code> writes one) and compared as constants in the <code>WHERE</code>. It used to be a <code>LEFT JOIN</code> against the block table whose <code>ON</code> clause held four <code>LIKE</code>s against <code>LOWER(attributed_to)</code>, evaluated for every candidate row of every timeline read — including for the overwhelming majority of accounts, who have blocked nothing and now add no clause at all. Each is compared with <code>author_host</code> — the lower-cased host of the author&#39;s actor id, which <code>saveStream()</code> writes beside <code>attributed_to</code> (<code>DomainBlocksRequestBuilder::authorHostOf()</code>) — as one <code>NOT IN</code>, for the post and for the post it boosts. A row stored before the column has it NULL until <code>Cron\\StreamAuthorHosts</code> reaches it; until that job sets <code>stream_author_hosts_filled</code>, such a row is matched by the old patterns (<code>domainPatterns()</code>: the exact host, both schemes, closed by the <code>/</code> that ends it) instead. What a block matches is the exact host either way, whatever port the id names. A subdomain is a separate block, which is what <code>DomainBlockTimelineTest</code> pins — the silenced-instance filter next door reads subdomains, and the two are easy to confuse.</p>\n<h2 id=\"the-moderation-panel\">The moderation panel</h2>\n<p> The Aloha Social section of the administration settings is one Vue application (<code>src/adminSettings.js</code>, components in <code>src/components/admin/</code>), built out of the same <code>NcTextField</code>, <code>NcSelect</code>, <code>NcCheckboxRadioSwitch</code>, <code>NcButton</code>, <code>NcNoteCard</code> and <code>NcDialog</code> components as the rest of the administration settings. <code>AdminSettings.vue</code> describes its sections as data — id, group, icon, title, a one-line description, search keywords, the component and its props — because the group list, the search, the Needs attention list and the page all need the same names; the section components draw only their body. One of six groups is shown at a time, <code>#&lt;section id&gt;</code> in the address opens the group a section is in, and the Needs attention list is computed from the initial state alone (open reports, the review total, sign-ups awaiting approval, the federation and background summaries), so it costs no request. <code>templates/settings/admin.php</code> is the element it mounts on and nothing else; what the server knows when it renders — the first page of the open reports, the resolved count, the federation summary, the access list, the retention window and, for an administrator proper, the Server card — travels as initial state from <code>AdminSettings::getForm()</code>, in the same shape the routes answer in, so a row that arrived with the page and one fetched afterwards are the same thing to the table that draws them. It was three hand-written plain-DOM scripts, on the reasoning that mounting Vue on a server-rendered page would pull the runtime into a page that had none; the shared <code>social-framework</code> chunk ended that, and the page had stopped looking like the rest of the administration settings. The account browser reads <code>GET /moderation/accounts</code>, which is <code>AdminApiService::accountPage()</code> — the same read the Mastodon admin API answers — narrowed to the six fields a table draws; before it, only a <em>reported</em> account could be acted on from the web, and everything else needed a moderation client and a token. Nothing on the page uses <code>v-html</code>, and <code>tests/js/components/admin/AdminSettings.test.js</code> pins that: a handle, an instance name and the comment on a report are whatever a remote server sent, and this is the page whose buttons delete accounts.</p>\n<h2 id=\"custom-emoji\">Custom emoji</h2>\n<p> <code>/api/v1/custom_emojis</code> answered <code>[]</code> unconditionally and outbound posts carried no <code>Emoji</code> tags, so emoji from every other instance rendered here and this one could publish none — the asymmetry somebody moving here notices first, because their own instance&#39;s emoji stop working. <code>EmojiService</code> holds the set: the row is in <code>social_emoji</code>, the picture in appdata under <code>emoji/</code>, and both a local client and a remote server dereference the same URL (<code>/emoji/{shortcode}</code>, unauthenticated like <code>/media/{uuid}</code> and for the same reason). What a post carries is the shortcode as text plus an <code>Emoji</code> tag saying where the picture is, added by <code>StreamService::addCustomEmojis()</code> on creation <em>and</em> on edit — rebuilt rather than appended to, so an edit that removes a shortcode removes its tag. The scan is Mastodon&#39;s own pattern: a colon on each side, neither of them against a word character or another colon, which is what stops <code>12:30:45</code> carrying an emoji called <code>30</code>. A shortcode this instance has no picture for stays the text it already was. Managed with <code>occ social:emoji</code>.</p>\n<h2 id=\"strikes\">Strikes</h2>\n<p> <code>social_moderation</code> is what stands <em>now</em>: one row an account, replaced by the next decision and deleted when it is lifted. <code>social_strike</code> is the history it used to throw away. Every <code>ModerationService::decide()</code> writes one, <code>warn()</code> writes one that applies nothing — Mastodon&#39;s <code>none</code>, and the step the ladder was missing between doing nothing and taking an account out of the timelines — and nothing removes one. A lift says the decision no longer stands, not that it was never taken; without that, the third silence in a month looked exactly like the first, because whoever lifted the last one took the only evidence it had happened. A strike carries the moderator who took it and the report it came from, so a history names somebody. The account is told through Nextcloud&#39;s notifications (<code>moderation_warning</code> in <code>Notifier</code>), and only a <strong>local</strong> account can be: telling a remote one means telling its instance, and no ActivityPub activity says &quot;your user has been warned&quot;. The count is what the account browser shows and the history is what opens behind it; <code>StrikesRequest::countForActors()</code> answers a whole page in one query, because asking per row turned a forty-account page into forty-one.</p>\n<h2 id=\"silencing-an-instance\">Silencing an instance</h2>\n<p> The same middle tier, applied to a whole server. A domain block (<code>social:fediverse add</code>, followed by <code>social:domain:purge</code>) cuts the instance off in both directions and deletes what it already sent, which also cuts off the local users who deliberately follow somebody there — so the tool was too blunt to reach for and the nuisance stayed. <code>social:fediverse silence &lt;host&gt;</code> adds the host to a second list (the <code>silenced_list</code> app value, read by <code>FediverseService::getSilencedAddresses()</code>) and changes exactly one thing: <code>StreamRequest::filterSilencedInstances()</code> drops the instance&#39;s posts from the <strong>public</strong>, <strong>global</strong>, <strong>hashtag</strong> and <strong>followed-tag</strong> timelines. Delivery, fetching, webfinger, following, and the home timeline of somebody who already follows the account are untouched — a silence is deliberately not enforced in <code>authorized()</code>. The clause is on <code>s.author_host</code>: the host itself by <code>NOT IN</code>, and everything under it by a <code>NOT LIKE &#39;%.&lt;host&gt;&#39;</code> suffix, read the way a domain block reads subdomains — a comparison against a short column rather than a scan of the id&#39;s text, but a suffix is still not indexed, which is why it runs only on the timelines that need it and why the list is meant to stay an admin-written handful. A row <code>Cron\\StreamAuthorHosts</code> has not reached yet is matched by its id as a prefix instead, as it always was. The silenced <em>accounts</em> beside it (<code>ModerationRequest::getActorIdsAt()</code>) are read through the distributed cache, dropped whenever a moderation decision is written. Nothing is deleted, so <code>social:fediverse unsilence</code> brings the posts back — the difference between this and a block, whose purge does not come back.</p>\n<h2 id=\"inbox-forwarding-activitypub-7-1-2\">Inbox forwarding (ActivityPub §7.1.2)</h2>\n<p> A reply to a local post arrives from the replier&#39;s instance and from nowhere else, so the followers of the local post would never see it: everyone would read a different, shorter thread. <code>ForwardService::forwardReply()</code> therefore passes such a reply on to the followers of the post it replies to, and <code>NoteInterface::activity()</code> offers it every newly stored note (a re-delivery finds the note already stored and is not offered again, so nobody is sent the same reply twice).</p>\n<p><strong>Edits out of order.</strong> Edits are delivered out of order as readily as anything else, so <code>NoteInterface</code> drops an <code>Update</code> whose <code>updated</code> is earlier than the one already stored, as Mastodon does; an edit without a date, or of a post never edited, is applied as before.</p>\n<h2 id=\"a-delete-that-overtakes-its-create\">A Delete that overtakes its Create</h2>\n<p> A <code>Delete</code> that finds nothing to delete is remembered for six hours in <code>DurableCache</code> (<code>DeleteInterface::EARLY_DELETE_NAMESPACE</code>), keyed by the object and holding the deleting actor; a <code>Create</code> of that object by that same actor in that time is dropped (<code>DeleteInterface::deletedBeforeArrival()</code>), as Mastodon drops one, so a late Create cannot put back a post its author already took down.</p>\n<p>A reply is forwarded only when all of this holds: it arrived with a <strong>valid linked-data signature</strong> (<code>SignatureService::ORIGIN_SIGNATURE</code>), because the recipients must be able to check the author&#39;s own signature rather than take our word for it; the post it replies to is <strong>local</strong>, since only the instance holding a post owes its followers the thread; and both the reply and the post are <strong>public or unlisted</strong>, so a private audience is never widened. The body sent is <code>getSource()</code> — the document exactly as it arrived, since re-encoding our model of it would drop the signature and change what was signed. Delivery goes through the normal request queue at <code>PRIORITY_LOW</code> via <code>RequestQueueService::generateRequestQueueFromSource()</code>, so nothing about it holds up the inbox response. The sender&#39;s instance and this one are left out of the recipient list.</p>\n<h2 id=\"add-and-remove\">Add and Remove</h2>\n<p> are handled by <code>FeaturedCollection</code>, which is how a remote account&#39;s pinned posts arrive: the activity&#39;s <code>object</code> is resolved against the local store (Mastodon sends a bare URI, not an embedded object), <code>target</code> must be the actor&#39;s own <code>featured</code> collection, and the post must be one this instance holds and that actor authored. A pin is stored as an action row, capped at <code>MAX_REMOTE_PINS</code>. <code>BlockInterface</code> records the incoming block as an <code>ActorRelation</code> of type <code>TYPE_BLOCKED_BY</code>.</p>\n<h2 id=\"actor-types\">Actor types</h2>\n<p> <code>Person</code>, <code>Service</code>, <code>Group</code>, <code>Organization</code> and <code>Application</code> all resolve to a handler, so all five are cached and can be followed — which is what Lemmy communities, Friendica and a.gup.pe groups, and Mastodon&#39;s instance and relay actors need. <code>OrderedCollection</code> and <code>Stream</code> have no handler, being containers rather than things an activity is about.</p>\n<p>An activity whose type this app does not implement is logged at <code>notice</code> with its type, activity id, object id, actor and origin, and answered <code>200 OK</code> so the sender does not redeliver it forever. It used to be discarded without a word, which made &quot;posts from that instance never arrive&quot; impossible to diagnose from this side.</p>\n<h2 id=\"tombstone\">Tombstone</h2>\n<p> has no interface either, and deliberately so: it names a deleted object rather than being one. <code>DeleteInterface</code> handles it by id — when an embedded object has no handler it looks the id up as a note, then as an actor, the same path a <code>Delete</code> carrying a bare id string takes. This is how a deletion from Mastodon, which sends <code>Delete</code> with an embedded <code>Tombstone</code>, is applied. Aloha Social sends the same shape. The note row is removed under a guard on its type, which is <code>Question</code> for a poll and <code>Note</code> for everything else a post is stored as.</p>\n<p>An incoming <code>Block</code> targeting a local user is remembered as a <code>blocked_by</code> relation and severs the follow relationship in both directions; <code>Undo{Block}</code> lifts it. A block between two accounts of this instance never arrives as an activity, so <code>RelationshipService::block()</code> writes the same <code>blocked_by</code> row for a local target itself and <code>unblock()</code> removes it. A <code>Follow</code> from an actor the target has blocked is answered with a <code>Reject</code>.</p>\n<p>A Bluesky account&#39;s block of a local one is a record in the blocker&#39;s repository that nothing delivers, so <code>Service\\BlockedBy\\BlockedByService</code> learns it through a <code>BlockedBySource</code> — today <code>Atproto\\Reader\\BlueskyBlockedBy</code>, which asks the AppView as the local account (<code>app.bsky.actor.getProfiles</code> → <code>viewer.blockedBy</code>) — and writes the same <code>blocked_by</code> row, so the readers of that row need nothing of their own. It asks before a reply, quote or follow (in the request), before a like, repost or new post&#39;s mentions go out (in <code>Cron\\AtprotoPublish</code>), and for the one account a relationship is asked about; an answer is believed for five minutes (<code>DurableCache::setShared</code>, since the queued job and the web request share it). Profile batches are isolated: a failed AppView batch is left unanswered while successful batches are retained, so the existing relation remains the fallback for unknown results. The reads already made as the person (custom feeds, post search, suggestions, starter packs) pass their answer to <code>BlueskyBlockedBy::learn()</code>, and <code>JetstreamEvents</code> records a watched account&#39;s <code>app.bsky.graph.block</code> of a local DID at once and asks again, through <code>BlockedByService::recheck()</code>, about the local accounts a blocker held when one of its block records is deleted. <code>BlockedByService::record()</code> writes only what changed and bumps the local account&#39;s timeline revision when it does. <code>assertMayReply()</code> (the post&#39;s author and, for a Bluesky post, its thread&#39;s first author) and <code>assertNotBlocked()</code> throw <code>BlockedByException</code>, an <code>InvalidActionException</code> the client API answers 403 with the reason; <code>PostService</code> checks a reply before the thread gate and the reply rule and a quote before the post gate, and <code>FollowService::followActor()</code> checks a new follow, whatever network the account is on.</p>\n","toc":[{"id":"inboxlimiter-assertallowed","text":"InboxLimiter::assertAllowed()","level":2},{"id":"signatureservice-checkrequest","text":"SignatureService::checkRequest()","level":2},{"id":"fediverseservice-authorized","text":"FediverseService::authorized()","level":2},{"id":"importservice-importfromjson","text":"ImportService::importFromJson()","level":2},{"id":"importservice-parseincomingrequest","text":"ImportService::parseIncomingRequest()","level":2},{"id":"what-a-refused-delivery-is-answered-with","text":"What a refused delivery is answered with","level":2},{"id":"401","text":"401","level":2},{"id":"403","text":"403","level":2},{"id":"400","text":"400","level":2},{"id":"404","text":"404","level":2},{"id":"429","text":"429","level":2},{"id":"503","text":"503","level":2},{"id":"500","text":"500","level":2},{"id":"a-delivery-that-arrives-twice","text":"A delivery that arrives twice","level":2},{"id":"receiving-a-forward","text":"Receiving a forward","level":2},{"id":"create-note","text":"Create (Note)","level":2},{"id":"update-note","text":"Update (Note)","level":2},{"id":"update-person","text":"Update (Person)","level":2},{"id":"delete-note-person","text":"Delete (Note, Person)","level":2},{"id":"follow","text":"Follow","level":2},{"id":"accept-follow","text":"Accept (Follow)","level":2},{"id":"reject-follow","text":"Reject (Follow)","level":2},{"id":"undo-follow-like-announce-emojireact-block","text":"Undo (Follow, Like, Announce, EmojiReact, Block)","level":2},{"id":"like","text":"Like","level":2},{"id":"announce","text":"Announce","level":2},{"id":"quoterequest","text":"QuoteRequest","level":2},{"id":"accept-reject-quoterequest","text":"Accept / Reject (QuoteRequest)","level":2},{"id":"move","text":"Move","level":2},{"id":"oauth-one-authorization-per-account","text":"OAuth: one authorization per account","level":2},{"id":"notifications-that-are-not-activities","text":"Notifications that are not activities","level":2},{"id":"who-may-moderate","text":"Who may moderate","level":2},{"id":"setup-checks","text":"Setup checks","level":2},{"id":"the-server-card","text":"The Server card","level":2},{"id":"when-public-posts-have-no-remote-recipient","text":"When public posts have no remote recipient","level":2},{"id":"the-audit-trail","text":"The audit trail","level":2},{"id":"moderation","text":"Moderation","level":2},{"id":"admin-metrics","text":"Admin metrics","level":2},{"id":"blocks-that-are-about-an-address","text":"Blocks that are about an address","level":2},{"id":"the-timeline-switcher","text":"The timeline switcher","level":2},{"id":"what-a-switch-looks-like","text":"What a switch looks like","level":2},{"id":"new-post","text":"New post","level":2},{"id":"explore","text":"Explore","level":2},{"id":"the-account-at-the-bottom","text":"The account at the bottom","level":2},{"id":"migration","text":"Migration","level":2},{"id":"every-import-runs-in-the-background","text":"Every import runs in the background","level":2},{"id":"moving-here-from-the-old-handle","text":"Moving here from the old handle","level":2},{"id":"moving-away-is-the-persons-own-with-what-stands-in-front-of-it","text":"Moving away is the person's own, with what stands in front of it","level":2},{"id":"between-two-aloha-social-servers-the-last-step-is-done-from-the-new-side","text":"Between two Aloha Social servers the last step is done from the new side","level":2},{"id":"writing-a-posts-recipients-once","text":"Writing a post's recipients once","level":2},{"id":"reading-a-timeline-in-two-queries","text":"Reading a timeline in two queries","level":2},{"id":"a-domain-block-is-not-a-join","text":"A domain block is not a join","level":2},{"id":"the-moderation-panel","text":"The moderation panel","level":2},{"id":"custom-emoji","text":"Custom emoji","level":2},{"id":"strikes","text":"Strikes","level":2},{"id":"silencing-an-instance","text":"Silencing an instance","level":2},{"id":"inbox-forwarding-activitypub-7-1-2","text":"Inbox forwarding (ActivityPub §7.1.2)","level":2},{"id":"a-delete-that-overtakes-its-create","text":"A Delete that overtakes its Create","level":2},{"id":"add-and-remove","text":"Add and Remove","level":2},{"id":"actor-types","text":"Actor types","level":2},{"id":"tombstone","text":"Tombstone","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"incoming-flow","manual":false,"prev":{"path":"/docs/architecture-outgoing-flow","title":"Outgoing Flow"},"next":{"path":"/docs/architecture-peertube-and-federated-video","title":"PeerTube and federated video"},"parent":"architecture-activitypub-federation"},{"slug":"architecture-peertube-and-federated-video","path":"/docs/architecture-peertube-and-federated-video","title":"PeerTube and federated video","description":"A Video is one of the note-like types in AP::NOTE_LIKE_TYPES — object types other servers Create into a timeline that this app has no model of its own for — and like the rest of them it is…","group":"architecture","html":"<p>A <code>Video</code> is one of the note-like types in <code>AP::NOTE_LIKE_TYPES</code> — object types\nother servers <code>Create</code> into a timeline that this app has no model of its own for\n— and like the rest of them it is stored as a <code>Note</code> carrying its wire type in\n<code>subtype</code>. That is what makes it storable, queryable and readable by a Mastodon\nclient without a second kind of post existing anywhere downstream.</p>\n<p>It is the one of the five that is read in detail, because it is the one whose\nwhole point is a file to play. PeerTube writes four things where an ordinary\n<code>Note</code> does not look, and <code>PeerTubeService</code> is where each is read:</p>\n<ul>\n<li><p><strong><code>url</code> is a list</strong>, not a string: the watch page (<code>text/html</code>), one link per\ntranscoded resolution (<code>video/mp4</code>), the HLS playlist\n(<code>application/x-mpegURL</code>), a torrent and a magnet URI. The best playable\nfile wins — <code>video/mp4</code> up to 1080p, by height — and the playlist is taken\nonly when there is no file at all, since Safari is the only browser that\nopens one. <code>magnet:</code> and the <code>rel: [&quot;metadata&quot;]</code> links are not something to\nhand a <code>&lt;video&gt;</code> and are dropped. The list is also <strong>nested</strong>, and that is\nnot decoration: an instance transcoding to HLS — the default, and what a\npublic PeerTube actually federates — publishes <em>one</em> top-level link, the\nplaylist, and hangs the playable file for each resolution off that link&#39;s\n<code>tag</code>. Reading only the top level found a playlist and nothing else on the\nmajority of real videos, so <code>tag</code> is walked as well.</p>\n</li>\n<li><p><strong><code>attributedTo</code> is a list of two actors</strong>, the channel (a <code>Group</code>) and the\naccount behind it (a <code>Person</code>), where every other server sends one id as a\nstring. The channel wins: it is what the <code>Create</code> is signed by, what a reader\nfollows, and what the video is listed under on PeerTube itself. <code>Stream::import()</code>\nasks for a string and got neither, so a federated video used to arrive\nattributed to nobody. A channel also announces its own\nvideo to its followers the moment it publishes it, so a followed channel\narrived <strong>twice</strong> — once as the video, once as &quot;the channel boosted the\nvideo&quot;. That <code>Announce</code> is skipped, narrowly: only a video, and only where the\nannouncer is the account the video is already attributed to, because somebody\nboosting their own post to resurface it is a thing people do and this must not\nswallow that.</p>\n</li>\n</ul>\n<h2 id=\"an-accounts-icon-and-a-channels-image-are-lists\">An account&#39;s icon and a channel&#39;s image are lists</h2>\n<p> of <code>Image</code>s, one\nper size, where Mastodon sends one. <code>Person::largestImage()</code> keeps the\nlargest by <code>width</code> × <code>height</code> (and a single object as it is), so a PeerTube\naccount arrives with its avatar and a channel with its banner.</p>\n<ul>\n<li><p><strong>The title is in <code>name</code></strong>, which a <code>Note</code> has no use for — and must not be\ncopied into, since <code>name</code> on a note means the option a poll vote chose. So the\ntitle becomes the first paragraph of the content, linked to the watch page.</p>\n</li>\n<li><p><strong>The description is markdown</strong>, and the object says so in its own\n<code>mediaType</code>. It is escaped and paragraph-split when the object declares\n<code>text/markdown</code> or <code>text/plain</code>, and read as html and sanitised otherwise,\nwhich is what every other object&#39;s <code>content</code> is. Believing the declaration in both\ndirections is the point: escaping html would show somebody their own tags, and\nrendering markdown as html would hand a remote server a way to put markup in a\npost that went through no sanitiser.</p>\n<p>The little of markdown a description actually uses — links, bare urls, bold\nand italic — is then rendered, because left alone it reads as asterisks and\nbrackets in the middle of a timeline (which is what Mastodon shows). The\norder is the safety: the text is escaped <em>first</em>, so every tag in the result\nis one this app wrote, and a link is only made of an <code>http(s)</code> target.\nHeadings, lists and code fences are deliberately not handled — rare in a\nvideo description, and each one a way to get this wrong.</p>\n</li>\n</ul>\n<h2 id=\"whether-replies-have-to-be-approved\">Whether replies have to be approved</h2>\n<p> PeerTube ≥ 6.2 moderates comments\n(FEP-5624): a video whose <code>commentsPolicy</code> is 3 takes a reply in and shows it\nto nobody until a human has looked, then sends an <code>ApproveReply</code> back to the\nserver the reply came from. Read in both spellings — the numeric\n<code>commentsPolicy</code> PeerTube sends and the FEP&#39;s own <code>canReply</code>, which names who\nmay reply <em>without</em> being approved — because the two arrived a version apart\nand instances run both. Without it a reply written here looked posted, sat in\na queue on the other side, and either appeared a day later or never, with\nnothing anywhere to say which. It is kept on the post as\n<code>Stream::DETAIL_REPLY_POLICY</code>, and a reply written to such a post carries\n<code>DETAIL_REPLY_STATE</code> — <code>pending</code> until the <code>ApproveReply</code> arrives. The\napproval is taken only from the author of the post replied to, on its own\nserver: the actor it is stored under or one its own document names in\n<code>attributedTo</code> (PeerTube approves as the account behind the video&#39;s\nchannel). One from any other account is refused. Both are\nlocal, derived facts, which is what the details column is for: neither is a\nproperty of the wire object, and the second is about somebody else&#39;s document.</p>\n<ul>\n<li><p><strong><code>Dislike</code></strong>, which Mastodon has never had and which therefore had no model\nhere at all: every one that arrived was logged as an unknown type and\ndropped, so a video whose author cared about the number showed none of them.\nStored the way a <code>Like</code> is — a row in <code>social_action</code> keyed by (actor,\nobject, type) — and counted onto the post as <code>dislikes</code>. <strong>It never\nnotifies</strong>: a like tells an author somebody liked them, and a dislike\narriving as a notification would be a way to needle somebody from anywhere,\none activity at a time.</p>\n</li>\n<li><p><strong><code>View</code></strong>, which PeerTube sends to the owner of a video for every watch.\nThis is the one place <code>social_stream_view</code> takes a number from another\nserver, and it does so on exactly the terms it counts a local one: <strong>one row\nper (post, person)</strong>, so it counts people rather than plays, and the person\nis the actor the sending server signed for — inflating it costs an actor id\nper view, which is the same bar a local account faces. Only ever on our own\nposts: a view of somebody else&#39;s video is their server&#39;s business. Outbound,\na <code>View</code> goes to the origin the <strong>first</strong> time somebody here opens a\nfederated video and not afterwards, because <code>seen()</code> is idempotent on (post,\nviewer) and one press of play is not a second view. An instance whose readers\nwatch without ever saying so is a freeloader on everybody else&#39;s counters.</p>\n</li>\n</ul>\n<h2 id=\"everything-else-the-object-says\">Everything else the object says</h2>\n<p> A video is not a post with a rectangle\nin it: it has a category, a licence, a language, chapters (FEP-6f7d&#39;s\n<code>hasParts</code>), subtitle tracks, a &quot;support the author&quot; line, <code>downloadEnabled</code>\nand three counters. None of it was read, so a federated video arrived as a\nparagraph and a player with all of that thrown away. It is kept together in\none block on the post&#39;s details (<code>Stream::DETAIL_VIDEO</code>) rather than spread\nover a dozen columns — it is local, derived data about somebody else&#39;s\ndocument, and a watch page wants all of it or none — and reaches a client as\n<code>video</code> on the status, null for every post that is not one. The <code>{id, label}</code>\npairs PeerTube sends are read as their <strong>label</strong>: the id means nothing off\nits own instance. An absent <code>downloadEnabled</code> is PeerTube&#39;s own default of\n&quot;yes&quot;, so only a stated refusal is recorded.</p>\n<h2 id=\"hls\">HLS</h2>\n<p> An instance transcoding to HLS — the default — publishes an <code>.m3u8</code>\nthat only Safari opens, so those videos showed a poster and a player that did\nnothing. The client now loads <strong>hls.js</strong>, lazily and only when such a video is\nactually opened, because it is a few hundred kilobytes and almost every post\nis not a video. The playlist it is given is the <strong>proxied</strong> one\n(<code>/media/playlist/{nid}</code>): a playlist names its segments relative to itself,\nso pointing a player at the origin&#39;s copy would have every segment fetched\nfrom there — the very thing the byte proxy exists to prevent, and worse, at\none request per few seconds of video. Both plain URI lines and <code>URI=&quot;…&quot;</code>\nattributes are rewritten, because a player follows both, and the segment\nroute refuses any address that is not on the playlist&#39;s own host.</p>\n<p>A pasted <strong>watch page</strong> resolves too. <code>SearchService::resolveStatus()</code> accepted\n<code>Note</code> and <code>Question</code> only, so a PeerTube address found nothing at all —\nalthough the very same object would have been stored had it arrived by\nfollowing the channel, which is the inbox and the search disagreeing about what\na post is. It now accepts every <code>AP::NOTE_LIKE_TYPES</code>. A PeerTube watch page is\n<code>/w/{shortUUID}</code>, which is the address a person copies out of their browser and\n<em>not</em> the object&#39;s id, so the &quot;a document is only evidence about itself&quot; rule\nis satisfied one level in: the document is trusted when it names the address it\nwas fetched from among its own <code>url</code> links.</p>\n<h2 id=\"where-somebody-stopped-watching\">Where somebody stopped watching</h2>\n<p> is <code>social_watch</code> — PeerTube&#39;s\n<code>WatchAction</code>, and the thing that makes a long video usable at all: a two-hour\ntalk watched in three sittings is three sittings of finding the place again. A\nfact about a <strong>reader</strong>: never federated, never shown to anybody else, never\ncounted into anything, one row per (post, viewer) moved rather than appended. A\nvideo watched past 95% is <strong>forgotten</strong> rather than bookmarked at the credits,\nand one under ten seconds in was never really started — a &quot;continue watching&quot;\nrow that offers back either is a row nobody presses twice. A video read on its\nown (<code>GET /api/v1/statuses/{id}</code>) carries the reader&#39;s <code>watch_progress</code> as well\n(<code>WatchService::attachProgress()</code>: one indexed read, only for a video and a\nsigned-in reader), which is where the player starts it again.</p>\n<h2 id=\"how-many-times-a-video-posted-here-was-watched\">How many times a video posted here was watched</h2>\n<p> is <code>VideoViewService</code> — the\npublic number under a video on a video site, and a different thing from\n<code>social_stream_view</code>, which counts the accounts that opened a post and is told\nto its author alone. The player reports a view (<code>POST /api/v1/statuses/{id}/view</code>) once somebody has played <code>MIN_SECONDS</code> (5) of it,\nand the count moves at most once per viewer, video and day: the viewer is the\naccount, or the Nextcloud session of somebody who is not signed in, and the\nauthor watching their own video is not counted. Only a keyed hash of (day,\nvideo, viewer) is kept, in <code>social_video_seen</code>, for the day it was counted on —\nthe key is the instance&#39;s <code>secret</code>, so a row cannot be worked back to a person\nwithout it, and the day and the video are inside the hash, so two rows of one\nperson cannot be matched — and <code>Cron\\Cache</code> deletes the rows of earlier days.\nThe number is a counter in <code>social_video_views</code>, put on every local video a\nclient is handed by <code>PostDecorationService</code> in one query per page: as\n<code>video_card.views</code> and, where the post has a <code>video</code> block, <code>video.views</code>. It\nalso goes out as the <code>views</code> of the <code>Video</code> this app publishes, which is the\nnumber PeerTube shows under it. A reader who hides the numbers\n(<code>/api/v1/social/counts</code>) is sent no view count at all. A video from another\nserver is never counted here: its own server counts it and the number arrives\nwith it.</p>\n<h2 id=\"subtitle-tracks\">Subtitle tracks</h2>\n<p> come through this server like the video does. A <code>&lt;track&gt;</code>\nmay not be loaded from another host (<code>media-src &#39;self&#39;</code>), and a reader turning\nsubtitles on should not be announced to the video&#39;s server for it, so\n<code>video.captions[].url</code> is this server&#39;s <code>/media/captions/{nid}/{index}.vtt</code>\n(<code>DocumentService::caption()</code>): keyed on the post and the track&#39;s place in the\nlist it stored, never on a url from the caller, read as the viewer may see the\npost, fetched whole up to 1 MB, refused unless it is WebVTT, and stored\nnowhere.</p>\n","toc":[{"id":"an-accounts-icon-and-a-channels-image-are-lists","text":"An account's icon and a channel's image are lists","level":2},{"id":"whether-replies-have-to-be-approved","text":"Whether replies have to be approved","level":2},{"id":"everything-else-the-object-says","text":"Everything else the object says","level":2},{"id":"hls","text":"HLS","level":2},{"id":"where-somebody-stopped-watching","text":"Where somebody stopped watching","level":2},{"id":"how-many-times-a-video-posted-here-was-watched","text":"How many times a video posted here was watched","level":2},{"id":"subtitle-tracks","text":"Subtitle tracks","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"peertube-and-federated-video","manual":false,"prev":{"path":"/docs/architecture-incoming-flow","title":"Incoming Flow"},"next":{"path":"/docs/architecture-reading-a-timeline-at-scale","title":"Reading a timeline at scale"},"parent":"architecture-activitypub-federation"},{"slug":"architecture-reading-a-timeline-at-scale","path":"/docs/architecture-reading-a-timeline-at-scale","title":"Reading a timeline at scale","description":"Three things decide whether this app works on an instance with a million accounts and ten million posts, and all three were measured rather than reasoned about — occ social:benchmark seeds…","group":"architecture","html":"<p>Three things decide whether this app works on an instance with a million\naccounts and ten million posts, and all three were measured rather than\nreasoned about — <code>occ social:benchmark</code> seeds a realistic instance and times the\nqueries against it, and <code>EXPLAIN</code> was read for each of the plans below.</p>\n<h2 id=\"the-home-timeline-pages-over-the-recipient-rows-own-sort-key\">The home timeline pages over the recipient rows&#39; own sort key</h2>\n<p> It used to\ndrive from the viewer&#39;s follows, fetch every recipient row every followed\naccount had ever produced, join each to <code>social_stream</code> to find out when its\npost was published, and sort the lot in a temporary table to keep twenty —\n<code>EXPLAIN</code> said <code>Using temporary; Using filesort</code> in as many words. One page load\ntherefore cost Σ(all posts of everyone you follow), and a client asks for one\nevery thirty seconds. Measured on a seeded instance of 402,725 posts and 805,212\nrecipient rows, with both paths run against the same machine in the same pass:\nthe old query takes <strong>1,661 ms</strong> and the public timeline over the same rows\n<strong>4.2 ms</strong>. That figure is not a bounded read either: <code>EXPLAIN</code> on MariaDB shows\nthe public, notification and direct pages driving from their recipient rows —\none collection and one type, a constant — joining each to its post and sorting\nall of them in a temporary table (<code>Using temporary; Using filesort</code>), so the\ncost grew with every public post ever written and with every notification an\naccount ever received. They now page on the recipient row&#39;s <code>nid</code>\n(<code>SocialLimitsQueryBuilder::paginate()</code> with the <code>sd</code> alias,\n<code>StreamTimelines::paginateOnRecipient()</code>), and <code>social_sd_atn</code> answers the\nfilter and the order as one descending range that stops at the limit — once the\nbackfill flag below says every row carries its nid; until then they page on the\npost&#39;s.</p>\n<h2 id=\"social-stream-dest-nid\">social_stream_dest.nid</h2>\n<p> is the post&#39;s own nid, copied onto the recipient row\nwhen it is written. It is safe to denormalise because a nid never changes after\nthe row exists — there is no update path to keep in step, only an insert — and\nit is the only way to have the sort key and the filter on the same table, which\nno index can span. With <code>(actor_id, type, nid)</code> the page is answered from the\nindex alone, without a row lookup: <strong>50 ms</strong> against the same 1,661. It is not a\nmerge that stops at the limit — <code>EXPLAIN</code> says <code>range social_sd_atn … Using index; Using filesort</code>: across several collections the database reads every\nentry the predicate admits and sorts them, so those 50 ms were the cost of\nreading and sorting every index entry of the reader&#39;s followed collections, and\nthey grow with everything those accounts ever posted. What bounds the read is therefore\nthe predicate, twice over:</p>\n<ul>\n<li><strong>The collections</strong> come from <code>FollowsRequest::limitToHomeCollections()</code>:\nup to 500 (<code>HOME_COLLECTIONS_IN_A_QUERY</code>) are named in an <code>IN (…)</code>; past that\nthe set is an <code>EXISTS</code> over <code>social_follow</code> correlated on the row, so a\nstatement never carries one parameter per followed account — SQLite refuses\none past 32,766. MariaDB turns that <code>EXISTS</code> into a semi-join driven from\nthe follow rows, provided nothing is <code>OR</code>ed beside it, so the reader&#39;s own\nfollower collection — how their own posts reach them — is read by a second\nquery of one collection and merged, rather than named in the list.</li>\n<li><strong>The time.</strong> A nid is the publication time times 10⁹ plus a random suffix,\nso &quot;published in the last day before the cursor&quot; is a range on the same\ncolumn (<code>StreamTimelines::homeRecipientNids()</code>). The page is read within one\nday first and only a page that comes back short is read again, over a week,\na month, a year and finally without a bound. It is exact, not a sample: every\nrow outside a window is further from the cursor than every row inside it, so\na window that fills the page holds the same rows the unbounded query would\nhave returned, and the merge with the followed-hashtag half below keeps its\nguarantee. The home <code>ETag</code> (<code>newestHomeNid()</code>), which a client asks for every\nthirty seconds, is the same query with a limit of one.</li>\n</ul>\n<p>The rows it reads over are the ones the join matched, which is <strong>every accepted\nfollow row of the viewer&#39;s, whatever its type</strong> — not only the ones of type\n<code>Follow</code>. The row that makes the difference is the <strong>Loopback</strong>, the self-follow\nevery local actor is given, whose target is the account&#39;s own id: it is how a\npost addressed to the reader <em>by name</em> — a mention, a reply from somebody they\ndo not follow — reaches their home timeline at all. Narrowing the set to\n<code>type = &#39;Follow&#39;</code> dropped every one of them; the notification still arrived and\nthe post was still readable at its own address, so what it looked like from\noutside was a timeline that paged straight past it.</p>\n<p>The guard on it is a <strong>flag written by the migration</strong>, not a question asked of\nthe table. The obvious check — &quot;is any nid still zero?&quot; — has no index that can\nanswer it and is a full scan of the largest table this app has, 427 ms on\n800,000 rows on every request; a guard that costs more than the query it guards\nis worse than no guard. That one was found by measuring, which is what the\nseeding harness is for.</p>\n<p>The per-viewer filters — blocks, mutes, hidden boosts — are what forced the\njoin, so they no longer ride in the page query. They are applied to the twenty\nrows it chose, where each is a lookup against twenty ids; the page is read three\ntimes wider than asked so that one which loses rows to a block still fills. When\nthat is not enough — a muted account that has just posted sixty times in a row,\na blocked instance that dominates the window — the page <strong>reads on</strong> from below\nthe oldest id it has already considered, up to four more windows. Empty is how\nboth clients read &quot;there is nothing more&quot; (the web app sets <code>allLoaded</code> on a\npage of zero, and no <code>Link: rel=&quot;next&quot;</code> is sent), so without it the timeline\nended in the middle while older posts the reader can see sat further down. The\nbound is what keeps a reader who has muted everything they follow from turning\none request into a walk of the table.</p>\n<p>A <strong>media or news narrowing is the exception</strong>, and the reason is worth keeping:\nit is a question about the <em>post</em>, and the page query reads only the recipient\nrows, which carry no such column. Moving it to the rows was right for blocks, which\ndrop a few posts, and wrong for this, which drops nearly all of them — on the\nseeded instance 143 of 402,725 posts carry media, so the Photos and Videos\ntimelines read the newest sixty ids, discarded all sixty and came back <strong>empty</strong>\nwhile the pictures sat further down. Those timelines take the join path, which\nhas the predicate in the query; they are read far less often than the home\ntimeline, and with <code>media_kind</code> indexed they are now faster than the fast path\nwas anyway. News is the same shape of question over <code>news_kind</code> and takes the\nsame path, for the same reason and with more of it: an article is rarer than a\nphotograph. A short (<code>only_short</code>, over <code>short_kind</code>) is rarer again, and\ntakes it too. The old query is kept as the fallback for an instance whose\nbackfill has not finished, and is slower and always correct.</p>\n<h2 id=\"the-public-page-is-read-the-same-way-and-so-are-the-narrowed-pages\">The public page is read the same way, and so are the narrowed pages</h2>\n<p> The\njoined public query had no selective predicate: on a public instance the\npublic collection&#39;s recipient rows are nearly every post, and the type,\narchived and silenced filters each keep nearly every row. What made it cheap\nwas one plan — walk <code>social_sd_atn</code> newest first, look each post up by key,\nstop at twenty — and nothing obliged the optimizer to choose it. On MySQL with\na hundred thousand seeded posts it chose the other one, a read of the whole of\n<code>social_stream</code> with a temporary table and a sort: <strong>1,208 ms</strong> against\n<strong>10.8 ms</strong> for the same twenty rows (<code>occ social:benchmark</code>, <code>public@20</code>, the\nnightly run&#39;s failure). So <code>StreamTimelines::publicTimelineNidsFromRecipients()</code>\nreads the page from <code>social_stream_dest</code> alone — the public collection, type\n<code>recipient</code>, subtype <code>to</code>, newest nid first, three times the page — and\n<code>publicNidsOf()</code> applies the type, cached-author, hidden-actor and silenced\nfilters to those few dozen ids by key, reading on (<code>refilledPage()</code>, the home\ntimeline&#39;s rounds) when they empty the window. <code>local=</code> and <code>remote=</code> keep the\njoin: the recipient row carries no origin, and a column on the largest table\nfor the two narrowings a client asks for least was not worth its backfill.</p>\n<p>A Photos, Videos, Shorts or News page, public or home, is a question about the\npost, which the recipient rows cannot answer and the join answered by reading\nthe table (<code>photos@20</code> on MySQL, <strong>218 ms → 14 ms</strong>). <code>narrowedNidsByKind()</code>\nreads the newest posts of the kind off its own <code>(kind, nid)</code> index —\n<code>kindWindowNids()</code>, one range per kind, merged — and asks the timeline&#39;s own\nquery whether each of those few dozen belongs to it (<code>s.nid IN (…)</code>), with the\nsame rounds. Where the rounds run out before the page fills while there are\nstill posts of that kind further down — photographs on the home page of\nsomebody who follows two accounts — it hands the request to the join, which\nis correct, rather than answer with a short page a client takes for the end.</p>\n<p>Two <code>OR</code>s the planners estimated badly went with it, each behind a flag\nwritten once the column it guards has no NULL left, as <code>dest_nid_filled</code> is:\n<code>archived = 0 OR archived IS NULL</code> on every list but the hashtag page\n(<code>stream_archived_filled</code>, <code>StreamRequestBuilder::hideArchived()</code>; with the\nbare equality MySQL walked <code>social_stream</code> in nid order looking for the tag\nrather than starting from the tag&#39;s index, so that page keeps the <code>OR</code>) and the media filters&#39; fallback over\nthe attachments of a row with no <code>media_kind</code> (<code>stream_media_kind_filled</code>,\n<code>SocialLimitsQueryBuilder::limitToMedia()</code> and its siblings).\n<code>Version1000Date20261013100500</code> gives the old rows their <code>archived = 0</code>,\n5,000 to a statement, and sets both flags when it finds nothing left to fill.\n<code>QueryPlanTest</code> pins both page shapes on a few hundred rows;\n<code>PublicPagePlanAtScaleTest</code> (with <code>SOCIAL_BENCHMARK=1</code>) seeds fifty thousand\nand asks MySQL and PostgreSQL for the plan again, because a plan at three\nhundred rows says nothing about the one at fifty thousand.</p>\n<h2 id=\"counters-are-added-to-not-counted\">Counters are added to, not counted</h2>\n<p> The three on an account lived only in\nthe <code>details</code> JSON, so moving one meant recomputing all of them — four aggregate\nqueries, on every post written and every follow accepted. For an account with a\nmillion followers that is a million index entries counted so a number on a\nprofile can go up by one. They are columns now, because a column can be\nincremented atomically; the JSON is still what is read, with the columns\noverlaid on it where the row is parsed, and the counting still happens in the\ncron&#39;s walk, which is where drift is reconciled. <code>-1</code> means &quot;never counted&quot;\nrather than &quot;none&quot;.</p>\n<p>The overlay is applied in <strong><code>Person::importFromDatabase()</code></strong>, where a row\nbecomes an actor, rather than in either of the two query builders that parse one\n— one of them did it and did not select the columns, so the overlay had nothing\nto lay on and every profile showed whatever the last cron walk had written.</p>\n<p><strong>Each move has to obey the recount&#39;s own rule</strong>, or the two disagree and the\nnumber visibly wobbles between cron passes. The recount counts <em>public</em>\nstatuses, so <code>count_posts</code> moves only for a post that names the public\ncollection (<code>Item::addressesPublic()</code>) — and moves <strong>down</strong> when one is deleted,\nwhich nothing did at all. <code>count_followers</code> is moved up by the Accept and down\nby the unfollow, whichever side it came from: a local <code>Undo</code> sent from here, or\none that arrived in the inbox, in each case only when the follow it undoes had\nbeen accepted. The cron&#39;s walk is the safety net for what races through, not\nthe thing that makes the number right.\nWhen an inbox <code>Undo</code> carries a composite Follow URI, the stored relationship is\nresolved by the exact actor and followed account pair; an unrelated Follow ID\ndoes not authorize deleting another relationship.</p>\n<h2 id=\"the-cron-walks-rather-than-reads\">The cron walks rather than reads</h2>\n<p> <code>Cron\\Cache</code> refreshed <em>every</em> local\naccount on every pass — the whole table in one PHP array, twelve minutes apart,\nwith a dozen queries and an avatar read behind each row. At a million accounts\nthat array does not fit in memory, and the failure is silent: the cron simply\nfalls behind. It pages, stops at the pass deadline, and remembers in app config\nwhere it got to.</p>\n<p>Three smaller things in the same shape. <code>social_stream.media_kind</code> is what the\nPhotos and Videos timelines ask instead of searching the attachment JSON with\n<code>LIKE</code>, which no index can serve and which was applied after the join.\n<code>social_stream.news_kind</code> is the same idea one step further: the News timeline&#39;s\nquestion — is this an <code>Article</code>, or does its text link to one — is not one a\ndatabase can be asked of stored markup <strong>at all</strong>, so there is no slow-but-correct\nquery to fall back to. It is decided once on the write by <code>Stream::newsKindOf()</code>\nand read through <code>(news_kind, nid)</code>; a row the backfill has not reached is simply\nnot news yet, which is the one place this differs from <code>media_kind</code> and is a\ndeliberate trade — every new post is classified from the moment the column\nexists, so the top of the page, which is the end a reader looks at, is right\nimmediately. <code>social_stream.short_kind</code> is the third column of the kind: whether\na post is a short video — its only attachment a <code>video</code> of at most\n<code>Stream::SHORT_MAX_SECONDS</code> (180), no wider than <code>SHORT_MAX_ASPECT</code> (1, upright\nor square), both from the attachment&#39;s meta — decided by <code>Stream::shortKindOf()</code>\nwherever the attachment copies are written (the post stored, edited, its copies\nrebuilt, a remote video cached and measured) and read through\n<code>(short_kind, nid)</code> by <code>only_short</code>. NULL is left on a post stored before the\ncolumn existed that is not a video: <code>Version1000Date20261012500100</code> reads only\nthe <code>media_kind = &#39;video&#39;</code> rows. The same two thresholds are what <code>/api/v2/config</code>\nannounces, and the short composer&#39;s longest recording is pinned to the first by\na test, so a short made here is never too long to be one. And a content search reads a word index, <code>social_search_term</code>:\none row per (word, post), written with the post, rewritten with an edit\n(<code>SearchTermsRequest::reindex()</code> writes only the words that changed) and\ndeleted with it. A word is an equality on (term, nid), read newest-first and\ncut at the page; every word of the query must be in the post and the last may\nbe a beginning (<code>SearchTerms::ofQuery()</code>). The candidates are then put through\nthe viewer&#39;s visibility exactly as before, in rounds while the visibility\nempties them. A query that is only a word beginning is read through the word&#39;s\nfirst three characters, <code>head</code>, indexed with the nid — PostgreSQL cannot answer\n<code>LIKE &#39;zeb%&#39;</code> from an ordinary index outside the C collation, and an equality\nit can, in nid order — and stays bounded by <code>search_window_days</code>, because a head\nas common as <code>the</code> holds nearly every post. Until <code>Cron\\SearchIndex</code>\nhas walked every post stored before the table existed, the search is the old\n<code>ILIKE</code> over that window.</p>\n<p>The English and German function words (<code>SearchTerms::STOP_WORDS</code>, 188 of\nthem: <code>the</code>, <code>and</code>, <code>of</code>, <code>der</code>, <code>und</code>, <code>nicht</code> …) are not written: each is\nin nearly every post, so each was a row per post that no search narrows on, and\nwith nothing bounding the posts by default the word table was the one growing\nfastest. Beside other words a function word asks nothing of the index — <code>the zebra</code> is a lookup of <code>zebra</code> — and a query made of nothing else (<code>to be or not to be</code>) is answered by the same bounded <code>ILIKE</code> scan, so it still finds what it\ndid. An edit takes the function words out of a post indexed before the list.</p>\n","toc":[{"id":"the-home-timeline-pages-over-the-recipient-rows-own-sort-key","text":"The home timeline pages over the recipient rows' own sort key","level":2},{"id":"social-stream-dest-nid","text":"social_stream_dest.nid","level":2},{"id":"the-public-page-is-read-the-same-way-and-so-are-the-narrowed-pages","text":"The public page is read the same way, and so are the narrowed pages","level":2},{"id":"counters-are-added-to-not-counted","text":"Counters are added to, not counted","level":2},{"id":"the-cron-walks-rather-than-reads","text":"The cron walks rather than reads","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"reading-a-timeline-at-scale","manual":false,"prev":{"path":"/docs/architecture-peertube-and-federated-video","title":"PeerTube and federated video"},"next":{"path":"/docs/architecture-delivering-at-scale","title":"Delivering at scale"},"parent":null},{"slug":"architecture-delivering-at-scale","path":"/docs/architecture-delivering-at-scale","title":"Delivering at scale","description":"Cron\\Queue used to read 200 rows every twelve minutes and deliver them one after another with a 30-second timeout each inside a 300-second budget: about a thousand deliveries an hour at…","group":"architecture","html":"<p><code>Cron\\Queue</code> used to read 200 rows every twelve minutes and deliver them one\nafter another with a 30-second timeout each inside a 300-second budget: about a\nthousand deliveries an hour at best and <strong>ten</strong> at worst, since ten unresponsive\npeers filled the whole pass. It now delivers <strong>several servers at a time</strong>:\n<code>ActivityService::manageRequests()</code> sends a batch in waves of up to <code>PARALLEL</code>\n(20) rows, one per host — the hosts with the most rows left first, so a batch\nthat holds each host&#39;s rows together does not end in waves of a few hosts&#39;\nleftovers — through <code>CurlService::sendMany()</code> (the HTTP client&#39;s\nasync calls, on a client <code>CurlService::parallelClient()</code> builds with Guzzle&#39;s\n<code>CurlMultiHandler</code> — the server&#39;s client defaults to <code>CurlHandler</code>, which\nperforms an &quot;async&quot; request the moment it is made, so the waves used to go out\none request after another and a dead peer&#39;s timeout was paid by every request\nbehind it in its wave; Nextcloud 34&#39;s <code>IClientService::newClient()</code> takes no\nhandler, so on 34 they still do), and settles every row\nexactly as a single delivery is settled. <code>retrieveJsonMany()</code> uses the same\nclient. A settled promise answers Guzzle&#39;s\nPSR-7 response rather than the <code>IResponse</code> a synchronous call returns, and\n<code>CurlService::settledResponse()</code> reads it as one; taking only an <code>IResponse</code> made\nevery parallel delivery a &quot;no response&quot;, so each was sent again and every\npeer was put behind the breaker. A wave costs about as long as its\nslowest peer, so a dead peer costs its timeout once, beside nineteen\ndeliveries, instead of in front of all of them — and then the breaker below\nholds its other rows back without a timeout at all. When a batch is done and\ntime is left, the run takes the next one (up to <code>MAX_BATCHES</code>, 30). The\ndeliveries have <code>REQUEST_DURATION</code> (240 seconds) and the inbound stream queue\nthen gets <code>STREAM_DURATION</code> (120) of its own, taken the same way, batch after\nbatch of 200 with what this run already handed out skipped: under one shared\ndeadline a delivery backlog spent all of it and the parents of replies and the\nposts a delivery only named waited behind it run after run.</p>\n<p>What that comes to: with peers answering within a second, a wave of twenty\ntakes about a second and a run delivers up to its ceiling of 6,000 rows (30\nbatches of 200) — some 30,000 an hour against a thousand before. When every\nwave holds a peer that runs into the 30-second timeout it is eight waves, 160\ndeliveries a run, against ten. The async drain a new post starts\n(<code>QueueController</code>, one wave of 40 rows within 20 seconds at a 10-second\ntimeout) goes out the same way, twenty servers at a time, and leaves the rest\nof the fan-out to the cron. Nextcloud runs one <code>cron.php</code> at a time, so past that\nthe way to scale is <code>social:worker</code>.</p>\n<p><code>occ social:worker</code> is the same delivery in a loop that does not stop. Claiming\na row was already atomic — <code>setAsRunning()</code> is an <code>UPDATE … WHERE status = standby</code> that throws when it loses the race — so several workers may run at once\nand will not collide, which is what makes this scale by adding processes rather\nthan by rewriting anything. It finishes the row in hand on <code>SIGTERM</code>, because a\ndelivery abandoned halfway is one the peer may already have taken.</p>\n<p>The circuit breaker used to be per-pass: <code>manageInit()</code> emptied it at the start\nof every run, so a dead peer was rediscovered every twelve minutes, one\n30-second timeout at a time, for every row addressed to it. It then moved to the\ndistributed cache — which on an instance without a memcache is a <code>NullCache</code>\nthat holds nothing, so there it was per-pass still. It is in the database now\n(<code>social_host_breaker</code>, <code>HostBreakerRequest</code>), shared between the cron, the\nasync worker and every <code>social:worker</code> process, with the wait doubling per\nconsecutive failure up to an hour and clearing the moment the host answers. A\npeer that answers a delivery 429 or 503 with <code>Retry-After</code> — seconds, or an\nHTTP date (<code>CurlService::retryAfter()</code>, carried on the\n<code>RequestContentException</code>) — is left alone at least as long as it asked, and\nnever longer than that same hour (<code>HostBreaker::MAX</code>), so an answer asking for a\nweek does not take a peer out of federation for one; the strike counts as any\nother. A\ndrain reads the failing hosts once, when it starts (<code>manageInit()</code> forgets the\ncopy), and looks every row&#39;s host up in that before it spends a timeout on it;\na healthy host costs no write at all, and one that fails costs one. The logic\nis <code>HostBreaker</code>, and the <strong>inbound stream queue uses the same table</strong>: a fetch\nof a post or of a reply&#39;s parent from a host behind the breaker is not made — a\n<code>Fetch</code> item is postponed until the breaker closes without spending a try\n(<code>StreamQueueRequest::postpone()</code>), a cache item is left for the next attempt\nwithout counting an error against it — a timeout or a 5xx puts the host behind\nit, and an answer takes it off. Each stream-queue batch reads the table afresh.</p>\n<p>And the <strong>inbox no longer walks a whole thread inline</strong>. That walk runs after the\nresponse is flushed but while the FPM worker is still held, and each item can be\na fetch from a server that is slow or gone; at a million users&#39; worth of inbound\ntraffic it is the pool. It does five items or three seconds, whichever comes\nfirst, and leaves the rest to the stream queue that exists for it.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"delivering-at-scale","manual":false,"prev":{"path":"/docs/architecture-reading-a-timeline-at-scale","title":"Reading a timeline at scale"},"next":{"path":"/docs/architecture-what-a-poll-costs","title":"What a poll costs"},"parent":null},{"slug":"architecture-what-a-poll-costs","path":"/docs/architecture-what-a-poll-costs","title":"What a poll costs","description":"A client asks for the home timeline and the unread count every thirty seconds, and the answer is almost always the one it already holds. Both carry an ETag built from the newest id the…","group":"architecture","html":"<p>A client asks for the home timeline and the unread count every thirty seconds,\nand the answer is almost always the one it already holds. Both carry an <code>ETag</code>\nbuilt from the newest id the viewer can see (<code>NotificationInboxService::unreadTag()</code>\nfor both unread counts, v1 and v2) — which changes exactly when the\nanswer does and costs an index-only read of the recipient rows: for the unread\ncount one descending range of the viewer&#39;s own, for the home timeline the same\nwindowed read the page makes, with a limit of one — so a poll that has not\nchanged is answered <code>304</code>. The sidebar&#39;s other two counts are tagged the same\nway: the held requests (the policy&#39;s <code>summary</code>, <code>pendingTag()</code>: the newest\nnotification, the revision, the policy, the muted threads, the silenced accounts\nand the day, since an account stops being new on its own) and the unread\nconversations (<code>ConversationService::unreadTag()</code>: the newest direct message, the\nrevision, and a per-account number moved whenever a conversation is marked read\nor dismissed). A newest id alone misses a row: a nid orders by its second first\nand by chance within it, so a second notification or message in the same second\ncan sort below the first. So every row the three counts count moves a number of\nits account&#39;s as it is written, in the same transaction (<code>StreamDestRequest</code>,\n<code>TimelineRevisionService::NOTIFICATIONS</code> and <code>CONVERSATIONS</code>), and their tags\ncarry it. The home timeline&#39;s tag does not: its rows are a write per follower,\nwhich is the fan-out it exists to avoid. What the held count reads when it does change is not the\nnotifications but who sent each (<code>StreamRequest::getNotificationSenders()</code>), over\nthe same lookback and judged by the same rules (<code>NotificationPolicyService::heldOf()</code>)\nas the requests inbox, which lists what it counts. The web app&#39;s own polls — the timeline every thirty\nseconds, the sidebar&#39;s three badge counts (unread activities, unread\nconversations, held requests; there is no combined route) every minute — only\nrun while the tab is visible: a hidden tab asks once when it is returned to,\nand a server that keeps failing is asked less and less often, down to once in\nfive minutes, until it answers. Media carries the stored\nfile&#39;s own tag, which matters because a timeline is forty to sixty pictures a\nscreen and each was a full Nextcloud boot.</p>\n<p>The tag carries a second number: the reader&#39;s <strong>timeline revision</strong>\n(<code>TimelineRevisionService</code>), one integer per account in its user config. The\nnewest id answers &quot;has anything arrived&quot;; everything else that decides what the\npage holds is a decision the reader made — following or unfollowing an account,\nblocking or muting one, adding a keyword filter, following a hashtag — and none\nof those moves an id. Without it, a reader who unfollows a noisy account is\nanswered <code>304</code> on every poll and goes on seeing it until somebody else happens\nto post: the page they are looking at is the one they just asked to change. The\nnumber is incremented where those rows are written, so it moves whether the\nchange came from the web app, a Mastodon client or the inbox. What it\ndeliberately does not cover is somebody else deleting a post further down a page\nthe reader already holds — making that reach every follower&#39;s tag is a write per\nfollower, which is the fan-out this design exists to avoid, and the page is\nrevalidated when anything else changes.</p>\n<p>The two json routes hand back a <strong><code>JSONResponse</code> rather than a <code>DataResponse</code></strong>,\nand that is what makes any of it work. A returned <code>DataResponse</code> is rebuilt by\nNextcloud&#39;s default json responder, which merges the <em>fresh</em> response&#39;s headers\nover the controller&#39;s — and every response&#39;s defaults include <code>Cache-Control: no-cache, no-store, must-revalidate</code>. The header the route set was therefore\nreplaced on the way out, and <code>no-store</code> forbids the browser to keep the body at\nall: it never sends <code>If-None-Match</code>, so the <code>304</code> was never asked for and the\nwhole thing was decoration, as the wire showed — our <code>ETag</code> and Nextcloud&#39;s\n<code>no-store</code> side by side. The dispatcher rebuilds only a <code>DataResponse</code>, so a\nroute that builds the <code>JSONResponse</code> itself reaches the wire as it is.\n<code>tests/Controller/PollCacheHeaderTest</code> pins both halves against the real\nframework class. The media routes were never affected: a <code>FileDisplayResponse</code>\ndoes not go through the responder.</p>\n<p>The routes the sidebar reads on every page load — <code>/api/v1/custom_emojis</code>,\n<code>/api/v1/trends/tags</code>, <code>/api/v1/instance</code>, <code>/api/v2/instance</code>, <code>/api/v1/lists</code>\nand <code>/api/v1/followed_tags</code> — have no cheap version number to tag, and are\ncheap to build, so they are tagged by what they say (<code>Revalidation::byContent()</code>,\na hash of the body and the paging <code>Link</code>) and go out the same way, as a\n<code>JSONResponse</code> with <code>private, no-cache</code>. The server still builds the answer; the\nbody is not sent again and the browser keeps the copy it has.</p>\n<p>With <code>notify_push</code> installed the client is told instead of asking, and the poll\ninterval drops from thirty seconds to five minutes; that is the single largest\nreduction available to an administrator and it is one app install.</p>\n<p>The page also carries <strong>the first screenful of the home timeline</strong> in its\ninitial state. Without it the first screen is a staircase: fetch the bundle,\nmount, and only then ask the server — a second round trip and a full boot before\nanything a person came to read is on screen. It is consumed once, and only by\nthe list it was rendered for. It goes through <code>FilterService::apply()</code> exactly\nas the API route&#39;s page does, which is both what keeps a muted word — and, for\na reader who asked, a post made with AI (<code>AiContentService</code>) — out of the one\nscreenful nobody asked the server for and what makes the seeded page byte for\nbyte what <code>/api/v1/timelines/home</code> would have answered.</p>\n<h2 id=\"a-ladder-of-sizes\">A ladder of sizes</h2>\n<p> is <code>social_video_rendition</code>. A stored video used to be one\nfile at whatever height it was uploaded at, so a reader on a phone on a train\ndownloaded the 1080p of it or nothing; a ladder is the same video written two or\nthree more times, smaller, plus a playlist that lets the player move between\nthem as the connection changes. It is also the shape PeerTube publishes, so a\nladdered video reaches a PeerTube reader the way a native one does.</p>\n<p>A rung is <strong>one row and one file</strong>. HLS normally means a directory of a few\nhundred segments, which would be a few hundred rows and a few hundred objects in\nthe store; <code>-hls_flags single_file</code> writes each rung as a single fragmented MP4\nand the playlist addresses each segment as a byte range into it, so a\nforty-minute video is three files rather than a thousand — which is, not by\ncoincidence, exactly the shape PeerTube&#39;s own fMP4 output has. The playlist, a\ncouple of kilobytes of text, is kept in the row beside it with the media\nfilename replaced by a placeholder: the URI it has to carry is a route on this\nserver, which is not known when ffmpeg writes the file and changes if the\ninstance is moved.</p>\n<p>Three things it is careful about. <strong>Keyframes are forced onto the segment\nboundary at every rung, with the same period</strong> — without that ffmpeg cuts at the\nnext keyframe it happens to find, the rungs end up with different boundaries,\nand a player switching between them stalls or skips. <strong>It never upscales</strong>: a\nrung at or above the source&#39;s height is dropped rather than encoded, because a\n480p video written out at 1080p is a bigger file of the same picture. <strong>A\nhalf-built ladder is torn down rather than published</strong>, since a master playlist\nadvertising a rung whose file is missing is a player that stalls rather than one\nthat picks another; nothing is ever <em>replaced</em>, so the failure mode of every\nstep is &quot;no ladder yet&quot; and never &quot;a video that 404s&quot;.</p>\n<p>Off unless an administrator turns it on (<code>video_ladder</code>, with\n<code>video_ladder_heights</code> for which sizes), because it is several ffmpeg encodes\nper video on somebody&#39;s server. <code>Cron\\Ladder</code> does one video every half-hour —\nits own job rather than a step of <code>Cron\\Transcode</code>, because a transcode is one\nencode and a ladder is three, and a job that did both would have an\nunpredictable cost per run with the transcoder waiting behind it. Ladders are\nbuilt from <code>video/mp4</code> only: a <code>.mov</code> goes through the transcoder first, and on\nan instance with the transcoder off it gets no ladder, which is the honest\nanswer — there is no ladder to build from a file this server has decided not to\ntouch. A transcode voids whatever ladder was built from the old bytes, so\n<code>replaceVideo()</code> resets the flag and the job rebuilds it.</p>\n<p>It is served by uuid, never by row id: a ladder is the same video as the file,\nso it must be no easier to reach than the file, and a route keyed on a small\ninteger would make a followers-only post&#39;s video findable by counting. Clients\nsee it as <code>hls_url</code> on the attachment — not one of Mastodon&#39;s keys, so a client\nthat does not know it plays <code>url</code>, which is the same video at one size — and\nPeerTube sees it as a streaming-playlist <code>Link</code> with a <code>Link</code> tag per rung,\nbecause PeerTube takes the resolutions from the tags rather than by fetching the\nplaylist and a link with no tags is one it accepts and then has no files for.</p>\n<h2 id=\"how-much-video-one-account-may-keep\">How much video one account may keep</h2>\n<p> is <code>video_quota</code>, off by default. There\nwas a ceiling on how big one <em>file</em> could be and none at all on how many of\nthem one account could upload, so the only real limit was the disk — and the\nadministrator found out about it from the disk. It is checked once, in\n<code>CacheDocumentService::saveFromTempToCache()</code>, which is the one place both an\nupload and a fetched remote attachment pass through; a <strong>fetched</strong> one is\nexempt, because charging somebody&#39;s quota for a video this instance chose to\ncache on their behalf would be a limit nobody could explain. The <strong>ladders are\nexempt too</strong>: they are made because an administrator asked for them, are\nseveral times the size of the upload, and would turn a quota somebody was told\nabout into one several times smaller than the number they were given — but they\n<em>are</em> counted in what an administrator is shown, because they are real disk.</p>\n<p>Counted from the stored <code>size</code> rather than by walking the files, since this is\nasked on every video upload. Rows written before that column existed carry <code>0</code>,\nso <code>MediaUsageService</code> — already doing a <code>stat</code> per stored file on the daily\ncron — writes the answer down as it passes, and the quota becomes accurate\nafter one pass rather than never. Who is holding what is a single grouped query\non the Storage card. <strong>Where the files are is not a setting</strong>: Nextcloud has no\nper-app object store, and an app that offered one would be offering something\nit cannot deliver; the card says whether the instance-wide <code>objectstore</code> in\n<code>config.php</code> is in force, which is the supported way to put this elsewhere and\ncovers Aloha Social&#39;s appdata along with everything else&#39;s.</p>\n<h2 id=\"what-happens-to-a-post-somebody-marked-sensitive\">What happens to a post somebody marked sensitive</h2>\n<p> is <code>SensitiveMediaService</code>.\nPeerTube gives an instance three NSFW policies and lets a person override the\none their instance chose; this app had one, hard-coded. The three are the same\nthree, under <strong>Mastodon&#39;s</strong> names rather than PeerTube&#39;s — <code>show_all</code>,\n<code>default</code>, <code>hide_all</code> — because Mastodon already has a field for exactly this\n(<code>reading:expand:media</code>), every client that speaks this API reads it, and a\nfourth vocabulary for the same three states would be one no client could act\non. <code>show_all</code> is PeerTube&#39;s <em>display</em>, <code>default</code> its <em>blur</em> (covered, the\nblurhash showing, one press away — what this app has always done, and the\ndefault so an upgrade changes nothing), <code>hide_all</code> its <em>hide</em> (not drawn, and\nno button to draw it: opening the post is what it takes).</p>\n<p>A <strong>content warning is not subject to it</strong>: the policy is about media somebody\nmarked sensitive, and a warning is an author saying something about the whole\npost in their own words — a reader who asked to see sensitive media has not\nasked to be shown past every warning anybody writes. An account&#39;s choice is\nstored against its Nextcloud user rather than its actor, because it is a fact\nabout a person reading and not an identity other servers see, and <strong>&quot;follow the\ninstance&quot; stays a state of its own</strong>: it looks the same as choosing what the\ninstance currently does until an administrator changes the default, at which\npoint a settings page that could not tell them apart would have silently pinned\neverybody to the old one. The effective policy travels in the page&#39;s own\ninitial state rather than behind a request, because it decides what the first\nscreenful looks like and a timeline that uncovered itself a moment after it\ndrew would be worse than either policy.</p>\n<h2 id=\"videos-can-be-held-for-a-moderator\">Videos can be held for a moderator</h2>\n<p> with <code>review_videos</code>, the third rule of\nthe review queue beside a new account&#39;s first post and the spam rules. Unlike\nthe other two it is <strong>not about the account</strong>: a trusted account with a\nthousand posts behind it is held by it too, every time, because what it is\nabout is the video — so it is asked before the &quot;a moderator has already decided\nabout this account&quot; gate that stops the others. A moderator&#39;s own video is not\nheld, for the same reason their first post is not.</p>\n<h2 id=\"a-forwarded-report-names-the-posts-by-the-address-the-receiving-server-k\">A forwarded report names the posts by the address the receiving server knows them by</h2>\n<p> A client reports a post by the id <em>this</em> API gave it — a snowflake\nnid — and those were going into the <code>Flag</code> as they arrived. No other server has\never seen them, so every forwarded report named one account the receiving\nmoderators could find and a list of numbers they could not: a report about an\naccount read as a complaint with no evidence, and a report about a <strong>video</strong>,\nwhere the video is the entire complaint, carried nothing at all — PeerTube\nresolves an abuse by the video&#39;s own address and would have found nothing every\ntime. <code>ReportForwardService</code> resolves each one through <code>social_stream</code> now, and\nleaves out anything local: the statuses in a report about a remote account are\nthat account&#39;s posts, and one of ours in the list is a reply somebody picked up\nby mistake.</p>\n<h2 id=\"bringing-a-channel-over\">Bringing a channel over</h2>\n<p> is <code>PostImportService</code>, which already read four\nnetworks&#39; archives and now reads PeerTube&#39;s. Their export carries two halves of\nthe same data: <code>activity-pub/outbox.json</code>, whose <code>Video</code> objects name each\nfile by its address on the <strong>old server</strong>, and <code>peertube/videos.json</code>, whose\n<code>archiveFiles</code> name the copy <strong>inside the archive</strong>. The second is the one read,\nbecause an import that needs the server somebody is leaving to still be running\nis one that stops working exactly when it is needed — and it states the privacy\nas a number rather than leaving it to be read out of an audience, and carries\nthe title, the tags, the category and the licence, which is most of what a video\nis.</p>\n<p>Three kinds are refused rather than translated. A <strong>private, internal or\npassword-protected</strong> video is one its author decided not to publish, and there\nis no audience here that means &quot;the people who had the password&quot;. A <strong>live</strong> has\nno recording to bring over; a saved replay is a video of its own and is exported\nas one. A video with <strong>no file in the archive</strong> would be a page with nothing to\nplay — and an export taken without its video files is refused by name, because\nthe JSON alone is a catalogue and the run would otherwise report &quot;nothing\nimported&quot; about a perfectly valid archive that was simply not the one to ask\nfor. The old instance&#39;s <strong>view, like and dislike counts are not carried over</strong>:\nthey are numbers about its readers, and a post here claiming four thousand\npeople had watched it on this server would be false.</p>\n<h2 id=\"one-video-by-its-address\">One video by its address</h2>\n<p> is the other half, as PeerTube has it: an export is\na heavy tool for a single video, and somebody who has lost their account on the\nold server cannot take one at all while the video is still there to be fetched.\nThe fetched document has to be a <code>Video</code> that <strong>names the address it was fetched\nfrom</strong>, which is the same evidence <code>SearchService::resolveStatus()</code> requires and\nis what stops a redirect substituting one video for another; the tallest\nplayable file link is stored, and an HLS playlist is passed over, since storing a\nlist of segments on somebody else&#39;s server and calling it a video is not an\nimport. A video <strong>already on this server</strong> is refused — bringing a neighbour&#39;s\npost over as your own is not an import, and it is the one case the server can\nactually tell. What it cannot check is whether the video is <em>yours</em>: neither can\nPeerTube&#39;s own importer, nor the archive import, which reads a file somebody\nuploaded. What stands in for it is the same thing in both places — one\ndeliberate act, rate-limited, producing an ordinary post of the account that\nasked for it, which moderation and reporting reach like any other.</p>\n<h2 id=\"peertubes-own-client-api\">PeerTube&#39;s own client API</h2>\n<p> is <code>PeerTubeApiController</code> and\n<code>PeerTubeApiService</code> — the same move the Pixelfed routes are, and for the same\nreason: the official PeerTube app, Tubelab and Fedilab all exist and are good,\nand a client somebody already has is worth more than one nobody has written.\nPeerTube&#39;s API is not Mastodon&#39;s, so this is a <strong>translation and not an alias</strong>;\nthe shapes live in the service so that what one client is promised can be read\nin one place.</p>\n<p>Two things decide how to judge it. It is <strong>read-only</strong>: PeerTube&#39;s upload is a\nresumable protocol with a transcoding state machine behind it, and a half-built\none that took somebody&#39;s file and lost it would be worse than none — comments\nare read and not posted for the same reason the Pixelfed routes do not post,\nthat a client posting through them would go round the review queue the composer\ngoes through. And it is <strong>gated on the domain root</strong>: no PeerTube client will\nask under <code>/apps/social/</code>, because they all build <code>https://&lt;host&gt;/api/v1/…</code>\nfrom the address a person types. Every route is correct and none is reachable\nby a real client until this instance answers at its own root — item 1 of the\nMastodon compatibility list, a decision for whoever runs the server rather than\nsomething this app can do to a Nextcloud.</p>\n<p>Three translations are worth stating because each could have been faked. A\nvideo&#39;s <strong>uuid is the one this app already publishes on the wire</strong>, so a video\nseen through this API and the same video seen over ActivityPub carry one uuid\nrather than two nothing can tell apart — and because that uuid is a one-way hash\nof the post&#39;s address, a video is addressable here by its numeric id only, which\na client that lists before it fetches already has. A category, licence or\nlanguage is <code>{id: 0, label}</code>: PeerTube&#39;s ids are indexes into its own lists,\nwhich this app does not have and must not guess at, and a wrong id is a client\nshowing the wrong category with confidence. And <code>total</code> on every list is the\nsize of <strong>that page</strong>, because these timelines are keyed on a cursor and have no\ncount to give — a number invented for the shape&#39;s sake is one a client would\ndraw a pager from.</p>\n<h2 id=\"-oauth-clients-local\">/oauth-clients/local</h2>\n<p> is the one place the two designs genuinely disagree.\nPeerTube hands out one pair per instance, the same to everybody for ever; this\napp mints a pair per client and hashes the secret, deliberately, so there is no\nstored plaintext to hand back twice. A fresh registration is answered instead,\nwhich is what the route is actually for — a client fetches a pair immediately\nbefore logging in and uses it at once — and is exactly what a Mastodon client\ndoes through <code>/api/v1/apps</code>.</p>\n<h2 id=\"playlists\">Playlists</h2>\n<p> are collections. PeerTube&#39;s <code>Playlist</code> is an ordered set of a\nchannel&#39;s videos with a title, a description and a visibility, which is what\nthis app already calls a collection — so it is stored as one rather than given\na table of its own, and appears as a tab on the channel&#39;s profile. <strong>Read-only\nand rebuilt</strong>: it is somebody else&#39;s document and the document is the whole\ntruth about it, so what arrives replaces what was there — which is the only way\na video <em>removed</em> from a playlist can leave this copy. Only videos this\ninstance already holds go in one: a playlist naming forty videos nobody here\nhas seen is not a reason to fetch forty videos, and it fills in as the rest\narrives by following the channel. A playlist of nothing we hold is not stored\nat all, because an empty page with a title on it is worse than nothing.\nThe playlist&#39;s owner (<code>attributedTo</code>) decides whose collection it is rebuilt\ninto, so it is held to the actor that sent it: the owner has to be that actor,\nor a channel on the actor&#39;s server that names the actor in its own\n<code>attributedTo</code> — which is how PeerTube publishes one, from the account and\nattributed to the channel. An owner that is a local account, or is not known\nhere, is refused (<code>PlaylistService::checkOwner()</code>).</p>\n<p>A document arriving a <strong>second</strong> time — a redelivery, an <code>Update</code> of the post it\nhangs off — describes a file on somebody else&#39;s server and knows nothing about\nthe copy this instance made of it. Written as it arrived it <em>cleared</em>\n<code>local_copy</code> and <code>resized_copy</code>, orphaning the cached file and breaking every\npost that showed the picture until the caching cron happened to fetch it again;\n<code>DocumentInterface::keepWhatOnlyTheRowKnows()</code> moves the stored copies and the\nrow&#39;s key onto the incoming document first. That is a bug older than video —\nevery re-delivered Mastodon picture hit it — but a streamed row depends on it\ntwice over, since the key is what the media proxy is addressed by.</p>\n<p>A picture the inbox could not fetch is stored with an empty <code>local_copy</code>, and\nthe post&#39;s own copy of its attachments (the <code>attachments</code> column, the client\nformat keyed by the document&#39;s nid) says so. When the caching cron or\n<code>occ social:media:retry</code> fetches it later, <code>StreamRequest::updateAttachments()</code>\nrebuilds that one entry from the document and leaves the post&#39;s other entries\nas they were stored. The inbox holds the download to the federation timeout,\nten seconds for the whole transfer (the server&#39;s HTTP client is curl, and its\ntimeout ends a download that is still arriving), so a large original from a\nslow origin is left to the caching run. The caching run and the retry command\nallow the download <code>DocumentService::BACKGROUND_FETCH_TIMEOUT</code> (120 seconds),\nwhich stays below the five minutes after which another run would start the\nsame download again; reaching the origin keeps the ten-second limit.</p>\n<p>When a remote image is refused permanently, the post still arrives with an\nimage placeholder. The local attachment response now carries <code>cache_error</code>:\n<code>1</code> is over the size limit, <code>2</code> is an unsupported type, <code>3</code> could not be read\nfrom the origin, and <code>4</code> could not be decoded. The placeholder exposes that\nreason to assistive technology and on hover. Aloha Social does not load the origin\ndirectly in a reader&#39;s browser, because that would bypass the instance&#39;s media\ntype and size checks. Permanent failures are intentionally skipped by the\nregular cache cron; <code>occ social:media:retry &lt;remote_url&gt;</code> clears the marker for\none uncached remote row and tries it again through the same checks. The\nadministrator can use that after changing a limit or when the origin recovers,\nwithout causing every rejected attachment to be fetched on every cron run.</p>\n<h2 id=\"the-video-is-referenced-not-mirrored\">The video is referenced, not mirrored</h2>\n<p> Every other attachment is copied into\nthis instance&#39;s storage on the way in; a two-hour talk is not, and the row that\nrepresents it carries <code>Document::COPY_STREAMED</code> in <code>local_copy</code> instead of a\nuuid. That sentinel does two jobs: <code>DocumentInterface::save()</code> skips the fetch,\nand the caching cron never picks the row up, because\n<code>getNotCachedDocuments()</code> only looks at rows whose <code>local_copy</code> is empty. The\n<strong>thumbnail</strong> is a second, ordinary document row — it is a few dozen kilobytes\nand it is mirrored, which is what lets a video timeline be scrolled without\ntouching another server. Two rows rather than one: hanging the still off the\nvideo row&#39;s <code>resized_copy</code> would have put one uuid on two rows, and\n<code>getByCopy()</code> would answer with whichever the database felt like.</p>\n<p>The attachment&#39;s url is rebuilt for the instance a reader is actually on, the\nway the uuid links are (<code>MediaAttachment::onThisInstance()</code>): it names a cache\nrow rather than a copy, but it was written under whichever <code>overwrite.cli.url</code>\nthe inbox request ran under, which on many instances is not the address anybody\nbrowses.</p>\n<p>Playing it goes through <strong><code>GET /media/stream/{nid}</code></strong> (<code>MediaApiController::mediaStream()</code>),\nwhich opens the origin and copies it to the reader a chunk at a time, storing\nnothing. It exists because the page cannot point a <code>&lt;video&gt;</code> at the origin\ndirectly — Nextcloud&#39;s content security policy says <code>media-src &#39;self&#39;</code> — and\nbecause widening that policy would also mean every reader who pressed play\nannouncing themselves to a server they never chose to talk to. The cost is that\nthis instance carries the bandwidth. What keeps the route from being an open\nproxy is that it takes a <strong>row id, not a url</strong>: only a <code>social_cache_doc</code> row\nthis app itself wrote as streamed answers, and the request still goes out\nthrough <code>CurlService</code>, so the domain access list and the local-address refusal\napply as they do to every other outbound request. The reader&#39;s <code>Range</code> header is\nforwarded and the origin&#39;s <code>206</code> comes back untouched, which is what makes\nseeking in a long video cost nothing.</p>\n<h2 id=\"publishing-one\">Publishing one</h2>\n<p> The other direction is the same shape written rather than\nread, and it lives in the same class so the two halves cannot drift:\n<code>PeerTubeService::asVideo()</code>. A <strong>local</strong> post whose attachments are exactly one\nvideo is serialised as a <code>Video</code> — <code>name</code> (a title, derived; see below),\n<code>duration</code> in the xsd form, <code>icon</code> for the poster, and <code>url</code> as the link list\nwith the web page and the file. Only the serialisation changes; the row stays a\n<code>Note</code>, exactly as an incoming <code>Video</code> is stored as one.</p>\n<p>Three things about it worth knowing:</p>\n<ul>\n<li><strong><code>attachment</code> is published as well.</strong> A <code>Video</code> carries its file in <code>url</code> and\nhas no need of it, but every Mastodon-family server reads <code>attachment</code> and\nnothing else, and these posts rendered there with an inline player before any\nof this existed. Publishing both costs a few hundred bytes and is the\ndifference between gaining PeerTube and trading Mastodon for it.</li>\n<li><strong>The title is derived</strong>, because a <code>Note</code> has none and this app does not ask\nfor one: the first line of the post, then the video&#39;s alt text, then the word\n<code>Video</code>. (<code>name</code> on a Note means the option a poll vote chose — see\n<code>PollService::handleIncomingVote</code> — so nothing reads <em>that</em>.) An explicit\ntitle field is the obvious next step and is not here yet.</li>\n<li><strong>There is one file rendition</strong>: the stored file — the upload itself, or\nwhere the server has ffmpeg the H.264 MP4 the transcoder replaced it with —\nrather than one file per resolution. A shorter list than PeerTube publishes,\nthe same shape, and a reader takes the best playable link it finds.</li>\n</ul>\n<p>It is on by default and an admin can turn it off with\n<code>occ config:app:set social publish_video_objects --value 0</code>. The switch exists\nbecause the one thing that cannot be proven from here is whether a\nMastodon-family server renders a <code>Video</code> as well as it rendered the <code>Note</code>; what\n<em>is</em> proven is the round trip — everything published goes back through the\nreader in the same class, in <code>PeerTubePublishTest</code>.</p>\n<p>What is <strong>not</strong> done: <code>Audio</code> (Funkwhale), <code>Article</code>, <code>Page</code> and <code>Event</code> are\nstill read by <code>fillNoteLikeContent()</code> alone — title and link, no media. The\nlink includes a <code>Link</code> attachment&#39;s <code>href</code>, which is where a Lemmy link post\nkeeps the one thing it is about (it has no <code>url</code>); it is appended to the content\nunless the content already links it, and the link preview is made from it. Nor are\nthere channels: a <code>Video</code> is attributed to the author&#39;s <code>Person</code>, where PeerTube\nsends the <code>[Person, Group]</code> pair. Both are valid ActivityPub; only the second is\nwhat PeerTube itself would send.</p>\n","toc":[{"id":"a-ladder-of-sizes","text":"A ladder of sizes","level":2},{"id":"how-much-video-one-account-may-keep","text":"How much video one account may keep","level":2},{"id":"what-happens-to-a-post-somebody-marked-sensitive","text":"What happens to a post somebody marked sensitive","level":2},{"id":"videos-can-be-held-for-a-moderator","text":"Videos can be held for a moderator","level":2},{"id":"a-forwarded-report-names-the-posts-by-the-address-the-receiving-server-k","text":"A forwarded report names the posts by the address the receiving server knows them by","level":2},{"id":"bringing-a-channel-over","text":"Bringing a channel over","level":2},{"id":"one-video-by-its-address","text":"One video by its address","level":2},{"id":"peertubes-own-client-api","text":"PeerTube's own client API","level":2},{"id":"-oauth-clients-local","text":"/oauth-clients/local","level":2},{"id":"playlists","text":"Playlists","level":2},{"id":"the-video-is-referenced-not-mirrored","text":"The video is referenced, not mirrored","level":2},{"id":"publishing-one","text":"Publishing one","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":[{"path":"/docs/architecture-quote-posts","title":"Quote posts","description":"A quote is a post that embeds another post rather than linking to it, and the part that needs agreeing on is not the embedding — it is consent. FEP-044f, and Mastodon 4.5 with it, treats a…","parent":true},{"path":"/docs/architecture-whole-conversations","title":"Whole conversations","description":"Opening a conversation also asks this source inline with a three-second timeout, guarded by a per-post lock. Each returned root and continuation is checked against the requested AT-URI…","parent":true},{"path":"/docs/architecture-who-liked-boosted-or-quoted","title":"Who liked, boosted or quoted","description":"Who reacted is kept an hour in the durable cache's table (DurableCache::setShared(), which the cron and the web server share even where APCu is the only memcache), not as actions: the…","parent":true},{"path":"/docs/architecture-who-follows-an-account-and-whom-it-follows","title":"Who follows an account, and whom it follows","description":"What a network listed is kept an hour in the durable cache's table (DurableCache::setShared(), social.followlists). The routes (AccountApiController::accountFollowers()/accountFollowing())…","parent":true},{"path":"/docs/architecture-counts-where-a-post-lives","title":"Counts where a post lives","description":"CountService::seen() is called with what a page serves — a status (StatusApiController::statusGet()), a conversation (StreamService::getContextByNid()) and every timeline page a client…","parent":true},{"path":"/docs/architecture-hashtags-and-searches-beyond-this-server","title":"Hashtags and searches beyond this server","description":"What is found is stored like any arriving post, indexed for the search as it is stored, so the timeline and the search simply have it the next time. The answers say X-Social-Filling while…","parent":true},{"path":"/docs/architecture-hidden-replies","title":"Hidden replies","description":"The author of a thread's first post may hide any reply in it, wherever it was written (HiddenReplyService, the hide_reply status action). The ids are kept on that first post…","parent":true},{"path":"/docs/architecture-who-may-reply","title":"Who may reply","description":"The author of a post written here says who may reply to it: everybody (the default), nobody, or any combination of their followers, the accounts they follow, the accounts the post mentions…","parent":true},{"path":"/docs/architecture-bluesky-custom-feeds-and-lists","title":"Bluesky custom feeds and lists","description":"Atproto\\Reader\\BlueskyFeeds reads getFeed and getListFeed as the viewer and filters posts they cannot see. An AppView page may contain only hidden posts and still include a continuation…","parent":true},{"path":"/docs/architecture-bookmarks-here-and-on-bluesky","title":"Bookmarks, here and on Bluesky","description":"Atproto\\Publisher\\BlueskyBookmarks keeps a person's bookmarks in step with Bluesky apps signed in here. getBookmarks reads the local bookmark timeline and includes the posts that have a…","parent":true},{"path":"/docs/architecture-direct-messages-with-bluesky","title":"Direct messages with Bluesky","description":"A conversation with somebody on Bluesky is a conversation in Messages like any other. Bluesky keeps direct messages on its chat service, not in repositories, so Atproto\\Chat\\ChatPoller (a…","parent":true},{"path":"/docs/architecture-lists-here-and-on-bluesky","title":"Lists, here and on Bluesky","description":"A person's lists are one set with their Bluesky lists. A list is private unless its owner makes it public (social_list.visibility; public on PUT /api/v1/lists/{id}, a switch in Settings →…","parent":true},{"path":"/docs/architecture-switching-off-bluesky","title":"Switching off Bluesky","description":"A person may switch their own presence on Bluesky off (D23 of the Bluesky specification, §4.6; Settings → Apps and account → Bluesky, POST /api/v1/social/bluesky/state).…","parent":true},{"path":"/docs/architecture-shared-lists-to-mute-or-block","title":"Shared lists to mute or block","description":"A person subscribes to somebody else's list of accounts, to mute or block everybody on it (ModerationListService, Blocking → Shared lists, /api/v1/social/moderation_lists). Each network…","parent":true},{"path":"/docs/architecture-accounts-this-instance-verified","title":"Accounts this instance verified","description":"Moderators verify accounts in the instance's name (VerificationService, VerificationController; Administration → Moderation → Verified accounts and the profile menu, which…","parent":true},{"path":"/docs/architecture-discovery","title":"Discovery","description":"All three return the previous handler's response untouched when FediverseService::jailed() says the instance is in allow-list mode with an empty list.","parent":true},{"path":"/docs/architecture-reading-a-timeline","title":"Reading a timeline","description":"The first decides which posts belong in the page: it carries all the joins and filters (recipients, follows, hidden actors, duplicate suppression) but projects a single column, s.nid. The…","parent":true}],"anchor":"what-a-poll-costs","manual":false,"prev":{"path":"/docs/architecture-delivering-at-scale","title":"Delivering at scale"},"next":{"path":"/docs/architecture-quote-posts","title":"Quote posts"},"parent":null},{"slug":"architecture-quote-posts","path":"/docs/architecture-quote-posts","title":"Quote posts","description":"A quote is a post that embeds another post rather than linking to it, and the part that needs agreeing on is not the embedding — it is consent. FEP-044f, and Mastodon 4.5 with it, treats a…","group":"architecture","html":"<p>A quote is a post that embeds another post rather than linking to it, and the\npart that needs agreeing on is not the embedding — it is consent. FEP-044f, and\nMastodon 4.5 with it, treats a quote as something the quoted author grants, and\na quote without that grant renders as a bare link no matter what the quoting\nserver says about it. So the feature is a handshake, and this app is on both\nends of it.</p>\n<p><strong>Quoting.</strong> <code>Status::import()</code> reads a client&#39;s <code>quote_id</code>, <code>PostService</code>\nstores it on the post as <code>quote</code>, and the post is published straight away — the\nauthor should not wait on somebody else&#39;s server. In the same step\n<code>requestQuoteApproval()</code> sends a <code>QuoteRequest</code> to the quoted author&#39;s inbox\nnaming the quoting post as its <code>instrument</code>. Until an answer comes back the\nquote&#39;s state is <code>pending</code>; a failure to even send the request is logged and\nnothing more, because the post is already out.</p>\n<p><strong>Being quoted.</strong> <code>QuoteRequestInterface::processIncomingRequest()</code> answers for\nlocal posts. The request&#39;s <code>instrument</code> is read as an id whether it arrives as\none or as the quoting post inlined, which is how Mastodon sends it. The policy is <code>Stream::isQuotable()</code> — public and unlisted, yes;\nanything narrower, no — which is the same rule <code>PinService::pin()</code> and\n<code>BoostService::create()</code> apply, and for the same reason: a quote carries the\naudience of the quoter, so a narrower post would reach readers its author never\naddressed. It is also exactly what <code>interactionPolicy.canQuote</code> advertises on\nour posts, and the two have to agree, because Mastodon offers its users a quote\nbutton on the strength of the advertisement and shows them an error if the\nrequest is then refused. A <code>Yes</code> is an <code>Accept</code> whose <code>result</code> is the URI of the\napproval.</p>\n<p><strong>Quoting a post of our own.</strong> Then this server is the authority the request\nwould be addressed to, and there is nobody to ask: a <code>QuoteRequest</code> would be the\ninstance delivering to its own inbox and waiting for its own answer.\n<code>PostService::applyQuote()</code> grants the approval on the spot instead — the post\nwas already checked against the same policy — and stamps it onto the note before\nthe wire object is snapshotted, so the first delivery already carries it.</p>\n<p><strong>What a client is told.</strong> The <code>quote</code> entity&#39;s state is read from the approval,\nnot from whether the quoted post happens to be in the database: <code>accepted</code> means\nthe author said yes, <code>pending</code> means no answer yet. Holding the quoted post\nanswers a different question — whether we <em>could</em> show it — and deriving the\nstate from that reported every quote as accepted the moment it was written,\nincluding ones the author went on to refuse. An accepted quote whose post is\nmissing here, or closed to this particular reader, is still <code>accepted</code>, with a\nnull <code>quoted_status</code>; calling that <code>pending</code> would report the author as not\nhaving answered when they have.</p>\n<p><strong>The approval.</strong> That URI is <code>&lt;quoted post&gt;/quote_authorizations/&lt;stamp&gt;</code>,\nwhere the stamp is the quoting post&#39;s id in base64url. Carrying the id rather\nthan a digest of it is what lets the endpoint be stateless: a peer that\ndereferences the URI — Mastodon does, before it will render the quote inline —\ngets a <code>QuoteAuthorization</code> document built from the stamp and the post&#39;s current\npolicy, with nothing stored in between. Deriving the stamp from the id also\nmeans a request redelivered twice is answered with the same URI both times\ninstead of two approvals that disagree.</p>\n<p>Answering from the <em>current</em> policy is deliberate, and it is the only way a\ngrant is taken back on this side. An author who narrows a post has withdrawn the\npermission, and a peer that re-checks the approval finds the endpoint no longer\nanswering. Nothing pushes that news: statelessness has a price, and this is it —\napprovals granted are not recorded, so there is no list of who to tell. A peer\nthat never re-checks goes on showing the quote. Withdrawal in the other\ndirection does arrive promptly: a <code>Reject</code> for a quote that was previously\naccepted is applied as a revocation, the stamp comes off both the\n<code>quote_authorization</code> column and the stored wire object so later deliveries stop\nclaiming an approval, and the client sees the quote&#39;s state as <code>revoked</code> rather\nthan <code>rejected</code>.</p>\n<p><strong>On the wire.</strong> <code>quote</code> is FEP-044f&#39;s name and what Mastodon 4.5 reads first;\n<code>quoteUrl</code> and <code>_misskey_quote</code> are emitted beside it for the servers that\npredate the FEP. <code>quoteAuthorization</code> carries the approval once there is one.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"quote-posts","manual":false,"prev":{"path":"/docs/architecture-what-a-poll-costs","title":"What a poll costs"},"next":{"path":"/docs/architecture-whole-conversations","title":"Whole conversations"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-whole-conversations","path":"/docs/architecture-whole-conversations","title":"Whole conversations","description":"Opening a conversation also asks this source inline with a three-second timeout, guarded by a per-post lock. Each returned root and continuation is checked against the requested AT-URI…","group":"architecture","html":"<p>A reader opening a post sees its whole conversation, wherever the replies\nwere written: not only the ones this server received because somebody here\nfollows their author. <code>StreamService::getContextByNid()</code> asks\n<code>RemoteFetchQueue::fillThread()</code> for the conversation&#39;s first post and for\nthe one opened, at most every ten minutes per post, for a post from another\nserver or a public one of this server&#39;s (which other networks read too), and\n<code>Cron\\FillThread</code> hands it to <code>ThreadService</code>. Opening the thread also reads\nthe first page of replies inline from its network under a shared three-second\nnetwork budget; the background fill continues paging and following replies\ndeeper into the conversation, with one budget of 150 replies:</p>\n<ul>\n<li><code>ActivityPubThreadSource</code> reads the post&#39;s <code>replies</code> collection as its\nserver described it, a few pages, fetches each reply this server does not\nhold from its own server (<code>StreamQueueService::fetchNow()</code>, held to the\nsame host breaker as the queue), and the replies of those in turn, three\nlevels deep. The inline read is limited to 20 direct replies and passes its\nremaining timeout to both collection and post fetches; additional pages and\nreplies stay on the existing background path. A failed collection or reply\nfetch keeps any replies already stored, marks the visible read incomplete,\nand lets the next context poll retry after five seconds instead of caching\nthe partial result as a successful read;</li>\n<li><code>Atproto\\Reader\\BlueskyThreadSource</code> asks the AppView for the thread\n(<code>getPostThread</code>) of a post that is on Bluesky — read from there, or\nwritten here and published — and stores each post as any Bluesky post is\nstored, parents first.</li>\n</ul>\n<p>Opening a conversation also asks this source inline with a three-second\ntimeout, guarded by a per-post lock. Each returned root and continuation is\nchecked against the requested AT-URI before it can be stored. A missing,\nunrecognized, or mismatched <code>thread</code> view is a failed read, so the queued fill\nremains available; an explicit <code>notFoundPost</code> or <code>blockedPost</code> is a valid\nempty result only when it names the requested URI. Bluesky caps the\nstandard <code>getPostThread</code> reply depth at ten. On both inline and background\nreads, every returned post is checked against its <code>replyCount</code>; if a node has\nfewer visible direct replies than that count, the AppView&#39;s V2 thread view is\ntried with that node as the anchor, with the specced cursor-paged post search\nas fallback. This applies to nested comments as well as the opened post, and\nall inline fallback reads share the same three-second budget. Unfilled\nbranches remain pending for the background fill. A successful read also\nqueues a background fill when it reached the ten-level limit and a deeper\nbranch remains; that fill follows such branches, each with its own bounded\nrequest, up to twenty continuation reads and the shared 150-new-reply budget.\nA timeout or missing branch does not discard replies already stored. Local\nposts still queue the background fill as well, since their Fediverse replies\nmay not yet be known here.</p>\n<p>The page is never held up by another server: the answer says so with\n<code>X-Social-Thread-Filling</code>, and the web app asks once more a few seconds\nlater. Nothing in what a reader sees says which network a reply came from.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"whole-conversations","manual":false,"prev":{"path":"/docs/architecture-quote-posts","title":"Quote posts"},"next":{"path":"/docs/architecture-who-liked-boosted-or-quoted","title":"Who liked, boosted or quoted"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-who-liked-boosted-or-quoted","path":"/docs/architecture-who-liked-boosted-or-quoted","title":"Who liked, boosted or quoted","description":"Who reacted is kept an hour in the durable cache's table (DurableCache::setShared(), which the cron and the web server share even where APCu is the only memcache), not as actions: the…","group":"architecture","html":"<p>The same idea as whole conversations, for the reactions to a post: the\nlists of who liked it, who boosted it and which posts quote it are the\nones from here and the ones from wherever the post lives, merged, with\nnothing to tell them apart. <code>InteractionService</code> asks each network the post\nis on (<code>InteractionSource</code>) in the background (<code>Cron\\FillInteractions</code>,\nqueued by <code>RemoteFetchQueue::fillInteractions()</code> at most every ten minutes\nper post and kind). Opening a reaction or quote list first asks supported\nsources inline with a three-second timeout and a per-post-and-kind lock, then\nreturns fresh actor ids or stored quote posts and queues profile resolution\nfor avatars not cached yet.\nThe five-second shared freshness marker bounds duplicate work from concurrent\nor rapidly repeated requests; failures fall back to the background queue:</p>\n<ul>\n<li><code>ActivityPubInteractionSource</code> reads the post&#39;s <code>likes</code> and <code>shares</code>\ncollections as its server describes them — Mastodon lists only the\nnumber, other servers name the accounts — and has the accounts not\ncached here fetched (<code>RemoteFetchQueue::resolveActors()</code>);</li>\n<li><code>Atproto\\Reader\\BlueskyInteractionSource</code> asks the AppView\n(<code>getLikes</code>, <code>getRepostedBy</code>, <code>getQuotes</code>) for a post that is on Bluesky,\nchecks that the returned subject URI matches the post it asked about,\ncaches each account as it is found and stores each quoting post. A\nmismatched or malformed answer is a failed read, so it cannot replace the\nlast complete reaction list and is retried through the background queue.</li>\n</ul>\n<p>Who reacted is kept an hour in the durable cache&#39;s table (<code>DurableCache::setShared()</code>, which the cron and the web server share even where APCu is the only memcache), not as actions: the\ncounts on a post, and the notifications, stay what they were. Quoting\nposts are stored as posts, so the quotes list reads them like any other.\nThe answers say <code>X-Social-Filling</code> while the read was just asked for.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"who-liked-boosted-or-quoted","manual":false,"prev":{"path":"/docs/architecture-whole-conversations","title":"Whole conversations"},"next":{"path":"/docs/architecture-who-follows-an-account-and-whom-it-follows","title":"Who follows an account, and whom it follows"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-who-follows-an-account-and-whom-it-follows","path":"/docs/architecture-who-follows-an-account-and-whom-it-follows","title":"Who follows an account, and whom it follows","description":"What a network listed is kept an hour in the durable cache's table (DurableCache::setShared(), social.followlists). The routes (AccountApiController::accountFollowers()/accountFollowing())…","group":"architecture","html":"<p>The same idea for the followers and following lists of an account on\nanother server: the follows this server knows come first, as always, and\nafter them the ones the network the account lives on lists, with nothing\nto tell them apart and nobody twice. <code>FollowListService</code> asks each network\nthe account is on (<code>FollowListSource</code>) in the background\n(<code>Cron\\FillFollowLists</code>, queued by <code>RemoteFetchQueue::fillFollowList()</code> at\nmost every ten minutes per account and direction, for a signed-in reader):</p>\n<ul>\n<li><code>ActivityPubFollowListSource</code> reads the actor&#39;s <code>followers</code> or\n<code>following</code> collection as its server describes it, at most four\ndocuments (the collection and its first pages), and has the accounts not\ncached here fetched (<code>RemoteFetchQueue::resolveActors()</code>). A server can\nkeep the lists to itself: Mastodon&#39;s &quot;hide your social graph&quot; answers the\ncollection and refuses its pages (401/403), others give only\n<code>totalItems</code>; either is a hidden list, and a hidden list is empty here\ntoo, the follows this server knows included — what Mastodon itself does;</li>\n<li><code>Atproto\\Reader\\BlueskyFollowListSource</code> asks the AppView\n(<code>app.bsky.graph.getFollowers</code>, <code>getFollows</code>, up to three pages and 100\naccounts) for an account on Bluesky, caches each account as it is found\n(<code>BlueskyActorService::store()</code>), and names one of this server&#39;s own\naccounts by its local id (<code>LocalRecordResolver</code>). Bluesky has no hidden\nlists.</li>\n</ul>\n<p>What a network listed is kept an hour in the durable cache&#39;s table\n(<code>DurableCache::setShared()</code>, <code>social.followlists</code>). The routes\n(<code>AccountApiController::accountFollowers()</code>/<code>accountFollowing()</code>) page the\nfollows known here by their ids as before; the last of those pages is\nfilled up with the listed accounts, and a page that reaches into them is\ncontinued by the <code>max_id</code> of its last account, which the service finds\namong the listed ones. A page asked for with <code>min_id</code> or <code>since</code> is the\nfollows known here alone. The answers say <code>X-Social-Filling</code> while the read\nis queued and its shared result cache has not been written yet; the web app\npolls the first page every two seconds for up to thirty seconds. Accounts\nnamed by an ActivityPub collection that are not cached or do not yet have a\nlocal account id are queued for resolution, and the page remains in the\nfilling state until they can be shown. An account of this server&#39;s own is\nunchanged.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"who-follows-an-account-and-whom-it-follows","manual":false,"prev":{"path":"/docs/architecture-who-liked-boosted-or-quoted","title":"Who liked, boosted or quoted"},"next":{"path":"/docs/architecture-counts-where-a-post-lives","title":"Counts where a post lives"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-counts-where-a-post-lives","path":"/docs/architecture-counts-where-a-post-lives","title":"Counts where a post lives","description":"CountService::seen() is called with what a page serves — a status (StatusApiController::statusGet()), a conversation (StreamService::getContextByNid()) and every timeline page a client…","group":"architecture","html":"<p>A post from elsewhere arrives with the likes, boosts and replies it had at\nthat moment, and nothing tells this server when they change: a <code>Like</code> of a\nremote post travels to that post&#39;s server, and a Bluesky post read off a\nfeed is stored once and never re-read. So the counts of the remote posts\npeople look at are asked for again, one concept with a source per network\n(<code>Service\\Counts\\CountSource</code>):</p>\n<ul>\n<li><code>ActivityPubCountSource</code> reads the post&#39;s document at its <code>id</code> and takes\nthe <code>totalItems</code> of its <code>likes</code>, <code>shares</code> and <code>replies</code> collections\n(<code>Stream::statedCount()</code>), twenty documents a round. If an origin gives a\ncollection URL without an inline total, those collection URLs are fetched\ntogether in a second round. Mastodon&#39;s <code>quoteCount</code> extension is retained as\nthe quote total. Requests to origins have a five-second timeout; an answer\nnaming some other document, or none — a post deleted at its source among\nthem — leaves what is stored. An answer with no usable counter is not\ntreated as fresh during an interactive read, so the background path can retry;</li>\n<li><code>Atproto\\Reader\\BlueskyCountSource</code> asks the AppView&#39;s <code>getPosts</code>, 25\nposts a call (<code>PostStore::postViews()</code>), for <code>likeCount</code>, <code>repostCount</code>,\n<code>replyCount</code> and <code>quoteCount</code>; a post is deleted as <code>DeletionSweep</code> deletes\nit only when the AppView explicitly returns <code>notFound</code>. Every requested URI\nmust occur exactly once in the response; a missing, duplicate or malformed\nentry leaves the whole batch untouched and keeps the deletion cursor in\nplace for another attempt. A blocked placeholder is kept;</li>\n<li><code>Atproto\\Reader\\BlueskyPublishedCountSource</code> does the same for a post of\nthis server&#39;s own that is also a record on Bluesky (see <strong>A local post&#39;s\ncounts on Bluesky</strong> below).</li>\n</ul>\n<p><code>CountService::seen()</code> is called with what a page serves — a status\n(<code>StatusApiController::statusGet()</code>), a conversation\n(<code>StreamService::getContextByNid()</code>) and every timeline page a client reads\n(<code>StreamService::getTimeline()</code> in the local format, <code>visiblePosts()</code>, the\nlist timeline) — and queues background reads. <code>seen()</code> keeps reporting a page as filling while any count remains due, even when the durable queue has already deduplicated that request. Timeline, profile and list responses carry <code>X-Social-Filling</code> during that period; the web app re-requests the page with a fresh URL so an ETag cannot turn the count refresh into a <code>304</code>, and stops polling when the worker stamps the new counts. Opening a post also attempts a\nper-post locked refresh with a three-second network budget; concurrent viewers\nreuse that attempt, and an unavailable or incomplete answer falls back to the\nbackground queue without marking unknown numbers fresh. A status response that\nreports <code>X-Social-Filling</code> is read again with bounded exponential backoff, at\nmost ten times, so a background result that lands after the initial request is\nmerged into the open post. Timeline pages use the same filling signal with bounded backoff and\na cache-busting query value, so unchanged ETags cannot hide newly stored counts.\nA boost stands for the post it boosts, direct messages are skipped,\nand so is a local post unless a source\nsupports it (one that goes to Bluesky, <code>Publisher::goesToBluesky()</code>), and a\npost is due when its <code>counts_at</code> is older than a quarter of an hour while the post\nis less than a day old, six hours after that. The due ones are handed to\n<code>RemoteFetchQueue::refreshCounts()</code>, which stamps each post in the durable\ncache for its interval (so a post is queued at most once per interval\nhowever many pages show it), takes at most twenty a call and queues\n<code>Cron\\RefreshCounts</code> jobs with the ids. The job re-reads each post, skips\nthe ones no longer due and hands the rest to the network each lives on\n(<code>CountService::refreshPosts()</code>); a post no source answers for is stamped\nall the same. The cron&#39;s pass over the posts nobody looked at\n(<code>RemoteCountService</code>, every two hours, fifty a pass) goes through the same\n<code>refreshPosts()</code>, so a Bluesky post there is asked of the AppView rather\nthan fetched as an ActivityPub document from bsky.app. It takes the remote\nposts of the last seven days (<code>PUBLISHED_WINDOW</code>, which MySQL and PostgreSQL\nfind through the <code>published_time</code> index) that are due, never asked first and then the one asked longest ago\n(<code>StreamRequest::getRemoteStreamsDueForCounts()</code>); a boost is left out, as it\nhas no counts of its own. An older post is asked about when somebody looks at\nit, and <code>occ social:counts:refresh --force</code> asks about every remote post. A post\nwhose server answers 404 or 410 is stamped thirty days ahead\n(<code>CountWriter::stampGone()</code>, <code>GONE_FOR</code>), so neither the pass nor a reader\nopening it asks again before then; <code>CurlService::retrieveObjectsMany()</code> reports\neach answer&#39;s status beside the documents for that. The same pass takes\nup to fifty more of this server&#39;s own posts of the last seven days that have\na Bluesky record (<code>StreamRequest::getPublishedStreamsDueForCounts()</code>, a join\non <code>social_atproto_record</code>); an older one is asked about when somebody looks\nat it.</p>\n<p>Posts opened in their detail view have a faster path:\n<code>TimelineList</code> refreshes up to four visible non-direct posts on entry, scroll\nand every five seconds, rotating through the visible posts when there are more\nthan four. This includes local posts mirrored to Bluesky; the backend chooses\nthe source that supports each post. <code>TimelineSinglePost</code> also asks for the\nstatus again when opened, even if a copy is already in the timeline.\n<code>StatusApiController::statusGet()</code> asks the matching ActivityPub or Bluesky\ncount source directly when <code>counts_at</code> is at least five seconds old, with a\nthree-second network timeout and a per-post lock, then reads the updated row\nfor the response. A failed or timed-out read leaves stored counts untouched\nand queues the normal background retry; the follow-up status read is\nread-only, so it cannot start another slow request. This keeps reader-facing\ncounts independent of Nextcloud&#39;s cron cadence; posts outside the viewport\nstill use the queued background path above. Bluesky thread reads use the same\nthree-second timeout and per-post lock, and failed reads remain eligible for\nthe background thread queue. When a response says counts or a conversation are\nstill being filled, the client checks again after three seconds while the\nreader stays on the page.</p>\n<p><code>CountWriter</code> stores an answer: the origin&#39;s total less what is counted here\ninto <code>remote_likes</code>, <code>remote_boosts</code> and <code>remote_replies</code> — only those keys,\nby the compare-and-swap <code>StreamRequest::changeDetails()</code>, so an edit&#39;s\nmentions or a refused quote stored meanwhile stay — <code>counts_at</code> set, then\n<code>StreamRequest::recount()</code> for the columns (see <strong>The counters are\ncolumns</strong> below), so every reader — the client and Mastodon APIs alike —\nsees the new numbers. No notification is made and no action is touched.\nThe last-asked time is the <code>counts_at</code> column the cron&#39;s pass already kept,\nnot a new table; <code>Stream::getCountsAt()</code> carries it to <code>seen()</code> with the row.</p>\n<h2 id=\"a-local-posts-counts-on-bluesky\">A local post&#39;s counts on Bluesky</h2>\n<p>A post of this server&#39;s own that went to Bluesky is a record in its\nauthor&#39;s repository, and a like, repost, reply or quote of it there is a\nrecord in somebody else&#39;s. A PDS is never told of those; this server hears\nof them only through the author&#39;s notifications (<code>NotificationPoller</code>), and\none that poll misses — downtime, a gap longer than its page, the request\nceiling — is never counted. So <code>BlueskyPublishedCountSource</code> reads the\nrecord&#39;s <code>likeCount</code>, <code>repostCount</code>, <code>replyCount</code> and <code>quoteCount</code> from\n<code>getPosts</code>, 25 records a call, and keeps only what the AppView counts that\nthis server does not hold.</p>\n<p>The AppView&#39;s totals overlap what is held here, and only part of it.\n<code>AtprotoRepoRequest::countHeldOnBluesky()</code> counts that part in one query:\nthe likes and boosts in <code>social_action</code> whose actor is a bsky.app account\n(what <code>NotificationPoller</code> took in), the replies and quotes in\n<code>social_stream</code> whose id is a bsky.app post, and the likes, boosts, replies\nand quotes of local accounts that have a record in their repository here\n(<code>local_id_prim</code> = the action&#39;s or post&#39;s <code>id_prim</code>, the collection matching\n— <code>InteractionPublisher</code> writes a like or boost there, <code>Publisher</code> a reply\nor quote). A like from the Fediverse, or by a local account not on Bluesky,\nis in neither. <code>CountWriter::writeBeyond()</code> stores <code>max(stated − that part, 0)</code> as <code>remote_likes</code>, <code>remote_boosts</code>, <code>remote_replies</code> and\n<code>remote_quotes</code>, and <code>recount()</code> adds everything held here, as for any\npost. A post whose notifications all arrived therefore has nothing beyond,\nand shows exactly what it showed before; one the poll missed a like of shows\nit one higher, in the columns, in the <code>details</code> copy the Mastodon and\nclient APIs read and on the statistics page, which sums those. The floor at\nzero takes care of a like the AppView has not indexed yet, and of a like\nundone on Bluesky that is still held here. A count the AppView does not\nstate keeps the half already stored. No <code>atproto</code> block is written on a\nlocal post, and nothing is notified: the people behind those likes are\nunknown here.</p>\n<p>An author whose presence on Bluesky is switched off\n(<code>IdentityService::activeForActor()</code> is null), or whose identity is not the\nrepository the record is in, is not asked about; the post is stamped and\nkeeps what it has. So is a post without a record, or one the AppView does\nnot return.</p>\n<p>Quotes are a fifth counter beside the four: <code>count_quotes</code>, recounted\n(<code>StreamRequest::recountQuotes()</code>) where a reply&#39;s parent is — a quoting post\nsaved, synced or deleted — from the posts held here that quote it, found by\n<code>quote_prim</code>, the indexed hash of what a post quotes (<code>quote</code> is TEXT, which\nno index covers); <code>remote_quotes</code> is the origin&#39;s half, which Bluesky&#39;s\n<code>quoteCount</code> fills. The status entity carries it as Mastodon 4.5&#39;s\n<code>quotes_count</code>, hidden with the other numbers for a reader who hides them.</p>\n<p>A page that queued a refresh says so: <code>GET /api/v1/statuses/{nid}</code> with\n<code>X-Social-Filling</code>, a conversation with the <code>X-Social-Thread-Filling</code> its\nbackground read already uses. The web app reads the post, or the\nconversation, once more six seconds later (<code>fetchStatus()</code>,\n<code>refetchThreadLater()</code>), so the new numbers appear without a reload; a\ntimeline page is not read again, and shows them when it is next loaded.</p>\n","toc":[{"id":"a-local-posts-counts-on-bluesky","text":"A local post's counts on Bluesky","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"counts-where-a-post-lives","manual":false,"prev":{"path":"/docs/architecture-who-follows-an-account-and-whom-it-follows","title":"Who follows an account, and whom it follows"},"next":{"path":"/docs/architecture-hashtags-and-searches-beyond-this-server","title":"Hashtags and searches beyond this server"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-hashtags-and-searches-beyond-this-server","path":"/docs/architecture-hashtags-and-searches-beyond-this-server","title":"Hashtags and searches beyond this server","description":"What is found is stored like any arriving post, indexed for the search as it is stored, so the timeline and the search simply have it the next time. The answers say X-Social-Filling while…","group":"architecture","html":"<p>A hashtag&#39;s timeline and a search of posts are answered, as before, from\nwhat this server holds — and the first page of either also has the posts\nbeyond it read in the background (<code>RemoteFetchQueue::fillPosts()</code>,\n<code>Cron\\FillPosts</code>, <code>PostDiscoveryService</code>, at most every ten minutes per\nhashtag, and per search and reader). Each network is a <code>PostSource</code>:</p>\n<ul>\n<li><code>FediversePostSource</code> asks the public hashtag timelines\n(<code>/api/v1/timelines/tag/{tag}</code>) of up to five Mastodon-speaking servers\nthis one talks to (<code>FediverseDirectoryService::sources()</code>), and fetches\neach post from its own server (<code>StreamQueueService::fetchNow()</code>), so what\nis stored is what its author&#39;s server says, never a peer&#39;s copy. The\nfediverse has no public search of posts, so a search is not asked of it;</li>\n<li><code>Atproto\\Reader\\BlueskyPostSource</code> asks the AppView&#39;s <code>searchPosts</code>,\nnewest first, as the reader where they are on Bluesky.</li>\n</ul>\n<p>What is found is stored like any arriving post, indexed for the search as\nit is stored, so the timeline and the search simply have it the next time.\nThe answers say <code>X-Social-Filling</code> while the read is new.</p>\n<p><strong>Followed hashtags</strong> are read the same way without anybody looking:\n<code>Cron\\FillFollowedTags</code>, every quarter of an hour, runs\n<code>Service\\Discovery\\FollowedTagsFill</code>, which takes the hashtags somebody here\nfollows, each once, ten a run, never read first and then the one read\nlongest ago (<code>FollowedTagsRequest::dueForFill()</code>, from\n<code>social_followed_tag.filled</code>), and asks every <code>PostSource</code> for each\n(<code>PostDiscoveryService::fillTag()</code>, as nobody in particular). Bounded so a\npopular tag cannot flood a timeline: at most 20 posts a tag from each\nnetwork a run, only those written since the tag was last read (less ten\nminutes, for a post a network shows late) and never any older than two\ndays, which is also all a first read goes back; a Fediverse status is dated\nby its <code>created_at</code>, a Bluesky post by the earlier of its record&#39;s\n<code>createdAt</code> and the AppView&#39;s <code>indexedAt</code>. A tag a page has just had read\nshares the ten-minute throttle (<code>RemoteFetchQueue::claimPostsFill()</code>) and\nwaits for the next run. What an administrator has turned off holds: with\nBluesky off for the instance, <code>BlueskyPostSource</code> asks nothing, and the\nservers asked are the directory&#39;s.</p>\n<p>Nothing is written for the home timeline. Its followed-tags half\n(<code>StreamRequest::followedTagNids()</code>) is a join at read time of the post&#39;s\nstored tags (<code>social_stream_tag</code>) with the reader&#39;s followed tags, limited\nto posts addressed to the public collection — and a post read from Bluesky\nis stored addressed to it, its hashtags as tags (those in the text and the\nrecord&#39;s <code>tags</code> beside it, which Bluesky&#39;s search finds a post by too). So a\nstored post is in the home timeline of everybody following one of its tags,\nand blocks, mutes, silenced accounts and keyword filters apply to it as to\nany post there.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"hashtags-and-searches-beyond-this-server","manual":false,"prev":{"path":"/docs/architecture-counts-where-a-post-lives","title":"Counts where a post lives"},"next":{"path":"/docs/architecture-hidden-replies","title":"Hidden replies"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-hidden-replies","path":"/docs/architecture-hidden-replies","title":"Hidden replies","description":"The author of a thread's first post may hide any reply in it, wherever it was written (HiddenReplyService, the hide_reply status action). The ids are kept on that first post…","group":"architecture","html":"<p>The author of a thread&#39;s first post may hide any reply in it, wherever it\nwas written (<code>HiddenReplyService</code>, the <code>hide_reply</code> status action). The ids\nare kept on that first post (<code>Stream::getHiddenReplies()</code>, the newest 300,\nas many as a Bluesky threadgate holds); a conversation read here leaves\nthem out and counts them (<code>X-Social-Hidden-Replies</code>), or marks them\n<code>hidden_by_author</code> when the reader asks for them, and the web app shows\nthem behind a button. A thread that is on Bluesky lists them in its\nthreadgate (<code>hiddenReplies</code>, rewritten by <code>Publisher::updateGates()</code>), so\nevery AppView hides them too; a Bluesky author&#39;s <code>hiddenReplies</code> are kept\nthe same way when their thread is read (<code>PostStore::rememberHiddenReplies()</code>).\nThe fediverse has no such list, so a fediverse server shows the replies\nit holds.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"hidden-replies","manual":false,"prev":{"path":"/docs/architecture-hashtags-and-searches-beyond-this-server","title":"Hashtags and searches beyond this server"},"next":{"path":"/docs/architecture-who-may-reply","title":"Who may reply"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-who-may-reply","path":"/docs/architecture-who-may-reply","title":"Who may reply","description":"The author of a post written here says who may reply to it: everybody (the default), nobody, or any combination of their followers, the accounts they follow, the accounts the post mentions…","group":"architecture","html":"<p>The author of a post written here says who may reply to it: everybody (the\ndefault), nobody, or any combination of their followers, the accounts they\nfollow, the accounts the post mentions and the members of up to five of\ntheir lists (<code>Stream::normalizeReplyRule()</code>, kept in the post&#39;s details as\n<code>reply_rule</code>, e.g. <code>followers,list:12</code>, so no column is needed). A reply is\nlet through when any part lets it through; a list&#39;s members are checked as\nthey are now, and snapshotted for what other servers are told\n(<code>ReplyRuleService::snapshotListMembers()</code>). <code>ReplyRuleService::refusal()</code> is the\none rule, applied wherever a reply comes from: <code>PostService</code> refuses one\nwritten here with the reason before anything is sent, and <code>NoteInterface</code>\ndoes not keep one that arrives from another server or from Bluesky. The\nauthor always may. A follow counts once it is accepted.</p>\n<p>The rule goes out with the post: to peers as\n<code>interactionPolicy.canReply.automaticApproval</code> (GoToSocial&#39;s field, which it\nholds its own users to), to Bluesky as an <code>app.bsky.feed.threadgate</code> under the\npost&#39;s key (<code>RecordMapper::threadgate()</code>, a rule for each part). A list a rule\nnames is published as a Bluesky curate list (<code>Atproto\\Publisher\\BlueskyLists</code>,\n<code>app.bsky.graph.list</code> and a <code>listitem</code> for each member with a Bluesky identity),\nkept in step as members are added or removed and withdrawn with the list, so\nthe threadgate&#39;s <code>listRule</code> can name it; it stays published while a\nthreadgate names it, even when the list is private. A change later\n(<code>PUT /api/v1/statuses/{nid}/interaction_policy</code> with <code>reply_policy</code>) is\nforward-only, like the quote policy: replies already made stay. It\nre-snapshots the stored source, as the quote policy does, and rewrites the\nthreadgate in one commit (<code>Publisher::updateGates()</code>), which a quote-policy\nchange now uses for the postgate too.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"who-may-reply","manual":false,"prev":{"path":"/docs/architecture-hidden-replies","title":"Hidden replies"},"next":{"path":"/docs/architecture-bluesky-custom-feeds-and-lists","title":"Bluesky custom feeds and lists"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-bluesky-custom-feeds-and-lists","path":"/docs/architecture-bluesky-custom-feeds-and-lists","title":"Bluesky custom feeds and lists","description":"Atproto\\Reader\\BlueskyFeeds reads getFeed and getListFeed as the viewer and filters posts they cannot see. An AppView page may contain only hidden posts and still include a continuation…","group":"architecture","html":"<p><code>Atproto\\Reader\\BlueskyFeeds</code> reads <code>getFeed</code> and <code>getListFeed</code> as the\nviewer and filters posts they cannot see. An AppView page may contain only\nhidden posts and still include a continuation cursor, so an empty visible\npage does not itself end the timeline. The reader follows up to ten empty\npages, keeping a separate short-lived retry cursor if that bound is reached;\nthe next request resumes from that cursor and a repeated remote cursor is an\nerror. Visible-page cursors remain keyed by viewer, feed and last visible\npost in <code>DurableCache</code>, with its database fallback when no memcache is\nconfigured.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"bluesky-custom-feeds-and-lists","manual":false,"prev":{"path":"/docs/architecture-who-may-reply","title":"Who may reply"},"next":{"path":"/docs/architecture-bookmarks-here-and-on-bluesky","title":"Bookmarks, here and on Bluesky"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-bookmarks-here-and-on-bluesky","path":"/docs/architecture-bookmarks-here-and-on-bluesky","title":"Bookmarks, here and on Bluesky","description":"Atproto\\Publisher\\BlueskyBookmarks keeps a person's bookmarks in step with Bluesky apps signed in here. getBookmarks reads the local bookmark timeline and includes the posts that have a…","group":"architecture","html":"<p><code>Atproto\\Publisher\\BlueskyBookmarks</code> keeps a person&#39;s bookmarks in step with\nBluesky apps signed in here. <code>getBookmarks</code> reads the local bookmark timeline\nand includes the posts that have a Bluesky record. Their AppView previews are\nfetched in groups of at most 25, including authenticated reads, while the\nresponse keeps the local bookmark order and pagination cursor. A failed group\nleaves its entries as <code>notFoundPost</code> placeholders and does not prevent the\nremaining groups from being read.</p>\n<p><code>Atproto\\Publisher\\BlueskyThreadMutes</code> keeps local conversation state and\nBluesky&#39;s private thread-notification preference in step. An accepted mute or\nunmute from a signed-in Bluesky app resolves its AT URI with\n<code>LocalRecordResolver::postId()</code>, mapping this instance&#39;s mirrored record back\nto the Social post id before updating the local conversation root.\n<code>ActionService</code> sends the same operation to Bluesky when a person changes the\nmute in Social; <code>PostRefs::strongRef()</code> finds the root&#39;s AT URI even when the\nstored post id is a local Social id. Posts remain visible while notifications\nare suppressed. An uncached root has no local thread state to update.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"bookmarks-here-and-on-bluesky","manual":false,"prev":{"path":"/docs/architecture-bluesky-custom-feeds-and-lists","title":"Bluesky custom feeds and lists"},"next":{"path":"/docs/architecture-direct-messages-with-bluesky","title":"Direct messages with Bluesky"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-direct-messages-with-bluesky","path":"/docs/architecture-direct-messages-with-bluesky","title":"Direct messages with Bluesky","description":"A conversation with somebody on Bluesky is a conversation in Messages like any other. Bluesky keeps direct messages on its chat service, not in repositories, so Atproto\\Chat\\ChatPoller (a…","group":"architecture","html":"<p>A conversation with somebody on Bluesky is a conversation in Messages like\nany other. Bluesky keeps direct messages on its chat service, not in\nrepositories, so <code>Atproto\\Chat\\ChatPoller</code> (a step of <code>Cron\\AtprotoSync</code>)\nreads each account&#39;s chat log as the account (<code>AppViewClient::chatAs()</code>,\ncursor in <code>social_atproto_chat_cursor</code>), and <code>ChatStore</code> stores each message\nsomebody else sent as a direct <code>Note</code> from them to the account, naming it,\nthrough <code>PostStore::storeMessage()</code> — the import path every post takes, so\nthe dest rows, the notification, push and the unread count follow as for\na Fediverse message. Each message answers the newest one of its Bluesky\nconversation, received or sent from here (kept with\n<code>DurableCache::setShared()</code>), so <code>ConversationService</code>, which groups direct\nmessages by the thread they are in, shows one conversation. A direct\nmessage written here is queued by <code>AtprotoPostListener</code> as an\n<code>AtprotoPublish</code> <code>message</code>, and <code>ChatSender</code> sends it to its recipients on\nBluesky in their conversation (<code>getConvoForMembers</code>, <code>sendMessage</code>), while\nthe Fediverse recipients get it over ActivityPub as before. The attempt is\nrecorded before it is sent, and a retry of the job looks for the message\namong the conversation&#39;s 100 newest (<code>getMessages</code>) before sending it\nagain, as its first attempt may have sent it without recording it. Opening\nMessages wakes the account&#39;s next read (<code>ConversationService::getPage()</code>).</p>\n<p>What the account writes in a Bluesky app arrives in the same log and is\nstored as its own direct message to the conversation&#39;s other members, saved\nwith <code>StreamRequest::save()</code> alone — the stream row and its recipient rows,\nno <code>PostService</code>, no <code>PostPublishedEvent</code>, not <code>local</code> — so nothing\ndelivers it again. <code>ChatSender</code> remembers the Bluesky id <code>sendMessage</code>\nanswered with (<code>ChatStore::sent()</code>), so the log&#39;s copy of a message sent\nfrom here is recognised, and which Bluesky conversation a message here is\nin (<code>ChatStore::convoOf()</code>: in the id of one from Bluesky, remembered for\none sent from here). With that, <code>ConversationService::markRead()</code>,\n<code>markAllRead()</code> and <code>remove()</code> tell <code>Chat\\ChatState</code> (resolved from the\ncontainer), which queues an <code>AtprotoPublish</code> <code>chat</code> job: <code>updateRead</code>,\n<code>updateAllRead</code>, or <code>leaveConvo</code> for a conversation that is still a\nrequest. The other way, a <code>logReadConvo</code> in the log marks the conversation\nread here up to that message (<code>ConversationService::markReadUpTo()</code>). A\nconversation that is a request on Bluesky is accepted when it is answered\nfrom here (<code>ChatSender</code>) or its sender is accepted from the requests, and\nleft when the sender is dismissed there (<code>NotificationPolicyService</code>\n<code>accept()</code>, <code>dismiss()</code>).</p>\n<p>Who may send the person direct messages is one setting for both networks,\nkept by <code>NotificationPolicyService</code> (<code>directMessagesFrom()</code>): it is the\npolicy&#39;s <code>for_private_mentions</code> read the other way round (accepted:\neverybody; held: people followed), plus the user value\n<code>direct_messages_nobody</code> for nobody, which holds direct messages from people\nfollowed as well. A change, from the settings page\n(<code>DirectMessagesSettings.vue</code>, <code>PATCH /api/v1/social/direct_messages</code>) or\nfrom the policy, is written to the person&#39;s repository as\n<code>chat.bsky.actor.declaration</code> (<code>Chat\\ChatDeclaration</code>,\n<code>Publisher::writeSelfRecord()</code>), which Bluesky&#39;s chat service goes by; one\na Bluesky app writes through <code>WriteService</code> becomes the setting here.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"direct-messages-with-bluesky","manual":false,"prev":{"path":"/docs/architecture-bookmarks-here-and-on-bluesky","title":"Bookmarks, here and on Bluesky"},"next":{"path":"/docs/architecture-lists-here-and-on-bluesky","title":"Lists, here and on Bluesky"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-lists-here-and-on-bluesky","path":"/docs/architecture-lists-here-and-on-bluesky","title":"Lists, here and on Bluesky","description":"A person's lists are one set with their Bluesky lists. A list is private unless its owner makes it public (social_list.visibility; public on PUT /api/v1/lists/{id}, a switch in Settings →…","group":"architecture","html":"<p>A person&#39;s lists are one set with their Bluesky lists. A list is private\nunless its owner makes it public (<code>social_list.visibility</code>; <code>public</code> on\n<code>PUT /api/v1/lists/{id}</code>, a switch in <strong>Settings → Lists</strong>). Outward,\n<code>ListController</code> hands every change to <code>Atproto\\Publisher\\BlueskyLists</code>:\n<code>sync()</code> publishes a public list as a curate list with its members that\nhave a Bluesky identity, renames the record when the list is renamed, and\nwithdraws it when the list is made private — unless one of the owner&#39;s\nthreadgates names it (see <strong>Who may reply</strong>); members added or taken out\nare listed or withdrawn as before. Inward, <code>Atproto\\Reader\\BlueskyListImport</code>\nreads the curate lists in the person&#39;s own repository: what a Bluesky app\nsigned in here writes (<code>WriteService</code> hands it each <code>list</code> and <code>listitem</code>\nit creates, replaces or deletes, after the record is written) and, at the\nlast step of a move here, what the account brought (<code>MoveInService:: importPosts()</code>). A list record becomes a public list, an item a member\n(a local DID the local account, any other the Bluesky account, cached\nfirst), and each record is tied to what it stands for by its local id —\n<code>list:&lt;id&gt;</code>, an item <code>list:&lt;id&gt;#&lt;md5 of the member&gt;</code> — which is how\n<code>BlueskyLists</code> finds it again. Records this server writes never pass\nthrough <code>WriteService</code>, and a record that already stands for a list is not\nimported again, so nothing goes round in a circle. A group list stays\nprivate: who is in a group is not its member&#39;s to show. Withdrawing a list\nalso takes the items in the repository that name it and stand for no\nmember here; a public list not on Bluesky yet is published by the\nmaintenance pass (<code>BlueskyLists::publishMissing()</code>, a page of lists at a\ntime, the place kept with <code>DurableCache::setShared()</code>).</p>\n<p>When <code>WriteService::apply()</code> receives only repository-native records, it\nvalidates and commits the batch through <code>RepositoryService::write()</code> once;\nlist synchronization runs after that repository commit. Its optional\n<code>swapCommit</code> is checked against the locked head before the repository changes,\nand the response carries the commit produced by the batch. Batches that include\nSocial actions still follow the action-specific paths, while <code>RepositoryService</code>\nstages their Bluesky records and exposes them to later actions in the same\nbatch. One database transaction commits the database-backed Social changes,\nrepository records, and firehose event; ActivityPub deliveries begin after\ncommit. On failure, the database transaction and deferred delivery starts are\nrolled back. Profile and media files use Nextcloud storage and are outside that\ndatabase rollback. A mixed batch checks <code>swapCommit</code> against the locked\nrepository head before committing.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"lists-here-and-on-bluesky","manual":false,"prev":{"path":"/docs/architecture-direct-messages-with-bluesky","title":"Direct messages with Bluesky"},"next":{"path":"/docs/architecture-switching-off-bluesky","title":"Switching off Bluesky"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-switching-off-bluesky","path":"/docs/architecture-switching-off-bluesky","title":"Switching off Bluesky","description":"A person may switch their own presence on Bluesky off (D23 of the Bluesky specification, §4.6; Settings → Apps and account → Bluesky, POST /api/v1/social/bluesky/state).…","group":"architecture","html":"<p>A person may switch their own presence on Bluesky off (D23 of the Bluesky\nspecification, §4.6; <strong>Settings → Apps and account → Bluesky</strong>, <code>POST /api/v1/social/bluesky/state</code>). <code>Atproto\\Identity\\PresenceService</code> does it\nwith what a move away already uses: <code>IdentityService::deactivate()</code> sets the\nidentity <code>deactivated</code> and puts <code>#account active: false</code> on the firehose, so\nthe relay and the AppView stop showing the account, and the sync and repository\nreads answer <code>RepoDeactivated</code>. Everything that writes for the person checks\n<code>Identity::isActive()</code> — the <code>Publisher</code> (posts, edits, gates, records,\nprofile), <code>ChatSender</code> — and so do the sign-ins of Bluesky apps\n(<code>SessionService</code>, <code>AuthorizationServer</code>), whose sessions are ended at once,\nand the notification and chat pollers, which drop the account&#39;s cursor. What\nasks the AppView in the person&#39;s name takes <code>IdentityService::activeForActor()</code>\nand reads anonymously without it, so reading Bluesky goes on. A delete still\ngoes to the repository. <code>IdentityService::forActor()</code> returns the row as it\nis, so nothing makes the identity again. Switching back on\n(<code>IdentityService::activate()</code>) puts <code>#account active: true</code>, <code>#identity</code> and a\n<code>#sync</code> of the head commit on the firehose, and keeps the time in the user value\n<code>atproto_on_since</code>; <code>PresenceService::writtenWhileOff()</code> keeps the publisher&#39;s\nreconcile pass from publishing what was written before it.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"switching-off-bluesky","manual":false,"prev":{"path":"/docs/architecture-lists-here-and-on-bluesky","title":"Lists, here and on Bluesky"},"next":{"path":"/docs/architecture-shared-lists-to-mute-or-block","title":"Shared lists to mute or block"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-shared-lists-to-mute-or-block","path":"/docs/architecture-shared-lists-to-mute-or-block","title":"Shared lists to mute or block","description":"A person subscribes to somebody else's list of accounts, to mute or block everybody on it (ModerationListService, Blocking → Shared lists, /api/v1/social/moderation_lists). Each network…","group":"architecture","html":"<p>A person subscribes to somebody else&#39;s list of accounts, to mute or block\neverybody on it (<code>ModerationListService</code>, <strong>Blocking → Shared lists</strong>,\n<code>/api/v1/social/moderation_lists</code>). Each network that publishes such lists\nis an <code>AccountListSource</code>; today that is Bluesky&#39;s\n(<code>Atproto\\Reader\\BlueskyModerationLists</code>, read with <code>getList</code>, each\naccount cached as it is found). Every account on a list gets an ordinary\nmute or block in <code>social_actor_relation</code>, so the timelines hide them as\nany other. The subscription keeps which relations it made (user value\n<code>moderation_lists</code>), and only those are taken back when it ends or an\naccount leaves the list. <code>Cron\\ModerationLists</code> reads each list again\nevery six hours. Where the list lives is told too, as D16 of the Bluesky\nspecification allows: a mute list is muted at the AppView, and a block\nlist is published as a <code>listblock</code> record only for somebody who publishes\ntheir blocks.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"shared-lists-to-mute-or-block","manual":false,"prev":{"path":"/docs/architecture-switching-off-bluesky","title":"Switching off Bluesky"},"next":{"path":"/docs/architecture-accounts-this-instance-verified","title":"Accounts this instance verified"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-accounts-this-instance-verified","path":"/docs/architecture-accounts-this-instance-verified","title":"Accounts this instance verified","description":"Moderators verify accounts in the instance's name (VerificationService, VerificationController; Administration → Moderation → Verified accounts and the profile menu, which…","group":"architecture","html":"<p>Moderators verify accounts in the instance&#39;s name (<code>VerificationService</code>,\n<code>VerificationController</code>; <strong>Administration → Moderation → Verified\naccounts</strong> and the profile menu, which <code>serverData.canVerify</code> turns on).\nAny account can be verified; each is a row in <code>social_verification</code>. The\naccount entity&#39;s <code>verification</code> (<code>Person::exportAsLocal()</code>) is read from\nthat table once per request (<code>exportOf()</code>, a whole-table index), never\nstored on the cached actor, which is rewritten whole on every refresh. The\nweb app draws one check, <code>VerifiedBadge</code>, for this and for Bluesky&#39;s own\nverification (<code>bluesky.verified</code>), naming who verified; <code>BlueskyBadge</code> is\nthe butterfly alone. The Fediverse&#39;s <code>rel=&quot;me&quot;</code> link verification\n(<code>ProfileLinkVerifier</code>, <code>VerifiedCheck</code>) is a different thing — a page\nproving a profile row — and stays apart. A deleted account&#39;s verification goes with it (<code>ActorCascadeService</code>, not on a suspension).</p>\n<p>Bluesky is where the instance&#39;s verifications are published: the\nadministrator&#39;s verifying account (<code>verification_account</code>) issues an\n<code>app.bsky.graph.verification</code> record per verified DID from its repository\n(<code>Atproto\\Publisher\\BlueskyVerifications</code>, local id\n<code>verification:&lt;did&gt;</code>). The record names the account&#39;s handle and display\nname, so it is withdrawn and written again when either changes —\n<code>Publisher::publishProfile()</code> for a local account, <code>BlueskyActorService::store()</code>\nfor a Bluesky one, both resolving the service lazily — and moved by\n<code>AtprotoPublish</code> (<code>verifications</code>) when the administrator chooses another\nverifying account. Bluesky apps show it once Bluesky trusts the verifying\naccount as a verifier; see the Bluesky specification, §12.6.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"accounts-this-instance-verified","manual":false,"prev":{"path":"/docs/architecture-shared-lists-to-mute-or-block","title":"Shared lists to mute or block"},"next":{"path":"/docs/architecture-discovery","title":"Discovery"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-discovery","path":"/docs/architecture-discovery","title":"Discovery","description":"All three return the previous handler's response untouched when FediverseService::jailed() says the instance is in allow-list mode with an empty list.","group":"architecture","html":"<p><code>WellKnown/WebfingerHandler</code> is registered as a Nextcloud well-known handler and serves three services at the server root:</p>\n<ul>\n<li><strong>WebFinger:</strong> <code>/.well-known/webfinger?resource=acct:user@domain</code> — returns the <code>self</code> link to the actor. The href is the actor&#39;s <strong>stored id</strong>, not a URL built from the host the request arrived under: on an instance reachable under two names, the request-derived form handed a remote server an actor id that disagreed with the document it then fetched. The <code>subject</code> is always the account&#39;s own handle, <code>acct:&lt;preferredUsername&gt;@&lt;social address&gt;</code>, whichever form found it (<code>acct:@user@host</code>, another letter case, no <code>acct:</code> scheme, the actor id), and the host part of a handle is compared case-insensitively</li>\n<li><strong>NodeInfo:</strong> <code>/.well-known/nodeinfo</code> — returns the discovery document pointing at the app&#39;s own <code>/apps/social/.well-known/nodeinfo/2.0</code> route (<code>OAuthController::nodeinfo2()</code>), which carries the actual server metadata</li>\n<li><strong>host-meta:</strong> <code>/.well-known/host-meta</code></li>\n</ul>\n<p>All three return the previous handler&#39;s response untouched when <code>FediverseService::jailed()</code> says the instance is in allow-list mode with an empty list.</p>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"discovery","manual":false,"prev":{"path":"/docs/architecture-accounts-this-instance-verified","title":"Accounts this instance verified"},"next":{"path":"/docs/architecture-reading-a-timeline","title":"Reading a timeline"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-reading-a-timeline","path":"/docs/architecture-reading-a-timeline","title":"Reading a timeline","description":"The first decides which posts belong in the page: it carries all the joins and filters (recipients, follows, hidden actors, duplicate suppression) but projects a single column, s.nid. The…","group":"architecture","html":"<p>A timeline is read in two queries rather than one.</p>\n<p>The first decides <em>which</em> posts belong in the page: it carries all the joins\nand filters (recipients, follows, hidden actors, duplicate suppression) but\nprojects a single column, <code>s.nid</code>. The second fetches the rows for exactly\nthose ids, joining only what is needed to render them.</p>\n<p>The reason is <code>SELECT DISTINCT</code>. Joining the recipients and follows tables can\nreturn a stream more than once, so the query has always been <code>DISTINCT</code> — over\neighty columns, several of them TEXT. A database cannot deduplicate that\nwithout building and sorting the entire matching set first, which is why a\ntimeline used to cost the same whether twenty rows were asked for or a hundred.\nDeduplicating one integer is cheap; the wide read is then a primary-key lookup\nof twenty rows.</p>\n<p>Measured with <code>occ social:benchmark</code> on 20 000 notes: the home timeline went\nfrom 219 ms to 89 ms and the public timeline from 121 ms to 29 ms, returning\nthe same rows in the same order.</p>\n<p>The status a row <em>points at</em> — the post a boost repeats, the post a notification\nis about — is joined by <code>SocialCrossQueryBuilder::leftJoinObjectStatus()</code>, and\nthat join carries the viewer bound of its own: addressed to the public\ncollection, written by the viewer, addressed to the viewer, or written by\nsomebody the viewer follows, as correlated <code>EXISTS</code> clauses rather than as\nfurther joins (a second FROM entry for the dest or follow table is a cartesian\nproduct). A boost carries the audience of the <em>booster</em>, not of the post, so\nwithout this a remote <code>Announce</code> of a followers-only status handed that status,\nin full, to everyone the booster reaches. When the viewer is not entitled to the\nobject the joined columns come back empty, which reads downstream as &quot;no\nobject&quot;: the row stays, its content does not.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"reading-a-timeline","manual":false,"prev":{"path":"/docs/architecture-discovery","title":"Discovery"},"next":{"path":"/docs/architecture-frontend-architecture","title":"Frontend Architecture"},"parent":"architecture-what-a-poll-costs"},{"slug":"architecture-frontend-architecture","path":"/docs/architecture-frontend-architecture","title":"Frontend Architecture","description":"The user interface is a Vue 3 front end using Vue Router, Pinia, @nextcloud/vue components, @nextcloud/axios, DOMPurify (via src/utils/sanitizeHtml.js), and the Twemoji pictures of…","group":"architecture","html":"<p>The user interface is a <strong>Vue 3</strong> front end using Vue Router, Pinia, <code>@nextcloud/vue</code> components, <code>@nextcloud/axios</code>, DOMPurify (via <code>src/utils/sanitizeHtml.js</code>), and the Twemoji pictures of <code>@discordapp/twemoji</code>, which the build copies into <code>img/twemoji/</code>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":[{"path":"/docs/architecture-entry-bundles","title":"Entry bundles","description":"The OStatus bundle and src/views/OStatus.vue are therefore dead code today: OStatusController::subscribe() and followRemote() both render the main template, so remote-follow lands in the…","parent":true},{"path":"/docs/architecture-store","title":"Store","description":"src/store/ holds six Pinia stores — timeline, account, settings, errors, notifications and instance — and index.js creates the Pinia every entry point installs. Components reach them…","parent":true},{"path":"/docs/architecture-routes-and-views","title":"Routes and views","description":"profile.followers and profile.following render the same ProfileFollowers component; it decides what to load from the route.","parent":true},{"path":"/docs/architecture-components","title":"Components","description":"A post in a list is a row, not a card. TimelineEntry flattens the post it holds (:not(.timeline-entry--direct), so on Activities too): no frame, no shadow, padding taken back to the row, a…","parent":true},{"path":"/docs/architecture-direct-messages","title":"Direct messages","description":"presents the direct timeline as a conversation list beside the selected thread. The list calls the Mastodon-compatible GET /api/v1/conversations route (40 newest conversations per…","parent":true}],"anchor":"frontend-architecture","manual":false,"prev":{"path":"/docs/architecture-reading-a-timeline","title":"Reading a timeline"},"next":{"path":"/docs/architecture-entry-bundles","title":"Entry bundles"},"parent":null},{"slug":"architecture-entry-bundles","path":"/docs/architecture-entry-bundles","title":"Entry bundles","description":"The OStatus bundle and src/views/OStatus.vue are therefore dead code today: OStatusController::subscribe() and followRemote() both render the main template, so remote-follow lands in the…","group":"architecture","html":"<p><code>webpack.common.js</code> defines these entries; the Nextcloud webpack preset prefixes the output with the app id, so they land in <code>js/</code> as:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Bundle</th>\n<th>Source</th>\n<th>Loaded by</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>social-social.js</code></td>\n<td><code>src/main.js</code></td>\n<td><code>templates/main.php</code> — the main SPA</td>\n</tr>\n<tr>\n<td><code>social-dashboard.js</code></td>\n<td><code>src/dashboard.js</code></td>\n<td><code>SocialWidget::load()</code></td>\n</tr>\n<tr>\n<td><code>social-oauth.js</code></td>\n<td><code>src/oauth.js</code></td>\n<td><code>templates/oauth2.php</code></td>\n</tr>\n<tr>\n<td><code>social-profilePage.js</code></td>\n<td><code>src/profile.js</code></td>\n<td><code>ProfileSectionListener</code></td>\n</tr>\n<tr>\n<td><code>social-ostatus.js</code></td>\n<td><code>src/ostatus.js</code></td>\n<td>nothing — no <code>addScript()</code> call references it</td>\n</tr>\n<tr>\n<td><code>social-filesAction.js</code></td>\n<td><code>src/filesAction.js</code></td>\n<td><code>FilesScriptsListener</code>, on the Files app&#39;s <code>LoadAdditionalScriptsEvent</code> — <strong>alone</strong>, see below</td>\n</tr>\n<tr>\n<td><code>social-adminSettings.js</code></td>\n<td><code>src/adminSettings.js</code></td>\n<td><code>AdminSettings::getForm()</code> — Administration → Aloha Social</td>\n</tr>\n</tbody></table></div>\n<p>The OStatus bundle and <code>src/views/OStatus.vue</code> are therefore dead code today: <code>OStatusController::subscribe()</code> and <code>followRemote()</code> both render the <code>main</code> template, so remote-follow lands in the main SPA on its <code>/ostatus/follow</code> route.</p>\n<p>None of those entries is self-contained. Vue, <code>@nextcloud/vue</code> and pinia used to be compiled into each of them, so opening the Dashboard and then the app downloaded the framework twice — 276 KB and then 347 KB gzipped, most of it the same bytes. The <code>framework</code> cache group in <code>webpack.common.js</code> puts what more than one entry needs into <code>social-framework.js</code>, which they share; <code>minChunks: 2</code> leaves a library only one entry uses inside that entry, so the single-page reader pays a few KB rather than the union. Gzipped: the app alone goes 347 KB → 354 KB, the Dashboard alone 276 KB → 306 KB, the Dashboard and then the app 623 KB → 368 KB, and adding a profile page after that 949 KB → 429 KB.</p>\n<p><strong>Every <code>Util::addScript()</code> for this app therefore loads <code>social-framework</code> before the entry</strong> — with one deliberate exception: <code>social-filesAction.js</code> registers &quot;Share to Aloha Social&quot; in the Files app and is loaded on every Files page, most of which will never post anything, so it is excluded from the <code>framework</code> cache group (<code>SELF_CONTAINED</code> in <code>webpack.common.js</code>), carries its few KB of <code>@nextcloud/files</code> and l10n itself, and is loaded by <code>FilesScriptsListener</code> with <code>addInitScript()</code> and nothing before it. It hands the picked paths to the app as <code>?attach=</code> query parameters; <code>Navigation.vue</code> opens the New post dialog with them and takes them off the address, and the composer attaches them through the same <code>attachPaths()</code> its own picker uses. The <code>overrides</code> entry for <code>@nextcloud/vue</code> in <code>package.json</code> exists for this dependency: <code>@nextcloud/vue</code> 9.12 optionally peers on a <code>@nextcloud/files</code> pre-release, and without the override <code>npm ci</code> refuses the 4.0.0 the server itself ships. Getting that wrong fails silently rather than loudly: webpack&#39;s runtime queues the startup module waiting for a chunk that never arrives, so the script runs to completion, nothing is thrown, nothing reaches the console, and the page simply stays empty. <code>tests/js/bundles.test.js</code> boots the built bundles in a jsdom window to pin it — an entry served alone injects no stylesheets and does nothing, and served after the framework it starts — and checks each of the five <code>addScript()</code> sites for the order. The same file pins the size budget <code>webpack.common.js</code> sets under <code>performance</code>: a warning (never a failed build) when a chunk passes 1 MiB or an entry with the framework chunk passes 1.4 MiB — sized just above the bundle as committed, and the test keeps it within a third of it, so growth is what warns rather than nothing.</p>\n<p><code>social-profilePage.js</code> is loaded on Nextcloud&#39;s profile page for every user, whether or not they have posted, so it carries the section, the timeline switcher and <code>ProfileStatusCard</code> but not the post renderer: the card loads <code>TimelineEntry</code> with <code>defineAsyncComponent</code>, which fetches the same chunk the app uses for it once there is a post to draw.</p>\n<p><code>optimization.concatenateModules</code> stays <code>false</code>. Scope hoisting is worth about a kilobyte and makes the build irreproducible: two runs over identical source emit alternating Terser manglings, and CI compares the committed bundle against a fresh build.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"entry-bundles","manual":false,"prev":{"path":"/docs/architecture-frontend-architecture","title":"Frontend Architecture"},"next":{"path":"/docs/architecture-store","title":"Store"},"parent":"architecture-frontend-architecture"},{"slug":"architecture-store","path":"/docs/architecture-store","title":"Store","description":"src/store/ holds six Pinia stores — timeline, account, settings, errors, notifications and instance — and index.js creates the Pinia every entry point installs. Components reach them…","group":"architecture","html":"<p><code>src/store/</code> holds six Pinia stores — <code>timeline</code>, <code>account</code>, <code>settings</code>, <code>errors</code>, <code>notifications</code> and <code>instance</code> — and <code>index.js</code> creates the Pinia every entry point installs. Components reach them through <code>mapStores</code>, or through a composable where the same few values are wanted together: <code>useServerData</code>, <code>useCurrentUser</code> and <code>useAccount</code> in <code>src/composables/</code> replaced the three mixins the app used to carry.</p>\n<p>Server-side state is not a store: it is passed through Nextcloud&#39;s initial state as <code>serverData</code> and read by <code>useServerData</code>.</p>\n<p>Reader preferences that shape the first feed are in that same initial state. <code>hideCounts</code> keeps counts consistent between the server response and optimistic actions; <code>hideRepliesInFeeds</code> filters replies out of the Home, public and hashtag feed cards while leaving them available in conversations. The <code>feed_preferences</code> API stores that choice per account, and the first server-provided Home page uses it before rendering so a refresh does not briefly show replies the reader chose to hide.</p>\n<p>The reader&#39;s own account travels the same way. <code>NavigationController::provideViewerAccount()</code> puts the cached actor — the one <code>GET /api/v1/global/account/info</code> answers with, in the same export format — into the initial state as <code>currentAccount</code>, and <code>App.vue</code> seeds the account store from it. The app used to ask for it in <code>beforeMount()</code>, which cost every load a second authenticated round trip before anything could render, for something the page request was already holding. A page rendered before the account exists provides nothing, and the app asks the old way.</p>\n<p>The account&#39;s name comes with it, in <code>serverData.viewer</code>: the <code>username</code> chosen on the setup screen and the <code>address</code> (<code>username@</code> the social address). The username need not be the Nextcloud user id, so <code>useCurrentUser()</code> keeps the two apart: <code>currentUser</code> is the Nextcloud user, for what Nextcloud answers to (avatars, its profile page); <code>username</code>, <code>cloudId</code> and <code>socialId</code> are the account&#39;s, and <code>isOwnHandle()</code> is how a page tells the reader&#39;s own profile, messages and shorts from anybody else&#39;s. The store makes the seeded account current under the handle it files it by (<code>setOwnAccount()</code>), not under one built from the user id. Other accounts carry their Nextcloud user as <code>nextcloud_user</code> (see API.md); avatars and <code>/u/</code> profile links go by <code>nextcloudUserOf()</code> in <code>src/utils/accountLocality.js</code>, never by the username. <code>serverData.socialAddress</code> is the host addresses end in, for the setup screen&#39;s preview.</p>\n<p>The Mastodon and ActivityPub entities the app exchanges are described as JSDoc\ntypedefs in <code>src/types/</code>, and <code>npm run typecheck</code> holds the stores, services and\nutilities to them (<code>jsconfig.json</code>). The same script runs <code>vue-tsc</code> over the\nwhole of <code>src/</code>, single-file components included (<code>jsconfig.vue.json</code>), and\nfails on any error.</p>\n<p>Each store is installed per Pinia instance rather than per module registration, which is the difference that matters for tests — two Pinias give two sets of state, where the Vuex modules shared one object literal between them.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"store","manual":false,"prev":{"path":"/docs/architecture-entry-bundles","title":"Entry bundles"},"next":{"path":"/docs/architecture-routes-and-views","title":"Routes and views"},"parent":"architecture-frontend-architecture"},{"slug":"architecture-routes-and-views","path":"/docs/architecture-routes-and-views","title":"Routes and views","description":"profile.followers and profile.following render the same ProfileFollowers component; it decides what to load from the route.","group":"architecture","html":"<p><code>src/router.js</code> declares:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Path</th>\n<th>Route name</th>\n<th>View</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>/</code></td>\n<td>— (redirects to <code>timeline</code>)</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>/timeline/:type?</code></td>\n<td><code>timeline</code></td>\n<td>Timeline</td>\n</tr>\n<tr>\n<td><code>/timeline/:type?/tags/:tag</code></td>\n<td><code>tags</code></td>\n<td>Timeline</td>\n</tr>\n<tr>\n<td><code>/timeline/:type?/list/:id</code></td>\n<td><code>list</code></td>\n<td>Timeline</td>\n</tr>\n<tr>\n<td><code>/@:account</code></td>\n<td><code>profile</code></td>\n<td>Profile + ProfileTimeline</td>\n</tr>\n<tr>\n<td><code>/@:account/followers</code></td>\n<td><code>profile.followers</code></td>\n<td>Profile + ProfileFollowers</td>\n</tr>\n<tr>\n<td><code>/@:account/following</code></td>\n<td><code>profile.following</code></td>\n<td>Profile + ProfileFollowers</td>\n</tr>\n<tr>\n<td><code>/@:account/portfolio</code></td>\n<td><code>profile.portfolio</code></td>\n<td>Profile + Portfolio</td>\n</tr>\n<tr>\n<td><code>/@:account/tagged</code></td>\n<td><code>profile.tagged</code></td>\n<td>Profile + ProfileTagged</td>\n</tr>\n<tr>\n<td><code>/@:account/collections</code></td>\n<td><code>profile.collections</code></td>\n<td>Profile + ProfileCollections</td>\n</tr>\n<tr>\n<td><code>/collections/:id</code></td>\n<td><code>collection</code></td>\n<td>CollectionPage</td>\n</tr>\n<tr>\n<td><code>/places/:id</code></td>\n<td><code>place</code></td>\n<td>PlacePage</td>\n</tr>\n<tr>\n<td><code>/discover</code></td>\n<td><code>discover</code></td>\n<td>Discover</td>\n</tr>\n<tr>\n<td><code>/follow_requests</code></td>\n<td><code>follow-requests</code></td>\n<td>FollowRequests</td>\n</tr>\n<tr>\n<td><code>/blocked</code></td>\n<td><code>blocked-accounts</code></td>\n<td>BlockedAccounts</td>\n</tr>\n<tr>\n<td><code>/filtered</code></td>\n<td>— (redirects to <code>blocked-accounts</code>)</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>/migration</code></td>\n<td><code>migration</code></td>\n<td>Migration</td>\n</tr>\n<tr>\n<td><code>/settings</code></td>\n<td><code>settings</code></td>\n<td>Settings</td>\n</tr>\n<tr>\n<td><code>/shorts</code></td>\n<td><code>shorts</code></td>\n<td>VideoShorts</td>\n</tr>\n<tr>\n<td><code>/reels</code></td>\n<td>— (redirects to <code>shorts</code>, keeping the query)</td>\n<td>—</td>\n</tr>\n<tr>\n<td><code>/switch</code></td>\n<td><code>switch</code></td>\n<td>SwitchWizard</td>\n</tr>\n<tr>\n<td><code>/statistics</code></td>\n<td><code>statistics</code></td>\n<td>Statistics</td>\n</tr>\n<tr>\n<td><code>/search/:term?</code></td>\n<td><code>search</code></td>\n<td>Search</td>\n</tr>\n<tr>\n<td><code>/@:account/:id</code></td>\n<td><code>single-post</code></td>\n<td>TimelineSinglePost</td>\n</tr>\n<tr>\n<td><code>/ostatus/follow</code></td>\n<td>—</td>\n<td>Profile + ProfileTimeline</td>\n</tr>\n</tbody></table></div>\n<p><code>profile.followers</code> and <code>profile.following</code> render the same <code>ProfileFollowers</code> component; it decides what to load from the route.</p>\n<p>Views outside the router: <code>AccountSetup.vue</code> (rendered by <code>App.vue</code> while the reader has no local account: a branded welcome and a collapsible fediverse explanation precede the choice between creating an account here and publishing an existing external handle on the Nextcloud profile. Creating is selected by default, and only the selected form is shown; the creation form is <code>src/components/AccountSetupForm.vue</code>, which the sign-in page an app opens uses as well. The suggested username, live address preview, permanence warning and optional Bluesky address appear before explicit submission; the Bluesky address is computed by <code>src/utils/blueskyHandle.js</code>, a port of <code>HandleMapper::label()</code> that <code>tests/Atproto/Identity/fixtures/handle-labels.json</code> pins to the PHP from both sides, and the number the server adds to a taken label is only announced, since the page cannot know it. Linking creates no local account and does not enable posting through the external one: the screen ends on a done view with a link back to Nextcloud and a way to the creation form, and a later visit notes the <code>linkedHandle</code> above the two answers), <code>Dashboard.vue</code> (mounted by the dashboard entry), <code>OAuth2Authorize.vue</code> (mounted by the OAuth entry on <code>#social-oauth2</code>; for somebody without an account it asks for the username first, without the linking answer, which gives an app nothing to sign in to, and reloads into the consent once the account exists), <code>ProfilePageIntegration.vue</code> (registered by the profile entry as the <code>social-profile-section</code> custom element), and <code>OStatus.vue</code> (unreachable, per the table above).</p>\n<p>The Nextcloud Profile page&#39;s classic script queue runs Aloha Social&#39;s <code>profile.js</code>\nbefore the Profile app&#39;s module entry. The latter creates\n<code>OCA.Profile.ProfileSections</code> and immediately reads the registry while mounting\nthe page. Registering from Aloha Social with optional chaining silently skipped the\nsection because the registry did not exist yet; deferring to a timer or\n<code>DOMContentLoaded</code> runs too late, after the Profile page has already taken its\ninitial section snapshot. <code>services/profileSections.js</code> intercepts the\nregistry&#39;s first assignment and registers synchronously during that assignment,\nthen restores the ordinary data property. The profile custom element also owns\na separate Vue app, so it installs Aloha Social&#39;s normal Nextcloud globals (<code>t</code>, <code>n</code>,\n<code>OC</code> and <code>OCA</code>) before rendering; without them, the section mounted but its\nfirst translated label threw during render. It renders in the light DOM so the\nProfile page&#39;s theme and Aloha Social&#39;s shared timeline component styles apply; a\nshadow root isolated those styles and left posts as unformatted list items.\nProfile posts use the same <code>account</code> entry type as Aloha Social&#39;s own profile view,\nand account counts use compact theme-aware metric chips. Tests cover delayed\nand immediate registry creation, the custom element&#39;s app setup, and profile\ntimeline data passed to Aloha Social&#39;s shared entry component.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"routes-and-views","manual":false,"prev":{"path":"/docs/architecture-store","title":"Store"},"next":{"path":"/docs/architecture-components","title":"Components"},"parent":"architecture-frontend-architecture"},{"slug":"architecture-components","path":"/docs/architecture-components","title":"Components","description":"A post in a list is a row, not a card. TimelineEntry flattens the post it holds (:not(.timeline-entry--direct), so on Activities too): no frame, no shadow, padding taken back to the row, a…","group":"architecture","html":"<p><strong>A post in a list is a row, not a card.</strong> <code>TimelineEntry</code> flattens the post it holds (<code>:not(.timeline-entry--direct)</code>, so on Activities too): no frame, no shadow, padding taken back to the row, a hairline drawn by the row&#39;s <code>::after</code> in the middle of the gap below it, clear of the hover tint (none above a reply, whose elbow line joins it to its parent) and a hover tint across the whole row, which opens the thread. The avatar stays in the entry&#39;s own column beside the post, which without a frame reads as part of it. The post component keeps its card wherever it is drawn outside a list. A notification is a row of the same kind: its summary line (faces, what happened, <code>shortAgo()</code> age) stands where a post&#39;s face would, the post or account it is about hangs under the summary&#39;s words (<code>margin-inline-start: 36px</code>, past the 24 px face and its gap), the account of a follow loses <code>UserEntry</code>&#39;s card, and the unread mark is a straight bar drawn by <code>::before</code> on the row&#39;s start edge beside the <strong>New</strong> tag (a notification is never a reply, so the elbow line&#39;s pseudo-element is free). The phone rule that makes room for a post&#39;s face in the header corner skips notifications, and <code>border: none</code> undoes the Nextcloud notifications app&#39;s global <code>.notification</code> bottom border. The reading timelines narrow the column by overriding <code>--social-column</code> to 616 px on <code>.social__wrapper--reading</code> (lists only; the photo and video grids keep 900). In <code>TimelinePost</code> the reply, boost and like buttons are always rendered and disabled with a reason (<code>refusedBecause</code>) when the post or its author does not allow them, so the row never shifts; their glyphs are transparent at rest on pointer devices and appear on hover or focus, except a pressed like or boost; touch screens (<code>hover: none</code>) keep them. With a pointer the row takes no room of its own: unless the post shows reactions, <code>TimelineEntry</code> gives the footer no height and floats the pill over the top end of the row, across the timestamp. A like or boost the reader gave then shows as the header&#39;s <code>.post-given</code> mark beside the timestamp (hidden everywhere else, <code>aria-hidden</code> because the pressed buttons carry the state), and the pressed glyph waits in the pill with the others. The reaction bar draws no add button of its own under a post (<code>offerAdd: false</code>): reactions are reached by holding the heart or through <strong>Add a reaction</strong> in <code>PostMenu</code>. Ages are <code>shortAgo()</code> (<code>src/utils/relativeTime.js</code>): the locale&#39;s narrow units through <code>Intl.NumberFormat</code> up to five weeks, then the date. The <code>Intl</code> formatters are built once per locale and kind and kept — an age is re-read on every tick of the clock for every post on screen — in the locale <code>src/utils/locale.js</code> resolves: the reader&#39;s Nextcloud locale, else their language, else the browser&#39;s, passing over a tag <code>Intl</code> rejects.</p>\n<p><code>src/components/</code> holds the timeline and profile UI: <code>TimelineList</code>, <code>TimelineEntry</code>, <code>TimelinePost</code>, <code>TimelineAvatar</code>, <code>ActorAvatar</code>, <code>ProfileInfo</code>, <code>FollowButton</code>, <code>UserEntry</code>, <code>Navigation</code>, <code>Search</code>, <code>FirstRun</code> (the four-step introduction a new account sees once, in place of the beta banner: the address, the colleagues and starter packs from the same routes Discover reads, the follows import Settings offers, and a hand-off to the composer), <code>FirstPostCelebration</code>, <code>MediaAttachment</code>, <code>PostAttachment</code>, <code>Emoji</code>, <code>EmptyContent</code>, <code>QuotedPost</code>, <code>HashtagFollowButton</code>, <code>HashtagFollowedList</code>, the <code>Gallery</code> group (<code>GalleryCarousel</code>, <code>GalleryMedia</code>, <code>GalleryRatio.js</code>), the <code>Composer/</code> group (<code>Composer</code>, <code>PreviewGrid</code>, <code>PreviewGridItem</code>, <code>SubmitStatusButton</code>, <code>LanguageSelect</code>), <code>ScheduledPosts</code> (the posts waiting to go out, in Settings), the <code>Visibility/</code> group (<code>VisibilitySelect</code>, <code>VisibilityIcon</code>), and <code>MessageContent.js</code>, a render-function component that parses a post body and rebuilds it as Vue nodes (turning mentions and hashtags into <code>router-link</code>s and emoji into <code>Emoji</code> components). AltBadge<code>, </code>Emoji<code>, </code>EmptyContent<code>, </code>QuotedPost<code>, </code>HashtagFollowButton<code>, </code>HashtagFollowedList<code>, the </code>Gallery<code> group (</code>GalleryCarousel<code>, </code>GalleryMedia<code>, </code>GalleryRatio.js<code>), the </code>Composer/<code> group (</code>Composer<code>, </code>PreviewGrid<code>, </code>PreviewGridItem<code>, </code>SubmitStatusButton<code>), the </code>Visibility/<code> group (</code>VisibilitySelect<code>, </code>VisibilityIcon<code>), and </code>MessageContent.js<code>, a render-function component that parses a post body and rebuilds it as Vue nodes (turning mentions and hashtags into </code>router-link<code>s and emoji into </code>Emoji<code>components).</code>src/components/<code>holds the timeline and profile UI:</code>TimelineList<code>, </code>TimelineEntry<code>, </code>TimelinePost<code>, </code>TimelineAvatar<code>, </code>ActorAvatar<code>, </code>ProfileInfo<code>, </code>FollowButton<code>, </code>UserEntry<code>, </code>Navigation<code>, </code>Search<code>, </code>FirstRun<code>(the four-step introduction a new account sees once, in place of the beta banner, and that</code>?welcome=1<code>on the home timeline shows again: the address, the colleagues and starter packs from the same routes Discover reads, the follows import Settings offers, and a hand-off to the composer),</code>StarterPackDetail<code>(one open starter pack, whatever it was read from — Discover&#39;s packs and a Bluesky pack&#39;s own page both draw it, handing it how to follow everybody and how to follow one member: a Follow per member, progress, a confirmation above ten people, failures and &quot;nobody followed&quot; reported as errors),</code>FirstPostCelebration<code>, </code>MediaAttachment<code>, </code>PostAttachment<code>, </code>Emoji<code>, </code>EmptyContent<code>, </code>QuotedPost<code>, </code>HashtagFollowButton<code>, </code>HashtagFollowedList<code>, the </code>Gallery<code> group (</code>GalleryCarousel<code>, </code>GalleryMedia<code>, </code>GalleryRatio.js<code>), the </code>Composer/<code> group (</code>Composer<code>, </code>PreviewGrid<code>, </code>PreviewGridItem<code>, </code>SubmitStatusButton<code>), the </code>Visibility/<code> group (</code>VisibilitySelect<code>, </code>VisibilityIcon<code>), the settings sections (</code>AccountSettings<code>, </code>ListsSettings<code>, </code>MigrationSettings<code>, </code>IntroductionSettings<code>— the link back to that introduction —,</code>ShortcutsSettings<code> — the on/off switch for the keyboard shortcuts (</code>keyboard_shortcuts<code>user value,</code>serverData.keyboardShortcuts<code>) above </code>ShortcutList<code>) the two account dialogs (</code>MuteDialog<code>, </code>ListMembershipDialog<code>), </code>ShortComposerDialog<code>(**New short**, behind the **+** on the Shorts stack and on the viewer&#39;s own tile in the Home Shorts bar; it asks for the lifetime first — *Keep it on my profile* makes a post with a video, *Only for 24 hours, for my followers* sends the video to</code>POST /api/v1/stories<code>instead of becoming a post, and a picture or a text card for 24 hours goes on to</code>StoryComposerDialog<code>&#39;s editor: upload, drop or record a video, trim it, pick a cover and post it — the cutting, recording and frame-grabbing are in </code>src/utils/shortVideo.js<code>, done in the browser with </code>MediaRecorder<code>and a canvas so the server stores an ordinary video attachment and knows nothing about trimming; the chosen cover goes up as</code>thumbnail<code>and</code>CacheDocumentService::applyCustomPoster()<code>puts it where the generated poster would have been), and</code>MessageContent.js<code>, a render-function component that parses a post body and rebuilds it as Vue nodes (turning mentions and hashtags into </code>router-link<code>s and emoji into </code>Emoji` components).</p>\n<p>The sidebar and post action labels are source literals passed to <code>t(&#39;social&#39;, …)</code>;\nthe German catalog ships each entry in both <code>l10n/de_DE.json</code> and\n<code>l10n/de_DE.js</code>, which are the two catalog forms this app includes. The\n<code>TranslatableStringsTest</code> checks every singular label in <code>Navigation.vue</code>,\n<code>TimelinePost.vue</code> and <code>DirectMessages.vue</code> against both files, so adding a\nmenu item without its translation is caught before the interface silently\nfalls back to English.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"components","manual":false,"prev":{"path":"/docs/architecture-routes-and-views","title":"Routes and views"},"next":{"path":"/docs/architecture-direct-messages","title":"Direct messages"},"parent":"architecture-frontend-architecture"},{"slug":"architecture-direct-messages","path":"/docs/architecture-direct-messages","title":"Direct messages","description":"presents the direct timeline as a conversation list beside the selected thread. The list calls the Mastodon-compatible GET /api/v1/conversations route (40 newest conversations per…","group":"architecture","html":"<h2 id=\"directmessages-vue\">DirectMessages.vue</h2>\n<p> presents the direct timeline as a conversation list beside\nthe selected thread. The list calls the Mastodon-compatible\n<code>GET /api/v1/conversations</code> route (40 newest conversations per request), shows\nthe latest status as a plain-text preview, and marks unread conversations.\nThe server answers one conversation per thread, as Mastodon&#39;s own\n<code>AccountConversation</code> does (unique per conversation <em>and</em> participant set), so\na direct message that is not a reply starts a new conversation there and in\nevery other client. The pane folds the rows between one set of participants\ninto one chat (<code>chats</code>, keyed by the sorted handles of everybody but the\nreader): the chat carries the newest thread&#39;s id and message, is unread while\nany of its threads is, and its row action dismisses every thread. The server\nand the client API are left as they are — the Bluesky chat bridge and\nthird-party clients rely on a conversation being a thread.\nThe selected conversation is stored in the <code>conversation</code> query parameter on\nthe direct timeline route, so opening or refreshing a link restores the chat;\nthe route keeps the thread id it was opened with and the chat is found by any\nof its threads (<code>chatOf()</code>), so it stays open when a new thread with the same\nperson arrives. Opening a chat loads the context of each of its threads&#39;\nnewest messages (up to eight, newest first) from\n<code>GET /api/v1/statuses/{nid}/context</code>; ancestors, the threads&#39; newest messages\nand descendants are combined, de-duplicated by status id and ordered by\n<code>created_at</code> before rendering through <code>TimelineEntry</code>. A successful load\nattempts <code>POST /api/v1/conversations/{id}/read</code> for each unread thread;\nfailure to persist a read marker is logged without hiding the already loaded\nmessages.</p>\n<p>Starting a conversation searches <code>GET /api/v1/global/accounts/search</code> and selects exactly one account. If that person already has a conversation in the loaded inbox, that thread is opened; duplicate API rows for the same account are collapsed to the newest row. Otherwise the right pane becomes a normal chat: it shows the selected person and a compact message field, with no audience selector, post toolbar or multi-recipient composer. <code>sendMessage()</code> always posts with <code>visibility: direct</code> to <code>POST /api/v1/statuses</code>, prepending the selected account&#39;s <code>@acct</code> mention internally because Aloha Social&#39;s ActivityPub delivery derives direct recipients from mentions. The person using the chat does not need to type that mention. Replies include the last status id as <code>in_reply_to_id</code>; successful sends clear the field, refresh the inbox and open the conversation returned for that peer. Failed sends retain the draft and display an error. The pane keeps itself current the way <code>TimelineList</code> does: it subscribes to <code>onTimelinePush()</code> and, with notify_push, re-reads every five minutes as a safety net, without it every 30 seconds; a hidden tab asks for nothing and catches up when it is looked at again (at once if a push arrived meanwhile, otherwise once it has been away a poll interval). A refresh (<code>refreshConversations()</code>) lays the first page over the rows on screen — the page&#39;s rows first, every older row the reader paged to after them, and the cursor kept once they have paged — and re-reads the open chat quietly (<code>loadThread(id, true)</code>), so nothing on screen is replaced by &quot;Loading…&quot; and the thread is scrolled to its end only when a message came or went. A reply that arrives in the open chat is marked read like one the reader opened; after a read marker is written the pane re-reads <code>GET /api/v1/conversations/unread_count</code>, which is the sidebar badge. The direct route removes the reading-column padding and announcement strip. The panes share one flat app-content surface with only a divider. The page reuses the feed&#39;s parts rather than stock list and form components: conversations and recipient results are feed-style rows (40px face, bold name, preview line, <code>shortAgo()</code> age, hover tint, hairline between rows) with <strong>Remove conversation</strong> in an <code>NcActions</code> menu shown on hover or focus (always on touch); <strong>All / Unread</strong> is <code>TimelineSwitcher</code>; the search field appears from nine conversations; empty states are <code>EmptyContent</code> with the <code>no-messages</code> illustration, whose action without a route is emitted as <code>action</code>. Incoming and outgoing messages retain <code>TimelineEntry</code> for content and attachments, with <code>type=&quot;direct&quot;</code>, which adds <code>timeline-entry--direct</code> so the feed&#39;s list-row rules in <code>TimelineEntry.vue</code> leave the bubble alone; their post headers are hidden and the chat layout supplies date breaks and message times. A time is drawn under the last message of a run (same author, same day) and beside the others on hover. Outgoing bubbles mix the author&#39;s <code>--account-hue</code> (set on the post, so the reader&#39;s own colour) into the page background; incoming ones use the hover grey. The thread, the recipient picker and the message field keep to the feed&#39;s 616px column. The message field is the composer&#39;s pill with the reader&#39;s face, an auto-growing textarea, a send button that appears once something is written, and Ctrl/Cmd+Enter to send. The peer appears in the thread header with their handle, so each bubble does not repeat the author. At narrow widths the list and chat become separate views with a back arrow. Older conversations are appended a page at a time from the <code>Link</code> header&#39;s cursor.</p>\n<h2 id=\"profileinfo-vue\">ProfileInfo.vue</h2>\n<p> keeps every control for the profile in one dialog: the banner\n(a file, or the address of one), the bio and the metadata fields. The banner\nbuttons used to float over the picture on the owner&#39;s own profile, which put\nediting chrome on a page whose job is to show somebody. Applying a banner from a\nURL leaves the dialog open, because the bio and the fields may still be being\nedited.</p>\n<p>Each field row in that dialog carries its verdict, because the one thing that\nmakes a field worth filling in is invisible otherwise: a value naming a web page\nis verified by <code>ProfileLinkVerifier</code> fetching the page and looking for a link\nback with <code>rel=&quot;me&quot;</code>, and nobody finds that out by accident. The row says\nverified and when, or not verified, or — for a bare <code>example.org</code> — that nothing\nwritten that way can ever be verified; and as soon as any row is an address the\ndialog shows the exact anchor to paste on the far end, with a copy button, and\nwhat the check will and will not do. The verdicts come from the entity&#39;s own\n<code>fields</code> on <code>verify_credentials</code>, never from <code>source.fields</code>, which is the\neditable copy and carries no <code>verified_at</code>, and they are keyed by the value they\nwere made about, which is why editing a value drops its tick there and then.\n<code>fieldLink()</code> in <code>src/utils/profileFields.js</code> is the client&#39;s copy of the\nplain-text half of <code>ProfileLinkVerifier::linkOf()</code>, so the dialog offers a tick\nfor exactly the values the server would try to verify.</p>\n<p>The verdicts themselves live on the <strong>cached</strong> actor&#39;s details, which is what\nmade them fragile: a local actor is rebuilt from the <code>actors</code> row, which has no\ndetails column, so <code>ActorService::cacheLocalActor()</code> writing <code>details</code> whole\nerased <code>fields_verified</code> on every write to a profile — a new bio, one flag, one\nedited field — and the ticks came back only when the next <code>Cron\\Cache</code> pass\nre-fetched every linked page. It now carries the verdicts across, and only those:\n<code>fields_checked</code> is still dropped, which is what makes that next pass look at an\nedited value at once rather than waiting out <code>RECHECK_SECONDS</code>, and a verdict\nwhose value is no longer among the fields is dropped with it.</p>\n<h2 id=\"composer-vue\">Composer.vue</h2>\n<p> grows a second attach control beside the paperclip: the\n<code>@nextcloud/dialogs</code> file picker, so a picture already in the user&#39;s Nextcloud\ngoes straight to <code>POST /api/v1/media/from-file</code> instead of being downloaded and\nuploaded back. Both sources fill the same attachment map and share one ceiling,\nthe server&#39;s (see &quot;What the server&#39;s limits are&quot; below). The preview grid sits\nunder the text box, as Mastodon and Bluesky have it — above it, four pictures\nand their descriptions pushed the box off a phone&#39;s screen — and it is under it\nin the DOM too, so the tab order goes from the words to the descriptions. With\nanything attached the box becomes a caption field. A picture with no alt text is marked as such on its own thumbnail, and a\ndescription is saved on leaving the field rather than only when the post goes\nout, so it survives a post that is never sent.</p>\n<p>The <strong>New post</strong> dialog keeps the text and all publishing controls in one\npopup. Attachment, content-warning, emoji, visibility and send controls stay\nin the main row; <strong>More options</strong> opens the less common post tools and\npublishing settings in labelled groups. The secondary controls have text\nlabels as well as icons; scheduling and location share a group, followed by\npublishing settings, where language and reply policy sit beside each other.\nThe <strong>More options</strong> toggle leads the toolbar in every composer, including\ninline composers on feeds, profiles, search, video pages and replies. The\ndialog title carries the author&#39;s avatar and a <strong>New story</strong> action beside\nthe title when stories are available; the story action opens the 24-hour short\ncomposer. The composer&#39;s inline author row is hidden in the dialog. A restored\ndraft opens the options when it contains a non-default secondary setting.</p>\n<p><strong>What a post says about itself.</strong> Three controls in the same toolbar row as\nthe visibility menu in the inline composer, each of them a field the client API\nhas always taken and the composer never sent. The New post dialog places these\nunder <strong>Publishing settings</strong> in its expanded options.</p>\n<h2 id=\"languageselect-vue\">LanguageSelect.vue</h2>\n<p> is an icon-sized <code>NcActions</code> wearing the current code,\ndefaulting to the reader&#39;s Nextcloud language without its region\n(<code>src/utils/postLanguage.js</code>: <code>getLanguage()</code> says how the interface is\nspelled, <code>de-DE</code>, while Mastodon&#39;s per-language filters are keyed by the plain\n<code>de</code>) and remembering the last choice in <code>localStorage</code> the way the visibility\nmenu does. It is sent as <code>language</code> on every post: the server would fill in the\nsame default (<code>PostService::languageFor()</code>), but a guess the poster can see is\none they can correct, and a post that federates with <code>language: null</code> is seen\nneither by the readers who filter for a language nor by the ones who filter one\nout. The languages on offer are the ones Nextcloud itself is translated into,\nnamed at run time by <code>Intl.DisplayNames</code> so the list carries no names to\ntranslate.</p>\n<h2 id=\"scheduling\">Scheduling</h2>\n<p> is the clock beside the poll button. <code>NcDateTimePicker</code> is a\ndate library and its locales, so it is a <code>defineAsyncComponent</code> fetched when\nthe clock is pressed rather than with every composer — the same treatment the\nemoji picker gets. Pressing it proposes an hour from now rounded to five\nminutes; the minimum is five minutes out, which is <code>ScheduledStatusService</code>&#39;s\n<code>MIN_LEAD_TIME</code>, checked here as well so the refusal arrives while the time can\nstill be moved. With a time set the Post button reads <strong>Schedule</strong>, the payload\ncarries <code>scheduled_at</code> as ISO 8601 in UTC, and the answer is a <code>ScheduledStatus</code>\nrather than a <code>Status</code>: nothing is on a timeline yet, so the composer refreshes\nnothing, celebrates nothing, and says when the post will go out instead.\n<code>ScheduledPosts.vue</code> lists what is waiting, in a section of Settings rather\nthan a page of its own — the list is short (an account may hold 300), what is\ndone with an entry is one thing, and a <code>post-scheduled</code> event on the bus keeps\nit in step with the dialog that opens over it. Moving one to another time is\nleft to the API.</p>\n<h2 id=\"the-focal-point\">The focal point</h2>\n<p> is the crosshair on a thumbnail in <code>PreviewGridItem.vue</code>,\nbeside the alt text and saved by the same <code>PUT /api/v1/media/{id}</code>. The whole\npicture becomes the control while the point is being set — pressed, dragged or\nmoved by the arrow keys, which is the only way to set one without a pointer —\nand a badge on the thumbnail says a point is set once the editor is closed.\n<code>src/utils/focalPoint.js</code> holds the three conversions in one place: the browser\nmeasures a pointer from the top left with y pointing down, Mastodon reads a\npoint from the centre with y pointing <em>up</em>, and CSS wants two percentages from\nthe top left again. <code>ProfileMediaGrid.vue</code> crops its tiles through the same\nfunction, so the editor and the grid cannot disagree about which way is up.</p>\n<h2 id=\"a-reply-reaches-the-conversation\">A reply reaches the conversation</h2>\n<p> <code>prefillMessageWithMentions()</code> starts a\nreply with a pill per participant — the author of the post being answered, then\neveryone that post mentioned, deduped by full handle and never the reader\nthemselves. It used to insert the author alone, so an answer in a conversation\nof three reached one of three: the server turns the handles in the text into\nrecipients, <code>Mention</code> tags and inboxes (<code>PostService::fixRecipientAndHashtags()</code>\ninto <code>StreamService::addRecipient()</code>), and it can only address the people the\ntext names.\n<strong>The notifications page.</strong> <code>/timeline/notifications</code> is the ordinary\n<code>TimelineList</code> with three things of its own, all of them in the client so that\nthe API stays the shape every Mastodon client expects.</p>\n<p><em>The filter row</em> is <code>TimelineSwitcher</code> again, with no <code>to</code> on any option, so the\nchoice is the page&#39;s own state: <code>src/services/notifications.js</code> holds the seven\nfilters and <code>excludeTypesFor()</code> turns one into the <code>exclude_types</code> the server\ntakes (<code>TimelineApiController::notifications()</code>). The choice is part of the store&#39;s\n<code>params</code>, so it is part of <code>getTimelineIdentity</code> — changing it refetches rather\nthan hiding rows already on screen — and <code>rememberedFilter()</code>/<code>rememberFilter()</code>\nkeep it in <code>localStorage</code> under <code>social.notificationsFilter</code>, inside a\n<code>try</code>/<code>catch</code> because reading it throws in a private window. The seven labels do\nnot fit the reading column, so the row scrolls at its natural widths rather\nthan shrinking them or hiding them at a viewport breakpoint.</p>\n<p><em>Grouping</em> is <code>groupNotifications()</code> in the same service: consecutive favourites\nor boosts of one status, and consecutive follows, become one card carrying\n<code>accounts</code> (everyone in it) and <code>ids</code> (every row it stands for). Only\nconsecutive ones — folding across something that happened in between would\nreorder what happened. <code>TimelineEntry</code> draws up to <code>GROUP_FACES</code> overlapping\navatars and <code>notificationSummary()</code> writes &quot;Anna, Bob and 3 others liked your\npost&quot;; <code>newestIdOf()</code> is what keeps the read marker covering every folded row.</p>\n<p><em>Unread</em> has one rule: <strong>the page is read once it has been in front of the\nreader for <code>SEEN_AFTER</code> (two seconds) with the tab visible</strong>, and it is read up\nto the newest card on it at that moment. It used to be read by an\n<code>immediate: true</code> watcher, i.e. by rendering — and the marker is the\nserver-side Mastodon one every client shares, so a tab opened in the background\ncleared the reader&#39;s phone for notifications no human had seen. The &quot;New&quot; and\n&quot;Earlier&quot; headings are drawn against <code>notificationsStore.fetchLastRead()</code>\n(<code>GET /api/v1/markers</code>), read once when the page opens and then frozen in the\ncomponent: a boundary that followed the marker would rub itself out as the page\nwas read.</p>\n<h2 id=\"the-home-feeds-line-is-the-servers-marker-too\">The home feed&#39;s line is the server&#39;s marker too</h2>\n<p> The <em>Up to date since\n14:02</em> line on My Feed (<code>caughtUpAt</code>, <code>.timeline-caughtup</code>) used to be drawn\nfrom a place this browser kept in <code>localStorage</code> — a convenience no other\ndevice inherited, so the phone and the web each had their own idea of what was\nnew. It is now drawn from the <code>home</code> marker of <code>GET /api/v1/markers</code>, the\nposition every Mastodon client reads and writes\n(<code>timelineStore.fetchHomeMarker()</code>, asked when the list opens), and advanced by\nthe same rule as notifications: after <code>SEEN_AFTER</code> in front of the reader with\nthe tab visible, up to the newest post on the page\n(<code>timelineStore.markHomeRead()</code>, which says each position once; the server\nnever moves a marker backwards). The browser&#39;s own copy stays — as the line\nuntil the server has answered, and as the fallback for an account whose server\nmarker is empty; whichever of the two is further along wins. The other\ntimelines keep the per-browser line, because Mastodon&#39;s marker vocabulary has\n<code>home</code> and <code>notifications</code> only, and a marker no app would sync is not worth a\nrequest. The browser&#39;s copy is written when the reader leaves a list — on a\nswitch, under the key of the list being <em>left</em> and with the newest post it\nshowed, since by then the store already holds the next list, which may be one\nfetched ahead that nobody has looked at yet.</p>\n<h2 id=\"what-the-servers-limits-are-and-who-asks\">What the server&#39;s limits are, and who asks</h2>\n<p> <code>MAX_LENGTH</code> and\n<code>MAX_ATTACHMENTS</code> were hard-coded in <code>Composer.vue</code>, <code>TimelinePost.vue</code> and\n<code>src/filesAction.js</code> — the server&#39;s numbers on the day they were typed, and\nnothing kept them so. <code>src/services/instanceLimits.js</code> reads them from\n<code>GET /api/v1/instance</code> (<code>configuration.statuses.max_characters</code>,\n<code>max_media_attachments</code>), once per page, with the old constants as the fallback\na failure leaves standing. It reads the upload ceiling too\n(<code>media_attachments.image_size_limit</code>, the <code>max_size</code> app value, 10 MB until\nknown), which the composer shrinks pictures to before they are sent. It is framework-free — no Vue, no Pinia, no axios —\nbecause the Files action is loaded on every Files page without any of them;\n<code>src/store/instance.js</code> is the reactive face of it for the components.</p>\n<h2 id=\"what-waits-for-the-timeline\">What waits for the timeline</h2>\n<p> Every page used to fire four requests as it\nmounted — the timeline, <code>trends/tags</code>, <code>lists</code> and <code>notifications/unread_count</code>\n— and on a small server they contended for PHP workers: 2.3 to 3.4 seconds each\nin parallel where the timeline alone takes 0.4. <code>src/services/boot.js</code> is the\none place that knows about it: the timeline store calls <code>noteTimelineRequest()</code>\nwith every request it sends and the first one on the page is the one everything\nelse yields to, while <code>afterFirstTimeline()</code> runs its callback once that has\nsettled — or, on a page that sends no timeline request at all, in the first idle\nslot after the first paint. The decision is taken in that idle slot rather than\nat mount, because the sidebar mounts before the timeline below it and at mount\ntime there is nothing yet to yield to. <code>Navigation.vue</code> and the instance store\nare the callers.</p>\n<h2 id=\"the-alt-badge\">The ALT badge</h2>\n<p> <code>AltBadge.vue</code>: a badge in the corner of a thumbnail that\ncarries a description, and the description under it when it is pressed. It\nrenders two roots (the button and the text) so that both position themselves\nagainst whatever frame holds them, which therefore has to be\n<code>position: relative</code> — <code>.photo</code> in <code>GalleryMedia.vue</code>, <code>.attachment-frame</code> in\n<code>PostAttachment.vue</code>. It was <code>GalleryMedia</code>&#39;s own markup and so appeared on the\nmedia-first mosaic only; the same picture in an ordinary two-up card had its\ndescription in an <code>alt</code> attribute and nowhere else.</p>\n<h2 id=\"the-foot-of-a-card\">The foot of a card</h2>\n<p> is one row: the reactions somebody left at the near end, the counts and their controls at the far one, wrapping to a second line only when a post has collected enough reactions to need it. It was two rows while the second was revealed by the pointer and had to live in the card&#39;s bottom padding, which cost every card in the timeline the height of both.</p>\n<h2 id=\"the-action-row\">The action row</h2>\n<p> How many replies, boosts and likes a post has is a fact <em>about the post</em>, so it is always drawn — as type: no button, no border, no surface, the glyphs dimmed to a hairline and the whole row out of the tab order&#39;s way until it is wanted. What arrives on hover (and on <code>:focus-within</code>, which is the entire keyboard path) is the <strong>controls</strong>: a pill fades in <em>behind</em> the row at the size the row already occupies, the glyphs come up to full, and the overflow menu appears. <strong>Nothing moves</strong> — no track widens, no digit shifts, so a pointer is never chasing a button that is still travelling, and a reader scanning a timeline can see which posts landed without pointing at each one in turn. The surface is a <code>::before</code> rather than the row&#39;s own background, border and shadow, so the whole thing arrives as one <code>opacity</code> — one compositor property on a page that can be showing a hundred of these — and it leaves in 100ms flat, because a pointer crossing four cards on its way somewhere else must not leave four pills fading behind it. The one thing lit at rest is a like or a boost this reader has already given (<code>[aria-pressed=&quot;true&quot;]</code>), which is state rather than chrome; in a timeline list on a pointer device that state moves to the header&#39;s <code>.post-given</code> mark instead, so the row keeps no footer of its own. Touch gets none of it: the <code>@media (hover: none)</code> block turns the row back into a row with everything visible, since no pointer will ever arrive to reveal anything.</p>\n<h2 id=\"sound-and-touch\">Sound and touch</h2>\n<p> <code>src/services/senses.js</code> is the one place that makes a\nsound or vibrates: <code>play(moment)</code>, <code>buzz(moment)</code>, and <code>feel(moment)</code> for both,\nover a fixed list of moments (<code>like</code>, <code>boost</code>, <code>react</code>, <code>post</code>, <code>follow</code>, <code>dm</code>,\n<code>heart</code>, <code>roll</code>). The sounds are synthesised with the Web Audio API — a few\noscillators and an envelope each, a band-passed noise sweep for <code>post</code> — so\nnothing is downloaded or decoded, and one <code>AudioContext</code> is made on the first\npress, which is the only moment a browser lets one start. The two switches are\nper device and per account in <code>localStorage</code> (<code>userKey()</code>), not on the server:\nsound is off until turned on, vibration on unless turned off (the app vibrated\non a like before the switch existed), and <code>buzz()</code> also answers\n<code>prefers-reduced-motion</code>. The DM chime rides on\n<code>fetchUnreadDirectMessages()</code>: it sounds when the count rises, never for the\nfirst count a page reads. <code>SensesSettings.vue</code> is the Settings section.</p>\n<h2 id=\"shorts-kept-and-24-hour\">Shorts, kept and 24-hour</h2>\n<p> Home carries the <strong>Shorts bar</strong> above the feed:\nthe viewer&#39;s own tile (<em>Your shorts</em>, with a <strong>+</strong>), then the people they follow\nwho have a 24-hour short up, unseen first, then an <em>All shorts</em> tile that opens\n<code>/shorts</code>. The bar and the 24-hour part of the stack are drawn from <code>/api/v1/stories/carousel</code>. The Shorts\nstack (<code>VideoShorts.vue</code>) puts the viewer&#39;s followees&#39; active 24-hour shorts\nfirst — grouped per person, unseen first, each marked <em>24h</em> with the hours it\nhas left — and then the kept shorts: the timeline of the chosen scope asked\nwith <code>only_short</code> (store type <code>shorts</code>), and For you asked with\n<code>only_short=true</code>, which <code>InterestFeedService</code> keeps as a ranking of its own\n(<code>shorts</code>, on <code>limitToShort()</code>, topped up with trending shorts). So the stack\nholds exactly what the server counts as a short — a single video of at most\nthree minutes, upright or square (<code>Stream::shortKindOf()</code>) — and the Videos\ngrid keeps every video; an empty stack says <em>No shorts here yet</em> and what a\nshort is. One viewer plays both kinds: pictures and text cards advance by\nthemselves after their hold time, seeing a 24-hour short calls the story seen\nendpoint, anybody who can see one can react or reply, and its owner sees <em>Who\nhas seen it</em>, the reactions and replies, and can delete it. The stack, the\nshort composer and the day panel draw over video, black ground and white\nwords whatever the theme: their colours are the <code>--social-on-dark-*</code> custom\nproperties <code>App.vue</code> defines once on the root (the switch wizard&#39;s network\nmarks read the same set), and each of the three carries a\n<code>@media (forced-colors: active)</code> rule that gives the controls and captions\nthe system&#39;s button, canvas and highlight colours with a border, since a\nforced-colours mode takes the scrims away and would leave the words on bare\nvideo. <code>tests/js/onDarkPalette.test.js</code> pins both.</p>\n<p>The Shorts page uses the app&#39;s regular page header for its title, scope picker\nand primary <strong>New short</strong> action. The player frame reads a video&#39;s decoded\ndimensions after <code>loadedmetadata</code> and fits the largest frame with that aspect\nratio into the space below the header. A 24-hour story picture supplies its\nnatural dimensions. Resizing the page or changing a video&#39;s aspect ratio keeps\nthe current slide aligned in the feed. Playback controls and post details\nremain over the video itself.</p>\n<h2 id=\"videos-with-sound\">Videos with sound</h2>\n<p> <code>src/composables/useSoundAutoplay.js</code> is shared by every\nplayer of Shorts, kept or 24-hour. It plays a video\nwith sound; when <code>play()</code> is rejected with <code>NotAllowedError</code> it plays it muted\nonce more and sets <code>soundHeld</code>, which draws the &quot;Tap for sound&quot; hint. <code>muted</code>\nis the reader&#39;s choice and <code>soundHeld</code> only the browser&#39;s refusal for the video\nplaying now, so the next video is asked with sound again. The choice is kept in\n<code>sessionStorage</code> (<code>userKey(&#39;social.videoMuted&#39;)</code>); without one, the\nper-device <strong>Start videos with sound</strong> switch (<code>videoSoundEnabled()</code> in\n<code>senses.js</code>, on by default) decides. WebKit allows sound per element, only once\na gesture has allowed that element, and a scroll is not a gesture. So Shorts\nhas <strong>one</strong> <code>&lt;video&gt;</code> that sits absolutely over the slide on screen\n(<code>--at: playing</code>) and swaps its <code>src</code>, while the other slides show their\n<code>preview_url</code> as an <code>&lt;img&gt;</code>. A run of one person&#39;s 24-hour shorts likewise\nkeeps one <code>&lt;video&gt;</code>, behind <code>v-show</code>, for every video in it instead of one\nkeyed per short, and starts it itself instead of through <code>autoplay</code>.</p>\n<h2 id=\"video-recommendations-signals\">Video recommendations signals</h2>\n<p> <code>src/services/videoPlayback.js</code> measures\nthe union of the player&#39;s <code>played</code> ranges, so overlapping ranges and seeks do\nnot inflate watch time. Shorts and video timelines share this helper and send\nonly the aggregate watched fraction through the consented recommendation\nsignal; they do not send a playback history. A bounded forward-time fallback\ncovers players that have not exposed played ranges yet.</p>\n<h2 id=\"words-and-stickers-drawn-to-a-picture\">Words and stickers drawn to a picture</h2>\n<p> <code>src/utils/textCard.js</code> draws a text\ncard (a 24-hour short at 1080×1920, a post at 1080×1080) and bakes stickers into a\npicture, on a canvas, and hands back a <code>File</code> that goes up through the ordinary\n<code>/api/v1/media</code> like any attachment. So nothing new federates: a Mastodon or\nPixelfed reader gets a picture. The words travel as the picture&#39;s description\n(and, for a card post, in the post itself). <code>wrapLines()</code> and <code>fitText()</code> are\nthe layout, kept pure for the tests; the drawing returns <code>null</code>, or the original\nfile for stickers, where a browser cannot draw, and the caller says so rather\nthan posting something other than what was on screen.</p>\n<h2 id=\"picture-filters-and-pictures-too-large-to-send\">Picture filters, and pictures too large to send</h2>\n<p> <code>src/utils/imageFilters.js</code>\nholds each filter as a list of <code>[function, amount]</code> steps (<code>grayscale</code>, <code>sepia</code>,\n<code>saturate</code>, <code>hue-rotate</code>, <code>brightness</code>, <code>contrast</code>). The preview is the CSS built\nfrom those steps on an <code>&lt;img&gt;</code>; <code>prepareImage()</code> bakes the same steps in on a\ncanvas. Where the 2D canvas really applies <code>filter</code> it is handed the same CSS.\nThat is found out by drawing a red pixel through <code>grayscale(1)</code> and reading it\nback, once per page, because WebKit has the property and ignores it. Elsewhere\nthe steps are worked out per pixel: the Filter Effects spec&#39;s own matrices and\nlinear transfer functions, in sRGB 0..1, clamped after each step, alpha left\nalone, a band of rows at a time. Before any of that the picture is decoded with\n<code>imageOrientation: &#39;from-image&#39;</code> (a canvas copy carries no EXIF) and drawn at a\nlongest edge of at most 4096 px, because iOS will not make a canvas over 16.7 M\npixels. With no filter, a picture within 4096 px and the instance&#39;s\n<code>image_size_limit</code> is uploaded exactly as it was chosen. A larger one is drawn\nat 4096 px, then smaller a step at a time while the encoded copy is still over\nthe limit. PNG stays PNG, and GIF and WebP are never drawn, since a canvas would\nkeep one frame of an animation. <code>useComposerAttachments</code> refuses a file that is\nnot a video and is still over the limit before uploading it, which is the same\ncheck the server would make after the whole upload. The server&#39;s own\n<code>image_max_edge</code> resize still applies afterwards. Choosing a filter uploads\nnothing. <code>bakeFilters()</code> runs as Post is pressed, before the media ids are read:\neach filtered picture is uploaded once, its description and focal point are\nwritten to the new upload, and that upload takes the first one&#39;s place in the\npost. The first upload is kept, so taking the filter off again after a post that\nfailed posts it again. A copy that will not upload holds the post back rather\nthan sending the picture unfiltered. The first upload of a filtered picture is\nleft on the server unattached.</p>\n<h2 id=\"image-metadata\">Image metadata</h2>\n<p> <code>ImageMetadataService</code> strips camera EXIF, GPS coordinates,\nXMP, IPTC, comments and timestamps from stored JPEG, PNG and WebP copies. It\nreads the declared IPTC <code>DigitalSourceType</code> first and stores only whether the\nimage was marked as AI-generated or AI-composite; the client receives that as\n<code>ai_generated</code>. The viewer shows the supplied description, original dimensions\nand this retained AI label. It does not expose discarded camera metadata.</p>\n<h2 id=\"the-games\">The games</h2>\n<p> <code>src/utils/composerCommands.js</code> resolves <code>/dice [n]</code>, <code>/roll</code>,\n<code>/flip</code> and <code>/pick a, b</code> in <code>Composer::createPost()</code> before anything is sent, so\nthe result is plain text in the post and cannot be re-rolled. A command is one\nonly at the start of a line or after a space (a URL containing <code>/dice</code> is left\nalone), and only <code>/pick</code> runs to the end of its line. The tumble the writer sees\nis <code>tumble()</code> on a timer; the result was decided before it started.</p>\n<p><strong>Arrivals.</strong> <code>timelineStore.markArrived(id)</code> names the post this reader has just\npublished for 2.4 seconds; <code>TimelinePost</code> plays <code>post-arrive</code> and a ring in the\nauthor&#39;s hue while it matches, so a reload afterwards does not replay it.</p>\n<h2 id=\"the-constellation\">The constellation</h2>\n<p> <code>src/utils/constellation.js</code> is a small force layout in a\nunit square — repulsion softened so two nodes on one spot part gently, springs\nalong the ties, a pull to the middle, a speed cap, and a node that meets an edge\nstops there so the whole thing comes to rest. <code>FollowConstellation.vue</code> draws it\n(an async chunk, <code>constellation</code>, so the Discover page does not carry it until\n<strong>Constellation</strong> is pressed) with a star per suggestion as a real button whose\nlabel says who and why; <code>prefers-reduced-motion</code> gets <code>settle()</code> at once instead\nof the animation.</p>\n<h2 id=\"phone-layout\">Phone layout</h2>\n<p> One breakpoint, 600px, stated twice on purpose: as <code>PHONE_WIDTH</code> in <code>src/services/phone.js</code> (a shared <code>matchMedia</code> query with <code>isPhone()</code> and <code>onPhoneChange()</code>) and as the <code>@media (max-width: 600px)</code> rule in the stylesheets that lay themselves out differently on a phone — <code>TimelineEntry.vue</code> (the avatar column goes; the face, 36px, sits inside the card over the corner <code>.post-header</code> leaves for it, which is why <code>TimelineAvatar</code> takes a <code>size</code>), <code>TimelinePost.vue</code> (less padding), <code>TimelineSinglePost.vue</code> (the 64px the fine print and the spine kept for the avatar column), and <code>Composer.vue</code> (the toolbar wraps, the visibility menu is icon-only, Post keeps the end of its row). Nextcloud&#39;s own mobile breakpoint, 1024px, is where the sidebar collapses; the only rule at that width is <code>Timeline.vue</code>&#39;s, which starts the page&#39;s first element below the sidebar toggle. A tablet in portrait is between the two and keeps the avatar column.</p>\n<h2 id=\"composer-vue-2\">Composer.vue</h2>\n<p> carries a full <code>tributeOptions</code> config for <code>@</code> account and <code>#</code> hashtag completion. <code>tributejs</code> is a plain DOM library rather than a component: it is attached to the contenteditable in <code>mounted()</code> and detached in <code>unmounted()</code>, and it appends its menu to the body, which the unscoped <code>.tribute-container</code> rule at the end of the file styles. The account collection searches <code>/api/v1/global/accounts/search</code> and the hashtag collection <code>/api/v1/global/tags/search</code>, both debounced. The composer&#39;s HTML-to-text conversion inserts one newline at each block boundary, including before a block that follows an unwrapped text node; browser contenteditables commonly encode the first Enter in that mixed form, so missing the leading separator concatenates the first two lines in a new post. The shared <code>htmlToPlainText()</code> applies the same rule when editing/redrafting and when presenting portfolio captions. The emoji picker is a separate <code>NcEmojiPicker</code>; it is loaded on first use and portals to <code>#content</code>, outside the composer toolbar and reaction modal&#39;s clipping/stacking containers while retaining Nextcloud theme variables inherited from the app root. The reaction picker shares that portal so the popover does not participate in its centered flex panel&#39;s sizing or sit beneath its backdrop. Portfolio captions are reduced to plain text by <code>htmlToPlainText()</code> and use <code>white-space: pre-line</code> so paragraph boundaries remain visible without rendering untrusted HTML.</p>\n<p>The inline composer&#39;s close control remains available when its secondary\ncontrols are grouped under More options. Its avatar stays hidden in that\nlayout; a dialog uses its own header and close control.</p>\n<h2 id=\"the-settings-page-and-what-is-on-it\">The Settings page, and what is on it</h2>\n<p> <code>src/views/Settings.vue</code> describes\nevery section once (<code>{ id, group, icon, component, title, lede }</code>) and sorts them\ninto six groups: <strong>Profile and privacy</strong> (<code>#account</code>, <code>#featured-tags</code>,\n<code>#portfolio</code>), <strong>Reading</strong> (<code>#interests</code>, <code>#lists</code>, <code>#bluesky-feeds</code> where\nBluesky is on — <code>BlueskyFeedsSettings.vue</code>, the Bluesky custom feeds and lists\nkept, read as timelines at <code>/timeline/bluesky/&lt;DID&gt;/&lt;feed|list&gt;/&lt;key&gt;</code> —, <code>#sensitive</code>, <code>#counts</code>,\n<code>#recap</code>, <code>#senses</code>), <strong>Notifications</strong> (<code>#notifications</code> for when,\n<code>#notification-policy</code> for who), <strong>Your posts</strong> (<code>#scheduled</code>, <code>#review</code>,\n<code>#archive</code>, <code>#files-comments</code>), <strong>Apps and account</strong> (<code>#apps</code>, <code>#bluesky</code>\nwhere the server gives every account a Bluesky identity — <code>BlueskySettings.vue</code>,\nthe handle, the DID, your own domain as the handle, the pause switch, the recovery phrase, the app\npasswords Bluesky apps sign in with and the apps signed in through OAuth —, <code>#invites</code>, <code>#storage</code>,\n<code>#delete</code>, last because it cannot be undone) and <strong>Help</strong>\n(<code>#introduction</code>, <code>#shortcuts</code>). One group is drawn at a time. The rail lists the\ngroups and, under the open one, its sections; on a narrow screen the groups are a\nrow of tabs. A group&#39;s link is <code>#</code> plus its first section&#39;s id, so every address\nis a section address and the links other pages hold keep working: a hash opens\nthe group its section is in, then scrolls to it (retried in <code>updated()</code>, because\nthe sections arrive in an async <code>settings</code> chunk). <strong>Find a setting</strong> matches\nevery typed word, folded to lower case without accents, against each section&#39;s\ntitle, lede and group, and draws the matches from all groups at once with their\ngroup named above each. The rail marks the last section whose heading has passed\nthe top (<code>services/sectionRail.js</code>), and the first one before any has: keeping\nthe previous mark left a section far down the page marked at the very top.\n<code>#migration</code> is sent on to the Migration page.</p>\n<h2 id=\"accountsettings-vue\">AccountSettings.vue</h2>\n<p> is <code>PATCH /api/v1/accounts/update_credentials</code> for\n<code>locked</code>, <code>discoverable</code>, <code>indexable</code>, <code>bot</code> and <code>source[privacy]</code>, saved as each\none changes, like every other setting on the page. A change made while a save is\non its way goes once that save answers, and the store&#39;s answer is not copied into\nthe form while a save is pending, since it predates the later change. A refused\nsave puts the form back to what the server holds. The display name is shown, not\nedited: it belongs to the Nextcloud account. How sensitive media is shown is a\nreading preference, so it is <code>SensitiveMediaSettings.vue</code> under Reading. The form\nsends <strong>only the fields that changed</strong>, which is not an optimisation: the route writes only what it is given, and a form that posted the\nwhole of itself back would re-save a display name into a backend that owns it\n(LDAP, SAML) and be refused for a switch it never meant to touch. The bio, the\nbanner and the metadata fields stay in the profile&#39;s own editor, because they are\nwhat a visitor reads and are edited where they are seen.</p>\n<h2 id=\"the-default-audience\">The default audience</h2>\n<p> <code>source.privacy</code> lives on <code>verify_credentials</code> and\nnowhere else — the account the initial state seeds the store with is the plain\nAccount entity and has no <code>source</code> — so the account store keeps the\nCredentialAccount separately as <code>credentials</code> and exposes\n<code>defaultPostVisibility</code>, which translates the wire&#39;s <code>private</code> into the\ncomposer&#39;s <code>followers</code> and answers <code>&#39;&#39;</code> for anything it does not know. The\ncomposer&#39;s chain is: what the caller passed, the post being replied to, the\naccount&#39;s default, the last visibility the reader used, and failing all of those\n<code>followers</code>. Because <code>verify_credentials</code> can land after a composer is already on\nscreen — the timeline draws one as the page opens — a watcher takes the default\nwhen it arrives, unless the audience has been settled by a caller, a reply or the\nreader.</p>\n<h2 id=\"listssettings-vue\">ListsSettings.vue</h2>\n<p> is the whole of <code>ListController</code> in one section: create,\nrename, delete with a confirmation, and members added through the same\n<code>/api/v1/global/accounts/search</code> the composer&#39;s mention autocomplete uses.\nLists carrying <code>nextcloud_group</code> are shown — a reader looks here when they wonder\nwho is in &quot;Design&quot; — with their members and without any of the three controls,\nbecause the group decides all of it and the server answers 422 to anybody who\ntries. The sidebar draws the lists from a fetch of its own, once per page, so\nevery change here is announced on the event bus as <code>LISTS_CHANGED</code> (exported by\n<code>src/services/eventBus.js</code>, because two unrelated components have to agree on the\nname) and <code>Navigation.vue</code> asks again.</p>\n<h2 id=\"muting-asks-two-questions\">Muting asks two questions</h2>\n<p> <code>MuteDialog.vue</code> — whether the notifications go\nquiet too, and for how long: indefinitely, an hour, a day, seven days or thirty —\nis opened from a profile and from the overflow menu of any post its author did\nnot write, in an <code>account-dialogs</code> chunk shared with <code>ListMembershipDialog</code>. It\nmutes itself rather than handing the answers back, because both callers would do\nexactly the same with them. Blocking is a plain confirmation in the same two\nplaces. A relationship reports <code>mute_expires_at</code> while a timed mute is running,\nwhich is what the profile writes out under the name.</p>\n<h2 id=\"the-statistics-page\">The Statistics page</h2>\n<p> <code>src/views/Statistics.vue</code> behind the account menu, and\n<code>StatisticsService</code> behind that. Everything is counted from this instance&#39;s own\nrows when the page is opened — nothing stored, nothing precomputed by a cron —\nwhich is what keeps it from showing a total a deletion has already made false,\nand the walk is bounded at <code>MAX_POSTS</code> with the answer saying how far it got.\nThe engagement figures come from each post&#39;s <code>details</code>, which is a JSON blob:\nthat is why the sum is a walk in PHP rather than a <code>SUM()</code>, because the three\ndatabases this app supports do not agree on how to reach inside one. A boost the\naccount made is counted as something it did and then left out of everything\nelse, because the likes on a boosted post belong to whoever wrote it. The bar\ncharts are CSS — a chart library would cost more than the page it draws — and\nevery bar carries its own figure in a <code>title</code>, because a bar whose only value is\nits height says nothing to a reader who cannot see it.</p>\n<p>What the page reports beyond the totals is what somebody running an account\nprofessionally asks of it: engagement per post and per follower (the second is\nthe industry&#39;s &quot;engagement rate&quot;, against followers because this app has no\nimpressions to divide by and says so rather than inventing a denominator), the\nmedian beside the mean because one viral post makes a mean meaningless, the\nshare of posts that got no answer at all, which kind of post averages best\n(media, hashtags, originals against replies, each visibility), which weekday and\nhour do, which hashtags are worth using as opposed to merely used, and where the\naudience is — the servers the followers are on, which is what a Fediverse account\nhas instead of a geography — and where the engagement comes from, by the same\nservers. A server is the host of an account&#39;s id unless the account&#39;s network\nknows better: <code>Service\\Statistics\\StatisticsSource</code> is what a network adds to\nthe page, and <code>Atproto\\Reader\\BlueskyStatistics</code> names a Bluesky account&#39;s PDS\n(Bluesky&#39;s own hosts as one) and counts the posts that also went out on Bluesky\nfrom the author&#39;s repository, which no instance path records. Two sample-size rules keep those from being noise:\nan hour is not named until three posts fall in it, and a hashtag&#39;s average is\nnot reported until it has been used twice.</p>\n<h2 id=\"and-the-way-back-out\">And the way back out</h2>\n<p> A post opened from a timeline is somewhere the reader\nwent <em>into</em>, so <code>TimelineSinglePost</code> carries a Back button above the thread. It\nuses <code>history.state.back</code> — which the router writes whenever it navigates inside\nthe app — to tell a post opened from a timeline from one opened from a link\nsomebody sent: the first goes back, the second goes to the home timeline, because\na button inside the app should not be the thing that leaves it.</p>\n<h2 id=\"which-is-only-a-way-back-if-the-timeline-is-still-there\">Which is only a way back if the timeline is still there</h2>\n<p> The store holds one\nlist at a time, and <code>changeTimelineType()</code> used to clear it on every call — which\nincludes the call <code>Timeline.vue</code> makes in <code>beforeMount()</code> when the view is\nmounted again on the way back out of a post. A reader four pages into a timeline\ncame back to fifteen posts. <code>switchTimeline()</code> compares the list being asked for\nwith the one being held (<code>getTimelineIdentity</code>: type, account and params, the\nsame value that tells a page in flight it is no longer wanted) and clears only\nwhen they genuinely differ, and it keeps the last <strong>four</strong> lists aside —\n<code>remembered</code> — so that coming back to one of them finds it whole. Four and not a\ncache of all of them: keeping every timeline ever opened is the leak\n<code>resetTimeline()</code> was written to stop. What is held aside is the <strong>ids</strong> only.\nThe statuses themselves live in the one <code>statuses</code> map every list reads, so a\nlike, an edit or a delete done in one list is what every other list shows on\nreturn — a copy of the index per list showed the reader the post as it was when\nthey left it. Coming back reads the ids against that map and drops the ones\nthat have gone, and each switch prunes the map to what the kept lists still\nname, the boosted post and the notification&#39;s post included; a status taken\noff one list without being deleted — unliked out of the likes, unbookmarked out\nof the bookmarks, hidden from For you — stays in it for the lists that still\nshow it. A restored list also sets <code>restored</code>, which is how <code>TimelineList</code>\nknows not to ask for another page on top of the ones it already has.</p>\n<p>Putting the reader back where they were then needs the page to exist first. Vue\nRouter applies the offset Back remembers as soon as the route has changed, and at\nthat moment the timeline is one screen tall, so the browser clamped a four-page\noffset to the bottom of what was there. <code>scrollBehavior</code> returns a promise\ninstead: <code>TimelineList</code> emits <code>timeline:rendered</code> on the event bus once its\nentries are on the page, and the router waits for that, or for two seconds,\nwhichever comes first — a view that never says anything still scrolls. The offset restored is the content column&#39;s, not the window&#39;s: a Nextcloud app is given a fixed viewport and the column scrolls inside it, so the position Vue Router remembers is always zero and applying it moved nothing. A <code>beforeEach</code> guard records <code>#app-content-vue</code>&#39;s <code>scrollTop</code> for the view being left, at most ten views deep.</p>\n<p>A long column is laid out a screen at a time: <code>.timeline-entry</code> has\n<code>content-visibility: auto</code> with <code>contain-intrinsic-size: auto 320px</code>, so a card\noff screen keeps a placeholder of about its height until it scrolls near, and\nits real size once it has been drawn. The sentinel below the list and the\nrestored offset above are unaffected — the placeholders have boxes — and the\nrestored offset lands where it was recorded.</p>\n<p>The &quot;N new posts&quot; pill that polling puts up is sticky, and so is the box the\nreader writes in: same stacking context, and the composer both taller and above.\nThe pill only appears once the reader is a screen or so down, which is exactly\nwhen the composer is stuck to the top — so it was painted behind it every time.\n<code>TimelineList</code> measures the composer, which is a sibling above it rather than a\nparent, and sets the pill&#39;s <code>top</code> below it; measured and not assumed, because a\ncontent warning, a row of attachments or a poll all make the composer taller.\nThe watching lasts only as long as the pill is on screen.</p>\n<h2 id=\"one-card-and-a-line-only-when-there-is-a-conversation\">One card, and a line only when there is a conversation</h2>\n<p> The post a page is\nabout used to be drawn inside two boxes: <code>TimelinePost</code>&#39;s own card, and around\nit a second card in <code>TimelineSinglePost</code> — white ground, padding, rounded\ncorners, a shadow, and a border in the accent colour on top of that. What marks\nthe post the page is about is that it is the one at the top with the thread\nhanging off it, so <code>.main-post</code> is spacing and stacking now and the card inside\ndoes the drawing. The 24px it is indented by is the 16 of margin plus the 8 of\npadding the lists above and below take, which is what puts every avatar in the\nconversation on one line — the line the spine runs down. And the spine itself\nis drawn only when <code>hasThread</code> holds, meaning there is a parent or a reply:\nbeside a post with neither, it was a line from nothing to nothing.</p>\n<p>Under it, &quot;No replies yet&quot; is a small drawing over a line of muted text rather\nthan a heading. <code>EmptyContent</code> takes either a <code>scene</code> or an <code>illustration</code> name,\nnever both. Both are drawn in markup, not fetched as files. A <code>scene</code> is one of\nthe eight full-size drawings in <code>illustrations/AlohaScene.vue</code>: <code>tide</code>,\n<code>islands</code>, <code>hammock</code>, <code>plumeria</code>, <code>bottle</code>, <code>board</code>, <code>wave</code> and <code>tracks</code>. Each\nsits in the same round window, painted in a sunset palette (coral, plumeria\ngold, lagoon teal, hibiscus). Every fill is that palette mixed in CSS with\n<code>--color-main-background</code>, so a dark theme gets a dimmed sunset without a\nfilter. The sky is the exception: coral mixed into a dark page turns brown, so\nunder a dark theme the sky is dusk blue instead. The direct-messages page has\nits own empty pane rather than a timeline, and shows the <code>bottle</code> scene there. An <code>illustration</code> is one of the small <code>currentColor</code> drawings\n(<code>NoReplies</code> a shell, <code>QuietTimeline</code> a drop on still water, <code>NobodyYet</code> an\nempty outrigger canoe, <code>NoMessages</code> a message in a bottle). A state with a small drawing keeps the compact layout;\nthe 60vh of height is room for the scenes only. NcEmptyContent pins any SVG in\nits icon slot to 64px with <code>!important</code>, so <code>EmptyContent</code> overrides that for the\nscene. The stock undraw pictures these replaced were licensed to this app by\npermission and are gone; anything new has to be ours.</p>\n<p><strong>The Aloha look.</strong> The same palette, used sparingly, in four more places:</p>\n<h2 id=\"a-like-blooms\">A like blooms</h2>\n<p> <code>TimelinePost</code> opens five plumeria petals (<code>PETALS</code>, a\nfifth of a turn apart) from the heart. They are gold at the base and the\nauthor&#39;s <code>--account-hue</code> at the tip, and they drift and fall away within\n0.9s. The <code>celebrate</code> flag is held for 1s so they finish before they unmount.\nPressing the card opens the post unless the press was meant for a control;\n<code>pressedControl()</code> reads that from <code>event.composedPath()</code>, because the heart&#39;s\nicon is swapped for the filled one while the click is still bubbling, and the\ndetached icon&#39;s <code>closest(&#39;button&#39;)</code> finds nothing.</p>\n<h2 id=\"loading-rolls-in\">Loading rolls in</h2>\n<p> At the foot of a timeline, the next page&#39;s wait is\n<code>WaveLoading</code>: one wavelength-wide line slid by exactly one wavelength, so it\nloops without a jump. The first page keeps <code>TimelineSkeleton</code>.</p>\n<h2 id=\"the-composer-says-aloha\">The composer says Aloha</h2>\n<p> A post of its own is asked for as &quot;Aloha, {name}.\nWhat’s new?&quot;, with the first word of the display name (or the user id). A\nreply, a quote, a caption, or a user with no name keep their plain prompts.</p>\n<h2 id=\"federation-is-islands\">Federation is islands</h2>\n<p> Discover&#39;s People tab opens with\n<code>FederationIslands</code>. It reads the reader&#39;s following list (pages of 50, at\nmost six). <code>services/islands.js</code> groups it by server, keeps the eight\nbusiest, and places them around the home island, sized by the square root of\neach count. A dashed route runs from each island home, its dashes moving\ntowards home. The summary sentence is the map&#39;s <code>aria-label</code> too. The\n<code>islands</code> scene and one sentence carry the same picture into the first\nstep of <code>FirstRun</code> and onto the empty Global timeline.</p>\n<h2 id=\"a-link-to-a-post-opened-cold\">A link to a post, opened cold</h2>\n<p> <code>/@{username}</code> and <code>/@{username}/{token}</code> are\nActivityPub addresses first, so <code>ActivityPubController</code> owns them; a request\nwhose <code>Accept</code> header asks for HTML is handed to <code>SocialPubController</code>, which is\nthe browser half of those two routes and nothing else — it has no routes of its\nown. Who is asking decides what they get. A reader with a session gets the app,\nthe very page <code>NavigationController::navigate()</code> serves at <code>/</code>, because the\nclient-side router has a view for each of these paths. This used to serve the\npublic page to everybody, so a link to a post or a profile landed a logged-in\nreader on a page with a blue header, a &quot;Get your own free account&quot; banner and a\nFollow button that started the remote-follow flow for an account they could have\nfollowed with one click. An ActivityPub request is untouched by any of it.</p>\n<p>For an anonymous reader, both the profile shell and the resolved single-post\nshell are <code>PublicTemplateResponse</code>s. A profile whose well-formed <code>user@host</code>\nhandle is not cached here still receives that shell; the browser resolves the\naccount through <code>GET /api/v1/global/account/info</code>, whose anonymous rate limit\nbounds remote lookups. The HTML request itself remains cache-only and never\nWebFingers an arbitrary name. The profile view uses the local account endpoint\nfor a bare local username and the global resolver for a federated handle. Both\naccount-info routes are read-only public GETs and carry <code>NoCSRFRequired</code>, so a\nsigned-out browser can load the profile without a session token; the remote\nresolver remains protected by its anonymous rate limit. This\ndetail matters after the post has been resolved: an ordinary <code>TemplateResponse</code>\nis private by default, so Nextcloud redirects the visitor to <code>/login</code> during\nthe document request and throws away the already-rendered public status. The\npublic single-post shell also receives the safe <code>serverData</code> state and\nserialized status before Vue starts; the guest timeline does not need a session\nto fetch the surrounding public context. Authenticated readers still get the\nnormal <code>navigate()</code> shell.</p>\n<p>The app writes its own links to a post as <code>/@acct/&lt;nid&gt;</code> — the numeric id its\nclient API uses — while the address a post is published under ends in a\ndifferent token, and the post used to be looked up by that address alone. So a\nlink opened in a new tab, a reload, or a link somebody sent found nothing,\nprovided no <code>item</code>, and the page said the post did not exist.\n<code>SocialPubController::resolvePost()</code> falls back to <code>getStreamByNid()</code> for a\nnumeric token, on the browser branch only: an ActivityPub request asks for a\npost by its address, and answering a second identifier there would invent a\nsecond canonical id for every post. The fallback goes through the same viewer\nfilter every other read does, so it shows what the reader may see and nothing\nmore. The other end of that is in <code>TimelineSinglePost</code>: the post the server\nrendered into the page carries its <em>client</em> id, and the view goes on that rather\nthan on what is in the address, so <code>/context</code> and the store are asked in the one\nidentifier they speak. The initial-state post is only used when the address\nnames it — by that id, or by the last segment of its <code>uri</code> — since the page is\nrendered once and the reader goes on reading, and a second post used to be\nanswered with the first.</p>\n<p>An address that names nothing is a <strong>404</strong> rather than a 500. Looking an account\nup used to try to <em>fetch</em> it, and a bare username is not an account anybody can\nresolve, so the exception saying so came out as a server error; the lookup is of\nwhat this instance already has now (<code>getFromAccount($username, false)</code>) — an\nanonymous page request is no reason to webfinger whatever is in the address. A\nvisitor gets <code>templates/notfound.php</code>, a small guest page shaped like the\nserver&#39;s own; a reader with a session gets the app with a 404 status, and its\nviews say &quot;User not found&quot; and &quot;This post is not available&quot; once they have\nasked.</p>\n<p>The portfolio URL is a separate browser route under <code>/@{username}/portfolio</code>.\nIt uses the same public page shell for anonymous readers and the client router\nloads the portfolio through the public <code>portfolio/{handle}</code> API. The published\nportfolio API resolves posts as the anonymous internet, so followers-only posts\ncannot leak onto a public page. The route is covered alongside the public actor,\nfollowers, and following pages. Captions are plain text and <code>white-space: pre-line</code> preserves paragraph breaks without interpreting user HTML.\nThe post route in <code>ActivityPubController</code> also matches any one-segment token\nunder <code>/@{username}/…</code>; because controllers contribute attribute routes in\nfilesystem order, it explicitly forwards the reserved <code>portfolio</code> token to\n<code>SocialPubController::portfolio()</code> before attempting post resolution. This\nkeeps the public portfolio working on both cold anonymous loads and logged-in\nnavigation regardless of route registration order.</p>\n<p>On the client, <code>TimelineSinglePost</code> asks for the post itself when nothing has\nloaded it — <code>timelineStore.fetchStatus()</code>, which is <code>GET /api/v1/statuses/{id}</code>.\n<code>/context</code> answers with what is <em>around</em> a post and never with the post, so a\npage reached from anywhere outside a timeline had nothing to draw. A tile on\nDiscover is exactly that: those posts belong to the Discover view and never\nreach the timeline store.</p>\n<p>The route parameter for <code>/context</code> is a string even when its contents are a\nnumeric status id. <code>StreamService::getContextByNid()</code> normalizes that decimal\nstring with <code>Nid::fromStorage()</code> before it reaches the query builder, whose\ninteger predicate rejects numeric strings under strict typing. Without that\nboundary conversion, the public post shell could render its initial status, but\nthe follow-up context request returned 500 and the page displayed a timeline\nload error.</p>\n<h2 id=\"the-pictures-on-discover\">The pictures on Discover</h2>\n<p> were not drawn at all, and had not been since the\ntab was added. <code>ProfileMediaGrid</code> builds each tile&#39;s route with the grid&#39;s\n<code>account</code> prop, which Discover leaves empty because the grid is everybody&#39;s —\nand <code>account</code> is a required route param, so <code>router-link</code> threw while resolving\nand took every tile with it. A tile links at the account that wrote the post it\ndraws, falling back to the grid&#39;s own account where a post carries none.</p>\n<h2 id=\"the-hashtags-on-discover\">The hashtags on Discover</h2>\n<p> <code>TrendingHashtags</code> is a ranking rather than a\nlist of names: a row carries its position, the tag, how often it was used in the\nwindow asked for, and a bar showing its share of the busiest tag on the list —\nwhich is the only comparison these numbers support, since <code>history</code> from this\nserver is a single bucket for the chosen window rather than a series (the\n<code>accounts</code> field is always <code>0</code>, so &quot;how many people&quot; is not something the page\nmay claim). The window itself is the useful part: <code>/api/v1/trends/tags</code> takes a\n<code>period</code> of <code>1h</code>, <code>12h</code>, <code>1d</code>, <code>3d</code> or <code>10d</code> and <strong>orders by that window&#39;s own\ncolumn</strong>, so choosing one re-ranks rather than relabels, and an answer that\narrives after the reader has moved to another window is dropped rather than\ndrawn. The empty state says which of the two emptinesses it is: nothing tagged\nin this stretch of time, or — over ten days — an instance where hashtags are not\nused.</p>\n<h2 id=\"beside-it-what-other-servers-say\">Beside it, what other servers say</h2>\n<p> The same tab carries a search box and, under\nthe ranking, a <em>Busy elsewhere in the fediverse</em> section; both draw <code>PeerTagRows</code>,\nbecause a tag found by searching and a tag that is busy somewhere else are the same\nrow and differ only in what put it on screen. A row names the servers — &quot;busy on\nmastodon.social, misskey.io&quot; — rather than counting them, since a named server is\ncheckable and &quot;1 server&quot; is not, and it counts only once there is no room left to\nname. Typing <strong>replaces</strong> the ranking rather than filtering it: what is on screen\notherwise is one window on one server, and narrowing that to a word answers a\nquestion nobody asked, so the box asks <code>/api/v1/directories/hashtags</code> and shows what\nthe servers said. A tag already in the ranking above is not repeated below it — the\nsame tag twice reads as a second opinion rather than as the answer to a different\nquestion. A failure out there is quiet: the ranking is this instance&#39;s own and is\nalready drawn, and an error card about strangers&#39; servers on a working page would be\nthis app apologising for somebody else.</p>\n<p>Following is answered once for the page. <code>HashtagFollowButton</code> looks a tag up\nfor itself when nobody has told it, which is right for the one button on a\nhashtag timeline and wrong for twenty on a ranking: it takes an optional\n<code>known</code> list and reads its state from that instead, so the page costs one\n<code>/api/v1/followed_tags</code> call rather than twenty lookups before anything can be\ndrawn. <code>null</code> means nobody has said, which is not the same as &quot;not followed&quot; —\nhence a list rather than a boolean, since a <code>Boolean</code> prop cannot carry the\nthird state.</p>\n<p><strong>What else a post&#39;s own page says.</strong> Four things that belong to a post being\nread rather than to a post being scrolled past.</p>\n<h2 id=\"postreactedby\">PostReactedBy</h2>\n<p> puts the faces behind likes, boosts and quotes under the post,\nthrough <code>GET /api/v1/statuses/{nid}/reblogged_by</code>, <code>/favourited_by</code> and\n<code>/quotes</code>. ActivityPub collections and Bluesky&#39;s AppView supply actor ids or\nquoted posts; cached profiles become avatar-bearing account objects, and\nunresolved ActivityPub actors are queued for profile resolution.\n<code>X-Social-Filling</code> stays set while either the network list or those profile\npictures are still being filled, so the visible row can reload after the\nbackground work. Retries stop after eight attempts if a remote profile never\nresolves. Nothing is requested when a count is zero, unless the reader hides\ncounts, in which case the number cannot establish that the list is empty. A\ndozen faces at most, with the count saying how many there are in all, and each\nrow reloads on its own when its own count changes.</p>\n<h2 id=\"postdetails\">PostDetails</h2>\n<p> is the fine print: the full date, the audience in the words the\ncomposer uses, the language named rather than coded (<code>Intl.DisplayNames</code>, the\ncode itself when nothing can name it), when it was last edited, and — for a post\nfrom another server — a link to where it actually lives. A local post gets no\nsuch link, its own address being the page the reader is on. Mastodon&#39;s\n<code>application</code> is not among these: the entity this app builds does not carry one,\nand inventing a value would be worse than the absence.</p>\n<p>The composer sits under the post, pointed at it, rather than at the top of the\npage waiting to be summoned by a reply button. <code>Composer</code> takes <code>inReplyTo</code> for\nthis: it seeds <code>replyTo</code>, and it is a <em>default</em> rather than a fixed target — pressing reply on\nanother post in the thread retargets the box as it always did, and sending or\ndismissing that reply comes back to the anchor rather than leaving the box\npointed at nothing. The header naming who is being replied to is hidden while\nthe target is the post directly above the box, where it would be the page\nrepeating itself. There is no box at all on the public page, where there is no\naccount to send from.</p>\n<p>The anchor is the one thing that does not open the box. Everywhere else a\n<code>replyTo</code> means a reply in progress, which is why it counts as expanded; a box\nthat is under every post would then be eight controls and a text area under\nevery post. So <code>expanded</code> ignores the anchored target, the box is a line of\nplaceholder until somebody clicks into it, and it closes again once the reply\nhas been sent. Pressing reply on the post it sits under sets <code>openedByHand</code>\ndirectly — the target does not change there, so opening is the whole of what\nthat button can do.</p>\n<h2 id=\"and-it-closes-by-hand-without-losing-anything\">And it closes by hand, without losing anything</h2>\n<p> A click elsewhere collapses\nan idle composer and may do no more than that — a stray click must not take a\nhalf-written post with it — so a box with a single word in it stayed open, and\nthe only way back to a line of placeholder was to delete the word. The close\nbutton in the composer&#39;s header is the way out, and it <strong>throws nothing away</strong>:\n<code>closedByHand</code> wins over everything <code>expanded</code> would otherwise stay open for,\nthe text stays in the box, and the draft stays on disk. Opening it again — a\nclick, a reply, the compose shortcut, or the next visit to the page — puts the\nreader back where they were. A half-written post is not something to ask\nsomebody about at the moment they are trying to get it out of their way; it is\nsomething to still be there when they come back. The button is not offered where\nthere is nothing to close <em>to</em>, which is the New post dialog, whose own way out\nis the dialog&#39;s. Posting still empties the box, through one <code>clearComposer()</code>, so\na field added to the composer cannot survive a post by being missed off one of\ntwo lists.</p>\n<h2 id=\"every-panel-the-toolbar-opens-closes-from-itself\">Every panel the toolbar opens closes from itself</h2>\n<p> The poll, the content\nwarning, the preview and the place picker were opened by a button in the toolbar\nand could be shut only by finding that same button and pressing it again — a row\nfurther down, and a thing to work out rather than see. Each carries its own close\nnow, beside the schedule editor&#39;s, which has had one all along; the button in the\ntoolbar keeps working and still says which state it is in. Closing takes what\nbelongs to the panel with it, as pressing the toolbar button always did: the\npoll&#39;s options, the warning&#39;s text, the place. The place picker keeps its\nnarrower <code>Remove the place</code> as well — that one clears the choice and leaves the\nsearch open, where the close puts the panel away and leaves the post without a\nplace, which is what an unpressed pin means.</p>\n<p>The draft on disk (<code>src/services/draft.js</code>) is the same promise across a reload\nor a navigation, and it holds everything in the box: the text, the content\nwarning, the audience, the language, the reply policy, the poll, the scheduled\ntime, the place, a video&#39;s title, the card, and <strong>the team account it was being\nwritten as</strong> — which is checked against the teams once <code>loadTeams()</code> has them,\nsince a draft can outlive leaving one. The composer builds it as one computed\n<code>draft</code> and writes it whenever that changes. Attachments are kept by the id of\ntheir upload (the upload made on attaching, not a filtered copy), with the alt\ntext as typed, the focal point and the filter. They come back at once, marked\n<code>checking</code>, and Post waits while <code>restoreDraftMedia()</code> asks\n<code>GET /api/v1/media/{id}</code> about each: an upload the server no longer has (a 404)\nis taken off with one toast for all of them, and one it could not be asked about\nstays as the draft had it. A filtered picture has its bytes fetched back into a\n<code>File</code>, because the filter is baked in from the file as the post is sent; when\nthat fails the filter is dropped, so the preview shows what would be posted.\nChoosing a filter for any picture with no file in the browser — added from\nFiles, written again from a deleted post — fetches it the same way\n(<code>fetchMediaFile</code>, kept under <code>objectUrl</code> for the swatches), and Post waits for\nit; one that cannot be fetched stays unfiltered, with an error toast.</p>\n<p>The one thing a draft cannot hold is an upload that has not come back, which\nhas no id yet. That alone is what the leave guard asks about: a <code>beforeunload</code>\nlistener and a <code>router.beforeEach</code> guard the composer registers on mount and\nremoves on unmount, both silent unless <code>hasPendingUploads</code>. The router&#39;s\nquestion is <code>admin/ConfirmDialog.vue</code>, and the navigation waits on its answer.</p>\n<p>And when the thread is shorter than the post says it is, the page says so.\n<code>replies_count</code> is what the post&#39;s own instance reported plus what has arrived\nhere, so the two differ honestly: a reply from a muted or blocked account is\nfiltered out of the thread but still counted, and a remote thread is only ever\nas complete as what has reached this server. The note counts against the\n<em>direct</em> replies on screen, since that is what the number on the post counts,\nand it waits for <code>TimelineList</code> to emit <code>settled</code> — before that, every reply is\none this page has not drawn, and saying so would be counting the loading.</p>\n<p>Saying it out loud found a counter that was wrong. Deleting a reply removed its\nrow and left its parent&#39;s <code>replies</code> detail alone, so a post whose reply had been\ndeleted claimed one that no page could ever show — invisible until something\ncompared the number with the thread. Both deletes now recount:\n<code>NoteInterface::delete()</code> for a <code>Delete</code> that arrives from another server, and\n<code>StreamService::deleteLocalItem()</code> for your own post, which never passes through\nthat interface at all. The arithmetic itself is <code>StreamRequest::recountReplies()</code>\n— <code>remote_replies</code> (what the post&#39;s own instance reported, which nothing here can\nsee) plus the replies stored here, counted in the same statement — which is a recount rather than a bump, because the\ntwo things that move the number cannot both be expressed as one, and a recount\nrepairs a count that has already drifted instead of tracking one. It runs after\nthe row is gone, or it counts the reply it has just removed.</p>\n<h2 id=\"the-counters-are-columns\">The counters are columns</h2>\n<p> (<code>Version1000Date20261008000600</code>). Replies, likes,\nboosts and dislikes used to be keys of the <code>details</code> JSON, and every writer of\nthat blob — a like, a boost, a reply, a dislike, the remote-count refresh, but\nalso a quote approval or a reply approval — read the whole of it and wrote the\nwhole of it back, so two landing on one post together kept whichever wrote last.\nEach counter is now a column of <code>social_stream</code>, and <code>StreamRequest::recount()</code>\nis its one writer: <code>SET count_x = &lt;origin&#39;s half&gt; + (SELECT COUNT(*) …)</code> in a\nsingle statement, so no writer carries a number it counted earlier and the last\nstatement to run includes everything committed before it. Replies are counted\nfrom the table being updated, through a derived table (<code>SELECT c FROM (SELECT COUNT(*) AS c …)</code>), which is what MySQL needs to allow that. The origin&#39;s halves\n(<code>remote_likes</code>, <code>remote_boosts</code>, <code>remote_replies</code>) are absolute numbers written\nby <code>Counts\\CountWriter</code> and stay in <code>details</code>. <code>Stream::importFromDatabase()</code> lays\nthe columns over the <code>details</code> keys, so every reader — the client and Mastodon\nAPIs, the ActivityPub collections, statistics, the annual report — is unchanged;\na column at zero adds no key the blob did not have. The JSON keys are no longer\nwritten by the counter writers and go stale; nothing reads them past the overlay.\nThe upgrade fills the columns from the JSON in pages of <code>nid</code>.</p>\n<p>Everything else in the blob — an edit&#39;s <code>mentions</code>, the origin&#39;s halves of the\ncounts, a quote&#39;s or a reply&#39;s state, the hidden replies of a thread, the\ndetached quotes — is written by compare-and-swap rather than as a column:\n<code>StreamRequest::changeDetails()</code> reads <code>details</code>, changes only its own keys, and\nwrites the result with <code>UPDATE … WHERE details = &lt;what was read&gt;</code> (<code>IS NULL</code>\nfor none), the one form every supported database answers atomically without a\nJSON function of its own. A write that finds the blob changed in between reads\nit again and changes its keys on that, once; a second loss is logged, the\nmentions wait for the next edit and the counts for the next ask.\n<code>updateMentions()</code>, <code>CountWriter</code> and <code>updateDetails($post, ...$keys)</code> — which\nwrites the named keys as a post read earlier holds them — all write through it;\nnothing puts a whole blob it read back over what is stored.</p>\n<h2 id=\"a-post-is-a-link-to-itself\">A post is a link to itself</h2>\n<p> Pressing anywhere on a post in a timeline opens\nthe post with its replies — the card, its picture, its video. <code>TimelinePost</code>\nworks out <code>postRoute</code>, which is <code>null</code> for exactly one post: the one whose page\nthe reader is already on (<code>$route.params.id</code>). A reply on that page is another\npost and links to its own page like any other. <code>onPostClick</code> is what keeps the\ncard from swallowing everything else: a link, a button, a control, a modified\nclick asking for a tab, or a press that ended a text selection all keep their\nmeaning. Below the card, <code>PostAttachment</code> takes the same route as a <code>to</code> prop —\nwhere it is set, a press on the media routes; where it is <code>null</code>, it opens the\nviewer — and <code>MediaAttachment</code> takes an <code>interactive</code> flag that decides whether\na video gets <code>controls</code> at all. A player in a timeline would put a play button\nin the way of the post and swallow the press meant to open it; the poster is\nwhat the reader is choosing from. On the post&#39;s own page the media is the\nsubject again: the picture opens full size, the video plays.</p>\n<h2 id=\"an-avatar-is-a-link\">An avatar is a link</h2>\n<p> <code>ActorAvatar</code> and <code>TimelineAvatar</code> wrap the face in a\nlink to the account, so the most obvious thing on screen to click does the\nobvious thing wherever either is used. Three cases, because a link has to go\nsomewhere that exists: the router where there is one; the account&#39;s own address\nwhere there is not, which is the profile section this app adds to a Nextcloud\nuser page — a custom element running an app of its own, where a <code>router-link</code>\nresolves to nothing and takes the avatar with it; and nothing at all for an\nactor with neither a handle nor an address. Each link is named (&quot;Open the\nprofile of @alice&quot;), because its only content is an avatar with empty alt text.\n<code>link: false</code> turns it off where the avatar already sits inside a link — two\nnested anchors is invalid and the browser resolves it by dropping content — and\non the composer&#39;s reply and quote lines, where following one would abandon a\ndraft.</p>\n<h2 id=\"the-sidebars-my-profile-shortcut-leaves-the-aloha-social-router\">The sidebar&#39;s “My profile” shortcut leaves the Aloha Social router</h2>\n<p> The Aloha Social\nposts section is registered on Nextcloud&#39;s user profile page by\n<code>ProfileSectionListener</code>; its custom element fetches the selected user&#39;s Aloha Social\naccount summary and statuses and renders them in that page. The page knows its user by the user id, which the account&#39;s username need not be, so the listener puts the username into the initial state (<code>profileAccount</code>, <code>&#39;&#39;</code> for a user without an account) and the section asks the API by it. Nextcloud renders the page, and fires the event, for visitors who are not signed in too, and the page&#39;s address is the login: for such a visitor the listener does nothing where the username is not the user id, so the section is left off rather than mapping the login to the account (the rule <code>Person::nextcloudUser()</code> follows). Above the posts, the\nsection shows localized post, following, and follower totals from the same\naccount response used by Aloha Social&#39;s profile header. The <strong>My profile</strong> shortcut therefore uses Nextcloud&#39;s generated <code>/u/{uid}</code> URL. The adjacent <strong>Aloha Social profile</strong> shortcut remains inside Aloha Social&#39;s router at <code>@{acct}</code>, preserving the app&#39;s own profile editor for ActivityPub fields, links, biography and banner. <code>generateUrl()</code> preserves the installation web root and\n<code>encodeURIComponent()</code> keeps unusual user IDs inside one path segment. Because\nthis destination belongs to another Nextcloud page, its navigation row is a\nnormal browser link: it works with modified clicks and is not marked active by\nAloha Social&#39;s router. The Navigation test covers the generated destination and\nexternal navigation behavior; the profile integration test checks the three\ncounts and fetched posts.</p>\n<h2 id=\"account-previews\">Account previews</h2>\n<p> <code>AccountHoverCard.vue</code> is the card that opens when the\npointer rests on an avatar or a mention, fetched once per handle and cached in\nthe account store. It answers &quot;who is this?&quot; without opening the profile, so it\ncarries what the profile header does: display name and handle, when the account\njoined, the bio, up to four of its metadata fields (<code>src/utils/profileFields.js</code>\nparses those out of the HTML Mastodon sends them as, and the profile page uses\nthe same function so the two cannot disagree about what a link is), and the\nthree counts. Badges say what is true <em>of</em> the account rather than about it —\nthat it follows you, that it approves its followers, that it is automated — each\nof which is something somebody deciding whether to follow wants before they\nclick. Everything is conditional: a card built from what a status carried knows\nless than one built from a lookup, and a gap is better than an invented value. Two rules keep it consistent. Every avatar that <em>stands for\nsomebody</em> goes through <code>ActorAvatar</code> (or <code>TimelineAvatar</code>, which adds the\ninstance ring) rather than a bare <code>&lt;img&gt;</code>, so the small ones preview too — the\nface on a &quot;X boosted&quot; line, the one on a notification, the ones in Discover.\nAnd <strong>every</strong> <code>NcAvatar</code> in the app passes <code>disableMenu</code>, without exception,\nbecause for a <em>local</em> account it otherwise hangs Nextcloud&#39;s own profile card\noff the same hover and opens it over the top of this one: the reader would get\na different card depending on which instance the account was on. There is one\naccount preview in this app and it is this app&#39;s. The avatars that are not a\nreference to somebody else — the reader&#39;s own face in the composer, the profile\nheader of the profile you are already reading, the two on the remote-follow\npage — simply have no card rather than Nextcloud&#39;s.</p>\n<p>That rule is the kind a new avatar added next year cannot be expected to\nremember, so <code>tests/js/hoverCard.test.js</code> reads the templates and fails with the\nfile and line of any <code>&lt;NcAvatar&gt;</code> that is missing it.</p>\n<h2 id=\"quotedpost-vue\">QuotedPost.vue</h2>\n<p> renders a status&#39;s <code>quote</code>. Only an <code>accepted</code> quote whose\n<code>quoted_status</code> came back becomes a card; <code>pending</code>, <code>rejected</code>, <code>revoked</code> and\nan accepted quote the reader may not see each get a line saying which, because\na quote that silently renders as nothing is indistinguishable from a bug. A\nquoted post that itself quotes something is not nested a second time — the\ncomponent prints one line and stops, so no chain and no cycle can recurse.</p>\n<p><strong>The Photos view.</strong> The sidebar&#39;s <code>Photos</code>, directly under Home, is a timeline\nwith <code>media_type=image</code> — what people showed rather than what they said. It is\nthe same query and the same filters, one predicate narrower, so nothing about\nvisibility, blocks, mutes or silencing is decided twice.</p>\n<p>It asked <code>only_media</code> alone until 0.26.70, which is Mastodon&#39;s question — <em>does\nthis post carry an attachment</em> — and is not the one a page called Photos is\nasking: measured against a live instance, forty posts of that timeline carried\ntwenty-five video attachments. <code>media_type</code> is the app&#39;s own narrowing and the\nprofile&#39;s Photos tab and Explore&#39;s Pictures tab were both already sending it;\nthis one page was not. <code>only_media</code> still goes out beside it, so a server that\nhas not been upgraded yet answers with media rather than with everything. A post\ncarrying both a picture and a video is <code>mixed</code> and is in both pages, which is\nwhat <code>limitToMediaType()</code> already said.</p>\n<p>Which people is the same switcher: Photos carries it too, so the photos of the\npeople you follow, of this instance and of everywhere are one control apart.\nThe scope rides in the <strong>query</strong> (<code>/timeline/photos?scope=timeline</code>) rather than\nin a <code>type</code> of its own, for two reasons: the sidebar&#39;s Photos entry stays lit\nwhichever scope is being read, and the page is one page with a filter on it\nrather than three pages that happen to look alike. It is the route&#39;s own three\nwords there as well (<code>timeline</code>, <code>federated</code>, and nothing at all for My Feed),\nso no part of this translates between two vocabularies. The scope arrives from\nthe address bar, so <code>Timeline.vue</code> reads it rather than trusting it: anything\nthat is not one of the two named scopes is the default. It is also part of what\n<code>Timeline.vue</code> reports as the timeline&#39;s params, which is what makes changing it\nrefetch instead of leaving the previous photos on screen.</p>\n<h2 id=\"posts-photos-and-videos-on-a-profile\">Posts, Photos and Videos on a profile</h2>\n<p> The same switcher, above the account&#39;s posts, asking the server a different question rather than filtering the page on screen — a page filtered in the client is a page that can come back empty while there are still videos to find. (The Videos page&#39;s chips are the one place that filters in the client, and they ask for further pages themselves to keep from coming back empty; see <strong>The Videos view</strong>.) The tab rides in the query (<code>/@alice?media=video</code>) so a profile stays one route and every link to it still names the same one, and the word is the API&#39;s own.</p>\n<p>Behind it: <code>only_media</code> is Mastodon&#39;s own parameter on <code>/api/v1/accounts/{id}/statuses</code> and had never been passed on; <code>media_type</code> is a <strong>Aloha Social extension</strong> that narrows it to one kind, because Mastodon has nothing finer and two tabs need the difference. <code>ProbeOptions::setMediaType()</code> takes only the three kinds an attachment can be — <code>image</code>, <code>video</code>, <code>audio</code>, which are the first half of its MIME type and so the only values the column can hold — and reads anything else as no preference, since the value arrives from a query string. <code>media_type</code> implies <code>only_media</code>: a post with no attachments cannot be one carrying a video. The predicate is <code>SocialLimitsQueryBuilder::limitToMediaType()</code>, a <code>LIKE</code> on <code>&quot;type&quot;:&quot;video&quot;</code> in the stored attachments — the column holds them as the client sees them, there is no column to compare and no JSON support to rely on across the three databases this app supports, and a description containing the same text is stored with its quotes escaped so it cannot collide. Unindexed, like the silenced-instance filter and for the same reason: it runs on a list something else has already narrowed to one account. Pinned posts are left out of a filtered tab, being about the account rather than about a kind of attachment.</p>\n<h2 id=\"the-profile-page-is-for-reading\">The profile page is for reading</h2>\n<p> The Aloha Social section embedded in Nextcloud&#39;s <code>/u/{uid}</code> profile never mounts a post composer; new posts are written from the Aloha Social app. It shows the account&#39;s posts for any visitor, and adds <strong>My Feed</strong> only when the signed-in account owns the profile. <strong>Local</strong> and <strong>Global</strong> show the viewer&#39;s public Aloha Social timelines. The account banner is fetched from Aloha Social&#39;s account endpoint and shown only when it is a custom header rather than the avatar fallback. When Nextcloud&#39;s native profile header exists, the component teleports the decorative banner into that header, behind its avatar and name; the image stays at the top of the Aloha Social section as a fallback when the header is absent. The native header has a <code>top: -40px</code> offset; the teleport makes it positioned and activates that offset, so the Aloha Social banner explicitly resets <code>top</code> and <code>bottom</code> to align with the content and avoid a 40px coloured strip beneath it. Public local post links use the native <code>/u/{uid}</code> page with a status anchor; remote and non-public posts keep their Aloha Social or ActivityPub destination. The native Profile app remains responsible for its follower and post totals.</p>\n<h2 id=\"external-post-embeds\">External post embeds</h2>\n<p> Public local post pages advertise <code>/api/oembed</code> through a <code>Link</code> header. That endpoint returns a rich oEmbed document whose iframe targets <code>/@{username}/{token}/embed</code>; it answers only for local posts with <code>visibility=public</code>. The embed endpoint repeats that check independently and serves a small HTML document instead of the application shell; missing, remote, unlisted, followers-only and direct posts all return the same 404. It sanitizes the body, preserves content warnings in a collapsed disclosure, and shows author/avatar/date plus same-instance image, video and audio media, so embedding does not silently contact a third-party media host. Cross-origin framing is enabled on the embed response only, through its CSP <code>frame-ancestors</code>; the app shell and ordinary public post page retain Nextcloud&#39;s framing policy.</p>\n<h2 id=\"federated-media-recovery\">Federated media recovery</h2>\n<p> A remote <code>Note</code> can have <code>source.attachment</code> while its stored <code>attachments</code> column is <code>[]</code>, for example when an earlier import could not persist a CDN image. The normal renderer only reads the latter, so the post text remains visible while every image disappears. <code>social:media:recover</code> walks remote rows with an empty attachment list by <code>nid</code> in pages of 50, decodes the original ActivityPub object, and feeds its attachments through the same <code>Stream::importAttachments()</code> and <code>DocumentInterface</code> path used by an incoming post. It reads <code>attachment</code> in either shape ActivityPub writes it, a list or a single object on its own. It writes only the recovered attachment list and its derived <code>media_kind</code>; a conditional update leaves a concurrent import intact, and the summary counts those separately (<code>already filled</code>) so a run that changed nothing can be told from one that failed. Documents without an ActivityPub id receive a generated id on each import, so <code>DocumentInterface::save()</code> first looks for the same URL under the same parent post and reuses that row&#39;s id, nid and stored copy. This avoids both duplicate downloads and a newly generated <code>/media/{uuid}</code> URL that has no cache row behind it. The command has a read-only <code>--dry-run</code> and an examination <code>--limit</code>. Existing posts with media, local posts, and originals without an attachment list are never changed. A media failure does not rewrite the post&#39;s text, recipients, or publication metadata, and another run can retry a post that remained empty.</p>\n<h2 id=\"direct-messages-are-one-private-chat-per-person\">Direct messages are one private chat per person</h2>\n<p> <code>DirectMessages.vue</code> uses Nextcloud Vue controls and the full Aloha Social app-content width for a two-pane layout: the left column owns conversation search, compact all/unread filters and one conversation row per person; the right column owns the selected conversation, its scrollable message lane and a private-message field. The new-chat pane starts with deduplicated people from existing conversations and the signed-in account&#39;s following list, then searches cached and resolvable accounts by name or handle through <code>/api/v1/accounts/search</code>. This endpoint returns a plain array of Mastodon-compatible account objects; the older <code>/api/v1/global/accounts/search</code> returns the same entities wrapped in <code>result</code>. The search delay and request counters keep stale responses from overwriting a later query; an explicit error state distinguishes failed searches from no matches. Selecting somebody reuses that person&#39;s existing conversation where possible; the new-chat header and composer then use the same visual structure as a thread rather than a separate contact card. The composer has no audience selector. Each send sets direct visibility and adds the protocol-required recipient mention internally; the chat removes the leading recipient routing mention from message bubbles and inbox previews whether the server returns it as an h-card, a mention link, or plain text, and a preview also drops the reader&#39;s own leading handle — what a message from the other side opens with — while the bubble keeps it; later mentions remain in the message. Context-loaded messages receive saved link-preview cards through the same batched attachment service used by timelines, so previews render inside the chat without fetching arbitrary URLs in the browser. The native conversation action dismisses the thread from this viewer&#39;s inbox; it preserves the statuses and a later message makes the conversation reappear. Duplicate API threads for the same peer are collapsed in the inbox. Incoming and outgoing posts render as separate bubbles aligned to opposite sides, while consecutive messages from the same account are grouped without repeating the sender label. Opening a thread fetches its context and marks it read; sending a reply targets the latest message and stays private. At mobile width the view becomes a single pane whose Back button returns to the list.</p>\n<p>The Aloha Social section embedded in Nextcloud&#39;s <code>/u/{uid}</code> profile deliberately\nleaves post/follower/following totals to the native Profile app, which already\nrenders those numbers. Each status card adds its Likes and Comments controls\ninside the native card footer: likes load the existing <code>favourited_by</code> and\n<code>reblogged_by</code> data only when opened; comments load the status context on demand\nand display direct replies only. The Open post link uses the status&#39;s public\nURL, so it works in the custom element without relying on Aloha Social&#39;s main Vue\nRouter instance. The profile owner also sees a separate <strong>My Feed</strong> section,\nloaded from the authenticated home-timeline endpoint with cursor pagination;\nit is never requested on another person&#39;s profile, so followed/private posts\ncannot leak into a public page.</p>\n<p><strong>The tab also decides how it is drawn</strong>, and there is nothing beside it to say otherwise: Posts is what somebody wrote, so it is a list of posts; Photos and Videos are what they showed, so they are grids. There used to be a grid/list switch here, remembered across profiles, and it could disagree with the tab — <code>ProfileMediaGrid</code> kept only the posts carrying a picture, so Posts showed sixteen of them as a list and three as a grid, with nothing to say where the other thirteen had gone. One question, one answer. The empty state comes from <code>TimelineList</code> in both views for the same reason: the grid carried one of its own that said &quot;No photos yet&quot; whatever the tab was, so an account with no videos was told it had no photos.</p>\n<h2 id=\"the-videos-view\">The Videos view</h2>\n<p> The sidebar&#39;s <code>Videos</code>, directly under Photos, is the same\npage again with <code>only_video</code> — this app&#39;s own narrowing of <code>only_media</code>, because\na video timeline that asked Mastodon&#39;s question would answer with every holiday\nphoto on the instance. It carries the same switcher, in the same query\n(<code>/timeline/videos?scope=federated</code>), through the same <code>isScopedPage</code> branch in\n<code>Timeline.vue</code>: Photos and Videos differ in one predicate and in nothing else,\nwhich is why <code>TimelineSwitcher</code> takes the page it is scoping as a prop rather\nthan a <code>photos</code> flag.</p>\n<p>Two things make a post a video, and the query asks both (<code>limitToVideo()</code>): an\nattachment whose Mastodon <code>type</code> is <code>video</code>, or a post that arrived as a PeerTube\n<code>Video</code>. The second counts whether or not this instance found a playable file in\nit — the post is a video either way, and a timeline that hid the ones it could\nnot play would be hiding exactly the videos worth reporting.</p>\n<h2 id=\"it-is-drawn-as-a-video-sites-front-page\">It is drawn as a video site&#39;s front page</h2>\n<p> <code>Timeline.vue</code> gives the Videos\npage <code>display: &#39;videos&#39;</code> (Photos keeps <code>grid</code>), a wider column\n(<code>social__wrapper--videos</code>) and no composer; <code>TimelineList</code> keeps the paging,\nthe new-post pill, the push and poll catch-up, the errors and the empty state,\nand hands the timeline to <code>VideoBrowse.vue</code>, which draws it and emits <code>more</code>\nwhen it wants another page. Each card is <code>VideoCard.vue</code>, and everything it\nsays comes from the status&#39;s <code>video_card</code> (<code>Stream::exportVideoCard()</code>, the\ncontract in API.md): the title, running time, thumbnail, views, live flag,\ncategory and publication date of every video post, whatever it arrived as,\nwith null for what its origin did not say. The channel is the status&#39;s\n<code>account</code>.</p>\n<h2 id=\"rows\">Rows</h2>\n<p> The number of columns comes from the component&#39;s measured width\n(<code>columnsFor()</code>: one below 560 px, two below 880, three below 1180, four\nabove) and is the one number the CSS grid and the keyboard both use. The grid\nis cut into runs of whole rows with a shelf after each run rather than one\ngrid with the shelves inside, so no row has a hole and the DOM order is the\nreading order. The arrow keys move a card or a row (left and right swap in a\nright-to-left language), Home and End to the ends.</p>\n<h2 id=\"chips-filter-in-the-client\">Chips filter in the client</h2>\n<p> All, Live (only when a loaded video is\nlive), the categories of the loaded videos and Recently uploaded (posted in\nthe last seven days, by <code>created_at</code>) choose among what the timeline holds\n(<code>utils/videoCard.js</code>). Category and live sit in the <code>details</code> JSON, with no\ncolumn and no index, and a chip is offered only for what is loaded, so the\nserver is not asked; instead a chip that leaves fewer than <code>FILL_TARGET</code> (12)\ncards asks for further pages, at most <code>MAX_FILL_PAGES</code> (5) before it offers\n<strong>Look further</strong>, so a filter cannot page through a whole timeline by itself.\nA boost and the post it boosts are one card.</p>\n<h2 id=\"shelves\">Shelves</h2>\n<p> are each fetched once per scope the page is read at, beside the\ntimeline (<code>timelineStore.fetchSideList()</code>, which asks the way that list\nwould and holds nothing): <strong>Shorts</strong> (<code>only_short</code> in the same scope; a card\nopens <code>/shorts?scope=…&amp;start={id}</code>, and <code>VideoShorts</code> jumps to that post\nonce it has arrived), <strong>From channels you follow</strong> (the home scope with\n<code>only_video</code>, not on My Feed, which is the grid itself, and not without a\nsession), and <strong>Continue watching</strong> (<code>GET /api/v1/videos/continue</code>, read\nonce per page view and only with a session). Continue watching says that it\nis loading, that nothing is waiting yet, or that the list could not be read\nand offers to ask again; only a shelf with videos draws a row of cards and\ncuts the grid short. Under a chip there are no shelves. It is read on mount:\nthe Videos page and a single post are different route components, so coming\nback through the router mounts the page again and asks again; a scope change\nwithin the page keeps the list, which is the same list in every scope.</p>\n<h2 id=\"watch-progress\">Watch progress</h2>\n<p> is the server&#39;s (<code>WatchService</code>, one <code>social_watch</code> row\nper video and reader). <code>/api/v1/videos/continue</code> hands each status back\nwith <code>watch_progress</code> (<code>WatchRequest::unfinishedProgress()</code>, the same query\nas before with the row&#39;s position, duration and time); every other list\ncarries it as null. <code>services/videoProgress.js</code> keeps what that answer said\nby post, and <code>progressOf(status)</code> — <code>{position, duration, fraction, updatedAt}</code> or null — is the one place a card asks for its accent bar, so a\nplayer that reports positions with <code>POST /api/v1/statuses/{id}/watched</code>\nneeds nothing more on this page.</p>\n<h2 id=\"hover-preview\">Hover preview</h2>\n<p> After 600 ms of the pointer on a card, a muted, looping\n<code>&lt;video&gt;</code> of the first video attachment plays over the picture and is\nremoved when the pointer leaves. Only for <code>(hover: hover) and (pointer: fine)</code>, never with <code>prefers-reduced-motion</code>, <code>prefers-reduced-data</code> or\nSave-Data (<code>mayPreview()</code>), and never for a live, sensitive or filtered post.</p>\n<h2 id=\"upload-a-video\">Upload a video</h2>\n<p> (<code>VideoUploadButton.vue</code>) opens a <code>video/*</code> file picker\nfrom the press itself — a picker opened after the composer had loaded would\nno longer be in answer to the press, and browsers refuse it — then opens the\ncomposer in a dialog with the file handed over as <code>initialFiles</code>, which it\nattaches through the same code as a drop.</p>\n<h2 id=\"the-player\">The player</h2>\n<p> A video&#39;s own page (<code>VideoHeader.vue</code>) plays it in\n<code>VideoPlayer.vue</code> rather than in a post&#39;s attachment. Where the bytes come from\nis decided in one place for every player in the app,\n<code>services/videoSource.js</code>, which <code>MediaAttachment</code> uses too: the file; a remote\nHLS playlist, proxied, through hls.js (fetched lazily) everywhere but Safari;\nor a local video&#39;s ladder beside its file, which falls back to the file on a\nfatal error.</p>\n<ul>\n<li><p><strong>The controls are the player&#39;s own, not the element&#39;s.</strong> The <code>&lt;video&gt;</code> has\nno <code>controls</code> attribute. That is a decision (#2703), not an omission. A\nnative <code>&lt;video controls&gt;</code> was checked in Chromium, Firefox and WebKit (a\nPlaywright page playing the same local clip); it has the same handful of\ncontrols in all three, and nothing else:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th></th>\n<th>Native controls</th>\n<th><code>VideoPlayer.vue</code></th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Play, seek, volume, full screen</td>\n<td>yes</td>\n<td>yes</td>\n</tr>\n<tr>\n<td>Picture in picture</td>\n<td>yes in Chromium and Firefox; WebKit has <code>webkitEnterFullscreen</code> instead</td>\n<td>where the API exists, with the iPhone fallback</td>\n</tr>\n<tr>\n<td>HLS</td>\n<td>Safari&#39;s own; Chromium and Firefox need hls.js and have no menu for its levels</td>\n<td>hls.js, or Safari&#39;s native playback</td>\n</tr>\n<tr>\n<td>Quality levels</td>\n<td>no API and no UI</td>\n<td>hls.js levels, Auto first</td>\n</tr>\n<tr>\n<td>Chapters</td>\n<td>not representable</td>\n<td>a list of moments to press</td>\n</tr>\n<tr>\n<td>Subtitles</td>\n<td>an engine menu over the element&#39;s <code>&lt;track&gt;</code>s only</td>\n<td><code>&lt;track&gt;</code>s plus the tracks hls.js finds in a playlist</td>\n</tr>\n<tr>\n<td>Playback speed</td>\n<td>engine-specific, not extensible</td>\n<td>0.5–2×, kept across videos</td>\n</tr>\n<tr>\n<td>Resume and the mini-player</td>\n<td>the app can seek the element; there is no place for the notice or the hand-off</td>\n<td>yes</td>\n</tr>\n<tr>\n<td>The app&#39;s keyboard shortcuts</td>\n<td>the engine&#39;s own keys only</td>\n<td>one documented set, with the player tests covering them</td>\n</tr>\n<tr>\n<td>Accessible names and states</td>\n<td>UA shadow DOM: empty to Playwright&#39;s accessibility snapshot in all three engines</td>\n<td>labelled buttons and sliders, <code>aria-pressed</code> on what latches, a live region</td>\n</tr>\n</tbody></table></div>\n<p>A hybrid — native controls where they are richer, this bar otherwise —\nwould give the same video a different set of controls in every engine and\ntwo accessibility models to keep working, for the one part of the page that\nhas to behave the same everywhere. The app&#39;s bar is one focusable <code>region</code>\nwith labelled buttons and sliders, <code>aria-pressed</code> on what latches, a live\nregion for what a key or menu changed, a focus ring, and\n<code>prefers-reduced-motion</code> respected; the player tests cover the keys and the\nfocus rules. In the headless WebKit build available here the element took\nfocus but did not start on Space, so that engine&#39;s native keyboard\nbehaviour is the platform&#39;s and not something this suite can pin. If\nbrowsers ever give native controls a standard quality menu and a track list\nthat includes hls.js&#39;s, this decision is worth revisiting.</p>\n</li>\n</ul>\n<p>Around that:</p>\n<h2 id=\"resume-and-progress\">Resume and progress</h2>\n<p> It starts at <code>progressOf(status)</code> — the single\nstatus&#39;s <code>watch_progress</code>, or what the page already knew — unless that is\nwithin ten seconds of the end or past 95%, and reports with <code>POST /api/v1/statuses/{id}/watched</code> at most every <code>REPORT_EVERY</code> (10 s) of playing,\non pause, at the end (the whole duration, which the server forgets) and on\n<code>pagehide</code> by <code>navigator.sendBeacon</code> (the route takes no CSRF token, which a\nbeacon cannot carry). Only for somebody signed in, never for a live video.\nA report goes into <code>videoProgress.js</code> (<code>rememberProgress()</code>) only once the\nserver answered that it stored it (<code>{&quot;stored&quot;: bool}</code>); a failed write is\nlogged, the player says the place was not saved, and the next report tries\nagain. <code>progressOf()</code> takes the newer of that and what the server said, so\nevery card of the video on the page moves with it and a finished one loses\nits bar. A beacon cannot answer, so it keeps the page&#39;s best effort.</p>\n<h2 id=\"views\">Views</h2>\n<p> After <code>VIEW_AFTER</code> (5) seconds actually played — the deltas of\n<code>timeupdate</code>, a seek not counting — it sends <code>POST /api/v1/statuses/{id}/view</code>\nonce per video it plays.</p>\n<ul>\n<li><strong>Menus inside the player</strong>, so that they work in full screen: speed\n(0.5–2×, kept in <code>localStorage</code> under <code>social.video.speed</code> and set as the\nelement&#39;s default rate so a new source keeps it), quality (hls.js&#39;s levels,\nlargest first, each height once, Auto first; offered only where there are\ntwo or more — PeerTube publishes one MP4 per resolution, but the app keeps\nthe largest as the attachment, so a choice exists for HLS playlists and local\nladders) and subtitles (the <code>&lt;track&gt;</code>s of <code>video.captions</code>, which point at\nthis server, plus any subtitle tracks hls.js finds in a playlist). Each is a\n<code>role=&quot;menu&quot;</code> of <code>menuitemradio</code>s that the arrows walk and Escape closes,\ngiving the focus back to its button.</li>\n</ul>\n<h2 id=\"keys\">Keys</h2>\n<p> (<code>PLAYER_SHORTCUTS</code> in <code>services/shortcuts.js</code>, also listed by\n<code>ShortcutList</code>). One <code>keydown</code> listener on the window in the capture phase,\nso it runs before the app&#39;s own shortcuts, and a key it takes is not passed\non (<code>stopImmediatePropagation</code>) — on the watch page <code>j</code>, <code>k</code>, <code>l</code> and <code>f</code>\nare the player&#39;s. The watch page&#39;s player answers wherever the focus is on\nthe page; the small player only while it has the focus, and the watch page&#39;s\nplayer leaves alone a key pressed inside another player. Nothing while the\nreader types (a field, a contenteditable, a modifier held — the player&#39;s own\nsliders excepted, which keep their arrows), behind an open dialog, with\nshortcuts off in Settings (<code>shortcutsEnabled</code>) or in Nextcloud&#39;s\nAccessibility settings (<code>offInNextcloud()</code>), and Space and Enter stay with a\nfocused button (<code>belongsToElement()</code>). The up and down arrows change the\nvolume only while the player has the focus.</p>\n<h2 id=\"picture-in-picture\">Picture in picture</h2>\n<p> where <code>document.pictureInPictureEnabled</code>, and full\nscreen on the player itself (so the controls stay), with Safari&#39;s prefixed\nAPI and an iPhone&#39;s <code>webkitEnterFullscreen()</code> on the video as fallbacks.</p>\n<h2 id=\"accessibility\">Accessibility</h2>\n<p> The player is a focusable <code>region</code>; every control is a\nlabelled button or slider with a visible focus ring; a polite live region\nsays what a key or a menu changed (speed, quality, subtitles, sound,\nvolume, where it went on from). The controls fade while it plays untouched,\nnever while it has the focus or a menu is open, and without the fade under\n<code>prefers-reduced-motion</code>.</p>\n<h2 id=\"a-videos-page-reacts-like-a-post\">A video&#39;s page reacts like a post</h2>\n<p> Like and boost beside the channel use\nthe timeline&#39;s own store actions (<code>postLike</code>/<code>postUnlike</code>,\n<code>postBoost</code>/<code>postUnBoost</code>), so an active state and a count are the same object\nthe grid reads, including after a reload. The author&#39;s <code>interaction_policy</code> is\nchecked before either is offered, and an action already taken can always be\nundone. <strong>Dislike</strong> is PeerTube&#39;s other counter and is offered only here, only\non a video; the same control takes it back. A visitor with no session is\noffered none of the three. The counts beside the buttons are\n<code>favourites_count</code> and <code>reblogs_count</code>, left out for a reader who hides the\nnumbers; the facts line keeps PeerTube&#39;s own like and dislike numbers. The\nundo reads <code>status.disliked</code>, which is <code>social_stream_act.disliked</code> — every\nstream query has to select that column, because a missing alias reads as\n<code>false</code> and makes an undo impossible.</p>\n<h2 id=\"the-small-player\">The small player</h2>\n<p> Leaving a video&#39;s page while it plays hands the video\n(<code>handOff()</code> in <code>services/miniPlayer.js</code>, the post and the position) to\n<code>MiniPlayer.vue</code>, which <code>App.vue</code> draws in the bottom corner — loaded with the\n<code>watch</code> chunk, keyed by the post — for as long as the state holds a video, so\nit survives every navigation inside the app. It plays on from there with a\n<code>VideoPlayer</code> in <code>mini</code> mode and reports where it is as the page&#39;s did.\n<strong>Back to the video</strong> opens the post&#39;s route; the watch page&#39;s player takes\nthe video back (<code>takeBack()</code>) and goes on from the same moment, playing or\npaused as it was. <strong>Close the player</strong> clears the state, which unmounts it and\nstops the video. Nothing starts a video in it: it only ever holds one that was\nplaying, and a watch page that starts another video closes it.</p>\n<h2 id=\"news-on-the-server-only\">News, on the server only</h2>\n<p> The web interface used to have a News timeline\nin the sidebar, a News tab in Discover and a switch for it in the Features section of the administration page.\nAll three are gone, and <code>/timeline/news</code> redirects to My Feed. What stays is\nwhat a client can still ask for: the <code>only_news</code> parameter on the home and\npublic timelines, <code>/api/v1/trends/links</code>, and <code>/api/v1/timelines/link</code> — the\nlast is also still how the web interface opens everything said here about one\narticle. <code>section_news</code> is no longer read or written.</p>\n<p>What counts as news is two things, and the app takes both rather than choosing:\na post that <strong>is</strong> an article — an <code>Article</code> or a <code>Page</code>, which is what Plume,\nWriteFreely, Ghost and the WordPress plugin publish, and which arrives here as a\n<code>Note</code> carrying that word in <code>subtype</code> (<code>AP::NOTE_LIKE_TYPES</code>) — and a post that\n<strong>points at</strong> one, meaning an ordinary note whose text carries a link to\nsomewhere else. The second is where the volume is: most news on the fediverse\ntravels as somebody&#39;s sentence with a URL after it.</p>\n<p>The question &quot;does this text link anywhere&quot; is asked by <code>Stream::firstLinkIn()</code>,\nwhich is the same code <code>LinkPreviewService</code> asks before it fetches a preview.\nThat is deliberate rather than tidy: if the two disagreed, a post could be in the\nNews timeline with no card to draw, or carry a card and not be there. A mention\nand a hashtag are anchors too, and both are dropped whole before anything is\nlooked for — counting them would have made News a copy of the home timeline.</p>\n<p>What is deliberately <strong>not</strong> asked is whether the preview was actually fetched.\nCards are read from the linked page after the post is stored and may never\narrive; a post that dropped out of the News timeline hours later because\nsomebody else&#39;s web server was down would be worse than one that sits there\nwithout a picture.</p>\n<p>Boosts are not in it. A boost is a row of its own with no content of its own, so\n<code>news_kind</code> is <code>&#39;&#39;</code> for it — which on this page is the right answer rather than a\ngap: a news page whose top five entries are the same article five times is a\nworse page.</p>\n<p><strong>Where the links themselves are.</strong> <code>/api/v1/trends/links</code> counts the URLs this\ninstance shares, and <code>/api/v1/timelines/link?url=…</code> is everything said <em>here</em>\nabout one of them. Both are API only now.</p>\n<p>In the player, a video attachment with a <strong>preview that is not the video itself</strong>\ngets that preview as its <code>poster</code> and <code>preload=&quot;none&quot;</code>. Only a federated video\nhas one, and it is what lets a page of twenty of them be scrolled without opening\ntwenty connections to other servers: <code>preload=&quot;metadata&quot;</code> on a proxied video is\nnot free the way it is on a local one. A video uploaded here has <code>preview_url</code>\npointing at the file, which is no use as a poster — a browser handed a video for\none downloads it to find a frame — so those keep <code>metadata</code> and no poster.</p>\n<h2 id=\"one-column-one-owner\">One column, one owner</h2>\n<p> <code>--social-column</code> in <code>App.vue</code> is the width of the\ntimeline — 900px — and every view that shows the same column reads it from\nthere: the profile, the followers and follow-request lists, the blocked\naccounts, search, the welcome banner and the composer. They each used to carry\ntheir own <code>600px</code>, so widening the timeline alone would have made every other\npage snap back on navigation. (The OAuth consent card keeps its own narrow\nwidth; it is a dialog, not the column.) The list keeps <code>--social-column-gutter</code> inside that, so a\npost is narrower than the column by a gutter on each side; the composer takes the\ncolumn whole and therefore stands that much proud of the posts beneath it, which\nis deliberate — the box you write in should read as the thing that makes them\nrather than as one of them. Both used to carry the same max-width independently\nwhile only one of them had a gutter, which is how they came to disagree.</p>\n<h2 id=\"timelinelist\">TimelineList</h2>\n<p> owns its own layout and the views that render it do not touch\nit. That is not style: <code>.social__timeline</code> is a child component&#39;s <strong>root</strong>, and\na scoped rule still reaches a child&#39;s root — so a view styling it lands beside\nthe list&#39;s own rule at the same specificity and wins or loses on whatever order\nthe bundle puts them in. <code>Timeline.vue</code> set <code>margin: 0</code> there, which beat the\nlist&#39;s <code>margin: 0 auto</code> and left the timeline flush to one side while the\ncomposer beside it stayed centred. Where a view genuinely needs to shift the\nlist — the reply spine in <code>TimelineSinglePost</code> — it says so through its own\nelement (<code>.thread .social__timeline</code>), which wins on specificity rather than on\nluck.</p>\n<p>Every entry in the list has the same edges for the same reason. A notification\nis a card, because it is a thing that happened and the post inside it is quoted\nevidence; a boost is not, because it is somebody else&#39;s post with a line saying\nwho passed it on. Giving a boost a card put a box inside a box and inset the\npost by the outer padding, so boosted posts were narrower than their neighbours.</p>\n<h2 id=\"posts-that-are-pictures\">Posts that are pictures</h2>\n<p> A post carrying attachments and no content\nwarning is laid out around them: <code>TimelinePost.vue</code>&#39;s <code>mediaLeads</code> puts\n<code>PostAttachment</code> above the text, which then reads as a caption. A warning wins\nover that — its cover has to come before anything it covers — and so does edit\nmode, where the text is the thing being worked on. One or two pictures are a\nmosaic; from three (<code>CAROUSEL_FROM</code>) they become a <code>GalleryCarousel</code> paged with\nthe arrow keys, Home and End, because eight thumbnails side by side are eight\npictures in which nothing can be made out. The older thumbnail grid stays for\nevery place the text still leads.</p>\n<h2 id=\"galleryratio-js\">GalleryRatio.js</h2>\n<p> reserves each picture&#39;s box from <code>meta.original</code> before it\nloads, clamped between 3:4 and 16:9, so a photo timeline does not jump under the\nreader&#39;s thumb as images arrive; <code>MediaAttachment.vue</code> paints the <code>blurhash</code>\ninto that box meanwhile — decoded into a 32-pixel bitmap in the preview&#39;s\nratio that the box scales up, since a hash holds a few colour components and\nnot a picture. <code>GalleryMedia.vue</code> carries the ALT badge — the\ndescription is what the picture <em>is</em>, and a reader who cannot see it is not the\nonly one who wants it — and sets the <code>alt</code> attribute from the same value.</p>\n<h2 id=\"hashtagfollowbutton-vue\">HashtagFollowButton.vue</h2>\n<p> reads <code>/api/v1/tags/{tag}</code> on mount and whenever the\nroute&#39;s tag changes, and takes its state from what the server answers rather\nthan from what was asked, so a refused follow does not leave the button lying.\nIt renders nothing on the public page, where there is no viewer to follow\nanything. <code>HashtagFollowedList.vue</code> is the disclosure beneath it.</p>\n<h2 id=\"messagecontent-js\">MessageContent.js</h2>\n<p> turns both Unicode and custom emoji into inline image\nelements while walking sanitized post text. <code>TimelinePost.vue</code> gives actual\ncontent images a block layout; its image rule excludes <code>.emoji</code> and\n<code>.custom-emoji</code>, which stay inline with the surrounding text. <code>QuotedPost.vue</code>\napplies the same inline sizing so a quoted remote status preserves the same\nword flow. Direct-message bubbles clone a direct status for display and strip\nonly its leading ActivityPub recipient h-card; the stored status remains\nunchanged, and mentions later in the message still render normally.</p>\n<hr>\n","toc":[{"id":"directmessages-vue","text":"DirectMessages.vue","level":2},{"id":"profileinfo-vue","text":"ProfileInfo.vue","level":2},{"id":"composer-vue","text":"Composer.vue","level":2},{"id":"languageselect-vue","text":"LanguageSelect.vue","level":2},{"id":"scheduling","text":"Scheduling","level":2},{"id":"the-focal-point","text":"The focal point","level":2},{"id":"a-reply-reaches-the-conversation","text":"A reply reaches the conversation","level":2},{"id":"the-home-feeds-line-is-the-servers-marker-too","text":"The home feed's line is the server's marker too","level":2},{"id":"what-the-servers-limits-are-and-who-asks","text":"What the server's limits are, and who asks","level":2},{"id":"what-waits-for-the-timeline","text":"What waits for the timeline","level":2},{"id":"the-alt-badge","text":"The ALT badge","level":2},{"id":"the-foot-of-a-card","text":"The foot of a card","level":2},{"id":"the-action-row","text":"The action row","level":2},{"id":"sound-and-touch","text":"Sound and touch","level":2},{"id":"shorts-kept-and-24-hour","text":"Shorts, kept and 24-hour","level":2},{"id":"videos-with-sound","text":"Videos with sound","level":2},{"id":"video-recommendations-signals","text":"Video recommendations signals","level":2},{"id":"words-and-stickers-drawn-to-a-picture","text":"Words and stickers drawn to a picture","level":2},{"id":"picture-filters-and-pictures-too-large-to-send","text":"Picture filters, and pictures too large to send","level":2},{"id":"image-metadata","text":"Image metadata","level":2},{"id":"the-games","text":"The games","level":2},{"id":"the-constellation","text":"The constellation","level":2},{"id":"phone-layout","text":"Phone layout","level":2},{"id":"composer-vue-2","text":"Composer.vue","level":2},{"id":"the-settings-page-and-what-is-on-it","text":"The Settings page, and what is on it","level":2},{"id":"accountsettings-vue","text":"AccountSettings.vue","level":2},{"id":"the-default-audience","text":"The default audience","level":2},{"id":"listssettings-vue","text":"ListsSettings.vue","level":2},{"id":"muting-asks-two-questions","text":"Muting asks two questions","level":2},{"id":"the-statistics-page","text":"The Statistics page","level":2},{"id":"and-the-way-back-out","text":"And the way back out","level":2},{"id":"which-is-only-a-way-back-if-the-timeline-is-still-there","text":"Which is only a way back if the timeline is still there","level":2},{"id":"one-card-and-a-line-only-when-there-is-a-conversation","text":"One card, and a line only when there is a conversation","level":2},{"id":"a-like-blooms","text":"A like blooms","level":2},{"id":"loading-rolls-in","text":"Loading rolls in","level":2},{"id":"the-composer-says-aloha","text":"The composer says Aloha","level":2},{"id":"federation-is-islands","text":"Federation is islands","level":2},{"id":"a-link-to-a-post-opened-cold","text":"A link to a post, opened cold","level":2},{"id":"the-pictures-on-discover","text":"The pictures on Discover","level":2},{"id":"the-hashtags-on-discover","text":"The hashtags on Discover","level":2},{"id":"beside-it-what-other-servers-say","text":"Beside it, what other servers say","level":2},{"id":"postreactedby","text":"PostReactedBy","level":2},{"id":"postdetails","text":"PostDetails","level":2},{"id":"and-it-closes-by-hand-without-losing-anything","text":"And it closes by hand, without losing anything","level":2},{"id":"every-panel-the-toolbar-opens-closes-from-itself","text":"Every panel the toolbar opens closes from itself","level":2},{"id":"the-counters-are-columns","text":"The counters are columns","level":2},{"id":"a-post-is-a-link-to-itself","text":"A post is a link to itself","level":2},{"id":"an-avatar-is-a-link","text":"An avatar is a link","level":2},{"id":"the-sidebars-my-profile-shortcut-leaves-the-aloha-social-router","text":"The sidebar's “My profile” shortcut leaves the Aloha Social router","level":2},{"id":"account-previews","text":"Account previews","level":2},{"id":"quotedpost-vue","text":"QuotedPost.vue","level":2},{"id":"posts-photos-and-videos-on-a-profile","text":"Posts, Photos and Videos on a profile","level":2},{"id":"the-profile-page-is-for-reading","text":"The profile page is for reading","level":2},{"id":"external-post-embeds","text":"External post embeds","level":2},{"id":"federated-media-recovery","text":"Federated media recovery","level":2},{"id":"direct-messages-are-one-private-chat-per-person","text":"Direct messages are one private chat per person","level":2},{"id":"the-videos-view","text":"The Videos view","level":2},{"id":"it-is-drawn-as-a-video-sites-front-page","text":"It is drawn as a video site's front page","level":2},{"id":"rows","text":"Rows","level":2},{"id":"chips-filter-in-the-client","text":"Chips filter in the client","level":2},{"id":"shelves","text":"Shelves","level":2},{"id":"watch-progress","text":"Watch progress","level":2},{"id":"hover-preview","text":"Hover preview","level":2},{"id":"upload-a-video","text":"Upload a video","level":2},{"id":"the-player","text":"The player","level":2},{"id":"resume-and-progress","text":"Resume and progress","level":2},{"id":"views","text":"Views","level":2},{"id":"keys","text":"Keys","level":2},{"id":"picture-in-picture","text":"Picture in picture","level":2},{"id":"accessibility","text":"Accessibility","level":2},{"id":"a-videos-page-reacts-like-a-post","text":"A video's page reacts like a post","level":2},{"id":"the-small-player","text":"The small player","level":2},{"id":"news-on-the-server-only","text":"News, on the server only","level":2},{"id":"one-column-one-owner","text":"One column, one owner","level":2},{"id":"timelinelist","text":"TimelineList","level":2},{"id":"posts-that-are-pictures","text":"Posts that are pictures","level":2},{"id":"galleryratio-js","text":"GalleryRatio.js","level":2},{"id":"hashtagfollowbutton-vue","text":"HashtagFollowButton.vue","level":2},{"id":"messagecontent-js","text":"MessageContent.js","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"direct-messages","manual":false,"prev":{"path":"/docs/architecture-components","title":"Components"},"next":{"path":"/docs/architecture-integration-points","title":"Integration Points"},"parent":"architecture-frontend-architecture"},{"slug":"architecture-integration-points","path":"/docs/architecture-integration-points","title":"Integration Points","description":"Recent Aloha Social notifications, rendered client-side; loads social-dashboard","group":"architecture","html":"<h2 id=\"dashboard\">Dashboard</h2>\n<p><strong>Class: </strong><code>SocialWidget</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Recent Aloha Social notifications, rendered client-side; loads <code>social-dashboard</code></p>\n<h2 id=\"dashboard-2\">Dashboard</h2>\n<p><strong>Class: </strong><code>SocialTimelineWidget</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Home timeline, 300-second reload interval</p>\n<h2 id=\"dashboard-3\">Dashboard</h2>\n<p><strong>Class: </strong><code>SocialMentionsWidget</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>The notifications probe filtered to <code>mention</code></p>\n<h2 id=\"dashboard-4\">Dashboard</h2>\n<p><strong>Class: </strong><code>SocialDirectWidget</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Direct messages</p>\n<h2 id=\"dashboard-5\">Dashboard</h2>\n<p><strong>Class: </strong><code>SocialBookmarksWidget</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Saved posts</p>\n<h2 id=\"dashboard-6\">Dashboard</h2>\n<p><strong>Class: </strong><code>SocialFollowRequestsWidget</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Follow requests awaiting an answer; conditional — offered to a locked account, or one that still has requests waiting</p>\n<h2 id=\"dashboard-7\">Dashboard</h2>\n<p><strong>Class: </strong><code>SocialTrendingWidget</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Trending hashtags over one day, 900-second reload interval; needs no viewer</p>\n<h2 id=\"dashboard-8\">Dashboard</h2>\n<p><strong>Class: </strong><code>SocialReportsWidget</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Open moderation reports; conditional — admins only</p>\n<h2 id=\"dashboard-9\">Dashboard</h2>\n<p><strong>Class: </strong><code>SocialFederationHealthWidget</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Instances the outbound queue is failing to reach; conditional — admins only</p>\n<h2 id=\"unified-search\">Unified Search</h2>\n<p><strong>Class: </strong><code>UnifiedSearchProvider</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Searches URIs (from the cache only: the search bar asks once per debounced prefix of what is typed, and every prefix of a URL is another URL, so an actor this instance does not hold is queued for <code>Cron\\ResolveActor</code> through <code>RemoteFetchQueue::resolveActors()</code> and found by a later search), accounts, hashtags and <strong>status content</strong> (case-insensitive substring over the statuses the viewer may see: own posts, public/unlisted, and what is addressed to them — the timeline viewer bound). Local hits link to the post page, remote hits to their origin. Honours the query&#39;s cursor and limit — each source is asked for one entry past the end of the page, and a further page is offered only when one of them supplied it. It used to advertise a next cursor unconditionally while reading neither, so &quot;load more&quot; served the first page for ever</p>\n<h2 id=\"notifications\">Notifications</h2>\n<p><strong>Class: </strong><code>Notifier</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Prepares Aloha Social notifications for the NC notification system: every subject in <code>NotificationService::SUBJECTS</code> is worded, linked into this app&#39;s own pages, and so is the <code>digest</code> subject <code>NotificationDeliveryService::digestFor()</code> raises — &quot;%n new notifications in Aloha Social&quot; with the counts per kind read out in <code>SUBJECTS</code> order, plural-aware, and a last line &quot;%n people are waiting to reach you&quot; when the digest carries <code>waiting</code>, linking to the notifications timeline (<code>NotificationService::emit()</code> builds the link from the post&#39;s nid or the account&#39;s handle), and a <code>follow_request</code> carries Accept/Decline actions that POST to <code>/api/v1/follow_requests/{id}/authorize</code> and <code>/reject</code>; the answer dismisses the stored row and withdraws the bell entry (<code>onFollowRequestAnswered()</code>). The icon is the acting account&#39;s avatar as this server serves it — a local account&#39;s Nextcloud avatar route, a remote account&#39;s cached copy through <code>/media/{uuid}</code> (<code>NotificationService::avatarOf()</code>), never the picture on its own server, which the web interface&#39;s content policy will not load — and otherwise a monochrome picture of what happened (<code>img/favourite.svg</code>, <code>boost.svg</code>, <code>reply.svg</code>, <code>follow.svg</code>, <code>follow_request.svg</code>, <code>poll.svg</code>, <code>notifications.svg</code>, <code>edit.svg</code>, <code>report.svg</code>, <code>moderation.svg</code>); only the digest keeps the app icon</p>\n<h2 id=\"references\">References</h2>\n<p><strong>Class: </strong><code>Reference\\PostReferenceProvider</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Unfurls links to this app&#39;s posts and profiles (<code>/@acct/{nid}</code>, <code>/@acct/{id tail}</code>, <code>/@acct</code>) into a card wherever Nextcloud renders references — Talk, Text, Deck — and on public shares too (<code>IPublicReferenceProvider</code>). Renders only public and unlisted posts and profiles, because the card is cached per link for everyone (<code>getCacheKey()</code> is <code>null</code>, the prefix is the link); anything narrower resolves to nothing and stays a link. Never fetches from another server: a remote account not cached here is not looked up</p>\n<h2 id=\"activity\">Activity</h2>\n<p><strong>Class: </strong><code>Activity\\Publisher</code>, <code>Activity\\Provider</code>, <code>Activity\\Setting</code>, <code>Activity\\Filter</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code> (<code>Publisher</code> is called from <code>NotificationService::emit()</code>)</p>\n<p>Every bell entry is also an Activity entry with the same subject (<code>NotificationService::SUBJECTS</code>), worded by <code>Provider</code> with the actor as a rich <code>user</code> (local) or <code>highlight</code> (remote) and the post as the message. <code>Setting</code> puts it in the stream by default, the digest mail off by default, and Activity&#39;s own notifications off for good — this app has a bell. <code>Filter</code> is the &quot;Aloha Social&quot; entry in Activity&#39;s sidebar</p>\n<h2 id=\"user-migration\">User migration</h2>\n<p><strong>Class: </strong><code>UserMigration\\SocialMigrator</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>Puts the user&#39;s Aloha Social data in a Nextcloud account export, and reads it back on import. See &quot;Account export and import&quot; below</p>\n<h2 id=\"profile-page\">Profile Page</h2>\n<p><strong>Class: </strong><code>ProfileSectionListener</code> · <strong>Registered in: </strong><code>Application::register()</code> (on <code>BeforeTemplateRenderedEvent</code>)</p>\n<p>Adds the <code>social-profilePage</code> script to the user profile page, and the username of the page user&#39;s account as <code>profileAccount</code> — to a signed-in reader, or where the username is the user id; nothing for a visitor otherwise</p>\n<h2 id=\"files\">Files</h2>\n<p><strong>Class: </strong><code>FilesScriptsListener</code> · <strong>Registered in: </strong><code>Application::register()</code> (on <code>OCA\\Files\\Event\\LoadAdditionalScriptsEvent</code>)</p>\n<p>Adds the self-contained <code>social-filesAction</code> init script, which registers &quot;Share to Aloha Social&quot; on pictures and videos</p>\n<h2 id=\"files-comments\">Files comments</h2>\n<p><strong>Class: </strong><code>FileCommentsListener</code> · <strong>Registered in: </strong><code>Application::register()</code> (on <code>PostPublishedEvent</code>, <code>PostEditedEvent</code>, <code>PostDeletedEvent</code>, <code>CommentAddedEvent</code>, <code>CommentUpdatedEvent</code>, <code>CommentDeletedEvent</code>) and <code>NoteInterface</code> (incoming replies, edits and deletes)</p>\n<p>Replies to a post made from Files as comments on the file, and the author&#39;s comments there as replies. See &quot;Replies as comments in Files&quot; below</p>\n<h2 id=\"user-events\">User Events</h2>\n<p><strong>Class: </strong><code>UserAccountListener</code> · <strong>Registered in: </strong><code>Application::register()</code> (on <code>UserUpdatedEvent</code> and <code>UserChangedEvent</code>)</p>\n<p>Re-caches the local actor when the NC account changes; a new or removed avatar (<code>UserChangedEvent</code> feature <code>avatar</code>, made here or in Nextcloud&#39;s settings) also goes to the followers and Bluesky (<code>AccountService::avatarChanged()</code>), and is a new icon document at this app&#39;s avatar route of the username with its version in the address (<code>DocumentService::cacheLocalAvatarByUsername()</code>, served by <code>AvatarController</code>, which hands a visitor the generated initials where the avatar&#39;s scope keeps the picture off the actor), so peers fetch it again and never see the login</p>\n","toc":[{"id":"dashboard","text":"Dashboard","level":2},{"id":"dashboard-2","text":"Dashboard","level":2},{"id":"dashboard-3","text":"Dashboard","level":2},{"id":"dashboard-4","text":"Dashboard","level":2},{"id":"dashboard-5","text":"Dashboard","level":2},{"id":"dashboard-6","text":"Dashboard","level":2},{"id":"dashboard-7","text":"Dashboard","level":2},{"id":"dashboard-8","text":"Dashboard","level":2},{"id":"dashboard-9","text":"Dashboard","level":2},{"id":"unified-search","text":"Unified Search","level":2},{"id":"notifications","text":"Notifications","level":2},{"id":"references","text":"References","level":2},{"id":"activity","text":"Activity","level":2},{"id":"user-migration","text":"User migration","level":2},{"id":"profile-page","text":"Profile Page","level":2},{"id":"files","text":"Files","level":2},{"id":"files-comments","text":"Files comments","level":2},{"id":"user-events","text":"User Events","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":[{"path":"/docs/architecture-replies-as-comments-in-files","title":"Replies as comments in Files","description":"A picture posted from Files keeps a link to the file it was copied from, and the conversation about it can be read in the file's Comments tab (FileCommentsService, tables social_file_post…","parent":true},{"path":"/docs/architecture-events-this-app-publishes","title":"Events this app publishes","description":"The app listens to Nextcloud's events and, until now, published none of its own — so nothing else on the server could know that somebody had posted. An Activity entry, a Talk message, a…","parent":true}],"anchor":"integration-points","manual":false,"prev":{"path":"/docs/architecture-direct-messages","title":"Direct messages"},"next":{"path":"/docs/architecture-replies-as-comments-in-files","title":"Replies as comments in Files"},"parent":null},{"slug":"architecture-replies-as-comments-in-files","path":"/docs/architecture-replies-as-comments-in-files","title":"Replies as comments in Files","description":"A picture posted from Files keeps a link to the file it was copied from, and the conversation about it can be read in the file's Comments tab (FileCommentsService, tables social_file_post…","group":"architecture","html":"<p>A picture posted from Files keeps a link to the file it was copied from, and\nthe conversation about it can be read in the file&#39;s Comments tab\n(<code>FileCommentsService</code>, tables <code>social_file_post</code> and <code>social_file_comment</code>).</p>\n<ol>\n<li><code>POST /api/v1/media/from-file</code> records the file id against the new\nattachment&#39;s nid (<code>rememberAttachment()</code>).</li>\n<li><code>PostPublishedEvent</code> gives the post its files: the attachments it carries\nthat are still waiting are linked to it, if the post is public or unlisted.</li>\n<li>A reply to a linked post — written here (<code>PostPublishedEvent</code>) or arriving\nin the inbox (<code>NoteInterface::save()</code>) — is copied onto each linked file as\na comment, if it is public or unlisted and the author has not blocked or\nmuted the replier or their server. Somebody else&#39;s reply is a comment of\nactor type <code>social_fediverse</code>, credited in its first line, because the\nFiles sidebar only names Nextcloud users; the author&#39;s own reply is their\nown comment. Every <code>@</code> that would start a Nextcloud mention gets a word\njoiner after it, so a remote reply cannot notify a user here. An <code>Update</code>\nor a local edit (<code>PostEditedEvent</code>) rewrites the comment, a <code>Delete</code> or\n<code>PostDeletedEvent</code> removes it.</li>\n<li>A comment the <strong>post&#39;s author</strong> writes on the file (<code>CommentAddedEvent</code>)\nis sent as their reply through <code>PostService::createPost()</code>, with the post&#39;s\nvisibility and after <code>PostReviewService::assess()</code>; a comment the review\nwould hold stays a comment. A mention of a user here becomes a mention\nof their account, or their name when they have none.\nEditing or deleting that comment edits or deletes the reply. Everybody\nelse&#39;s comments stay on this server.</li>\n</ol>\n<p>The class marks its own comment writes and the reply it is sending, so the\nevents those cause are not answered a second time. It reads the post services\nfrom the container when it needs them, because <code>NoteInterface</code> depends on it\nand they reach <code>NoteInterface</code>. Every entry point from the inbox or an upload\nlogs a failure instead of throwing. The per-user switch is <code>files_comments</code>\n(<code>GET</code>/<code>PATCH /api/v1/social/files_comments</code>), on unless turned off; nothing\nhappens while the Comments app is disabled.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"replies-as-comments-in-files","manual":false,"prev":{"path":"/docs/architecture-integration-points","title":"Integration Points"},"next":{"path":"/docs/architecture-events-this-app-publishes","title":"Events this app publishes"},"parent":"architecture-integration-points"},{"slug":"architecture-events-this-app-publishes","path":"/docs/architecture-events-this-app-publishes","title":"Events this app publishes","description":"The app listens to Nextcloud's events and, until now, published none of its own — so nothing else on the server could know that somebody had posted. An Activity entry, a Talk message, a…","group":"architecture","html":"<p>The app listens to Nextcloud&#39;s events and, until now, published none of its own\n— so nothing else on the server could know that somebody had posted. An\nActivity entry, a Talk message, a Flow rule or an integration of somebody&#39;s own\nhad nothing to subscribe to, and would have had to poll this app&#39;s client API\nfrom inside the same server to find out.</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Event</th>\n<th>Dispatched from</th>\n<th>Carries</th>\n<th>When</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>OCA\\Social\\Events\\PostPublishedEvent</code></td>\n<td><code>PostService::createPost()</code></td>\n<td>the <code>Stream</code> as stored, and <code>getAuthorId()</code></td>\n<td>after the post is stored and addressed, <strong>before</strong> it is delivered</td>\n</tr>\n<tr>\n<td><code>OCA\\Social\\Events\\PostEditedEvent</code></td>\n<td><code>PostService::editPost()</code></td>\n<td>the <code>Stream</code> as edited, and <code>getAuthorId()</code></td>\n<td>after the edit and its revision are stored, <strong>before</strong> the <code>Update</code> is delivered</td>\n</tr>\n<tr>\n<td><code>OCA\\Social\\Events\\PostDeletedEvent</code></td>\n<td><code>StreamService::deleteLocalItem()</code></td>\n<td>the post as it last was</td>\n<td>after the row is gone and the <code>Delete</code> is queued</td>\n</tr>\n</tbody></table></div>\n<p>All three are <strong>local posts only</strong>. Everything that arrives from elsewhere arrives\nthrough the inbox, in volume, and an event per federated post would be a\nfirehose nobody asked for — that is a separate event with a separate name if\nanybody ever wants one.</p>\n<p>A listener must not wait for <em>delivery</em>: delivery is a queue and other people&#39;s\nservers, and a listener that waited on it would be waiting on the internet. The\npublish event says the post exists and has been addressed, which is the thing a\nlistener can act on.</p>\n<p>Subscribe as usual:</p>\n<pre><code class=\"language-php\">$context-&gt;registerEventListener(PostPublishedEvent::class, MyListener::class);\n</code></pre>\n<h2 id=\"user-events\">User Events</h2>\n<p><strong>Class: </strong><code>UserDeletedListener</code> · <strong>Registered in: </strong><code>Application::register()</code> (on <code>UserDeletedEvent</code>)</p>\n<p>Deletes the Aloha Social account of a deleted Nextcloud user through <code>AccountService::deleteActor()</code>: the actor is tombstoned, app authorizations and approved device codes are revoked, what belongs to it is dropped and a <code>Delete</code> is federated. A user who never opened Aloha Social has nothing here and is skipped; a failure is logged rather than thrown, since the Nextcloud user is already gone</p>\n<h2 id=\"group-events\">Group Events</h2>\n<p><strong>Class: </strong><code>GroupListListener</code> · <strong>Registered in: </strong><code>Application::register()</code> (on <code>UserAddedEvent</code>, <code>UserRemovedEvent</code>, <code>GroupDeletedEvent</code>, <code>GroupChangedEvent</code>)</p>\n<p>Keeps the group lists in step with the groups; never fails the group operation, a failure is logged and the cron&#39;s reconcile settles it</p>\n<h2 id=\"webfinger-nodeinfo-host-meta\">WebFinger / NodeInfo / host-meta</h2>\n<p><strong>Class: </strong><code>WebfingerHandler</code> · <strong>Registered in: </strong><code>Application::register()</code></p>\n<p>ActivityPub discovery at the server root</p>\n<h2 id=\"contacts-menu\">Contacts Menu</h2>\n<p><strong>Class: </strong><code>ContactsMenuProvider</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>&quot;Follow %s on Aloha Social&quot; entry linking to the actor page</p>\n<h2 id=\"background-jobs\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\Cache</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>12-minute interval, <code>MAX_DURATION</code> of 300 seconds: reaps deleted actors, refreshes local and remote actor caches, caches documents, recomputes hashtag trends, closes polls, prunes remote statuses past retention (bounded to 5000 per run), sweeps cached remote actors nobody refers to (bounded to 500), syncs the timelines of the remote actors a local account follows (<code>getRemoteActorsToSync()</code> — accepted follows only, because a synced outbox feeds its followers&#39; home timelines and nothing else reads it; its own batch — the refresh now stamps what it touched, so a shared selection would leave the sync nothing to do on a small instance), verifies profile links, reconciles group lists, finds out which servers the Discover page may ask (<code>FediverseDirectoryService::refresh()</code>) deletes the expired rows of <code>social_durable_cache</code>, forgets who was counted watching a video on the days before today (<code>VideoViewService::forgetEarlierDays()</code>), and sweeps the OAuth tables (<code>ClientService::sweep()</code>: authorizations idle past the token TTL, and app registrations nobody authorized within seven days — <code>social_client.last_update</code> moving off <code>creation</code> at the first authorization is what marks one as used). The budget is threaded through the steps and into the three loops that make a request per remote actor — the actor refresh and the details refresh each get at most <code>REMOTE_ACTOR_SECONDS</code> (90) of it and take batch after batch of <code>SYNC_BATCH</code> until then (<code>CacheActorService::walkDue()</code>), where one batch of fifty a pass could not keep the ten-day lifetime past about 60,000 cached actors; a step that has no time left is skipped and named in the log, and the next run <strong>starts with the first step it skipped</strong> (<code>cache_cron_start</code>), so the tail of the list is not the part that never runs</p>\n<h2 id=\"background-jobs-2\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\Queue</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>12-minute interval: drains the outbound request queue and the inbound stream queue, each on a budget of its own (240 and 120 seconds)</p>\n<h2 id=\"background-jobs-3\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\BlocklistSync</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Daily: re-reads the block lists an administrator follows (<code>BlocklistSubscriptionService::fetchEnabled()</code>); one app-setting read and nothing else while no source is on</p>\n<h2 id=\"background-jobs-4\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\StarterPackSources</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Daily: reads the starter packs the <code>starter_pack_sources</code> app value names (<code>CollectionPackService::refresh()</code>) — the fediverse&#39;s collections, checking every member&#39;s <code>featureAuthorization</code>, and Bluesky&#39;s suggested starter packs while Bluesky is on — and stores them; a source that cannot be reached keeps what was read from it last time. One run at a time (<code>setAllowParallelRuns(false)</code>), reading for at most <code>MAX_DURATION</code> (300 seconds); what it did not get to keeps what was read last time</p>\n<h2 id=\"background-jobs-5\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\ActorCleanup</code> · <strong>Registered in: </strong>queued by <code>PersonInterface::delete()</code></p>\n<p>Finishes detaching a deleted account from the posts that addressed it, when there are more of them than one inbox request should rewrite. Not in <code>appinfo/info.xml</code>, for the same reason <code>Cron\\DomainPurge</code> is not: it is meaningless without an argument. Re-queues itself while rows remain</p>\n<h2 id=\"background-jobs-6\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\SyncRemoteTimeline</code> · <strong>Registered in: </strong>queued by <code>RemoteFetchQueue::syncTimeline()</code> or <code>fillTimeline()</code></p>\n<p>Reads one bounded page of a remote account&#39;s outbox after its profile was opened. The first page is refreshed at most every 15 minutes; later pages resume from the durable outbox cursor only when scrolling reaches the end of locally stored posts. A failed page leaves the cursor in place for retry. Not in <code>appinfo/info.xml</code>, for the same reason as <code>Cron\\DomainPurge</code>. The followed accounts are synced by <code>Cron\\Cache</code> regardless</p>\n<h2 id=\"background-jobs-7\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\ResolveActor</code> · <strong>Registered in: </strong>queued by <code>RemoteFetchQueue::resolveActors()</code> and <code>resolveAccounts()</code></p>\n<p>Fetches and caches one remote actor a page named and did not have, with the actor id (or, from <code>resolveAccounts()</code>, a <code>user@host</code> handle) as its argument; not in <code>appinfo/info.xml</code>, for the same reason as <code>Cron\\DomainPurge</code>. A failure is logged and dropped: the next page that names the actor queues it again</p>\n<h2 id=\"background-jobs-8\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\DomainPurge</code> · <strong>Registered in: </strong>queued by <code>FediverseService::addAddress()</code></p>\n<p>Queued with a domain when one is added to the deny list, never registered in <code>appinfo/info.xml</code> — a job listed there is added once at install time with no argument, and this one is meaningless without a domain. Runs 10 batches of <code>DomainPurgeService</code> per pass and re-queues itself while anything of the domain is left</p>\n<h2 id=\"background-jobs-9\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\SearchIndex</code> · <strong>Registered in: </strong>queued by <code>Version1000Date20261008000401</code></p>\n<p>Adds the posts stored before <code>social_search_term</code> existed to it, 500 at a time in nid order for up to a minute per run, from the cursor in the <code>search_index_cursor</code> app setting; re-queues itself until a chunk comes back short, then sets <code>search_index_ready</code> and the search stops scanning. A chunk that fails twice at the same cursor (<code>search_index_failing</code>) is indexed one post at a time, and the post a chunk of one fails on is logged by nid, counted in <code>search_index_skipped</code> (shown by the &quot;index repairs&quot; setup check) and passed over, so no post holds the index back for good. Not in <code>appinfo/info.xml</code>: it is a one-off</p>\n<h2 id=\"background-jobs-10\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\ThreadRoots</code> · <strong>Registered in: </strong>queued by <code>Version1000Date20261016100400</code></p>\n<p>Gives the direct messages stored before <code>social_stream.root_prim</code> existed the root of their thread, reading <code>social_stream</code> 2000 posts at a time in nid order for up to a minute per run from the cursor in the <code>thread_roots_cursor</code> app setting; a message that already has a root is passed over and one that fails is logged and passed over, so a repeated run changes nothing it already did; re-queues itself until a chunk comes back short. Not in <code>appinfo/info.xml</code>: it is a one-off</p>\n<h2 id=\"background-jobs-11\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\CompactStoredCopies</code> · <strong>Registered in: </strong>queued by <code>Version1000Date20261012000100</code></p>\n<p>Takes out of the rows stored before it the copies nothing reads back: the decoded <code>object</code> beside each <code>cache</code> item&#39;s <code>content</code>, and the whole post or actor in a notification&#39;s <code>details</code>. One walk of <code>social_stream</code> by nid, 500 rows a page and 40 pages a run, re-queued with the nid it reached until a page comes back short. Not in <code>appinfo/info.xml</code>: it is a one-off</p>\n<h2 id=\"background-jobs-12\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\InterestHides</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Daily: forgets the &quot;less like this&quot; hides older than twice the For you window (the reach of a photo or video ranking), which can no longer keep anything out of the feed</p>\n<h2 id=\"background-jobs-13\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\MediaSweep</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Daily: removes the cached documents (rows and files) whose post, cached actor or story is gone, once they are 30 days old, page after page of 500 in nid order — each page read after the last row of the one before, so a row that would not go is not read again — for up to <code>SECONDS</code> (120) per run; one page a day fell behind any prune or purge that orphaned more. Then records the type of up to 500 documents stored before the type was</p>\n<h2 id=\"background-jobs-14\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\ExpiredStories</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Hourly: deletes the stories (24-hour shorts) whose day is up, at most 500 per run. The read filter on <code>expires_at</code> is the other half of the guarantee; this is what stops the rows and pictures outliving it</p>\n<h2 id=\"background-jobs-15\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\ScheduledPosts</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>5-minute interval: publishes the scheduled posts whose time has come, at most 50 per run. Shorter than the other two jobs on purpose — a post may be published up to one cron period late, and a period longer than the five minutes&#39; notice the API demands would promise a precision the app cannot keep</p>\n<h2 id=\"background-jobs-16\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\NotificationDigests</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>5-minute interval, for the same reason as <code>ScheduledPosts</code>: visits the users flagged by <code>NotificationDeliveryService</code> (at most 1000 per run, 240 seconds), and for each raises the digests that have fallen due since their last one — the digest times in digest mode, the end of the quiet window in either mode — with the due time as the cut rather than the moment the job ran, so a late job reports the window the user asked for and the next window starts where it ended. At most four per user per run; a user with no clock yet gets one started rather than a digest of everything since 1970</p>\n<h2 id=\"background-jobs-17\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\AtprotoMaintenance</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>5-minute interval, only while Bluesky is on: reconciles the last day&#39;s public posts with their Bluesky records (publishes what the listener missed, replaces an edit within the grace period, removes the record of a deleted post; the newest 100 posts and post records written here, and the next 100 of the rest of the day from where the last run stopped, the position in <code>social_durable_cache</code>), resends directory operations the PLC refused, prunes the firehose past its replay window, drops retired instance keys, checks a bounded page of stored Bluesky posts against the AppView and the author&#39;s PDS (<code>DeletionSweep</code>; each cycle snapshots its highest NID, retries inconclusive per-post checks in the next cycle, and persists its cursor in <code>atproto_delete_cursor</code>), checks custom handles once a day (<code>CustomHandleService::recheck()</code>, dropping one that failed seven checks in a row), and picks up account moves whose job stopped (<code>StaleMoves</code>: a running move not written to for an hour, with no job queued and none holding its lock, is queued again once, then failed with <code>move-interrupted</code> — or, moving here at the follows or the posts, done)</p>\n<h2 id=\"background-jobs-18\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\AtprotoHealthCheck</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>15-minute interval, only while Bluesky is on: refreshes cached checks of public OAuth protected-resource and authorization-server discovery (JSON origin, one authorization server, PAR, DPoP/ES256, grants, S256, scopes and client-auth methods), public PLC DID resolution, AppView profile and newest-post visibility, relay host status and one active local repo per relay, and the firehose reverse-proxy WebSocket handshake; reports missing external indexing as a warning because relays and AppViews converge asynchronously</p>\n<h2 id=\"background-jobs-19\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\AtprotoSync</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>2-minute interval, only while Bluesky is on: reads the newest page of each due watch (<code>social_atproto_watch</code>) from the public AppView and stores what is new, then asks the AppView&#39;s notifications for each due local account (<code>social_atproto_notify_cursor</code>); both within the request ceiling, both backed off after empty reads</p>\n<h2 id=\"background-jobs-20\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\AtprotoVideo</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>1-minute interval, only while Bluesky is on and a video service is set: sends up to three queued videos to Bluesky&#39;s video service in their accounts&#39; names, asks after the jobs being made, and publishes each post whose video has ended — with the video, or as a link (<code>social_atproto_video</code>)</p>\n<h2 id=\"background-jobs-21\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\FillFollowedTags</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>15-minute interval: reads the new posts with ten of the hashtags people here follow from every network (<code>FollowedTagsFill</code>), the ones read longest ago first — see <strong>Hashtags and searches beyond this server</strong></p>\n<h2 id=\"background-jobs-22\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\Transcode</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>15-minute interval, one video per run: re-encodes a stored video that is not an H.264 MP4 into one (<code>video_transcode</code>), the sweep behind <code>Cron\\TranscodeBeforeDelivery</code>, which converts the video a held post is waiting on; a no-op without ffmpeg</p>\n<h2 id=\"background-jobs-23\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\VideoPosters</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>15-minute interval: makes the poster frames of up to five stored videos that have none (<code>VideoPosterBackfill</code>), in nid order from the <code>poster_backfill_cursor</code> app setting, each video once, and rewrites the attachment copies of the posts carrying each; does nothing while the server has no ffmpeg, so the cursor waits for it</p>\n<h2 id=\"background-jobs-24\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\Ladder</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>30-minute interval, one video per run, only while <code>video_ladder</code> is on: writes a stored MP4 at the ladder of smaller sizes as HLS (<code>video_ladder_heights</code>)</p>\n<h2 id=\"background-jobs-25\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\GifPack</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>15-minute interval, a few pictures per run, only while <code>gif_pack</code> is on: fetches the first screenful of the animated emoji into appdata before anybody opens the picker, then does nothing but one appdata listing</p>\n<h2 id=\"background-jobs-26\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\MediaSweep</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Daily, 500 rows of each kind per run: deletes the stored files whose parent — the post, the cached actor or the story — is gone for more than <code>DAYS</code> (30), and fills in the media type of rows stored before it was recorded, without which a client hides the attachment</p>\n<h2 id=\"background-jobs-27\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\Index</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>5-minute interval: repairs missing rows of the stream side indexes (recipients, tags) for posts stored before they existed, incrementally and without truncating anything</p>\n<h2 id=\"background-jobs-28\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\ExternalSignups</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Hourly: forgets registrations whose email was never confirmed and invitations that expired or were used up, since a pending registration reserves its handle and its email address</p>\n<h2 id=\"background-jobs-29\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\ModerationLists</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>6-hour interval: reads again the shared mute and block lists people here subscribe to (<code>ModerationListService::refresh()</code>), so a list that grew is applied here</p>\n<h2 id=\"background-jobs-30\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\AtprotoPublish</code> · <strong>Registered in: </strong>queued by <code>AtprotoPostListener</code> and <code>AccountService</code></p>\n<p>One post or profile at a time: publish, edit, delete, profile — the work the listener queues on the post events, done off the request — and the likes, reposts, direct messages and conversation changes queued the same way. Not in <code>appinfo/info.xml</code>: meaningless without its argument. A failure that may pass (a service down, a lock that timed out) queues the job again with the attempt count in its argument, on <code>Backoff::bluesky()</code> (<code>tries^4 + 30</code> seconds, eight attempts, about 80 minutes in all), and the last attempt is logged as given up at error level; a failure no attempt would change (what the job is of is gone, a 4xx other than 408/425/429, a record that does not fit its lexicon, sealed keys) is logged and left. A like or repost undone before its job runs writes nothing. The maintenance job is the backstop for a post whose job failed or was never queued</p>\n<h2 id=\"background-jobs-31\">Background Jobs</h2>\n<p><strong>Class: </strong><code>Cron\\AtprotoMove</code> · <strong>Registered in: </strong>queued by <code>MoveAwayService</code>, <code>MoveInService</code> and <code>InboundMoveService</code></p>\n<p>One move of a Bluesky account, the steps left of it: away — the repository, the blobs, the preferences, the DID, the activation; here — the repository, the blobs, the preferences, the follows, then, once the person entered the e-mailed code, the DID and the posts into the timeline; moved here by the other side — the follows and the posts, once the account is active. Not in <code>appinfo/info.xml</code>: meaningless without its argument. A step that fails stops it, and the person starts it again from there; a job that dies is noticed by <code>AtprotoMaintenance</code> (<code>StaleMoves</code>). The job holds the move&#39;s lock (<code>ILockingProvider</code>, <code>AtprotoMove::lockOf()</code>) while it runs, so a second job queued for the same move leaves it to the first; what it writes when a step fails is written only while the move is still <code>running</code> (<code>AtprotoMoveRequest::updateIfRunning()</code>), so a move called off meanwhile stays called off</p>\n<h2 id=\"repair-step\">Repair step</h2>\n<p><strong>Class: </strong><code>Migration\\EncryptPrivateKeys</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Seals legacy plaintext actor private keys with ICrypto, once. A row it cannot process is named and skipped rather than aborting <code>occ upgrade</code> with the instance in maintenance mode</p>\n<h2 id=\"repair-step-2\">Repair step</h2>\n<p><strong>Class: </strong><code>Migration\\BackfillRemoteVisibility</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Backfills the empty visibility of remote statuses stored before estimation landed (public/unlisted set-based, followers/direct per author), idempotent</p>\n<h2 id=\"repair-step-3\">Repair step</h2>\n<p><strong>Class: </strong><code>Migration\\CacheFeaturedCollections</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Rebuilds the cached copy of every local actor when something the cache carries has changed — the <code>featured</code> URL, the display name. Gated on a <code>VERSION</code> marker rather than re-running on every upgrade, and it counts the local actors before loading any</p>\n<h2 id=\"repair-step-4\">Repair step</h2>\n<p><strong>Class: </strong><code>Migration\\InstallBackfills</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code> (install)</p>\n<p>Runs, when the app is installed, the backfills Nextcloud skips there: it runs an app&#39;s migrations schema-only on install, so no <code>postSchemaChange()</code> does, and the flags those raise stayed down for good on an instance installed after them. It calls the <code>fill()</code> of <code>Version1000Date20260917000001</code> (<code>dest_nid_filled</code>, the home timeline&#39;s fast path) and <code>Version1000Date20261013100500</code> (<code>stream_archived_filled</code>, <code>stream_media_kind_filled</code>), which find the tables empty and raise their flags at once, and queues <code>Cron\\SearchIndex</code> (<code>search_index_ready</code>) and <code>Cron\\StreamAuthorHosts</code> (<code>stream_author_hosts_filled</code>) as <code>Version1000Date20261008000401</code> and <code>Version1000Date20261008000503</code> do, which raise theirs on their first run</p>\n<h2 id=\"repair-step-5\">Repair step</h2>\n<p><strong>Class: </strong><code>Migration\\BackfillStreamPostFields</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Fills in <code>social_stream.tags</code>, <code>language</code>, <code>updated</code>, <code>quote</code> and <code>quote_authorization</code> for the rows stored before those columns existed, by re-reading each row&#39;s wire object through <code>Stream::importFromDatabase()</code> — one parser, not a second copy of it. Pages on the primary key, writes only the rows that disagree, and is gated on a marker so it is not a full scan of the largest table on every later upgrade</p>\n<h2 id=\"repair-step-6\">Repair step</h2>\n<p><strong>Class: </strong><code>Migration\\ClearAvatarHeaders</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Removes the header the old avatar fallback stored in the source document of a cached local actor: an <code>image</code> that is the account&#39;s icon, or Nextcloud&#39;s avatar route of its handle at any size. A cache rebuild read it back from there, so it never went away by itself; until this has run <code>Person::getHeader()</code> reads such a header as none. Local rows only, paged on the primary key, gated on a marker</p>\n<h2 id=\"repair-step-7\">Repair step</h2>\n<p><strong>Class: </strong><code>Migration\\RepublishBlueskyProfiles</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Queues one <code>AtprotoPublish</code> <code>profile</code> job per active Bluesky identity, once, while Bluesky is on: the profiles published before named the account by its username rather than by the name it federates (<code>RecordMapper::displayNameOf()</code>). Gated on a marker</p>\n<h2 id=\"repair-step-8\">Repair step</h2>\n<p><strong>Class: </strong><code>Migration\\RepublishAvatarAddresses</code> · <strong>Registered in: </strong><code>appinfo/info.xml</code></p>\n<p>Queues <code>Cron\\RepublishAvatars</code> once (gated on a marker). The job walks the local accounts, 50 a run, each run queueing the next from where it got to, and for every account whose username is not its login — the only ones whose old icon address, Nextcloud&#39;s <code>/avatar/{uid}/…</code>, named something not public — re-caches it and sends its followers an actor <code>Update</code> (<code>AccountService::republishActor()</code>), so their servers read the icon at this app&#39;s avatar route of the username. Team accounts, channels and deleted accounts are skipped</p>\n<p>The four timeline tiles (home, mentions, direct, bookmarks) extend\n<code>Dashboard\\TimelineWidget</code>, which resolves the viewer, builds the <code>ProbeOptions</code>\nand turns a stream row into a tile row; a subclass supplies the probe, the\n<code>/timeline/{path}</code> it opens and its empty-state wording. A row&#39;s <code>sinceId</code> is\nthe stream <code>nid</code>, which is what the widget feeds back to <code>ProbeOptions::setSince()</code>\non the next poll — <code>setMinId()</code> would return the oldest matching rows instead of\nthe newest. A boost renders as the post it repeats, subtitled with who boosted\nit; a boost or notification whose subject did not resolve has no row.</p>\n<p>The occ commands are registered in <code>appinfo/info.xml</code>. <code>lib/Command/</code> also holds <code>SocialCommand.php</code>, the base class all of them extend — it declares <code>--output</code> and the writers that honour it, in place of the server&#39;s private <code>OC\\Core\\Command\\Base</code> — and <code>ExtendedBase.php</code>, a shared base several of them extend. Neither calls <code>setName()</code>, so neither registers a command of its own. See <code>docs/OCC-Commands.md</code>.</p>\n<hr>\n","toc":[{"id":"user-events","text":"User Events","level":2},{"id":"group-events","text":"Group Events","level":2},{"id":"webfinger-nodeinfo-host-meta","text":"WebFinger / NodeInfo / host-meta","level":2},{"id":"contacts-menu","text":"Contacts Menu","level":2},{"id":"background-jobs","text":"Background Jobs","level":2},{"id":"background-jobs-2","text":"Background Jobs","level":2},{"id":"background-jobs-3","text":"Background Jobs","level":2},{"id":"background-jobs-4","text":"Background Jobs","level":2},{"id":"background-jobs-5","text":"Background Jobs","level":2},{"id":"background-jobs-6","text":"Background Jobs","level":2},{"id":"background-jobs-7","text":"Background Jobs","level":2},{"id":"background-jobs-8","text":"Background Jobs","level":2},{"id":"background-jobs-9","text":"Background Jobs","level":2},{"id":"background-jobs-10","text":"Background Jobs","level":2},{"id":"background-jobs-11","text":"Background Jobs","level":2},{"id":"background-jobs-12","text":"Background Jobs","level":2},{"id":"background-jobs-13","text":"Background Jobs","level":2},{"id":"background-jobs-14","text":"Background Jobs","level":2},{"id":"background-jobs-15","text":"Background Jobs","level":2},{"id":"background-jobs-16","text":"Background Jobs","level":2},{"id":"background-jobs-17","text":"Background Jobs","level":2},{"id":"background-jobs-18","text":"Background Jobs","level":2},{"id":"background-jobs-19","text":"Background Jobs","level":2},{"id":"background-jobs-20","text":"Background Jobs","level":2},{"id":"background-jobs-21","text":"Background Jobs","level":2},{"id":"background-jobs-22","text":"Background Jobs","level":2},{"id":"background-jobs-23","text":"Background Jobs","level":2},{"id":"background-jobs-24","text":"Background Jobs","level":2},{"id":"background-jobs-25","text":"Background Jobs","level":2},{"id":"background-jobs-26","text":"Background Jobs","level":2},{"id":"background-jobs-27","text":"Background Jobs","level":2},{"id":"background-jobs-28","text":"Background Jobs","level":2},{"id":"background-jobs-29","text":"Background Jobs","level":2},{"id":"background-jobs-30","text":"Background Jobs","level":2},{"id":"background-jobs-31","text":"Background Jobs","level":2},{"id":"repair-step","text":"Repair step","level":2},{"id":"repair-step-2","text":"Repair step","level":2},{"id":"repair-step-3","text":"Repair step","level":2},{"id":"repair-step-4","text":"Repair step","level":2},{"id":"repair-step-5","text":"Repair step","level":2},{"id":"repair-step-6","text":"Repair step","level":2},{"id":"repair-step-7","text":"Repair step","level":2},{"id":"repair-step-8","text":"Repair step","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"events-this-app-publishes","manual":false,"prev":{"path":"/docs/architecture-replies-as-comments-in-files","title":"Replies as comments in Files"},"next":{"path":"/docs/architecture-account-export-and-import","title":"Account export and import"},"parent":"architecture-integration-points"},{"slug":"architecture-account-export-and-import","path":"/docs/architecture-account-export-and-import","title":"Account export and import","description":"lib/UserMigration/SocialMigrator.php implements the server's OCP\\UserMigration\\IMigrator (and ISizeEstimationMigrator), registered in Application::register(). It is what makes a user's…","group":"architecture","html":"<p><code>lib/UserMigration/SocialMigrator.php</code> implements the server&#39;s\n<code>OCP\\UserMigration\\IMigrator</code> (and <code>ISizeEstimationMigrator</code>), registered in\n<code>Application::register()</code>. It is what makes a user&#39;s Fediverse identity part of\n<code>occ user:export</code> / <code>occ user:import</code> and of the account-transfer UI; before it\nexisted, an exported account carried nothing of this app at all.</p>\n<p>The migrator id is <code>social</code> and the export format version is <code>1</code>. Everything it\nwrites lives under <code>social/</code> in the archive:</p>\n<h2 id=\"social-actor-json\">social/actor.json</h2>\n<p>The actor: id, handle, display name, bio, profile fields, <code>locked</code>, <code>discoverable</code>, <code>indexable</code>, <code>bot</code>, <code>sensitive</code>, default privacy, language, avatar and header URLs, <code>alsoKnownAs</code>, <code>movedTo</code>, the <strong>public</strong> key and the creation date</p>\n<h2 id=\"social-following-accounts-csv\">social/following_accounts.csv</h2>\n<p>Who the account follows, in Mastodon&#39;s <code>following_accounts.csv</code> shape (<code>Account address,Show boosts,Notify on new posts,Languages</code>) — written by <code>MigrationService::exportFollowsCsv()</code>, read by <code>MigrationService::parseFollowsCsv()</code>, and accepted by Mastodon&#39;s own &quot;Import follows&quot;</p>\n<h2 id=\"social-followers-csv\">social/followers.csv</h2>\n<p>Who follows the account, same shape. A record for the user; nothing imports it, because a follower is somebody else&#39;s decision</p>\n<h2 id=\"social-blocked-accounts-csv\">social/blocked_accounts.csv</h2>\n<p>Blocked handles, one per line (the shape Mastodon exports)</p>\n<h2 id=\"social-muted-accounts-csv\">social/muted_accounts.csv</h2>\n<p>Muted handles with the <code>Hide notifications</code> column</p>\n<h2 id=\"social-bookmarks-csv\">social/bookmarks.csv</h2>\n<p>The URLs of the bookmarked posts</p>\n<h2 id=\"social-likes-csv\">social/likes.csv</h2>\n<p>The URLs of the favourited posts</p>\n<h2 id=\"social-interests-json\">social/interests.json</h2>\n<p>For you as <code>InterestService::export()</code> writes them: every row (tag, score, <code>scored_at</code>, manual, position) and the reader&#39;s learning switch, languages and reading pace. Imported rows keep their times, so decay carries on rather than restarting; out-of-range values are clamped and a row that is not a hashtag is left out. The posts hidden with &quot;less like this&quot; do not travel: they name posts on this server</p>\n<h2 id=\"social-outbox-json\">social/outbox.json</h2>\n<p>The user&#39;s own posts as an ActivityPub <code>OrderedCollection</code>, written a page at a time through a temporary file so that an account with years of posts never has to fit in memory</p>\n<h2 id=\"social-media-attachments-files-id-original-ext\">social/media_attachments/files/&lt;id&gt;/original.&lt;ext&gt;</h2>\n<p>The file of one attachment of one of those posts, in the layout Mastodon&#39;s own export uses. <code>&lt;id&gt;</code> is the attachment id the post carries</p>\n<h2 id=\"social-media-attachments-header-ext-avatar-ext\">social/media_attachments/header.&lt;ext&gt;, avatar.&lt;ext&gt;</h2>\n<p>The profile banner, and a profile picture where this app has one of its own. Named in <code>actor.json</code> as <code>headerFile</code> and <code>avatarFile</code></p>\n<p>Reads are paged everywhere (<code>SocialMigrator::PAGE</code>, 50 rows); the block and mute\nlists come from one capped query (<code>RELATIONS_LIMIT</code>, 5000), and reaching the cap\nis reported on the console rather than silently truncating. A follow whose\naccount this server never cached is left out of the CSV instead of being written\nas a bare actor URL, which no reader of the format accepts.</p>\n<p><strong>The files travel with the posts.</strong> As the outbox is walked, each attachment\nthat names a copy this instance stored is copied into the archive and its <code>url</code>\nis rewritten to that path — relative, because an absolute one names the server\nthe archive is leaving. The address it had here is kept beside it as\n<code>originalUrl</code>, so nothing the archive knew is lost and a reader that cannot use\nthe copy still knows where the picture was served from. The bytes go through\n<code>IExportDestination::addFileAsStream()</code> from the stored copy&#39;s own stream: a\ntwo-gigabyte video costs the export no more memory than a sentence does. An\nattachment this instance has no bytes of — a streamed PeerTube video, a copy a\nretention sweep removed — keeps the URL it had, which is all there ever was of\nit. The size estimate (<code>ISizeEstimationMigrator</code>) counts the media too, per kind\n(<code>SIZE_IMAGE</code>/<code>SIZE_AUDIO</code>/<code>SIZE_VIDEO</code>, from one grouped count in\n<code>CacheDocumentsRequest::countLocalCopiesByType()</code>): the table stores no file\nsize, and an estimate that left the files out was wrong by orders of magnitude\nfor any account with a video on it.</p>\n<h2 id=\"what-deliberately-does-not-travel\">What deliberately does not travel</h2>\n<ul>\n<li><strong>The actor&#39;s private key.</strong> It is the only secret that lets anything speak as\nthat account, ActivityPub has no revocation for it, and the app encrypts it at\nrest (<code>PrivateKeyCipher</code>, see Security above) precisely so that a copy of the\ndatabase is not enough to impersonate a local actor. An export archive is an\nordinary file the user downloads and keeps, so a plaintext key in it would\nundo that — and for nothing: an account imported elsewhere is a <em>new</em> actor\nwith a new id, and <code>AccountService::createActor()</code> gives it a fresh pair.\nIdentity continuity is carried by <code>alsoKnownAs</code> plus a <code>Move</code> from the old\nserver (<code>MigrationService::move()</code>), which is why the import records the old\nactor id as an alias. The public key is exported, because it is public and\nsays which actor this was.</li>\n<li><strong>Other people&#39;s posts.</strong> The local copies of remote statuses are a cache of\nsomebody else&#39;s content, re-fetched wherever they are needed.</li>\n<li><strong>Moderation decisions taken against the account</strong>, and reports. A suspension\ndeliberately outlives even the deletion of an actor (<code>PersonInterface::delete()</code>),\nso it must not be something a user can shed by exporting and re-importing.</li>\n<li><strong>Tokens, OAuth clients and client secrets</strong>, and the outbound request queue.\nA credential that survived a move would be one nobody can revoke.</li>\n<li><strong>Other people&#39;s media.</strong> Only the files of the user&#39;s own posts are copied,\nand only where this instance stored them. A streamed video is deliberately\nnever mirrored here (<code>Document::COPY_STREAMED</code>) and there is nothing to put in\nthe archive; the Nextcloud account&#39;s avatar is the account&#39;s rather than this\napp&#39;s, and core&#39;s own migrator carries it.</li>\n</ul>\n<h2 id=\"what-an-import-does\">What an import does</h2>\n<p>An import is safe on a server where the account already exists: the actor is\ntaken as found and only created when there is none\n(<code>AccountService::getActorFromUserId($uid, create: true)</code>), every write is\nidempotent, and nothing is ever deleted. A missing file is not a failure — an\narchive from an older version, or one assembled by hand, imports whatever it\ndoes carry, and an archive with no version for this migrator is skipped\nentirely (the migrator is not mandatory). An archive that carries a version but\nnone of the files above — the export of a user who never used this app — creates\nno account either: a Fediverse identity is something a user asks for.</p>\n<ul>\n<li>the profile — <code>locked</code>, <code>discoverable</code>/<code>indexable</code>, the fields and the bio —\ngoes back through <code>AccountService</code>, the same path the API uses. The <strong>display\nname</strong> does not: it belongs to the Nextcloud account, the core <code>account</code>\nmigrator carries it, and <code>AccountService</code> re-derives the actor&#39;s name from it.</li>\n<li>the old actor id is recorded in <code>alsoKnownAs</code>, so a <code>Move</code> from the old\naccount is accepted here. <code>movedTo</code> is <strong>not</strong> imported: it would point the\nnew account&#39;s own followers somewhere else.</li>\n<li>the follows are re-created through the ordinary follow path\n(<code>MigrationService::importFollows()</code>), one handle at a time, and a handle whose\nserver is unreachable is reported without stopping the rest.</li>\n<li>blocks and mutes are written straight to the relation table. Resolving a\nhandle may fetch the remote actor (a signed GET), but no <code>Block</code> is federated:\nthe account on the other end was already blocked, and was never told about the\nmove.</li>\n<li>bookmarks and favourites are re-marked on the posts this server already has\nand the account may read (looked up as the account). A post nobody here has\nseen is skipped rather than fetched from its origin, and a favourite is not\nre-federated as a <code>Like</code>.</li>\n<li>the posts in <code>outbox.json</code> are <strong>not</strong> replayed into the timeline. Their ids\nbelong to the server they were written on, the threads around them are not\nhere, and minting new ids would either publish years of posts to the Fediverse\nagain or fill the timeline with statuses no remote server can resolve.\nMastodon&#39;s own import does not restore statuses either.</li>\n<li>their <strong>files</strong> are, onto the posts this server does have: an attachment whose\nURL names a <code>media_attachments/…</code> path in the archive is stored through\n<code>DocumentService::storeLocalAttachment()</code> — which is the path the composer&#39;s\nown upload takes, so the type is sniffed from the bytes, anything\n<code>filterMimeTypes()</code> refuses is refused here too, and the metadata is stripped —\nand the post&#39;s stored copy of its attachments is re-pointed at it. Nothing is\ntranscoded: the file in the archive is the one that was stored here, already\nconverted and resized when it was first uploaded. Where the post&#39;s picture is\nstill here nothing happens; where the post itself is not here the file stays in\nthe archive rather than becoming a row nothing can show; and where the archive\nnames a file it does not hold, the attachment keeps the address it had, which\nis what <code>originalUrl</code> is for. This is the case of an archive read back after\nthe files were lost and the rows were not.</li>\n<li>the <strong>banner</strong> goes back through <code>BannerService::setFromTempFile()</code>, the path\nthat owns it, so the actor cache and the followers are told exactly as they are\nwhen it is set by hand. The <strong>avatar</strong> is the Nextcloud account&#39;s, so\n<code>AvatarService::restoreFromArchive()</code> decides: a picture the account already\nhas is never written over, and only an account still showing its generated\ninitials gets the one out of the archive — the order the migrators of an\naccount import run in is not this app&#39;s to depend on.</li>\n</ul>\n<p>So the only thing an import sends to other servers is a <code>Follow</code> per followed\naccount — which is the only way a follow can exist at all — plus the single\n<code>Update{Person}</code> that any bio change sends to the account&#39;s followers, of which\na freshly imported account has none. No <code>Delete</code>, no <code>Move</code>, no <code>Like</code>, no\n<code>Block</code>.</p>\n<hr>\n","toc":[{"id":"social-actor-json","text":"social/actor.json","level":2},{"id":"social-following-accounts-csv","text":"social/following_accounts.csv","level":2},{"id":"social-followers-csv","text":"social/followers.csv","level":2},{"id":"social-blocked-accounts-csv","text":"social/blocked_accounts.csv","level":2},{"id":"social-muted-accounts-csv","text":"social/muted_accounts.csv","level":2},{"id":"social-bookmarks-csv","text":"social/bookmarks.csv","level":2},{"id":"social-likes-csv","text":"social/likes.csv","level":2},{"id":"social-interests-json","text":"social/interests.json","level":2},{"id":"social-outbox-json","text":"social/outbox.json","level":2},{"id":"social-media-attachments-files-id-original-ext","text":"social/media_attachments/files/<id>/original.<ext>","level":2},{"id":"social-media-attachments-header-ext-avatar-ext","text":"social/media_attachments/header.<ext>, avatar.<ext>","level":2},{"id":"what-deliberately-does-not-travel","text":"What deliberately does not travel","level":2},{"id":"what-an-import-does","text":"What an import does","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"account-export-and-import","manual":false,"prev":{"path":"/docs/architecture-events-this-app-publishes","title":"Events this app publishes"},"next":{"path":"/docs/architecture-external-users","title":"External users"},"parent":null},{"slug":"architecture-external-users","path":"/docs/architecture-external-users","title":"External users","description":"Internal Nextcloud users use Aloha Social as they always have. An administrator can also open Aloha Social to a limited number of external users: people without a Nextcloud account who…","group":"architecture","html":"<p>Internal Nextcloud users use Aloha Social as they always have. An administrator can\nalso open Aloha Social to a limited number of <strong>external users</strong>: people without a\nNextcloud account who register one themselves, log in through the normal\nlogin form and reach nothing but Aloha Social. The settings are on the Aloha Social\nsettings page, in the External users cards, and are all off by default.</p>\n<h2 id=\"they-are-real-nextcloud-users\">They are real Nextcloud users</h2>\n<p> <code>External\\ExternalUserBackend</code> is a user\nbackend of this app, holding the logins in <code>social_ext_user</code>. Because they are\nordinary users on it, the login form, sessions, remember-me, password reset,\npassword confirmation, two-factor authentication, the Users page (disable,\ndelete, the backend column says &quot;Aloha Social&quot;) and the Mastodon OAuth flow all work\nunchanged. The backend does not implement <code>ICreateUserBackend</code>, so nobody\ncreates one from the Users page or <code>occ user:add</code>; they are made by\n<code>ExternalUserService::createAccount()</code> only. The user id is the handle: lower\ncase letters, digits and underscore, with dot and dash inside, at most 64\ncharacters, not reserved (a built-in list and the administrator&#39;s), not\nanybody&#39;s user id on any backend, not held by an Aloha Social actor, deleted ones in\nretention included, and not reserved by a pending registration.</p>\n<h2 id=\"externalexternalgroupbackend\">External\\ExternalGroupBackend</h2>\n<p> exposes one read-only group, <code>social-external</code>,\nwhose members are exactly the external users. It is hidden from the share\ndialog. Core&#39;s mandatory two-factor setting is group-based, and an\nadministrator who restricts Aloha Social to groups names the externals with it.</p>\n<h2 id=\"loaded-before-login\">Loaded before login</h2>\n<p> <code>appinfo/info.xml</code> declares the app\n<code>extended_authentication</code>, which every entry point loads before it\nauthenticates anybody — <code>index.php</code>, <code>ocs/</code>, <code>remote.php</code> and <code>public.php</code> —\nand which, unlike <code>authentication</code>, still lets Aloha Social be restricted to groups.\n<code>Application::boot()</code> registers both backends there. Where Aloha Social is\nrestricted to groups, switching external users on adds <code>social-external</code> to\nthem, and the settings card says when the restriction leaves them out.</p>\n<h2 id=\"registration\">Registration</h2>\n<p> (<code>ExternalSignupService</code>, <code>SignupController</code>, the\n<code>social-signup</code> entry). The login page shows a &quot;Create an account&quot; button,\nthrough <code>SignupLoginProvider</code>, while there is room and registration is not by\ninvitation only. The mode decides who is admitted: <code>open</code> admits anybody,\n<code>invite</code> only the holder of an invitation link, <code>approval</code> puts the\nregistration in a queue on the settings page. A valid invitation admits its\nholder in every mode, approval included, and a use is counted when the form is\nsent. With email confirmation on, which is the default, the account is made\nonly when the link in the confirmation email is followed, within 24 hours.\nThe form asks for the handle, the email, a password (8 characters at least,\nand the instance&#39;s password policy), acceptance of the server rules and, when\na minimum age is set, confirmation of it. It carries a honeypot field and two\nrate limits, 10 an hour per address on the route and 5 registrations an hour\nper address in all, and it stops taking registrations while 1000 are\nwaiting. A pending registration reserves its handle and its email; the\nunconfirmed ones are forgotten by <code>Cron\\ExternalSignups</code> after a day. Email\ndomains on the access block list are refused, as they are for every account.</p>\n<h2 id=\"externaluserservice-createaccount\">ExternalUserService::createAccount()</h2>\n<p> takes a lock, then checks the room left\nunder the maximum, the handle and the email again, because the person may have\nregistered while there was room. It writes the login, dispatches\n<code>BeforeUserCreatedEvent</code> and <code>UserCreatedEvent</code> itself, sets the email, sets\nevery account property to at most <code>v2-local</code> (display name, email and avatar)\nor <code>v2-private</code> (everything else) and turns the core profile off, so nothing\nabout the person is published to trusted servers or the lookup server, makes\nAloha Social their default app, and creates the Aloha Social actor. When any of that\nfails, the user is deleted again. <code>ExternalFirstLoginListener</code> stops the\nfirst-login event for external users before other apps see it, so Files does\nnot copy the skeleton into their home and no default calendar is made.</p>\n<h2 id=\"what-they-reach\">What they reach</h2>\n<p> (<code>ExternalScope</code>, <code>Middleware\\ExternalScopeMiddleware</code>).\nThe middleware is registered as a <strong>global</strong> middleware, so it runs before the\ncontrollers of every app and of core, and it refuses whatever <code>ExternalScope</code>\ndoes not allow: a page is answered with a redirect to Aloha Social, anything else\nwith 403. Allowed are this app, theming, notifications and the two-factor\nproviders; logging in and out, two-factor challenges, password reset and\nconfirmation; avatars and the assets every page loads; the core capabilities;\ntheir own user status; and the personal settings sections for their account\ndetails, language, security, appearance and notifications, whose navigation is\ncut down to those sections. Everything else is refused, including every app\ninstalled later. Core&#39;s profile page, <code>/u/{userId}</code>, is sent to the Aloha Social\nprofile for everybody when it is an external user&#39;s, and for an external user\nwhoever&#39;s it is. The app menu, unified search, the contacts menu and the\naccount menu entries that lead elsewhere are taken off the page by\n<code>css/external-scope.css</code> (<code>ExternalPageListener</code>); on a server that dispatches\n<code>NavigationEntriesFilterEvent</code>, <code>ExternalNavigationListener</code> also removes the\nnavigation entries themselves.</p>\n<p>WebDAV is not a controller. <code>External\\ExternalDavGuard</code> runs in\n<code>Application::boot()</code>, which <code>remote.php</code> calls right before it hands the\nrequest to the DAV server, and ends a request with 403 when its session or its\nHTTP basic credentials are an external user&#39;s: this covers the legacy\n<code>/remote.php/caldav</code> and <code>/remote.php/carddav</code> endpoints, which have no hook\nof their own and would list the system address book. <code>ExternalDavListener</code>\nadds a <code>beforeMethod:*</code> handler to the DAV server of <code>/remote.php/dav</code> and\n<code>/remote.php/webdav</code> at priority 15, after Sabre&#39;s authentication, which\nrefuses an external user whatever the credential was. Nextcloud&#39;s desktop and\nmobile clients, Talk and every CalDAV and CardDAV client are therefore\nrefused; Mastodon apps work through the OAuth flow of this app.</p>\n<h2 id=\"who-sees-them\">Who sees them</h2>\n<p> Inside Aloha Social they are local accounts like any other.\nOutside it they are invisible: <code>ExternalCollaboratorPlugin</code>, a collaborator\nsearch plugin for user shares, removes them from every people search that\ngoes through core — the share dialog, mentions, Talk;\n<code>ExternalUserStatusListener</code> removes them from the user lists\n<code>UserEnumerationFilterEvent</code> filters; <code>ExternalAddressBookListener</code> deletes\ntheir card from the system address book as soon as it is written (the card is\nnamed <code>Social:&lt;uid&gt;.vcf</code>), which keeps them out of the contacts menu and of\nevery CardDAV client. Administrators still see them on the Users page.</p>\n<h2 id=\"quota\">Quota</h2>\n<p> <code>ExternalMediaQuota</code> is one number for every external user, in MB,\nchecked in <code>CacheDocumentService::filterQuota()</code> — the one place every local\nupload passes — against the stored size of every local document the account\nholds. The video quota every account has still applies on top. Media that\nfederated in is not charged to anybody. The person sees what they use on\ntheir Aloha Social settings page (<code>serverData.externalMedia</code>). Aloha Social stores media in\napp data, so the core per-user quota is not involved.</p>\n<h2 id=\"two-factor-authentication\">Two-factor authentication</h2>\n<p> <code>ExternalTwoFactorService</code> reads and writes\ncore&#39;s mandatory two-factor setting for <code>social-external</code> and keeps its\nshape: enforcement for a list of groups gains or loses the group, enforcement\nfor everybody gains or loses it as an excluded group, and taking the last\ngroup off a list turns enforcement off rather than leaving an empty list,\nwhich core would read as everybody.</p>\n<h2 id=\"promotion\">Promotion</h2>\n<p> <code>ExternalUserService::promote()</code> moves an external user to\nNextcloud&#39;s database backend with the same user id and password hash, in one\ntransaction, and removes the login here. Their two-factor setup, preferences\nand Aloha Social account are keyed by the user id and stay. <code>Cron\\ExternalPromoted</code>\nwrites their system address book card in a later request, which sees them on\ntheir new backend.</p>\n<p><strong>Removal.</strong> Deleting an external user goes through <code>IUserManager</code>, so the\nAloha Social account goes the way it goes for any deleted user. <code>occ social:reset</code>\nrefuses to run while external users exist, because emptying <code>social_ext_user</code>\nwould leave Nextcloud users nobody can log in as.</p>\n<hr>\n","toc":[{"id":"they-are-real-nextcloud-users","text":"They are real Nextcloud users","level":2},{"id":"externalexternalgroupbackend","text":"External\\ExternalGroupBackend","level":2},{"id":"loaded-before-login","text":"Loaded before login","level":2},{"id":"registration","text":"Registration","level":2},{"id":"externaluserservice-createaccount","text":"ExternalUserService::createAccount()","level":2},{"id":"what-they-reach","text":"What they reach","level":2},{"id":"who-sees-them","text":"Who sees them","level":2},{"id":"quota","text":"Quota","level":2},{"id":"two-factor-authentication","text":"Two-factor authentication","level":2},{"id":"promotion","text":"Promotion","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"external-users","manual":false,"prev":{"path":"/docs/architecture-account-export-and-import","title":"Account export and import"},"next":{"path":"/docs/architecture-security","title":"Security"},"parent":null},{"slug":"architecture-security","path":"/docs/architecture-security","title":"Security","description":"a signature on a GET is verified by SignatureService::checkGetRequest() and resolved to the account behind it by AuthorizedFetchService::reader(), so what this instance serves can depend…","group":"architecture","html":"<p><strong>What is enforced</strong></p>\n<h2 id=\"authorized-fetch-inbound\">Authorized fetch (inbound)</h2>\n<p>a signature on a <strong>GET</strong> is verified by <code>SignatureService::checkGetRequest()</code> and resolved to the account behind it by <code>AuthorizedFetchService::reader()</code>, so what this instance serves can depend on who asked: <code>displayPost()</code> reads the object as that remote account, which is what lets a followers-only post reach the people who follow it from another server. Before this, verification ran on inbox POSTs only, every GET served what an anonymous reader gets, and a follower elsewhere saw a profile with nothing on it — safe, and also wrong. A GET has no body, so the digest and content-length checks that bind one are not asked for; everything else is the POST path&#39;s, including the requirement that <code>(request-target)</code>, <code>host</code> and <code>date</code> be inside the signature and the replay window on the date. An <strong>unsigned</strong> GET is not an error — it is the ordinary case, and it gets what it always got. A signature that is present and <em>fails</em> leaves the reader anonymous rather than answering 401: a peer whose clock has drifted, or whose key cannot be fetched at that moment, should still see the public object the route exists to serve. A signer on an instance the access list excludes, and a <em>local</em> actor&#39;s key signing an inbound fetch (this instance talking to itself, or a replay of one of our own requests), are both refused as readers. <strong>Secure mode</strong> — <code>secure_mode</code>, off by default — turns the other half on: an unsigned ActivityPub GET is a 401. It is off by default because switching it on makes this instance invisible to every peer that does not sign, which is a decision about who to federate with rather than something to arrive at by upgrading</p>\n<h2 id=\"http-signatures-on-outbound-requests\">HTTP Signatures on outbound requests</h2>\n<p>every queued delivery is signed with the sending actor&#39;s RSA private key over <code>(request-target)</code>, <code>content-length</code>, <code>date</code>, <code>host</code> and <code>digest</code>. Outbound ActivityPub <strong>GET</strong>s are signed too, by <code>HttpSignatureService::signFetch()</code>, over <code>(request-target) host date</code> — there is no body to digest. Without this, any peer running Mastodon&#39;s authorized-fetch or GoToSocial&#39;s secure mode answers 401 to every actor, object and collection fetch, which reads as &quot;user not found&quot; when following and as threads that stop at the first remote reply. The signing identity is one fixed local actor rather than whoever is reading, so a remote instance is not told which of our accounts read which of its posts; a peer that rejects a signed GET is retried once unsigned, so nobody becomes less reachable than before. WebFinger, host-meta and NodeInfo stay unsigned</p>\n<h2 id=\"http-signature-verification-on-inbound-requests\">HTTP Signature verification on inbound requests</h2>\n<p><code>SignatureService::checkRequest()</code> requires <code>(request-target)</code>, <code>host</code>, <code>date</code> and <code>digest</code> to all be within the signed header set, so the signature binds the body and cannot be replayed against another host; it rejects a missing <code>date</code>, one that is not an RFC 7231 IMF-fixdate (<code>SignatureService::parseHttpDate()</code>: a free-form parse took <code>now</code> or <code>+1 hour</code>, which never age out — <code>UTC</code> for <code>GMT</code> and a one-digit day are still read), one older than <code>DATE_PAST</code> (12 h) or more than <code>DATE_FUTURE</code> (1 h) ahead — Mastodon&#39;s bounds, so a peer with a drifting clock or a slow queue is not refused for good — and, since a window that wide would let a captured delivery be sent again, a request whose exact signature was already taken in, which <code>ActivityPubController</code> answers 200 without processing (<code>isReplayed()</code>; <code>rememberRequest()</code> records it in <code>DurableCache</code> once it has been taken in, so identical bytes resent after a failure are still processed, and keeps it for the window&#39;s whole width and a minute (<code>REPLAY_MARGIN</code>): a request dated an hour ahead is accepted until thirteen hours after it arrived, and is still known on that last second; RFC 9421 <code>created</code> is held to the same window and remembered the same way); a <code>content-length</code> that disagrees with the body <em>when the header is sent</em> (a chunked sender omits it, and refusing those outright cost interoperability for nothing), and a <code>digest</code> that does not match. <code>Digest</code> and <code>Content-Digest</code> are parsed rather than byte-compared, so a lowercase algorithm token, a multi-value digest or an RFC 9530 header is accepted as long as one algorithm we can compute matches. A signature algorithm that is neither <code>hs2019</code> nor absent is refused by name instead of being assumed to be sha256, which used to fail an Ed25519 key with a misleading message. The <code>host</code> verified is the configured one as a peer addresses it, <code>ConfigService::getCloudAuthority()</code> — with the port when the cloud URL names a non-default one, since that is the <code>Host</code> a peer connects to and signs. When the signed <code>host</code> differs from it — which fails every inbound delivery on a multi-domain install or one reached on another port than it is configured with — the log names both. A <code>keyId</code> without a fragment that is not an actor&#39;s own id — GoToSocial publishes every key at <code>…/users/name/main-key</code> and answers it with a stub of the actor — is resolved by <code>CacheActorService::getFromKeyId()</code>: the stub&#39;s <code>publicKey.owner</code> (or a bare key document&#39;s <code>owner</code> or <code>controller</code>) names the actor, which has to be on the <code>keyId</code>&#39;s host, has to be served at exactly that id, and has to list this exact <code>keyId</code> among its own keys (<code>publicKey</code>, one of several, or <code>assertionMethod</code>/<code>verificationMethod</code>, none of them naming another owner) — a stub with no owner, an owner elsewhere, or one whose document does not claim the key is refused, and nothing about it is remembered. The signature is verified with the key that actor&#39;s document publishes. The owner found is remembered (<code>DurableCache</code>, <code>KEY_HOLDER_NAMESPACE</code>, 30 days), so a known GoToSocial account&#39;s delivery is a database read, and it is the signer the activity has to speak for; until this, every delivery from GoToSocial was refused with a 401. A signature that does not verify, or whose key cannot be retrieved, is refused by <code>checkRequest()</code> itself (it throws), rather than returning an empty origin for a later check to catch</p>\n<h2 id=\"inbound-inbox-deliveries-are-rate-limited\">Inbound inbox deliveries are rate-limited</h2>\n<p><code>InboxLimiter</code> caps deliveries in two places (<code>inbox_throttle</code> app setting, default 300 per minute, 0 disables). Before any signature work, <code>assertAllowed()</code> spends a bucket keyed on the <strong>source address</strong>, which is the one thing about an unauthenticated request the sender cannot choose. After the signature has been verified, <code>assertOriginAllowed()</code> spends a second, looser bucket (<code>HOST_LIMIT_FACTOR</code>, 4×) keyed on the <strong>verified origin</strong>, which bounds what one instance can send from however many addresses. The second bucket used to be spent up front on the host named in the sender&#39;s own unverified <code>keyId</code> — which meant four cheap addresses could fill a large instance&#39;s bucket every minute and have its genuine deliveries answered 429, cutting this server off from it. Only a peer that can sign for a host now spends that host&#39;s budget</p>\n<h2 id=\"a-delivery-is-bounded-in-size\">A delivery is bounded in size</h2>\n<p><code>InboxLimiter::readBody()</code> refuses a body over <code>MAX_BODY</code> (1 MiB) with <code>413</code>, by the declared <code>Content-Length</code> where there is one and by a bounded read where there is not. Both inboxes are public and unauthenticated, and the <code>Digest</code> is hashed over the body <em>before</em> the signature is verified — a signature over a body nobody has hashed proves nothing about the body — so until this the only ceiling was PHP&#39;s <code>post_max_size</code>, which a Nextcloud sets to hundreds of megabytes so that file uploads work. Anyone at all could hand every worker in the pool that much to allocate and SHA-256; the rate limit bounds requests, not bytes, and one request was enough to hold a worker for seconds. An activity is a few kilobytes, and a sender with more to say has <code>Collection</code> pages to say it in</p>\n<h2 id=\"ld-signatures-are-bounded-in-time-and-replay-checked\">LD signatures are bounded in time and replay-checked</h2>\n<p><code>checkObject()</code> refuses a <code>created</code> that is not an RFC 3339 date-time (<code>parseObjectDate()</code>), and a signature whose <code>created</code> lies more than <code>LD_WINDOW</code> (24 h) from now, and remembers accepted signatures in <code>DurableCache</code> for twice the window and a minute (<code>REPLAY_MARGIN</code>) — a <code>created</code> a day ahead is inside the window until two days after it was accepted — so a captured activity cannot be re-POSTed indefinitely by an instance that once saw it</p>\n<h2 id=\"linked-data-signatures\">Linked Data Signatures</h2>\n<p>outgoing Create, Update, Delete, Like, Announce and Undo carry an RsaSignature2017 signature; incoming ones are verified by <code>SignatureService::checkObject()</code>, which also retries against a refreshed public key. Follow and Accept are not LD-signed</p>\n<h2 id=\"instance-access-control\">Instance access control</h2>\n<p><code>FediverseService::authorized()</code> is checked on both inbox routes and on every outgoing <code>CurlService</code> request. On an inbound request it is asked about the host of the <code>keyId</code> (and, for a Linked Data signature, of the actor) inside <code>SignatureService</code> <strong>before</strong> the signing key is looked up or fetched, so a refused instance never makes this one do outbound work on its behalf; the controllers ask again about the origin the activity is finally stored under. It reads one app config value, <code>access_type</code>, which is either <code>all_but</code> (the default: everything is allowed unless the host is in the list) or <code>none_but</code> (only listed hosts, plus the local host, are allowed), together with a single host list in <code>access_list</code>. Hosts are compared case-insensitively and without the trailing dot of the absolute form, and the two modes read the list differently on purpose: a deny-list entry covers the domain and everything under it (<code>isListed()</code>), because blocking <code>evil.test</code> while <code>www.evil.test</code> walks straight back in is not a block; an allow-list entry matches exactly (<code>isExactlyListed()</code>), because a subdomain of an allowed domain is a different instance and whoever runs the parent was never asked. <code>occ social:fediverse</code> manages both</p>\n<h2 id=\"outbound-requests-cannot-be-steered-at-the-local-network\">Outbound requests cannot be steered at the local network</h2>\n<p> A host that is, or resolves to, anything but a globally reachable unicast address — private, loopback, link-local, shared (100.64/10), benchmarking, documentation, multicast or otherwise special-purpose, or an IPv6 address wrapping one of those (IPv4-mapped, SIIT, NAT64, 6to4) — is refused before anything is sent, unless the instance has set <code>allow_local_remote_servers</code> (<code>lib/Security/RemoteAddress.php</code>; a name that resolves to nothing is refused too — failing closed). The host is resolved once, every address of the answer is checked, and the request is <strong>pinned to exactly that set</strong> (<code>CURLOPT_RESOLVE</code>, <code>CurlService::pinReachable()</code>), so the client cannot be answered differently by a second lookup; the answer is remembered for a minute per process. <code>CurlService</code> follows redirects itself and resolves, checks and pins <strong>every hop</strong> afresh, with the federation access list applied to each; the server&#39;s own client enforces its local-address rule on top. Only <code>http</code>/<code>https</code> URLs are ever requested — the one asked for, a host-meta&#39;s WebFinger template and every redirect — so a <code>file://</code> or <code>gopher://</code> URL cannot be reached. The banner-by-URL endpoint applies the same rules and a size ceiling before fetching</p>\n<h2 id=\"json-ld-contexts-are-served-only-from-the-copies-shipped-in-context\">JSON-LD contexts are served only from the copies shipped in context/</h2>\n<p> Signature normalisation never resolves a document&#39;s <code>@context</code> over the network, so a remote activity cannot make the server open an arbitrary URL and cannot substitute the bytes a signature is computed over; an unrecognised context makes the LD signature unverifiable rather than triggering a fetch</p>\n<h2 id=\"html-sanitisation\">HTML sanitisation</h2>\n<p>remote HTML reaches local timelines, so <code>ACore</code> runs <code>lib/Security/HtmlSanitizer.php</code> over every <code>AS_CONTENT</code> field it imports or reads back from the database (a post&#39;s <code>content</code> on <code>Stream::import()</code> as well, so an object exported before it is stored is already clean), and strips tags from string, username and account fields. On PHP 8.4 and later the sanitiser parses and serialises with <code>Dom\\HTMLDocument</code>, the HTML5 parser a browser uses; on 8.3 it falls back to libxml&#39;s HTML4 <code>DOMDocument</code> and reads its own output back until it stops changing, because a tree libxml builds differently from the browser is where mutation XSS starts. A relative <code>href</code> or <code>cite</code> is resolved against the object&#39;s own id — the browser would resolve it against this server, so <code>href=&quot;/logout&quot;</code> in a remote post pointed here — a protocol-relative one gets <code>https:</code>, and one with no http(s) id to resolve against loses its <code>href</code>. The frontend sanitises again with DOMPurify in <code>src/utils/sanitizeHtml.js</code>, with the same element, scheme and <code>class</code> allowlists as the server — a bio rendered with <code>v-html</code> could otherwise borrow Nextcloud&#39;s own UI classes — and <code>sanitizeHtml.test.js</code> reads the PHP lists to keep the two in step</p>\n<h2 id=\"an-attachment-cannot-write-over-a-document-it-does-not-own\">An attachment cannot write over a document it does not own</h2>\n<p> A remote attachment keeps the id it arrives with, and <code>DocumentInterface::save()</code> updates the stored row of that id -- before the inbox has held the signer to the activity, since attachments are stored while the post is imported. So <code>mayRewrite()</code> lets a row be rewritten from federation input only by the post it hangs off (a redelivery, an <code>Update</code>) or by the server whose host its id names, re-using it on another of its own posts. A row of this instance&#39;s own is never rewritten from outside: one a local account owns (<code>account</code> set), one hanging off a local post, or one whose id is on this host. An attachment that names such a row is stored as a new document under a fresh <code>/documents/g/</code> id instead, and the row it named stays as it was; the url-and-parent lookup for an attachment without an id is held to the same rule.</p>\n<h2 id=\"actor-private-keys-are-encrypted-at-rest\">Actor private keys are encrypted at rest</h2>\n<p><code>social_actor.private_key</code> holds the PEM encrypted with the instance secret (<code>ICrypto</code>, via <code>PrivateKeyCipher</code>), so a database dump alone is not enough to impersonate a local actor — it also takes the <code>secret</code> from <code>config.php</code>. Rows written before encryption existed (recognisable by their <code>-----BEGIN</code> prefix) are still readable and are rewritten once by the <code>EncryptPrivateKeys</code> repair step on upgrade</p>\n<h2 id=\"client-secrets-authorization-codes-and-access-tokens-are-stored-hashed\">Client secrets, authorization codes and access tokens are stored hashed</h2>\n<p><code>sha256:&lt;hex&gt;</code> digests (<code>SecretHasher</code>). A stored value without the prefix is not accepted at all — migration <code>Version1000Date20261008000100</code> hashed the last legacy plaintext rows, or deleted the ones it could not write — and a presented secret that already carries the prefix is refused, so the stored digest is not itself a working credential: offering it for lookup made a database dump, a backup or a read-only SQL flaw hand out usable tokens, which is the one thing hashing them is for</p>\n<h2 id=\"self-signed-certificates\">Self-signed certificates</h2>\n<p>TLS peer verification is skipped only when the <code>allow_self_signed</code> app config value is <code>1</code></p>\n<h2 id=\"for-you-learns-only-from-what-the-reader-may-read-and-shows-it-to-nobody\">For you learns only from what the reader may read, and shows it to nobody else</h2>\n<p> A signal names a post by id and nothing else; the hashtags are read from the stored post through the same visibility, block and mute filter the timelines use (<code>StreamRequest::getVisibleByNids()</code>), because the interests it produces are shown back on the reader&#39;s settings page — a signal naming a stranger&#39;s followers-only post would otherwise put that post&#39;s hashtags there. No raw signal is kept, nothing is federated, and every route is the viewer&#39;s own. Learning is <strong>on by default</strong> for a reader who has not chosen (<code>interests_default</code>), with a one-time notice in the web interface; an administrator for whom profiling from reading needs consent turns the default off</p>\n<h2 id=\"external-users-reach-aloha-social-only\">External users reach Aloha Social only</h2>\n<p>every controller of every app is checked against <code>ExternalScope</code>&#39;s allowlist by a global middleware before it runs, and WebDAV by <code>ExternalDavGuard</code> and <code>ExternalDavListener</code>; hiding the menus is not what keeps them out. See <a href=\"/docs/architecture-external-users#external-users\">External users</a>.</p>\n<p><strong>Known gaps — these are real and deliberate to record</strong></p>\n<ul>\n<li><strong>The federation endpoints are readable by anyone.</strong> <code>ActivityPubController::actor()</code>, <code>actorAlias()</code>, <code>outbox()</code>, <code>followers()</code>, <code>following()</code> and <code>displayPost()</code> all carry <code>#[PublicPage]</code> with <code>#[NoCSRFRequired]</code>. This instance does not <em>require</em> a signed fetch of its own collections, so any anonymous caller can read a local actor&#39;s profile, outbox, follower and following collections and individual posts. (Outbound fetches this app makes <em>are</em> signed — see above; the two directions are independent.)</li>\n<li><strong>The older dual blacklist/whitelist implementation in <code>FediverseService</code> is commented out</strong>. What remains is the single-list <code>access_type</code>/<code>access_list</code> mechanism described above</li>\n<li><strong><code>FediverseService::getKnownAddresses()</code> returns an empty array</strong> unconditionally</li>\n<li><strong>The base URL is set once.</strong> <code>ConfigService::setCloudUrl()</code> will overwrite it, but stored actor and stream ids embed the old URL, so changing it in practice requires <code>occ social:reset</code></li>\n</ul>\n<hr>\n","toc":[{"id":"authorized-fetch-inbound","text":"Authorized fetch (inbound)","level":2},{"id":"http-signatures-on-outbound-requests","text":"HTTP Signatures on outbound requests","level":2},{"id":"http-signature-verification-on-inbound-requests","text":"HTTP Signature verification on inbound requests","level":2},{"id":"inbound-inbox-deliveries-are-rate-limited","text":"Inbound inbox deliveries are rate-limited","level":2},{"id":"a-delivery-is-bounded-in-size","text":"A delivery is bounded in size","level":2},{"id":"ld-signatures-are-bounded-in-time-and-replay-checked","text":"LD signatures are bounded in time and replay-checked","level":2},{"id":"linked-data-signatures","text":"Linked Data Signatures","level":2},{"id":"instance-access-control","text":"Instance access control","level":2},{"id":"outbound-requests-cannot-be-steered-at-the-local-network","text":"Outbound requests cannot be steered at the local network","level":2},{"id":"json-ld-contexts-are-served-only-from-the-copies-shipped-in-context","text":"JSON-LD contexts are served only from the copies shipped in context/","level":2},{"id":"html-sanitisation","text":"HTML sanitisation","level":2},{"id":"an-attachment-cannot-write-over-a-document-it-does-not-own","text":"An attachment cannot write over a document it does not own","level":2},{"id":"actor-private-keys-are-encrypted-at-rest","text":"Actor private keys are encrypted at rest","level":2},{"id":"client-secrets-authorization-codes-and-access-tokens-are-stored-hashed","text":"Client secrets, authorization codes and access tokens are stored hashed","level":2},{"id":"self-signed-certificates","text":"Self-signed certificates","level":2},{"id":"for-you-learns-only-from-what-the-reader-may-read-and-shows-it-to-nobody","text":"For you learns only from what the reader may read, and shows it to nobody else","level":2},{"id":"external-users-reach-aloha-social-only","text":"External users reach Aloha Social only","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"security","manual":false,"prev":{"path":"/docs/architecture-external-users","title":"External users"},"next":{"path":"/docs/architecture-supporting-two-nextcloud-versions","title":"Supporting two Nextcloud versions"},"parent":null},{"slug":"architecture-supporting-two-nextcloud-versions","path":"/docs/architecture-supporting-two-nextcloud-versions","title":"Supporting two Nextcloud versions","description":"appinfo/info.xml claims 35 and 36, and both are meant, so a change has to hold on either.","group":"architecture","html":"<p><code>appinfo/info.xml</code> claims 35 and 36, and both are meant, so a change has to\nhold on either.</p>\n<ul>\n<li><strong>Analysis runs against the newer one.</strong> <code>nextcloud/ocp</code> is a dev dependency\npinned to <code>dev-master</code>, which tracks the unreleased server — 36 until it\nbranches off as <code>stable36</code>. Psalm therefore sees the API the app will meet\nnext, not the one it met last.</li>\n<li><strong>The unit suite runs against whichever OCP is installed.</strong> It is standalone:\n<code>tests/bootstrap.php</code> loads the interfaces from that package rather than\nbooting a server. Where the two versions differ in a way a test can see, the\ntest asks rather than assumes — <code>ApiControllerTest::userFolderMock()</code> is the\nexample, because 36 narrowed <code>IRootFolder::getUserFolder()</code> from <code>Folder</code> to\n<code>IUserFolder</code> and PHPUnit checks a stubbed return value against the declared\ntype.</li>\n<li><strong>CI runs both servers.</strong> The version matrix is derived from <code>info.xml</code>, so\nthe nightly PHPUnit run installs the app on each supported server and runs\nthe integration suite there (a pull request runs the newest stable server\nand, for coverage, master), and the nightly browser tests run on both.</li>\n<li><strong>Deprecations are treated as breakage.</strong> 36 logs\n<code>Calling IQueryBuilder::orX without parameters is deprecated and will throw soon</code>; the conditions that are assembled in a loop (<code>limitToQueueDue()</code>,\n<code>limitToSyncDue()</code>, the trend windows) build their parts into an array and\npass them in one call. <code>tests/Db/FakeExpressions.php</code> refuses an empty\ncomposite outright, so the old shape fails the suite.</li>\n</ul>\n<hr>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"supporting-two-nextcloud-versions","manual":false,"prev":{"path":"/docs/architecture-security","title":"Security"},"next":{"path":"/docs/architecture-keeping-this-document-in-sync","title":"Keeping this document in sync"},"parent":null},{"slug":"architecture-keeping-this-document-in-sync","path":"/docs/architecture-keeping-this-document-in-sync","title":"Keeping this document in sync","description":"This file, docs/API.md and docs/OCC-Commands.md describe the current implementation. They must be updated in the same change as the code they describe.","group":"architecture","html":"<p>This file, <code>docs/API.md</code> and <code>docs/OCC-Commands.md</code> describe the current implementation. They must be updated in the same change as the code they describe.</p>\n<p><code>tests/DocumentationTest.php</code> mechanically enforces the parts that can be checked, in both directions where that is possible:</p>\n<ul>\n<li>the registered occ commands, <strong>and every option and argument each of them declares</strong> — a documented flag that does not exist, and an existing flag nobody documented, both fail;</li>\n<li>the HTTP routes the app registers — the <code>#[FrontpageRoute]</code> attributes on the controllers, read by reflection the way the server reads them, plus what is left in <code>appinfo/routes.php</code> — against the route tables of <code>docs/API.md</code>;</li>\n<li>the repair steps of <code>appinfo/info.xml</code> against the integration table above;</li>\n<li>the tables declared in <code>CoreRequestBuilder</code> against the schema table above;</li>\n<li>the supported Nextcloud and PHP version ranges, and the app version stated at the top of this file, against <code>appinfo/info.xml</code>;</li>\n<li>two claims of <em>absence</em>, which is the direction the rest of it is blind in: a sentence saying there is no <code>/some/route</code> must be true, and a symbol the docs call &quot;commented out&quot; may not be called by live code. The false claim that key-pair rotation was unavailable, published six lines after the flag that performs it, is what these were written for.</li>\n</ul>\n<p>Everything else is on the author of the change. In particular nothing can check a paragraph of prose against the behaviour it describes, so a feature described in words the &quot;not implemented&quot; guard does not recognise, or a mechanism described plausibly and wrongly, still gets through.</p>\n<h2 id=\"remote-outbox-reference-imports-and-reply-edits\">Remote outbox reference imports and reply edits</h2>\n<p><code>RemoteOutboxPageReader::resolveEntry()</code> resolves URI-only collection entries and\nreferenced <code>Create</code> / <code>Update</code> objects on the actor origin. The per-page budget is\nsix reference requests with a three-second request timeout. The caller advances\nits cursor only past consumed entries; budget exhaustion leaves the pending entry\nfor the continuation. Failed requests are isolated, with the first page eligible\nfor a later fresh profile refresh. A remote object must return the exact requested\nID. Embedded foreign boost content is replaced with its object ID before parsing:\n<code>AnnounceInterface</code> verifies the boosting activity and its normal cache queue\nretrieves the original post. Existing visibility restrictions and duplicate-boost\nhandling remain in that handler.</p>\n<p>For native ATProto post replacements, <code>WriteService</code> maps changed reply references\ninto <code>PostService::editPost()</code>. The service checks readability, blocking and reply\ngates, rejects audience widening and cycles, and resets the old conversation and\napproval state. <code>StreamRequest::update()</code> writes local parent columns alongside\nthe source snapshot; both parent counts are refreshed before the repository\nbatch commits. This uses the same conditional-write lock as other post changes.</p>\n<h2 id=\"public-profile-navigation-preferences\">Public profile navigation preferences</h2>\n<p><code>Model\\ProfileLayout</code> validates the public default and visible tabs. <code>AccountService</code>\nreads and writes the existing per-user <code>profile_layout</code> config and rebuilds the\nactor cache; no new permission store or content query is introduced. <code>Person</code>\nexports the selection through the local account API and the optional native\nActivityPub presentation extension. <code>LocalController::accountProfileLayout()</code>\nrequires the current Nextcloud account and CSRF protection. Invalid defaults\nreturn 422. The parent Profile view supplies the same preference to its existing\nchild views and resolves unspecified entry URLs with <code>router.replace</code>; explicit\ntab links remain authoritative. Public page state carries the configured cloud\naddress without running signed-in setup, and local public lookups use bare\nusernames rather than generated remote handles. Guest views do not use private\nread-marker endpoints.</p>\n","toc":[{"id":"remote-outbox-reference-imports-and-reply-edits","text":"Remote outbox reference imports and reply edits","level":2},{"id":"public-profile-navigation-preferences","text":"Public profile navigation preferences","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Architecture.md","sections":null,"anchor":"keeping-this-document-in-sync","manual":false,"prev":{"path":"/docs/architecture-supporting-two-nextcloud-versions","title":"Supporting two Nextcloud versions"},"next":null,"parent":null},{"slug":"performance","path":"/docs/performance","title":"Performance and scalability","description":"Reviewed against: Aloha Social 0.26.279 on 2026-10-27; source branch main at 33935993. The latest successful repeatable benchmark available that day is the Nightly performance run…","group":"performance","html":"<p><strong>Reviewed against:</strong> Aloha Social <strong>0.26.279</strong> on <strong>2026-10-27</strong>; source\nbranch <code>main</code> at <code>33935993</code>. The latest successful repeatable benchmark\navailable that day is the <a href=\"https://github.com/AlohaSocial/social/actions/runs/40426921866\">Nightly performance run 40426921866</a>.\nIt ran the benchmark from <code>main</code> commit <code>2ab03f1</code> (app <strong>0.26.278</strong>), so it is\none patch behind this checkout. No benchmark of 0.26.279 itself was available\nat review time.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Performance.md","sections":[{"path":"/docs/performance-latest-ci-query-snapshot","title":"Latest CI query snapshot","description":"All populated probes returned the requested 20 rows and stayed under their configured guardrails in that run. The direct-message probe returned zero rows in both databases, so its timing…","parent":false},{"path":"/docs/performance-what-the-benchmark-covers","title":"What the benchmark covers","description":"occ social:benchmark seeds plausible actors, posts, recipients, hashtags, notifications and search terms, runs an ANALYZE, then times the query and hydration path for each probe. The…","parent":false},{"path":"/docs/performance-running-a-comparable-local-benchmark","title":"Running a comparable local benchmark","description":"Use a disposable development Nextcloud database: seeding writes 100,000 rows and is not suitable for a production instance. The command and cleanup options are documented in OCC-Commands.md.","parent":false},{"path":"/docs/performance-current-performance-risks-to-investigate","title":"Current performance risks to investigate","description":"For schema and data-flow context, see Architecture.md. For operator checks and queue health, see Admin.md.","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/performance-latest-ci-query-snapshot","title":"Latest CI query snapshot"},"parent":null},{"slug":"performance-latest-ci-query-snapshot","path":"/docs/performance-latest-ci-query-snapshot","title":"Latest CI query snapshot","description":"All populated probes returned the requested 20 rows and stayed under their configured guardrails in that run. The direct-message probe returned zero rows in both databases, so its timing…","group":"performance","html":"<p>The workflow seeded 100,000 public posts from 2,000 actors, with 300 followed\naccounts, enabled the search index and recipient <code>nid</code> backfill, then took the\nmedian of five runs. It used PHP 8.3.36, PostgreSQL 14 and MySQL 8.4 on GitHub\nActions. Values are milliseconds for a page of 20 records:</p>\n<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Query</th>\n<th align=\"right\">MySQL 8.4</th>\n<th align=\"right\">PostgreSQL 14</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Home timeline</td>\n<td align=\"right\">27.96</td>\n<td align=\"right\">57.80</td>\n</tr>\n<tr>\n<td>Public timeline</td>\n<td align=\"right\">8.74</td>\n<td align=\"right\">12.07</td>\n</tr>\n<tr>\n<td>Notifications</td>\n<td align=\"right\">14.88</td>\n<td align=\"right\">88.98</td>\n</tr>\n<tr>\n<td>Photos</td>\n<td align=\"right\">11.33</td>\n<td align=\"right\">45.54</td>\n</tr>\n<tr>\n<td>Videos</td>\n<td align=\"right\">16.24</td>\n<td align=\"right\">52.28</td>\n</tr>\n<tr>\n<td>Hashtag</td>\n<td align=\"right\">21.59</td>\n<td align=\"right\">58.91</td>\n</tr>\n<tr>\n<td>Account posts</td>\n<td align=\"right\">10.08</td>\n<td align=\"right\">42.32</td>\n</tr>\n<tr>\n<td>Search</td>\n<td align=\"right\">35.37</td>\n<td align=\"right\">80.77</td>\n</tr>\n</tbody></table></div>\n<p>All populated probes returned the requested 20 rows and stayed under their\nconfigured guardrails in that run. The direct-message probe returned <strong>zero\nrows</strong> in both databases, so its timing is not evidence about a populated\ninbox. Page-size-50 timings and row counts are in the run artifacts. The run\nchecks query behavior on a synthetic fixture; it does not represent the spread\nof real media, follow graphs, blocks, retention or database hardware.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Performance.md","sections":null,"anchor":"latest-ci-query-snapshot","manual":false,"prev":{"path":"/docs/performance","title":"Performance and scalability"},"next":{"path":"/docs/performance-what-the-benchmark-covers","title":"What the benchmark covers"},"parent":null},{"slug":"performance-what-the-benchmark-covers","path":"/docs/performance-what-the-benchmark-covers","title":"What the benchmark covers","description":"occ social:benchmark seeds plausible actors, posts, recipients, hashtags, notifications and search terms, runs an ANALYZE, then times the query and hydration path for each probe. The…","group":"performance","html":"<p><code>occ social:benchmark</code> seeds plausible actors, posts, recipients, hashtags,\nnotifications and search terms, runs an <code>ANALYZE</code>, then times the query and\nhydration path for each probe. The <a href=\"https://github.com/AlohaSocial/social/blob/master/.github/workflows/perf-nightly.yml\">nightly workflow</a>\nruns it on both supported CI database families and keeps the JSON reports as\n90-day artifacts. A probe over its explicit ceiling or its configured baseline\nfactor fails that job.</p>\n<p>The benchmark is read-focused. It does not measure ActivityPub delivery,\nremote outbox imports, Bluesky relay/AppView indexing, cron backlog, media\ntranscoding, first paint, or production latency. The direct-message dataset is\ncurrently empty. These are known coverage gaps, not known performance failures.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Performance.md","sections":null,"anchor":"what-the-benchmark-covers","manual":false,"prev":{"path":"/docs/performance-latest-ci-query-snapshot","title":"Latest CI query snapshot"},"next":{"path":"/docs/performance-running-a-comparable-local-benchmark","title":"Running a comparable local benchmark"},"parent":null},{"slug":"performance-running-a-comparable-local-benchmark","path":"/docs/performance-running-a-comparable-local-benchmark","title":"Running a comparable local benchmark","description":"Use a disposable development Nextcloud database: seeding writes 100,000 rows and is not suitable for a production instance. The command and cleanup options are documented in OCC-Commands.md.","group":"performance","html":"<p>Use a disposable development Nextcloud database: seeding writes 100,000 rows\nand is not suitable for a production instance. The command and cleanup options\nare documented in <a href=\"/docs/occ\">OCC-Commands.md</a>.</p>\n<pre><code class=\"language-sh\">php occ social:benchmark --viewer=admin --actors=2000 --notes=100000 \\\n  --follows=300 --seed-only --force --no-interaction\nphp occ social:benchmark --viewer=admin --time-only --runs=5 --output=json_pretty\nphp occ social:benchmark --clean --force --no-interaction\n</code></pre>\n<p>Record the Social commit, Nextcloud version, PHP version, database version,\ncache/index state, seed parameters and run artifact with any new measurements.\nCompare like with like; do not copy an older benchmark into the baseline file\nwithout reviewing its guardrail effect.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Performance.md","sections":null,"anchor":"running-a-comparable-local-benchmark","manual":false,"prev":{"path":"/docs/performance-what-the-benchmark-covers","title":"What the benchmark covers"},"next":{"path":"/docs/performance-current-performance-risks-to-investigate","title":"Current performance risks to investigate"},"parent":null},{"slug":"performance-current-performance-risks-to-investigate","path":"/docs/performance-current-performance-risks-to-investigate","title":"Current performance risks to investigate","description":"For schema and data-flow context, see Architecture.md. For operator checks and queue health, see Admin.md.","group":"performance","html":"<ul>\n<li><strong>Synthetic query results may not match real distributions.</strong> Follow graph\nshape, post visibility, notification policies and media density can change\nquery plans. Compare query plans and latency at multiple instance sizes before\nadding indexes or denormalized data.</li>\n<li><strong>Federation freshness is a separate latency budget.</strong> A fast timeline query\ncan still show stale remote data when cron, a poller, relay or remote server is\ndelayed. Diagnose queue and synchronization health before attributing that\nsymptom to SQL.</li>\n<li><strong>Large multi-protocol reads have external dependencies.</strong> Bluesky AppView,\nChat, PLC and relay calls and ActivityPub remote imports must be timed and\nreported separately from local DB response time.</li>\n<li><strong>The benchmark does not yet populate direct messages.</strong> Add representative\nconversations before making claims about inbox scalability.</li>\n</ul>\n<p>For schema and data-flow context, see <a href=\"/docs/architecture\">Architecture.md</a>. For\noperator checks and queue health, see <a href=\"/docs/admin\">Admin.md</a>.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Performance.md","sections":null,"anchor":"current-performance-risks-to-investigate","manual":false,"prev":{"path":"/docs/performance-running-a-comparable-local-benchmark","title":"Running a comparable local benchmark"},"next":null,"parent":null},{"slug":"debt","path":"/docs/debt","title":"Technical debt and current maintenance status","description":"Reviewed against: Aloha Social 0.26.279 (appinfo/info.xml) on 2026-10-27; source branch main at 33935993. Counts below were measured from that checkout. They describe code size and…","group":"project","html":"<p><strong>Reviewed against:</strong> Aloha Social <strong>0.26.279</strong> (<code>appinfo/info.xml</code>) on <strong>2026-10-27</strong>; source\nbranch <code>main</code> at <code>33935993</code>. Counts below were measured from\nthat checkout. They describe code size and maintenance boundaries; they are not\na quality score, a claim that every test is green, or a production audit.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Technical-Debt.md","sections":[{"path":"/docs/debt-current-snapshot","title":"Current snapshot","description":"The declared support range is Nextcloud 34–36 and PHP 8.3–8.5. package.json requires Node 24 and npm 11. Local CLI versions are not a substitute for the CI compatibility matrix.","parent":false},{"path":"/docs/debt-maintenance-items-with-ongoing-cost","title":"Maintenance items with ongoing cost","description":"Aloha Social exposes its own Nextcloud API, a broad but partial Mastodon client API, ActivityPub federation and an optional native AT Protocol PDS/XRPC surface. The legacy hashtag-interest…","parent":false},{"path":"/docs/debt-current-priorities","title":"Current priorities","description":"Aloha Social documentation.","parent":false},{"path":"/docs/debt-what-this-document-does-not-claim","title":"What this document does not claim","description":"This is a source-based maintenance review, not a full dead-code proof, security audit, benchmark of a production instance or proof that all CI checks pass. The API reference is…","parent":false}],"anchor":null,"manual":false,"prev":null,"next":{"path":"/docs/debt-current-snapshot","title":"Current snapshot"},"parent":null},{"slug":"debt-current-snapshot","path":"/docs/debt-current-snapshot","title":"Current snapshot","description":"The declared support range is Nextcloud 34–36 and PHP 8.3–8.5. package.json requires Node 24 and npm 11. Local CLI versions are not a substitute for the CI compatibility matrix.","group":"project","html":"<div class=\"md-table\"><table>\n<thead>\n<tr>\n<th>Area</th>\n<th align=\"right\">Current observation</th>\n<th>What it means</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>PHP under <code>lib/</code></td>\n<td align=\"right\">1,097 files; 233,484 lines</td>\n<td>Large backend surface spanning Nextcloud, ActivityPub and AT Protocol.</td>\n</tr>\n<tr>\n<td>Vue/JavaScript under <code>src/</code></td>\n<td align=\"right\">338 files; 101,686 lines</td>\n<td>The web client has become a substantial product in its own right.</td>\n</tr>\n<tr>\n<td>HTTP route attributes</td>\n<td align=\"right\">637 declarations</td>\n<td>API documentation and route tests must stay synchronized; this is a declaration count, not a count of unique URLs.</td>\n</tr>\n<tr>\n<td>Migration classes</td>\n<td align=\"right\">67</td>\n<td>Upgrade paths are part of the supported product; schema edits need fresh-install and upgrade coverage.</td>\n</tr>\n<tr>\n<td><code>TABLE_*</code> constants</td>\n<td align=\"right\">101</td>\n<td>The central table registry is a broad map of the schema, not a direct SQL table count.</td>\n</tr>\n<tr>\n<td><code>@deprecated</code> markers in <code>lib/</code></td>\n<td align=\"right\">11</td>\n<td>Some compatibility helpers remain. Remove a marker only after callers and supported integrations no longer need it.</td>\n</tr>\n<tr>\n<td>Explicit <code>TODO:</code> / <code>FIXME</code> comments in <code>lib/</code> and <code>src/</code></td>\n<td align=\"right\">0</td>\n<td>This search does not rule out undocumented work or risks.</td>\n</tr>\n</tbody></table></div>\n<p>Reproduce the source counts from the repository root:</p>\n<pre><code class=\"language-sh\">find lib -name &#39;*.php&#39; | wc -l\nfind lib -name &#39;*.php&#39; -exec cat {} + | wc -l\nfind src -type f \\( -name &#39;*.js&#39; -o -name &#39;*.vue&#39; \\) | wc -l\nfind src -type f \\( -name &#39;*.js&#39; -o -name &#39;*.vue&#39; \\) -exec cat {} + | wc -l\nrg -n &#39;#\\[(FrontpageRoute|ApiRoute)&#39; lib | wc -l\nrg -l &#39;class Version1000Date&#39; lib/Migration | wc -l\nrg -c &#39;public const TABLE_&#39; lib/Db/CoreRequestBuilder.php\nrg -n &#39;@deprecated&#39; lib | wc -l\nrg -n &#39;\\b(TODO:|TODO -|FIXME)&#39; lib src\n</code></pre>\n<p>The declared support range is Nextcloud 34–36 and PHP 8.3–8.5. <code>package.json</code>\nrequires Node 24 and npm 11. Local CLI versions are not a substitute for the\nCI compatibility matrix.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Technical-Debt.md","sections":null,"anchor":"current-snapshot","manual":false,"prev":{"path":"/docs/debt","title":"Technical debt and current maintenance status"},"next":{"path":"/docs/debt-maintenance-items-with-ongoing-cost","title":"Maintenance items with ongoing cost"},"parent":null},{"slug":"debt-maintenance-items-with-ongoing-cost","path":"/docs/debt-maintenance-items-with-ongoing-cost","title":"Maintenance items with ongoing cost","description":"Aloha Social exposes its own Nextcloud API, a broad but partial Mastodon client API, ActivityPub federation and an optional native AT Protocol PDS/XRPC surface. The legacy hashtag-interest…","group":"project","html":"<h2 id=\"compatibility-surfaces-must-be-maintained-deliberately\">Compatibility surfaces must be maintained deliberately</h2>\n<p>Aloha Social exposes its own Nextcloud API, a broad but partial Mastodon client\nAPI, ActivityPub federation and an optional native AT Protocol PDS/XRPC surface.\nThe legacy hashtag-interest API remains alongside the ranked For You API for\ncompatibility, and an administrator can still force that legacy feed. This\ncreates duplicated behavior and documentation. Keep the surfaces clearly\nlabelled; any retirement needs usage evidence, a migration path and an API\ncompatibility decision. See <a href=\"/docs/api\">API.md</a>,\n<a href=\"/docs/integrations\">Integrations.md</a> and <a href=\"/docs/for-you\">For-You.md</a>.</p>\n<p>Remote behavior is also configuration-dependent: ActivityPub delivery and\nprofile imports rely on Nextcloud background work; Mastodon clients need root\nrewrite rules; AT Protocol hosting needs reachable PLC, relay, AppView and\noptional Chat services. Unit tests cannot establish those remote services are\navailable. Keep the operator checks and live-test procedures current rather\nthan describing a successful local route as proof of federation.</p>\n<h2 id=\"schema-history-is-an-upgrade-contract\">Schema history is an upgrade contract</h2>\n<p>The 67 migration classes include paths for existing installations, not only\nfresh installs. Do not squash or reorder migrations based solely on the current\nschema fixture: an older supported app version may have applied a different\nsubset. Update the schema fixture and exercise upgrade paths when changing\nstorage. See <a href=\"/docs/architecture\">Architecture.md</a> and\n<a href=\"/docs/feature\">tests/Integration/README.md</a>.</p>\n<h2 id=\"deprecated-helpers-still-need-a-caller-by-caller-plan\">Deprecated helpers still need a caller-by-caller plan</h2>\n<p>There are 11 <code>@deprecated</code> markers today. They include older query-builder\nhelpers and traits/interfaces retained for compatibility. The count alone does\nnot show whether removal is safe. Before removing one, search production and\nextension callers, replace internal use, and cover the behavior on all supported\ndatabases. Do not treat the marker as a scheduled removal date unless one is\ndocumented.</p>\n<h2 id=\"performance-evidence-is-stronger-but-not-production-evidence\">Performance evidence is stronger, but not production evidence</h2>\n<p>A nightly benchmark now seeds 100,000 posts and times timeline/search queries\non MySQL and PostgreSQL. The most recent successful run available during this\nreview is dated 2026-10-27 and is documented in\n<a href=\"/docs/performance\">Performance.md</a>. It uses app version 0.26.278, one patch before\nthis checkout&#39;s 0.26.279. The benchmark does not measure remote delivery,\nAppView indexing, background queue delay, real user profiles, populated direct\nmessages or browser rendering. Treat the figures as a repeatable query baseline,\nnot a production service-level objective.</p>\n","toc":[{"id":"compatibility-surfaces-must-be-maintained-deliberately","text":"Compatibility surfaces must be maintained deliberately","level":2},{"id":"schema-history-is-an-upgrade-contract","text":"Schema history is an upgrade contract","level":2},{"id":"deprecated-helpers-still-need-a-caller-by-caller-plan","text":"Deprecated helpers still need a caller-by-caller plan","level":2},{"id":"performance-evidence-is-stronger-but-not-production-evidence","text":"Performance evidence is stronger, but not production evidence","level":2}],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Technical-Debt.md","sections":null,"anchor":"maintenance-items-with-ongoing-cost","manual":false,"prev":{"path":"/docs/debt-current-snapshot","title":"Current snapshot"},"next":{"path":"/docs/debt-current-priorities","title":"Current priorities"},"parent":null},{"slug":"debt-current-priorities","path":"/docs/debt-current-priorities","title":"Current priorities","description":"Aloha Social documentation.","group":"project","html":"<ol>\n<li>Keep the API and integration matrix accurate as features evolve; clearly mark\npartial client parity and remote-service dependencies.</li>\n<li>Continue reducing legacy compatibility code only when real usage and upgrade\nevidence support removal.</li>\n<li>Preserve migration and repository invariants across SQLite, MySQL and\nPostgreSQL, including upgrades from supported releases.</li>\n<li>Extend performance measurements to meaningful direct-message data and\nrepresentative profile/feed shapes, and retain run artifacts for comparison.</li>\n<li>Use live interoperability checks for DNS, TLS, proxying, background jobs and\npublic indexing; unit tests cannot validate those deployment conditions.</li>\n</ol>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Technical-Debt.md","sections":null,"anchor":"current-priorities","manual":false,"prev":{"path":"/docs/debt-maintenance-items-with-ongoing-cost","title":"Maintenance items with ongoing cost"},"next":{"path":"/docs/debt-what-this-document-does-not-claim","title":"What this document does not claim"},"parent":null},{"slug":"debt-what-this-document-does-not-claim","path":"/docs/debt-what-this-document-does-not-claim","title":"What this document does not claim","description":"This is a source-based maintenance review, not a full dead-code proof, security audit, benchmark of a production instance or proof that all CI checks pass. The API reference is…","group":"project","html":"<p>This is a source-based maintenance review, not a full dead-code proof, security\naudit, benchmark of a production instance or proof that all CI checks pass. The\n<a href=\"/docs/api\">API reference</a> is mechanically checked against registered routes;\nother behavior claims still need review when the implementation changes.</p>\n","toc":[],"source":"https://github.com/AlohaSocial/social/blob/master/docs/Technical-Debt.md","sections":null,"anchor":"what-this-document-does-not-claim","manual":false,"prev":{"path":"/docs/debt-current-priorities","title":"Current priorities"},"next":null,"parent":null},{"slug":"get-started","path":"/get-started","title":"Get started","description":"Find your place on the fediverse and make the first post.","group":"start","html":"","toc":[],"source":null,"sections":null,"anchor":null,"manual":true,"prev":null,"next":null,"parent":null},{"slug":"docs/configuration","path":"/docs/configuration","title":"Configuration reference","description":"All configuration options: occ commands, config.php settings, environment variables and server requirements.","group":"admin","html":"","toc":[],"source":null,"sections":null,"anchor":null,"manual":true,"prev":null,"next":null,"parent":null},{"slug":"docs/maintenance","path":"/docs/maintenance","title":"Maintenance and updates","description":"Upgrades, backups, monitoring and disaster recovery.","group":"admin","html":"","toc":[],"source":null,"sections":null,"anchor":null,"manual":true,"prev":null,"next":null,"parent":null},{"slug":"docs/contributing","path":"/docs/contributing","title":"Contributing","description":"Code style, pull requests, tests and the release workflow.","group":"project","html":"","toc":[],"source":null,"sections":null,"anchor":null,"manual":true,"prev":null,"next":null,"parent":null},{"slug":"developers/docs","path":"/developers/docs","title":"Developer chapters overview","description":"Where the long-form chapters for extending the app live.","group":"developer","html":"","toc":[],"source":null,"sections":null,"anchor":null,"manual":true,"prev":null,"next":null,"parent":null},{"slug":"developers/docs/protocol","path":"/developers/docs/protocol","title":"Protocol chapter","description":"ActivityPub and AT Protocol details, as implemented.","group":"developer","html":"","toc":[],"source":null,"sections":null,"anchor":null,"manual":true,"prev":null,"next":null,"parent":null},{"slug":"developers/docs/federation","path":"/developers/docs/federation","title":"Federation chapter","description":"Server-to-server delivery, retries and propagation.","group":"developer","html":"","toc":[],"source":null,"sections":null,"anchor":null,"manual":true,"prev":null,"next":null,"parent":null},{"slug":"developers/docs/api","path":"/developers/docs/api","title":"API chapter","description":"Endpoints, authentication and response shapes.","group":"developer","html":"","toc":[],"source":null,"sections":null,"anchor":null,"manual":true,"prev":null,"next":null,"parent":null},{"slug":"developers/docs/operations","path":"/developers/docs/operations","title":"Operations chapter","description":"Deployment, scaling and monitoring of a deployment.","group":"developer","html":"","toc":[],"source":null,"sections":null,"anchor":null,"manual":true,"prev":null,"next":null,"parent":null}];

export const DOC_BY_PATH: Record<string, DocPage> = Object.fromEntries(
  DOC_PAGES.map((page) => [page.path, page]),
);

export function getDocBySlug(slug: string): DocPage | undefined {
  return DOC_BY_PATH[`/docs/${slug}`];
}

export function pagesInGroup(groupId: string): DocPage[] {
  return DOC_PAGES.filter((page) => page.group === groupId);
}
