Reference
Admin API
Admins + moderatorsThe 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), orexempt.ruleId: the matched rule’s ID,"draft", ornullfordefault/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.
| 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
400while federation is off, and409when 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.