Справочник API
Полный справочник пользовательского REST API — в репозитории:
docs/API.md.
Здесь — то, что нужно знать до первого запроса.
База и формат
Все пути относительно /api/v1, формат JSON. Ответы и коды ошибок на
английском; язык интерфейса — забота клиента.
Аутентификация
| Субъект | Механизм |
|---|---|
| Человек | Authorization: Bearer <access token>, 15 минут |
| Браузер | тот же заголовок + refresh в httpOnly-cookie |
| Машина | отдельный токен из /machine/login, скоуп «проект × окружение» |
Заголовок X-Client (web, cli, sdk, mobile) попадает в аудит и решает,
где окажется refresh-токен: браузеру он выдаётся только в cookie.
Ошибки
{ "error": { "code": "VALIDATION", "message": "..." } }
Ветвиться следует по code, а не по тексту. Каждый ответ несёт X-Request-Id —
это единственное, что нужно процитировать в обращении.
Пагинация
{ "items": [...], "nextCursor": "..." }. Курсор непрозрачный: передайте его
обратно в ?cursor=, пока он приходит.
Частая ошибка
GET /projects требует ?orgId= — без него ответ будет VALIDATION.