Autenticação, erros e limites
Tudo o que vale para todas as rotas: como se identificar, o que cada escopo permite, o formato dos erros e quantas requisições cabem por minuto.
Autenticação
Chave de API no cabeçalho Authorization, com o prefixo Bearer. A URL base é https://praeko.app; tudo é JSON em UTF-8.
Authorization: Bearer praeko_…
X-Praeko-Contract: en| Item | Detalhe |
|---|---|
| Formato da chave | Começa com praeko_. Chaves antigas começam com arauto_ e continuam valendo. |
X-Praeko-Contract: en |
Escolhe o contrato em inglês nos caminhos que existem nos dois contratos (/v1/posts, /v1/insights, /v1/youtube/videos). Sempre envie. |
| Segredo | Mostrado uma vez, ao criar. O Praeko guarda só o hash. |
| Cookie do painel | Só para o painel. Programas devem usar chave de API. |
| Agentes de IA (MCP) | O servidor MCP em https://praeko.app/mcp aceita a chave de API ou o login por OAuth (o agente abre uma tela de consentimento e você escolhe o acesso). Veja Servidor MCP. |
Escopos
Cada chave tem um escopo e cada nível inclui o anterior. O escopo mínimo de cada rota aparece como selo na referência.
| Escopo | Permite | Rotas |
|---|---|---|
| read | Ler canais, posts, calendário, métricas, comentários, uso. | GET na maioria dos recursos |
| write | Criar, editar e cancelar posts; subir mídia; responder comentários; horários; ideias. | POST, PUT, PATCH, DELETE de conteúdo |
| admin | Chaves, webhooks, token do Instagram, importar métricas. | api-keys, webhooks, insights/import |
Erros
O status HTTP é o da falha. O corpo segue sempre o mesmo envelope; code é estável, message é texto em português.
{
"error": {
"code": "time_in_past",
"message": "tiktok: 2026-11-01T10:00:00Z já passou ou é daqui a menos de 30 s",
"details": {}
}
}| Status | code | Significa |
|---|---|---|
| 400 | empty_body, invalid_json |
Corpo vazio ou que não é um objeto JSON. |
| 401 | unauthorized, invalid_api_key, revoked_api_key, expired_api_key |
Sem chave, ou chave inexistente, revogada, expirada. Traz WWW-Authenticate: Bearer. |
| 403 | forbidden |
O escopo da chave não basta. |
| 404 | post_not_found, media_not_found, webhook_not_found… |
O recurso não existe neste workspace. |
| 409 | channel_not_connected, no_slots, media_not_ready… |
O estado atual impede a ação. |
| 413 | body_too_large |
O corpo passa de 1 MB. |
| 422 | invalid_field, invalid_request, time_in_past… |
Campo inválido; details.errors lista todos. Campos em português são recusados. |
| 429 | rate_limited |
Limite por minuto. Traz Retry-After. |
| 502 | youtube_error, instagram_error, tiktok_unavailable, buffer_error |
A rede recusou; a mensagem dela vem no corpo. |
A lista completa dos códigos do contrato, com status e significado, está em Erros e limites.
Limites
| Limite | Valor |
|---|---|
| Requisições | 300 por minuto por chave (aproximado, por instância). Passou: 429 com Retry-After. |
| Corpo JSON | 1 MB |
| Arquivo de mídia | Até 50 MiB de uma vez (simple: true); acima, em partes de no mínimo 5 MiB |
| Webhooks | 10 por workspace; entrega com 10 s de limite |
| Log de uso | 30 dias, só metadados |
Idempotência
Mande o cabeçalho Idempotency-Key (um UUID) em POST, PATCH e DELETE e uma repetição depois de uma falha de rede devolve a resposta da primeira vez, com Idempotent-Replayed: true, sem criar nada de novo. A chave vale 24 horas, por workspace e por rota. Chave reusada com outro pedido volta 422 idempotency_key_reuse; primeiro pedido ainda em andamento volta 409 idempotency_in_progress. Sem o cabeçalho nada muda. Detalhes, curl, SDK e CLI em Repetir uma requisição.
curl -X POST https://praeko.app/v1/posts \
-H "Authorization: Bearer $PRAEKO_KEY" -H "X-Praeko-Contract: en" \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" -d @post.jsonVersões e changelog
A versão vai no caminho: /v1. Os caminhos em português continuam respondendo, marcados com Deprecation: true e Link: …; rel="successor-version". A data para desligá-los ainda não foi fixada. O changelog público lista as mudanças, com a data de cada uma.
Caminhos descontinuados
Estes caminhos em português ainda funcionam e respondem com Deprecation: true e Link: <novo>; rel="successor-version": os aliases /v1/... em português (por exemplo /v1/canais, no lugar de /v1/channels), /saude (use /health) e /conexoes/:rede/retorno (use /connections/:network/callback). No painel, os endereços antigos (#/publicar, #/canais, #/conectar-agente…) são reescritos para os novos (#/publish, #/channels, #/connect-agent…) e /entrar redireciona (301) para /sign-in. Mude as suas integrações para os caminhos novos. Antes de desligar qualquer um, o aviso sai aqui no changelog, com pelo menos 90 dias de antecedência; a data ainda não foi fixada.