OmniRoute/docs/i18n/bg/docs/reference/API_REFERENCE.md

API Reference (Български)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇩 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 · 🇺🇦 uk-UA · 🇵🇰 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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Основна справочна документация за OmniRoute API. Тя обхваща публичния интерфейс /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": "Write a function to..."}
  ],
  "stream": true
}

Персонализирани заглавки

Заглавка	Посока	Описание
X-OmniRoute-No-Cache	Заявка	Задайте на true, за да заобиколите кеша
x-omniroute-no-memory	Заявка	Задайте на true, за да пропуснете инжектирането на памет + умения за тази заявка (аналогично на no-cache; избягва допълнителния разход на токени/средства за всяко извикване)
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	Отговор	Сумата в USD, спестена от кеша при 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 (fail-open).

Семантика на разходите при попадение в кеша: при HIT в семантичния кеш (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, но никога избраната връзка или идентификационните данни. При подновяване и освобождаване поколението се подава в 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 ключ и точното активно поколение в рамките на една транзакция в базата данни. displayName е само конфигурираното име на връзката с премахнати околни интервали; стойността му е null, когато не съществува безопасно конфигурирано име. OmniRoute никога не го заменя с имейл адрес или генерирана идентичност на акаунт. Стойността за доставчика е нечувствителен етикет за показване и никога не е генериран идентификатор на съвместим доставчик. Идентификационни данни, токени, бисквитки, необработени идентификатори на връзки или API ключове, хешове на собственици, тайни за изолиране и вътрешни данни за маршрутизиране не се включват.

Заявките с грешен ключ, грешен собственик, остаряло поколение, липсващ, изтекъл, освободен или обезсилен наем връщат една и съща грешка 409 LEASE_FENCE_STALE без метаданни за връзката. Клиент, получил отговор за изчакване на капацитет, няма активно обвързване, което да провери. Когато маршрутизирането прехвърли активен наем, същото поколение остава валидно и състоянието атомарно връща новото обвързване, но никога старото. Съществуващите клиенти остават непроменени, тъй като отговорите за придобиване, подновяване, освобождаване и изчакване запазват предишните си структури.

Този договор на сървъра не променя стандартната команда /status на OpenAI Codex. В момента стандартният Codex отчита своя доставчик на модела и вграденото състояние на удостоверяване/акаунта, но не визуализира произволни метаданни за акаунти на персонализирани доставчици; бъдеща клиентска интеграция трябва да извиква това действие и да решава как да показва connection.displayName.

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

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

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

Временната конкуренция за ресурс връща 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

Замяна на плана за компресия за отделна заявка. Има най-висок приоритет — надделява над замяната от комбинацията за маршрутизиране, активния профил, автоматичното задействане и настройката по подразбиране от панела. Стойности:

Стойност	Ефект
off	Без компресия за тази заявка.
default	Изведеният от панела профил по подразбиране (игнорира активния профил).
engine:<id>	Една машина, когато е активирана, напр. engine:rtk.
<combo>	Именувана комбинация, съпоставена първо по име (без значение от регистъра), а след това по идентификатор.

Бележки:

• Непознатите стойности се игнорират (заявката никога не се отхвърля); определянето продължава съгласно обичайния приоритет на операторите.
• Ако няколко комбинации споделят едно и също име, подайте id на комбинацията за детерминирано съвпадение.
• Комбинация с име off или default не може да бъде избрана по име (тези ключови думи се интерпретират първо); посочете такава комбинация чрез нейния идентификатор.
• Главният превключвател за компресия е безусловно ограничение: когато компресията е глобално деактивирана, тази заглавка не може да я активира.

Приложеният план се връща в заглавката на отговора:

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), също се разпознават. Операциите на 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 } могат да бъдат публичен HTTPS URL, data: URI или необработени 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 MiB декодирани данни на елемент и 16 MiB декодирани данни за цялата заявка.

Преобразуване за доставчика (каноничните елементи никога не се препращат непроменени):

• Мултимодални модели на Jina: всеки елемент от най-горно ниво се превръща в един обект с ключ за съответната модалност (text / image / audio / video / pdf), като за вградените мултимедийни данни се използват data 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": "A beautiful sunset over mountains",
  "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	Синхронен, чрез партньорската крайна точка openapi/chat/completions на Vertex AI — вижте по-долу за удостоверяването/URL адреса.

И трите доставчика отговарят с тяло в същия формат като този на Mistral:

{
  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
  "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 ключът на връзката е или идентификационен JSON за Service Account (който се обменя за краткотраен OAuth токен за достъп чрез потока JWT bearer), или вече издаден OAuth токен за достъп, използван без промени. URL адресът на външната крайна точка е общата партньорска крайна точка openapi/chat/completions на Vertex, съставена от проекта и региона на връзката — изрично зададените providerSpecificData.project/providerSpecificData.region винаги имат предимство; в противен случай проектът се извлича от project_id в JSON файла на Service Account, а регионът по подразбиране е 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 (редактиране/inpaint)
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.

---

API за файлове

Съвместима с OpenAI крайна точка за файлове за пакетен вход/изход и качване на файлове със зададено предназначение.

Метод	Път	Описание
POST	/v1/files	Качване на файл (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — максимум 512 MiB
GET	/v1/files	Извеждане на списък с файловете за удостоверения API ключ
GET	/v1/files/[id]	Извличане на метаданните на файл
DELETE	/v1/files/[id]	Изтриване на файл
GET	/v1/files/[id]/content	Поточно връщане на необработеното съдържание на файла

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

---

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	Отмяна на пакет в процес на обработка

Удостоверяване: Bearer API ключ. Пакетите са обхванати за всеки 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	Статистика по доставчик за попадения/латентност/кеш

Удостоверяване: Bearer API ключ (extractApiKey + isValidApiKey). Политиката за търсене се прилага чрез enforceApiKeyPolicy.

---

API за извличане на уеб съдържание

Извлича съдържание от URL чрез конфигуриран доставчик за извличане на уеб съдържание (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Метод	Път	Описание
POST	/v1/web/fetch	Извлича/събира съдържание от URL — тялото се валидира от v1WebFetchSchema

Удостоверяване: Bearer API ключ (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.

Удостоверяване: Bearer API ключ по време на ръкостискането.

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 чрез WebSocket е свързано изключително с codex (ChatGPT бекенд). То слуша на същия порт като API/таблото за управление по пътищата /v1/responses, /responses и /api/v1/responses. При първия кадър response.create то удостоверява + подготвя чрез вътрешния мост codex-responses-ws, избира codex OAuth връзка и създава тунел към 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.

Удостоверяване: Bearer API ключ по време на ръкостискането. Включеният HTTP сървър (server-ws.mjs) трябва да бъде активната входна точка (каквато е по подразбиране, когато съществува app/server-ws.mjs).

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

OpenAI Codex CLI валидира името на модела от страната на клиента, когато 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"   # без завършваща наклонена черта; WS URL се извежда автоматично (използвайте 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 създава тунел към избраната codex OAuth връзка. Валидирано от край до край спрямо локалния сървър: ChatGPT връща codex.rate_limits + response.created и предава поточно завършения отговор.

---

Квоти и докладване на проблеми

Метод	Път	Описание
GET	/v1/quotas/check	Предварително валидиране на квотата за provider + accountId преди издаване на регистриран ключ
POST	/v1/issues/report	Докладване в GitHub на неуспешно издаване поради квота/ключ (изисква GITHUB_ISSUES_REPO + токен)

Удостоверяване: Bearer API ключ (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 форматът ги разграничава.

Удостоверяване: собственият Bearer API ключ на извикващата страна, валидиран с 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	Текущи обобщени данни за латентността по доставчик/модел (средна стойност/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	Крайна точка generateContent на Gemini

Тези крайни точки отразяват формата на 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. Това е крайна точка от клас за управление (удостоверяването се прилага централизирано от authz конвейера).

Обработка на заявки

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).

---

Webhooks

Абонаменти за изходящи webhook известия за събития в OmniRoute (завършване на заявка, изчерпване на квота, ротация на ключове и др.).

Метод	Път	Описание
GET	/api/webhooks	Изброява webhook абонаментите (тайните са маскирани като <prefix>...)
POST	/api/webhooks	Създава webhook — тяло: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Извлича webhook
PUT	/api/webhooks/[id]	Актуализира url/events/secret/description
DELETE	/api/webhooks/[id]	Премахва webhook
POST	/api/webhooks/[id]/test	Изпраща тестов payload към URL адреса на webhook и връща статуса на доставката

Удостоверяване: сесия за управление/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)

Удостоверяване: Bearer API ключ (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]	Изтрива конкретна задача по идентификатор

Удостоверяване: за всеки метод се изисква удостоверяване за управление (requireCloudAgentManagementAuth). Преди v3.8.0 тези маршрути не изискваха удостоверяване — вижте commit 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 — в кодовата база няма подмаршрути за отделни идентификатори.

---

Устойчивост (разширено)

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
}

Удостоверяване: Изисква сесия за управление (бисквитка auth_token на таблото) или API ключ с обхват за управление.

Вижте ACP Framework за пълни подробности.

---

Анализи и наблюдаемост

Крайни точки за анализи в реално време за наблюдение на маршрутизирането, компресията и разнообразието от доставчици. Те захранват страниците /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 отбелязва наследен Codex YAML)
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

Удостоверяване: Изисква сесия за управление.

---

Умения на агенти

Управлявайте уменията на AI агенти (подобни на персонализираните 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	Генерира чрез AI ново умение въз основа на описание на естествен език

Удостоверяване: Изисква сесия за управление или 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.

---

Защитни механизми

Преглед на защитните механизми по време на изпълнение (откриване на PII, откриване на инжектиране в подкани, свързване с визуални модели). Защитните механизми се изпълняват при всяка заявка; отказът за отделно извикване се задава чрез заглавката на заявката x-omniroute-disabled-guardrails — няма постоянен интерфейс за активиране/деактивиране.

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

Удостоверяване: Изисква сесия за управление.

Вижте Сигурност > Защитни механизми за пълни подробности.

---

---

Удостоверяване

Вижте Удостоверяване за управление за четирите вида идентификационни данни (сесия на таблото, локален CLI токен, oma_live_… токен за достъп, API ключ с обхват за управление) и как те се различават от ключовете за инференция.

• Маршрутите на таблото (/dashboard/*) използват бисквитката auth_token
• Влизането използва запазения хеш на паролата; резервно се използва INITIAL_PASSWORD
• requireLogin може да се превключва чрез /api/settings/require-login
• Маршрутите /v1/* могат по избор да изискват Bearer API ключ, когато REQUIRE_API_KEY=true
• „токен за управление“ / „API ключ с обхват за управление“ в тази справка означава един от видовете в това ръководство — не допълнителен недефиниран тип тайна

Несъвместима промяна (v3.8.0) — /api/v1/agents/tasks/* и крайните точки за управление на периода на изчакване вече изискват удостоверяване за управление (бисквитка auth_token на таблото или API ключ с обхват за управление). Клиентите, които преди са извиквали тези маршрути без удостоверяване, ще получат 401 Unauthorized. Вижте commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).