Referê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. Auth com Bearer token em cada request. Versionado no path: /v1/.... Rate-limit por token; a resposta traz os habituais headers X-RateLimit-*.

curl

1# cada endpoint leva uma API key no header Authorization2curl https://api.verbumia.ca/v1/projects \3  -H "Authorization: ApiKey vrb_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.

CLI

@verbumia/cli

Push, pull, import, export — cobre a maioria das necessidades de automação.

MCP

Configurar o Claude Desktop

Lê chaves, propõe traduções, revê diffs de PR a partir de qualquer agente.

SDK

React + i18next

Lê traduções e captura chaves em falta no teu runtime.

Referência

Todas as docs

Índice de tudo o que publicámos até agora.

OpenAPI live para early devs

Se estás a correr o backend Verbumia localmente, a spec OpenAPI 3.1 live está exposta em:

backend local

http://localhost:8820/openapi.json

Aponta Stoplight, Swagger UI, Insomnia, Postman ou qualquer ferramenta compatível com OpenAPI para esse URL. A forma está a mexer-se — é por isso que esta página é um placeholder — mas é a fonte da verdade neste momento se quiseres explorar endpoints cedo.

Quando aterra a referência pública?

A spec OpenAPI pública será servida em https://api.verbumia.ca/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.