Référence API

La spec OpenAPI est servie en production

https://api.sonenta.dev/openapi.json

Mesuré le 2026-09-10 : OpenAPI 3.1.0, 439 chemins. Pointez Stoplight, Swagger UI, Insomnia, Postman ou n'importe quel outil compatible OpenAPI sur cette URL.

Ce que la spec ne décrit pas

Les routes de staff (/api/admin/*) sont retirées de la spec publiée. La spec décrit la surface client, pas la surface d'administration. Un outil qui génère un client depuis ce fichier ne verra donc jamais ces routes, ce qui est voulu.

La forme

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/*, le Bearer porte un jeton d'utilisateur final à portée restreinte, une famille de jetons différente d'une session. Vérifiez laquelle la surface attend.

Les clés d'API viennent de Org Settings → API Keys dans le dashboard.

curl https://api.sonenta.dev/v1/projects \
  -H "Authorization: ApiKey snt_live_<prefix>.<secret>"

Limites de débit

Le rate-limit couvre quatre surfaces : feedback, bundle, missing et MCP.

Les trois premières partagent une même famille d'en-têtes, préfixée par surface : X-Feedback-RateLimit-Limit, -Remaining, -Reset, plus X-Feedback-Quota-Remaining quand un plafond mensuel s'applique.

MCP a sa propre implémentation et ses propres en-têtes, X-MCP-RateLimit-* et X-MCP-Quota-Remaining, avec le code d'erreur mcp_rate_limited.

L'appairage de l'édition en contexte a son propre verrou anti-bruteforce : POST /v1/in-context/pair rend un 429 pairing_locked_out avec Retry-After, compté par adresse IP.

Il n'existe aucun en-tête générique X-RateLimit-*, et en dehors de ces surfaces aucun autre endpoint /v1/ n'expose de compteur documenté.

Deux choses à ne pas déduire :

• Les écritures feedback ne passent pas toutes par le compteur. Ne transposez pas d'une route à l'autre : lisez les en-têtes de la réponse que vous recevez.
• L'absence de X-Feedback-Quota-Remaining ne veut pas dire « aucun quota ». L'en-tête est simplement omis quand le plan ne porte pas de plafond mensuel.

Au-dessus du plafond, la réponse est un 429 en application/problem+json qui porte un code et un Retry-After en secondes.

Le décompte du rate-limit se fait par organisation, pas par clé d'API : émettre une seconde clé n'augmente pas votre budget, elle le partage.

Erreurs

Les erreurs suivent RFC 7807 (application/problem+json) : un objet avec type, title, status, code et detail, plus les champs propres à l'erreur. Le code est stable et destiné au traitement automatique ; le detail est destiné à un humain et peut changer.

Repli CDN

Les bundles publiés sont servis par le CDN. Si le CDN est injoignable, l'API sert les mêmes bundles en repli, sous /cdn/v1/.... Vos apps n'ont rien à faire : les SDK basculent seuls.

Les deux chemins ont des politiques de cache distinctes. Aucun délai de propagation n'est publié ici, parce qu'aucun n'a été chronométré de bout en bout.

Ressources

Ressource	Ce que ça représente
Projects	Workspaces. Create, list, archive, transfert de propriété.
Locales	Set de locales scopé au projet. Ajouter, marquer par défaut, activer ou désactiver pour les clients.
Namespaces	Buckets logiques de clés par projet, par exemple checkout ou common.
Keys	Clés de traduction avec description, screenshots, longueur maximale, règles de pluriel.
Translations	Valeur par locale d'une clé, avec ses statuts et son historique de révisions.
Missing keys	La file du SDK runtime. Lister, grouper par fréquence, marquer triagé.

Faut-il vraiment appeler l'API ?

À peu près tout ce pour quoi vous appelleriez l'API est déjà exposé ailleurs, et souvent plus commodément :

• @sonenta/cli : push, pull, import, export, releases. Couvre la plupart des besoins d'automatisation.
• MCP : lire les clés, proposer des traductions, publier, depuis n'importe quel agent.
• SDK : lire les traductions et capturer les clés manquantes à l'exécution.