REST API
Bald verfügbarAPI-Referenz
Die vollständige API-Referenz wird automatisch aus unserer OpenAPI-3.1-Spec generiert, sobald die Surface stabil ist. Lieber ein Platzhalter als Fake-Doku zu Endpunkten, die sich noch ändern könnten. In der Zwischenzeit hier die Form, was abgedeckt wird, und was du heute tun kannst.
Form (kann sich ändern)
REST über HTTPS. JSON rein, JSON raus. Im Pfad versioniert: /v1/.... Es gibt zwei Authentifizierungsschemata, und das gesendete Schema erklärt, welche Art von Principal Sie sind: Authorization: ApiKey <prefix>.<secret> für einen programmatischen Aufrufer, Authorization: Bearer <token> für eine angemeldete Session. Jede Route entscheidet, welche Arten sie akzeptiert, aus der URL lässt sich also nichts ableiten: die meisten Projektrouten akzeptieren beide, /v1/mcp/* akzeptiert nur API-Keys, und Konto- und Staff-Routen akzeptieren nur die Session. Alles andere liefert 401. Die Scopes eines API-Keys werden vor der Rechteprüfung auf eine Projektrolle abgebildet (project:read wird viewer, project:write oder cdn:write wird developer). Vorsicht bei Bearer: auf /v1/feedback/* und /v1/in-context/* trägt es ein Endnutzer-Token mit eingeschränktem Scope, eine andere Token-Familie als eine Session; prüfen Sie, welche die jeweilige Surface erwartet. Rate-Limits gelten nur für drei Surfaces (feedback, bundle, missing), und ihre Header sind pro Familie präfixiert: X-Feedback-RateLimit-Limit, -Remaining, -Reset, plus X-Feedback-Quota-Remaining. Es gibt keinen generischen X-RateLimit-*-Header, und alle anderen /v1/-Endpunkte liefern gar keine Limit-Header. Gezählt wird pro Organisation, nicht pro API-Key: ein zweiter Key erhöht Ihr Budget nicht, er teilt es.
curl 1# jeder Endpunkt nimmt einen API-Key im Authorization-Header2curl https://api.sonenta.dev/v1/projects \3 -H "Authorization: ApiKey snt_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }API-Keys kommen aus Org Settings → API Keys im Dashboard. Derselbe Key funktioniert für die CLI, den MCP-Server und direkte REST-Calls, die API konsumiert einfach den Bearer.
Ressourcen zum Launch
Diese Ressourcen wird die V1-API exponieren. Die exakte Form, Felder, Error-Codes, Pagination, landet, wenn wir die OpenAPI-Spec veröffentlichen.
| Ressource | Was sie repräsentiert | V1-Ops |
|---|---|---|
| Projects | Workspaces. Anlegen, listen, archivieren, Ownership übertragen. | GET · POST · PATCH · DELETE |
| Locales | Projekt-scoped Locale-Set. Locale hinzufügen, als Default markieren, für Clients aktivieren/deaktivieren. | GET · POST · PATCH · DELETE |
| Namespaces | Logische Buckets von Keys pro Projekt (z. B. "checkout", "common"). | GET · POST · PATCH · DELETE |
| Keys | Übersetzungs-Keys mit Beschreibung, Screenshot-URLs, Max-Length, Plural-Regeln. | GET · POST · PATCH · DELETE |
| Translations | Wert eines Keys pro Locale. Draft-, In-Review-, Approved-States; Revisionshistorie. | GET · POST · PATCH · DELETE |
| Missing keys | Die Runtime-SDK-Queue. Listen, nach Frequenz gruppieren, als triagiert markieren. | GET · PATCH |
| Webhooks | Auf Übersetzungs-Events abonnieren. V2. | V2 |
Was du heute tun kannst
Fast alles, wofür du zur API greifen würdest, ist bereits über die CLI, den MCP-Server oder das Runtime-SDK verfügbar. Nutze sie, wenn die API kommt, kann dein Code auf direkte HTTP-Calls umsteigen, ohne dass sich an dem, was er tut, etwas ändert.
Wann landet die öffentliche Referenz?
Die öffentliche OpenAPI-Spec wird unter https://api.sonenta.dev/openapi.json ausgeliefert, sobald die V1-Surface eingefroren ist. Ab dann wechselt diese Seite vom Platzhalter zu einer voll gerenderten Referenz (Stoplight oder ein ähnlicher Viewer über der Spec), kein Marketing, nur jeder Endpunkt, jedes Payload, jeder Error-Code, aus der Source generiert.