Reference

Every admin route, every control header, the error shape and how access is guarded, on one page. Each row links to the page that defines it.

#Routes

Routes live under /__admin by default.

#Discovery and health

A running emulator is its own reference:

curl localhost:8787/__admin

{
  "service": "stripe",
  "namespace": "default",
  "adminPrefix": "/__admin",
  "docs": "https://mockingbird.chrisvouga.dev/docs/admin-controls"
}

#State

#Time

#Failure

#Everything at once

#Inspection

An emulator adds its own routes beside these (webhook deliveries, an outbox, vendor-specific switches). GET /__admin lists them and the emulator's guide explains them.

#Choosing the namespace

Every admin route acts on one namespace: the one named by ?namespace=<key>, else by x-mockingbird-namespace, else default. /__admin/ns/<key>/… reaches the vendor API in that namespace for clients that can only set a base URL.

#Headers

Scope, order and response headers are on Request headers.

#Values

Request bodies are JSON. A content-type header is not required.

#Errors

An admin error always has this shape, never a vendor's:

{ "error": { "type": "mockingbird_admin", "message": "no snapshot nope in namespace default" } }

A request that is refused has changed nothing.

#Access

Without an admin key the controls are open, which suits a local test process.

Set one with adminKey on createRuntime or createServer, --admin-key <key>, or MOCKINGBIRD_ADMIN_KEY. Then x-mockingbird-admin-key: <key> is required on:

• every admin route except GET /__admin/health and the admin page's shell (GET /__admin/ui), which holds no data;
• any vendor request carrying a control header that changes state or injects a failure. The three that only select (x-mockingbird-namespace, x-mockingbird-branch, x-mockingbird-at) need no key, except a write with x-mockingbird-at on main, which rewinds it.

adminPrefix, --admin-prefix <path> or MOCKINGBIRD_ADMIN_PREFIX moves the whole tree from /__admin to another path.

#Admin page

GET /__admin/ui is the same controls as a page. The hash opens a screen: http://localhost:8787/__admin/ui#snapshots. On a narrow window the sidebar collapses to icons; Jump (⌘K or Ctrl+K) searches the names below. The header Namespace select is Namespaces. Routes runs any admin route: pick it, fill the path parameters and JSON body, and press Send request.

#Where the controls apply

HTTP emulators have every control in this guide, and a conformance suite runs the same checks against each of them. The PostgreSQL and SQLite engines answer the same /__admin routes for reset, snapshots, checkpoints, branches and state; they have no HTTP request to delay or fault, and their snapshots stay in the process. Redis is controlled through its fleet endpoint. A fleet adds one aggregate control listener that resets, snapshots and moves the clock across every service at once; see Fleets.

The Node server and the CLI destroy the socket for a drop, a timeout or a truncate. Bun.serve cannot close a connection from a handler, so the Bun adapter answers 500 for a drop.