API Reference

Base URL: https://partner.medassistai.ru

Формат данных: JSON (Content-Type: application/json)

Авторизация

В API используются две модели авторизации:

Дополнительно для auth-endpoint’ов (/v1/auth/*) требуется:

• Cookie csrftoken (получается через GET /v1/auth/csrf)
• Заголовок X-CSRFToken: <значение csrftoken>
• Заголовок Referer: https://partner.medassistai.ru/

Сводная таблица endpoint’ов

Auth: /v1/auth/*

Важно: auth URL’ы объявлены без trailing slash: /v1/auth/login, а не /v1/auth/login/.

GET /v1/auth/csrf

CSRF bootstrap — выставляет cookie csrftoken.

Авторизация: не требуется

Ответ: 204 No Content

POST /v1/auth/register

Регистрация пользователя. Выставляет refresh cookie (httpOnly), возвращает access token.

Авторизация: CSRF

Тело запроса:

{
  "email": "user@example.com",
  "password": "pass12345"
}

Ответ 201 Created:

{
  "access_token": "<jwt>",
  "access_expires_at": "2025-12-13T00:00:00Z"
}

Ошибки:

POST /v1/auth/login

Вход по email/password. Выставляет refresh cookie, возвращает access token.

Авторизация: CSRF

Тело запроса:

{
  "email": "user@example.com",
  "password": "pass12345"
}

Ответ 200 OK:

{
  "access_token": "<jwt>",
  "access_expires_at": "2025-12-13T00:00:00Z"
}

Ошибки:

POST /v1/auth/refresh

Обновление access token. Refresh token ротируется (выдаётся новый refresh cookie).

Авторизация: CSRF

Источник refresh token:

• Cookie refresh_token (предпочтительно)
• Или JSON body: {"refresh_token": "..."}

Ответ 200 OK:

{
  "access_token": "<jwt>",
  "access_expires_at": "2025-12-13T00:00:00Z"
}

Ошибки:

POST /v1/auth/logout

Отзыв refresh token и очистка cookie.

Авторизация: CSRF + refresh cookie

Ответ: 204 No Content

API Key: /v1/api-key/*

GET /v1/api-key/

Метаданные активного ключа (секрет не возвращается).

Авторизация: JWT

Ответ 200 OK (ключ есть):

{
  "api_key": {
    "key_id": "abc123",
    "prefix": "abc1",
    "revoked": false,
    "created_at": "2025-12-13T00:00:00Z"
  }
}

Ответ 200 OK (ключа нет):

{
  "api_key": null
}

POST /v1/api-key/rotate

Выпуск нового ключа (старый деактивируется). Полный ключ возвращается только один раз.

Авторизация: JWT

Ответ 200 OK:

{
  "api_key": {
    "key": "keyid.secret_part",
    "key_id": "keyid"
  }
}

Billing: /v1/billing/*

GET /v1/billing/balance

Текущий баланс кредитов.

Авторизация: JWT

Ответ 200 OK:

{
  "currency": "CREDITS",
  "balance_credits": "12.000000",
  "reserved_credits": "0.000000",
  "available_credits": "12.000000"
}

Поля:

• balance_credits — общий баланс (включая резерв)
• reserved_credits — зарезервировано под выполняющиеся запросы
• available_credits — доступно для новых запросов

GET /v1/billing/ledger

История операций по балансу (с пагинацией через курсор).

Авторизация: JWT

Query-параметры:

Ответ 200 OK:

{
  "items": [
    {
      "kind": "topup",
      "amount_credits": "100.000000",
      "created_at": "2025-12-12T00:00:00Z",
      "meta": {"reason": "manual_topup"}
    }
  ],
  "next_cursor": "2025-12-11T00:00:00Z|..."
}

Типы операций (kind): topup (пополнение), charge (списание), adjustment (корректировка).

Requests: /v1/requests

GET /v1/requests

История запросов (без текстов — только метаданные).

Авторизация: JWT

Query-параметры:

Ответ 200 OK:

{
  "items": [
    {
      "id": "uuid",
      "status": "succeeded",
      "operation": "text_process_short",
      "started_at": "2025-12-12T00:00:00Z",
      "model": "MedAssistModel1",
      "charged_credits": "1.000000",
      "has_text_payload": true
    }
  ],
  "next_cursor": null
}

GET /v1/requests/<request_id>

Polling-endpoint для получения результата обработки текста.

Авторизация: API Key

Ответ 202 Accepted (запрос ещё обрабатывается):

{
  "request_id": "uuid",
  "operation": "text_process_short",
  "status": "started"
}

Используйте заголовок Retry-After (если есть) как подсказку для интервала polling.

Ответ 200 OK (результат готов):

{
  "request_id": "uuid",
  "operation": "text_process_short",
  "output_text": "Результат обработки...",
  "billing": {"charged_credits": "1.000000"},
  "model": "MedAssistModel1"
}

Поле output_text возвращается в формате Markdown.

Text Processing: /v1/text/process/*

Обработка текста работает в режиме always-async:

1. POST /v1/text/process/{short|long} → 202 Accepted + request_id
2. GET /v1/requests/<request_id> → polling до 200 OK

POST /v1/text/process/short

Обработка текста в кратком стиле.

POST /v1/text/process/long

Обработка текста в развёрнутом стиле.

Авторизация: API Key + Idempotency-Key

Заголовки:

Тело запроса (строго фиксировано):

{
  "text": "Текст для обработки"
}

• Допускается только поле text (string, обязательное)
• Любые дополнительные поля будут отклонены с 400 invalid_request
• Максимальная длина: 100 000 символов
• Кодировка: UTF-8

Ответ 202 Accepted:

{
  "request_id": "uuid",
  "operation": "text_process_short",
  "status": "started",
  "poll_url": "/v1/requests/<request_id>"
}

Формат ошибок

Все ошибки возвращаются в едином формате:

{
  "error": {
    "code": "error_code",
    "message": "Описание ошибки"
  }
}

Коды ошибок

Про 429 на polling: endpoint GET /v1/requests/<request_id> имеет отдельный лимит на частоту опроса (по умолчанию 60 запросов/мин). Рекомендуемый интервал polling: 2 секунды.

Про 503 provider_error: сервис автоматически делает несколько попыток с экспоненциальной задержкой. Чтобы повторить обработку заново, отправьте новый запрос с новым Idempotency-Key.