# Requests

Send JSON for request bodies.

```
Content-Type: application/json
```

Identifiers are UUIDs. `workspaceId` is required on list routes that are not already scoped by a path id. Dates are ISO-8601 in UTC.

## Responses

Every response uses the same envelope. `data` is `null` when the call fails. `error` is `null` when it succeeds.

```json
{
  "success": true,
  "data": {},
  "error": null
}
```

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "workspaceId is required."
  }
}
```

`error.details` is present on validation failures and lists the fields that failed.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | A required field is missing or a value is invalid |
| 401 | — | The bearer token is missing, unknown, or revoked |
| 403 | — | The key does not include the required scope |
| 404 | — | The record does not exist in this workspace |
| 429 | `RATE_LIMIT_EXCEEDED` | The workspace used its monthly API allowance |

Treat any `success: false` as a failure, including a `2xx` you do not expect. Retry `429` after the monthly window resets. Do not retry `401` or `403` with the same key.

## Allowance

Each API key counts against the workspace plan's monthly request allowance. When the allowance is used up, the API returns `429` with `RATE_LIMIT_EXCEEDED`. Reading analytics and delivering webhooks are included in that same allowance.

## Publishing a player

`PATCH /v1/player-config/{playerId}/draft` does not change the embed. `POST /v1/player-config/{playerId}/publish` copies the draft to the live player and increments `publishedVersion`. A newly created player has `publishedVersion` `0` until the first publish.

Video uploads are two steps. `POST /v1/videos` creates the record. `POST /v1/videos/{videoId}/upload-url` returns the one-time upload target. Poll `GET /v1/videos/{videoId}/status` until `status` is `ready`.
