API REST
In arrivoRiferimento API
Il riferimento API completo sarà auto-generato dalla nostra spec OpenAPI 3.1 nel momento in cui la superficie sarà stabile. Preferiamo shippare un placeholder piuttosto che fake-doc endpoint che possono ancora muoversi. Nel frattempo, ecco la forma, cosa coprirà e cosa fare oggi.
Forma (soggetta a cambiamenti)
REST su HTTPS. JSON in, JSON out. Versionato nel path: /v1/.... Esistono due schemi di autenticazione, e quello che invii dichiara che tipo di principal sei: Authorization: ApiKey <prefix>.<secret> per un chiamante programmatico, Authorization: Bearer <token> per una sessione autenticata. Ogni route decide quali tipi accetta, quindi nulla si deduce dall'URL: la maggior parte delle route di progetto accetta entrambi, /v1/mcp/* accetta solo chiavi API, e le route di account e di staff accettano solo la sessione. Qualsiasi altro caso restituisce 401. Gli scope di una chiave API vengono mappati su un ruolo di progetto prima del controllo dei permessi (project:read diventa viewer, project:write o cdn:write diventa developer). Attenzione al Bearer: su /v1/feedback/* e /v1/in-context/* porta un token di utente finale con scope ristretto, una famiglia di token diversa da una sessione; verifica quale si aspetta la surface. Il rate-limit si applica solo a tre surface (feedback, bundle, missing), e i loro header sono prefissati per famiglia: X-Feedback-RateLimit-Limit, -Remaining, -Reset, più X-Feedback-Quota-Remaining. Non esiste alcun header generico X-RateLimit-*, e tutti gli altri endpoint /v1/ non restituiscono alcun header di limitazione. Il conteggio è per organizzazione, non per chiave API: emettere una seconda chiave non aumenta il tuo budget, lo condivide.
curl 1# ogni endpoint prende una API key nell'header Authorization2curl https://api.sonenta.dev/v1/projects \3 -H "Authorization: ApiKey snt_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }Le API key vengono da Org Settings → API Keys nella dashboard. La stessa key funziona per la CLI, il server MCP e le chiamate REST dirette, l'API consuma solo il bearer.
Risorse che vedrai al lancio
Queste sono le risorse che l'API V1 esporrà. La forma esatta, campi, codici d'errore, paginazione, atterra quando pubblicheremo la spec OpenAPI.
| Risorsa | Cosa rappresenta | Ops V1 |
|---|---|---|
| Projects | Workspace. Create, list, archive, transfer ownership. | GET · POST · PATCH · DELETE |
| Locales | Set di locali con scope di progetto. Aggiungi un locale, segnalo come default, abilita/disabilita per i client. | GET · POST · PATCH · DELETE |
| Namespaces | Bucket logici di chiavi per progetto (es. "checkout", "common"). | GET · POST · PATCH · DELETE |
| Keys | Chiavi di traduzione con la loro descrizione, URL di screenshot, max-length, regole di plurale. | GET · POST · PATCH · DELETE |
| Translations | Valore per locale di una chiave. Stati draft, in-review, approved; storia delle revisioni. | GET · POST · PATCH · DELETE |
| Missing keys | La coda dell'SDK runtime. List, group by frequency, marca come triata. | GET · PATCH |
| Webhooks | Iscriviti agli event di traduzione. V2. | V2 |
Cosa fare oggi
Praticamente tutto per cui ricorreresti all'API è già esposto via la CLI, il server MCP o l'SDK runtime. Usali, quando l'API shippa, il tuo codice può passare a chiamate HTTP dirette senza cambiare quello che fa davvero.
Quando atterra il riferimento pubblico?
La spec OpenAPI pubblica sarà servita a https://api.sonenta.dev/openapi.json non appena la superficie V1 sarà congelata. Da lì, questa pagina passerà da placeholder a un riferimento renderizzato per intero (Stoplight o un viewer simile sopra la spec), niente copy di marketing, solo ogni endpoint, ogni payload, ogni codice d'errore, generato dalla sorgente.