API reference

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

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

REST поверх HTTPS. JSON на вход, JSON на выход. Версионирование в пути: /v1/.... Существуют две схемы аутентификации, и та, которую вы отправляете, объявляет, какого рода принципалом вы являетесь: Authorization: ApiKey <prefix>.<secret> для программного вызова, Authorization: Bearer <token> для авторизованной сессии. Каждый маршрут сам решает, какие типы принимает, поэтому из URL ничего вывести нельзя: большинство проектных маршрутов принимают оба варианта, /v1/mcp/* принимает только ключи API, а маршруты аккаунта и staff принимают только сессию. Любой другой случай возвращает 401. Scopes ключа API отображаются на проектную роль до проверки прав (project:read становится viewer, project:write или cdn:write становится developer). Осторожно с Bearer: на /v1/feedback/* и /v1/in-context/* он несёт токен конечного пользователя с ограниченной областью, это другое семейство токенов, чем сессия; проверьте, какое из них ожидает конкретная поверхность. Rate-limit применяется только к трём поверхностям (feedback, bundle, missing), и их headers имеют префикс по семейству: X-Feedback-RateLimit-Limit, -Remaining, -Reset, плюс X-Feedback-Quota-Remaining. Универсального заголовка X-RateLimit-* не существует, а все остальные endpoints /v1/ вообще не возвращают заголовков ограничения. Подсчёт ведётся по организации, а не по ключу API: выпуск второго ключа не увеличивает ваш бюджет, а делит его.

curl

1# каждый эндпоинт принимает API-ключ в заголовке Authorization2curl https://api.sonenta.dev/v1/projects \3  -H "Authorization: ApiKey snt_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

@sonenta/cli

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

MCP

Настрой Claude Desktop

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

SDK

React + i18next

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

Справка

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

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

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

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