Skip to main content
Everything in ProdBreak is reachable over plain HTTP. The SDKs and test plugins are clients of this contract, and curl is the zero-dependency fallback. Two planes share one origin:
  • Vendor plane — the vendor’s real paths (/v1/...), called by your app’s SDK.
  • Control plane — /__admin__/*, called by test code / the SDK / curl.
This contract carries a version string. Vendor specifics (resource names, the error envelope) are supplied by the pack; shapes here use Stripe/Deck-shaped examples.

​
Auth

Every request carries the instance-minted bearer key: 
Authorization: Bearer pbw_<instance-minted-key>
A wrong or missing key is a 401. The key authenticates you to the one world; it does not select among worlds. More →

​
Vendor plane

Your app’s calls arrive unchanged and are resolved in this order:
  1. Armed fault matches? → fire it.
  2. X-Mock-Scenario header present? → run that scenario.
  3. Magic value in the request? → run its outcome.
  4. Otherwise → normal stateful handling (out-of-control fields resolved inside this step).
Every response carries X-Mock-Resolution-Trace: <id> (see the trace endpoint below).

​
Control plane

Method & pathPurpose
POST /__admin__/seedSilent insert of history (ids validated against the pack regex).
POST /__admin__/resetEmpty state + rewind clock to t0. Optional { t0 }.
POST /__admin__/faults · DELETE /__admin__/faults[/{id}]Arm / clear a forced fault.
GET /__admin__/state[?resource=]Introspect the world.
POST /__admin__/world/eventsFire an external cause. 409 if its precondition fails.
GET /__admin__/world/nextThe live “what can happen next” set.
POST /__admin__/clock/advanceAdvance time; returns events that fired.
POST /__admin__/clock/durationsCollapse named durations (CI determinism).
POST /__admin__/webhooks/endpoints · DELETE .../{id}Register / remove an endpoint (+ its deterministic secret).
POST /__admin__/exogenous/pins · DELETE .../{id}Pin / clear an out-of-control value (or a branch choice).
GET /__admin__/trace/{id}The resolution trace for a prior call.

​
Example: arm a fault

curl -X POST http://localhost:8801/__admin__/faults \
  -H "Authorization: Bearer $PRODBREAK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resource": "charges", "operation": "create",
        "status": 402, "error": { "code": "card_declined" }, "count": 1 }'
# → { "id": "flt_1" }

​
Example: read the resolution trace

curl http://localhost:8801/__admin__/trace/rtr_8a2 \
  -H "Authorization: Bearer $PRODBREAK_KEY"
# → { "operation": "runTask", "outcome": "normal",
#     "exogenous": [ { "field_path": "output.balance", "source": "pin", "value": 1432.18 } ] }

​
Error envelope

ProdBreak returns a generic shape by default; each pack overrides it with the vendor’s real one. 
{ "error": { "code": "<machine_code>", "message": "<human message>" } }
StatusWhen
400unknown scenario / malformed control body
401bad/missing key
404unknown resource or object
409world-event precondition not met
422invalid seed id / setting a faithful field
vendor codesforced via fault / scenario / magic value