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

---

Публичный API

Caiioo включает в себя REST API, который позволяет управлять всем программно: запускать агентов, управлять инструментами, планировать задачи и многое другое. API работает на том же локальном сервере, который обслуживает десктопное приложение и браузерный мост.

Базовый URL: http://localhost:3847/v1

Аутентификация: Существует два способа аутентификации, оба регулируются переключателем API в настройках:

Для внешних потребителей (скрипты, интеграции, curl): Установите токен доступа к API в разделе Настройки > Доступ к API, затем используйте его как Bearer-токен:

curl -H "Authorization: Bearer ВАШ_API_TOKEN" http://localhost:3847/v1/providers

Для локального приложения (автоматически): Десктопное приложение Caiioo, расширения для браузеров и мобильные приложения аутентифицируются автоматически через существующий заголовок авторизации реле (X-Relay-Auth). Ручная настройка не требуется — приложение обрабатывает это в фоновом режиме.

Настройка:

1. Откройте Caiioo Настройки > Доступ к API
2. Включите переключатель Включить публичный API
3. Установите Токен доступа к API (любая строка на ваш выбор — относитесь к ней как к паролю)
4. Используйте этот токен во всех запросах к API

API доступен на localhost и через приватное реле. Проверьте GET /v1/auth/info (авторизация не требуется) для получения текущего статуса и инструкций по настройке.

Провайдеры и модели

Узнайте, какие провайдеры LLM настроены и какие модели доступны.

Список провайдеров:

GET /v1/providers

Возвращает все настроенные типы провайдеров (Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten и другие по мере добавления) с флагами возможностей (supportsVision, supportsToolCalling, supportsStreaming и т. д.) и информацией о том, настроен ли API-ключ.

Список моделей провайдера:

GET /v1/providers/anthropic/models

Возвращает каталог моделей для этого провайдера. Каждая модель включает id, displayName и contextLength (если доступно).

Общий каталог по всем провайдерам:

GET /v1/models

Объединяет модели от всех настроенных провайдеров в один список. Провайдеры без API-ключей пропускаются и указываются в warnings.

Агенты

Агенты — это сердце caiioo. Каждый агент — это Режим, настроенная личность со своим системным промптом, инструментами и навыками.

Список всех агентов:

GET /v1/agents

Возвращает встроенных агентов (Shopping, Workplace, General) и созданных вами. Каждый помечен как source: \"builtin\" или source: \"custom\".

Создать агента:

POST /v1/agents
Content-Type: application/json

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"Research Agent\",
    \"description\": \"Ищет в сети и резюмирует находки\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"Вы — ассистент-исследователь. Всегда цитируйте источники.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

Возвращает 201. Векторные часы добавляются автоматически для синхронизации.

Обновить агента:

PATCH /v1/agents/my-research-agent
Content-Type: application/json

{ \"branding\": { \"name\": \"Research Agent\", \"description\": \"Обновленное описание\" } }

Объединяет изменения с существующим агентом. Встроенные агенты возвращают 403 — они только для чтения.

Удалить агента:

DELETE /v1/agents/my-research-agent

Мягкое удаление через tombstone (синхронизируется между устройствами). Возвращает 204.

Запуск агентов

Это основное действие — вызов агента для обработки сообщения.

Синхронный режим

Ожидание полного ответа:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "input": { "message": "Какая сегодня погода в Париже?" },
  "mode": "sync"
}

Возвращает 200 с { content, usage, status: "completed" } после завершения работы агента. Если агент выдает ошибку, возвращает 500 с { error, status: "error" }.

Асинхронный режим

Отправил и забыл — полезно для длительных задач:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "my-research-agent",
  "input": { "message": "Напиши анализ тенденций в возобновляемой энергетике на 2000 слов" },
  "mode": "async"
}

Немедленно возвращает 202 с { runId, threadId, status: "running" }.

Опрос статуса:

GET /v1/runs/{runId}

Возвращает { run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }. Статус принимает одно из значений: running, completed, error или cancelled.

Потоковая передача событий в реальном времени (SSE):

GET /v1/runs/{runId}/events

Возвращает text/event-stream с каждым событием агента по мере его возникновения: GENERATION_STARTED, STREAMING_CONTENT, вызовы инструментов, активность субагентов и конечное событие (GENERATION_COMPLETE, GENERATION_ERROR или GENERATION_CANCELLED). Поток завершается после конечного события.

Отмена запуска:

POST /v1/runs/{runId}/cancel

Возвращает { run: { ..., status: "cancelled" } }.

Threads

Threads — это диалоги. Каждый запуск агента происходит внутри thread, и они сохраняются между сессиями. API позволяет просматривать, читать, создавать и управлять threads программно.

Список всех threads (только метаданные):

GET /v1/threads

Возвращает threads для текущего профиля без сообщений для повышения производительности. Каждый thread включает id, title, createdAt, updatedAt, modeId, archived и статистику использования.

Получить thread с полным списком сообщений:

GET /v1/threads/{id}

Возвращает полный объект thread, включая массив messages — каждое сообщение пользователя, ответ ассистента, вызов инструмента и результат работы инструмента.

Получить только сообщения:

GET /v1/threads/{id}/messages

Возвращает только массив messages — это легче, чем полный объект thread, когда вам нужен только диалог.

Создать thread:

POST /v1/threads
Content-Type: application/json

{ "title": "Research project", "modeId": "general" }

Возвращает 201 с новым thread. По умолчанию API НЕ переключает активный thread в приложении — передайте "setActive": true в теле запроса, если это необходимо. Новый thread немедленно появится в боковой панели (через WebSocket трансляцию).

Обновить thread:

PATCH /v1/threads/{id}
Content-Type: application/json

{ "title": "Renamed project", "archived": true }

Поля, доступные для обновления: title, modeId, archived, lastUsedModel. Изменения транслируются в боковую панель в режиме реального времени.

Удалить thread:

DELETE /v1/threads/{id}

Выполняет мягкое удаление thread (пометка для синхронизации). Возвращает 204. Удаленные threads перемещаются в корзину и могут быть восстановлены до тех пор, пока корзина не будет очищена.

Активный thread:

GET /v1/threads/active            # Возвращает { threadId }
PUT /v1/threads/active            # Тело: { "threadId": "..." }

Управление корзиной:

GET /v1/threads/trash/count       # Возвращает { count }
POST /v1/threads/trash/empty      # Возвращает { deletedCount, protectedCount }

Защищенные threads (сохраненные с помощью переключателя хранения данных) исключаются при очистке корзины.

Продолжение диалога через API: Чтобы отправить последующее сообщение в существующий thread, используйте POST /v1/runs с ID этого thread:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

Агент видит всю историю переписки из данного thread.

Вложения

Вложения — это файлы, связанные с тредами: скриншоты, PDF, документы, загруженные изображения, сгенерированные артефакты. API позволяет просматривать, загружать, скачивать и управлять ими.

Список всех вложений (только метаданные):

GET /v1/attachments

Возвращает метаданные вложений для текущего профиля. Тяжелые поля (dataUrl, extractedContent, extractedImages) удалены — используйте эндпоинты деталей или контента для их получения.

Список вложений для конкретного треда:

GET /v1/threads/{threadId}/attachments

Получение метаданных вложения:

GET /v1/attachments/{id}

Возвращает полные метаданные, включая extractedContent (текст OCR, распарсенный markdown), contentType, fileName, size и флаг hasContent. Необработанный бинарный файл НЕ включен — используйте эндпоинт /content для этого.

Скачивание бинарного файла вложения:

GET /v1/attachments/{id}/content

Возвращает необработанный файл с правильными заголовками Content-Type и Content-Disposition. Перенаправьте это в файл:

curl -o output.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

Загрузка вложения:

POST /v1/attachments
Content-Type: application/json

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "report.pdf",
  "description": "Квартальный отчет",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl — это URL-адрес данных в кодировке base64. Возвращает 201 с ID нового вложения. Вложение привязывается к указанному треду.

Обновление метаданных вложения:

PATCH /v1/attachments/{id}
Content-Type: application/json

{ "description": "Обновленное описание", "fileName": "new-name.pdf" }

Удаление вложения:

DELETE /v1/attachments/{id}

Мягкое удаление через tombstone. Возвращает 204.

MCP Servers

Управляйте подключениями к вашим серверам MCP (Model Context Protocol) — серверам, которые предоставляют агентам доступ к внешним инструментам и источникам данных.

Список настроенных серверов:

GET /v1/mcp-servers

Возвращает все конфигурации MCP серверов для текущего профиля. Конфиденциальные поля (authToken, env, credentialId) удаляются из ответа.

Получить конфигурацию сервера:

GET /v1/mcp-servers/{id}

Добавить новый MCP сервер:

POST /v1/mcp-servers
Content-Type: application/json

{
  "id": "my-server",
  "name": "My MCP Server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
  "serverType": "local"
}

Для удаленных HTTP-серверов используйте "url" вместо "command":

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

Обновить сервер:

PATCH /v1/mcp-servers/{id}
Content-Type: application/json

{ "name": "Renamed Server", "args": ["-y", "@mcp/server-v2"] }

Включить/выключить сервер:

POST /v1/mcp-servers/{id}/toggle
Content-Type: application/json

{ "enabled": false }

Удалить сервер:

DELETE /v1/mcp-servers/{id}

Управление процессами

Для локальных (stdio) MCP серверов вы можете управлять процессом сервера напрямую.

Список запущенных процессов:

GET /v1/mcp-servers/processes

Возвращает запущенные процессы серверов с указанием pid, startedAt и статуса running.

Запустить сервер:

POST /v1/mcp-servers/{id}/start

Считывает command/args/env из конфигурации сервера и порождает процесс. Возвращает статус процесса.

Остановить сервер:

POST /v1/mcp-servers/{id}/stop

Корректно завершает процесс сервера (SIGTERM с переходом к SIGKILL при необходимости).

Вызвать метод JSON-RPC напрямую:

POST /v1/mcp-servers/{id}/call
Content-Type: application/json

{ "method": "tools/list", "params": {} }

Отправляет необработанный запрос JSON-RPC 2.0 на сервер и возвращает результат. Полезно для отладки или вызова методов, не представленных через API инструментов.

Инструменты и наборы инструментов

Просматривайте и вызывайте инструменты, которые используют агенты: просмотр веб-страниц, поиск, календарь, Gmail, Slate и другие.

Список наборов инструментов (сгруппированный):

GET /v1/toolkits

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

Список всех инструментов (плоский):

GET /v1/tools
GET /v1/tools?source=embedded   # Только встроенные инструменты
GET /v1/tools?source=mcp        # Только инструменты серверов MCP

Получение сведений об инструменте со схемой ввода:

GET /v1/tools/calculator

Возвращает JSON Schema инструмента для его входных параметров, чтобы вы могли провести валидацию перед вызовом.

Прямой вызов инструмента:

POST /v1/tools/calculator/invoke
Content-Type: application/json

{ "input": { "expression": "sqrt(144) + 3^2" } }

Возвращает { result }. Ввод проверяется на соответствие схеме инструмента — неверный ввод возвращает 422 с подробностями. Удаленные инструменты MCP возвращают 501 с рекомендацией использовать /v1/runs (им требуется транспорт подпроцесса агента).

Коннекторы

Управляйте интеграциями OAuth — Google, Microsoft, GitHub, Notion, Slack и другими.

Просмотр доступных интеграций:

GET /v1/connectors/catalog

Возвращает всех зарегистрированных провайдеров OAuth с их именами, категориями и областями доступа по умолчанию.

Список ваших подключенных аккаунтов:

GET /v1/connectors

Возвращает активные подключения для текущего профиля. Токены никогда не раскрываются — только метаданные (провайдер, email, статус, области доступа, метки времени).

Проверка состояния подключения:

POST /v1/connectors/{id}/test

Возвращает { health: { status, isTokenExpired, canRefresh } }.

Удаление подключения:

DELETE /v1/connectors/{id}

Создание новых подключений требует интерактивного потока OAuth через интерфейс приложения или маршруты /auth/*.

Триггеры

Планируйте автоматический запуск агентов — ежедневные сводки, еженедельные отчеты, мониторинг на основе интервалов.

Список триггеров:

GET /v1/triggers

Создание запланированного триггера:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Утренняя сводка",
  "prompt": "Обобщи мои непрочитанные письма и сегодняшний календарь",
  "modeId": "general",
  "schedule": { "type": "daily", "time": "08:00" }
}

Поддерживаемые типы расписания:

• { "type": "interval", "minutes": 60 } — каждые N минут (мин. 15, макс. 1440)
• { "type": "daily", "time": "09:00" } — ежедневно в определенное время
• { "type": "weekly", "day": "mon", "time": "09:00" } — еженедельно
• { "type": "weekdays", "time": "08:30" } — с понедельника по пятницу
• { "type": "daysOfWeek", "days": ["mon", "wed", "fri"], "time": "10:00" } — конкретные дни
• { "type": "monthly", "dayOfMonth": 1, "time": "09:00" } — ежемесячно
• { "type": "manual" } — только при запуске через API

Ручной запуск триггера:

POST /v1/triggers/{id}/fire

Возвращает 202 с threadId для результирующего запуска.

Обновление или удаление:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

Вебхуки

Триггеры вебхуков позволяют внешним сервисам (CI/CD, мониторинг, конструкторы форм) инициировать запуск агента через HTTP.

Создание триггера вебхука:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Deploy hook",
  "prompt": "Произошел деплой: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

Возвращает 201 с webhookSecret и webhookPath. Сохраните секрет — он понадобится для подписи полезной нагрузки.

Отправка вебхука:

# Вычисление HMAC-SHA256 необработанного тела запроса
SIGNATURE=$(echo -n '{"repo":"my-app","branch":"main"}' | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

POST /v1/webhooks/{triggerId}
Content-Type: application/json
X-Webhook-Signature: $SIGNATURE

{"repo": "my-app", "branch": "main"}

Эндпоинт вебхука НЕ требует bearer-авторизации — вместо этого он использует проверку HMAC. Возвращает 202 с threadId отправленного запуска. Плейсхолдер {{webhook.body}} в промпте триггера заменяется необработанным телом запроса.

Пользовательские функции

Создавайте собственные инструменты, которые могут вызывать агенты. Функции пишутся на JavaScript или Python и выполняются в песочнице.

Список функций:

GET /v1/functions

Создание функции:

POST /v1/functions
Content-Type: application/json

{
  "name": "calculate_bmi",
  "description": "Рассчитать индекс массы тела по росту и весу",
  "language": "javascript",
  "source": "return { bmi: (input.weightKg / (input.heightM * input.heightM)).toFixed(1) };",
  "inputSchema": {
    "type": "object",
    "properties": {
      "weightKg": { "type": "number" },
      "heightM": { "type": "number" }
    },
    "required": ["weightKg", "heightM"]
  }
}

Функции JavaScript получают input и должны возвращать результат. Функции Python устанавливают переменную result:

# Пример на Python
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

Прямое выполнение функции:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

Безопасность: JavaScript выполняется в песочнице Node vm (без доступа к файловой системе или сети, таймаут 10с). Python выполняется как подпроцесс с таймаутом 30с. Оба варианта проверяют ввод перед выполнением.

Обновление или удаление:

PATCH /v1/functions/{id}
DELETE /v1/functions/{id}

Ворклоу (Рабочие процессы)

Организуйте работу нескольких агентов в виде DAG (направленного ациклического графа) — запускайте шаги параллельно, где это возможно, и передавайте выходные данные предыдущих шагов в последующие.

Валидация графа ворклоу:

POST /v1/workflows/validate
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Исследовать тенденции в возобновляемой энергетике" },
      { "id": "analyze", "agentId": "general", "prompt": "Изучить цены конкурентов" },
      { "id": "report", "agentId": "general", "prompt": "Написать отчет, объединяющий: {{outputs.research}} и {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

Возвращает { valid: true/false, errors: [...] }. Проверяет на наличие циклов, дублирующихся ID и отсутствующих ссылок на зависимости.

Выполнение ворклоу:

POST /v1/workflows/execute
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Исследовать тенденции в возобновляемой энергетике" },
      { "id": "summarize", "agentId": "general", "prompt": "Обобщить: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

Возвращает { status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }.

Независимые узлы (без общих зависимостей) запускаются параллельно. Плейсхолдер {{outputs.nodeId}} в промпте узла заменяется текстовым выводом указанного вышестоящего узла. Каждый узел — это полноценный запуск агента, поэтому он может использовать инструменты, просматривать веб-страницы и иметь доступ ко всем возможностям целевого агента.

Базы знаний

Организуйте документы в коллекции с возможностью поиска, на которые могут ссылаться агенты.

Список баз знаний:

GET /v1/knowledge/bases

Создание базы знаний:

POST /v1/knowledge/bases
Content-Type: application/json

{ "name": "Научные статьи" }

Возвращает 201 с ID новой базы.

Загрузка документа в базу знаний:

POST /v1/knowledge/bases/{id}/documents
Content-Type: application/json

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "Тенденции возобновляемой энергетики 2026"
}

Поле dataUrl представляет собой URL-адрес данных в кодировке base64. Возвращает 201 с метаданными документа.

Список документов в базе знаний:

GET /v1/knowledge/bases/{id}/documents

Поиск внутри базы знаний:

POST /v1/knowledge/bases/{id}/search
Content-Type: application/json

{ "query": "возобновляемая энергия" }

Возвращает подходящие документы на основе имени файла и описания. Семантический (векторный) поиск появится в будущем выпуске.

Удаление документа или базы знаний:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

Экспорт и импорт агентов

Делитесь агентами как переносимыми пакетами — между устройствами, командами или через Community Hub.

Экспорт агента:

POST /v1/agents/{id}/export

Возвращает JSON-пакет с определением агента, требованиями к инструментам, коннекторам и шаблонами триггеров. Метаданные синхронизации удаляются — пакет представляет собой чистый чертеж.

Импорт агента:

POST /v1/agents/import
Content-Type: application/json

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"Research Agent\", \"description\": \"От команды\" },
      \"defaultSettings\": { \"systemPrompt\": \"Вы исследуете вещи.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

Возвращает 201. Конфликты ID со встроенными или существующими агентами возвращают 409.

Обработка ошибок

API использует стандартные коды состояния HTTP:

Код	Значение
200	Успех
201	Создано
202	Принято (асинхронная операция запущена)
204	Удалено (нет содержимого)
400	Неверный запрос — проверьте поле error для подробностей
401	Не авторизован — отсутствует или неверный секрет сессии
403	Запрещено — например, попытка изменить встроенного агента
404	Не найдено
409	Конфликт — например, ID агента уже существует
422	Ошибка валидации — ввод не соответствует схеме инструмента
500	Ошибка сервера — проверьте поле error
501	Не реализовано — функция существует, но недоступна этим способом
503	Сервис недоступен — хранилище или провайдер не готовы

Все ответы с ошибками включают { "error": "человекочитаемое сообщение" }.

Пример быстрого старта

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

# 1. Создание пользовательского агента
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "quick-summarizer",
    "branding": { "name": "Quick Summarizer" },
    "defaultSettings": {
      "systemPrompt": "Кратко обобщи любой ввод в виде 3 пунктов.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. Асинхронный запуск
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "quick-summarizer", "input": { "message": "Обобщи https://en.wikipedia.org/wiki/Artificial_intelligence" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. Стриминг событий
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. Экспорт агента для совместного использования
curl -X POST http://localhost:3847/v1/agents/quick-summarizer/export \
  -H "Authorization: Bearer $API_TOKEN"

---

This guide is maintained by the Caiioo team using Slate, our built-in editor.