API REST
Em breveReferência API
A referência API completa será auto-gerada a partir da nossa spec OpenAPI 3.1 assim que a superfície for estável. Preferimos shipar um placeholder do que fake-doc de endpoints que ainda podem mexer-se. Entretanto, aqui está a forma, o que vai cobrir e o que fazer hoje.
Forma (sujeita a alteração)
REST sobre HTTPS. JSON in, JSON out. Versionado no path: /v1/.... Existem dois esquemas de autenticação, e aquele que você envia declara que tipo de principal você é: Authorization: ApiKey <prefix>.<secret> para uma chamada programática, Authorization: Bearer <token> para uma sessão autenticada. Cada rota decide quais tipos aceita, portanto nada se deduz da URL: a maioria das rotas de projeto aceita ambos, /v1/mcp/* aceita apenas chaves de API, e as rotas de conta e de staff aceitam apenas a sessão. Qualquer outro caso devolve 401. Os scopes de uma chave de API são mapeados para um papel de projeto antes do controlo de permissões (project:read passa a viewer, project:write ou cdn:write passa a developer). Atenção ao Bearer: em /v1/feedback/* e /v1/in-context/* ele transporta um token de utilizador final com âmbito restrito, uma família de tokens diferente de uma sessão; verifique qual delas a surface espera. O rate-limit aplica-se apenas a três surfaces (feedback, bundle, missing), e os seus headers são prefixados por família: X-Feedback-RateLimit-Limit, -Remaining, -Reset, mais X-Feedback-Quota-Remaining. Não existe nenhum header genérico X-RateLimit-*, e todos os outros endpoints /v1/ não devolvem qualquer header de limitação. A contagem é por organização, não por chave de API: emitir uma segunda chave não aumenta o seu orçamento, partilha-o.
curl 1# cada endpoint leva uma API key no header Authorization2curl https://api.sonenta.dev/v1/projects \3 -H "Authorization: ApiKey snt_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }As API keys vêm de Org Settings → API Keys no dashboard. A mesma key serve para a CLI, o servidor MCP e chamadas REST diretas, a API só consome o bearer.
Recursos que vais ver no lançamento
Estes são os recursos que a API V1 vai expor. A forma exata, campos, códigos de erro, paginação, aterra quando publicarmos a spec OpenAPI.
| Recurso | O que representa | Ops V1 |
|---|---|---|
| Projects | Workspaces. Create, list, archive, transfer ownership. | GET · POST · PATCH · DELETE |
| Locales | Conjunto de locales com scope de projeto. Adicionar um locale, marcá-lo como default, ativar/desativar para clientes. | GET · POST · PATCH · DELETE |
| Namespaces | Buckets lógicos de chaves por projeto (p. ex. "checkout", "common"). | GET · POST · PATCH · DELETE |
| Keys | Chaves de tradução com a sua descrição, URLs de screenshot, max-length, regras de plural. | GET · POST · PATCH · DELETE |
| Translations | Valor por locale de uma chave. Estados draft, in-review, approved; histórico de revisões. | GET · POST · PATCH · DELETE |
| Missing keys | A fila do SDK runtime. List, group by frequency, marcar como triada. | GET · PATCH |
| Webhooks | Subscreve eventos de tradução. V2. | V2 |
O que fazer hoje
Quase tudo para o que recorrerias à API já está exposto via a CLI, o servidor MCP ou o SDK runtime. Usa-os, quando a API shipar, o teu código pode passar para chamadas HTTP diretas sem mudar o que realmente faz.
Quando aterra a referência pública?
A spec OpenAPI pública será servida em https://api.sonenta.dev/openapi.json assim que a superfície V1 estiver congelada. A partir daí, esta página passará de placeholder a uma referência totalmente renderizada (Stoplight ou um viewer similar sobre a spec), sem copy de marketing, apenas cada endpoint, cada payload, cada código de erro, gerado a partir da fonte.