API reference

Полный API reference автоматически сгенерируется из нашей OpenAPI 3.1 spec, как только поверхность стабилизируется. Лучше зашипить плейсхолдер, чем фейк-документировать эндпоинты, которые ещё могут двигаться. А пока — вот форма, что она покроет, и что делать сегодня.

Форма (может меняться)

REST поверх HTTPS. JSON на вход, JSON на выход. Bearer-token аутентификация в каждом запросе. Версионирование в пути: /v1/.... Rate-limit по токену; в ответе обычные хедеры X-RateLimit-*.

curl

1# каждый эндпоинт принимает API-ключ в заголовке Authorization2curl https://api.verbumia.ca/v1/projects \3  -H "Authorization: ApiKey vrb_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }

API-ключи берутся в Org Settings → API Keys в дашборде. Один и тот же ключ подходит CLI, MCP server и прямым REST-вызовам — API просто потребляет bearer.

Ресурсы на старте

Эти ресурсы будут доступны в V1 API. Точная форма — поля, коды ошибок, пагинация — зафиксируется при публикации OpenAPI spec.

Ресурс	Что представляет	Операции V1
Projects	Workspace'ы. Create, list, archive, передача ownership.	GET · POST · PATCH · DELETE
Locales	Набор локалей в рамках проекта. Добавить локаль, отметить как дефолтную, включать/выключать для клиентов.	GET · POST · PATCH · DELETE
Namespaces	Логические корзины ключей внутри проекта (например, "checkout", "common").	GET · POST · PATCH · DELETE
Keys	Ключи переводов с описанием, URL'ами скриншотов, max-length, plural rules.	GET · POST · PATCH · DELETE
Translations	Значение ключа на конкретной локали. Состояния draft, in-review, approved; история ревизий.	GET · POST · PATCH · DELETE
Missing keys	Очередь runtime SDK. List, group by frequency, пометка как triaged.	GET · PATCH
Webhooks	Подписка на события переводов. V2.	V2

Что делать сегодня

Почти всё, ради чего тебе понадобился бы API, уже доступно через CLI, MCP server или runtime SDK. Используй их — когда API выйдет, твой код переключится на прямые HTTP-вызовы без изменения сути.

CLI

@verbumia/cli

Push, pull, import, export — закрывает большинство автоматизаций.

MCP

Настрой Claude Desktop

Читай ключи, предлагай переводы, ревьюй PR-diff из любого агента.

SDK

React + i18next

Читай переводы и захватывай пропущенные ключи в рантайме.

Справка

Вся документация

Указатель всего, что мы опубликовали.

Live OpenAPI для ранних разработчиков

Если ты крутишь Verbumia backend локально, live OpenAPI 3.1 spec доступна по адресу:

локальный backend

http://localhost:8820/openapi.json

Натравливай Stoplight, Swagger UI, Insomnia, Postman или любой инструмент с поддержкой OpenAPI на этот URL. Форма движется — потому эта страница и плейсхолдер — но это сейчас источник истины, если хочешь поковыряться с эндпоинтами заранее.

Когда выйдет публичный reference?

Публичная OpenAPI spec будет отдаваться по https://api.verbumia.ca/openapi.json, как только поверхность V1 будет заморожена. Тогда эта страница из плейсхолдера превратится в полностью отрендеренный reference (Stoplight или похожий viewer над spec) — без маркетинга, только каждый эндпоинт, каждый payload, каждый код ошибки, сгенерированный из исходника.