> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prodbreak.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> The raw HTTP control contract every client wraps. curl works; the SDKs are thin shells over this.

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

<Note>
  This contract carries a version string. Vendor specifics (resource names, the error envelope) are
  supplied by the [pack](/apis/overview); shapes here use Stripe/Deck-shaped examples.
</Note>

## 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 →](/concepts/worlds)

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

```bash theme={null}
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

```bash theme={null}
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.

```jsonc theme={null}
{ "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  |