Endpoints: Platform Admin
Platform admin
Section titled “Platform admin”Cross-tenant operations for platform admins. These routes are deliberately not scoped to the caller’s org: they require is_superadmin, a permission axis independent of the org role.
The product adds the allowed-models catalog, the cross-tenant custom-rule routes and the analysis rollup to the platform’s admin surface.
GET /v1/admin/organizations
Section titled “GET /v1/admin/organizations”List every organization on this instance
Every organization on the instance. Superadmin only: deliberately not scoped to the caller’s org.
contract carries an enterprise org’s committed terms and is null on every other plan. An org moved off enterprise keeps its stored contract but reports null here, so the list never shows terms that are not in force. contract_expired is a renewal prompt and revokes nothing. sso_enabled is true only when the org’s SSO connection is configured and enabled; GET /admin/organizations/{org_id} has its details.
In the dashboard: Platform Admin → Organizations.
Response 200 (application/json)
{ "organizations": [ { "org_id": "string", "name": "string", "slug": "string", "plan_tier": "free", "trial_usage": { "key": 0 }, "contract": { "expires_at": "2026-01-01T00:00:00Z", "included_units_per_month": 0, "committed_amount_usd": 0, "reference": "string" }, "contract_expired": false, "member_count": 0, "monthly_budget_usd": 0, "current_month_cost_usd": 0, "created_at": "2026-01-01T00:00:00Z", "locked": true, "require_2fa": false, "sso_enabled": false, "pending_deletion_at": "2026-01-01T00:00:00Z" } ]}GET /v1/admin/organizations/{org_id}
Section titled “GET /v1/admin/organizations/{org_id}”Get one organization’s platform-admin summary
One organization, with the fields of the list plus its full SSO connection (sso, null when none): the same fields as GET /orgs/{org_id}/sso, so never the client secret, only client_secret_set. Superadmin only.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "org_id": "string", "name": "string", "slug": "string", "plan_tier": "free", "trial_usage": { "key": 0 }, "contract": { "expires_at": "2026-01-01T00:00:00Z", "included_units_per_month": 0, "committed_amount_usd": 0, "reference": "string" }, "contract_expired": false, "member_count": 0, "monthly_budget_usd": 0, "current_month_cost_usd": 0, "created_at": "2026-01-01T00:00:00Z", "locked": true, "require_2fa": false, "sso_enabled": false, "pending_deletion_at": "2026-01-01T00:00:00Z", "sso": { "protocol": "oidc", "display_name": "string", "issuer": "string", "client_id": "string", "client_secret_set": false, "idp_entity_id": "string", "idp_sso_url": "string", "idp_certificates": [ { "pem": "string", "expires_at": "2026-01-01T00:00:00Z" } ], "email_attribute": "string", "service_provider": { "entity_id": "string", "acs_url": "string", "metadata_url": "string" }, "default_role": "owner", "allowed_domains": [ "string" ], "verified_domains": [ "string" ], "domain_verification_record": "string", "enabled": true, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" }}| Field | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
name | string | yes | |
slug | string | yes | |
plan_tier | "free" | "paid" | "enterprise" | yes | |
trial_usage | object | no | |
contract | OrgContract | null | no | The org’s negotiated terms, but only while it is on the tier they govern (entitlements.active_contract) — an org downgraded off ‘enterprise’ keeps its stored contract but reports null here, so this list never shows terms that aren’t in force. |
contract_expired | boolean | no | Contract term has lapsed (entitlements.contract_expired). Advisory — an expired contract does not revoke anything; this is the operator’s renewal prompt. See models.auth.OrgContract.expires_at. |
member_count | integer | yes | |
monthly_budget_usd | number | null | yes | |
current_month_cost_usd | number | yes | |
created_at | string (date-time) | yes | |
locked | boolean | yes | |
require_2fa | boolean | no | |
sso_enabled | boolean | no | |
pending_deletion_at | string (date-time) | null | no | |
sso | SSOConnectionInfo | null | no |
404— Organization not found
DELETE /v1/admin/organizations/{org_id}
Section titled “DELETE /v1/admin/organizations/{org_id}”Schedule an organization for deletion
Superadmin only. A soft delete: sets locked: true (every org-scoped endpoint answers 423 at once, as with PATCH .../lock) and pending_deletion_at: now. The org is hard-deleted, through every org-scoped collection, by the first POST /admin/organizations/purge-pending run after pending_deletion_at is more than org_offboarding.grace_period_days old. Cancel at any time before then with POST .../cancel-deletion.
purge_after is computed from the current grace period, not stored, so changing the period moves it for every org still pending.
In the dashboard: Platform Admin → Organizations → an org, Danger zone tab.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "org_id": "string", "pending_deletion_at": "2026-01-01T00:00:00Z", "purge_after": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
pending_deletion_at | string (date-time) | yes | |
purge_after | string (date-time) | yes | pending_deletion_at + the currently-configured org_offboarding.grace_period_days — always derived from the live config, not stored, so a later grace-period change is reflected immediately. |
404— Organization not found409— Already scheduled for deletion
GET /v1/admin/organizations/{org_id}/members
Section titled “GET /v1/admin/organizations/{org_id}/members”List one organization’s members
Superadmin mirror of GET /orgs/{org_id}/members: same response, but the caller need not belong to org_id. To find a user without knowing their org, use GET /admin/users.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "members": [ { "user_id": "string", "email": "string", "name": "string", "role": "string", "is_active": true, "account_active": true, "created_at": "2026-01-01T00:00:00Z", "teams": [ "string" ], "provisioned_via": "scim" } ]}404— Organization not found
PATCH /v1/admin/organizations/{org_id}/members/{user_id}
Section titled “PATCH /v1/admin/organizations/{org_id}/members/{user_id}”Change a member’s role and/or org-scoped active status (platform-admin)
Cross-tenant mirror of PATCH /orgs/{org_id}/members/{user_id}, with the same body, guards and response: role is never owner, the caller’s own membership cannot be changed, and the org’s only owner cannot be demoted or deactivated. Superadmin only.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
Request body (application/json)
{ "role": "string", "is_active": true}Response 200 (application/json)
{ "user_id": "string", "email": "string", "name": "string", "role": "string", "is_active": true, "account_active": true, "created_at": "2026-01-01T00:00:00Z", "teams": [ "string" ], "provisioned_via": "scim"}| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | yes | |
email | string | yes | |
name | string | null | no | |
role | string | yes | |
is_active | boolean | no | Org-scoped — see Membership.is_active. Distinct from account_active. |
account_active | boolean | no | Account-wide User.is_active — deactivating this blocks login entirely, in every org, unlike the org-scoped is_active above. Editable only via PATCH /admin/users/{user_id} (superadmin), never through the org-scoped membership endpoints. |
created_at | string (date-time) | yes | |
teams | string[] | no | Names of every team (see models.teams.Team) this user belongs to in this org — populated from team_members, not stored on the membership itself. |
provisioned_via | "scim" | "sso" | "invite" | null | no | See Membership.provisioned_via. |
400— Targets the caller’s own membership404— Organization or membership not found409— Would demote or deactivate the org’s only remaining owner
DELETE /v1/admin/organizations/{org_id}/members/{user_id}
Section titled “DELETE /v1/admin/organizations/{org_id}/members/{user_id}”Remove a member from an organization (platform-admin)
Cross-tenant mirror of DELETE /orgs/{org_id}/members/{user_id}. Superadmin only.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
200204— No Content400— Targets the caller’s own membership404— Organization or membership not found409— The target is the org’s only remaining owner
POST /v1/admin/organizations/{org_id}/members/{user_id}/reset-password
Section titled “POST /v1/admin/organizations/{org_id}/members/{user_id}/reset-password”Reset a member’s password (platform-admin)
Cross-tenant mirror of POST /orgs/{org_id}/members/{user_id}/reset-password. Superadmin only. Clears the password and signs the account out everywhere, then emails a single-use link, valid for 30 minutes, and returns the same link once for handing over when the deployment sends no mail.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
Response 200 (application/json)
{ "reset_url": "string", "expires_at": "2026-01-01T00:00:00Z"}400— The account authenticates through SSO404— Organization or membership not found
POST /v1/admin/organizations/{org_id}/members/{user_id}/reset-2fa
Section titled “POST /v1/admin/organizations/{org_id}/members/{user_id}/reset-2fa”Disable a member’s two-factor authentication (platform-admin)
Cross-tenant mirror of POST /orgs/{org_id}/members/{user_id}/reset-2fa. Superadmin only. Clears the member’s TOTP secret and recovery codes.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Organization or membership not found
GET /v1/admin/usage
Section titled “GET /v1/admin/usage”Platform-wide spend this month, broken down by organization
Platform-wide spend this month (the cost of every usage event), broken down by organization. Superadmin only.
In the dashboard: Platform Admin → Billing → Usage.
Response 200 (application/json)
{ "period": "string", "total_cost_usd": 0, "by_org": [ { "org_id": "string", "name": "string", "cost_usd": 0 } ]}GET /v1/admin/metrics/summary
Section titled “GET /v1/admin/metrics/summary”Platform-wide API request telemetry, broken down by organization
Superadmin only. The aggregation GET /metrics/summary computes for one org, rolled up across every org on the instance.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
days | integer | no | Number of days to aggregate |
Response 200 (application/json)
{ "period_days": 0, "requests_total": 0, "by_org": [ { "org_id": "string", "name": "string", "requests_total": 0 } ]}GET /v1/admin/organizations/{org_id}/audit
Section titled “GET /v1/admin/organizations/{org_id}/audit”Audit events for one organization (platform-admin)
One organization’s audit events, with the filters and response of GET /metrics/audit, reachable cross-tenant. Superadmin only.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
action | string | null | no | Filter by action, e.g. ‘settings.update’ |
actor_id | string | null | no | Filter by actor — matches either a user_id or a key_id |
target_type | string | null | no | Filter by target type, e.g. ‘api_key’ |
since | string | null | no | ISO-8601 lower bound (inclusive) |
until | string | null | no | ISO-8601 upper bound (inclusive) |
limit | integer | no | |
offset | integer | no |
Response 200 (application/json)
{ "events": [ { "event_id": "string", "org_id": "string", "action": "string", "target_type": "string", "target_id": "string", "actor_user_id": "string", "actor_key_id": "string", "actor_token_id": "string", "actor_email": "string", "actor_is_superadmin": false, "ip": "string", "before": {}, "after": {}, "request_id": "string", "timestamp": "2026-01-01T00:00:00Z" } ], "total_returned": 0}404— Organization not found
GET /v1/admin/audit
Section titled “GET /v1/admin/audit”Cross-org audit events (platform-admin)
Cross-org audit feed. Superadmin only. Omit org_id for every organization, including org-less platform actions such as superadmin.grant; pass it for one org, with the same result as GET /admin/organizations/{org_id}/audit.
In the dashboard: Platform Admin → Audit Log.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | null | no | Restrict to one org; omit for all orgs |
action | string | null | no | |
actor_id | string | null | no | |
target_type | string | null | no | |
since | string | null | no | |
until | string | null | no | |
limit | integer | no | |
offset | integer | no |
Response 200 (application/json)
{ "events": [ { "event_id": "string", "org_id": "string", "action": "string", "target_type": "string", "target_id": "string", "actor_user_id": "string", "actor_key_id": "string", "actor_token_id": "string", "actor_email": "string", "actor_is_superadmin": false, "ip": "string", "before": {}, "after": {}, "request_id": "string", "timestamp": "2026-01-01T00:00:00Z" } ], "total_returned": 0}GET /v1/admin/audit/export
Section titled “GET /v1/admin/audit/export”Download cross-org (or one-org) audit events as CSV or JSON (platform-admin)
The cross-org (or, with org_id, one-org) audit feed as a CSV or JSON file, like GET /metrics/audit/export. Superadmin only.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format | string | no | ‘json’ or ‘csv’ |
org_id | string | null | no | Restrict to one org; omit for all orgs |
action | string | null | no | |
actor_id | string | null | no | |
target_type | string | null | no | |
since | string | null | no | |
until | string | null | no | |
limit | integer | no |
200
GET /v1/admin/users
Section titled “GET /v1/admin/users”List every user on this instance
One page of accounts, sorted by email, each with the orgs it belongs to and its role there. Superadmin only. q matches a case-insensitive substring of the email, the name or the name of one of the user’s organizations, literally, not as a regex. An account in no org has empty memberships. is_active on the user is account-wide; on a membership it is org-scoped. total counts every match, across pages.
In the dashboard: Platform Admin → Users.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
q | string | null | no | Case-insensitive substring of the email, the name or an org’s name |
limit | integer | no | |
offset | integer | no |
Response 200 (application/json)
{ "users": [ { "user_id": "string", "email": "string", "name": "string", "created_at": "2026-01-01T00:00:00Z", "is_active": true, "is_superadmin": true, "two_factor_enabled": true, "has_password": true, "memberships": [ { "org_id": "string", "org_name": "string", "role": "string", "is_active": true } ] } ], "total": 0}| Field | Type | Required | Description |
|---|---|---|---|
users | PlatformUserSummary[] | yes | |
total | integer | yes | Users matching the filter, across every page. |
POST /v1/admin/users/{user_id}/superadmin
Section titled “POST /v1/admin/users/{user_id}/superadmin”Grant or revoke another user’s platform-admin flag
Grants or revokes another user’s is_superadmin flag. Requires an existing superadmin. No self-promotion: you cannot change your own flag here or anywhere else.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
user_id | string | yes |
Request body (application/json)
{ "enabled": true}Response 200 (application/json)
{ "user_id": "11a75db9-...", "is_superadmin": true}404— No such user
PATCH /v1/admin/users/{user_id}
Section titled “PATCH /v1/admin/users/{user_id}”Edit a user’s account-wide name/active status
Changes a user’s account-wide name and is_active. Superadmin only. This is not a membership’s org-scoped status (PATCH /admin/organizations/{org_id}/members/{user_id}): deactivating a user here blocks login in every org they belong to. Returns the user, shaped like GET /auth/me’s user.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
user_id | string | yes |
Request body (application/json)
{ "name": "string", "is_active": true}Response 200 (application/json)
{ "user_id": "string", "email": "string", "name": "string", "created_at": "2026-01-01T00:00:00Z", "is_active": true, "two_factor_enabled": false, "has_password": true}| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | yes | |
email | string | yes | |
name | string | null | no | |
created_at | string (date-time) | yes | |
is_active | boolean | yes | |
two_factor_enabled | boolean | no | |
has_password | boolean | no | Whether the account has a local password, and so can use the password and two-factor endpoints under /auth/me. False for an account created through an SSO connection or a social login provider. |
404— No such user
POST /v1/admin/users/{user_id}/reset-password
Section titled “POST /v1/admin/users/{user_id}/reset-password”Reset a user’s password, account-wide
Account-wide password reset. Superadmin only. Clears the password and signs the account out everywhere, then emails a single-use link, valid for 30 minutes, and returns the same link once for handing over when the deployment sends no mail. Unlike the per-org resets, the user need not belong to any organization.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
user_id | string | yes |
Response 200 (application/json)
{ "reset_url": "string", "expires_at": "2026-01-01T00:00:00Z"}400— The account authenticates through SSO404— No such user
POST /v1/admin/users/{user_id}/2fa-reset
Section titled “POST /v1/admin/users/{user_id}/2fa-reset”Disable a user’s two-factor authentication, account-wide
Account-wide 2FA reset. Superadmin only. Clears the user’s TOTP secret and recovery codes. Unlike the per-org reset, the user need not belong to any organization.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
user_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— No such user
PATCH /v1/admin/organizations/{org_id}/lock
Section titled “PATCH /v1/admin/organizations/{org_id}/lock”Lock or unlock an organization
Locks or unlocks an organization. Superadmin only. Every org-scoped endpoint of a locked org answers 423, whatever the caller’s role: membership, keys, the product’s work, everything. The dashboard shows a full-page lock message instead of its normal shell. Login still succeeds and GET /auth/me reports organization_locked: true, so a member can see why nothing works. Unlocking is immediate.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "locked": true}Response 200 (application/json)
{ "org_id": "7c3c6e2e-...", "locked": true}404— Organization not found
PATCH /v1/admin/organizations/{org_id}/2fa-policy
Section titled “PATCH /v1/admin/organizations/{org_id}/2fa-policy”Require or stop requiring two-factor authentication for an organization
Requires, or stops requiring, two-factor authentication in an organization. Superadmin only, for the same reason as PATCH .../lock: an org admin could lock themselves out by turning it on before enrolling, or weaken security after a compromise by turning it off. While true, every org-scoped endpoint answers 403 to a human session whose user has not enrolled; API keys are exempt. Login still succeeds and GET /auth/me reports mfa_required: true, so the member can reach POST /auth/me/2fa/enroll.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "require_2fa": true}Response 200 (application/json)
{ "org_id": "7c3c6e2e-...", "require_2fa": true}404— Organization not found
PATCH /v1/admin/organizations/{org_id}/plan
Section titled “PATCH /v1/admin/organizations/{org_id}/plan”Set an organization’s plan tier, its contract terms, and optionally its trial usage
Sets an organization’s plan, its contract terms on enterprise, and optionally its trial usage. Superadmin only. There is no self-serve checkout: moving a customer between plans is a manual operator action. This applies only on a cloud deployment (deployment.mode); self-hosted deployments are always unlimited, so this endpoint cannot express an enterprise agreement for a self-hosted install, which is a support contract.
free: each meter is available until its lifetime trial allowance runs out, then returns402. Never billed.paid: every meter is unlimited; every unit of the billed meter is billed from the first, at the degressive rate.enterprise: every meter is unlimited; only units abovecontract.included_units_per_monthare billed, at the cheapest tier’s rate.
Every contract field is optional; an enterprise org with no contract is unlimited and never expires. Omit contract to leave the stored one untouched, so a downgrade keeps the paperwork for a later re-upgrade; send null to clear it. A contract with any other plan is a 422.
trial_usage ({"<meter>": 0}) sets the named meters’ counters to grant or reset a trial; meters not named are untouched.
A commitment is not a limit: going over included_units_per_month or past expires_at refuses nothing. Both show on GET /orgs/{org_id}/usage as overage_units and contract_expired for a person to act on. Audited as org.plan_update, with before and after.
In the dashboard: Platform Admin → Organizations → an org, Overview tab.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "plan_tier": "free", "trial_usage": { "key": 0 }, "contract": { "expires_at": "2026-01-01T00:00:00Z", "included_units_per_month": 0, "committed_amount_usd": 0, "reference": "string" }}| Field | Type | Required | Description |
|---|---|---|---|
plan_tier | "free" | "paid" | "enterprise" | yes | |
trial_usage | object | null | no | Set the lifetime trial counter of each meter named here — to grant or reset trial credit. Meters not named are left alone; null or omitted leaves every counter alone. Every key must be a registered meter. |
contract | OrgContract | null | no | Negotiated terms, for plan_tier=‘enterprise’. Omit the key entirely to leave whatever is stored untouched; send it explicitly as null to clear it. (Omitted and null are distinguished via model_fields_set — unlike trial_usage above, whose null and omitted both mean ‘leave alone’, because there is no such thing as clearing a counter.) Rejected with 422 when sent alongside a non-enterprise plan_tier: no other tier reads a contract, so writing one there is an operator mistake, not a no-op. |
Response 200 (application/json)
{ "org_id": "7c3c6e2e-...", "plan_tier": "enterprise", "contract": { "included_units_per_month": 5000 }}404— Organization not found
POST /v1/admin/organizations/{org_id}/cancel-deletion
Section titled “POST /v1/admin/organizations/{org_id}/cancel-deletion”Cancel a scheduled organization deletion
Clears pending_deletion_at. Superadmin only. It does not unlock the org: that stays a separate PATCH .../lock, since the lock may have been wanted on its own.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "org_id": "string", "pending_deletion_at": null}404— Organization not found409— Not scheduled for deletion
POST /v1/admin/organizations/purge-pending
Section titled “POST /v1/admin/organizations/purge-pending”Hard-delete every organization whose deletion grace period has elapsed
Superadmin only. Irreversibly deletes, through every org-scoped collection (members, teams, API keys and every collection a product registers), each organization whose pending_deletion_at is more than org_offboarding.grace_period_days old. audit_events and usage_events of a purged org are kept, orphaned by org_id. User documents are never deleted, only that org’s membership rows.
It does nothing when no organizations are due, so it is safe to call as often as needed; OpenTremor-task-scheduler’s heartbeat calls it. Unlike POST /admin/retention/run, it needs no self-gating, since an empty match is cheap. One org’s failure does not stop the batch: see errors. Always 200.
Response 200 (application/json)
{ "purged": [ { "org_id": "string", "name": "string" } ], "errors": [ { "org_id": "string", "error": "string" } ]}GET /v1/admin/settings
Section titled “GET /v1/admin/settings”Platform settings — effective values, current overrides, which secrets are set, and what’s excluded
Superadmin only. effective is each field’s hardcoded default with any stored override applied: what is in force now. overrides lists only the fields an admin changed. These sections are never read from the config file or the environment; every field applies to the next request, with no restart.
- Editable:
logging,registration,branding,social_login,server,session,retention,jobs,org_offboarding,rate_limit(thresholds only), and every section a mounted product registers. - Managed, not editable:
mcpandtelemetrykeep their defaults; they are read at startup, before an override could apply. - Excluded, file or environment only:
storage,cors,auth,jwt,two_factor,secrets,mail,worker,notificationsanddeployment.
excluded_sections lists the managed and excluded sections with the reason for each. ignored_file_settings lists the fields the config file sets anyway, with the value it sets: the platform ignored them at boot.
Response 200 (application/json)
{ "effective": {}, "overrides": {}, "secrets_set": {}, "ignored_file_settings": {}, "excluded_sections": [ { "section": "string", "reason": "string" } ], "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z", "deployment_mode": "self_hosted"}PATCH /v1/admin/settings
Section titled “PATCH /v1/admin/settings”Update platform settings
Superadmin only. Partial update: only fields in the body change. null clears a field’s override and falls back to the hardcoded default, never the config file. Fields are flat (server_max_input_size_mb, retention_audit_days, …). Returns the same shape as GET /admin/settings.
Changes apply to the next request. retention_telemetry_days and retention_audit_days are also pushed live to the running MongoDB TTL indexes with collMod. Secret fields (secrets_set lists them) are write-only: never returned, stored encrypted under secrets.encryption_key.
In the dashboard: one page per group of sections, under Platform Admin → Security, Connections and System.
Response 200 (application/json)
{ "effective": {}, "overrides": {}, "secrets_set": {}, "ignored_file_settings": {}, "excluded_sections": [ { "section": "string", "reason": "string" } ], "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z", "deployment_mode": "self_hosted"}POST /v1/admin/storage/prepare-mongodb
Section titled “POST /v1/admin/storage/prepare-mongodb”Prepare a target MongoDB instance for use as the storage backend
Superadmin only. The API form of opentremor-admin init-db: connects to uri/database (which need not be this instance’s database), creates every collection and index the app relies on, idempotently, and optionally a dedicated app user. It never changes which database this instance uses: that is storage.mongodb in the config file.
Omit app_username and app_password together to skip the user step; admin_uri serves only that step and defaults to uri. app_user_created is null when no user was requested and false when it already existed. uri and database are remembered for GET /admin/storage; the credentials are not.
In the dashboard: Platform Admin → System → Storage.
Request body (application/json)
{ "uri": "string", "database": "string", "admin_uri": "string", "app_username": "string", "app_password": "string"}Response 200 (application/json)
{ "database": "string", "collections_ensured": [ "string" ], "app_user_created": true}502— Could not connect to the target MongoDB, or the app-user step failed
GET /v1/admin/storage
Section titled “GET /v1/admin/storage”The database this instance uses, and the last MongoDB target prepared
The database this instance runs on, and the last uri/database used with prepare-mongodb (null if never), so the dashboard form can prefill. Superadmin only.
Response 200 (application/json)
{ "active_database": "string", "last_prepared": { "uri": "string", "database": "string", "updated_at": "2026-01-01T00:00:00Z" }}POST /v1/admin/retention/run
Section titled “POST /v1/admin/retention/run”Run a retention sweep now
Runs a retention sweep. Superadmin only. Self-gating by default: when retention.sweep_enabled is off, or the last real run is newer than retention.sweep_interval_hours, it returns the previous result with skipped: true instead, which makes it safe for OpenTremor-task-scheduler to call on a short heartbeat. force=true (the dashboard’s Run sweep now) always runs.
counts is keyed by sweep step, not a fixed set: the installed modules register the steps (a standard install registers findings_purged and resources_redacted), so render whatever keys come back. {} means nothing ran. error is set when the sweep failed partway; counts still shows what completed.
In the dashboard: Platform Admin → System → Data Lifecycle.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
force | boolean | no |
Response 200 (application/json)
{ "started_at": "2026-01-01T00:00:00Z", "duration_ms": 0, "counts": { "key": 0 }, "error": "string", "skipped": false}GET /v1/admin/retention/status
Section titled “GET /v1/admin/retention/status”Last retention sweep’s result
The last real retention sweep’s result, shaped like POST /admin/retention/run’s; fields are null if no sweep has run. Superadmin only.
Response 200 (application/json)
{ "started_at": "2026-01-01T00:00:00Z", "duration_ms": 0, "counts": { "key": 0 }, "error": "string", "skipped": false}POST /v1/admin/jobs/sweep
Section titled “POST /v1/admin/jobs/sweep”Run a stuck-job sweep now
Runs a stuck-job sweep across every org. Superadmin only. It re-queues each running job whose worker’s lease expired (or fails it once it used jobs.max_attempts), and marks failed every running job, and every in-process job still queued, with no progress in over jobs.stuck_timeout_minutes. Self-gating like POST /admin/retention/run, on jobs.sweep_enabled and jobs.sweep_interval_hours; force=true always runs. A job it failed can be resumed with POST /jobs/{job_id}/retry.
In the dashboard: Platform Admin → System → Jobs.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
force | boolean | no |
Response 200 (application/json)
{ "started_at": "2026-01-01T00:00:00Z", "duration_ms": 0, "jobs_marked_failed": 0, "jobs_requeued": 0, "error": "string", "skipped": false}GET /v1/admin/jobs/sweep-status
Section titled “GET /v1/admin/jobs/sweep-status”Last stuck-job sweep’s result
The last real stuck-job sweep’s result, shaped like POST /admin/jobs/sweep’s; fields are null if no sweep has run. Superadmin only.
Response 200 (application/json)
{ "started_at": "2026-01-01T00:00:00Z", "duration_ms": 0, "jobs_marked_failed": 0, "jobs_requeued": 0, "error": "string", "skipped": false}GET /v1/admin/diagnostics
Section titled “GET /v1/admin/diagnostics”Download the support bundle
A zip to read and send when this install misbehaves: versions, checks, the effective configuration, the last 500 log lines at warning and above from the replica that answers, and the last 20 failed jobs. Every secret is redacted, and nothing is sent anywhere. Superadmin only. Each download is recorded in the audit log as diagnostics.download.
In the dashboard: Platform Admin → System → General → Download diagnostics.
200— The bundle
GET /v1/admin/migrations
Section titled “GET /v1/admin/migrations”List schema migrations
Every migration applied to this database, newest first, and the ones this image knows but has not applied. Pending migrations run at startup, so pending is empty on a server that serves requests.
In the dashboard: Platform Admin → System → Migrations.
Response 200 (application/json)
{ "applied": [ { "id": "string", "summary": "string", "applied_at": "2026-01-01T00:00:00Z", "changed": 0, "duration_ms": 0 } ], "pending": [ { "id": "string", "summary": "string" } ]}| Field | Type | Required | Description |
|---|---|---|---|
applied | AppliedMigration[] | yes | Newest first. |
pending | PendingMigration[] | yes | Known to this image and not applied yet. Empty once the server has started: pending migrations run before it serves requests. |
GET /v1/admin/custom-rules
Section titled “GET /v1/admin/custom-rules”List custom rules across every organization
Platform-admin only. Omit org_id to see every org’s rules; pass it to scope the view to one org (still cross-tenant — no membership required).
Filters: pack, category, rule_type, enabled.
In the dashboard: Platform Admin → Catalog → Rules.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | null | no | |
pack | string | null | no | |
category | string | null | no | |
rule_type | string | null | no | |
enabled | boolean | null | no |
Response 200 (application/json)
{ "rules": [ { "rule_id": "string", "org_id": "string", "title": "string", "description": "string", "category": "string", "severity": "CRITICAL", "packs": [ "string" ], "rule_type": "string", "enabled": true, "requires_review": false, "scope": { "team_ids": [ "string" ], "repositories": [ { "provider": "github", "external_id": "string" } ], "product_ids": [ "string" ] }, "is_builtin_seed": false, "origin": { "kind": "adr", "repository": { "provider": "github", "external_id": "string" }, "path": "string", "commit_sha": "string", "blob_sha": "string", "excerpt": "string" }, "builtin_id": "string", "pack_update": { "rule_type": "aws", "title": "string", "severity": "CRITICAL", "category": "string", "description": "string" }, "created_by": "string", "created_at": "string", "updated_at": "string" } ]}GET /v1/admin/custom-rules/{org_id}/{rule_id}
Section titled “GET /v1/admin/custom-rules/{org_id}/{rule_id}”Get one organization’s custom rule
One organization’s custom rule. Superadmin only.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
rule_id | string | yes |
Response 200 (application/json)
{ "rule_id": "string", "org_id": "string", "title": "string", "description": "string", "category": "string", "severity": "CRITICAL", "packs": [ "string" ], "rule_type": "string", "enabled": true, "requires_review": false, "scope": { "team_ids": [ "string" ], "repositories": [ { "provider": "github", "external_id": "string" } ], "product_ids": [ "string" ] }, "is_builtin_seed": false, "origin": { "kind": "adr", "repository": { "provider": "github", "external_id": "string" }, "path": "string", "commit_sha": "string", "blob_sha": "string", "excerpt": "string" }, "builtin_id": "string", "pack_update": { "rule_type": "aws", "title": "string", "severity": "CRITICAL", "category": "string", "description": "string" }, "created_by": "string", "created_at": "string", "updated_at": "string"}| Field | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes | |
title | string | yes | |
description | string | yes | |
category | string | yes | |
severity | SeverityLevel | yes | |
packs | string[] | yes | |
rule_type | string | null | no | |
enabled | boolean | yes | |
requires_review | boolean | no | |
scope | RuleScope | null | no | |
is_builtin_seed | boolean | no | True for a rule imported from a pack’s built-in ruleset at org setup (dashboard badge). Seeded rows default to enabled=True. A seeded row replaces its rule in the pack file, enabled or not: disabling it removes the rule from the ruleset, and the file’s wording never comes back. |
origin | RuleOrigin | null | no | The repository file this rule was drawn from; null for a rule a person wrote |
builtin_id | string | null | no | For a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote |
pack_update | PackRuleVariant | null | no | For a seeded rule the org edited: the pack file’s new wording, set when the file changed the rule after the org’s edit. POST …/rules/{rule_id}/reset takes it. |
created_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
404— Rule not found
GET /v1/admin/analysis/metrics/summary
Section titled “GET /v1/admin/analysis/metrics/summary”Platform-wide resources analysed and findings produced, broken down by organization
Platform-admin only — cross-org rollup of the same aggregation GET /analysis/metrics/summary (metrics:read, own org) computes for a single org.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
days | integer | no | Number of days to aggregate |
Response 200 (application/json)
{ "period_days": 0, "resources_analyzed_total": 0, "findings_total": 0, "by_org": [ { "org_id": "string", "name": "string", "resources_analyzed_total": 0, "findings_total": 0 } ]}POST /v1/admin/jira/sync
Section titled “POST /v1/admin/jira/sync”Bring every org’s Jira issues up to date with their findings
Platform-admin only. Safe for OpenTremor-task-scheduler to call every minute: an org synced by another call right now, backing off after a failure, paused, or locked is skipped, and nothing runs while jira.enabled is off.
Response 200 (application/json)
{ "orgs": 0, "created": 0, "updated": 0, "failed": 0, "goal_updates": 0}| Field | Type | Required | Description |
|---|---|---|---|
orgs | integer | yes | Orgs synced on this tick |
created | integer | yes | |
updated | integer | yes | |
failed | integer | yes | Orgs whose sync failed and now backs off |
goal_updates | integer | no | Comments and moves to Done on goal step issues |
Pricing
Section titled “Pricing”One price list for the whole instance. It prices the billed meter for orgs on the paid plan and the overage of enterprise orgs. Pricing is degressive: each tier prices only the units that fall inside it.
GET /v1/pricing
Section titled “GET /v1/pricing”Current metered pricing tiers
Public, no authentication: what the marketing pricing page renders. Returns the built-in defaults until a platform admin changes them with PATCH /admin/pricing.
up_to is where a tier ends, in units per month, counted from the first unit: with tiers ending at 1,000 and 10,000, units 1,001 to 10,000 cost the second tier’s price. Each tier prices only the units inside it. up_to: null means “and beyond”, on the last tier only.
Response 200 (application/json)
{ "tiers": [ { "up_to": 1, "price_per_unit_usd": 0 } ], "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z"}GET /v1/admin/pricing
Section titled “GET /v1/admin/pricing”Current metered pricing tiers (platform-admin view)
Superadmin only. The same data as GET /pricing.
Response 200 (application/json)
{ "tiers": [ { "up_to": 1, "price_per_unit_usd": 0 } ], "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z"}PATCH /v1/admin/pricing
Section titled “PATCH /v1/admin/pricing”Replace the metered pricing tiers
Superadmin only. Replaces the whole list. Tiers must be strictly ascending by up_to, end with up_to: null, and never rise in price_per_unit_usd (degressive pricing). The new tiers apply to the next GET /orgs/{org_id}/usage and the next load of the public pricing page.
In the dashboard: Platform Admin → Billing → Pricing.
Request body (application/json)
{ "tiers": [ { "up_to": 1, "price_per_unit_usd": 0 } ]}Response 200 (application/json)
{ "tiers": [ { "up_to": 1, "price_per_unit_usd": 0 } ], "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z"}Network access
Section titled “Network access”Address lists and per-path source rules for the API, the dashboard and the docs (OpenTremor-platform#0021), and the denial events they record. Every route requires a superadmin.
GET /v1/admin/network-access/lists
Section titled “GET /v1/admin/network-access/lists”List address lists
Response 200 (application/json)
{ "lists": [ { "list_id": "string", "name": "string", "entry_type": "ip", "source": "static", "description": "string", "entries": [ "string" ], "url": "string", "file": "string", "selector": [ "string" ], "refresh_hours": 0, "status": { "last_success_at": "2026-01-01T00:00:00Z", "last_error": "string", "entry_count": 0 }, "resolved": [ "string" ], "used_by": [ "string" ], "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ]}POST /v1/admin/network-access/lists
Section titled “POST /v1/admin/network-access/lists”Create an address list
A url or file list is fetched before this returns; a failed fetch still creates the list, with the error in status.last_error.
Request body (application/json)
{ "description": "string", "entries": [ "string" ], "url": "string", "file": "string", "selector": [ "string" ], "refresh_hours": 24, "name": "string", "entry_type": "ip", "source": "static"}| Field | Type | Required | Description |
|---|---|---|---|
description | string | null | no | |
entries | string[] | null | no | static only. |
url | string | null | no | url only. HTTPS, checked by the egress rules. |
file | string | null | no | file only. A path relative to network.list_sources_dir. |
selector | string[] | null | no | url and file: the JSON keys whose values are collected, e.g. [“hooks”] for a code host’s published ranges. Unset: plain text, one entry per line, # starts a comment. |
refresh_hours | integer | no | url and file only. |
name | string | yes | |
entry_type | "ip" | "host" | yes | |
source | "static" | "url" | "file" | yes |
Response 201 (application/json)
{ "list_id": "string", "name": "string", "entry_type": "ip", "source": "static", "description": "string", "entries": [ "string" ], "url": "string", "file": "string", "selector": [ "string" ], "refresh_hours": 0, "status": { "last_success_at": "2026-01-01T00:00:00Z", "last_error": "string", "entry_count": 0 }, "resolved": [ "string" ], "used_by": [ "string" ], "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}409— Conflict
GET /v1/admin/network-access/lists/presets
Section titled “GET /v1/admin/network-access/lists/presets”Ready-made address list definitions
Response 200 (application/json)
{ "presets": [ { "name": "string", "label": "string", "entry_type": "ip", "url": "string", "selector": [ "string" ], "suggested_service": "api", "suggested_path": "string", "on_by_default": false } ]}GET /v1/admin/network-access/lists/{list_id}
Section titled “GET /v1/admin/network-access/lists/{list_id}”Get an address list
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id | string | yes |
Response 200 (application/json)
{ "list_id": "string", "name": "string", "entry_type": "ip", "source": "static", "description": "string", "entries": [ "string" ], "url": "string", "file": "string", "selector": [ "string" ], "refresh_hours": 0, "status": { "last_success_at": "2026-01-01T00:00:00Z", "last_error": "string", "entry_count": 0 }, "resolved": [ "string" ], "used_by": [ "string" ], "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}PATCH /v1/admin/network-access/lists/{list_id}
Section titled “PATCH /v1/admin/network-access/lists/{list_id}”Change an address list
Name, entry type and source are fixed. A changed URL, file or selector is fetched before this returns.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id | string | yes |
Request body (application/json)
{ "description": "string", "entries": [ "string" ], "url": "string", "file": "string", "selector": [ "string" ], "refresh_hours": 1}Response 200 (application/json)
{ "list_id": "string", "name": "string", "entry_type": "ip", "source": "static", "description": "string", "entries": [ "string" ], "url": "string", "file": "string", "selector": [ "string" ], "refresh_hours": 0, "status": { "last_success_at": "2026-01-01T00:00:00Z", "last_error": "string", "entry_count": 0 }, "resolved": [ "string" ], "used_by": [ "string" ], "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}404— Not Found
DELETE /v1/admin/network-access/lists/{list_id}
Section titled “DELETE /v1/admin/network-access/lists/{list_id}”Delete an address list
409 while a network rule or an egress policy names it — the response names them.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found409— Conflict
POST /v1/admin/network-access/lists/{list_id}/refresh
Section titled “POST /v1/admin/network-access/lists/{list_id}/refresh”Fetch an address list’s source now
A failed fetch keeps the previous entries; status.last_error says why.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id | string | yes |
Response 200 (application/json)
{ "list_id": "string", "name": "string", "entry_type": "ip", "source": "static", "description": "string", "entries": [ "string" ], "url": "string", "file": "string", "selector": [ "string" ], "refresh_hours": 0, "status": { "last_success_at": "2026-01-01T00:00:00Z", "last_error": "string", "entry_count": 0 }, "resolved": [ "string" ], "used_by": [ "string" ], "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}404— Not Found409— Conflict
GET /v1/admin/network-access/rules
Section titled “GET /v1/admin/network-access/rules”List network access rules
Response 200 (application/json)
{ "rules": [ { "rule_id": "string", "service": "api", "path_prefix": "string", "lists": [ "string" ], "cidrs": [ "string" ], "mode": "enforce", "description": "string", "denied_24h": 0, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ]}POST /v1/admin/network-access/rules
Section titled “POST /v1/admin/network-access/rules”Create a network access rule
Request body (application/json)
{ "lists": [ "string" ], "cidrs": [ "string" ], "mode": "report", "description": "string", "service": "api", "path_prefix": "string"}| Field | Type | Required | Description |
|---|---|---|---|
lists | string[] | no | Names of ip address lists. |
cidrs | string[] | no | Extra IPs or CIDRs, for one-offs. |
mode | "enforce" | "report" | no | |
description | string | null | no | |
service | "api" | "dashboard" | "docs" | yes | |
path_prefix | string | yes |
Response 201 (application/json)
{ "rule_id": "string", "service": "api", "path_prefix": "string", "lists": [ "string" ], "cidrs": [ "string" ], "mode": "enforce", "description": "string", "denied_24h": 0, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}409— Conflict
PATCH /v1/admin/network-access/rules/{rule_id}
Section titled “PATCH /v1/admin/network-access/rules/{rule_id}”Change a network access rule
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes |
Request body (application/json)
{ "lists": [ "string" ], "cidrs": [ "string" ], "mode": "enforce", "description": "string"}Response 200 (application/json)
{ "rule_id": "string", "service": "api", "path_prefix": "string", "lists": [ "string" ], "cidrs": [ "string" ], "mode": "enforce", "description": "string", "denied_24h": 0, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}404— Not Found409— Conflict
DELETE /v1/admin/network-access/rules/{rule_id}
Section titled “DELETE /v1/admin/network-access/rules/{rule_id}”Delete a network access rule
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found409— Conflict
GET /v1/admin/network-access
Section titled “GET /v1/admin/network-access”Network access overview — the firewall view
Response 200 (application/json)
{ "filter_enabled": true, "caller": { "client_ip": "string", "peer": "string", "forwarded_for": [ "string" ], "trusted_hops": [ "string" ] }, "trusted_proxies": [ "string" ], "rules": [ { "rule_id": "string", "service": "api", "path_prefix": "string", "lists": [ "string" ], "cidrs": [ "string" ], "mode": "enforce", "description": "string", "denied_24h": 0, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ], "lists": [ { "list_id": "string", "name": "string", "entry_type": "ip", "source": "static", "description": "string", "entries": [ "string" ], "url": "string", "file": "string", "selector": [ "string" ], "refresh_hours": 0, "status": { "last_success_at": "2026-01-01T00:00:00Z", "last_error": "string", "entry_count": 0 }, "resolved": [ "string" ], "used_by": [ "string" ], "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ], "key_allowlists": [ { "org_id": "string", "org_name": "string", "key_id": "string", "key_name": "string", "ip_allowlist": [ "string" ], "last_refused_ip": "string", "last_refused_at": "2026-01-01T00:00:00Z" } ], "events_retention_days": 0}| Field | Type | Required | Description |
|---|---|---|---|
filter_enabled | boolean | yes | |
caller | CallerAddress | yes | How this server sees the admin calling it: the resolved address and the hops behind it. |
trusted_proxies | string[] | yes | |
rules | RuleInfo[] | yes | |
lists | AddressListInfo[] | yes | |
key_allowlists | KeyAllowlistRow[] | yes | |
events_retention_days | integer | yes |
POST /v1/admin/network-access/check
Section titled “POST /v1/admin/network-access/check”Trace a request through the network rules and an API key’s allowlist
Uses the rules as stored now, ignoring report mode: would_deny marks a rule in report mode that matches but lets the request through.
Request body (application/json)
{ "service": "api", "ip": "string", "path": "string", "api_key_id": "string"}Response 200 (application/json)
{ "allowed": true, "layers": [ { "layer": "rule", "verdict": "allow", "decided_by": "string", "matched": "string" } ]}GET /v1/admin/network-access/events
Section titled “GET /v1/admin/network-access/events”Denial events, newest first
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
service | "api" | "dashboard" | "docs" | null | no | |
layer | "rule" | "key" | null | no | |
ip | string | null | no | |
ref_id | string | null | no | A rule ID or an API key ID. |
since | string (date-time) | null | no | |
before | string (date-time) | null | no | Pass the previous page’s next_before. |
limit | integer | no |
Response 200 (application/json)
{ "events": [ { "timestamp": "2026-01-01T00:00:00Z", "layer": "rule", "service": "api", "path": "string", "client_ip": "string", "forwarded_for": [ "string" ], "ref_id": "string", "org_id": "string", "mode": "enforce", "request_id": "string", "count": 0 } ], "next_before": "2026-01-01T00:00:00Z"}GET /v1/admin/network-access/events/top-sources
Section titled “GET /v1/admin/network-access/events/top-sources”The most-denied addresses
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
hours | integer | no | |
limit | integer | no |
Response 200 (application/json)
{ "sources": [ { "client_ip": "string", "count": 0, "top_ref_id": "string" } ]}Backups
Section titled “Backups”Scheduled backups of the whole database (OpenTremor-platform#0038), encrypted with age to public keys. A platform admin sets the keys under /admin/backups/keys: each change is proven with the identity, re-authenticated, delayed 24 hours and emailed (OpenTremor-platform#0039). BACKUP_AGE_RECIPIENTS pins them instead. The schedule, retention and target are the backup settings. Superadmin only. Restoring is a command-line procedure, not an endpoint.
GET /v1/admin/backups/keys
Section titled “GET /v1/admin/backups/keys”List the backup encryption keys
The age public keys backups are encrypted to, with each one’s state. source is environment when BACKUP_AGE_RECIPIENTS sets them; the list is then read-only.
In the dashboard: Platform Admin → Backups → Encryption key.
Response 200 (application/json)
{ "source": "environment", "environment_recipients": [ "string" ], "keys": [ { "key_id": "string", "recipient": "string", "label": "string", "state": "pending", "added_by": "string", "requested_at": "2026-01-01T00:00:00Z", "active_from": "2026-01-01T00:00:00Z", "removal_requested_by": "string", "removed_from": "2026-01-01T00:00:00Z" } ], "delay_hours": 0, "proof": "two_factor"}| Field | Type | Required | Description |
|---|---|---|---|
source | "environment" | "dashboard" | yes | environment: the operator sets the keys and this list is read-only. |
environment_recipients | string[] | no | The keys BACKUP_AGE_RECIPIENTS sets, when source is environment. |
keys | BackupKeyInfo[] | yes | |
delay_hours | integer | yes | How long a change waits before it takes effect. |
proof | "two_factor" | "password" | null | yes | What the caller confirms a change with. None: this account cannot change keys. |
POST /v1/admin/backups/keys
Section titled “POST /v1/admin/backups/keys”Add a backup encryption key
Needs the challenge’s decrypted answer and a 2FA code, or the password for an account without 2FA. The key takes effect in 24 hours, or at once when no key is in force. Every superadmin is emailed.
Request body (application/json)
{ "password": "string", "code": "string", "challenge": "string", "answer": "string", "label": "string"}| Field | Type | Required | Description |
|---|---|---|---|
password | string | null | no | |
code | string | null | no | |
challenge | string | yes | |
answer | string | yes | The decrypted message. |
label | string | yes | Where the identity is kept, e.g. Vault, office safe. |
Response 201 (application/json)
{ "key_id": "string", "recipient": "string", "label": "string", "state": "pending", "added_by": "string", "requested_at": "2026-01-01T00:00:00Z", "active_from": "2026-01-01T00:00:00Z", "removal_requested_by": "string", "removed_from": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
key_id | string | yes | |
recipient | string | yes | The age public key (age1…). The private key is never sent. |
label | string | yes | |
state | "pending" | "active" | "removing" | yes | pending until active_from; active; removing until removed_from. |
added_by | string | null | no | Email of the platform admin who added it. |
requested_at | string (date-time) | yes | |
active_from | string (date-time) | yes | |
removal_requested_by | string | null | no | |
removed_from | string (date-time) | null | no |
400— Bad Request401— Unauthorized403— Forbidden409— Conflict
POST /v1/admin/backups/keys/challenge
Section titled “POST /v1/admin/backups/keys/challenge”Get a challenge for a new key
Encrypts a random message to the key. Decrypt it with the matching identity, in the browser or with age -d, and send the answer to POST /admin/backups/keys within 10 minutes. This proves the identity was saved before backups depend on it.
Request body (application/json)
{ "recipient": "string"}| Field | Type | Required | Description |
|---|---|---|---|
recipient | string | yes | The age public key to add (age1…). |
Response 200 (application/json)
{ "challenge": "string", "ciphertext": "string"}| Field | Type | Required | Description |
|---|---|---|---|
challenge | string | yes | Signed token to send back with the answer. Valid 10 minutes. |
ciphertext | string | yes | The age-encrypted message, base64. Decrypt it with the identity. |
409— Conflict
POST /v1/admin/backups/keys/{key_id}/remove
Section titled “POST /v1/admin/backups/keys/{key_id}/remove”Remove a backup encryption key
Backups stop being encrypted to the key in 24 hours. Needs a 2FA code, or the password for an account without 2FA. Every superadmin is emailed. Backups already written stay encrypted to it: keep its identity while they are kept.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
key_id | string | yes |
Request body (application/json)
{ "password": "string", "code": "string"}Response 200 (application/json)
{ "key_id": "string", "recipient": "string", "label": "string", "state": "pending", "added_by": "string", "requested_at": "2026-01-01T00:00:00Z", "active_from": "2026-01-01T00:00:00Z", "removal_requested_by": "string", "removed_from": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
key_id | string | yes | |
recipient | string | yes | The age public key (age1…). The private key is never sent. |
label | string | yes | |
state | "pending" | "active" | "removing" | yes | pending until active_from; active; removing until removed_from. |
added_by | string | null | no | Email of the platform admin who added it. |
requested_at | string (date-time) | yes | |
active_from | string (date-time) | yes | |
removal_requested_by | string | null | no | |
removed_from | string (date-time) | null | no |
401— Unauthorized403— Forbidden404— Not Found409— Conflict
POST /v1/admin/backups/keys/{key_id}/cancel
Section titled “POST /v1/admin/backups/keys/{key_id}/cancel”Cancel a pending key change
Drops a key that has not taken effect yet, or keeps a key whose removal is pending. No re-authentication: it only keeps things as they are.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
key_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found409— Conflict
GET /v1/admin/backups
Section titled “GET /v1/admin/backups”Backup status and recent runs
Whether backups can run (problems lists what is missing), the last success, and the 50 newest runs.
In the dashboard: Platform Admin → Backups.
Response 200 (application/json)
{ "enabled": true, "target": "local", "interval_hours": 0, "retention_days": 0, "recipients": 0, "key_source": "environment", "local_dir": "string", "problems": [ "string" ], "last_success_at": "2026-01-01T00:00:00Z", "overdue": true, "runs": [ { "run_id": "string", "status": "running", "trigger": "schedule", "target": "local", "location": "string", "bucket": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "size_bytes": 0, "sha256": "string", "documents": { "key": 0 }, "recipients": 0, "recipient_keys": [ "string" ], "error": "string" } ]}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | yes | |
target | "local" | "s3" | yes | |
interval_hours | integer | yes | |
retention_days | integer | yes | |
recipients | integer | yes | How many age recipients backups are encrypted to now. |
key_source | "environment" | "dashboard" | yes | environment when BACKUP_AGE_RECIPIENTS or the configuration file sets the recipients, which locks them; dashboard otherwise. |
local_dir | string | yes | Where the local target keeps backups (BACKUP_LOCAL_DIR). |
problems | string[] | yes | Why a backup cannot run now. Empty when the configuration is complete. |
last_success_at | string (date-time) | null | no | |
overdue | boolean | yes | True when backups are enabled and the last success is older than twice the interval. |
runs | BackupRunInfo[] | yes |
POST /v1/admin/backups
Section titled “POST /v1/admin/backups”Start a backup now
Starts a backup in the background, whether or not backup.enabled is on. 409 when one is already running or the configuration is incomplete.
Response 202 (application/json)
{ "run_id": "string", "status": "running", "trigger": "schedule", "target": "local", "location": "string", "bucket": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "size_bytes": 0, "sha256": "string", "documents": { "key": 0 }, "recipients": 0, "recipient_keys": [ "string" ], "error": "string"}| Field | Type | Required | Description |
|---|---|---|---|
run_id | string | yes | |
status | "running" | "succeeded" | "failed" | yes | |
trigger | "schedule" | "manual" | "migration" | yes | |
target | "local" | "s3" | yes | |
location | string | null | no | The file name in backup.local_dir, or the object key in the bucket. |
bucket | string | null | no | |
started_at | string (date-time) | yes | |
finished_at | string (date-time) | null | no | |
size_bytes | integer | null | no | Size of the encrypted file. |
sha256 | string | null | no | SHA-256 of the encrypted file, to check a download. |
documents | object | null | no | Documents written, per collection. |
recipients | integer | null | no | How many age recipients the file is encrypted to. |
recipient_keys | string[] | no | The age public keys the file is encrypted to: which identity opens it. |
error | string | null | no |
409— Conflict
POST /v1/admin/backups/tick
Section titled “POST /v1/admin/backups/tick”Start a backup if one is due
The task scheduler calls this every 15 minutes. It marks failed any run whose server stopped, deletes runs past backup.retention_days (never the newest successful one), and starts a backup when backup.enabled is on and the last success is older than backup.interval_hours. After a failure it waits an hour before trying again.
Response 200 (application/json)
{ "started": "string", "skipped": "string", "expired": 0, "pruned": 0}| Field | Type | Required | Description |
|---|---|---|---|
started | string | null | no | The run started by this tick. |
skipped | string | null | no | Why no run started: disabled, not_due, running or misconfigured. |
expired | integer | no | Runs marked failed because their server stopped. |
pruned | integer | no | Runs deleted by retention. |
GET /v1/admin/backups/{run_id}
Section titled “GET /v1/admin/backups/{run_id}”Get one backup run
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
run_id | string | yes |
Response 200 (application/json)
{ "run_id": "string", "status": "running", "trigger": "schedule", "target": "local", "location": "string", "bucket": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "size_bytes": 0, "sha256": "string", "documents": { "key": 0 }, "recipients": 0, "recipient_keys": [ "string" ], "error": "string"}| Field | Type | Required | Description |
|---|---|---|---|
run_id | string | yes | |
status | "running" | "succeeded" | "failed" | yes | |
trigger | "schedule" | "manual" | "migration" | yes | |
target | "local" | "s3" | yes | |
location | string | null | no | The file name in backup.local_dir, or the object key in the bucket. |
bucket | string | null | no | |
started_at | string (date-time) | yes | |
finished_at | string (date-time) | null | no | |
size_bytes | integer | null | no | Size of the encrypted file. |
sha256 | string | null | no | SHA-256 of the encrypted file, to check a download. |
documents | object | null | no | Documents written, per collection. |
recipients | integer | null | no | How many age recipients the file is encrypted to. |
recipient_keys | string[] | no | The age public keys the file is encrypted to: which identity opens it. |
error | string | null | no |
404— Not Found
DELETE /v1/admin/backups/{run_id}
Section titled “DELETE /v1/admin/backups/{run_id}”Delete a backup
Deletes the file from its target, then the run. 409 while it runs. When the file cannot be deleted (502), the run is kept so the file is not forgotten.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
run_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found409— Conflict502— Bad Gateway
GET /v1/admin/backups/{run_id}/download
Section titled “GET /v1/admin/backups/{run_id}/download”Download a backup file
The encrypted file of a successful local backup. Only the holder of an age identity matching one of the run’s recipient_keys can decrypt it. A backup stored in a bucket is downloaded from the bucket (409).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
run_id | string | yes |
200404— Not Found409— Conflict