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

Публічний API

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

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

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

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

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

Для локального додатка (автоматично): Десктопний додаток Caiioo, розширення для браузера та мобільні додатки автентифікуються автоматично через наявний заголовок relay auth (x-relay-auth; заголовки HTTP нечутливі до регістру). Ручне налаштування не потрібне — додаток обробляє це за лаштунками. Запити з relay-auth ігнорують перемикач Enable Public API, оскільки вони вже є довіреними; перемикач обмежує лише запити з bearer-токеном.

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

Відкрийте Caiioo Налаштування > API Access
Увімкніть Enable Public API
Встановіть API access token (будь-який рядок на ваш вибір — ставтеся до нього як до пароля)
Використовуйте цей токен у всіх запитах до API

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

Ліміти запитів: кожен запит до /v1/* обмежений за IP клієнта — 100 GET-запитів на хвилину для читання та 30 запитів на запис на хвилину (POST / PATCH / DELETE) сумарно. Запити понад ліміт отримують 429. Доставка вебхуків (POST /v1/webhooks/:id) не потребує bearer-автентифікації та не підпадає під ці ліміти.

Профілі

Один пристрій може містити кілька профілів користувачів (наприклад, особистий + робочий). API дозволяє зовнішнім скриптам переглядати доступні профілі та перемикати активний перед виконанням іншої роботи. Створення, оновлення та видалення профілів навмисно не винесені в публічний API — ці процеси належать до інтерфейсу налаштування програми.

Список профілів:

GET /v1/profiles

Повертає { profiles: [...] } з одним записом для кожного невидаленого профілю. Кожен запис містить id, name, email, avatarUrl, tier, accessibleModes, license, organization, preferences, onboardingComplete, createdAt, lastAccessedAt. Поля з токенами (serviceCredentials, oauthConnections) та внутрішні дані синхронізації (vectorClock, lastModifiedBy) видалені. Використовуйте /v1/connectors для перегляду підключень OAuth.

Отримати активний профіль:

GET /v1/profiles/active

Повертає { profile } для профілю, який зараз використовується цим сервером. Усі ресурси /v1/*, прив'язані до профілю (гілки, вкладення, налаштування, навички), працюють з цим профілем.

Змінити активний профіль:

PUT /v1/profiles/active
Content-Type: application/json

{ "profileId": "user-uuid-from-list" }

Повертає { profile } для нового активного профілю. Повертає 404, якщо ID не відповідає жодному відомому профілю.

Провайдери та моделі

Дізнайтеся, які провайдери LLM налаштовані та які моделі доступні.

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

GET /v1/providers

Повертає всі підтримувані типи провайдерів. Наразі: anthropic, openai, google, openrouter, ollama, poe, mlx, perplexity, baseten, cloudflare. Кожен запис містить type, displayName, icon, requiresApiKey, hasApiKey та об'єкт capabilities із прапорцями, наведеними нижче.

Прапорець можливостей	Значення
`supportsVision`	Провайдер може приймати зображення на вхід
`supportsPdfFile`	Провайдер може приймати блоки вмісту файлів PDF нативно
`supportsToolCalling`	Провайдер підтримує виклик функцій/інструментів
`supportsStreaming`	Провайдер передає токени потоково (інкрементально)
`supportsExtendedThinking`	Провайдер надає бюджет для міркування/мислення
`supportsPromptCaching`	Провайдер підтримує директиви кешування промптів
`nativeReasoningBlocks`	Провайдер видає міркування як нативні блоки повідомлень (а не текст)
`requiresThoughtSignature`	Провайдер вимагає повернення підписаних токенів міркування

Прапорці можливостей дублюють поле readonly capabilities кожного класу провайдера (див. src/shared/providers/*-provider.ts) і перевіряються тестом на відповідність — викликайте цей ендпоінт під час виконання, а не використовуйте жорстко закодовану матрицю.

Примітки для BYOK провайдерів:

perplexity надає кураторський список моделей Sonar (Perplexity не має публічного ендпоінту /models).
cloudflare (AI Gateway) — це BYOK + мульти-вендор; список моделей визначається конфігурацією вашого шлюзу і повертається як порожній масив через /v1/providers/cloudflare/models. Використовуйте власний каталог шлюзу.

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

GET /v1/providers/openrouter/models

Повертає каталог моделей для цього провайдера. Кожна модель містить id, displayName та contextLength, де це можливо. Повертає 503, якщо у провайдера відсутній API ключ або його висхідний каталог недоступний.

Загальний каталог усіх провайдерів:

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.

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

Це основна подія — виклик агента для обробки повідомлення.

Тіло запиту — підтримувані поля

Поле	Обов'язково	Опис
`agentId`	так	ID вбудованого режиму (наприклад, `general`) або ID користувацького агента
`input.message`	так	Текст повідомлення користувача
`input.attachments`	ні	Масив ID вкладень (вже завантажених через `/v1/attachments`) для додавання до цього кроку
`input.variables`	ні	Перевизначення змінних для конкретного запуску, що об'єднуються з резолвером змінних агента
`input.tabContext`	ні	Рядок довільної форми, що вставляється як контекст сторінки (використовується браузерним мостом)
`input.messageId`	ні	ID повідомлення, наданий клієнтом — корисно для дедуплікації при повторних спробах
`threadId`	ні	Існуючий тред для продовження. Якщо пропущено, створюється та повертається новий тред
`mode`	ні	`"sync"` або `"async"`. За замовчуванням `"async"`

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

Очікування повної відповіді:

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

{
  "agentId": "general",
  "input": { "message": "What's the weather in Paris today?" },
  "mode": "sync"
}

Повертає 200 з { content, usage, status: "completed" } після завершення роботи агента. Якщо в роботі агента виникає помилка, повертає 500 з { error, status: "error" }. Синхронні запуски перериваються за таймаутом через 5 хвилин зі status: "error", якщо не отримано фінальної події — використовуйте async + SSE для завдань, що можуть тривати довше.

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

Запустити та забути — корисно для тривалих завдань:

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

{
  "agentId": "my-research-agent",
  "input": { "message": "Write a 2000-word analysis of renewable energy trends" },
  "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).

Після фінальної події сервер надсилає останній SSE-фрейм з event: terminal та порожнім корисним навантаженням як явний маркер кінця потоку, після чого закриває з'єднання. Клієнти повинні розглядати отримання цього фрейму (або закриття з'єднання) як сигнал до припинення читання.

Якщо ви підписуєтеся після того, як запуск уже завершився, сервер відтворює один фрейм типу RUN_SNAPSHOT, що містить повний фінальний запис record, після чого йде маркер event: terminal, а потім з'єднання закривається.

Скасування запуску:

POST /v1/runs/{runId}/cancel

Повертає { run: { ..., status: "cancelled" } }.

Threads

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

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

GET /v1/threads

Повертає { threads: [...] } для поточного профілю з видаленим масивом messages (використовуйте ендпоінт деталізації, коли вони вам потрібні). Усі інші поля зберігаються — id, title, createdAt, updatedAt, modeId, archived, статистика використання, а також subAgentHistories, anonymizerSnapshot, threadToolApprovals, threadVariables, threadToolOverrides, messagingBinding, scheduledTaskId, якщо вони встановлені. (Повний обсяг даних доступний виключно через API — трансляція бічної панелі через WebSocket використовує більш обмежений набір даних, щоб залишатися в межах лімітів передачі.)

Отримати 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 }. Новий thread негайно з'являється на бічній панелі (через WebSocket трансляцію). API ніколи не перемикає активний thread у додатку під час створення — викличте PUT /v1/threads/active окремо, якщо вам це потрібно.

Оновити 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 Сервери

Керуйте підключеннями до ваших 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"
}

Дозволені необов'язкові поля для POST: command, args, env, url, description, transportType, authType, authToken, authHeader, headers, specType, specPath, timeoutMs, credentialId, oauthConnectionId, approval. Поля, що керуються сервером (customOAuth, hubPackageId, profileId, connectorId, teamPublished, teamOrgId, vectorClock, ...), не можуть бути встановлені через API.

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

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

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

Поля, доступні для оновлення, відповідають білому списку POST (включаючи credentialId та oauthConnectionId — зручно для ротації OAuth підключення без видалення та повторного створення). Поля, що керуються сервером, залишаються лише для читання.

Увімкнути/вимкнути сервер:

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 інструментів.

Tools & Toolkits

Переглядайте та викликайте інструменти, які використовують агенти — веб-перегляд, пошук, календар, Gmail, Slate та інші.

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

GET /v1/toolkits

Повертає вбудовані інструменти, згруповані за категоріями (Productivity, Search, Utilities тощо), а також будь-які підключені MCP сервери як окремі набори інструментів, кожен з переліком доступних дій.

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

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

Отримати деталі інструменту зі схемою введення:

GET /v1/tools/calculator

Повертає { tool: { name, displayName, description, source, category, inputSchema, actions?, requiredTier?, requiredRuntimes?, riskTier?, riskExplanation?, requiresApproval? } }.

Поле	Значення
`inputSchema`	JSON Schema для вхідних даних інструменту — перевірте перед викликом
`actions`	Опціональні під-дії (наприклад, Slate `read`/`write`); кожна має `id`, `displayName`, `description`, опціональний `requiredTier`
`requiredTier`	Мінімальний рівень доступу користувача (`free`, якщо не вказано). Виклик через публічний API відхиляє все, що вище `free`
`requiredRuntimes`	Платформи, на яких доступний цей інструмент (`macos`, `ios` тощо); якщо пропущено ⇒ всюди
`riskTier`	Ризик згоди: `low` (за замовчуванням), `medium`, `high`
`riskExplanation`	Зрозуміле людині пояснення причини підвищеного `riskTier`
`requiresApproval`	`true`, якщо інструмент потребує підтвердження користувача для кожного виклику — публічний API відхиляє такі виклики

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

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

{ "input": { "expression": "sqrt(144) + 3^2" }, "threadId": "optional-thread-id" }

Повертає { result }. Вхідні дані перевіряються на відповідність схемі інструменту — невалідні дані повертають 422 з деталями. Передайте опціональний threadId, якщо інструменту потрібен контекст потоку (наприклад, пошук вкладень).

Обмеження — що відхиляє публічний API:

Інструменти з обмеженням за рівнем доступу (metadata.requiredTier !== 'free') → 403. Цикл агента перевіряє рівень доступу відповідно до сесії користувача; публічний API не має контексту рівня доступу, тому консервативна політика полягає у відмові. Замість цього використовуйте POST /v1/runs з агентом, який має відповідний рівень доступу.
Інструменти, що потребують підтвердження (metadata.approval.requiresApproval === true) → 403. У циклі немає людини, щоб запитати підтвердження. Викликайте через POST /v1/runs (що відобразить запит користувачеві) або встановіть режим підтвердження інструментів на approve_all у додатку для обходу.
Віддалені MCP інструменти → 501 з рекомендацією використовувати /v1/runs (вони потребують транспорту підпроцесу агента).

Інструменти Vision та інструменти для роботи з зображеннями: спочатку завантажте файл через POST /v1/attachments, потім передайте отриманий ID вкладення всередині input (наприклад, { "input": { "attachment_id": "att_abc", "prompt": "What is in this image?" } }). Інструмент зчитує бінарні дані зі сховища за допомогою threadId; ви не передаєте байти безпосередньо в запиті.

Конектори

Керуйте інтеграціями OAuth — Google, Microsoft, GitHub, Notion, Slack та іншими.

Перегляд доступних інтеграцій:

GET /v1/connectors/catalog

Повертає всіх зареєстрованих провайдерів OAuth з їхніми іменами, категоріями та стандартними областями доступу (scopes).

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

GET /v1/connectors

Повертає активні з'єднання для поточного профілю. Токени ніколи не розкриваються — лише метадані (провайдер, email, статус, області доступу, мітки часу).

Отримати одне з'єднання:

GET /v1/connectors/{id}

Повертає метадані для одного з'єднання. Токени ніколи не розкриваються.

Перевірити стан з'єднання:

POST /v1/connectors/{id}/test

Повертає { health: { status, isTokenExpired, canRefresh } }.

Видалити з'єднання:

DELETE /v1/connectors/{id}

Створення нових з'єднань вимагає інтерактивного процесу OAuth через інтерфейс додатка або маршрути /auth/*.

Тригери

Налаштовуйте агентів для автоматичного запуску — щоденні брифінги, щотижневі звіти, моніторинг через певні інтервали.

Кожен тригер має дискримінатор kind: schedule (за замовчуванням — спрацьовує за годинником), webhook (спрацьовує, коли зовнішній сервіс надсилає POST-запит на шлях вебхука) або messaging (спрацьовує від підключеного адаптера повідомлень — наприклад, вхідні повідомлення Slack/Discord, що відповідають фільтру каналу).

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

GET /v1/triggers

Повертає { triggers: [...] }. Кожен запис містить свій kind, розклад та поля, специфічні для типу (наприклад, webhookSecret/webhookPath для тригерів вебхуків, messagingAdapterId/messagingChannelFilter для тригерів повідомлень).

Отримати один тригер:

GET /v1/triggers/{id}

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

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}} у запиті тригера замінюється необробленим тілом запиту.

Тригери повідомлень

Тригери повідомлень спрацьовують, коли підключений адаптер повідомлень (наприклад, інтеграція Slack або Discord, встановлена через Community Hub) отримує вхідне повідомлення, що відповідає фільтру тригера. Створюйте з kind: "messaging":

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

{
  "name": "Відповідач на згадки",
  "prompt": "Корисно дай відповідь на: {{message.text}}",
  "modeId": "general",
  "kind": "messaging",
  "messagingAdapterId": "slack-team-acme",
  "messagingChannelFilter": "#support"
}

Адаптер відповідає за відправку відповідних подій у тригер; messagingChannelFilter залежить від конкретного адаптера.

Користувацькі функції

Створюйте власні інструменти, які можуть викликати агенти. Функції пишуться на 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}

Навички

Навички — це збережені запити, на які агенти можуть посилатися та швидко запускати з вікна нової розмови. Навички, встановлені з Hub (керовані через встановлення пакетів), сюди НЕ входять — відображаються та редагуються лише навички, створені користувачем.

Список навичок:

GET /v1/skills

Повертає { skills: [...] } навичок, створених користувачем для активного профілю. Видалені навички, навички з Hub та тіні синхронізації відфільтровані.

Отримати одну навичку:

GET /v1/skills/{id}

Створити навичку:

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

{
  "prompt": "Підсумуй сторінку у 3 пунктах.",
  "tags": ["utility", "summarize"],
  "isFavorite": true,
  "modes": ["general"],
  "displayName": "Швидкий підсумок",
  "description": "Стислий огляд активної сторінки у трьох пунктах"
}

Обов'язковим є лише поле prompt. modes (необов'язково) обмежує навичку конкретними ID агентів; пропустіть для всіх режимів. Повертає 201 з новою навичкою (включаючи призначені сервером id, createdAt, updatedAt).

Оновити навичку:

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

{ "prompt": "Оновлений запит", "isFavorite": false }

Поля для оновлення: prompt, tags, modes, displayName, description, isFavorite. Спроби оновити навичку з Hub повертають 404.

Видалити навичку:

DELETE /v1/skills/{id}

М'яке видалення. Повертає 204. Для навичок з Hub повертає 404 — замість цього видаліть вихідний пакет.

Робочі процеси (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`	Помилка валідації — вхідні дані не відповідають схемі інструменту
`429`	Обмеження частоти запитів — див. ліміти в розділі Автентифікація
`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.