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. Auth bearer-token przy każdym żądaniu. Wersjonowane w ścieżce: /v1/.... Rate-limit per token; odpowiedź niesie zwykłe nagłówki X-RateLimit-*.

curl

1# każdy endpoint przyjmuje klucz API w nagłówku Authorization2curl https://api.verbumia.ca/v1/projects \3  -H "Authorization: ApiKey vrb_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

@verbumia/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.

Live OpenAPI dla early devs

Jeśli odpalasz backend Verbumia lokalnie, live'owa specka OpenAPI 3.1 jest wystawiona pod:

backend lokalny

http://localhost:8820/openapi.json

Wskaż Stoplight, Swagger UI, Insomnia, Postman lub dowolne narzędzie świadome OpenAPI na ten URL. Kształt się rusza — dlatego ta strona jest placeholderem — ale to teraz źródło prawdy, jeśli chcesz wcześnie eksplorować endpointy.

Kiedy pojawi się publiczna referencja?

Publiczna specka OpenAPI będzie serwowana pod https://api.verbumia.ca/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.