API REST
BientôtRéférence API
La référence API complète sera auto-générée à partir de notre spec OpenAPI 3.1 dès que la surface sera stable. On préfère shipper un placeholder plutôt que de fake-doc des endpoints qui peuvent encore bouger. En attendant, voici la forme, ce que ça couvrira, et quoi utiliser aujourd'hui.
Forme (sujette à changement)
REST sur HTTPS. JSON en entrée, JSON en sortie. Versionné dans le path : /v1/.... Deux schémas d'authentification existent, et celui que vous envoyez déclare quel type de principal vous êtes : Authorization: ApiKey <prefix>.<secret> pour un appelant programmatique, Authorization: Bearer <token> pour une session connectée. Chaque route décide des types qu'elle accepte, et rien ne se déduit de l'URL : la plupart des routes projet acceptent les deux, /v1/mcp/* n'accepte que la clé d'API, les routes de compte et de staff n'acceptent que la session. Tout autre cas renvoie 401. Les scopes d'une clé d'API sont mappés en rôle projet avant le contrôle de permission (project:read devient viewer, project:write ou cdn:write devient developer). Attention au Bearer : sur /v1/feedback/* et /v1/in-context/* il porte un jeton d'utilisateur final à portée restreinte, une famille de jetons différente d'une session ; vérifiez laquelle la surface attend. Le rate-limit ne s'applique qu'à trois surfaces (feedback, bundle, missing), et leurs headers sont préfixés par famille : X-Feedback-RateLimit-Limit, -Remaining, -Reset, plus X-Feedback-Quota-Remaining. Il n'existe aucun header générique X-RateLimit-*, et tous les autres endpoints /v1/ ne renvoient aucun header de limitation. Le décompte se fait par organisation, pas par clé d'API : émettre une seconde clé n'augmente pas votre budget, elle le partage.
curl 1# chaque endpoint prend une clé API dans le header Authorization2curl https://api.sonenta.dev/v1/projects \3 -H "Authorization: ApiKey snt_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }Les clés API viennent de Org Settings → API Keys dans le dashboard. La même clé fonctionne pour la CLI, le serveur MCP, et les appels REST directs, l'API consomme juste le bearer.
Ressources au lancement
Voici les ressources que l'API V1 exposera. La forme exacte, champs, codes d'erreur, pagination, sera figée à la publication de la spec OpenAPI.
| Ressource | Ce que ça représente | Ops V1 |
|---|---|---|
| Projects | Workspaces. Create, list, archive, transfer d'ownership. | GET · POST · PATCH · DELETE |
| Locales | Set de locales scopé au projet. Ajouter une locale, marquer comme défaut, activer/désactiver pour les clients. | GET · POST · PATCH · DELETE |
| Namespaces | Buckets logiques de clés par projet (ex. « checkout », « common »). | GET · POST · PATCH · DELETE |
| Keys | Clés de traduction avec leur description, URLs de screenshot, max-length, règles de pluriel. | GET · POST · PATCH · DELETE |
| Translations | Valeur par locale d'une clé. États draft / in-review / approved ; historique de révisions. | GET · POST · PATCH · DELETE |
| Missing keys | La file du SDK runtime. List, group by frequency, marquer triagé. | GET · PATCH |
| Webhooks | S'abonner aux events de traduction. V2. | V2 |
Quoi faire aujourd'hui
À peu près tout ce pour quoi vous appelleriez l'API est déjà exposé via la CLI, le serveur MCP, ou le SDK runtime. Utilisez-les, quand l'API shippe, votre code pourra basculer vers des appels HTTP directs sans changer ce qu'il fait vraiment.
Quand la référence publique arrive ?
La spec OpenAPI publique sera servie à https://api.sonenta.dev/openapi.json dès que la surface V1 sera figée. À ce moment, cette page passera de placeholder à une référence rendue intégralement (Stoplight ou un viewer similaire au-dessus de la spec), pas de marketing, juste chaque endpoint, chaque payload, chaque code d'erreur, généré depuis la source.