Skip to content
Omicron

Reference

Admin API

Admins + moderators

The administrative endpoints under /api/admin — instance settings, email, moderation, users, and defederation.

Everything under /api/admin requires an authenticated admin or moderator account — but not every endpoint accepts both. The Users and Content and reports sections below accept moderators; Instance, Settings, Security, Discoverability, Media, Email, Federation domains, and both role-grant endpoints are admin-only, and a moderator calling them gets 403 Admin access required. These are the endpoints the admin panel itself calls; they are documented here because operators sometimes need to script against them.

Independent apps can instead request admin:read or admin:write through client OAuth. These permissions are not included in ordinary read write, and they never grant a role or bypass the endpoint’s ownership/confirmation rules. The account’s current role is checked for each request. Password-confirmed account deletion and role changes should open /admin in the system browser rather than collect an operator’s password.

Instance

Method Path Purpose
GET /api/admin/instance Instance identity, visitor card, public information
PUT /api/admin/instance Update them (domain and federation apply on restart)
POST /api/admin/instance/banner Upload the visitor-card banner image
DELETE /api/admin/instance/banner Revert the banner to the bundled artwork
POST /api/admin/instance/rotate-secret Rotate the session secret

PUT /api/admin/instance accepts any subset of appName, appDomain, federationEnabled, bannerText, about, rules, privacyPolicy, contactEmail, contactUrl, abuseEmail, and statusUrl. The three page sections accept Markdown up to 20,000 characters each and are stored alongside their server-rendered sanitized HTML; blank clears back to the built-in placeholder. Emails must be valid, and contact/status URLs must be http(s). Invalid values answer 400.

Rotating signs everyone out and invalidates JWTs on the next restart. JWT issuance and public-key discovery pause until that restart completes. If SESSION_SECRET is pinned in the environment, rotate it there instead.

Settings and analytics

Method Path Purpose
GET /api/admin/settings Built-in view-counting setting
PUT /api/admin/settings/analytics Built-in analytics behaviour

The built-in analytics privacy model is described in Writer dashboard.

Umami Cloud

These routes require an admin account; moderators receive 403.

Method Path Purpose
GET /api/admin/umami Read the website ID and enabled flag
PUT /api/admin/umami Replace both settings

Both return the same shape and use Cache-Control: no-store:

{
  "enabled": true,
  "websiteId": "94db1cb1-74f4-4a40-ad6c-962362670409"
}

PUT requires both fields. enabled is a boolean; websiteId is a string of at most 4,096 characters after trimming. Supply a UUID or a script snippet containing exactly one quoted data-website-id attribute. Only the lowercase UUID is stored and returned; the snippet and its URLs are discarded. Invalid input returns 400 with { "error": string }.

The default is { "enabled": false, "websiteId": "" }. Setting enabled to false keeps the supplied ID; send an empty string too to remove it. A blank ID with enabled: true is rejected. Changes apply live and do not delete data already held by Cloud. For the admin walkthrough and privacy implications, see Umami Cloud.

Security

Method Path Purpose
GET /api/admin/security Current security settings
PUT /api/admin/security/anubis Toggle the AI-scraper shield

The toggle applies live — the backend re-routes traffic through the challenge service via Caddy’s internal admin API. No restart.

IP access rules

All of these routes are admin-only, including reads and previews:

Method Path Purpose
GET /api/admin/security/access-rules List saved rules
POST /api/admin/security/access-rules Add a temporary rule
PATCH /api/admin/security/access-rules/:id Enable or disable a rule
DELETE /api/admin/security/access-rules/:id Remove a rule
POST /api/admin/security/access-rules/test Preview saved rules or a draft

Creation body:

{
  "network": "192.0.2.0/24",
  "action": "block",
  "reason": "Temporary automated traffic",
  "expiresInHours": 24
}

action is allow or block. network accepts IPv4/IPv6 addresses or CIDR ranges and is normalized to a network with a prefix. IPv4-mapped IPv6 ranges and interface-scoped IPv6 addresses are rejected. expiresInHours must be 1, 24, 168, or 720; it is required. reason is optional, defaults to an empty string, and is limited to 300 characters.

GET, POST, PATCH, and DELETE return { "rules": [...] }. Each rule contains id, network, action, reason, enabled, createdAt, and expiresAt; timestamps are ISO strings. New rules are enabled and prepended. The first enabled, unexpired match wins. At most 100 unexpired rules can be saved, including disabled ones. Adding a rule prunes expired entries.

PATCH takes { "enabled": boolean }; an expired rule cannot be re-enabled. Unknown rule IDs and validation/application failures return 400 with { "error": string }. Writes require managed Caddy, but reads and previews do not. The challenge switch does not disable IP rules.

Preview body:

{
  "ip": "192.0.2.10",
  "path": "/search",
  "draft": { "network": "192.0.2.0/24", "action": "allow" }
}

Omit draft to test saved rules only. A draft is tested before saved rules but is never persisted or applied. ip must be a single address, not a CIDR range. path must start with /, contain no query or fragment, and be at most 2,048 characters. The result is { "action", "ruleId", "message" }:

  • action: allow, block, default (no matching custom rule), or exempt.
  • ruleId: the matched rule’s ID, "draft", or null for default/exempt.
  • message: a human-readable explanation. It does not simulate Anubis’s bot policy or certify that an IP is what Caddy will see behind a proxy.

For exempt paths, proxy limitations, expiry behavior, and the UI walkthrough, see IP access rules.

Discoverability

Method Path Purpose
GET /api/admin/seo Discoverability settings, including the IndexNow key
PUT /api/admin/seo Update indexingEnabled, verification, indexNowEnabled

Documented in full in Discoverability. The IndexNow key appears only here — the public /api/seo withholds it, since it is what authorises submissions for the domain.

Media

Method Path Purpose
GET /api/admin/unsplash Whether an Unsplash key is configured
PUT /api/admin/unsplash Set the key, or clear it with null

Both return { "configured": boolean } and nothing more — the key is never read back, so it cannot end up in a browser cache or a screenshot. Clearing it turns Unsplash off; Openverse needs no key and keeps working. See Admin panel.

Email

Method Path Purpose
GET /api/admin/email Current email configuration (secrets are write-only)
PUT /api/admin/email Update mode and connection details
POST /api/admin/email/dkim Generate an RSA-2048 DKIM keypair
GET /api/admin/email/dns The SPF, DKIM, and DMARC records to publish, and live verification
GET /api/admin/email/port25 Test outbound port 25 from inside the container
POST /api/admin/email/test Send a live test message

Passwords and API keys are never read back — the API returns “unchanged” rather than the stored secret. The DKIM private key never leaves the server.

See Email.

Users

Moderators may call every endpoint in this table except the two role grants — and only against regular accounts: acting on an admin’s account, or (on a moderator’s) on another moderator’s, is refused with 403. Role grants are admin-only.

Method Path Purpose
GET /api/admin/users List local accounts, newest first (?q= over handle, name and email; ?suspended=, ?admin=, ?verified=; ?cursor= + ?limit= for pages)
POST /api/admin/users/:id/suspend Suspend or reinstate an account
POST /api/admin/users/:id/freeze Freeze or unfreeze an account. Frozen accounts are hidden and remote copies are retracted; body { freeze, notify? }
GET /api/admin/users/:id One account with counts, latest posts and reports against it
PATCH /api/admin/users/:id Edit profile fields and the login email
POST /api/admin/users/:id/avatar Replace another account’s avatar (raw image body)
DELETE /api/admin/users/:id/avatar Clear another account’s avatar back to initials
POST /api/admin/users/:id/role Grant or revoke the admin role (confirm with your password; admin-only)
POST /api/admin/users/:id/moderator-role Grant or revoke the moderator role (confirm with your password; admin-only)
POST /api/admin/users/:id/verification-email Resend the verification email
POST /api/admin/users/:id/verify Manually mark the address verified
POST /api/admin/users/:id/delete Delete an account (confirm with username + your password)
POST /api/admin/users/:id/restore Restore a deleted account within 30 days
GET /api/admin/users/deleted Recently deleted accounts, with expiry (?q=, ?cursor= + ?limit=, nextCursor + total + filteredTotal in the response)
DELETE /api/admin/users/deleted/:id Erase a deleted account permanently

Deleting takes { "username", "password" }: the account’s exact username plus your own password, both re-verified server-side. The account is notified by email, through the instance’s configured email transport. A deleted account is kept for 30 days and comes back with /restore; the expiry and /deleted/:id erase it for good and free the username.

Listing is keyset-paginated: ?limit= sizes the page (1–100, default 50) and the response carries nextCursor (pass back as ?cursor=) plus total (unfiltered) and filteredTotal (matching the current filter). The deleted listing paginates the same way, with its own ?q= search over handle, name and email.

PATCH takes any subset of displayName, bio, publicEmail, customSection, tags, links, and email. Editing email stores it unverified: the verification mail goes to the new address and a security notice to the previous one.

Content and reports

Moderators may call every endpoint in this section.

Method Path Purpose
GET /api/admin/reports The moderation queue
POST /api/admin/reports/:id/resolve Resolve or dismiss a report
POST /api/admin/posts/:id/ai-assisted Add the AI-Assisted disclosure
DELETE /api/admin/posts/:id/ai-assisted Remove the AI-Assisted disclosure
DELETE /api/admin/posts/:id Remove a post

The AI-Assisted routes take no body and return { "aiAssisted": true } or { "aiAssisted": false }, respectively. They change only the disclosure and accept local posts; remote posts are controlled by their originating instance. Repeating a request that already matches the current value is a no-op. Changing a published post federates an ActivityPub Update; drafts and scheduled posts are not federated.

Removing a published post federates a Delete to remote servers.

Tags

Admins only. For fragmented or misspelled tags. Slugs are normalized the same way as a post’s tags.

Method Path Purpose
GET /api/admin/tags/aliases { aliases }: every alias and its target
POST /api/admin/tags/alias { alias, target }: map a slug to a tag
POST /api/admin/tags/merge { from, to }: fold one tag into another

An alias slug must not already be a real tag, and its target must exist. A merge moves every post and tag follow from from to to, leaves from as an alias of to, and deletes the from tag. It cannot be undone. Both return 400 when the two slugs are the same or invalid.

Federation domains

Method Path Purpose
GET /api/admin/domains Blocked domains, each with its severity
POST /api/admin/domains Suspend or limit a domain
DELETE /api/admin/domains/:domain Lift a block

POST takes { domain, reason?, severity? }, where severity is "suspend" (the default) or "limit", and answers 201 with { domain, purged }. Posting a domain that is already listed updates its reason and severity.

Remote account blocks

Method Path Purpose
GET /api/admin/blocked-actors Blocked remote accounts
POST /api/admin/blocked-actors { account, reason? }: block one
DELETE /api/admin/blocked-actors?apId=… Unblock by ActivityPub id

account is a user@host handle or a profile URL. An account the instance hasn’t cached is looked up first, which needs federation on. 404 when it can’t be found, 400 for a local account. Blocking purges the account’s cached profile, posts and follows.

Federation network

Method Path Purpose
GET /api/admin/federation Settings, last FediDB run, and tracked instances
PATCH /api/admin/federation/settings Change any of the settings below
POST /api/admin/federation/discover Read FediDB now
POST /api/admin/federation/instances { domain }: track an instance by hand
PATCH /api/admin/federation/instances/:domain { autoCache }: pause or resume one
DELETE /api/admin/federation/instances/:domain Stop tracking a hand-added instance
POST /api/admin/federation/instances/:domain/sync Sync one instance now

Settings are autoCache and fedidbDiscovery (booleans, both default true), syncIntervalHours (1–168, default 6) and authorsPerInstance (1–100, default 20).

  • Removing an instance FediDB listed answers 400: pause it instead.
  • Adding or resuming a suspended or limited domain answers 400.
  • Discover and sync answer 400 while federation is off, and 409 when a sync of that instance is already running. Both are limited to 6 calls a minute per admin.

Notes for scripting

  • Every write is subject to the general API write limiter (RL_API_WRITE_MAX, default 120/min).
  • Changes to the domain and the federation flag are only effective after docker compose up -d.
  • Prefer the admin panel for one-off changes. Script only what you genuinely need to repeat — these routes track the UI’s needs and can change between releases.

Found a mistake?Edit this page on GitHub.