Primeiros passos
Gerencie vídeos, uploads, arquivos, testes A/B e domínios do VTurb via REST
A API do VTurb é uma API REST pública para a sua conta VTurb. Toda resposta documentada é registrada a partir do comportamento real da API.
URL base
https://api.vturb.comTodo caminho começa com /v1.
Autenticação
Envie o seu token de API do VTurb (vt_...) como bearer token em toda requisição:
curl https://api.vturb.com/v1/videos \
-H "Authorization: Bearer vt_..."Cada ação exige um escopo no token: videos:read, videos:upload e videos:write para vídeos, ab_tests:read e ab_tests:write para testes A/B, domains:read e domains:write para domínios.
- Um token ausente ou inválido retorna
unauthorized. - Um token sem o escopo que a ação exige retorna
forbidden. - Uma organização que não está habilitada para a API retorna
org_not_enabled.
Erros
Os erros são corpos application/problem+json com os mesmos quatro campos. code nomeia o erro, e type aponta para a página dele em Erros:
{
"type": "https://docs.vturb.com/errors/not_found",
"code": "not_found",
"message": "Resource not found.",
"request_id": "0b5e7a1c-9f3d-4c2b-8e1a-7d6c5b4a3f21"
}Listas
Os endpoints de lista aceitam os parâmetros de query cursor e per_page para paginação por cursor.
Atualizar um vídeo
PATCH /v1/videos/{id} é um merge-patch: envie só o que você quer alterar, e todo o resto mantém o valor salvo. Como o merge-patch funciona explica as regras, e cada recurso tem o próprio guia.
Retorna o uso atual da cota da API para a empresa autenticada GET
Retorna o uso e os limites atuais da cota da empresa — uma entrada por janela de cota, como por minuto ou por dia. Todas as API keys da empresa compartilham essa cota. Use este endpoint para se auto-limitar antes de disparar requisições analíticas pesadas. Observações: - Quando uma métrica não tem limite, a resposta usa `limit: null` e `remaining: null` para você não dividir por zero. - Quando a empresa não tem cota, `quotas` é uma lista vazia. - Uma única chamada à API pode contar como mais de uma query contra `max_queries_per_minute`, então o contador `queries` pode subir mais rápido que a sua taxa real de requisições. A resposta inclui `queries.note` para sinalizar isso quando há um limite ativo. O `read_bytes` reflete o volume de dados efetivamente lido e é o sinal mais confiável para dimensionar o seu uso. - O próprio endpoint conta como 1 query contra `max_queries_per_minute`.
Como o merge-patch funciona
A regra única por trás de toda atualização de vídeo: envie só o que você quer alterar.