# Sandbox · Reference

> Test scenarios with simulated watches, so you can integrate without watches. Only on `sandbox.api.safeonuba.com`.

Page: https://safeonuba.com/en/developers/reference/sandbox · SafeOnuba API v1 (`api_version: "2026-09-24"`), in preview: the contract may change.

## Launch a test scenario

`POST /v1/sandbox/scenarios` · any token · [see it on the web](https://safeonuba.com/en/developers/reference/sandbox#runSandboxScenario)

**Only on `sandbox.api.safeonuba.com`**; in production, 404. A scenario doesn’t invent alerts: simulated watches at a sandbox site send their facts and the usual engine decides, so what arrives —webhook, `GET`, headcount— is the same as would arrive from a real watch, marked `simulated: true`. At most five open at once per client and one evacuation per site.

### Body (`application/json`, schema `SandboxScenarioRequest`)

- `scenario` (SandboxScenario, required) Values: `sos`, `fall`, `heat_stress`, `evacuation`.
- `site_id` (string (uuid)): The sandbox site. Without it, the first one of yours that is a sandbox site.

### Responses

- `202`: Launched. → `SandboxScenarioRun` (`application/json`)
- `401`: The token is missing, has expired or has been revoked. → `Problem` (`application/problem+json`)
- `403`: The token lacks the scope the route requires, or the site doesn’t belong to the client. → `Problem` (`application/problem+json`)
- `404`: This is not the sandbox, or the site isn’t yours. → `Problem` (`application/problem+json`)
- `409`: An evacuation is already under way at that site, or five scenarios are open. → `Problem` (`application/problem+json`)
- `422`: The site isn’t a sandbox site, or it has a real watch and nothing runs. → `Problem` (`application/problem+json`)
- `429`: Too many requests, or too much query time: each client has a number of requests per minute (600 by default) and a query time per minute (30 s by default), and each request spends however long it takes, so a long list counts for more than a single alert. `Retry-After` says when to retry. → `Problem` (`application/problem+json`)

### Example request (sandbox)

```bash
curl -X POST "https://sandbox.api.safeonuba.com/v1/sandbox/scenarios" \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "scenario": "sos"
}'
```

### Example response (`202`)

```json
{
  "run_id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
  "scenario": "sos",
  "site_id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
  "resource": {
    "type": "alert",
    "id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90"
  },
  "ends_at": "2026-09-24T11:04:12Z"
}
```