Це машинний переклад оригінального документа англійською мовою. У разі будь-яких розбіжностей між цим перекладом та оригінальною англійською версією, пріоритет має версія англійською мовою. Читати оригінал англійською мовою

Публічний API

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

Base URL: http://localhost:3847/v1

Автентифікація: Два способи автентифікації, обидва обмежуються перемикачем API в налаштуваннях:

Для зовнішніх споживачів (скрипти, інтеграції, curl): Встановіть токен доступу до API у Налаштування > Доступ до API, а потім використовуйте його як Bearer токен:

curl -H "Authorization: Bearer YOUR_API_TOKEN" http://localhost:3847/v1/providers

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

Налаштування:

Відкрийте Caiioo Налаштування > Доступ до API
Увімкніть Enable Public API
Встановіть API access token (будь-який рядок на ваш вибір — ставтеся до нього як до пароля)
Використовуйте цей токен у всіх запитах до 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, і threads зберігаються між сесіями. 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 (tombstone для синхронізації). Повертає 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 до сервера та повертає результат. Корисно для налагодження або виклику методів, які не доступні через tools 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-схему інструмента для його вхідних параметрів, щоб ви могли провести валідацію перед викликом.

Викликати інструмент безпосередньо:

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 з їхніми іменами, категоріями та стандартними областями доступу (scopes).

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

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}

Робочі процеси (Workflows)

Організовуйте роботу кількох агентів у 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, що містить визначення агента, вимоги до інструментів (на основі увімкнених інструментів), вимоги до конекторів (які постачальники OAuth потрібні) та шаблони тригерів. Метадані синхронізації видаляються — пакет є чистим, автономним кресленням.

Імпортувати агента:

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.