Requests
Send JSON for request bodies.
Code
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.
Code
Code
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.