# Requisições

Envie JSON no corpo da requisição.

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

Os identificadores são UUIDs. `workspaceId` é obrigatório nas listas que ainda não estão limitadas por um id no caminho. As datas são ISO-8601 em UTC.

## Respostas

Toda resposta usa o mesmo envelope. `data` é `null` quando a chamada falha. `error` é `null` quando ela tem sucesso.

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

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

`error.details` aparece nas falhas de validação e lista os campos que falharam.

## Erros

| Status | Código | Significado |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Falta um campo obrigatório ou há um valor inválido |
| 401 | — | O token Bearer está ausente, é desconhecido ou foi revogado |
| 403 | — | A chave não inclui o escopo exigido |
| 404 | — | O registro não existe neste workspace |
| 429 | `RATE_LIMIT_EXCEEDED` | O workspace esgotou a cota mensal da API |

Trate qualquer `success: false` como falha, inclusive um `2xx` que você não esperava. Tente o `429` de novo quando a janela mensal reiniciar. Não tente de novo um `401` ou um `403` com a mesma chave.

## Cota

Cada chave de API conta na cota mensal de requisições do plano do workspace. Quando a cota acaba, a API responde `429` com `RATE_LIMIT_EXCEEDED`. Ler análises e entregar webhooks entra na mesma cota.

## Publicar um player

`PATCH /v1/player-config/{playerId}/draft` não muda o embed. `POST /v1/player-config/{playerId}/publish` copia o rascunho para o player ao vivo e incrementa `publishedVersion`. Um player recém-criado tem `publishedVersion` `0` até a primeira publicação.

O envio de um vídeo tem dois passos. `POST /v1/videos` cria o registro. `POST /v1/videos/{videoId}/upload-url` devolve o destino de envio de uso único. Consulte `GET /v1/videos/{videoId}/status` até `status` ser `ready`.
