Regras Gerais da API

Esta página descreve as regras gerais para trabalhar com a Kinescope API que se aplicam a todos os endpoints. Se você é novo na API, comece por aqui.

Para quem é este artigo

• Desenvolvedores — precisam começar a usar a Kinescope API
• Desenvolvedores backend — precisam entender as regras básicas de autorização e formatos de solicitação
• Engenheiros DevOps — precisam integrar o Kinescope em processos automatizados

Informações básicas

URL base

Todas as solicitações da API são feitas para:

https://api.kinescope.io

Versões da API

A Kinescope API usa versionamento via prefixos de URL:

Autorização

Formato do token

Para autorização na API pública, use o cabeçalho Authorization com o tipo Bearer:

Authorization: Bearer SEU_TOKEN_DE_API

Importante: O token de API deve estar no formato UUID (por exemplo, e51e55a1-7615-493e-9055-10ac9cc44ccd). Você pode obter um token no Dashboard do Kinescope em Configurações → Tokens de API.

Workspace e tokens

Cada token de API está vinculado a um workspace específico. Ao fazer uma solicitação, o workspace é determinado automaticamente a partir do token — você não precisa passá-lo separadamente.

Todos os endpoints requerem o cabeçalho Authorization: Bearer ....

Formato de resposta

Resposta bem-sucedida

Todas as respostas bem-sucedidas são retornadas em formato JSON com um wrapper:

{
  "data": {
    "id": "video-uuid",
    "title": "Meu Vídeo",
    "status": "done"
  }
}

Resposta de lista com paginação

As listas são retornadas com metadados de paginação e ordenação:

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 156
    },
    "order": {
      "created_at": "desc"
    }
  },
  "data": [
    {"id": "video-1", "title": "Primeiro Vídeo"},
    {"id": "video-2", "title": "Segundo Vídeo"}
  ]
}

Cabeçalhos de resposta

O cabeçalho X-Request-ID chega nas respostas bem-sucedidas e nos erros 400, 401 e 500. Ele não é enviado em 404 e 405. Use-o ao entrar em contato com o suporte:

X-Request-ID: 7127f2d7-0e96-40d0-9a03-2e987c096466

Paginação

Use parâmetros de paginação para recuperar listas:

Exemplo:

curl "https://api.kinescope.io/v1/videos?page=2&per_page=25" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

Ordenação

Use o parâmetro order para ordenar os resultados:

order=campo.direção,campo2.direção

• campo — nome do campo para ordenação
• direção — direção: asc (crescente) ou desc (decrescente)
• Múltiplos campos podem ser especificados separados por vírgulas

Exemplos:

# Mais recentes primeiro, depois em ordem alfabética
curl "https://api.kinescope.io/v1/videos?order=created_at.desc,title.asc" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

# Por data de criação crescente apenas
curl "https://api.kinescope.io/v1/videos?order=created_at.asc" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

Se um campo for especificado sem direção, asc é usado por padrão.

Importante: Nem todos os campos suportam ordenação. Se um campo inválido for especificado, a API retornará um erro com código 400216 (NOT_ALLOWED_ORDER_FIELD).

Formato de data

Para analytics e intervalos de tempo

Os parâmetros from e to suportam dois formatos:

1. Formato curto: YYYY-MM-DD (por exemplo, 2024-01-01)
2. Formato completo: RFC3339 YYYY-MM-DDTHH:MM:SSZ (por exemplo, 2024-01-01T00:00:00Z)

Exemplo:

curl "https://api.kinescope.io/v1/analytics/overview?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

Ambos os parâmetros são obrigatórios para endpoints de analytics.

Tratamento de erros

Formato de erro

Todos os erros são retornados em um formato consistente:

{
  "error": {
    "code": 400404,
    "message": "not found",
    "detail": "The requested video does not exist or has been deleted"
  }
}

Códigos de resposta HTTP

Erro de validação

Para erros de validação, a resposta também inclui um array invalid_params:

{
  "error": {
    "code": 400400,
    "message": "validation error",
    "invalid_params": [
      {
        "name": "title",
        "reason": "required",
        "message": "Title is required"
      },
      {
        "name": "privacy_type",
        "reason": "oneof",
        "message": "Must be one of: anywhere, nowhere, custom"
      }
    ]
  }
}

Formatos especiais de resposta

Exportação CSV

Alguns endpoints suportam exportação de dados em formato CSV via sufixo .csv na URL:

Exemplo:

# JSON (padrão)
curl "https://api.kinescope.io/v1/billing/invoices/123" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

# CSV
curl "https://api.kinescope.io/v1/billing/invoices/123.csv" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

Importante: O formato CSV não é suportado por todos os endpoints. Verifique a documentação do endpoint específico ou tente adicionar .csv à URL — se o formato não for suportado, JSON será retornado.

Limites e restrições

Os números acima são publicados, mas não se confirmam na prática: 50 requisições paralelas passam sem nenhum 429. A API não envia RateLimit-* nem Retry-After. Veja a seção «Erros» da referência da API para a descrição atual.

O que fazer a seguir?

Agora que você conhece as regras gerais da API, pode prosseguir para seções específicas:

1. Upload de arquivos via API — upload de vídeos e materiais complementares
2. Referência da API — documentação completa da API
3. Analytics — obtendo estatísticas de visualização via API
4. Autenticação JWT para chat — configurando autorização do chat de stream
5. Backend de autorização — controle de acesso a vídeos

Ainda tem dúvidas? Escreva para o chat de suporte na interface do Kinescope — nossos especialistas vão ajudar!