Публичный API

1. Аутентификация

2. Эндпоинты

2.1. Управление диалогами

POST /public/v1/conversations — создание диалога

Вызывается перед отправкой первого сообщения.

{
  "ui_language": "ru",               // "ru" | "en", по умолчанию "ru"
  "programming_language": "1c",      // "1c" | "java" | ..., по умолчанию "1c"
  "script_language": "ru",           // язык комментариев к коду, "ru" | "en"
  "title": null                      // опц.: название диалога, null — без названия
}

{
  "uuid": "3f2b...",
  "create_time": "2026-08-25T10:00:00Z"
}

GET /public/v1/conversations — список диалогов

Query-параметры: limit (1–100, по умолчанию 10), offset (≥0).

{
  "conversations": [
    {
      "uuid": "3f2b...",
      "skill_name": "public_api",
      "title": "Объяснение функции X",   // опц., null если не задано
      "create_time": "2026-08-25T10:00:00Z"
    }
  ]
}

GET /public/v1/conversations/{conversation_uuid} — информация о диалоге

Возвращает основные сообщения диалога (пользователь, ассистент, результаты инструментов — без служебных), отсортированные по времени, единым плоским списком без ветвления.

{
  "uuid": "3f2b...",
  "create_time": "2026-08-25T10:00:00Z",
  "skill_name": "public_api",
  "title": "Объяснение функции X",       // опц., null если не задано
  "details": {
    "ui_language": "ru",
    "script_language": "ru",
    "programming_language": "1c"
  },
  "messages": [ /* ConversationMessage, см. «Модели данных» */ ]
}

DELETE /public/v1/conversations/{conversation_uuid} — удаление

204 No Content.

2.2. Названия диалогов

POST /public/v1/conversations/{conversation_uuid}/title — генерация названия

Вызывается после генерации первого ответа ассистента. Сервер генерирует название по содержимому диалога. При первом вызове — генерация; последующие вызовы возвращают сохранённое название. Если информации недостаточно — 424 INSUFFICIENT_CONTEXT (повторить после новых сообщений).

Тело запроса пустое

{ "title": "Объяснение функции X" }

PUT /public/v1/conversations/{conversation_uuid}/title — изменение названия

Ручное изменение названия диалога клиентом.

{ "title": "Моё название" }

2.3. Компактизация контекста

Компактизация — механизм сжатия длинного контекста диалога. В публичном API работает в двух режимах:

• Авто-компактизация (серверная): запускается автоматически при приближении к max_context_length, без управления со стороны клиента.
• Управляемая компактизация: клиент явно инициирует сжатие через эндпоинт ниже.

POST /public/v1/conversations/{conversation_uuid}/compact — управляемая компактизация

Синхронно запускает компактизацию и ждёт завершения.

{
  "instruction": ""                  // опц., требования к сжатию на естественном языке
}

{
  "success": true,
  "result": {
    "status": "compact_finished"    // compact_finished | compact_limited
  }
}

2.4. Сообщения (стриминг)

POST /public/v1/conversations/{conversation_uuid}/messages — создание сообщения

Заголовки: Стандартные заголовки + Accept: text/event-stream.

{
  "parent_uuid": null,               // uuid сообщения-родителя; null для первого
  "role": "user",                    // "user" | "tool"
  "content": "Какая сегодня погода?",  // str для role=user; список ToolContent для role=tool
  "tools": [ /* ClientTool, опц. — только при role=user */ ],
  "no_generate": false               // опц.: сохранить сообщение без генерации ответа
}

{
  "uuid": "msg-2",
  "parent_uuid": "msg-1",            // null для промежуточных пакетов дельт
  "role": "assistant",               // null для пакетов дельт
  "content": { /* AssistantMessageContent, только в финальном пакете */ },
  "content_delta": { /* AssistantMessageContentDelta, в промежуточных */ },
  "finished": false
}

• content — строка для role: user и список ToolContent для role: tool.
• tools — список ClientTool (только для role: user).

Семантика стриминга

1. Первый пакет — эхо пользовательского сообщения: role/parent_uuid из запроса, content и content_delta = null, finished: true. Даёт клиенту uuid отправленного сообщения.
2. Для role: tool первые пакеты — подтверждения сохранённых tool-сообщений (по одному на tool_call_id).
3. Сообщения assistant приходят дельтами (finished: false, заполнен content_delta), завершаясь финальным пакетом (finished: true, заполнен content). Финальный content приоритетнее накопленных дельт — сервер мог отфильтровать/скорректировать текст.
4. Ответ может содержать несколько сообщений assistant (например, сообщение + вызов инструмента + следующее сообщение).

2.5. Контекст диалога

GET /public/v1/conversations/{conversation_uuid}/context_tokens

Query-параметры: branch (опционально; по умолчанию latest; если указать message_uuid, учитывается ветка диалога до этого сообщения).

{ "token_count": 1234, "max_context_length": 128000 }

Позволяет клиенту понимать заполненность контекста до отправки сообщения. При приближении к max_context_length срабатывает серверная авто-компактизация.

3. Модели данных

// UserContent (role: user) — упрощён до строки
// В запросе: content — str. tools — опц. список ClientTool.
"content": "Объясни, как работает эта функция"

// ClientTool — полное описание инструмента
{
  "name": "get_weather",
  "description": "...",
  "parameters": { /* JSON Schema */ }
}

// ToolContent (role: tool) — результат выполнения инструмента
{
  "content": "<result or comment>",  // опц.; null для accepted/rejected без комментария
  "structured_content": {...},       // опц.: структурированные данные для рендеринга
  "details": {...},                  // опц.: дополнительные детали для рендеринга
  "tool_call_id": "call_abc",
  "status": "ok"                     // ok | accepted | rejected | error | timeout | ignored
}

// AssistantMessageContent (финальный пакет assistant)
{
  "content": "Привет.",              // опц.
  "reasoning_content": null,         // опц., размышления LLM
  "tool_calls": [                    // опц., если LLM вызывает инструмент
    { "id": "call_abc", "function": { "name": "get_weather", "arguments": "{\"location\":\"...\"}" } }
  ]
}

// AssistantMessageContentDelta (промежуточные пакеты)
{
  "content": "При",                  // дельта текста
  "reasoning_content": null,
  "tool_calls": [ { "index": 0, "id": "call_abc", "function": { "name": null, "arguments": "{\"loc" } } ]
}

// ConversationMessage (в GET /conversations/{uuid})
{
  "uuid": "msg-2",
  "parent_uuid": "msg-1",
  "role": "assistant",
  "content": { /* AssistantMessageContent | str (user) | ToolContent */ },
  "create_time": "2026-08-25T10:00:01Z"
}

Правила статусов инструментов

• Клиентские инструменты: ok (с content), rejected (content опц. — комментарий), error (с content), timeout (с content), ignored (content = null).
• Серверные инструменты (MCP/system): accepted (content = null) или rejected (content опц.).
• arguments в tool_calls — строка JSON, может быть невалидной посередине стриминга; клиент собирает её накоплением.

4. Бюджет и лимиты

Расход приводится к обезличенным учётным единицам и ограничивается лимитами (скользящее 5-часовое окно и недельный лимит). Клиенту отдаётся только процент использования — абсолютные значения расхода и лимита не публикуются.

GET /public/v1/budget — текущее состояние лимитов

{
  "limits": {
    "sliding_5h": {
      "used_percent": 42.5,                 // % от 5-часового окна
      "resets_at": "2026-08-25T16:00:00Z"   // окончание текущего 5-часового окна
    },
    "weekly": {
      "used_percent": 18.0,
      "resets_at": "2026-08-27T16:00:00Z"   // окончание текущей недели
    }
  }
}

5. Модели ошибок

Единый формат ошибок:

{
  "error": "...",                   // описание/детали ошибки (строка или объект)
  "error_type": "validation"        // машинный код ошибки (snake_case)
}