API Reference

Все HTTP-методы

Полный справочник публичных, сессионных и служебных методов.

Справочник HTTP-методов

Раскройте карточку метода: в ней входные данные, успешный ответ и ограничения.

Provider API: модели и LLM

Единый минимальный API для приложений. SimpleClaw проверяет ключ, подписку и credits, а затем передаёт запрос во внутренний Model Gateway. До первого вызова прочитайте правила credits и ошибки.

GET/v1/modelsКаталог моделейПубличный

Доступ: Публичный

Запрос

Параметров нет.

Успешный ответ

JSON ответаПоказать

{
  "object": "list",
  "data": [
    {
      "id": "model-id",
      "object": "model",
      "owned_by": "openai",
      "display_name": "Название",
      "pricing": {
        "modelWeight": "2.5",
        "baseCreditsPerMillion": "35",
        "calculationVersion": "weighted-v2",
        "inputCreditsPerMillion": 87.5,
        "outputCreditsPerMillion": 437.5,
        "cacheReadCreditsPerMillion": 8.75,
        "reasoningCreditsPerMillion": 0
      }
    }
  ]
}

35 — только пример, не цена по умолчанию. Вес безразмерный, база задана за 1 млн приведённых токенов. Без действующей ставки модель недоступна для новых запросов.

GET/v1/models/favoritesСписок избранных моделейТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

[
  "model-id"
]

Возвращает public ID моделей, которые пользователь отметил в кабинете.

PUT/v1/models/:publicId/favoriteДобавить модель в избранноеТребуется авторизация

Доступ: Сессия

Запрос

Path: publicId модели из каталога.

Успешный ответ

JSON ответаПоказать

{
  "favorite": true
}

Идемпотентная операция. Недоступная модель вернёт MODEL_UNAVAILABLE.

DELETE/v1/models/:publicId/favoriteУбрать модель из избранногоТребуется авторизация

Доступ: Сессия

Запрос

Path: publicId модели.

Успешный ответ

JSON ответаПоказать

{
  "favorite": false
}

Идемпотентная операция: удаляет отметку только текущего пользователя.

POST/v1/chat/completionsОтправить сообщение моделиТребуется авторизация

Доступ: Bearer API key

Запрос

JSON запросаПоказать

{
  "model": "model-id",
  "messages": [
    {
      "role": "user",
      "content": "Привет"
    }
  ],
  "max_tokens": 1024,
  "temperature": 0.7
}

Успешный ответ

JSON ответаПоказать

{
  "id": "chatcmpl_…",
  "object": "chat.completion",
  "created": 0,
  "model": "model-id",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 1,
    "total_tokens": 2
  }
}

Поддерживаются model, текстовые messages, max_tokens (1–32768) и temperature (0–2). Поле message временно доступно для обратной совместимости. Streaming и tools пока не поддерживаются.

POST/v1/messagesAnthropic Messages для Claude CodeТребуется авторизация

Доступ: Bearer или x-api-key

Запрос

Header: anthropic-version: 2023-06-01. Body: { "model": "anthropic-model-id", "max_tokens": 1024, "messages": [{ "role": "user", "content": "Привет" }], "stream": true }

Успешный ответ

{ "id": "msg_…", "type": "message", "role": "assistant", "content": [{ "type": "text", "text": "…" }], "stop_reason": "end_turn", "usage": { "input_tokens": 1, "output_tokens": 1 } } | Anthropic SSE

Только активные модели ANTHROPIC. Поддерживаются system, text/tool_use/tool_result blocks и конечный SSE для Claude Code; image/document/cache/thinking блоки вернут 400. Ключ проходит те же проверки доступа, credits и budget.

POST/v1/responsesOpenAI Responses для CodexТребуется авторизация

Доступ: Bearer API key

Запрос

JSON запросаПоказать

{
  "model": "model-id",
  "instructions": "…",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Привет"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "function",
      "name": "read_file",
      "parameters": {}
    }
  ],
  "stream": true
}

Успешный ответ

{ "id": "resp_…", "object": "response", "status": "completed", "output": [{ "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "…" }] }], "usage": { "input_tokens": 1, "output_tokens": 1, "total_tokens": 2 } } | response.* SSE

Stateless transport для Codex: поддержаны message, function_call и function_call_output, function tools и завершающий SSE после settlement. previous_response_id, hosted tools, изображения и файлы вернут безопасный 400.

Вход и сессия

После входа сервер создаёт две непрозрачные HttpOnly cookie: активная сессия живёт 5 минут и продлевается при работе в кабинете, а refresh token действует 30 дней. Если активная сессия истекла, действующий refresh token бесшовно создаёт новую без обращения к провайдеру. Браузер не получает OAuth-токены.

POST/v1/auth/telegram/webappВход из Telegram Mini AppПубличный

Доступ: Публичный

Запрос

JSON запросаПоказать

{
  "initData": "raw Telegram initData"
}

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Проверяются raw initData, HMAC и свежесть auth_date.

GET/v1/auth/telegram/loginНачать вход TelegramПубличный

Доступ: Публичный

Нет.

302 Redirect к Telegram.

GET/v1/auth/vk/loginНачать вход VK IDПубличный

Доступ: Публичный

Нет.

302 Redirect к VK ID.

GET/v1/auth/yandex/loginНачать вход Яндекс IDПубличный

Доступ: Публичный

Нет.

302 Redirect к Яндекс ID.

GET/v1/auth/sber/loginНачать вход Сбер IDПубличный

Доступ: Публичный

Нет.

302 Redirect к Сбер ID.

Production требует mTLS и проверки ID-токена.

GET/v1/auth/identitiesСписок своих способов входаТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

[
  {
    "provider": "TELEGRAM|VK|YANDEX|SBER",
    "createdAt": "ISO-8601"
  }
]

Внешний subject не возвращается. См. правила привязки ниже.

GET/v1/auth/account-mergeПредпросмотр объединения аккаунтовТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

{
  "provider": "VK",
  "expiresAt": "ISO-8601",
  "source": {
    "loginProviders": [
      "VK"
    ],
    "paymentCount": 1,
    "subscriptionCount": 0,
    "apiKeyCount": 1,
    "usageCount": 0,
    "prepaidCreditBalance": 0
  },
  "conflicts": []
}

Доступен только после проверки второго аккаунта у провайдера. Не раскрывает внешний subject и секреты.

POST/v1/auth/account-merge/confirmПодтвердить объединениеТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Текущий аккаунт остаётся основным. При конфликте перенос целиком отменяется. Сессии и ключи второго аккаунта отзываются с сохранением истории.

POST/v1/auth/account-merge/cancelОтменить объединениеТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Удаляет предложение без изменения аккаунтов.

POST/v1/auth/telegram/linkПривязать TelegramТребуется авторизация

Доступ: Сессия

Запрос

Пустая форма из настроек.

Успешный ответ

302 Redirect к Telegram.

Привязка связана с текущей server-side сессией. После callback новая сессия не выдаётся.

POST/v1/auth/vk/linkПривязать VK IDТребуется авторизация

Доступ: Сессия

Запрос

Пустая форма из настроек.

Успешный ответ

302 Redirect к VK ID.

См. единое правило в методе привязки Telegram.

POST/v1/auth/yandex/linkПривязать Яндекс IDТребуется авторизация

Доступ: Сессия

Запрос

Пустая форма из настроек.

Успешный ответ

302 Redirect к Яндекс ID.

См. единое правило в методе привязки Telegram.

POST/v1/auth/sber/linkПривязать Сбер IDТребуется авторизация

Доступ: Сессия

Запрос

Пустая форма из настроек.

Успешный ответ

302 Redirect к Сбер ID.

См. единое правило в методе привязки Telegram.

GET/v1/auth/telegram/callbackCallback TelegramПубличный

Доступ: Публичный

Запрос

Query: state, code.

Успешный ответ

302 на WEB_ORIGIN, пара HttpOnly cookie: active session и refresh.

GET/v1/auth/vk/callbackCallback VK IDПубличный

Доступ: Публичный

Запрос

Query: state, code, device_id (необязательно).

Успешный ответ

302 на WEB_ORIGIN, пара HttpOnly cookie: active session и refresh.

GET/v1/auth/yandex/callbackCallback Яндекс IDПубличный

Доступ: Публичный

Запрос

Query: state, code.

Успешный ответ

302 на WEB_ORIGIN, пара HttpOnly cookie: active session и refresh.

GET/v1/auth/sber/callbackCallback Сбер IDПубличный

Доступ: Публичный

Запрос

Query: state, code.

Успешный ответ

302 на WEB_ORIGIN, пара HttpOnly cookie: active session и refresh.

GET/v1/auth/telegram/mock/authorizeЗавершить Telegram login локальноПубличный

Доступ: ПубличныйТолько локальный mock

Запрос

Query: state.

Успешный ответ

302 на callback.

GET/v1/auth/vk/mock/authorizeЗавершить VK login локальноПубличный

Доступ: ПубличныйТолько локальный mock

Запрос

Query: state.

Успешный ответ

302 на callback.

GET/v1/auth/yandex/mock/authorizeЗавершить Яндекс login локальноПубличный

Доступ: ПубличныйТолько локальный mock

Запрос

Query: state.

Успешный ответ

302 на callback.

GET/v1/auth/sber/mock/authorizeЗавершить Сбер login локальноПубличный

Доступ: ПубличныйТолько локальный mock

Запрос

Query: state.

Успешный ответ

302 на callback.

POST/v1/auth/logoutВыйтиТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Отзывает активную сессию и связанный refresh token только на текущем устройстве, затем очищает обе cookie.

Личный кабинет, тарифы и платежи

Доступ выдаётся только после серверного подтверждения оплаты; подробнее в правилах подписки. Формат основных сущностей — в контрактах.

GET/v1/meТекущий пользовательТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

{ "id": "uuid", "displayName": "Имя" | null, "createdAt": "ISO-8601" }

GET/v1/catalog/plansПубличный каталог тарифовПубличный

Доступ: Публичный

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

[
  {
    "code": "provider-month",
    "name": "Provider",
    "priceMinor": 99000,
    "currency": "RUB",
    "accessType": "PROVIDER",
    "limitFiveHour": 0,
    "limitWeek": 0,
    "creditQuotaFiveHour": 100000,
    "creditQuotaWeek": 500000
  }
]

GET/v1/subscriptionСвои подпискиТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

[
  {
    "planCode": "provider-month",
    "planName": "Provider",
    "accessType": "PROVIDER",
    "status": "ACTIVE",
    "autoRenew": true,
    "startsAt": "ISO-8601",
    "endsAt": "ISO-8601"
  }
]

POST/v1/subscription/cancel-renewalОтключить автопродлениеТребуется авторизация

Доступ: Сессия

Запрос

JSON запросаПоказать

{
  "accessType": "PROVIDER"
}

Успешный ответ

Подписка или null.

Идемпотентно меняет только autoRenew=false для указанного типа доступа; оплаченный доступ остаётся до endsAt.

POST/v1/paymentsСоздать платёжТребуется авторизация

Доступ: Сессия

Запрос

Header: Idempotency-Key (16–128). Body: { "productCode": "provider-month" }

Успешный ответ

{ "id": "uuid", "productCode": "provider-month", "amountMinor": 99000, "currency": "RUB", "status": "PENDING", "checkoutUrl": "https://…" | null, "createdAt": "ISO-8601" }

Клиент перенаправляет пользователя на checkoutUrl. В local mock это /checkout/:paymentId, в Prodamus — подписанная платёжная форма. Возврат с формы никогда не выдаёт доступ: его подтверждает только подписанный webhook. Тот же ключ того же пользователя возвращает исходный платёж; второй активный тип подписки запрещён.

GET/v1/paymentsИстория своих платежейТребуется авторизация

Доступ: Сессия

Запрос

Query: limit 1–50 (20 по умолчанию), cursor до 128.

Успешный ответ

{ "items": [{ "id": "uuid", "productCode": "…", "amountMinor": 99000, "currency": "RUB", "status": "SUCCEEDED", "createdAt": "ISO-8601", "providerReference": "…" | null }], "nextCursor": "…" | null }

GET/v1/payments/:idДетали своего платежаТребуется авторизация

Доступ: Сессия

Запрос

Path: UUID платежа.

Успешный ответ

JSON ответаПоказать

{
  "id": "uuid",
  "productCode": "…",
  "amountMinor": 99000,
  "currency": "RUB",
  "status": "SUCCEEDED",
  "createdAt": "ISO-8601",
  "provider": "prodamus"
}

Чужой и отсутствующий платёж дают одинаковый 404. Ответ не содержит сырых данных Prodamus или ссылки на чек.

GET/v1/payments/mock/checkout/:idMock checkoutТребуется авторизация

Доступ: СессияТолько локальный mock

Запрос

Path: id платежа.

Успешный ответ

JSON ответаПоказать

{
  "status": "pending"
}

POST/v1/payments/:id/mock/confirmПодтвердить mock-платёжТребуется авторизация

Доступ: СессияТолько локальный mock

Запрос

Path: id платежа.

Успешный ответ

Подтверждённый платёж.

POST/v1/payments/:id/mock/failПометить mock-платёж неуспешнымТребуется авторизация

Доступ: СессияТолько локальный mock

Запрос

Path: id платежа.

Успешный ответ

Неуспешный платёж.

POST/v1/payments/prodamus/webhookWebhook ProdamusТребуется авторизация

Доступ: Только Prodamus

Запрос

JSON body от Prodamus; header Sign.

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Служебный endpoint: подпись HMAC-SHA256 и provider event ID проверяются до выдачи доступа. Пользовательский браузер не должен вызывать этот метод.

Provider API-ключи и Agent

API-ключ предназначен только для Provider API — он не заменяет браузерную сессию. У одного пользователя может быть любое число ключей; их usage и credits общие. Правила описаны в бизнес-логике.

GET/v1/access/keysСписок своих ключейТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

[
  {
    "id": "uuid",
    "label": "production",
    "creditBudget": 10,
    "tokenPrefix": "sc_abcd",
    "status": "ACTIVE",
    "createdAt": "ISO-8601",
    "revokedAt": null,
    "lastUsedAt": null
  }
]

GET/v1/access/credit-budgetПолучить доступный бюджет ключейТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

{
  "source": "PLAN",
  "limit": 500,
  "allocated": 100,
  "available": 400,
  "prepaidBalance": {
    "total": 1000,
    "spent": 30,
    "reserved": 20,
    "remaining": 950
  }
}

Все суммы — credits. spent — подтверждённый расход; reserved — удержания до ответа или сверки; remaining — доступный остаток. source: PLAN — недельная credit-квота Provider-тарифа; BALANCE — предоплаченный баланс; NONE — лимит пока нельзя назначить.

POST/v1/access/keysСоздать API-ключТребуется авторизация

Доступ: Сессия

Запрос

{ "label": "production", "creditBudget": 10 } | {}

Успешный ответ

JSON ответаПоказать

{
  "id": "uuid",
  "token": "sc_…",
  "label": "production",
  "creditBudget": 10,
  "…": "метаданные ключа"
}

label необязателен, 1–80 символов. creditBudget — необязательный недельный лимит в credits. Сырой ключ возвращается только здесь; Cache-Control: no-store.

POST/v1/access/keys/:id/revealПоказать API-ключТребуется авторизация

Доступ: Сессия

Запрос

Path: id UUID активного ключа.

Успешный ответ

JSON ответаПоказать

{
  "id": "uuid",
  "token": "sc_…",
  "…": "метаданные ключа"
}

Явное действие владельца; Cache-Control: no-store.

POST/v1/access/keys/:id/rotateПеревыпустить один API-ключТребуется авторизация

Доступ: Сессия

Запрос

Path: id UUID активного ключа.

Успешный ответ

JSON ответаПоказать

{
  "id": "uuid",
  "token": "sc_…",
  "…": "метаданные нового ключа"
}

Немедленно заменяет только указанный ключ. Остальные ключи и общий баланс не меняются; Cache-Control: no-store.

PUT/v1/access/keys/:id/budgetИзменить лимит API-ключаТребуется авторизация

Доступ: Сессия

Запрос

Path: id UUID. Body: { "creditBudget": 10 } | { "creditBudget": null }

Успешный ответ

JSON ответаПоказать

{
  "id": "uuid",
  "creditBudget": 10,
  "…": "метаданные ключа"
}

null снимает индивидуальный лимит. Все значения — credits; при токенном тарифе budget в credits назначается в пределах отдельного предоплаченного баланса.

PUT/v1/access/keys/:id/long-contextРазрешить длинный контекстТребуется авторизация

Доступ: Сессия

Запрос

Path: id UUID. Body: { "allowLongContext": true } или false

Успешный ответ

JSON ответаПоказать

{
  "id": "uuid",
  "allowLongContext": true,
  "…": "метаданные ключа"
}

Разрешение относится только к этому ключу. Короткие запросы остаются по обычной ставке; для некоторых моделей длинные дороже.

DELETE/v1/access/keys/:idУдалить один API-ключТребуется авторизация

Доступ: Сессия

Запрос

Path: id UUID активного ключа.

Успешный ответ

204 No Content

Немедленно прекращает доступ и убирает ключ из списка. История usage остаётся без сырого секрета. Повторное удаление возвращает API_TOKEN_NOT_FOUND.

GET/v1/access/agentСтатус AgentТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

null | { "state": "PROVISIONING" | "READY" | "STOPPED" }

В MVP Agent можно только наблюдать, не управлять им.

Администрирование

Администратор — это подтверждённый Telegram-пользователь, чей числовой Telegram ID находится в server-side списке. Он не получает сырой API-ключ пользователя. Rate cards меняют только будущие списания.

GET/v1/admin/accessПроверить admin-доступТребуется авторизация

Доступ: Сессия

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

{
  "isAdmin": true
}

GET/v1/admin/plansВсе тарифыТребуется авторизация

Доступ: Администратор

Запрос

Нет.

Успешный ответ

Массив Plan, включая isActive, createdAt, updatedAt.

POST/v1/admin/plansСоздать тарифТребуется авторизация

Доступ: Администратор

Запрос

JSON запросаПоказать

{
  "code": "provider-month",
  "name": "Provider",
  "priceMinor": 99000,
  "currency": "RUB",
  "accessType": "PROVIDER",
  "providerQuotaMode": "ROLLING_TOKENS",
  "limitWeek": 500000
}

Успешный ответ

Созданный тариф.

code: [a-z][a-z0-9-]{1,62}; цена — минимальные единицы. Provider поддерживает необязательные токенные лимиты за 5 часов, 7 дней или оплаченный период; пустые лимиты не отображаются. allowedModelIds ограничивает модели.

PATCH/v1/admin/plans/:codeИзменить тарифТребуется авторизация

Доступ: Администратор

Запрос

Path: code. Body: минимум одно поле: name, priceMinor, currency, providerQuotaMode, токенные лимиты, allowedModelIds, isActive.

Успешный ответ

Обновлённый тариф.

Код и тип доступа неизменяемы.

DELETE/v1/admin/plans/:codeПолностью удалить тарифТребуется авторизация

Доступ: Администратор

Запрос

Path: code.

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Каскадно удаляет локальные подписки, платежи и зависимые записи. Внешние операции требуют отдельного урегулирования; действие сохраняется в журнале.

GET/v1/admin/agent-retentionПолитика хранения AgentТребуется авторизация

Доступ: Администратор

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

{
  "days": 7
}

Только срок хранения остановленного сетапа; действующие Agent-подписки не меняются.

PATCH/v1/admin/agent-retentionИзменить срок хранения AgentТребуется авторизация

Доступ: Администратор

Запрос

{ "days": 1 } … { "days": 365 }

Успешный ответ

JSON ответаПоказать

{
  "days": 7
}

Новая политика применяется только к будущим дедлайнам и не сокращает уже обещенное хранение.

GET/v1/admin/usersНайти пользователейТребуется авторизация

Доступ: Администратор

Запрос

Query: page≥1; search≤120; blocked=ALL|ACTIVE|BLOCKED; subscription=ALL|WITH_SUBSCRIPTION|WITHOUT_SUBSCRIPTION; provider=TELEGRAM|VK|YANDEX|SBER; sort=LAST_ACTIVE_AT|REGISTERED_AT|DISPLAY_NAME; direction=ASC|DESC.

Успешный ответ

JSON ответаПоказать

{
  "items": [
    {
      "id": "uuid",
      "displayName": "…",
      "registeredAt": "ISO-8601",
      "lastActiveAt": "ISO-8601",
      "blockedAt": null,
      "loginProviders": [
        "TELEGRAM"
      ],
      "hasSubscription": true
    }
  ],
  "page": 1,
  "pageSize": 10,
  "total": 1
}

GET/v1/admin/users/:idКарточка пользователяТребуется авторизация

Доступ: Администратор

Запрос

Path: id UUID.

Успешный ответ

Пользователь из списка плюс subscriptions, payments, credentials, agents, recentLogins (до 20) и recentUsage (до 20). История содержит только безопасные metadata.

POST/v1/admin/users/:id/blockЗаблокировать пользователяТребуется авторизация

Доступ: Администратор

Запрос

Path: id UUID.

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Активные сессии отзываются, Provider API блокируется немедленно.

POST/v1/admin/users/:id/unblockРазблокировать пользователяТребуется авторизация

Доступ: Администратор

Запрос

Path: id UUID.

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

DELETE/v1/admin/users/:idПолностью удалить учётную записьТребуется авторизация

Доступ: Администратор

Запрос

Path: id UUID.

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Каскадно удаляет локальные подписки, платежи, ключи, расход и агента. Автор и сводка удаления сохраняются в журнале.

GET/v1/admin/audit-logЖурнал действийТребуется авторизация

Доступ: Администратор

Запрос

Query: page≥1; search≤120; actor=ALL|ADMIN|USER|SYSTEM; category=ALL|MONEY|CHANGES; action; from/to=YYYY-MM-DD.

Успешный ответ

Страница записей с автором, действием, объектом, временем и безопасными деталями.

POST/v1/admin/users/:id/subscriptionsВручную выдать подпискуТребуется авторизация

Доступ: Администратор

Запрос

planCode, endsAt (ISO UTC), reason=CORRECTION|SUPPORT|DUPLICATE

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Не создаёт платёж; автопродление выключено.

PATCH/v1/admin/users/:id/subscriptions/:subscriptionIdИзменить подпискуТребуется авторизация

Доступ: Администратор

Запрос

planCode и/или endsAt, reason

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Только действующую подписку. Тип доступа менять нельзя; отменённая или истёкшая подписка возвращает 409 INVALID_STATE.

POST/v1/admin/users/:id/subscriptions/:subscriptionId/cancelОтменить подпискуТребуется авторизация

Доступ: Администратор

Запрос

reason

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Останавливает локальный доступ без автоматического возврата.

DELETE/v1/admin/users/:id/subscriptions/:subscriptionIdУдалить подпискуТребуется авторизация

Доступ: Администратор

Запрос

reason

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Каскадно удаляет зависимые локальные записи, но не платёж.

GET/v1/admin/ai/modelsМодели и rate cardsТребуется авторизация

Доступ: Администратор

Запрос

Нет.

Успешный ответ

Массив AiModel с rateCards.

GET/v1/admin/ai/models/pricing-policyБазовая цена моделейТребуется авторизация

Доступ: Администратор

Запрос

Нет.

Успешный ответ

{ "baseCreditsPerMillion": null } или заданная десятичная строка.

POST/v1/admin/ai/models/pricing-policyИзменить базовую ценуТребуется авторизация

Доступ: Администратор

Запрос

JSON запросаПоказать

{
  "baseCreditsPerMillion": "35"
}

Успешный ответ

Новая цена и число обновлённых моделей.

Пример 35 не является значением по умолчанию. Новые версии ставок действуют для следующих запросов; история сохраняется.

POST/v1/admin/ai/modelsСоздать модельТребуется авторизация

Доступ: Администратор

Запрос

Body: { "publicId": "model-id", "provider": "OPENAI", "upstreamModelId": "remote/model", "displayName": "Модель" }.

Успешный ответ

201: локальная выключенная модель. 409: идентификатор уже занят.

Публичный ID: 2–128 символов a-z, 0-9, точка, дефис и подчёркивание, начинается с буквы. Для доступа добавьте действующую ставку и включите модель. Внешний каталог не меняет настройки.

POST/v1/admin/ai/models/configuration/previewПроверить файл моделей и весовТребуется авторизация

Доступ: Администратор

Запрос

JSON: schemaVersion=1, updatedAt ISO8601 с зоной, models[]. Каждый элемент: publicId, provider, upstreamModelId, displayName, weight (строка), protocols (chat_completions/responses/messages).

Успешный ответ

Новые/изменённые/отсутствующие модели, конфликты, contentHash и catalogRevision.

Новые модели выключены; ручное имя и доступность сохраняются. Messages только для Anthropic.

POST/v1/admin/ai/models/configuration/applyПрименить файл моделейТребуется авторизация

Доступ: Администратор

Запрос

JSON запросаПоказать

{
  "configuration": "тот же JSON-объект",
  "expectedRevision": "catalogRevision из preview"
}

Успешный ответ

{ applied, contentHash }; 409 — конфигурация изменилась, повторите просмотр.

Атомарное применение с аудитом. Повтор файла не перезаписывает последующие ручные изменения; исчезнувшие модели сохраняются.

POST/v1/admin/ai/models/:publicId/weightИзменить вес моделиТребуется авторизация

Доступ: Администратор

Запрос

JSON запросаПоказать

{
  "weight": "2.5"
}

Успешный ответ

Новая неизменяемая версия weighted-v2.

Сначала задайте базовую цену. До 6 десятичных знаков, положительный вес меньше 1000000. История и начатые запросы сохраняют прежнюю версию.

PATCH/v1/admin/ai/models/:publicIdИзменить модельТребуется авторизация

Доступ: Администратор

Запрос

Path: publicId. Body: { "displayName"?: "…", "isActive"?: true }, минимум одно поле.

Успешный ответ

Обновлённая модель.

Provider, publicId и upstream ID неизменяемы.

POST/v1/admin/ai/models/:publicId/rate-cardsДобавить rate cardТребуется авторизация

Доступ: Администратор

Запрос

JSON запросаПоказать

{
  "effectiveAt": "ISO-8601",
  "inputCreditsPerMillion": 1,
  "outputCreditsPerMillion": 1,
  "cacheReadCreditsPerMillion": 0,
  "reasoningCreditsPerMillion": 0
}

Успешный ответ

Созданная rate card.

Дата — сейчас или будущее; значения неотрицательны, одно — положительно. Редактирование запрещено.

POST/v1/admin/ai/models/:publicId/rate-cards/:id/disableОтключить rate cardТребуется авторизация

Доступ: Администратор

Запрос

Path: publicId, id UUID.

Успешный ответ

JSON ответаПоказать

{
  "success": true
}

Не меняет историю, влияет только на новые запросы.

Read-only MCP и OAuth 2.1

Публичный MCP доступен без авторизации и содержит search_docs и list_models. Аккаунтный MCP после OAuth 2.1 Authorization Code с PKCE или через один токен из кабинета открывает только свои list_models, get_account_limits и get_usage_summary. Оба варианта не выполняют LLM- или VLM-inference, платежи, админские действия или операции с API-ключами.

POST/v1/mcpПубличный MCP JSON-RPCПубличный

Доступ: Публичный

Запрос

JSON запросаПоказать

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_models",
    "arguments": {}
  }
}

Успешный ответ

JSON-RPC 2.0 через Streamable HTTP. initialize: protocolVersion 2025-06-18, simpleclaw-public. tools/list: search_docs(query 1–200), list_models. tools/call — только эти инструменты.

Для ChatGPT выберите Streamable HTTP и скопируйте URL из руководства «Подключение в ChatGPT»: он подставляется из текущего окружения. STDIO, команда запуска и API-ключ не нужны. Неизвестный метод/инструмент: -32601; неверные аргументы: -32602.

POST/v1/mcp/accountАккаунтный MCPТребуется авторизация

Доступ: OAuth или account token

Запрос

Тот же JSON-RPC. Header: Authorization: Bearer mcp_…

Успешный ответ

tools/list: list_models, get_account_limits, get_usage_summary. Только данные владельца токена.

OAuth требует scope account:read и корректную audience/resource. Account-токен создаётся в кабинете; на аккаунт может существовать только один.

GET/v1/mcp/tokenСтатус account MCP-токенаТребуется авторизация

Доступ: Сессия

Запрос

Без тела

Успешный ответ

Метаданные токена без raw-значения либо null.

Raw-значение никогда не возвращается этим endpoint-ом.

POST/v1/mcp/tokenСоздать account MCP-токенТребуется авторизация

Доступ: Сессия

Запрос

Без тела

Успешный ответ

Метаданные и raw token; значение показывается только один раз.

Если активный токен уже есть, возвращается MCP_TOKEN_EXISTS.

POST/v1/mcp/token/rotateПеревыпустить account MCP-токенТребуется авторизация

Доступ: Сессия

Запрос

Без тела

Успешный ответ

Новые метаданные и raw token.

Старый токен немедленно становится недействительным.

DELETE/v1/mcp/tokenОтозвать account MCP-токенТребуется авторизация

Доступ: Сессия

Запрос

Без тела

Успешный ответ

204 No Content.

Повторный отзыв возвращает MCP_TOKEN_NOT_FOUND.

GET/v1/mcp/oauth/authorizeПолучить OAuth codeТребуется авторизация

Доступ: Сессия

Запрос

Query: client_id, точный зарегистрированный HTTPS redirect_uri, response_type=code, code_challenge base64url 43–128, code_challenge_method=S256, scope=account:read, resource; state необязателен.

Успешный ответ

302 на redirect_uri?code=…&state=…

Code одноразовый, живёт 5 минут; resource совпадает с MCP_OAUTH_AUDIENCE.

POST/v1/mcp/oauth/tokenОбменять code на токенПубличный

Доступ: Публичный

Запрос

JSON запросаПоказать

{
  "grant_type": "authorization_code",
  "code": "…",
  "client_id": "…",
  "redirect_uri": "https://…",
  "code_verifier": "43–128 символов",
  "resource": "simpleclaw-mcp-account"
}

Успешный ответ

JSON ответаПоказать

{
  "access_token": "mcp_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "account:read",
  "resource": "simpleclaw-mcp-account"
}

Проверяются client, redirect_uri, code, audience и PKCE S256. Ошибки OAUTH_INVALID_REQUEST, OAUTH_INVALID_CLIENT, OAUTH_INVALID_GRANT.

Здоровье сервиса и документы

Для машинной интеграции используйте /docs/llms.txt, для интерактивной схемы — OpenAPI.

GET/health/liveLivenessПубличный

Доступ: Публичный

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

{
  "status": "ok"
}

GET/health/readyReadinessПубличный

Доступ: Публичный

Запрос

Нет.

Успешный ответ

JSON ответаПоказать

{
  "status": "ok",
  "timestamp": "ISO-8601",
  "checks": {
    "database": "ok"
  }
}

При недоступной базе — 503.

GET/v1/docsИнтерактивная OpenAPIПубличный

Доступ: Публичный

Запрос

Нет.

Успешный ответ

Swagger UI.

GET/docsЭта документацияПубличный

Доступ: Публичный

Запрос

Нет.

Успешный ответ

HTML-страница.

GET/docs/llms.txtКраткая версия для LLMПубличный

Доступ: Публичный

Запрос

Нет.

Успешный ответ

text/plain.