Referencia API

La referencia API completa se auto-generará desde nuestra spec OpenAPI 3.1 en cuanto la superficie sea estable. Preferimos shipear un placeholder a fake-doc endpoints que aún pueden moverse. Mientras tanto, aquí va la forma, qué cubrirá y qué hacer hoy.

Forma (sujeta a cambios)

REST sobre HTTPS. JSON in, JSON out. Auth por Bearer token en cada request. Versionado en el path: /v1/.... Rate-limit por token; la respuesta lleva los habituales headers X-RateLimit-*.

curl

1# cada endpoint toma una API key en el header Authorization2curl https://api.verbumia.ca/v1/projects \3  -H "Authorization: ApiKey vrb_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }

Las API keys vienen de Org Settings → API Keys en el dashboard. La misma key sirve para el CLI, el servidor MCP y llamadas REST directas — la API solo consume el bearer.

Recursos que verás en el lanzamiento

Estos son los recursos que la API V1 expondrá. La forma exacta — campos, códigos de error, paginación — aterriza cuando publiquemos la spec OpenAPI.

Recurso	Qué representa	Ops V1
Projects	Workspaces. Create, list, archive, transfer ownership.	GET · POST · PATCH · DELETE
Locales	Conjunto de locales con scope de proyecto. Añadir un locale, marcarlo como default, habilitar/deshabilitar para clientes.	GET · POST · PATCH · DELETE
Namespaces	Buckets lógicos de claves por proyecto (p. ej. "checkout", "common").	GET · POST · PATCH · DELETE
Keys	Claves de traducción con su descripción, URLs de screenshot, max-length, reglas de plural.	GET · POST · PATCH · DELETE
Translations	Valor por locale de una clave. Estados draft, in-review, approved; historial de revisiones.	GET · POST · PATCH · DELETE
Missing keys	La cola del SDK runtime. List, group by frequency, marcar como triada.	GET · PATCH
Webhooks	Suscríbete a eventos de traducción. V2.	V2

Qué hacer hoy

Casi todo para lo que recurrirías a la API ya está expuesto vía el CLI, el servidor MCP o el SDK runtime. Úsalos — cuando la API shipee, tu código podrá pasar a llamadas HTTP directas sin cambiar lo que realmente hace.

CLI

@verbumia/cli

Push, pull, import, export — cubre la mayoría de las necesidades de automatización.

MCP

Configurar Claude Desktop

Lee claves, propone traducciones, revisa diffs de PR desde cualquier agente.

SDK

React + i18next

Lee traducciones y captura claves faltantes en tu runtime.

Referencia

Todas las docs

Índice de todo lo que hemos publicado hasta ahora.

OpenAPI live para early devs

Si corres el backend de Verbumia en local, la spec OpenAPI 3.1 live se expone en:

backend local

http://localhost:8820/openapi.json

Apunta Stoplight, Swagger UI, Insomnia, Postman o cualquier herramienta compatible con OpenAPI a esa URL. La forma se está moviendo — por eso esta página es un placeholder — pero ahora mismo es la fuente de verdad si quieres explorar endpoints temprano.

¿Cuándo aterriza la referencia pública?

La spec OpenAPI pública se servirá en https://api.verbumia.ca/openapi.json en cuanto la superficie V1 quede congelada. A partir de ahí, esta página pasará de placeholder a una referencia renderizada al completo (Stoplight o un viewer similar sobre la spec) — sin copy de marketing, solo cada endpoint, cada payload, cada código de error, generado desde la fuente.