Admin API endpoint catalogue (complete route reference)

This is the authoritative list of every route the engine serves under /admin. It is written for a developer integrating against the engine directly, or auditing exactly what the in-account console can reach. Every entry is taken from the route handlers in the engine’s admin router, not from a summary comment, so a row matches what the code actually dispatches. It is complete for a production engine: a gate here holds the rows to the generated route set and fails on a served route with no row, and the single family that is excluded is named and explained under what this catalogue leaves out.

The /admin surface is the only API the console calls, and the engine runs inside your own Cloudflare account. There is no inbound path from the vendor: this surface is reached only by your own console within your account. Each row names the method, the path, the capability a caller must hold, and the behaviour worth knowing before you call it.

For a generated route-level view, the method, path, summary and tag of every route, with a downloadable machine-readable spec, see the API explorer. This page is the human-grouped catalogue; the explorer is the route-level view generated from the same code at build time. The generated spec does not assert request or response shapes, and being a build-time snapshot it does not detect drift from a deployed engine. For how a request authenticates and how a role resolves to a capability, see authentication and authorisation.

How to read this catalogue

Authorisation is decided by capability, not by a role rank. A route gates on a single capability, and a caller holds a capability through their resolved role. The capability floor column names the capability the route requires; the roles and capabilities page maps each built-in role to its capability set. Where a column says “owner”, the route checks the role directly rather than a capability, which the notes call out.

A few behaviours recur across the table, so they are stated once here rather than repeated on every row.

The reads are open to any authenticated role that holds the relevant read capability, and they carry no body to mis-parse, so they have no per-caller rate-limit pre-check. Every mutating route is a POST, and each one is rate-limited per caller after its capability gate, failing open so an unavailable limiter never blocks a verified operator’s recovery action. The four break-glass routes gated directly on the bare ADMIN_TOKEN are the exception: POST /admin/demo/reset, POST /admin/control-plane/restore, POST /admin/control-plane/restore-sealed and POST /admin/control-plane/apply-staged check the bearer token directly rather than going through a capability gate, and none of the four is rate-limited. A 403 from a capability gate is JSON ({ "error": "forbidden", "required": <capability>, "have": <role> }), distinct from the plaintext 401 a sign-in failure returns, so the console can tell a missing capability from a missing session on the status code alone.

A defined set of high-consequence writes additionally requires a fresh step-up re-authentication, so a stale ambient session cannot perform one on its own. Which routes are in that set is decided in the engine rather than listed here, because a route list on this page is a value the clock moves. A caller on the bare break-glass token or behind Cloudflare Access is exempt, since each manages its own re-authentication; a cookie-session caller that has not re-authenticated recently gets a 401 carrying stepUpRequired: true, which the console catches to run the ceremony and retry with a single-use step-up token. The check fails closed, so an unavailable check refuses the action rather than waving it through.

Routing that runs before the switch

Some requests are matched before the main route switch. Most are matched early because a dynamic path segment cannot be a literal switch case; the cost estimate is grouped here as an early fixed-path read. They are listed so the catalogue is genuinely complete.

The SAML assertion-consumer POST is an exception to the origin-checked write guard. It is an identity-provider-driven post that carries no same-site cookie, so it is not subject to the cookie-session origin check; its replay defence is a single-use RelayState bound to the in-response-to value, enforced in the Durable Object.

Downpipes and runs

The configured backups, running one now, and the run history. The restore screen’s calendar consumes point-in-time resolution directly, and the recovery-time estimate is read by the Recovery time (RTO) panel on the SLA report card. The console keeps coverage and recovery figures honest from the engine’s own answers.

GET /admin/runs/at resolves a recovery-timeline pick into a run id; that id then flows through the normal restore path. The restore screen’s calendar is built directly on this route, both for grouping a downpipe’s ring by day and for reading its own honest floor. The portal restore still always picks a run by id, never an arbitrary timestamp, and shows recovery freshness as the newest good run. The reasoning behind that choice lives on recovery objectives.

Canary and the integrity probe

The integrity canary flies a tiny seal, read and restore on a schedule to prove the whole path still works end to end. Reading its state is open to any authenticated role; flying it now is a run action; changing whether, where and how often it flies is a governance decision the owner makes directly.

Restore and recovery

The most consequential family. A dry-run plans and writes nothing; an apply writes archived data back and needs both the apply capability and a separate dual-control approval. The verify and attest routes prove an archive is recoverable without writing or surfacing any plaintext. The restore family has its own deep-dive at the restore and recovery API guide; the rows here are the catalogue summary.

The apply is never a single call. The engine gates it in order: the apply capability first (an unauthorised apply is a 403 and an audited denial before the rate limiter, so a blocked production write is never masked by a 429), then the step-up re-authentication described above, then a usable approval bound to the exact plan hash with a distinct approver (no approval yields 403 restore not approved with the plan hash), then a two-phase integrity verify. The mechanics live on dual control, which is the canonical home rather than this catalogue.

Attended verification sessions

Proving archives recoverable on an engine that holds no operational key, without the break-glass private ever leaving the operator’s browser. A session pins the runs it will cover, proves live possession of the recovery identity against the break-glass public key the engine holds in either posture, then verifies each pinned run from a browser-supplied per-run master, sample-decrypting to a discard sink. Every route below gates on drill.run, is rate-limited and is audited, and starting a session additionally needs a step-up re-authentication, because starting one is what enables per-run masters at all. The session record holds a sampling seed and a challenge proof hash, never a key, and the Durable Object refuses a caller whose subject differs from the session’s creator, so only the identity that started a session can drive it.

The operator-facing account of what a session proves, and what it does not, is on attended verification.

Retention pruning

Applying a downpipe’s retention policy on an engine that holds no operational key. The scheduled retention pass honestly defers on a break-glass-only estate, because deciding which segments a retained run still references means reading the archive back. These routes move that key work to the browser: the engine serves each candidate run’s non-secret master capsule, the browser recovers each master locally, and it hands back only the masters. Each recovered master builds one enumerator for one call and is zeroed before the response is built. The planner and the apply are the same ones the cron pass calls, unmodified.

Approving a prune and applying one each additionally need a step-up re-authentication. A prune apply deletes the archive itself, which a restore apply does not, so it also carries its own maker-is-not-checker approval rather than riding the config change-control queue. What retention keeps and when it prunes is on retention and pruning.

Keys and the key ceremony

Installing and rotating the engine’s own secrets without a customer command line. Every write here is owner-exclusive: the key ceremony is the highest-consequence cryptographic action, and the capability behind it is held by the owner alone. The vintage inventory is a read, gated like the run-history reads it is derived from.

In the two-recipient posture the engine holds a decryption-capable operational private key, so it can run its own restore tests. The break-glass-only route removes that key on purpose. The vendor holds nothing in either posture. The trust model is set out on the no-custody trust model.

Destinations and the archive target

Where backups land. Verifying a destination is a live write probe before anything is stored; repointing where every backup lands is break-glass-grade, so these are owner-exclusive.

Sources and discovery

What the engine can back up, plus attaching new source bindings to the engine itself. The account-wide discovery token and the attach token are owner-exclusive; both are verified live and never persisted.

A Worker sees only what is bound to it, so resources in the account that are not attached to the engine do not appear in discovery. Attaching them is the binding step the connect-a-source flow documents. The Cloudflare configuration source advertises its surface registry here: there are 313 Cloudflare config surfaces, of which 60 auto-restore in-band and 253 are backup-and-preview only. The full list is on the Cloudflare config surface reference.

Identity providers and people

Connecting external identity providers, mapping their groups to roles, and composing custom roles. The provider-connection routes are owner-exclusive because a connection is an authentication trust root; group and custom-role writes sit behind the access.policy capability.

downpipes ships 8 named providers plus generic OIDC and OAuth2. SAML is sign-only and service-provider-initiated only. A per-connection allowIdpInitiated boolean is accepted and stored by the connection API, and the XML response verifier does read it, but setting it true does not enable anything: the assertion consumer refuses any assertion that carries no server-minted RelayState record, and that refusal returns before the connection is loaded. Only an SP-initiated request mints such a record. Treat the field as inert and do not build against it. The full provider matrix, and which login modes actually complete at first sign-in, are on the supported providers reference.

Sessions and passkeys

Managing enrolled passkeys and terminating sessions. Self-service actions need only an authenticated caller; acting on another member is gated inside the Durable Object.

Notifications and alerting

Alert channels, rules and the delivery history. The writes sit behind the notify capability; with the change-control gate armed, a channel change is queued for a second approver.

Posture, coverage and expiry

The honest posture and coverage views, the credential and key expiry tracker, and accepting a posture risk. Coverage stays honest-unknown from the portal when no inventory is stored; the inventory submission is engine-only and is reference data that never grants data access.

The coverage inventory is submitted from the Security centre’s populate-inventory modal, which parses what you paste into the per-type resource lists and posts them. From the portal, coverage is never green for an unknown resource. GET /admin/runs/at now feeds the restore screen’s calendar directly. The reasoning is on coverage.

Config change-control and version history

downpipes versions its own governance configuration and offers an opt-in dual-control gate over config mutations. The reads sit behind the config-read capability; the gate toggle is owner-only, with an asymmetric off switch so it can never deadlock its own disarm.

The approve and reject for both inboxes are the dynamic-path routes listed under routing that runs before the switch. The change-control mechanics are covered on change control, and the version history on config version history.

Audit trail

The tamper-evident, hash-chained trail. The reads are open to any authenticated role; the one write the console performs records an intent marker only, never a result or a value, and is owner-only.

The trail records operator identity (the actor email, the source IP, the role, and approver emails on a restore apply), so it carries personal data and is tamper-evident rather than identity-free. The feed and its contents are described on the SIEM audit feed.

Audit-log push (SIEM)

The engine can also push the same hash-chained trail outward to a SIEM over HTTPS, rather than waiting on a collector to poll it. One configured destination covers three payload shapes, raw JSON, Splunk HEC, or Datadog, chosen by a format field alongside the endpoint URL and the auth header name. The auth secret is sealed at rest and never returned by any of the reads below.

The outbound POST runs through the same egress-secure fetch the alert webhook uses (https only, private and metadata address ranges blocked by default, a timeout, no redirect followed), and delivery is at-least-once: a sequence cursor advances only on a 2xx, so an interrupted delivery re-sends rather than silently drops. Because the engine is the one dialling out, a Cloudflare Access perimeter in front of the console hostname never blocks it, unlike the pull feed above. The full account, the eight body formats, the three sinks that carry them, the security posture, and the at-least-once semantics, is on forwarding the audit log to your SIEM (push).

Metrics push (OTLP)

The engine can also push its own backup-health metrics outward to an OpenTelemetry collector over OTLP/HTTP, so a monitoring stack sees run health without polling. One destination, one transport and one bearer or API-key secret, sealed at rest before storage and never read back by the view below.

Both writes are among the step-up-gated set described at the top of this page: a stolen ambient session redirecting operational telemetry is the same class of egress theft as redirecting the audit trail. The collector-side setup is on OTLP metrics push.

Licence and the control plane

The assurance licence is fail-open and gates only assurance features, never the data or recovery path. The activation route is owner-exclusive and verifies the token live against the pinned vendor key before storing.

Control-plane disaster recovery

Rebuilding the control plane (the downpipe and destination configuration, the role table and the owner-governed policy) after it has been wiped, from a signed export pulled out-of-band from the destination bucket. The export carries a non-secret inventory of the identity-provider connections and the notification routing, so a recovery has the checklist of what to reconnect, but those connections, along with sessions and passkeys, are re-established after the rebuild rather than restored, and any account-held secret rides only as a wrapped envelope or a marker that it must be re-entered. The restore, restore-sealed and apply-staged routes are gated directly on the bare break-glass ADMIN_TOKEN rather than the capability model, because after a wipe the role table is empty and a passkey or Access caller resolves only to a recovery-required viewer that cannot authorise the rebuild. See recovering downpipes itself for the end-to-end flow.

Controlled self-update

A controlled, reversible self-update with a canary gate and an always-available rollback. A signed release can carry the engine alone or the engine and the console as components, applied engine-first. Every write here is owner-exclusive, requires a one-shot deploy token that is never stored, and never touches the data or recovery path.

The update flow, its trust model and the rollback path are on applying an update and update trust and rollback.

Status, setup and support

The presence-only onboarding reads, the live preflight, and the support-bundle and ingest-credential surface. The status reads carry presence and counts only, never a secret value.

GET /admin/status and GET /admin/setup-state are presence-only by design: they report what is configured or not, counted and proven, but never a secret value, so they are account reconnaissance behind the authentication gate rather than a data surface.

Demo-only

One route exists only on a throwaway demo engine.

What this catalogue leaves out

One family of routes is deliberately not a row above, and it is left out because a production engine does not serve it rather than because it is undocumented.

The harness fault-injection surface, POST /admin/test-fault/arm, POST /admin/test-fault/disarm, POST /admin/test-fault/canary-tick, POST /admin/test-fault/retention-tick and GET /admin/test-fault/status, exists only on an engine deployed with the HARNESS_TEST_FAULTS flag set, which is a test estate of ours rather than a customer deployment. Without that flag the router returns 404 for the whole /admin/test-fault/ prefix before authentication, exactly as the demo reset does, so a self-hosted engine has no fault surface to find or invoke. With the flag on, the caller must additionally hold the owner role. The routes arm and read one persisted fault and run a cron tick on demand, so a fault-provocation journey need not wait a real hour.

Nothing else is omitted. A gate in this repository compares the generated route set against the rows above on every run and fails naming any route that is served but has no row, with that one prefix as its only exclusion.

Where this fits

This catalogue is the map. For a generated route-level view, the method, path, summary and tag of every route, with a downloadable spec, open the API explorer. For how a call authenticates and how a role becomes a capability, read authentication and authorisation. For the restore family in depth, including the apply preconditions and the cf-config restore context, read the restore and recovery API guide. For the role-to-capability map, see roles and capabilities. When a call returns a status you did not expect, the error and status codes reference and troubleshooting explain the shapes.

Last updated 4 August 2026.