Справочник API

Все эндпоинты строятся от базового URL вашего инстанса (например, https://api.runne.run). Режимы аутентификации:

• Сессия — cookie runne_session (кабинет клиента). Маршруты с проверкой владения дополнительно требуют, чтобы сессия владела воркспейсом.
• API-ключ — Authorization: Bearer rn_live_… или x-api-key: rn_live_….
• Вебхук — HMAC-подпись в X-YooKassa-Signature.
• Публичный — без аутентификации.

Auth и сессия

Метод	Путь	Auth	Скоуп	Описание
POST	/v1/auth/register	Публичный (auth rate limit 5/мин/IP)	—	Регистрация {email, password, name}; авто-вход, 201 {customer_id, email}
POST	/v1/auth/login	Публичный (auth rate limit 10/мин/IP)	—	Вход {email, password}; 200 {expires_at} + cookie сессии
POST	/v1/auth/logout	Сессия	—	Отзыв jti сессии на сервере, очистка cookie; {success: true}
GET	/v1/auth/me	Сессия	—	{customer_id, email, name, status, is_platform_admin}

Воркспейсы

Метод	Путь	Auth	Скоуп	Описание
POST	/v1/workspaces	Сессия	—	Создать воркспейс {name}; 201 DTO воркспейса
GET	/v1/workspaces	Сессия	—	Список своих воркспейсов; {workspaces: [...]}

API-ключи

Метод	Путь	Auth	Скоуп	Описание
POST	/v1/workspaces/{workspace_id}/api-keys	Сессия (владелец)	—	Создать ключ {name, scopes[], rate_limit?}; 201 включая raw_key (однократно)
GET	/v1/workspaces/{workspace_id}/api-keys	Сессия (владелец)	—	Список ключей; {api_keys: [...]}
DELETE	/v1/workspaces/{workspace_id}/api-keys/{api_key_id}	Сессия (владелец)	—	Отозвать ключ; {success: true}

Платежи и вебхуки

Метод	Путь	Auth	Скоуп	Описание
POST	/v1/payments	Сессия	—	Создать платёж YooKassa {workspace_id, amount_rubles, description?}; 201
GET	/v1/payments?workspace_id=	Сессия	—	Список платежей своего воркспейса
POST	/webhooks/yookassa	Вебхук (HMAC-SHA256)	—	Обработать payment.succeeded/canceled, receipt.succeeded/canceled (идемпотентно)

Реестр и баланс

Метод	Путь	Auth	Скоуп	Описание
GET	/v1/workspaces/{workspace_id}/transactions	Сессия (владелец)	—	История транзакций ?type=&from=&to=&limit=&offset=
GET	/v1/workspaces/{workspace_id}/balance	Сессия (владелец)	—	{balance, updated_at}
GET	/v1/balance	API-ключ	balance:read	{balance, currency, updated_at}

Потребление и стоимость

Метод	Путь	Auth	Скоуп	Описание
POST	/v1/cost/estimate	Публичный	—	Оценить стоимость {model, max_tokens}
GET	/v1/workspaces/{workspace_id}/usage-report	Сессия (владелец)	—	Агрегированное потребление `?from=&to=&group_by=day

Квоты

Метод	Путь	Auth	Скоуп	Описание
GET	/v1/workspaces/{workspace_id}/quota	Сессия (владелец)	—	Текущая квота; `{quota:
GET	/v1/workspaces/{workspace_id}/quota/usage	Сессия (владелец)	—	Потребление за текущий период; {usage: {...}}

Chat completions

Метод	Путь	Auth	Скоуп	Описание
POST	/v1/chat/completions	API-ключ + rate limit	chat:write	OpenAI-совместимый {model, messages[], max_tokens?}; в beta mock-провайдер

Модели

Метод	Путь	Auth	Скоуп	Описание
GET	/v1/models	Публичный	—	Список активных моделей с текущим прайсом
GET	/v1/models/{provider}/{model}	Публичный	—	Одна модель (в ответе нет прайса)

Admin (только platform admin)

Требует сессию, чей клиент is_platform_admin равен true. Не-админы получают 403.

Метод	Путь	Описание
GET	/v1/admin/dashboard/overview	Метрики системного обзора
GET	/v1/admin/dashboard/top-workspaces	Топ воркспейсов по потреблению (?limit=)
GET	/v1/admin/dashboard/top-models	Топ моделей по потреблению (?limit=)
GET	/v1/admin/customers	Список клиентов с пагинацией (?page=&limit=&status=)
GET	/v1/admin/customers/{customer_id}	Карточка клиента: профиль + воркспейсы
PUT	/v1/admin/customers/{customer_id}/status	Задать статус `{status: active
POST	/v1/admin/workspaces/{workspace_id}/adjust	Скорректировать баланс {amount, description} (decimal со знаком)
PUT	/v1/admin/workspaces/{workspace_id}/quota	Обновить квоту
PUT	/v1/admin/models/{provider}/{model}/pricing	Обновить прайс модели
GET	/v1/admin/models/{provider}/{model}/pricing-history	История прайса
GET	/v1/admin/workspaces/{workspace_id}/payments	Платежи воркспейса
GET	/v1/admin/workspaces/{workspace_id}/receipts	Чеки воркспейса

Системные

Метод	Путь	Auth	Описание
GET	/health	Публичный	{status: "ok"}
GET	/	Публичный	Информация о сервисе

Конверт ошибки

Не все не-2xx ответы используют один конверт. Доменные ошибки используют { "error": { "code": "…", "message": "…" } }; ошибки валидации 400 используют { "success": false, "error": { … } } (без code); некоторые 401/403 (подпись вебхука, владение api-key) возвращают плоскую строку { "error": "…" }. Таблицу кодов и рекомендации см. в Ошибки.