Referencja API

Pełna referencja API zostanie auto-generowana z naszej specki OpenAPI 3.1, gdy tylko surface się ustabilizuje. Wolimy wypuścić placeholder niż fake-dokumentować endpointy, które jeszcze mogą się zmienić. Tymczasem oto kształt, co obejmie i co zrobić dziś.

Kształt (może się zmienić)

REST przez HTTPS. JSON na wejściu, JSON na wyjściu. Wersjonowane w ścieżce: /v1/.... Istnieją dwa schematy uwierzytelniania, a ten, który wysyłasz, deklaruje, jakim typem principala jesteś: Authorization: ApiKey <prefix>.<secret> dla wywołania programowego, Authorization: Bearer <token> dla zalogowanej sesji. Każda trasa sama decyduje, które typy akceptuje, więc z URL nic nie wynika: większość tras projektowych przyjmuje oba, /v1/mcp/* przyjmuje wyłącznie klucze API, a trasy konta i staff przyjmują wyłącznie sesję. Każdy inny przypadek zwraca 401. Scopes klucza API są mapowane na rolę projektową przed kontrolą uprawnień (project:read staje się viewer, project:write lub cdn:write staje się developer). Uwaga na Bearer: na /v1/feedback/* i /v1/in-context/* niesie token użytkownika końcowego o ograniczonym zakresie, czyli inną rodzinę tokenów niż sesja; sprawdź, której oczekuje dana surface. Rate-limit dotyczy tylko trzech surfaces (feedback, bundle, missing), a ich headers mają prefiks według rodziny: X-Feedback-RateLimit-Limit, -Remaining, -Reset, plus X-Feedback-Quota-Remaining. Nie istnieje żaden ogólny header X-RateLimit-*, a wszystkie pozostałe endpoints /v1/ nie zwracają żadnych headers ograniczeń. Liczy się na organizację, a nie na klucz API: wydanie drugiego klucza nie zwiększa twojego budżetu, tylko go dzieli.

curl

1# każdy endpoint przyjmuje klucz API w nagłówku Authorization2curl https://api.sonenta.dev/v1/projects \3  -H "Authorization: ApiKey snt_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }

Klucze API pochodzą z Org Settings → API Keys w panelu. Ten sam klucz działa dla CLI, serwera MCP i bezpośrednich callów REST, API po prostu konsumuje bearer.

Zasoby przy starcie

Oto zasoby, które API V1 wystawi. Dokładny kształt, pola, kody błędów, paginacja, pojawi się przy publikacji specki OpenAPI.

Zasób	Co reprezentuje	Ops V1
Projects	Workspace'y. Tworzenie, listowanie, archiwizacja, transfer własności.	GET · POST · PATCH · DELETE
Locales	Zestaw locale w obrębie projektu. Dodaj locale, oznacz jako domyślny, włącz/wyłącz dla klientów.	GET · POST · PATCH · DELETE
Namespaces	Logiczne kubły kluczy w projekcie (np. "checkout", "common").	GET · POST · PATCH · DELETE
Keys	Klucze tłumaczeń z opisem, URL-ami screenshotów, max-length, regułami liczby mnogiej.	GET · POST · PATCH · DELETE
Translations	Wartość klucza per locale. Stany draft, in-review, approved; historia rewizji.	GET · POST · PATCH · DELETE
Missing keys	Kolejka SDK runtime. Listuj, grupuj po częstotliwości, oznacz jako triagowane.	GET · PATCH
Webhooks	Subskrybuj eventy tłumaczeń. V2.	V2

Co zrobić dziś

Niemal wszystko, po co sięgnąłbyś do API, jest już wystawione przez CLI, serwer MCP albo SDK runtime. Korzystaj z nich, gdy API wystartuje, twój kod może przejść na bezpośrednie calle HTTP bez zmiany tego, co faktycznie robi.

CLI

@sonenta/cli

Push, pull, import, export, pokrywa większość potrzeb automatyzacji.

MCP

Skonfiguruj Claude Desktop

Czytaj klucze, proponuj tłumaczenia, recenzuj diffy PR z dowolnego agenta.

SDK

React + i18next

Czytaj tłumaczenia i wyłapuj brakujące klucze w runtime.

Referencja

Wszystkie dokumenty

Indeks wszystkiego, co dotąd opublikowaliśmy.

Kiedy pojawi się publiczna referencja?

Publiczna specka OpenAPI będzie serwowana pod https://api.sonenta.dev/openapi.json jak tylko surface V1 zostanie zamrożony. Od tej chwili ta strona zmieni się z placeholdera w pełni wyrenderowaną referencję (Stoplight albo podobny viewer nad specką), żadnego marketingu, tylko każdy endpoint, każdy payload, każdy kod błędu, generowane ze źródła.