HTTP API
Один шлюз на весь HTTP. v1 — развёрнутый JSON, v2 — тот же путь и статус, тело — RPC envelope. Справочник методов: /api/docs.
Версии
| v1 | v2 | |
|---|---|---|
| Префикс | /api/v1, плюс /api/auth | /api/v2. Auth остаётся на v1 |
| Успех | Голый ресурс | {ok: true, data, warnings?} |
| Ошибка | {detail, code?, fields?, retry_after?} | {ok: false, error: {code, message, details?}} |
Ветвитесь по code / error.code. Человеческое сообщение показывайте, не парсите.
Коды
| code | HTTP | Когда |
|---|---|---|
unauthorized | 401 | Нет или протух bearer. На session-only маршрутах — и ключ. |
forbidden | 403 | Аутентифицирован, но нет права, воркспейса или скоупа. |
not_found | 404 | Нет id или id чужого воркспейса. |
unprocessable | 422 | JSON прошёл, схема или правило — нет. Смотрите fields. |
rate_limited | 429 | Ждите retry_after секунд и заголовок Retry-After. |
Воркспейс в запросе
Чтения с арендой принимают workspace_id. У ключа он один — параметр можно не слать, шлюз подставит. Явное значение всегда побеждает. Сессия с несколькими воркспейсами должна указать один, иначе отказ, без угадывания.