API REST
PróximamenteReferencia 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. Versionado en el path: /v1/.... Existen dos esquemas de autenticación, y el que envías declara qué tipo de principal eres: Authorization: ApiKey <prefix>.<secret> para una llamada programática, Authorization: Bearer <token> para una sesión iniciada. Cada ruta decide qué tipos acepta, así que nada se deduce de la URL: la mayoría de las rutas de proyecto aceptan ambos, /v1/mcp/* solo acepta claves de API, y las rutas de cuenta y de staff solo aceptan sesión. Cualquier otro caso devuelve 401. Los scopes de una clave de API se asignan a un rol de proyecto antes del control de permisos (project:read pasa a viewer, project:write o cdn:write pasa a developer). Cuidado con Bearer: en /v1/feedback/* y /v1/in-context/* lleva un token de usuario final con alcance restringido, una familia de tokens distinta de una sesión; comprueba cuál espera la superficie. El rate-limit solo se aplica a tres superficies (feedback, bundle, missing), y sus headers llevan prefijo por familia: X-Feedback-RateLimit-Limit, -Remaining, -Reset, más X-Feedback-Quota-Remaining. No existe ningún header genérico X-RateLimit-*, y el resto de endpoints /v1/ no devuelve ningún header de limitación. El recuento es por organización, no por clave de API: emitir una segunda clave no aumenta tu presupuesto, lo comparte.
curl 1# cada endpoint toma una API key en el header Authorization2curl https://api.sonenta.dev/v1/projects \3 -H "Authorization: ApiKey snt_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.
¿Cuándo aterriza la referencia pública?
La spec OpenAPI pública se servirá en https://api.sonenta.dev/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.