Skip to content
DashboardWebsite

Endpoints: 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.

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 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

NameTypeRequiredDescription
org_idstringyes

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"
}
}
FieldTypeRequiredDescription
org_idstringyes
namestringyes
slugstringyes
plan_tier"free" | "paid" | "enterprise"yes
trial_usageobjectno
contractOrgContract | nullnoThe 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_expiredbooleannoContract 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_countintegeryes
monthly_budget_usdnumber | nullyes
current_month_cost_usdnumberyes
created_atstring (date-time)yes
lockedbooleanyes
require_2fabooleanno
sso_enabledbooleanno
pending_deletion_atstring (date-time) | nullno
ssoSSOConnectionInfo | nullno
  • 404 — Organization not found

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"org_id": "string",
"pending_deletion_at": "2026-01-01T00:00:00Z",
"purge_after": "2026-01-01T00:00:00Z"
}
FieldTypeRequiredDescription
org_idstringyes
pending_deletion_atstring (date-time)yes
purge_afterstring (date-time)yespending_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 found
  • 409 — 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

NameTypeRequiredDescription
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes
user_idstringyes

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"
}
FieldTypeRequiredDescription
user_idstringyes
emailstringyes
namestring | nullno
rolestringyes
is_activebooleannoOrg-scoped — see Membership.is_active. Distinct from account_active.
account_activebooleannoAccount-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_atstring (date-time)yes
teamsstring[]noNames 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" | nullnoSee Membership.provisioned_via.
  • 400 — Targets the caller’s own membership
  • 404 — Organization or membership not found
  • 409 — 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

NameTypeRequiredDescription
org_idstringyes
user_idstringyes
  • 200
  • 204 — No Content
  • 400 — Targets the caller’s own membership
  • 404 — Organization or membership not found
  • 409 — 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

NameTypeRequiredDescription
org_idstringyes
user_idstringyes

Response 200 (application/json)

{
"reset_url": "string",
"expires_at": "2026-01-01T00:00:00Z"
}
  • 400 — The account authenticates through SSO
  • 404 — 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

NameTypeRequiredDescription
org_idstringyes
user_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — Organization or membership not found

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
}
]
}

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

NameTypeRequiredDescription
daysintegernoNumber 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

NameTypeRequiredDescription
org_idstringyes

Query parameters

NameTypeRequiredDescription
actionstring | nullnoFilter by action, e.g. ‘settings.update’
actor_idstring | nullnoFilter by actor — matches either a user_id or a key_id
target_typestring | nullnoFilter by target type, e.g. ‘api_key’
sincestring | nullnoISO-8601 lower bound (inclusive)
untilstring | nullnoISO-8601 upper bound (inclusive)
limitintegerno
offsetintegerno

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

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

NameTypeRequiredDescription
org_idstring | nullnoRestrict to one org; omit for all orgs
actionstring | nullno
actor_idstring | nullno
target_typestring | nullno
sincestring | nullno
untilstring | nullno
limitintegerno
offsetintegerno

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
}

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

NameTypeRequiredDescription
formatstringno‘json’ or ‘csv’
org_idstring | nullnoRestrict to one org; omit for all orgs
actionstring | nullno
actor_idstring | nullno
target_typestring | nullno
sincestring | nullno
untilstring | nullno
limitintegerno
  • 200

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

NameTypeRequiredDescription
qstring | nullnoCase-insensitive substring of the email, the name or an org’s name
limitintegerno
offsetintegerno

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
}
FieldTypeRequiredDescription
usersPlatformUserSummary[]yes
totalintegeryesUsers matching the filter, across every page.

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

NameTypeRequiredDescription
user_idstringyes

Request body (application/json)

{
"enabled": true
}

Response 200 (application/json)

{
"user_id": "11a75db9-...",
"is_superadmin": true
}
  • 404 — No such user

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

NameTypeRequiredDescription
user_idstringyes

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
}
FieldTypeRequiredDescription
user_idstringyes
emailstringyes
namestring | nullno
created_atstring (date-time)yes
is_activebooleanyes
two_factor_enabledbooleanno
has_passwordbooleannoWhether 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

NameTypeRequiredDescription
user_idstringyes

Response 200 (application/json)

{
"reset_url": "string",
"expires_at": "2026-01-01T00:00:00Z"
}
  • 400 — The account authenticates through SSO
  • 404 — No such user

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

NameTypeRequiredDescription
user_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

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 returns 402. 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 above contract.included_units_per_month are 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

NameTypeRequiredDescription
org_idstringyes

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"
}
}
FieldTypeRequiredDescription
plan_tier"free" | "paid" | "enterprise"yes
trial_usageobject | nullnoSet 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.
contractOrgContract | nullnoNegotiated 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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"org_id": "string",
"pending_deletion_at": null
}
  • 404 — Organization not found
  • 409 — 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"
}
]
}

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: mcp and telemetry keep 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, notifications and deployment.

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"
}

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"
}

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

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"
}
}

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

NameTypeRequiredDescription
forcebooleanno

Response 200 (application/json)

{
"started_at": "2026-01-01T00:00:00Z",
"duration_ms": 0,
"counts": {
"key": 0
},
"error": "string",
"skipped": false
}

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
}

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

NameTypeRequiredDescription
forcebooleanno

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
}

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
}

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

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"
}
]
}
FieldTypeRequiredDescription
appliedAppliedMigration[]yesNewest first.
pendingPendingMigration[]yesKnown to this image and not applied yet. Empty once the server has started: pending migrations run before it serves requests.

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

NameTypeRequiredDescription
org_idstring | nullno
packstring | nullno
categorystring | nullno
rule_typestring | nullno
enabledboolean | nullno

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

NameTypeRequiredDescription
org_idstringyes
rule_idstringyes

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"
}
FieldTypeRequiredDescription
rule_idstringyes
org_idstringyes
titlestringyes
descriptionstringyes
categorystringyes
severitySeverityLevelyes
packsstring[]yes
rule_typestring | nullno
enabledbooleanyes
requires_reviewbooleanno
scopeRuleScope | nullno
is_builtin_seedbooleannoTrue 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.
originRuleOrigin | nullnoThe repository file this rule was drawn from; null for a rule a person wrote
builtin_idstring | nullnoFor a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote
pack_updatePackRuleVariant | nullnoFor 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_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 404 — Rule not found

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

NameTypeRequiredDescription
daysintegernoNumber 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
}
]
}

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
}
FieldTypeRequiredDescription
orgsintegeryesOrgs synced on this tick
createdintegeryes
updatedintegeryes
failedintegeryesOrgs whose sync failed and now backs off
goal_updatesintegernoComments and moves to Done on goal step issues

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.

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"
}

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"
}

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"
}

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.

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"
}
]
}

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"
}
FieldTypeRequiredDescription
descriptionstring | nullno
entriesstring[] | nullnostatic only.
urlstring | nullnourl only. HTTPS, checked by the egress rules.
filestring | nullnofile only. A path relative to network.list_sources_dir.
selectorstring[] | nullnourl 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_hoursintegernourl and file only.
namestringyes
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

NameTypeRequiredDescription
list_idstringyes

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

NameTypeRequiredDescription
list_idstringyes

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

NameTypeRequiredDescription
list_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — Not Found
  • 409 — 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

NameTypeRequiredDescription
list_idstringyes

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
  • 409 — Conflict

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"
}
]
}

Create a network access rule

Request body (application/json)

{
"lists": [
"string"
],
"cidrs": [
"string"
],
"mode": "report",
"description": "string",
"service": "api",
"path_prefix": "string"
}
FieldTypeRequiredDescription
listsstring[]noNames of ip address lists.
cidrsstring[]noExtra IPs or CIDRs, for one-offs.
mode"enforce" | "report"no
descriptionstring | nullno
service"api" | "dashboard" | "docs"yes
path_prefixstringyes

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

NameTypeRequiredDescription
rule_idstringyes

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 Found
  • 409 — 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

NameTypeRequiredDescription
rule_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — Not Found
  • 409 — Conflict

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
}
FieldTypeRequiredDescription
filter_enabledbooleanyes
callerCallerAddressyesHow this server sees the admin calling it: the resolved address and the hops behind it.
trusted_proxiesstring[]yes
rulesRuleInfo[]yes
listsAddressListInfo[]yes
key_allowlistsKeyAllowlistRow[]yes
events_retention_daysintegeryes

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"
}
]
}

Denial events, newest first

Query parameters

NameTypeRequiredDescription
service"api" | "dashboard" | "docs" | nullno
layer"rule" | "key" | nullno
ipstring | nullno
ref_idstring | nullnoA rule ID or an API key ID.
sincestring (date-time) | nullno
beforestring (date-time) | nullnoPass the previous page’s next_before.
limitintegerno

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

NameTypeRequiredDescription
hoursintegerno
limitintegerno

Response 200 (application/json)

{
"sources": [
{
"client_ip": "string",
"count": 0,
"top_ref_id": "string"
}
]
}

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.

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"
}
FieldTypeRequiredDescription
source"environment" | "dashboard"yesenvironment: the operator sets the keys and this list is read-only.
environment_recipientsstring[]noThe keys BACKUP_AGE_RECIPIENTS sets, when source is environment.
keysBackupKeyInfo[]yes
delay_hoursintegeryesHow long a change waits before it takes effect.
proof"two_factor" | "password" | nullyesWhat the caller confirms a change with. None: this account cannot change 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"
}
FieldTypeRequiredDescription
passwordstring | nullno
codestring | nullno
challengestringyes
answerstringyesThe decrypted message.
labelstringyesWhere 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"
}
FieldTypeRequiredDescription
key_idstringyes
recipientstringyesThe age public key (age1…). The private key is never sent.
labelstringyes
state"pending" | "active" | "removing"yespending until active_from; active; removing until removed_from.
added_bystring | nullnoEmail of the platform admin who added it.
requested_atstring (date-time)yes
active_fromstring (date-time)yes
removal_requested_bystring | nullno
removed_fromstring (date-time) | nullno
  • 400 — Bad Request
  • 401 — Unauthorized
  • 403 — Forbidden
  • 409 — Conflict

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"
}
FieldTypeRequiredDescription
recipientstringyesThe age public key to add (age1…).

Response 200 (application/json)

{
"challenge": "string",
"ciphertext": "string"
}
FieldTypeRequiredDescription
challengestringyesSigned token to send back with the answer. Valid 10 minutes.
ciphertextstringyesThe 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

NameTypeRequiredDescription
key_idstringyes

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"
}
FieldTypeRequiredDescription
key_idstringyes
recipientstringyesThe age public key (age1…). The private key is never sent.
labelstringyes
state"pending" | "active" | "removing"yespending until active_from; active; removing until removed_from.
added_bystring | nullnoEmail of the platform admin who added it.
requested_atstring (date-time)yes
active_fromstring (date-time)yes
removal_requested_bystring | nullno
removed_fromstring (date-time) | nullno
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — Not Found
  • 409 — 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

NameTypeRequiredDescription
key_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — Not Found
  • 409 — Conflict

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"
}
]
}
FieldTypeRequiredDescription
enabledbooleanyes
target"local" | "s3"yes
interval_hoursintegeryes
retention_daysintegeryes
recipientsintegeryesHow many age recipients backups are encrypted to now.
key_source"environment" | "dashboard"yesenvironment when BACKUP_AGE_RECIPIENTS or the configuration file sets the recipients, which locks them; dashboard otherwise.
local_dirstringyesWhere the local target keeps backups (BACKUP_LOCAL_DIR).
problemsstring[]yesWhy a backup cannot run now. Empty when the configuration is complete.
last_success_atstring (date-time) | nullno
overduebooleanyesTrue when backups are enabled and the last success is older than twice the interval.
runsBackupRunInfo[]yes

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"
}
FieldTypeRequiredDescription
run_idstringyes
status"running" | "succeeded" | "failed"yes
trigger"schedule" | "manual" | "migration"yes
target"local" | "s3"yes
locationstring | nullnoThe file name in backup.local_dir, or the object key in the bucket.
bucketstring | nullno
started_atstring (date-time)yes
finished_atstring (date-time) | nullno
size_bytesinteger | nullnoSize of the encrypted file.
sha256string | nullnoSHA-256 of the encrypted file, to check a download.
documentsobject | nullnoDocuments written, per collection.
recipientsinteger | nullnoHow many age recipients the file is encrypted to.
recipient_keysstring[]noThe age public keys the file is encrypted to: which identity opens it.
errorstring | nullno
  • 409 — Conflict

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
}
FieldTypeRequiredDescription
startedstring | nullnoThe run started by this tick.
skippedstring | nullnoWhy no run started: disabled, not_due, running or misconfigured.
expiredintegernoRuns marked failed because their server stopped.
prunedintegernoRuns deleted by retention.

Get one backup run

Path parameters

NameTypeRequiredDescription
run_idstringyes

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"
}
FieldTypeRequiredDescription
run_idstringyes
status"running" | "succeeded" | "failed"yes
trigger"schedule" | "manual" | "migration"yes
target"local" | "s3"yes
locationstring | nullnoThe file name in backup.local_dir, or the object key in the bucket.
bucketstring | nullno
started_atstring (date-time)yes
finished_atstring (date-time) | nullno
size_bytesinteger | nullnoSize of the encrypted file.
sha256string | nullnoSHA-256 of the encrypted file, to check a download.
documentsobject | nullnoDocuments written, per collection.
recipientsinteger | nullnoHow many age recipients the file is encrypted to.
recipient_keysstring[]noThe age public keys the file is encrypted to: which identity opens it.
errorstring | nullno
  • 404 — Not Found

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

NameTypeRequiredDescription
run_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — Not Found
  • 409 — Conflict
  • 502 — Bad Gateway

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

NameTypeRequiredDescription
run_idstringyes
  • 200
  • 404 — Not Found
  • 409 — Conflict