<!-- https://missblue.dev/docs/sandbox-api -->

# Sandbox API

Use an mb_sandbox_ key on the normal API origin. Other supported endpoints operate on isolated fixtures. On POST /v1/messages, X-Miss-Blue-Sandbox-Scenario chooses sent, delivered, read, reply, failed, offline, rate_limited or timeout. See /docs/sandbox for limits and unsupported operations.

Base URL: `https://api.missblue.dev`

Every request carries `Authorization: Bearer $MISS_BLUE_KEY`.

### GET /v1/sandbox

Inspect this project's sandbox.

Returns the virtual number, retained fixtures, endpoints without secrets, delivery attempts, expiry and limits. Requires a sandbox key.

Example:

```bash
curl -X GET https://api.missblue.dev/v1/sandbox \
  -H "Authorization: Bearer $MISS_BLUE_KEY"
```

Errors:

- `403` — A live or legacy test key was supplied.

### DELETE /v1/sandbox

Reset fixtures and sandbox webhook endpoints.

The virtual number ID and API keys stay valid. Returns the reset sandbox state.

Example:

```bash
curl -X DELETE https://api.missblue.dev/v1/sandbox \
  -H "Authorization: Bearer $MISS_BLUE_KEY"
```

### GET /v1/sandbox/events

List retained simulated events.

Example:

```bash
curl -X GET https://api.missblue.dev/v1/sandbox/events \
  -H "Authorization: Bearer $MISS_BLUE_KEY"
```

Response:

```json
{"data":[],"total":0}
```

### POST /v1/sandbox/events

Emit a documented webhook type with test data.

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `type` | `string` | yes | One of the documented webhook event types. |
| `data` | `object` | yes | Fixture payload. It is marked sandbox and sent only to sandbox endpoints. |

Request body:

```json
{
  "type": "call.ended",
  "data": {
    "call": {
      "id": "fixture-call"
    }
  }
}
```

Example:

```bash
curl -X POST https://api.missblue.dev/v1/sandbox/events \
  -H "Authorization: Bearer $MISS_BLUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "call.ended",
    "data": {
      "call": {
        "id": "fixture-call"
      }
    }
  }'
```

### POST /v1/sandbox/messages/{id}/simulate

Advance a simulated outbound message.

Returns the message. Completed receipts cannot move backwards; each reply adds an inbound fixture.

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `scenario` | `string` | yes | sent, delivered, read, reply, failed, offline or timeout. |
| `reply_text` | `string` | no | Optional text for the reply scenario, up to 4096 bytes. |

Request body:

```json
{
  "scenario": "reply",
  "reply_text": "Thanks, I received it."
}
```

Example:

```bash
curl -X POST https://api.missblue.dev/v1/sandbox/messages/8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d/simulate \
  -H "Authorization: Bearer $MISS_BLUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "reply",
    "reply_text": "Thanks, I received it."
  }'
```

Errors:

- `409` — The message already passed the requested status or the fixture limit was reached.