OmniRoute/docs/i18n/uk-UA/docs/reference/API_REFERENCE.md

API Reference (Українська)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Мови: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Основний довідник з API OmniRoute. Він охоплює загальнодоступну поверхню /v1 і найчастіше використовувані кінцеві точки керування; машиночитаний файл docs/openapi.yaml і дерево маршрутів у src/app/api/ є вичерпними джерелами.

---

Зміст

• Доповнення чату
• Ексклюзивні оренди керованих сесій
• Вбудовування
• Генерування зображень
• OCR документів
• Список моделей
• Маніфест плагіна провайдера
• Кінцеві точки сумісності
• API файлів
• API пакетів
• API пошуку
• Потокове передавання через WebSocket
• Квоти та повідомлення про проблеми
• Семантичний кеш
• Панель керування та адміністрування
• Керування комбінаціями
• Вебхуки
• Зареєстровані ключі (автоматичне керування)
• Протокол агентів
• Проксі керування
• Відмовостійкість (розширено)
• Навички
• Пам’ять
• Сервер MCP
• Сервер A2A
• Хмара, оцінювання та перевірка
• Обробка запитів
• Автентифікація

---

Доповнення чату

POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Напиши функцію для..."}
  ],
  "stream": true
}

Спеціальні заголовки

Заголовок	Напрямок	Опис
X-OmniRoute-No-Cache	Запит	Установіть значення true, щоб оминути кеш
x-omniroute-no-memory	Запит	Установіть значення true, щоб пропустити додавання пам’яті та навичок для цього запиту (аналогічно до вимкнення кешу; дає змогу уникнути витрат токенів і коштів для кожного виклику)
X-OmniRoute-Progress	Запит	Установіть значення true, щоб отримувати події перебігу виконання
X-Session-Id	Запит	Ключ закріпленої сесії для зовнішньої прив’язки до сесії
x_session_id	Запит	Також приймається варіант із символами підкреслення (прямий HTTP-запит)
X-OmniRoute-Session-Id	Запит	Надана викликачем мітка сесії/розмови (також передається до пам’яті). За наявності зберігається без змін у call_logs.session_tag для обліку витрат за сесіями (#8249) — ніколи не генерується за відсутності
Idempotency-Key	Запит	Ключ дедуплікації (вікно 5 с)
X-Request-Id	Запит	Альтернативний ключ дедуплікації
X-OmniRoute-Cache	Відповідь	HIT або MISS (без потокового передавання)
X-OmniRoute-Idempotent	Відповідь	true, якщо виконано дедуплікацію
X-OmniRoute-Progress	Відповідь	enabled, якщо відстеження перебігу виконання ввімкнено
X-OmniRoute-Session-Id	Відповідь	Фактичний ідентифікатор сесії, використаний OmniRoute
X-OmniRoute-Request-Id	Відповідь	Ідентифікатор для кореляції запиту (якщо відомий)
X-OmniRoute-Version	Відповідь	Версія збірки OmniRoute (завжди наявна)
X-OmniRoute-Cost-Saved	Відповідь	Сума в доларах США, заощаджена завдяки кешу в разі HIT (лише для влучань у кеш)
X-OmniRoute-Decision	Відповідь	Трасування маршрутизації: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> — стратегія комбінації або single для запиту без комбінації) — завжди наявне у відповідях після завершення

Примітка щодо Nginx: якщо ви покладаєтеся на заголовки із символами підкреслення (наприклад, x_session_id), увімкніть underscores_in_headers on;.

Заголовки телеметрії витрат: успішні відповіді без потокового передавання також містять набір телеметрії витрат X-OmniRoute-* — X-OmniRoute-Response-Cost (у USD, фіксовані 10 десяткових знаків; 0.0000000000 для безкоштовних послуг або послуг без визначеної ціни), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit і X-OmniRoute-Fallback-Attempts (лише коли > 0), а також X-OmniRoute-Request-Id і X-OmniRoute-Version. Їх повертають завершення чату, /v1/responses, /v1/messages, а також кінцеві точки для медіаданих — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations і /v1/moderations (вартість завжди становить 0). Вартість медіаданих обчислюється окремо для кожної модальності (за зображення, секунду, символ або одиницю пошуку), якщо ціноутворення доступне; інакше вона становить 0 (відмова без блокування).

Семантика вартості в разі влучання в кеш: у разі ВЛУЧАННЯ в семантичний кеш (X-OmniRoute-Cache-Hit: true) запит до зовнішнього постачальника не виконується, тому значення X-OmniRoute-Response-Cost становить 0.0000000000 (додаткова вартість обслуговування влучання). Початкова/потенційна вартість указується окремо в X-OmniRoute-Cost-Saved. Системи обліку платежів мають підсумовувати X-OmniRoute-Response-Cost (влучання нічого не коштують); системи аналітики кешу можуть агрегувати X-OmniRoute-Cost-Saved.

Ексклюзивні оренди керованих сеансів

Ексклюзивна оренда керованих сеансів — це необов’язковий, незалежний від клієнта контракт маршрутизації: один активний власник утримує одне придатне підключення OmniRoute. Вона не орендує модель, не вимагає OAuth, не ідентифікує конкретного клієнта й не вимагає конкретного постачальника.

API-ключ, що використовується для автентифікації, повинен мати область дії lease:exclusive і явний непорожній список allowedConnections. Межа мутації бази даних забезпечує одночасне дотримання обох вимог під час створення ключа та часткових оновлень.

POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}

Успішні відповіді на отримання, поновлення та звільнення містять часові позначки, state і точне додатне значення generation, але ніколи не розкривають вибране підключення чи облікові дані. Для поновлення та звільнення значення generation передається в тілі JSON:

{ "action": "renew", "generation": 1 }

{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }

Власник активної оренди може явно запросити безпечні для конфіденційності відображувані метадані для свого поточного прив’язування:

{ "action": "status", "generation": 1 }

{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}

Ця необов’язкова дія перевірки стану обмежується непрозорим ідентифікатором власника, автентифікованим керованим API-ключем і точним активним значенням generation у межах однієї транзакції бази даних. displayName містить лише налаштоване ім’я підключення з видаленими пробілами на початку та в кінці; воно дорівнює null, якщо безпечного налаштованого імені не існує. OmniRoute ніколи не підставляє адресу електронної пошти або згенеровану ідентичність облікового запису. Значення постачальника є неконфіденційною відображуваною міткою й ніколи не є згенерованим ідентифікатором сумісного постачальника. Облікові дані, токени, файли cookie, необроблені ідентифікатори підключень або API-ключів, хеші власників, секрети відсікання та внутрішні дані маршрутизації не включаються.

Запити з неправильним ключем, неправильним власником, застарілим значенням generation, а також пошуки відсутніх, прострочених, звільнених і анульованих оренд повертають однакову помилку 409 LEASE_FENCE_STALE без метаданих підключення. Клієнт, який отримав відповідь про очікування доступної місткості, не має активного прив’язування для перевірки. Коли маршрутизація переводить активну оренду на інше підключення, те саме значення generation залишається чинним, а стан атомарно повертає нове прив’язування, але ніколи не старе. Поведінка наявних клієнтів не змінюється, оскільки відповіді на отримання, поновлення, звільнення та очікування зберігають свої попередні структури.

Цей серверний контракт не змінює стандартний /status OpenAI Codex. Наразі стандартний Codex повідомляє про свого постачальника моделі та вбудований стан автентифікації/облікового запису, але не відображає довільні користувацькі метадані облікового запису постачальника; майбутня клієнтська інтеграція повинна викликати цю дію та вирішувати, як відображати connection.displayName.

Після цього кожен керований запит на інференс передає обидва керівні заголовки:

X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1

Точний власник, значення generation, активне підключення та автентифікований API-ключ перевіряються механізмом відсікання безпосередньо перед кожною підтримуваною спробою звернення до висхідного сервісу. Повторне використання власника та generation з іншим ключем завершується невдало, навіть якщо цей ключ дозволяє те саме підключення. Необроблені значення власників не зберігаються, не записуються до журналів, не залишаються у знімку запиту й не пересилаються до висхідного сервісу.

Тимчасова конкуренція повертає HTTP 429 із Retry-After і:

{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}

Ця відповідь означає лише те, що звичайний набір придатних підключень був непорожнім, а кожен вільний кандидат утримувався сторонньою активною орендою. Непідтримувані моделі/постачальники, невідповідність політиці, період очікування, квота, стан працездатності та інші звичайні помилки придатності зберігають наявні відповіді OmniRoute.

x-omniroute-compression

Перевизначення плану стиснення для окремого запиту. Має найвищий пріоритет — переважає над перевизначенням комбінації маршрутизації, активним профілем, автоматичним запуском і значенням Default на панелі. Значення:

Значення	Ефект
off	Без стиснення для цього запиту.
default	Профіль Default, визначений панеллю (активний профіль ігнорується).
engine:<id>	Один рушій, якщо його ввімкнено, наприклад engine:rtk.
<combo>	Іменована комбінація: спочатку зіставляється за іменем без урахування регістру, а потім за id.

Примітки:

• Невідомі значення ігноруються (запит ніколи не відхиляється); визначення продовжується відповідно до звичайного порядку пріоритетів операторів.
• Якщо кілька комбінацій мають однакове ім’я, передайте id комбінації для детермінованого зіставлення.
• Комбінацію з іменем off або default не можна вибрати за іменем (ці ключові слова інтерпретуються першими); посилайтеся на таку комбінацію за її id.
• Головний перемикач стиснення є жорстким обмеженням: коли стиснення глобально вимкнено, цей заголовок не може його ввімкнути.

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

X-OmniRoute-Compression: <mode>; source=<source>

де <source> має одне зі значень: request-header, routing-override, active-profile, auto-trigger, default або off.

---

Векторні представлення

POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}

Доступні провайдери: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

Ідентифікатори каталогу мають формат provider/model (приклад: jina-ai/jina-embeddings-v5-omni-small). Прості ідентифікатори моделей Jina, наявні в реєстрі (наприклад, jina-embeddings-v5-text-small, jina-reranker-v3.5), також розпізнаються. Для операцій embed/rerank/classify/segment Jina спочатку використовуються облікові дані jina-ai з інформаційної панелі; JINA_AI_API_KEY використовується лише як резервний варіант, якщо ключ в інформаційній панелі відсутній. Картка jina-reader призначена лише для Reader / r.jina.ai (POST /v1/web/fetch) і ніколи не обслуговує векторні представлення чи переранжування.

Моделі реєстру, для яких заявлено мультимодальну підтримку, також приймають до 32 структурованих елементів у нейтральному до провайдера форматі. Типи медіаелементів: text, image, audio, video і document. Їхнє медіаджерело source має вигляд {"type":"url","url":"https://..."} або {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano і псевдонім сімейства jina-ai/jina-embeddings-v5-omni → omni-small) також приймає нативні документи EmbeddingsV5Request від Jina та пересилає їх без змін до https://api.jina.ai/v1/embeddings:

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}

Нативні значення { image | audio | video | pdf } можуть бути загальнодоступною URL-адресою HTTPS, URI data: або необробленими даними base64. OmniRoute не перетворює ці об’єкти на рядки й не завантажує нативні URL-адреси зображень — Jina самостійно отримує загальнодоступні медіадані. Додаткові поля Jina (task, normalized, truncate, embedding_type) пересилаються. Текстові SKU Jina, як і раніше, відхиляють нетекстові документи.

Обмеження безпеки й передавання:

• Віддалені URL-адреси медіаданих мають бути загальнодоступними та використовувати HTTPS. Канонічні елементи {type,source:url} завантажуються на боці сервера (з повторною перевіркою переспрямувань, обмеженням часу очікування й розміру, перевіркою загальнодоступності DNS і прив’язуванням з’єднання) та вбудовуються перед викликом провайдера. Нативні елементи Jina {image:"https://..."} пересилаються без змін після такої самої перевірки загальнодоступності HTTPS; Jina завантажує дані за URL-адресою.
• Вбудовані медіадані base64 обмежені 8 МіБ декодованих даних на елемент і 16 МіБ декодованих даних на весь запит.

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

• Мультимодальні моделі Jina: кожен елемент верхнього рівня стає одним об’єктом із ключем модальності (text / image / audio / video / pdf), для вбудованих медіаданих використовуються URI даних; один вектор на кожен елемент верхнього рівня.
• Сімейство Gemini Embedding 2: один масив верхнього рівня стає одним нативним запитом models/{model}:embedContent із content.parts (text або inline_data).
• Невідомі/динамічні моделі без явних метаданих модальності відхиляють структуровані вхідні дані з HTTP 400.

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

Непідтримувані комбінації моделі й модальності повертають HTTP 400 замість примусового перетворення елемента. Поля розширення, не пов’язані з вхідними даними, у застарілих запитах із рядками/токенами й надалі передаються без змін.

# Перелічити всі моделі векторних представлень
GET /v1/embeddings

---

Генерація зображень

POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "Гарний захід сонця над горами",
  "size": "1024x1024"
}

Доступні провайдери: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (локально), ComfyUI (локально).

# Перелік усіх моделей генерації зображень
GET /v1/images/generations

---

OCR документів

POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}

model вибирає провайдера OCR за допомогою префікса provider/model; ідентифікатор моделі без префікса (наприклад, mistral-ocr-latest) зіставляється із зареєстрованим для нього провайдером, а якщо model не вказано, за замовчуванням використовується Mistral (mistral-ocr-latest). Зареєстровані провайдери (open-sse/config/ocrRegistry.ts):

Ідентифікатор провайдера	Ідентифікатор моделі	Значення model	Примітки
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (або mistral-ocr-latest без префікса)	Синхронний — відповідь повертається безпосередньо з єдиного запиту до зовнішнього сервісу.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Асинхронний зовнішній сервіс (analyze + опитування) — див. нижче.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Синхронний, через партнерську кінцеву точку Vertex AI openapi/chat/completions — автентифікацію та URL описано нижче.

Усі три провайдери повертають відповідь в однаковому форматі Mistral:

{
  "pages": [{ "index": 0, "markdown": "# Витягнутий текст..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Процес опитування Azure Document Intelligence

API analyze Azure Document Intelligence є асинхронним: початковий запит повертає заголовок Operation-Location замість тіла відповіді, а результат необхідно отримувати шляхом опитування. Обробник (open-sse/handlers/ocr.ts) опитує цю URL-адресу щосекунди, виконуючи до 30 спроб, негайно завершується з помилкою (не продовжує опитування), якщо відповідь на опитування має статус, відмінний від ok, або статус "failed", і повертає 504, якщо операція все ще виконується після вичерпання ліміту спроб. Остаточна відповідь Azure нормалізується до того самого формату pages/markdown, який використовується Mistral, перш ніж її буде повернуто виклику, тому клієнтському коду не потрібно окремо обробляти цього провайдера.

Автентифікація та визначення кінцевої точки Vertex AI DeepSeek OCR

vertex-deepseek-ocr повторно використовує ту саму автентифікацію Vertex AI, яку OmniRoute уже підтримує для трафіку чату/зображень (open-sse/executors/vertex.ts): API-ключ підключення є або обліковими даними Service Account JSON (які обмінюються на короткостроковий токен доступу OAuth через процес JWT-bearer), або вже випущеним токеном доступу OAuth, який використовується без змін. Кінцева URL-адреса зовнішнього сервісу — це загальна партнерська кінцева точка Vertex openapi/chat/completions, сформована на основі проєкту та регіону підключення — явно вказані providerSpecificData.project/providerSpecificData.region завжди мають пріоритет; інакше проєкт визначається з project_id у Service Account JSON, а регіоном за замовчуванням є us-central1. Обидва значення визначаються в open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl) і використовуються в src/app/api/v1/ocr/route.ts перед передаванням до handleOcr.

---

Список моделей

GET /v1/models
Authorization: Bearer your-api-key

→ Повертає всі моделі чатів, вбудовувань і зображень, а також їхні комбінації у форматі OpenAI

Префікси ідентифікаторів моделей (?prefix=)

Більшість моделей представлено з префіксом постачальника. Вибір префікса контролюється функціональним прапорцем MODELS_CATALOG_PREFIX_MODE, але його можна перевизначити для кожного окремого запиту за допомогою параметра запиту — це корисно для клієнта, якому потрібен чистий список без зміни загальносерверного налаштування для всіх інших:

GET /v1/models?prefix=alias        # один ідентифікатор на модель — короткий префікс псевдоніма
GET /v1/models?prefix=dual         # обидві форми (типове налаштування сервера)
GET /v1/models?prefix=canonical    # лише повний префікс ідентифікатора постачальника

Режим	Виводить	Примітки
dual	cc/claude-sonnet-4-6 і claude/claude-sonnet-4-6	Типовий режим. Обидва ідентифікатори спрямовуються до тієї самої моделі; збережено, щоб конфігурації клієнтів із жорстко заданою будь-якою з форм продовжували працювати. Приблизно подвоює розмір каталогу.
alias	cc/claude-sonnet-4-6	Один запис на модель. Постачальники без окремого псевдоніма все одно виводять свій запис, тому нічого не втрачається.
canonical	claude/claude-sonnet-4-6	Один запис на модель із повним префіксом ідентифікатора постачальника. Постачальники без окремого псевдоніма (наприклад, antigravity/…, agy/…) також виводять тут свій єдиний ідентифікатор, тому нічого не втрачається.

Дзеркальний запис у режимі dual також можна розпізнати без параметра запиту: він містить поле parent, яке вказує на основний ідентифікатор.

Клієнти, які відображають засіб вибору моделі, мають запитувати ?prefix=alias — саме так робить розширення OmniCopilot для VS Code.

Варіанти моделей без міркування

Для моделей Claude із підтримкою міркування /v1/models також представляє варіант без міркування, ідентифікатор якого має префікс claude-3-omniroute-no-thinking/:

claude-3-omniroute-no-thinking/<provider>/<model>

Вибір цього ідентифікатора (наприклад, у конфігурації Claude Code, яка завжди додає блок thinking) призводить до повернення фактичної моделі <provider>/<model> із вимкненим міркуванням — thinking:{type:"disabled"} для маршруту /v1/messages або з вилученими полями reasoning/reasoning_effort для маршруту /v1/chat/completions. Цей варіант вказується лише для моделей сімейства Claude, які підтримують міркування та враховують значення disabled (тому, наприклад, моделі лише з адаптивним режимом, які відхиляють disabled, не включаються). Оператори можуть примусово ввімкнути або вимкнути цей варіант для кожної моделі за допомогою ModelSpec.noThinkingAlias.

---

Маніфест плагінів провайдерів

GET /api/v1/provider-plugin-manifest

Повертає JSON-сумісний маніфест плагінів провайдерів, який використовується Bifrost, CLIProxyAPI та майбутніми бічними маршрутизаторами. Відповідь генерується з реєстру провайдерів TypeScript і навмисно не містить секретів клієнтів OAuth, визначення середовища виконання, функцій-виконавців, заголовків запитів і даних облікових записів.

Використовуйте цю кінцеву точку, коли бічний процес працює поза основним процесом і не може безпосередньо імпортувати open-sse/config/providerPluginManifestRegistry.ts.

---

Кінцеві точки сумісності

Метод	Шлях	Формат
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	OpenAI Responses
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	OpenAI Images
POST	/v1/images/edits	OpenAI Images (редагування/домальовування)
POST	/v1/videos/generations	Генерування відео у стилі OpenAI
POST	/v1/music/generations	Генерування музики у стилі OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (повертає аудіовміст)
POST	/v1/rerank	Переранжування у стилі Cohere/Voyage
POST	/v1/classify	Класифікація Jina (api.jina.ai)
POST	/v1/segment	Сегментатор Jina (segment.jina.ai)
POST	/v1/moderations	OpenAI Moderations
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	Псевдонім каталогу OpenAI
GET	/api/v1/vscode/{token}/models	Псевдонім моделей OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Токенізований псевдонім OpenAI
POST	/api/v1/vscode/{token}/responses	Токенізований псевдонім OpenAI Responses
POST	/api/v1/vscode/{token}/api/chat	Токенізований псевдонім Ollama
GET	/api/v1/vscode/{token}/api/tags	Токенізований псевдонім тегів Ollama

Усі маршрути POST мають однакову структуру: Bearer your-api-key + перевірене за допомогою Zod тіло JSON (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema тощо; див. src/shared/validation/schemas.ts). У разі помилки перевірки схеми повертається 4xx.

Для клієнтів, які не можуть додати Authorization: Bearer ..., OmniRoute також приймає ключі API в URL через сумісні параметри рядка запиту (?token=..., ?apiKey=..., ?api_key=..., ?key=...) або спеціальні кінцеві точки /api/v1/vscode/{token}/..., описані нижче.

# Переранжування
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Класифікація Jina (облікові дані Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Сегментатор Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

# Пошук Jina (s.jina.ai; псевдоніми провайдера: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Модерація
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — повертає вміст audio/mpeg (або у запитаному форматі)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Редагування зображення (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Генерування відео / музики (ідентифікатор моделі з префіксом провайдера)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Спеціальні маршрути провайдерів

POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations

Префікс провайдера додається автоматично, якщо він відсутній. Для невідповідних моделей повертається 400.

---

Files API

Сумісна з OpenAI кінцева точка для файлів, призначена для пакетного введення/виведення та завантаження файлів із зазначенням призначення.

Метод	Шлях	Опис
POST	/v1/files	Завантажити файл (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — максимум 512 МіБ
GET	/v1/files	Перелічити файли для автентифікованого ключа API
GET	/v1/files/[id]	Отримати метадані файлу
DELETE	/v1/files/[id]	Видалити файл
GET	/v1/files/[id]/content	Передати необроблений вміст файлу у відповідь як потік

Автентифікація: ключ API типу Bearer — доступ до файлів обмежується окремо для кожного ключа API через getApiKeyRequestScope. Ключ бачить, завантажує та видаляє лише власні файли; сеанс панелі керування без ключа має доступ для читання в межах усього екземпляра; доступ до файлу без власника (анонімне завантаження або завантаження через сеанс панелі керування) заборонено всім викликачам без сеансу. GET /v1/files відхиляє анонімного викликача — а також наданий ключ, який не вдається розпізнати, — із кодом 401, навіть коли REQUIRE_API_KEY=false, замість виведення списку файлів усіх клієнтів (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches API

Сумісна з OpenAI пакетна обробка.

Метод	Шлях	Опис
POST	/v1/batches	Створити пакет — тіло перевіряється за допомогою v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Перелічити пакети
GET	/v1/batches/[id]	Отримати стан пакета та request_counts
DELETE	/v1/batches/[id]	Видалити завершений або невдалий пакет
POST	/v1/batches/[id]/cancel	Скасувати пакет, обробка якого триває

Автентифікація: ключ API типу Bearer. Доступ до пакетів обмежується окремо для кожного ключа API за тим самим тристороннім правилом, що й для файлів: лише власний ключ, доступ у межах усього екземпляра для сеансу панелі керування, а доступ до записів без власника заборонено всім викликачам без сеансу (отримання, видалення, скасування та перевірка input_file_id під час створення). GET /v1/batches відхиляє анонімного викликача з кодом 401, навіть коли REQUIRE_API_KEY=false.

---

API пошуку

Абстракція провайдерів вебпошуку (Tavily, Brave, Exa, Serper тощо).

Метод	Шлях	Опис
GET	/v1/search	Перелік налаштованих провайдерів пошуку та їхніх можливостей
POST	/v1/search	Виконання пошукового запиту — тіло перевіряється за допомогою v1SearchSchema, підтримує кешування/об’єднання
GET	/v1/search/analytics	Статистика влучень/затримки/кешу для кожного провайдера

Автентифікація: API-ключ Bearer (extractApiKey + isValidApiKey). Політика пошуку застосовується через enforceApiKeyPolicy.

---

API отримання вебвмісту

Видобування вмісту з URL через налаштованого провайдера отримання вебвмісту (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Метод	Шлях	Опис
POST	/v1/web/fetch	Отримання/скрейпінг URL — тіло перевіряється за допомогою v1WebFetchSchema

Автентифікація: API-ключ Bearer (extractApiKey + isValidApiKey). Політика застосовується через enforceApiKeyPolicy.

Резервний перехід з урахуванням квоти (#8297): якщо явний provider не вказано, пул (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) перебирається у фіксованому порядку пріоритетності (заповнення першого доступного) — налаштований провайдер з обмеженою частотою запитів пропускається замість негайного завершення запиту, а повторювана помилка вищого рівня або помилка квоти (HTTP 429 завжди; 402/403 для безкоштовних тарифів Firecrawl/Tavily/TinyFish із квотами — не для Jina Reader і ніколи для звичайного некоректного запиту 400) спричиняє перехід до наступного ще не випробуваного провайдера з налаштованими обліковими даними під час виконання запиту. Коли всі провайдери в пулі вичерпано, кінцева точка повертає єдиний 429 (із заголовком Retry-After) замість попереднього загального 400. Коли запитується явний provider, прихованого резервного переходу немає — обмеження частоти або помилка явно вказаного провайдера повертається як його власна помилка (429 у разі обмеження частоти, інакше — статус вищого рівня).

---

Потокове передавання через WebSocket

GET /v1/ws?handshake=1

Перевіряє рукостискання для оновлення з’єднання до WebSocket і повертає приклади повідомлень дротового протоколу (request, cancel). Фактичні кадри WS обробляються вбудованим сервером WS поза таблицею маршрутів Next.js.

Автентифікація: API-ключ Bearer під час рукостискання.

Responses API через WebSocket (лише codex)

# Той самий хост:порт, що й HTTP API (типово 20128); оновіть з’єднання:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (або: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Першим кадром ОБОВ’ЯЗКОВО має бути response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Проксі Responses-API-over-WebSocket під’єднано виключно до codex (серверна частина ChatGPT). Він прослуховує той самий порт, що й API/панель керування, за шляхами /v1/responses, /responses і /api/v1/responses. Після отримання першого кадру response.create він виконує автентифікацію та підготовку через внутрішній міст codex-responses-ws, вибирає OAuth-з’єднання codex і тунелює дані до wss://chatgpt.com/backend-api/codex/responses через транспорт wreq-js. Моделі, відмінні від codex, відхиляються (codex_ws_provider_required). Для маршрутизації зі спільною квотою використовуйте model: "qtSd/<group>/codex/<model>". Реалізовано у app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Автентифікація: API-ключ Bearer під час рукостискання. Вбудований HTTP-сервер (server-ws.mjs) має бути активною точкою входу (він є нею типово, якщо існує app/server-ws.mjs).

Ідентифікатор моделі: використовуйте простий ідентифікатор ChatGPT (без префікса codex/)

Codex CLI від OpenAI перевіряє назву моделі на боці клієнта, коли supports_websockets = true, і відхиляє ідентифікатори з префіксом провайдера, як-от codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Надсилайте простий ідентифікатор (наприклад, gpt-5.5). Міст OmniRoute працює лише з codex, тому перед тунелюванням до вищого рівня він повторно визначає простий ідентифікатор як модель codex (resolveCodexWsModelInfo) — навіть попри те, що простий gpt-5.5 за HTTP інакше маршрутизувався б до іншого провайдера.

Налаштування OpenAI Codex CLI

Спрямуйте Codex CLI до OmniRoute, додавши користувацького провайдера з підтримкою WebSocket до ~/.codex/config.toml (використовуйте окремий CODEX_HOME, щоб не змінювати наявну конфігурацію):

model = "gpt-5.5"                 # простий ідентифікатор — НЕ "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # без кінцевої скісної риски; URL-адреса WS формується автоматично (у виробничому середовищі використовуйте https/wss)
wire_api = "responses"                    # єдине підтримуване значення з лютого 2026 року
supports_websockets = true                # вмикає транспорт Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # містить API-ключ OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # API-ключ OmniRoute (будь-який ключ, якщо REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI оновлює base_url + /responses до WebSocket, а OmniRoute тунелює його до вибраного OAuth-з’єднання codex. Перевірено наскрізно на локальному сервері: ChatGPT повертає codex.rate_limits + response.created і потоково передає завершення.

---

Квоти та звітування про проблеми

Метод	Шлях	Опис
GET	/v1/quotas/check	Попередня перевірка квоти для provider + accountId перед видачею зареєстрованого ключа
POST	/v1/issues/report	Повідомлення GitHub про помилку квоти або видачі ключа (потрібні GITHUB_ISSUES_REPO + токен)

Автентифікація: API-ключ Bearer (isAuthenticated).

---

Самообслуговування щодо використання (/api/usage/om-usage)

Будь-який API-ключ може переглядати власне використання та квоти — автентифікація керування не потрібна. Це кінцева точка, яку клієнт (CLI, панель OmniCopilot) використовує, щоб показати власнику ключа його витрати.

# Текстовий формат (історичний контракт — звичайний текст для термінала)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Структурований формат — для використання інтерфейсом користувача
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Для ключа має бути ввімкнено allowUsageCommand (типово вимкнено — менеджер API-ключів на панелі перемикає цю опцію для кожного ключа). Без неї кінцева точка повертає 403.

?format=json повертає дискриміновану структуру, тому клієнт ніколи не зчитує поле даних із відповіді про відмову. У разі успіху:

{
  "allowed": true,
  // наявне лише тоді, коли для ключа ввімкнено індивідуальні ліміти використання (денні/тижневі в USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // знімок квоти вибраного провайдера або null, якщо в кеші ще нічого немає:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // знімки всіх підключень, щоб інтерфейс міг відображати кілька провайдерів поруч:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

У разі відмови (401 — неправильний ключ / 403 — доступ не дозволено) той самий маршрут повертає { "allowed": false, "error": { "message": "…" } } — наявне, але порожнє поле personal/provider (ключ дозволено, але даних ще не отримано) є іншим станом, ніж відмова, і лише формат JSON дає змогу їх розрізнити.

Автентифікація: власний API-ключ Bearer клієнта, перевірений за допомогою isValidApiKey — це не інтерфейс керування (/api/keys/…), який залишається захищеним через requireManagementAuth.

---

Семантичний кеш

# Отримати статистику кешу
GET /api/cache/stats

# Очистити всі кеші
DELETE /api/cache/stats

Приклад відповіді:

{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}

Вплив на затримку

У разі ВЛУЧАННЯ в семантичний кеш відповідь надається з кешу без виклику вищого сервісу, тому вказане значення X-OmniRoute-Response-Latency є близьким до нуля (незалежно від початкової затримки вищого сервісу). Клієнтам, чутливим до затримки (тестування продуктивності, моніторинг p50/p99), слід перевіряти заголовок відповіді X-OmniRoute-Cache-Latency:

Значення	Значення
synthetic	Відповідь надано з кешу; затримка не є реальним часом вищого сервісу
(відсутнє)	Відповідь отримано внаслідок реального виклику вищого сервісу

Обхід кешу для окремого ключа

API-ключі можуть відмовитися від читання семантичного кешу за допомогою cacheDefaultMode:

Значення	Поведінка
legacy	Звичайна поведінка кешу (типова)
bypass	Повністю пропускати пошук у кеші; завжди звертатися до вищого сервісу

Задається під час створення ключа (POST /api/keys) або оновлення (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Обхід для окремого запиту

Будь-який запит може обійти кеш незалежно від налаштувань ключа:

X-OmniRoute-No-Cache: true

---

Панель керування та адміністрування

Маршрути керування (/api/*, окрім загальнодоступних маршрутів автентифікації/входу) не авторизуються за допомогою звичайних API-ключів для інференсу. Сімейства облікових даних, області доступу та приклади curl: Автентифікація для керування.

Автентифікація

Кінцева точка	Метод	Опис
/api/auth/login	POST	Вхід
/api/auth/logout	POST	Вихід
/api/settings/require-login	GET/PUT	Увімкнення або вимкнення входу

Керування провайдерами

Кінцева точка	Метод	Опис
/api/providers	GET/POST	Перегляд списку / створення провайдерів
/api/providers/[id]	GET/PUT/DELETE	Керування провайдером
/api/providers/[id]/test	POST	Перевірка з’єднання з провайдером
/api/providers/[id]/models	GET	Перегляд списку моделей провайдера
/api/providers/validate	POST	Перевірка конфігурації провайдера
/api/providers/bulk	POST	Масове додавання API-ключів для ОДНОГО провайдера
/api/providers/import	POST	Імпорт неоднорідного СПИСКУ провайдерів з обробленого файлу CSV/JSON (#6836); результати часткових помилок для кожного рядка
/api/provider-nodes*	Різні	Керування вузлами провайдерів
/api/provider-models	GET/POST/PATCH/DELETE	Користувацькі моделі (додавання, оновлення, приховування/відображення, видалення)

Потоки OAuth

Кінцева точка	Метод	Опис, специфічний для провайдера
/api/oauth/[provider]/[action]	Різні	OAuth провайдера

Маршрутизація та конфігурація

Кінцева точка	Метод	Опис
/api/models/alias	GET/POST	Псевдоніми моделей
/api/models/catalog	GET	Усі моделі за провайдером і типом
/api/combos*	Різні	Керування комбінаціями
/api/keys*	Різні	Керування API-ключами
/api/pricing	GET	Ціноутворення моделей

Використання та аналітика

Кінцева точка	Метод	Опис
/api/usage/history	GET	Історія використання
/api/usage/logs	GET	Журнали використання
/api/usage/request-logs	GET	Журнали на рівні запитів
/api/usage/[connectionId]	GET	Використання для кожного з’єднання
/api/usage/token-limits	GET/POST/DELETE	Бюджети обмежень токенів для кожного ключа API
/api/usage/model-latency-stats	GET	Ковзна агрегована статистика затримки для кожного постачальника/моделі (avg/p50/p95/p99, частка успішних запитів); фільтри: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Зведення про стан кешу промптів на основі call_logs — співвідношення записів/читань, розподіл розміру записів p50/p90/p99, концентрація великих записів, розподіл за моделями та вердикт healthy/degraded/thrash/no-data; параметри запиту range (1h|24h|7d|30d, типово 24h) і необов’язковий model (#8827)

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

Кінцева точка	Метод	Опис
/api/settings	GET/PUT/PATCH	Загальні налаштування
/api/settings/proxy	GET/PUT	Конфігурація мережевого проксі
/api/settings/proxy/test	POST	Перевірка з’єднання через проксі
/api/settings/ip-filter	GET/PUT	Список дозволених/заблокованих IP-адрес
/api/settings/thinking-budget	GET/PUT	Режим перезапису запиту для обмірковування/міркування (наскрізний / автоматичне видалення / власний / адаптивний). Не залежить від стиснення. Див. THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Глобальний системний промпт
/api/settings/compression	GET/PUT	Глобальна конфігурація стиснення
/api/settings/purge-request-history	POST	Очищення рядків журналу запитів і локальних артефактів журналу викликів

Контекст і стиснення

Кінцева точка	Метод	Опис
/api/compression/preview	POST	Попередній перегляд стиснення off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Список доступних мовних пакетів Caveman
/api/compression/rules	GET	Список метаданих правил Caveman
/api/context/caveman/config	GET/PUT	Псевдонім налаштувань, специфічних для Caveman
/api/context/rtk/config	GET/PUT	Налаштування, специфічні для RTK, включно з користувацькими фільтрами та збереженням необробленого виводу
/api/context/rtk/filters	GET	Каталог фільтрів RTK і діагностика користувацьких фільтрів
/api/context/rtk/test	POST	Запуск попереднього перегляду/тесту RTK для текстового навантаження
/api/context/rtk/raw-output/[id]	GET	Читання збереженого редагованого необробленого виводу за ідентифікатором вказівника
/api/context/combos	GET/POST	Перегляд списку/створення комбінацій стиснення
/api/context/combos/[id]	GET/PUT/DELETE	Перегляд деталей/оновлення/видалення комбінації стиснення
/api/context/combos/[id]/assignments	GET/PUT	Призначення комбінацій стиснення комбінаціям маршрутизації
/api/context/analytics	GET	Псевдонім аналітики стиснення

Моніторинг

Кінцева точка	Метод	Опис
/api/sessions	GET	Відстеження активних сеансів
/api/rate-limits	GET	Обмеження частоти запитів для кожного облікового запису
/api/monitoring/health	GET	Перевірка працездатності + зведення щодо постачальників (catalogCount, configuredCount, activeCount, monitoredCount). Подання керування містить credentialHealth: скалярні значення кешу перевірок, failedConnections, коли failed>0, і staleDbNonOkCount (закріплений test_status SQLite, а не показник). Див. MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Статистика кешу / очищення
/api/modality-bridge/stats	GET	Значення attempts у пам’яті, успішні спроби/bridged, помилки, влучання в кеш, totalLatencyMs, latencySamples, обчислене за вибірками averageLatencyMs і час останнього використання (скидаються після перезапуску; автентифікація керування)
/api/modality-bridge/video/runtime	GET	Сувора перевірка довіреного loopback-з’єднання перед автентифікацією/перевіркою керування; очищені від конфіденційних даних відомості про доступність і версії FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extract	POST	Внутрішній автентифікований брокер байтів через довірене loopback-з’єднання; вхідні дані до 50 MiB, обмежена черга/вихідні дані до 32 MiB, 503 у разі вичерпання ресурсів, 499 у разі відключення, 504 у разі перевищення граничного часу; це не загальнодоступний API для завантаження файлів

Резервне копіювання та експорт/імпорт

Кінцева точка	Метод	Опис
/api/db-backups	GET	Перелічити доступні резервні копії
/api/db-backups	PUT	Створити резервну копію вручну
/api/db-backups	POST	Відновити з певної резервної копії
/api/db-backups/export	GET	Завантажити базу даних як файл .sqlite
/api/db-backups/import	POST	Завантажити файл .sqlite для заміни бази даних
/api/db-backups/exportAll	GET	Завантажити повну резервну копію як архів .tar.gz

Хмарна синхронізація

Кінцева точка	Метод	Опис
/api/sync/cloud	Різні	Операції хмарної синхронізації
/api/sync/initialize	POST	Ініціалізувати синхронізацію
/api/cloud/*	Різні	Керування хмарою

Тунелі

Кінцева точка	Метод	Опис
/api/tunnels/cloudflared	GET	Отримати стан встановлення та виконання Cloudflare Quick Tunnel для панелі керування
/api/tunnels/cloudflared	POST	Увімкнути або вимкнути Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Отримати стан виконання ngrok Tunnel для панелі керування
/api/tunnels/ngrok	POST	Увімкнути або вимкнути ngrok Tunnel (action=enable/disable)

Інструменти CLI

Кінцева точка	Метод	Опис
/api/cli-tools/claude-settings	GET	Стан Claude CLI
/api/cli-tools/codex-settings	GET	Стан Codex CLI
/api/cli-tools/droid-settings	GET	Стан Droid CLI
/api/cli-tools/openclaw-settings	GET	Стан OpenClaw CLI
/api/cli-tools/runtime/[toolId]	GET	Загальне середовище виконання CLI

Відповіді CLI містять: installed, runnable, command, commandPath, runtimeMode, reason.

Агенти ACP

Кінцева точка	Метод	Опис
/api/acp/agents	GET	Перелічити всіх виявлених агентів (вбудованих і власних) зі станом
/api/acp/agents	POST	Додати власного агента або оновити кеш виявлення
/api/acp/agents	DELETE	Видалити власного агента за параметром запиту id

Відповідь GET містить agents[] (id, name, binary, version, installed, protocol, isCustom) і summary (total, installed, notFound, builtIn, custom).

Відмовостійкість і обмеження частоти

Кінцева точка	Метод	Опис
/api/resilience	GET/PATCH	Отримати/оновити чергу запитів, затримку з'єднання, запобіжник провайдера та налаштування очікування
/api/resilience/reset	POST	Скинути автоматичні запобіжники провайдера
/api/resilience/model-cooldowns	GET	Перелічити активні блокування для кожного (провайдера, з'єднання, моделі), відсортовані за часом, що залишився
/api/resilience/model-cooldowns	DELETE	Зняти блокування моделі — тіло {provider, model} або {all: true}, щоб очистити все
/api/rate-limits	GET	Стан обмеження частоти для кожного облікового запису
/api/rate-limit	GET	Глобальна конфігурація обмеження частоти

Усі чотири маршрути /api/resilience/* вимагають автентифікації керування (requireManagementAuth). Повний опис відмінностей між запобіжником провайдера, затримкою з'єднання та блокуванням моделі див. у розділі Відмовостійкість (розширено).

Оцінювання

Кінцева точка	Метод	Опис
/api/evals	GET/POST	Перелічити набори оцінювання / запустити оцінювання

Політики

Кінцева точка	Метод	Опис
/api/policies	GET/POST/DELETE	Керувати політиками маршрутизації

Відповідність вимогам

Кінцева точка	Метод	Опис
/api/compliance/audit-log	GET	Журнал аудиту відповідності вимогам (останні N)

v1beta (сумісність із Gemini)

Кінцева точка	Метод	Опис
/v1beta/models	GET	Перелічити моделі у форматі Gemini
/v1beta/models/{...path}	POST	Кінцева точка Gemini generateContent

Ці кінцеві точки відтворюють формат API Gemini для клієнтів, яким потрібна нативна сумісність із Gemini SDK.

Внутрішні / системні API

Кінцева точка	Метод	Опис
/api/init	GET	Перевірка ініціалізації застосунку (використовується під час першого запуску)
/api/tags	GET	Сумісні з Ollama теги моделей (для клієнтів Ollama)
/api/restart	POST	Ініціює коректний перезапуск сервера
/api/shutdown	POST	Ініціює коректне завершення роботи сервера
/api/system/env/repair	POST	Відновлює змінні середовища постачальника OAuth

Примітка: Ці кінцеві точки використовуються системою внутрішньо або для сумісності з клієнтами Ollama. Зазвичай кінцеві користувачі не звертаються до них безпосередньо.

Відновлення середовища OAuth (v3.6.1+)

POST /api/system/env/repair
Content-Type: application/json

{
  "provider": "claude-code"
}

Відновлює відсутні або пошкоджені змінні середовища OAuth для певного постачальника. Повертає:

{
  "success": true,
  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}

---

Транскрибування аудіо

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

Транскрибуйте аудіофайли за допомогою будь-якого налаштованого постачальника STT. Перший сегмент шляху вибирає нативного постачальника (openai/…, deepgram/…). Шлюзи, які повторно експортують модель іншого постачальника, використовують кваліфікований ідентифікатор (openrouter/deepgram/nova-3).

Запит:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=openai/whisper-1"

Відповідь:

{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

Приклади ідентифікаторів моделей: openai/whisper-1 (потребує ключа OpenAI), openrouter/deepgram/nova-3 (потребує ключа OpenRouter), deepgram/nova-3 (потребує нативного ключа Deepgram). Запит із простим ідентифікатором deepgram/nova-3 не використовує OpenRouter.

Підтримувані формати: mp3, wav, m4a, flac, ogg, webm.

---

Сумісність з Ollama

Для клієнтів, які використовують формат API Ollama:

# Кінцева точка чату (формат Ollama)
POST /v1/api/chat

# Перелік моделей (формат Ollama)
GET /api/tags

Запити автоматично перетворюються між форматом Ollama та внутрішніми форматами.

Токенізовані псевдоніми для VS Code / псевдоніми без заголовків

Використовуйте ці псевдоніми, коли інтеграція не може додати заголовок Authorization і потребує вбудовування ключа API в базову URL-адресу.

# Псевдонім каталогу в стилі OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Псевдоніми чату в стилі OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Псевдоніми в стилі Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Приклад:

curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

Примітки:

• Токенізовані псевдоніми повторно використовують ті самі обробники, що й /v1/* та /api/tags; структури відповідей залишаються ідентичними.
• Надавайте перевагу Authorization: Bearer ..., якщо клієнт підтримує користувацькі заголовки.
• Токени в URL-адресах можуть з’являтися в журналах зворотного проксі, історії браузера та телеметрії поза OmniRoute. Розглядайте їх як варіант для забезпечення сумісності, а не як стандартний режим автентифікації.

---

Телеметрія

# Отримати зведення телеметрії затримок (p50/p95/p99 для кожного постачальника)
GET /api/telemetry/summary

Відповідь:

{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}

---

Бюджет

# Отримати стан бюджету для всіх ключів API
GET /api/usage/budget

# Установити або оновити бюджет
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}

Примітки щодо схеми (setBudgetSchema): поле apiKeyId є обов’язковим; принаймні одне з полів dailyLimitUsd, weeklyLimitUsd або monthlyLimitUsd повинно бути більшим за нуль. Необов’язкові поля: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Застаріла структура {keyId, limit, period} повертає 400 Bad Request.

Ліміти токенів

Бюджети токенів для кожного API-ключа (окремі від наведеного вище бюджету в USD). Застосовуються безпосередньо під час обробки запиту: коли використання ключа в поточному вікні досягає ліміту, запити відхиляються з помилкою 429 Too Many Requests. Ліміти можуть поширюватися на певну model, provider або застосовуватися globalьно до всього ключа; якщо запиту відповідає кілька лімітів, застосовується найсуворіший із них.

# Перелічити ліміти токенів ключа (включно з поточним використанням у вікні)
GET /api/usage/token-limits?apiKeyId=key-123

# Створити або оновити ліміт токенів
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# Видалити ліміт токенів за ідентифікатором
DELETE /api/usage/token-limits?id=tl-abc

Примітки до схеми (setTokenLimitSchema): apiKeyId і scopeType (model | provider | global) є обов’язковими. scopeValue є обов’язковим, якщо scopeType не дорівнює global (наприклад, ідентифікатор моделі для області model або ідентифікатор провайдера для області provider). tokenLimit має бути додатним цілим числом (перетворюється з рядка). Необов’язкові поля: id (не вказуйте для створення, вкажіть для оновлення), resetInterval (daily | weekly | monthly, типове значення — monthly), resetTime (HH:MM), enabled (типове значення — true). Відповіді GET доповнюють кожен ліміт полями tokensUsed, remaining, windowStart, periodStartAt і nextResetAt. Це кінцева точка класу керування (автентифікація застосовується централізовано конвеєром авторизації).

Обробка запитів

1. Клієнт надсилає запит до /v1/*
2. Обробник маршруту викликає handleChat, handleEmbedding, handleAudioTranscription або handleImageGeneration
3. Визначається модель (безпосередньо провайдер/модель або псевдонім/комбінація)
4. Облікові дані вибираються з локальної БД із фільтрацією за доступністю облікового запису
5. Для чату: handleChatCore перевіряє семантичний кеш/кеш сигнатур і визначає налаштування стиснення комбінації
6. Якщо ввімкнено, проактивне стиснення виконується перед трансляцією для провайдера (lite, Caveman, RTK або їх поєднання)
7. Виконавець провайдера надсилає запит до зовнішнього сервісу
8. Відповідь перетворюється назад у формат клієнта (для чату) або повертається без змін (для вбудовувань/зображень/аудіо)
9. Дані про використання, аналітика стиснення та журнали запитів записуються
10. У разі помилок застосовується резервний варіант відповідно до правил комбінації

Повний опис архітектури: ARCHITECTURE.md

---

Керування комбінаціями

Комбінації маршрутизації вищого рівня (уже описані вище в розділі /api/combos*) також можна зіставляти 1:1 за шаблоном ідентифікатора моделі, що забезпечує прозоре перенаправлення ідентифікатора моделі у стилі OpenAI до комбінації.

Метод	Шлях	Опис
GET	/api/model-combo-mappings	Перелічити всі зіставлення модель→комбінація
POST	/api/model-combo-mappings	Створити зіставлення — тіло: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Отримати окреме зіставлення
PUT	/api/model-combo-mappings/[id]	Оновити поля наявного зіставлення
DELETE	/api/model-combo-mappings/[id]	Видалити зіставлення

Автентифікація: сеанс керування/API-ключ (requireManagementAuth).

---

Вебхуки

Підписки на вихідні вебхуки для подій OmniRoute (завершення запиту, вичерпання квоти, ротація ключів тощо).

Метод	Шлях	Опис
GET	/api/webhooks	Перелічити вебхуки (секрети маскуються як <prefix>...)
POST	/api/webhooks	Створити вебхук — тіло: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Отримати вебхук
PUT	/api/webhooks/[id]	Оновити url/events/secret/description
DELETE	/api/webhooks/[id]	Видалити вебхук
POST	/api/webhooks/[id]/test	Надіслати тестове корисне навантаження на URL вебхука та повернути статус доставлення

Автентифікація: сеанс керування/API-ключ (requireManagementAuth).

---

Зареєстровані ключі (автоматичне керування)

Використовуються підсистемою автоматичного керування ключами для випуску та ротації API-ключів у базового постачальника/облікового запису з добовими/погодинними квотами.

Метод	Шлях	Опис
GET	/api/v1/registered-keys	Перелічити зареєстровані ключі (лише замаскований префікс)
POST	/api/v1/registered-keys	Випустити новий зареєстрований ключ — тіло: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Повертає необроблений ключ один раз. Повертає 429 у разі відмови через квоту.
GET	/api/v1/registered-keys/[id]	Отримати метадані зареєстрованого ключа (без необробленого ключового матеріалу)
DELETE	/api/v1/registered-keys/[id]	Відкликати зареєстрований ключ
POST	/api/v1/registered-keys/[id]/revoke	Явна кінцева точка відкликання (має той самий ефект, що й DELETE)

Автентифікація: API-ключ Bearer (isAuthenticated). Див. також /v1/quotas/check і /v1/issues/report.

---

Протокол агентів

Завдання хмарних агентів (Claude Code, Codex Cloud, OpenHands тощо), що виконуються віддалено від імені користувачів OmniRoute.

Метод	Шлях	Опис
GET	/api/v1/agents/tasks	Перелік завдань — необов’язкові ?provider=, ?status=, ?limit= (1–500, типове значення — 50)
POST	/api/v1/agents/tasks	Створити завдання — тіло перевіряється за допомогою CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Повертає 201 з оболонкою завдання
DELETE	/api/v1/agents/tasks?id=...	Видалити завдання
GET	/api/v1/agents/tasks/[id]	Отримати завдання — синхронно оновлює статус із зовнішнього хмарного агента, коли задано external_id
POST	/api/v1/agents/tasks/[id]	Дискримінована дія: {action: "approve"}, {action: "message", message} або {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Видалити конкретне завдання за id

Автентифікація: для кожного методу потрібна автентифікація керування (requireCloudAgentManagementAuth). До v3.8.0 ці методи не вимагали автентифікації — критичну зміну див. у коміті 588a0333.

# Створити хмарне завдання Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

---

Проксі керування

Вихідні проксі HTTP(S)/SOCKS, які можна призначати постачальникам, обліковим записам або глобально.

Метод	Шлях	Опис
GET	/api/v1/management/proxies	Перелік проксі (з ?id= повертає один; з ?id=&where_used=1 повертає граф призначень)
POST	/api/v1/management/proxies	Створити проксі — тіло перевіряється за допомогою createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Оновити проксі — тіло перевіряється за допомогою updateProxyRegistrySchema (потрібен id)
DELETE	/api/v1/management/proxies?id=...&force=1	Видалити проксі (використовуйте force=1, щоб від’єднати призначення)
GET	/api/v1/management/proxies/assignments	Перелік призначень — можна фільтрувати за proxy_id, scope, scope_id; передайте resolve_connection_id=<id>, щоб визначити активний проксі для з’єднання
PUT	/api/v1/management/proxies/assignments	Призначити — тіло перевіряється за допомогою proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Очищає кеш диспетчера
PUT	/api/v1/management/proxies/bulk-assign	Масове призначення — тіло перевіряється за допомогою bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Агреговані дані про стан проксі (кількість успіхів/помилок, затримка) за певний проміжок часу

Автентифікація: сесія керування/API-ключ потрібні для кожного маршруту (requireManagementAuth).

Зазначені в описі завдання POST /api/v1/management/proxies/[id]/assignments і POST /api/v1/management/proxies/[id]/health обслуговуються наведеними вище пласкими маршрутами /assignments і /health — у кодовій базі немає підмаршрутів для окремих id.

---

Відмовостійкість (розширено)

OmniRoute надає три незалежні механізми обробки тимчасових збоїв; наведені нижче кінцеві точки керування дають операторам змогу переглядати та перевизначати їх:

Область дії	Сховище стану	Перегляд	Скидання / очищення
Запобіжник постачальника	domain_circuit_breakers + у пам’яті	/api/monitoring/health	POST /api/resilience/reset
Затримка підключення	rateLimitedUntil у підключеннях постачальника	/api/rate-limits, /api/providers/[id]	(повторно вмикається відкладено; очищення через PUT постачальника)
Блокування моделі	Реєстр доступності моделей у пам’яті	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience приймає перевизначення запобіжника постачальника в providerBreaker.oauth і providerBreaker.apikey. Кожен профіль підтримує degradationThreshold, failureThreshold і resetTimeoutMs; ті самі поля доступні в Панель керування → Налаштування → Відмовостійкість.

# Очистити блокування однієї моделі
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# Видалити всі блокування
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Повний концептуальний довідник і стандартні налаштування запобіжників: див. CLAUDE.md → «Стан середовища виконання відмовостійкості».

---

Навички

Фреймворк навичок для розширення OmniRoute за допомогою власних виконуваних обробників, а також інтеграцій із маркетплейсами.

Метод	Шлях	Опис
GET	/api/skills	Перелік установлених навичок — фільтрація за ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, із пагінацією
GET	/api/skills/[id]	Отримати одну навичку
PUT	/api/skills/[id]	Оновити навичку (назву, опис, режим, схему, обробник, теги)
DELETE	/api/skills/[id]	Видалити навичку
POST	/api/skills/install	Установити навичку з необробленого маніфесту — тіло: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Перелік нещодавніх виконань навичок (журнал аудиту з вхідними/вихідними даними та тривалістю)
GET	/api/skills/marketplace?q=...	Пошук/перелік популярних навичок із маркетплейсу SkillsMP (потрібне налаштування skillsmpApiKey)
POST	/api/skills/marketplace/install	Установити навичку за ідентифікатором із SkillsMP
GET	/api/skills/skillssh?q=&limit=	Пошук у реєстрі skills.sh
POST	/api/skills/skillssh/install	Установити навичку за ідентифікатором із skills.sh

Автентифікація: сеанс керування/API-ключ. Маршрути пошуку в маркетплейсі приймають або автентифікацію керування, або Bearer API-ключ (isAuthenticated).

---

Пам’ять

Постійне сховище контекстної/фактичної пам’яті, ізольоване для кожного ключа API / сеансу.

Метод	Шлях	Опис
GET	/api/memory	Перелік записів пам’яті — ?apiKeyId=, ?type=, ?sessionId=, ?q=, із пагінацією offset/limit або page/limit
POST	/api/memory	Створення запису пам’яті — тіло перевіряється за допомогою Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Отримання одного запису пам’яті
DELETE	/api/memory/[id]	Видалення запису пам’яті
GET	/api/memory/health	Стан підсистеми пам’яті (підключення до БД, бекенд векторних представлень, стан векторного індексу)

Автентифікація: сеанс керування/ключ API (requireManagementAuth). Перелік значень type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (див. MemoryType у src/lib/memory/types.ts).

---

Сервер MCP

OmniRoute постачається із вбудованим сервером Model Context Protocol із 3 транспортами (stdio, SSE, streamable-http) та інструментами з обмеженими областями доступу. Наведені нижче кінцеві точки панелі керування зчитують дані про стан/аудит і проксіюють HTTP-транспорти.

Метод	Шлях	Опис
GET	/api/mcp/status	Сигнал активності, транспорт, стан підключення, останній виклик, найпопулярніші інструменти, показник успішності за 24 години
GET	/api/mcp/tools	Перелік інструментів MCP із name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Відкриття потоку SSE для транспорту SSE (повертає 503, якщо MCP вимкнено або транспорт не відповідає налаштуванню)
POST	/api/mcp/sse	Надсилання кадру JSON-RPC через транспорт SSE
GET	/api/mcp/stream	Відкриття SSE-частини транспорту Streamable HTTP (повідомлення, ініційовані сервером)
POST	/api/mcp/stream	Надсилання кадру JSON-RPC через транспорт Streamable HTTP
DELETE	/api/mcp/stream	Завершення сеансу Streamable HTTP
GET	/api/mcp/audit	Запит журналу аудиту — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Агрегована статистика аудиту (загальна кількість, показник успішності, середня тривалість, найпопулярніші інструменти)

Автентифікація: транспорти sse/stream використовують спеціальний механізм автентифікації MCP (Bearer-ключ API з областю доступу mcp); маршрути status/tools/audit* доступні для читання з панелі керування (додаткова автентифікація, окрім доступу до хоста панелі керування, не потрібна).

Обидва HTTP-транспорти контролюються параметрами settings.mcpEnabled і settings.mcpTransport — невідповідність транспорту повертає 400, а вимкнений стан MCP повертає 503.

---

Сервер A2A

OmniRoute надає кінцеву точку A2A (Agent-to-Agent) JSON-RPC 2.0, а також REST-обгортку для перевірки та використання в інформаційній панелі.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # необов’язково, якщо не задано OMNIROUTE_API_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Маршрутизуй це завдання з програмування"}]
  }
}

Підтримувані методи (усі залежать від settings.a2aEnabled):

Метод	Опис
message/send	Синхронне виконання навички; повертає {task, artifacts, metadata}
message/stream	Потокове виконання того самого набору навичок через SSE
tasks/get	Отримання завдання за taskId
tasks/cancel	Скасування завдання за taskId

Вбудовані навички: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Картка агента

GET /.well-known/agent.json

Повертає загальнодоступну картку агента A2A (ім’я, опис, можливості, каталог навичок, схема автентифікації), яка публічно кешується протягом 1 години. Автентифікація не потрібна.

Допоміжні REST-методи

Метод	Шлях	Опис
GET	/api/a2a/status	Стан увімкнення A2A + статистика завдань + зведення кешованої картки агента
GET	/api/a2a/tasks	Список завдань — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Не реалізовано як допоміжний REST-метод — створюйте через JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Отримання одного завдання
POST	/api/a2a/tasks/[id]/cancel	Скасування завдання

Автентифікація: допоміжні REST-методи працюють без автентифікації керування (доступні для читання з інформаційної панелі); маршрут JSON-RPC /a2a використовує Bearer OMNIROUTE_API_KEY, якщо його налаштовано.

---

Хмара, оцінювання та аналіз

Метод	Шлях	Опис
POST	/api/cloud/auth	Перевірка Bearer-ключа та повернення замаскованих підключень до провайдерів і псевдонімів моделей для клієнтів хмарної синхронізації
POST	/api/cloud/credentials/update	Оновлення зашифрованих облікових даних для провайдера, синхронізованого з хмарою
POST	/api/cloud/model/resolve	Перетворення логічного ідентифікатора моделі на конкретного провайдера/модель за допомогою локальної таблиці маршрутизації
GET	/api/cloud/models/alias	Перелік псевдонімів моделей, доступних для хмарної синхронізації
GET	/api/assess	Читання категоризацій останнього аналізу (для кожного провайдера/моделі)
POST	/api/assess	Запуск аналізу — тіло: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Перелік вбудованих наборів оцінювання та останніх запусків
POST	/api/evals	Запуск оцінювання
POST	/api/evals/suites	Створення користувацького набору оцінювання — тіло перевіряється за допомогою evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Отримання користувацького набору оцінювання

Автентифікація: /api/cloud/auth перевіряє Bearer-ключ безпосередньо; інші маршрути /api/cloud/*, /api/evals/* і /api/assess потребують сеансу керування/API-ключа. POST-запит /api/assess використовує validateBody зі схемою області дії на основі дискримінованого об’єднання.

---

Керування ACP (Agent Client Protocol)

як дочірні процеси. Ці кінцеві точки керують виявленням агентів ACP і реєстрацією користувацьких агентів.

Метод	Шлях	Опис
GET	/api/acp/agents	Перелічити всі відомі CLI-агенти (вбудовані та користувацькі) зі статусом встановлення, версією та бінарним файлом
POST	/api/acp/agents	Зареєструвати користувацького агента ACP або оновити кеш — тіло: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} або {action: "refresh"}
DELETE	/api/acp/agents	Видалити користувацького агента ACP — параметр запиту: ?id=<agentId>

Приклад відповіді (GET /api/acp/agents):

{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}

Автентифікація: Потрібен сеанс керування (файл cookie auth_token панелі керування) або API-ключ з областю доступу до керування.

Повну інформацію див. у розділі Фреймворк ACP.

---

Аналітика та спостережуваність

Кінцеві точки аналітики в реальному часі для моніторингу маршрутизації, стиснення та різноманітності провайдерів. Вони забезпечують роботу сторінок /dashboard/analytics/*.

Аналітика автоматичної маршрутизації

Метод	Шлях	Опис
GET	/api/analytics/auto-routing	Агрегована статистика автоматичної маршрутизації: загальна кількість викликів, розподіл стратегій і рівнів, провідні провайдери
GET	/api/analytics/auto-routing?days=7	Статистика за часовим вікном (за замовчуванням 24 год)

Приклад відповіді:

{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}

Аналітика стиснення

Метод	Шлях	Опис
GET	/api/analytics/compression	Агрегована статистика стиснення: заощаджені токени, відсоток економії, розподіл режимів, використання рушіїв

Приклад відповіді:

{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}

Відстеження різноманітності провайдерів

Метод	Шлях	Опис
GET	/api/analytics/diversity	Відстеження різноманітності на основі ентропії Шеннона: запобігає виникненню єдиних точок відмови шляхом вимірювання розподілу між провайдерами

Приклад відповіді:

{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}

Автентифікація: Потрібен сеанс керування або API-ключ з областю доступу до керування.

---

Адміністративні операції

Ендпоїнти лише для адміністраторів, призначені для операційного керування.

Метод	Шлях	Опис
GET	/api/admin/concurrency	Отримати поточні обмеження паралельності (глобальні та для кожного провайдера)
POST	/api/admin/concurrency	Оновити обмеження паралельності — тіло: {global?: number, perProvider?: Record<string, number>}

Автентифікація: Потрібен сеанс керування з областю доступу адміністратора.

---

Керування інструментами CLI

Керуйте інструментами CLI, які інтегруються з OmniRoute (antigravity, chipotle, commandCode, devin-cli тощо). Повний список див. у Довіднику провайдерів.

Метод	Шлях	Опис
GET	/api/cli-tools/all-statuses	Стан усіх інструментів CLI (встановлення, версія, час останньої активності)
GET	/api/cli-tools/status	Докладні відомості про стан одного інструмента CLI (параметр запиту ?tool=)
POST	/api/cli-tools/apply	Записати згенеровану конфігурацію інструмента (dryRun показує попередній результат; 422 + containerEphemeralTarget у контейнері; migration зазначає застарілий YAML Codex)
GET	/api/cli-tools/backups	Отримати список резервних копій конфігурацій інструментів CLI
POST	/api/cli-tools/backups	Створити резервну копію конфігурацій усіх інструментів CLI
POST	/api/cli-tools/backups	Відновити: той самий ендпоїнт із {tool, backupId} у тілі запиту відновлює відповідну резервну копію
GET	/api/cli-tools/antigravity-mitm	Стан MITM-проксі Antigravity (інструмент CLI "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Налаштувати псевдоніми antigravity-mitm

Автентифікація: Потрібен сеанс керування.

---

Навички агентів

Керуйте навичками ШІ-агентів (подібними до користувацьких GPT від OpenAI, але призначеними для агентів).

Метод	Шлях	Опис
GET	/api/agent-skills	Отримати список усіх навичок агентів (вбудованих і користувацьких)
GET	/api/agent-skills/[id]	Отримати певну навичку агента
POST	/api/agent-skills	Створити користувацьку навичку агента — тіло: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Оновити користувацьку навичку агента
DELETE	/api/agent-skills/[id]	Видалити користувацьку навичку агента
GET	/api/agent-skills/[id]/raw	Отримати необроблений промпт і метадані (без виконання)
POST	/api/agent-skills/generate	Згенерувати нову навичку за допомогою ШІ на основі опису природною мовою

Автентифікація: Потрібен сеанс керування або API-ключ з областю доступу до керування.

---

Керування кешем

Керуйте семантичним кешем і кешем міркувань.

Метод	Шлях	Опис
GET	/api/cache	Огляд кешу: загальна кількість записів, частота влучань, розмір на диску
GET	/api/cache/entries	Перелік кешованих записів (із пагінацією)
DELETE	/api/cache/entries	Видалення записів кешу (фільтрація за параметрами запиту)
GET	/api/cache/stats	Детальна статистика кешу (за постачальниками та моделями)
GET	/api/cache/reasoning	Стан кешу міркувань (для відтворення міркувань)
DELETE	/api/cache/reasoning	Очищення кешу міркувань — параметри запиту: ?toolCallId=<id> (один), ?provider=<p> або без параметрів (усі записи)

Автентифікація: Потрібен сеанс керування.

---

Система пам’яті

Керуйте постійною пам’яттю (FTS5 + векторні вкладення).

Метод	Шлях	Опис
GET	/api/memory	Перелік записів пам’яті (фільтрація за областю, типом і пошуковим запитом)
POST	/api/memory	Створення нового запису пам’яті — тіло: {scope, type, content, metadata?}
GET	/api/memory/[id]	Отримання конкретного запису пам’яті
PUT	/api/memory/[id]	Оновлення запису пам’яті
DELETE	/api/memory/[id]	Видалення запису пам’яті
GET	/api/memory?q=	Пошук у пам’яті (FTS5 + векторний пошук) — статистику включено до тієї самої відповіді

Автентифікація: Потрібен сеанс керування або API-ключ з областю керування.

---

Вебхуки

Керуйте підписками вебхуків на події.

Метод	Шлях	Опис
GET	/api/webhooks	Перелік усіх підписок вебхуків
POST	/api/webhooks	Створення підписки вебхука — тіло: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Отримання конкретної підписки вебхука
PUT	/api/webhooks/[id]	Оновлення підписки вебхука
DELETE	/api/webhooks/[id]	Видалення підписки вебхука
GET	/api/webhooks/[id]/deliveries	Перелік історії доставок для вебхука (журнал успішних і невдалих доставок)
POST	/api/webhooks/[id]/test	Надсилання тестової події до вебхука

Автентифікація: Потрібен сеанс керування.

Повний перелік типів подій див. у розділі Фреймворк вебхуків.

---

Фреймворк навичок

Керування навичками (фреймворком агентних розширень).

Метод	Шлях	Опис
GET	/api/skills	Переглянути всі встановлені навички (вбудовані та користувацькі)
POST	/api/skills/install	Встановити навичку з локального шляху або URL
DELETE	/api/skills/[id]	Видалити навичку
PUT	/api/skills/[id]	Увімкнути або вимкнути навичку — тіло: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Виконати навичку — тіло: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Переглянути історію виконання всіх навичок (фільтр за ?apiKeyId=)

Автентифікація: Потрібен сеанс керування або API-ключ із дозволами на керування.

Повну інформацію див. у розділі Фреймворк навичок.

---

Плагіни

Керування плагінами OmniRoute (сторонніми розширеннями).

Метод	Шлях	Опис
GET	/api/plugins	Переглянути встановлені плагіни
POST	/api/plugins/marketplace/install	Встановити плагін із маркетплейсу
DELETE	/api/plugins/[name]	Видалити плагін
POST	/api/plugins/[name]/activate	Активувати плагін
POST	/api/plugins/[name]/deactivate	Деактивувати плагін
GET	/api/plugins/[name]/config	Отримати конфігурацію плагіна
PUT	/api/plugins/[name]/config	Оновити конфігурацію плагіна

Автентифікація: Потрібен сеанс керування.

Повну інформацію див. у розділі Фреймворк плагінів.

---

Тіньова маршрутизація

Тіньове / A-B-порівняння провайдерів не є окремим REST-інтерфейсом — воно налаштовується через комбіновану маршрутизацію (див. Автоматичне комбінування). Метрики порівняння для кожної комбінації надаються через GET /api/combos/metrics.

---

Захисні механізми

Перевірка захисних механізмів середовища виконання (виявлення персональних даних, виявлення ін’єкцій у промпти, перенаправлення візуального вмісту). Захисні механізми виконуються для кожного запиту; відмовитися від них для окремого виклику можна за допомогою заголовка запиту x-omniroute-disabled-guardrails — постійного інтерфейсу для їх увімкнення або вимкнення немає.

Метод	Шлях	Опис
GET	/api/guardrails	Переглянути зареєстровані захисні механізми та їхній стан (назва / увімкнено / пріоритет)
POST	/api/guardrails/test	Виконати пробний запуск конвеєра перед викликом на прикладі вхідних даних — тіло: {input, disabledGuardrails?}

Автентифікація: Потрібен сеанс керування.

Повну інформацію див. у розділі Безпека > Захисні механізми.

---

---

Автентифікація

Опис чотирьох типів облікових даних (сеанс інформаційної панелі, локальний токен CLI, токен доступу oma_live_…, API-ключ з областю дії керування) та їхніх відмінностей від ключів інференсу наведено в розділі Автентифікація керування.

• Маршрути інформаційної панелі (/dashboard/*) використовують файл cookie auth_token
• Для входу використовується збережений хеш пароля; резервний варіант — INITIAL_PASSWORD
• Параметр requireLogin можна перемикати через /api/settings/require-login
• Маршрути /v1/* можуть вимагати API-ключ Bearer, якщо REQUIRE_API_KEY=true
• У цій довідці «токен керування» / «API-ключ з областю дії керування» означає один із типів, описаних у цьому посібнику, а не невизначений додатковий тип секрету

Критична зміна (v3.8.0) — /api/v1/agents/tasks/* і кінцеві точки керування періодом очікування тепер вимагають автентифікації керування (файл cookie auth_token інформаційної панелі або API-ключ з областю дії керування). Клієнти, які раніше викликали ці маршрути без автентифікації, отримуватимуть відповідь 401 Unauthorized. Див. коміт 588a0333 (fix(auth): require management auth for agent and cooldown APIs).