# Sandbox

> Test the whole lifecycle with a sandbox key: simulate the review of sandbox releases.

<!-- Generated from openapi/hills-v1.json by scripts/api-reference.mjs. Edit the operation in hills-music (server/lib/ops), not this page. -->

Test the whole lifecycle with a sandbox key: simulate the review of sandbox releases.

Base URL `https://app.hillsmusic.com/api/v1`. Every request sends an API key: `Authorization: Bearer hm_live_…` (production) or `hm_test_…` (sandbox).

- Simulate the review of a sandbox release (sandbox keys only)

## Simulate the review of a sandbox release (sandbox keys only)

`POST /api/v1/sandbox/releases/{id}/simulate` · Scope: `ddex:write` or `catalog:read` · Sandbox keys only (production keys get 403 sandbox_only).

With a sandbox key (hm_test_…): moves a sandbox release as if HILLS staff had decided — approve (→ approved), reject (→ changes_requested, with your reason) or live (→ approved and live) — so you can test status polling (GET /releases/{id}, GET /ddex/{id}) end to end. Nothing is sent anywhere. A production key gets 403 sandbox_only; a production release is never found (404). catalog:read works too.

> **Deprecated:** The status fields in the old words (status on releases, stores[key].state on each store, status and previous_status in simulate answers) are removed on April 30, 2027. Use release_status and delivery_state for the release, stores[key].status for each store, and in simulate answers release_status, delivery_state and previous_release_status instead. Until then answers carry `Deprecation` and `Sunset` headers. [What changes](https://developer.hillsmusic.com/changelog/#2026-10-11-status-fields-sunset)

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | Yes | The sandbox release (release_id from GET /ddex/{id} items). |

### Request body

JSON.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `outcome` | `approve` \| `reject` \| `live` | Yes | The decision to simulate. |
| `reason` | string | No | Rejection reason to echo back (reject). |

### Example request

```bash
curl -X POST "https://app.hillsmusic.com/api/v1/sandbox/releases/912/simulate" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome":"approve"}'
```

### Response `200`

```json
{
  "data": {
    "id": 912,
    "status": "approved",
    "previous_status": "pending",
    "reason": null,
    "sandbox_expires_at": "2026-11-06T09:00:00Z",
    "environment": "sandbox",
    "release_status": "approved",
    "delivery_state": "not_started",
    "previous_release_status": "in_review"
  }
}
```

### Errors

| Status | When |
| --- | --- |
| 400 | invalid: a parameter is wrong; field names it. |
| 401 | unauthenticated, invalid_key, key_revoked or key_expired. |
| 403 | insufficient_scope: the key lacks the scope; scope names it. account_inactive or api_not_in_plan. sandbox_only: a production key (hm_live_…). |
| 404 | not_found: no such thing, or not yours (or not in the key's environment). |
| 409 | invalid_state: The release's status doesn't allow this outcome (see the outcomes table). |
| 429 | rate_limited: wait Retry-After seconds. |

Source: https://developer.hillsmusic.com/reference/sandbox/