HTTP API

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:

Armed fault matches? → fire it.
X-Mock-Scenario header present? → run that scenario.
Magic value in the request? → run its outcome.
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 & path	Purpose
`POST /__admin__/seed`	Silent insert of history (ids validated against the pack regex).
`POST /__admin__/reset`	Empty 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/events`	Fire an external cause. `409` if its precondition fails.
`GET /__admin__/world/next`	The live “what can happen next” set.
`POST /__admin__/clock/advance`	Advance time; returns events that fired.
`POST /__admin__/clock/durations`	Collapse 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>" } }

Status	When
`400`	unknown scenario / malformed control body
`401`	bad/missing key
`404`	unknown resource or object
`409`	world-event precondition not met
`422`	invalid seed id / setting a faithful field
vendor codes	forced via fault / scenario / magic value

Get started

Core concepts

Supported APIs

Testing in CI

Running a live sandbox

Reference

Trust

Auth

Vendor plane

Control plane

Example: arm a fault

Example: read the resolution trace

Error envelope

​Auth

​Vendor plane

​Control plane

​Example: arm a fault

​Example: read the resolution trace

​Error envelope

Auth

Vendor plane

Control plane

Example: arm a fault

Example: read the resolution trace

Error envelope