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

API Reference (Filipino)

🌐 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 · 🇵🇱 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

---

🌐 Mga Wika: 🇺🇸 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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Pangunahing sanggunian para sa OmniRoute API. Saklaw nito ang pampublikong /v1 surface at ang mga pinakamadalas gamiting endpoint sa pamamahala; ang nababasa ng makina na docs/openapi.yaml at ang route tree sa ilalim ng src/app/api/ ang mga kumpletong sanggunian.

---

Talaan ng mga Nilalaman

• Mga Chat Completion
• Eksklusibong mga Lease ng Pinamamahalaang Session
• Mga Embedding
• Pagbuo ng Larawan
• OCR ng Dokumento
• Listahan ng mga Modelo
• Manifest ng Provider Plugin
• Mga Endpoint ng Compatibility
• Files API
• Batches API
• Search API
• WebSocket Streaming
• Pag-uulat ng mga Quota at Isyu
• Semantic Cache
• Dashboard at Pamamahala
• Pamamahala ng Combo
• Mga Webhook
• Mga Nakarehistrong Key (Awtomatikong Pamamahala)
• Protocol ng mga Agent
• Mga Proxy sa Pamamahala
• Katatagan (pinalawak)
• Mga Skill
• Memory
• MCP Server
• A2A Server
• Cloud, mga Eval at Assess
• Pagproseso ng Request
• Authentication

---

Mga Chat Completion

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
}

Mga Custom Header

Header	Direksyon	Paglalarawan
X-OmniRoute-No-Cache	Request	Itakda sa true upang lampasan ang cache
x-omniroute-no-memory	Request	Itakda sa true upang laktawan ang pag-inject ng memory + skills para sa request na ito (tumutulad sa no-cache; iniiwasan ang overhead sa token/gastos sa bawat call)
X-OmniRoute-Progress	Request	Itakda sa true para sa mga event ng progreso
X-Session-Id	Request	Sticky session key para sa external session affinity
x_session_id	Request	Tinatanggap din ang variant na may underscore (direktang HTTP)
X-OmniRoute-Session-Id	Request	Tag ng session/conversation na ibinigay ng caller (ginagamit din ng memory). Kapag mayroon, pinapanatili nang eksakto sa call_logs.session_tag para sa pag-uugnay ng gastos sa bawat session (#8249) — hindi kailanman binubuo kapag wala
Idempotency-Key	Request	Dedup key (5s na palugit)
X-Request-Id	Request	Alternatibong dedup key
X-OmniRoute-Cache	Response	HIT o MISS (hindi streaming)
X-OmniRoute-Idempotent	Response	true kung na-deduplicate
X-OmniRoute-Progress	Response	enabled kung naka-on ang pagsubaybay sa progreso
X-OmniRoute-Session-Id	Response	Epektibong session ID na ginamit ng OmniRoute
X-OmniRoute-Request-Id	Response	ID para sa pag-uugnay ng request (kapag nalalaman)
X-OmniRoute-Version	Response	Bersyon ng build ng OmniRoute (laging naroroon)
X-OmniRoute-Cost-Saved	Response	Halagang USD na naiwasang gastusin dahil sa cache sa isang HIT (mga cache hit lamang)
X-OmniRoute-Decision	Response	Bakas ng routing: strategy=<name>; provider=<alias>; latency_ms=<n> (ang <name> ay ang combo strategy, o single para sa request na hindi combo) — laging naroroon sa mga completion response

Paalala tungkol sa Nginx: kung umaasa ka sa mga header na may underscore (halimbawa, x_session_id), i-enable ang underscores_in_headers on;.

Mga header ng telemetry ng gastos: kasama rin sa mga matagumpay na tugon na hindi streaming ang hanay ng telemetry ng gastos na X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, nakapirming 10 decimal; 0.0000000000 para sa libre/walang presyo), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit, at X-OmniRoute-Fallback-Attempts (kapag > 0 lamang), kasama ang X-OmniRoute-Request-Id at X-OmniRoute-Version. Inilalabas ang mga ito ng mga chat completion, /v1/responses, /v1/messages, at ng mga media endpoint — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations, at /v1/moderations (palaging 0 ang gastos). Kinakalkula ang gastos sa media ayon sa bawat modality (bawat larawan, bawat segundo, bawat character, bawat search-unit) kapag may available na pagpepresyo; kung wala, 0 ito (fail-open).

Semantika ng gastos sa cache hit: sa isang HIT ng semantic cache (X-OmniRoute-Cache-Hit: true), walang ginagawang upstream call, kaya ang X-OmniRoute-Response-Cost ay 0.0000000000 (ang karagdagang gastos sa paghahatid ng hit). Hiwalay na iniuulat sa X-OmniRoute-Cost-Saved ang orihinal/gastos na sana ay natamo. Dapat pagsamahin ng mga consumer ng billing ang X-OmniRoute-Response-Cost (walang gastos ang mga hit); maaaring pagsama-samahin ng cache analytics ang X-OmniRoute-Cost-Saved.

Mga Eksklusibong Pinamamahalaang Lease ng Session

Ang eksklusibong pinamamahalaang pag-lease ng session ay isang opt-in at client-neutral na kontrata sa pagruruta: isang aktibong may-ari ang humahawak sa isang kwalipikadong koneksyon ng OmniRoute. Hindi ito nagle-lease ng modelo, nangangailangan ng OAuth, tumutukoy sa partikular na client, o nangangailangan ng partikular na provider.

Ang API key na ginagamit sa pagpapatotoo ay dapat may scope na lease:exclusive at tahasang hindi bakanteng listahan ng allowedConnections. Magkasamang ipinapatupad ng hangganan ng mutation sa database ang dalawang field kapag gumagawa ng key at nagsasagawa ng mga bahagyang update.

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"}

Inilalantad ng matagumpay na mga tugon sa pagkuha, pag-renew, at pag-release ang mga timestamp, state, at ang eksaktong positibong generation, ngunit hindi kailanman ang napiling koneksyon o mga kredensyal. Ibinibigay ng pag-renew at pag-release ang generation sa JSON body:

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

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

Maaaring tahasang humiling ang aktibong may-ari ng lease ng metadata sa pagpapakita na ligtas sa privacy para sa kasalukuyan nitong binding:

{ "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"
  }
}

Ang opt-in na status action na ito ay nililimitahan ng opaque na may-ari, napatotohanang pinamamahalaang API key, at eksaktong aktibong generation sa iisang transaksyon sa database. Ang displayName ay ang naka-trim na naka-configure na pangalan lamang ng koneksyon; ito ay null kapag walang umiiral na ligtas at naka-configure na pangalan. Hindi kailanman ipinapalit ng OmniRoute ang isang email o nabuong pagkakakilanlan ng account. Ang value ng provider ay isang hindi sensitibong label sa pagpapakita at hindi kailanman isang nabuong identifier ng compatible provider. Hindi kasama ang mga kredensyal, token, cookie, raw na koneksyon o mga API key id, mga hash ng may-ari, mga fencing secret, at panloob na data sa pagruruta.

Ang mga lookup na may maling key, maling may-ari, lipas na generation, nawawala, nag-expire, na-release, at napawalang-bisa ay pawang nagbabalik ng parehong error na 409 LEASE_FENCE_STALE nang walang metadata ng koneksyon. Ang client na nakatanggap ng tugon para sa paghihintay ng kapasidad ay walang aktibong binding na maaaring siyasatin. Kapag inililipat ng pagruruta ang isang aktibong lease, nananatiling valid ang parehong generation at atomikong ibinabalik ng status ang bagong binding, at hindi kailanman ang luma. Nananatiling hindi nagbabago ang mga umiiral na client dahil pinananatili ng mga tugon sa pagkuha, pag-renew, pag-release, at paghihintay ang dati nilang mga anyo.

Hindi binabago ng kontratang ito ng server ang stock na OpenAI Codex /status. Kasalukuyang iniuulat ng stock na Codex ang model provider nito at built-in na estado ng pagpapatotoo/account ngunit hindi nito nire-render ang arbitraryong metadata ng account ng custom provider; dapat tawagin ng isang integrasyon ng client sa hinaharap ang action na ito at magpasya kung paano ipapakita ang connection.displayName.

Pagkatapos, ibinibigay ng bawat pinamamahalaang kahilingan sa inference ang parehong control header:

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

Kaagad na nililimitahan ang eksaktong may-ari, generation, aktibong koneksyon, at napatotohanang API key bago ang bawat sinusuportahang upstream na pagtatangka. Nabibigo ang muling paggamit sa may-ari at generation gamit ang ibang key kahit pinapahintulutan ng key na iyon ang parehong koneksyon. Hindi pine-persist, nila-log, pinananatili sa snapshot ng kahilingan, o ipinapasa upstream ang mga raw na may-ari.

Ang pansamantalang kompetisyon sa kapasidad ay nagbabalik ng HTTP 429 na may Retry-After at:

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

Nangangahulugan lamang ang tugon na ito na hindi bakante ang karaniwang hanay ng mga kwalipikadong koneksyon at ang bawat libreng kandidato ay hawak ng aktibong lease ng ibang may-ari. Pinananatili ng mga hindi sinusuportahang modelo/provider, hindi pagtutugma ng patakaran, cooldown, quota, kalagayan, at iba pang karaniwang pagkabigo sa pagiging kwalipikado ang kanilang mga umiiral na tugon ng OmniRoute.

x-omniroute-compression

Override ng compression plan sa bawat kahilingan. Ito ang may pinakamataas na precedence—nangingibabaw sa override ng routing-combo, aktibong profile, auto-trigger, at Default ng panel. Mga value:

Value	Epekto
off	Walang compression para sa kahilingang ito.
default	Ang Default profile na nagmula sa panel (binabalewala ang aktibong profile).
engine:<id>	Isang engine kapag naka-enable, hal. engine:rtk.
<combo>	Isang pinangalanang combo, unang itinutugma ayon sa pangalan (case-insensitive), pagkatapos ay ayon sa id.

Mga tala:

• Binabalewala ang mga hindi kilalang value (hindi kailanman tinatanggihan ang kahilingan); babalik ang resolution sa normal na precedence ng operator.
• Kung magkakapareho ang pangalan ng maraming combo, ipasa ang id ng combo para sa deterministikong pagtutugma.
• Hindi maaaring piliin ayon sa pangalan ang isang combo na may pangalang off o default (unang binibigyang-kahulugan ang mga keyword na iyon); tukuyin ang ganitong combo gamit ang id nito.
• Ang pangunahing switch ng compression ay isang mahigpit na gate: kapag naka-disable ang compression sa pangkalahatan, hindi ito maaaring i-enable ng header na ito.

Ibinabalik sa response header ang inilapat na plan:

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

kung saan ang <source> ay isa sa request-header, routing-override, active-profile, auto-trigger, default, o off.

---

Mga Embedding

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

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

Mga available na provider: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

Ang mga catalog id ay provider/model (halimbawa: jina-ai/jina-embeddings-v5-omni-small). Nalulutas din ang mga bare na Jina model id na lumalabas sa registry (halimbawa, jina-embeddings-v5-text-small, jina-reranker-v3.5). Ginagamit muna ng Jina embed/rerank/classify/segment ang mga credential na jina-ai sa dashboard; fallback lamang ang JINA_AI_API_KEY kapag walang dashboard key. Ang jina-reader card ay para lamang sa Reader / r.jina.ai (POST /v1/web/fetch) at hindi kailanman naghahatid ng mga embedding o rerank.

Ang mga registry model na nag-a-advertise ng multimodal support ay tumatanggap din ng hanggang 32 provider-neutral na structured item. Ang mga uri ng media item ay text, image, audio, video, at document. Ang kanilang media source ay alinman sa {"type":"url","url":"https://..."} o {"type":"base64","data":"...","media_type":"..."}.

Ang Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano, at ang family alias na jina-ai/jina-embeddings-v5-omni → omni-small) ay tumatanggap din ng mga native na EmbeddingsV5Request doc ng Jina at ipinapasa ang mga ito nang buo sa 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,..." }]
    }
  ]
}

Ang mga native na value na { image | audio | video | pdf } ay maaaring pampublikong HTTPS URL, data: URI, o raw base64. Hindi ginagawang string ng OmniRoute ang mga object na iyon o kinukuha ang mga native na image URL — ang Jina mismo ang kumukuha ng pampublikong media. Ipinapasa ang mga karagdagang Jina field (task, normalized, truncate, embedding_type). Tinatanggihan pa rin ng mga text-only na Jina SKU ang mga doc na hindi text.

Mga limitasyon sa seguridad at transport:

• Dapat pampublikong HTTPS ang mga remote media URL. Kinukuha sa server-side ang mga canonical na {type,source:url} item (muling pag-validate ng redirect, timeout, mga limitasyon sa laki, pampublikong DNS, pag-pin ng koneksyon) at ini-inline bago ang provider call. Ang mga Jina-native na {image:"https://..."} item ay ipinapasa nang walang pagbabago pagkatapos ng parehong pagsusuri sa pampublikong HTTPS; kinukuha ng Jina ang URL.
• Limitado sa 8 MiB na decoded data bawat item at 16 MiB na decoded data sa buong request ang inline base64 media.

Pagsasalin para sa provider (ang mga canonical na item ay hindi kailanman ipinapasa nang walang pagbabago):

• Mga Jina multimodal model: ang bawat top-level na item ay nagiging isang object na may key ayon sa modality (text / image / audio / video / pdf) gamit ang mga data URI para sa inline media; isang vector bawat top-level na item.
• Pamilya ng Gemini Embedding 2: ang isang top-level na array ay nagiging iisang native na models/{model}:embedContent request na may content.parts (text o inline_data).
• Tinatanggihan ng mga unknown/dynamic model na walang tahasang modality metadata ang structured input gamit ang 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"
}

Nagbabalik ng HTTP 400 ang mga hindi suportadong kumbinasyon ng model/modality sa halip na i-coerce ang item. Ang mga non-input extension field sa mga legacy na string/token request ay patuloy na ipinapasa nang walang pagbabago.

# Ilista ang lahat ng embedding model
GET /v1/embeddings

---

Pagbuo ng Larawan

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"
}

Mga available na provider: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (lokal), ComfyUI (lokal).

# Ilista ang lahat ng modelo ng larawan
GET /v1/images/generations

---

OCR ng Dokumento

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"
  }
}

Pinipili ng model ang OCR provider sa pamamagitan ng prefix na provider/model; ang isang model id na walang prefix (hal. mistral-ocr-latest) ay iniuugnay sa nakarehistrong provider nito, at kung hindi ibinigay ang model, gagamitin bilang default ang Mistral (mistral-ocr-latest). Mga nakarehistrong provider (open-sse/config/ocrRegistry.ts):

Provider id	Model id	Value ng model	Mga Tala
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (o mistral-ocr-latest lamang)	Synchronous — direktang ibinabalik ang tugon mula sa iisang upstream call.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Asynchronous na upstream (analyze + poll) — tingnan sa ibaba.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Synchronous, sa pamamagitan ng partner endpoint na openapi/chat/completions ng Vertex AI — tingnan sa ibaba para sa auth/URL.

Tumutugon ang lahat ng tatlong provider gamit ang parehong body na may format ng Mistral:

{
  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Daloy ng pag-poll sa Azure Document Intelligence

Asynchronous ang analyze API ng Azure Document Intelligence: nagbabalik ang paunang request ng Operation-Location header sa halip na body, at kailangang paulit-ulit na i-poll ang resulta. Ang handler (open-sse/handlers/ocr.ts) ay nagpo-poll sa URL na iyon bawat segundo nang hanggang 30 pagtatangka, agad na nabibigo (hindi nagpapatuloy sa pag-poll) kapag may poll response na hindi ok o status na "failed", at nagbabalik ng 504 kung tumatakbo pa rin ang operasyon matapos maubos ang nakalaang bilang ng pagtatangka. Ang panghuling tugon ng Azure ay ina-normalize sa parehong format na pages/markdown na ginagamit ng Mistral bago ito ibalik sa caller, kaya hindi kailangang magkaroon ng espesyal na pagproseso ang client code para sa provider.

Authentication at endpoint resolution ng Vertex AI DeepSeek OCR

Muling ginagamit ng vertex-deepseek-ocr ang parehong authentication ng Vertex AI na sinusuportahan na ng OmniRoute para sa traffic ng chat/larawan (open-sse/executors/vertex.ts): ang API key ng koneksyon ay maaaring isang Service Account JSON credential (ipinagpapalit para sa panandaliang OAuth access token sa pamamagitan ng JWT-bearer flow) o isang nagawa nang OAuth access token na ginagamit nang walang pagbabago. Ang upstream endpoint URL ay ang generic na partner endpoint na openapi/chat/completions ng Vertex, na binubuo mula sa project at region ng koneksyon — palaging nangingibabaw ang tahasang providerSpecificData.project/providerSpecificData.region; kung wala nito, kinukuha ang project mula sa project_id ng Service Account JSON at ang default na region ay us-central1. Isinasagawa ang parehong resolution sa open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), na ginagamit ng src/app/api/v1/ocr/route.ts bago ipadala sa handleOcr.

---

Ilista ang mga Modelo

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

→ Ibinabalik ang lahat ng chat, embedding, at image model + mga combo sa format ng OpenAI

Mga prefix ng model id (?prefix=)

Karamihan sa mga modelo ay inilalathala sa ilalim ng isang provider prefix. Ang prefix na makukuha mo ay kinokontrol ng MODELS_CATALOG_PREFIX_MODE feature flag, at maaaring i-override sa bawat request gamit ang isang query parameter — kapaki-pakinabang para sa client na nais ng malinis na listahan nang hindi binabago ang setting sa buong server para sa lahat:

GET /v1/models?prefix=alias        # isang id bawat modelo — ang maikling alias prefix
GET /v1/models?prefix=dual         # parehong anyo (default ng server)
GET /v1/models?prefix=canonical    # ang buong provider-id prefix lamang

Mode	Inilalabas	Mga Tala
dual	cc/claude-sonnet-4-6 at claude/claude-sonnet-4-6	Default. Parehong nagru-route ang dalawang id sa iisang modelo; pinanatili ito upang patuloy na gumana ang mga configuration ng client na naka-hardcode sa alinmang anyo. Halos dinodoble nito ang catalog.
alias	cc/claude-sonnet-4-6	Isang entry bawat modelo. Inilalabas pa rin ng mga provider na walang natatanging alias ang kanilang entry, kaya walang nawawala.
canonical	claude/claude-sonnet-4-6	Isang entry bawat modelo sa ilalim ng buong provider-id prefix. Inilalabas din dito ng mga provider na walang natatanging alias (hal. antigravity/…, agy/…) ang kanilang nag-iisang id, kaya walang nawawala.

Makikilala rin ang isang mirror na nasa dual mode kahit wala ang query parameter: mayroon itong parent field na tumuturo sa pangunahing id.

Ang mga client na nagre-render ng model picker ay dapat humiling ng ?prefix=alias — ito ang ginagawa ng OmniCopilot VS Code extension.

Mga variant ng modelo na walang thinking

Para sa mga Claude model na may kakayahang mag-thinking, naglalathala rin ang /v1/models ng isang no-thinking variant na ang id ay may prefix na claude-3-omniroute-no-thinking/:

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

Kapag pinili ang id na ito (hal. sa isang Claude Code config na palaging naglalakip ng thinking block), ibinabalik ito sa tunay na <provider>/<model> nang naka-suppress ang reasoning — thinking:{type:"disabled"} sa /v1/messages path, o inaalis ang mga reasoning/reasoning_effort field sa /v1/chat/completions path. Inililista lamang ang variant para sa mga Claude-family model na sumusuporta sa thinking at sumusunod sa disabled (kaya hindi kasama, halimbawa, ang mga adaptive-only model na tumatanggi sa disabled). Maaaring sapilitang i-on o i-off ng mga operator ang variant para sa bawat modelo sa pamamagitan ng ModelSpec.noThinkingAlias.

---

Manifest ng Provider Plugin

GET /api/v1/provider-plugin-manifest

Ibinabalik ang JSON-safe na manifest ng provider plugin na ginagamit ng Bifrost, CLIProxyAPI, at mga sidecar router sa hinaharap. Binubuo ang tugon mula sa TypeScript provider registry at sadyang hindi isinasama ang mga OAuth client secret, runtime environment resolution, executor function, request header, at account data.

Gamitin ang endpoint na ito kapag tumatakbo ang isang sidecar nang out-of-process at hindi nito direktang ma-import ang open-sse/config/providerPluginManifestRegistry.ts.

---

Mga Endpoint para sa Compatibility

Pamamaraan	Path	Format
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 (pag-edit/inpaint)
POST	/v1/videos/generations	Pagbuo ng video na istilong OpenAI
POST	/v1/music/generations	Pagbuo ng musika na istilong OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (nagbabalik ng audio body)
POST	/v1/rerank	Rerank na istilong Cohere/Voyage
POST	/v1/classify	Jina classify (api.jina.ai)
POST	/v1/segment	Jina segmenter (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 catalog alias
GET	/api/v1/vscode/{token}/models	OpenAI models alias
POST	/api/v1/vscode/{token}/chat/completions	OpenAI tokenized alias
POST	/api/v1/vscode/{token}/responses	OpenAI Responses tokenized alias
POST	/api/v1/vscode/{token}/api/chat	Ollama tokenized alias
GET	/api/v1/vscode/{token}/api/tags	Ollama tags tokenized alias

Iisa ang anyo ng lahat ng POST route: Bearer your-api-key + JSON body na na-validate ng Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, atbp., tingnan ang src/shared/validation/schemas.ts). Nagbabalik ng 4xx kapag nabigo ang schema validation.

Para sa mga client na hindi makapaglakip ng Authorization: Bearer ..., tumatanggap din ang OmniRoute ng mga API key sa URL sa pamamagitan ng query-string compatibility (?token=..., ?apiKey=..., ?api_key=..., ?key=...) o ng mga nakalaang /api/v1/vscode/{token}/... endpoint na nakadokumento sa ibaba.

# Rerank
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina classify (mga kredensyal ng Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina segmenter
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina search (s.jina.ai; mga provider alias: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Mga moderation
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — nagbabalik ng audio/mpeg (o hiniling na format) na body
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Pag-edit ng image (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Pagbuo ng video / musika (model id na may provider prefix)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Mga Nakalaang Provider Route

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

Awtomatikong idinaragdag ang provider prefix kung nawawala ito. Nagbabalik ng 400 ang mga hindi nagtutugmang model.

---

Files API

Endpoint ng mga file na compatible sa OpenAI para sa batch na input/output at mga pag-upload ayon sa layunin ng file.

Paraan	Path	Paglalarawan
POST	/v1/files	Mag-upload ng file (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — maximum na 512 MiB
GET	/v1/files	Ilista ang mga file para sa napatunayang API key
GET	/v1/files/[id]	Kunin ang metadata ng file
DELETE	/v1/files/[id]	Mag-delete ng file
GET	/v1/files/[id]/content	I-stream pabalik ang raw na nilalaman ng file

Awtorisasyon: Bearer API key — ang saklaw ng mga file ay ayon sa bawat API key sa pamamagitan ng getApiKeyRequestScope. Ang isang key ay makakakita, makakapag-download, at makakapag-delete lamang ng sarili nitong mga file; binabasa ng dashboard session na walang key ang buong instance; ang file na walang may-ari (anonymous o in-upload sa dashboard session) ay ipinagkakait sa bawat caller na hindi session. Tinatanggihan ng GET /v1/files ang isang anonymous na caller — at ang ibinigay na key na hindi ma-resolve — gamit ang 401 kahit na REQUIRE_API_KEY=false, sa halip na ilista ang mga file ng bawat tenant (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches API

Batch processing na compatible sa OpenAI.

Paraan	Path	Paglalarawan
POST	/v1/batches	Gumawa ng batch — bina-validate ang body ng v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Ilista ang mga batch
GET	/v1/batches/[id]	Kunin ang status ng batch + request_counts
DELETE	/v1/batches/[id]	Mag-delete ng natapos/nabigong batch
POST	/v1/batches/[id]/cancel	Kanselahin ang batch na kasalukuyang pinoproseso

Awtorisasyon: Bearer API key. Ang saklaw ng mga batch ay ayon sa bawat API key sa ilalim ng parehong tatlong-posibleng panuntunan gaya ng mga file: sariling key lamang, saklaw ang buong instance para sa dashboard session, ipinagkakait sa bawat caller na hindi session ang mga record na null ang may-ari (pagkuha, pag-delete, pagkansela, at ang pagsusuri sa input_file_id sa paggawa). Tinatanggihan ng GET /v1/batches ang isang anonymous na caller gamit ang 401 kahit na REQUIRE_API_KEY=false.

---

Search API

Abstraksiyon ng provider ng web/search (Tavily, Brave, Exa, Serper, atbp.).

Pamamaraan	Path	Paglalarawan
GET	/v1/search	Ilista ang mga naka-configure na provider ng paghahanap + mga kakayahan
POST	/v1/search	Magpatakbo ng query sa paghahanap — bina-validate ng v1SearchSchema ang body, sumusuporta sa caching/coalescing
GET	/v1/search/analytics	Mga istatistika ng hit/latency/cache para sa bawat provider

Auth: Bearer API key (extractApiKey + isValidApiKey). Ipinapatupad ang patakaran sa paghahanap sa pamamagitan ng enforceApiKeyPolicy.

---

Web Fetch API

Kumuha ng content mula sa isang URL sa pamamagitan ng naka-configure na web-fetch provider (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Pamamaraan	Path	Paglalarawan
POST	/v1/web/fetch	Kunin/i-scrape ang isang URL — bina-validate ng v1WebFetchSchema ang body

Auth: Bearer API key (extractApiKey + isValidApiKey). Ipinapatupad ang patakaran sa pamamagitan ng enforceApiKeyPolicy.

Fallback na isinasaalang-alang ang quota (#8297): kapag walang ibinigay na tahasang provider, ang pool (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) ay sinusundan ayon sa nakapirming pagkakasunod-sunod ng priyoridad (fill-first) — nilalaktawan ang isang naka-configure ngunit nalilimitahan ang rate na provider sa halip na agad na ihinto ang request, at ang isang maaaring subukang muli/quota na upstream failure (HTTP 429 palagi; 402/403 para sa mga libreng tier ng Firecrawl/Tavily/TinyFish na may istilong quota — hindi para sa Jina Reader, at hindi kailanman para sa karaniwang 400 bad request) ay lumilipat sa susunod na hindi pa nasusubukang provider na may credential sa oras ng request. Kapag naubos na ang bawat provider sa pool, nagbabalik ang endpoint ng iisang 429 (na may Retry-After header) sa halip ng dating generic na 400. Kapag tahasang hiniling ang isang provider, walang tahimik na fallback — inilalabas ng tahasang provider na nalilimitahan ang rate o pumapalya ang sarili nitong error (429 kung nalilimitahan ang rate, kung hindi ay ang upstream status).

---

WebSocket Streaming

GET /v1/ws?handshake=1

Bina-validate ang isang WebSocket upgrade handshake at ibinabalik ang mga halimbawang mensahe ng wire protocol (request, cancel). Ang mga aktuwal na WS frame ay pinangangasiwaan ng kasamang WS server sa labas ng route table ng Next.js.

Auth: Bearer API key habang isinasagawa ang handshake.

Responses API sa pamamagitan ng WebSocket (codex lamang)

# Parehong host:port ng HTTP API (default 20128); i-upgrade ang koneksyon:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (o: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Ang unang frame ay DAPAT na response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Ang proxy ng Responses-API-over-WebSocket ay nakakonekta eksklusibo sa codex (ChatGPT backend). Nakikinig ito sa parehong port ng API/dashboard sa mga path na /v1/responses, /responses, at /api/v1/responses. Sa unang response.create frame, nagsasagawa ito ng authentication + paghahanda sa pamamagitan ng internal na codex-responses-ws bridge, pumipili ng codex OAuth connection, at nagtu-tunnel sa wss://chatgpt.com/backend-api/codex/responses sa pamamagitan ng wreq-js transport. Tinatanggihan ang mga model na hindi codex (codex_ws_provider_required). Para sa quota-share routing, gamitin ang model: "qtSd/<group>/codex/<model>". Ipinatupad sa app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Auth: Bearer API key habang isinasagawa ang handshake. Ang kasamang HTTP server (server-ws.mjs) ay dapat ang aktibong entrypoint (ito ang default kapag umiiral ang app/server-ws.mjs).

Model id: gamitin ang hubad na ChatGPT id (walang codex/ prefix)

Bina-validate ng OpenAI Codex CLI ang pangalan ng model sa panig ng client kapag supports_websockets = true at tinatanggihan ang mga id na may prefix ng provider gaya ng codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Ipadala ang hubad na id (hal. gpt-5.5). Codex-only ang bridge ng OmniRoute, kaya muli nitong nire-resolve ang hubad na id bilang isang codex model (resolveCodexWsModelInfo) bago mag-tunnel upstream — kahit na ang hubad na gpt-5.5 ay karaniwang iru-route sa ibang provider sa pamamagitan ng HTTP.

Pag-configure sa OpenAI Codex CLI

Ituro ang Codex CLI sa OmniRoute sa pamamagitan ng pagdaragdag ng custom na provider na may suporta sa WebSocket sa ~/.codex/config.toml (gumamit ng hiwalay na CODEX_HOME upang maiwasang mabago ang umiiral na config):

model = "gpt-5.5"                 # hubad na id — HINDI "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # walang trailing slash; awtomatikong binubuo ang WS URL (gumamit ng https/wss sa production)
wire_api = "responses"                    # ang tanging sinusuportahang value mula noong Peb 2026
supports_websockets = true                # ine-enable ang Responses-over-WS transport
env_key = "OMNIROUTE_API_KEY"             # naglalaman ng OmniRoute API key (Bearer)

export OMNIROUTE_API_KEY=sk-...           # isang OmniRoute API key (anumang key kung REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

Ina-upgrade ng CLI ang base_url + /responses sa isang WebSocket at itu-tunnel ito ng OmniRoute sa napiling codex OAuth connection. Na-validate nang end-to-end laban sa lokal na server: Nagbabalik ang ChatGPT ng codex.rate_limits + response.created at ini-stream ang completion.

---

Mga Quota at Pag-uulat ng mga Isyu

Paraan	Path	Paglalarawan
GET	/v1/quotas/check	Paunang i-validate ang quota para sa isang provider + accountId bago mag-isyu ng nakarehistrong key
POST	/v1/issues/report	Mag-ulat sa GitHub ng pagkabigo sa quota/pag-isyu ng key (nangangailangan ng GITHUB_ISSUES_REPO + token)

Auth: Bearer API key (isAuthenticated).

---

Pansariling paggamit (/api/usage/om-usage)

Maaaring basahin ng anumang API key ang sarili nitong paggamit at mga quota — walang management auth. Ito ang endpoint na ginagamit ng isang client (CLI, ang OmniCopilot panel) upang ipakita sa may-ari ng key ang kanyang gastos.

# Text na anyo (ang makasaysayang kontrata — plain text para sa isang terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Nakabalangkas na anyo — ang ginagamit ng isang UI
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Dapat naka-enable ang allowUsageCommand sa key (naka-off bilang default — itinatakda ito ng API-key manager ng dashboard para sa bawat key). Kung wala ito, sasagot ang endpoint ng 403.

Nagbabalik ang ?format=json ng isang natatanging hugis upang hindi kailanman magbasa ang tumatawag ng isang field ng data mula sa isang pagtanggi. Kapag matagumpay:

{
  "allowed": true,
  // naroroon lamang kapag pinili ng key ang mga limitasyon sa paggamit kada key (araw-araw/lingguhang USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // ang snapshot ng napiling quota ng provider, o null kapag wala pang naka-cache:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // snapshot ng bawat koneksyon, upang ma-render ng isang UI ang ilang provider nang magkatabi:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Kapag tinanggihan (401 maling key / 403 hindi pinapayagan), ibinabalik ng parehong route ang { "allowed": false, "error": { "message": "…" } } — ang umiiral ngunit walang laman na personal/provider (pinapayagan ang key, wala pang nakuhang impormasyon) ay ibang estado mula sa pagtanggi, at ang JSON na anyo lamang ang nakapaghihiwalay sa mga ito.

Auth: sariling Bearer API key ng tumatawag, na bina-validate gamit ang isValidApiKey — hindi ito ang management surface (/api/keys/…), na nananatiling protektado ng requireManagementAuth.

---

Semantic Cache

# Kunin ang mga estadistika ng cache
GET /api/cache/stats

# I-clear ang lahat ng cache
DELETE /api/cache/stats

Halimbawa ng response:

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

Epekto sa latency

Inihahatid ng isang semantic cache HIT ang response mula sa cache nang walang upstream call, kaya halos zero ang iniulat na X-OmniRoute-Response-Latency (anuman ang orihinal na upstream latency). Dapat suriin ng mga client na sensitibo sa latency (benchmarking, p50/p99 monitoring) ang response header na X-OmniRoute-Cache-Latency:

Value	Kahulugan
synthetic	Inihatid ang response mula sa cache; hindi tunay na upstream time ang latency
(wala)	Response mula sa tunay na upstream call

Pag-bypass ng cache kada key

Maaaring hindi gumamit ng semantic cache reads ang mga API key sa pamamagitan ng cacheDefaultMode:

Value	Gawi
legacy	Normal na gawi ng cache (default)
bypass	Ganap na laktawan ang cache lookup; palaging tumawag sa upstream

Itakda sa paggawa ng key (POST /api/keys) o pag-update (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Pag-bypass kada request

Maaaring i-bypass ng anumang request ang cache anuman ang mga setting ng key:

X-OmniRoute-No-Cache: true

---

Dashboard at Pamamahala

Ang mga ruta ng pamamahala (/api/* maliban sa pampublikong auth/login) ay hindi pinahihintulutan ng mga karaniwang inference API key. Para sa mga pamilya ng kredensyal, saklaw, at mga halimbawa ng curl: Authentication sa Pamamahala.

Authentication

Endpoint	Paraan	Paglalarawan
/api/auth/login	POST	Mag-login
/api/auth/logout	POST	Mag-logout
/api/settings/require-login	GET/PUT	I-toggle kung kailangan ang login

Pamamahala ng Provider

Endpoint	Paraan	Paglalarawan
/api/providers	GET/POST	Ilista / gumawa ng mga provider
/api/providers/[id]	GET/PUT/DELETE	Pamahalaan ang isang provider
/api/providers/[id]/test	POST	Subukan ang koneksyon ng provider
/api/providers/[id]/models	GET	Ilista ang mga modelo ng provider
/api/providers/validate	POST	Patunayan ang config ng provider
/api/providers/bulk	POST	Maramihang magdagdag ng mga API key para sa ISANG provider
/api/providers/import	POST	Mag-import ng magkakaibang LISTAHAN ng provider mula sa na-parse na CSV/JSON file (#6836); mga resulta ng bahagyang pagkabigo sa bawat row
/api/provider-nodes*	Iba-iba	Pamamahala ng node ng provider
/api/provider-models	GET/POST/PATCH/DELETE	Mga custom na modelo (magdagdag, mag-update, magtago/magpakita, magtanggal)

Mga Daloy ng OAuth

Endpoint	Paraan	Paglalarawan
/api/oauth/[provider]/[action]	Iba-iba	OAuth na partikular sa provider

Routing at Config

Endpoint	Paraan	Paglalarawan
/api/models/alias	GET/POST	Mga alias ng modelo
/api/models/catalog	GET	Lahat ng modelo ayon sa provider + uri
/api/combos*	Iba-iba	Pamamahala ng combo
/api/keys*	Iba-iba	Pamamahala ng API key
/api/pricing	GET	Pagpepresyo ng modelo

Paggamit at Analytics

Endpoint	Paraan	Paglalarawan
/api/usage/history	GET	Kasaysayan ng paggamit
/api/usage/logs	GET	Mga log ng paggamit
/api/usage/request-logs	GET	Mga log sa antas ng kahilingan
/api/usage/[connectionId]	GET	Paggamit kada koneksyon
/api/usage/token-limits	GET/POST/DELETE	Mga badyet sa limitasyon ng token kada API key
/api/usage/model-latency-stats	GET	Patuloy na pinagsama-samang latency kada provider/model (avg/p50/p95/p99, antas ng tagumpay); mga filter: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Buod ng kalagayan ng prompt cache sa call_logs — ratio ng pagsulat/pagbasa, distribusyon ng laki ng pagsulat na p50/p90/p99, konsentrasyon ng mabibigat na pagsulat, paghahati kada model, at hatol na healthy/degraded/thrash/no-data; mga query param na range (1h|24h|7d|30d, default na 24h) at opsyonal na model (#8827)

Mga Setting

Endpoint	Paraan	Paglalarawan
/api/settings	GET/PUT/PATCH	Mga pangkalahatang setting
/api/settings/proxy	GET/PUT	Configuration ng network proxy
/api/settings/proxy/test	POST	Subukan ang koneksyon sa proxy
/api/settings/ip-filter	GET/PUT	Allowlist/blocklist ng IP
/api/settings/thinking-budget	GET/PUT	Mode ng muling pagsulat sa kahilingan para sa thinking/reasoning (passthrough / auto-strip / custom / adaptive). Hiwalay sa compression. Tingnan ang THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Pandaigdigang system prompt
/api/settings/compression	GET/PUT	Pandaigdigang configuration ng compression
/api/settings/purge-request-history	POST	Burahin ang mga row ng log ng kahilingan at mga lokal na artifact ng call log

Konteksto at Compression

Endpoint	Paraan	Paglalarawan
/api/compression/preview	POST	I-preview ang off/lite/standard/aggressive/ultra/RTK/stacked na compression
/api/compression/language-packs	GET	Ilista ang mga available na Caveman language pack
/api/compression/rules	GET	Ilista ang metadata ng mga panuntunan ng Caveman
/api/context/caveman/config	GET/PUT	Alias ng mga setting na partikular sa Caveman
/api/context/rtk/config	GET/PUT	Mga setting na partikular sa RTK, kabilang ang mga custom na filter at pagpapanatili ng raw output
/api/context/rtk/filters	GET	Katalogo ng RTK filter at mga diagnostic ng custom na filter
/api/context/rtk/test	POST	Patakbuhin ang RTK preview/test gamit ang isang text payload
/api/context/rtk/raw-output/[id]	GET	Basahin ang pinanatiling na-redact na raw output gamit ang pointer id
/api/context/combos	GET/POST	Ilista/lumikha ng compression combo
/api/context/combos/[id]	GET/PUT/DELETE	Detalye/pag-update/pagtanggal ng compression combo
/api/context/combos/[id]/assignments	GET/PUT	Italaga ang mga compression combo sa mga routing combo
/api/context/analytics	GET	Alias ng analytics ng compression

Pagsubaybay

Endpoint	Paraan	Paglalarawan
/api/sessions	GET	Pagsubaybay sa mga aktibong session
/api/rate-limits	GET	Mga rate limit para sa bawat account
/api/monitoring/health	GET	Pagsusuri sa kalagayan + buod ng provider (catalogCount, configuredCount, activeCount, monitoredCount). Kabilang sa management view ang credentialHealth: mga scalar ng probe cache, failedConnections kapag failed>0, at staleDbNonOkCount (sticky na test_status ng SQLite, hindi ang gauge). Tingnan ang MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Mga estadistika ng cache / i-clear
/api/modality-bridge/stats	GET	Mga nasa memory na attempts, mga tagumpay/bridged, mga pagkabigo, mga cache hit, totalLatencyMs, latencySamples, averageLatencyMs na nakabatay sa bilang ng sample, at oras ng huling paggamit (nire-reset sa pag-restart; management auth)
/api/modality-bridge/video/runtime	GET	Mahigpit na trusted-loopback check bago ang management auth/probe; na-sanitize na availability at mga bersyon ng FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extract	POST	Internal na authenticated trusted-loopback byte broker; 50 MiB na input, may limitasyong queue/32 MiB na output, 503 kapag puno ang kapasidad, 499 kapag nadiskonekta, 504 kapag lumampas sa deadline; hindi isang pampublikong upload API

Backup at Pag-export/Pag-import

Endpoint	Paraan	Paglalarawan
/api/db-backups	GET	Ilista ang mga available na backup
/api/db-backups	PUT	Gumawa ng manual na backup
/api/db-backups	POST	Mag-restore mula sa isang partikular na backup
/api/db-backups/export	GET	I-download ang database bilang .sqlite file
/api/db-backups/import	POST	Mag-upload ng .sqlite file upang palitan ang database
/api/db-backups/exportAll	GET	I-download ang buong backup bilang .tar.gz archive

Pag-sync sa Cloud

Endpoint	Paraan	Paglalarawan
/api/sync/cloud	Iba-iba	Mga operasyon ng cloud sync
/api/sync/initialize	POST	Simulan ang pag-sync
/api/cloud/*	Iba-iba	Pamamahala sa cloud

Mga Tunnel

Endpoint	Paraan	Paglalarawan
/api/tunnels/cloudflared	GET	Basahin ang status ng pag-install/runtime ng Cloudflare Quick Tunnel para sa dashboard
/api/tunnels/cloudflared	POST	I-enable o i-disable ang Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Basahin ang runtime status ng ngrok Tunnel para sa dashboard
/api/tunnels/ngrok	POST	I-enable o i-disable ang ngrok Tunnel (action=enable/disable)

Mga CLI Tool

Endpoint	Paraan	Paglalarawan
/api/cli-tools/claude-settings	GET	Status ng Claude CLI
/api/cli-tools/codex-settings	GET	Status ng Codex CLI
/api/cli-tools/droid-settings	GET	Status ng Droid CLI
/api/cli-tools/openclaw-settings	GET	Status ng OpenClaw CLI
/api/cli-tools/runtime/[toolId]	GET	Pangkalahatang CLI runtime

Kasama sa mga tugon ng CLI ang: installed, runnable, command, commandPath, runtimeMode, reason.

Mga ACP Agent

Endpoint	Paraan	Paglalarawan
/api/acp/agents	GET	Ilista ang lahat ng natukoy na agent (built-in + custom) at status
/api/acp/agents	POST	Magdagdag ng custom na agent o i-refresh ang detection cache
/api/acp/agents	DELETE	Mag-alis ng custom na agent gamit ang id query param

Kasama sa tugon ng GET ang agents[] (id, name, binary, version, installed, protocol, isCustom) at summary (total, installed, notFound, builtIn, custom).

Resilience at Mga Rate Limit

Endpoint	Paraan	Paglalarawan
/api/resilience	GET/PATCH	Kunin/i-update ang request queue, connection cooldown, provider breaker, at mga setting ng paghihintay
/api/resilience/reset	POST	I-reset ang mga provider circuit breaker
/api/resilience/model-cooldowns	GET	Ilista ang mga aktibong lockout kada (provider, connection, model), inayos ayon sa natitirang oras
/api/resilience/model-cooldowns	DELETE	Alisin ang model lockout — body na {provider, model} o {all: true} upang burahin ang lahat
/api/rate-limits	GET	Status ng rate limit kada account
/api/rate-limit	GET	Global na configuration ng rate limit

Kinakailangan ng lahat ng apat na /api/resilience/* route ang management auth (requireManagementAuth). Tingnan ang Resilience (pinalawak) para sa kumpletong paghahambing ng provider breaker, connection cooldown, at model lockout.

Mga Eval

Endpoint	Paraan	Paglalarawan
/api/evals	GET/POST	Ilista ang mga eval suite / magpatakbo ng evaluation

Mga Patakaran

Endpoint	Paraan	Paglalarawan
/api/policies	GET/POST/DELETE	Pamahalaan ang mga routing policy

Pagsunod

Endpoint	Paraan	Paglalarawan
/api/compliance/audit-log	GET	Audit log ng pagsunod (huling N)

v1beta (Compatible sa Gemini)

Endpoint	Paraan	Paglalarawan
/v1beta/models	GET	Ilista ang mga model sa format ng Gemini
/v1beta/models/{...path}	POST	Gemini generateContent endpoint

Ginagaya ng mga endpoint na ito ang format ng API ng Gemini para sa mga client na nangangailangan ng native na compatibility sa Gemini SDK.

Mga Internal / System API

Endpoint	Paraan	Paglalarawan
/api/init	GET	Pagsusuri sa pagsisimula ng application (ginagamit sa unang pagpapatakbo)
/api/tags	GET	Mga tag ng model na compatible sa Ollama (para sa mga Ollama client)
/api/restart	POST	Mag-trigger ng maayos na pag-restart ng server
/api/shutdown	POST	Mag-trigger ng maayos na pag-shutdown ng server
/api/system/env/repair	POST	Ayusin ang mga environment variable ng OAuth provider

Tandaan: Ginagamit ang mga endpoint na ito sa loob ng system o para sa compatibility sa Ollama client. Karaniwang hindi direktang tinatawag ang mga ito ng mga end user.

Pag-aayos ng OAuth Environment (v3.6.1+)

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

{
  "provider": "claude-code"
}

Inaayos ang mga nawawala o sirang OAuth environment variable para sa isang partikular na provider. Ibinabalik nito ang:

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

---

Transkripsyon ng Audio

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

I-transcribe ang mga audio file gamit ang anumang naka-configure na STT provider. Pinipili ng unang segment ng path ang native na provider (openai/…, deepgram/…). Gumagamit ang mga gateway na muling nag-e-export ng modelo ng ibang vendor ng qualified id (openrouter/deepgram/nova-3).

Kahilingan:

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

Tugon:

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

Mga halimbawang model id: openai/whisper-1 (nangangailangan ng OpenAI key), openrouter/deepgram/nova-3 (nangangailangan ng OpenRouter key), deepgram/nova-3 (nangangailangan ng native na Deepgram key). Ang kahilingang deepgram/nova-3 lamang ay hindi gumagamit ng OpenRouter.

Mga sinusuportahang format: mp3, wav, m4a, flac, ogg, webm.

---

Compatibility sa Ollama

Para sa mga client na gumagamit ng format ng API ng Ollama:

# Endpoint ng chat (format ng Ollama)
POST /v1/api/chat

# Listahan ng modelo (format ng Ollama)
GET /api/tags

Awtomatikong isinasalin ang mga kahilingan sa pagitan ng mga format ng Ollama at mga internal na format.

Mga Tokenized na Alias para sa VS Code / Mga Alias na Walang Header

Gamitin ang mga alias na ito kapag hindi makapaglagay ang isang integration ng Authorization header at kailangang i-embed ang API key sa base URL.

# Alias ng catalog na OpenAI-style
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Mga alias ng chat na OpenAI-style
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Mga alias na Ollama-style
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Halimbawa:

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"}]}'

Mga tala:

• Muling ginagamit ng mga tokenized na alias ang parehong mga handler gaya ng /v1/* at /api/tags; nananatiling magkapareho ang mga anyo ng tugon.
• Piliin ang Authorization: Bearer ... hangga't sinusuportahan ng client ang mga custom na header.
• Maaaring lumabas ang mga token na nakabatay sa URL sa mga log ng reverse proxy, history ng browser, at telemetry sa labas ng OmniRoute. Ituring ang mga ito bilang opsyon para sa compatibility, hindi bilang default na paraan ng authentication.

---

Telemetry

# Kunin ang buod ng telemetry ng latency (p50/p95/p99 para sa bawat provider)
GET /api/telemetry/summary

Tugon:

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

---

Badyet

# Kunin ang katayuan ng badyet para sa lahat ng API key
GET /api/usage/budget

# Magtakda o mag-update ng badyet
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"
}

Mga tala sa schema (setBudgetSchema): kinakailangan ang apiKeyId; dapat mas mataas sa zero ang kahit isa sa dailyLimitUsd, weeklyLimitUsd, o monthlyLimitUsd. Mga opsyonal na field: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Nagbabalik ng 400 Bad Request ang lumang anyong {keyId, limit, period}.

Mga Limitasyon sa Token

Mga badyet sa token para sa bawat API key (hiwalay sa badyet na nakabatay sa USD sa itaas). Ipinapatupad nang inline sa path ng request: kapag umabot sa limit ang paggamit ng isang key sa kasalukuyang window nito, tatanggihan ang mga request gamit ang 429 Too Many Requests. Maaaring ilapat ang mga limitasyon sa isang partikular na model, isang provider, o global sa buong key; kapag maraming limitasyon ang tumugma sa isang request, ang pinakamahigpit ang mananaig.

# Ilista ang mga limitasyon sa token ng isang key (kasama ang kasalukuyang paggamit sa window)
GET /api/usage/token-limits?apiKeyId=key-123

# Gumawa o mag-update ng limitasyon sa token
POST /api/usage/token-limits
Content-Type: application/json

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

# Magtanggal ng limitasyon sa token ayon sa id
DELETE /api/usage/token-limits?id=tl-abc

Mga tala sa schema (setTokenLimitSchema): Kinakailangan ang apiKeyId at scopeType (model | provider | global). Kinakailangan ang scopeValue maliban kung global ang scopeType (hal. isang model id para sa saklaw na model, isang provider id para sa saklaw na provider). Dapat ay positibong integer ang tokenLimit (kino-convert mula sa string). Opsyonal: id (huwag isama upang gumawa, isama upang mag-update), resetInterval (daily | weekly | monthly, default na monthly), resetTime (HH:MM), enabled (default na true). Pinagyayaman ng mga tugon sa GET ang bawat limitasyon gamit ang tokensUsed, remaining, windowStart, periodStartAt, at nextResetAt. Isa itong management-class endpoint (sentral na ipinapatupad ng authz pipeline ang awtentikasyon).

Pagproseso ng Request

1. Nagpapadala ang client ng request sa /v1/*
2. Tinatawag ng route handler ang handleChat, handleEmbedding, handleAudioTranscription, o handleImageGeneration
3. Tinutukoy ang model (direktang provider/model o alias/combo)
4. Pinipili ang mga credential mula sa lokal na DB nang may pag-filter batay sa availability ng account
5. Para sa chat: sinusuri ng handleChatCore ang semantic/signature cache at tinutukoy ang mga setting ng combo compression
6. Tumatakbo ang proactive compression bago ang provider translation kapag naka-enable (lite, Caveman, RTK, o stacked)
7. Ipinapadala ng provider executor ang upstream request
8. Isinasalin pabalik ang tugon sa format ng client (chat) o ibinabalik nang walang pagbabago (embeddings/images/audio)
9. Itinatala ang paggamit, analytics ng compression, at mga log ng request
10. Inilalapat ang fallback kapag may mga error alinsunod sa mga panuntunan ng combo

Kumpletong sanggunian sa arkitektura: ARCHITECTURE.md

---

Pamamahala ng Combo

Ang mga higher-level routing combo (na naibuod na sa ilalim ng /api/combos*) ay maaari ding i-map nang 1:1 mula sa pattern ng model id, na nagbibigay-daan sa transparent na pag-redirect ng isang OpenAI-style model id patungo sa isang combo.

Paraan	Path	Paglalarawan
GET	/api/model-combo-mappings	Ilista ang lahat ng model→combo mapping
POST	/api/model-combo-mappings	Gumawa ng mapping — body: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Kunin ang isang mapping
PUT	/api/model-combo-mappings/[id]	I-update ang mga field ng isang umiiral na mapping
DELETE	/api/model-combo-mappings/[id]	Mag-alis ng mapping

Auth: management session/API key (requireManagementAuth).

---

Mga Webhook

Mga outbound na subscription sa webhook para sa mga event ng OmniRoute (pagkumpleto ng request, pagkaubos ng quota, pag-rotate ng key, atbp.).

Paraan	Path	Paglalarawan
GET	/api/webhooks	Ilista ang mga webhook (naka-mask ang mga secret bilang <prefix>...)
POST	/api/webhooks	Gumawa ng webhook — body: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Kunin ang isang webhook
PUT	/api/webhooks/[id]	I-update ang url/events/secret/description
DELETE	/api/webhooks/[id]	Alisin ang isang webhook
POST	/api/webhooks/[id]/test	Magpadala ng test payload sa URL ng webhook at ibalik ang status ng delivery

Auth: session/API key para sa pamamahala (requireManagementAuth).

---

Mga Rehistradong Key (Awtomatikong Pamamahala)

Ginagamit ng subsystem para sa awtomatikong pamamahala ng key upang mag-isyu at mag-rotate ng mga API key gamit ang isang backing provider/account, na may mga pang-araw-araw/oras-oras na quota.

Paraan	Path	Paglalarawan
GET	/api/v1/registered-keys	Ilista ang mga rehistradong key (naka-mask na prefix lamang)
POST	/api/v1/registered-keys	Mag-isyu ng bagong rehistradong key — body: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Ibinabalik ang raw key nang isang beses. Nagbabalik ng 429 kapag tinanggihan dahil sa quota.
GET	/api/v1/registered-keys/[id]	Kunin ang metadata ng isang rehistradong key (walang raw na materyal)
DELETE	/api/v1/registered-keys/[id]	Bawiin ang isang rehistradong key
POST	/api/v1/registered-keys/[id]/revoke	Tahasang endpoint para sa pagbawi (kapareho ng epekto ng DELETE)

Auth: Bearer API key (isAuthenticated). Tingnan din ang /v1/quotas/check at /v1/issues/report.

---

Protocol ng Mga Agent

Mga gawain ng cloud agent (Claude Code, Codex Cloud, OpenHands, atbp.) na isinasagawa nang malayuan para sa mga user ng OmniRoute.

Paraan	Path	Paglalarawan
GET	/api/v1/agents/tasks	Ilista ang mga gawain — opsyonal ang ?provider=, ?status=, ?limit= (1–500, default na 50)
POST	/api/v1/agents/tasks	Gumawa ng gawain — bina-validate ang body ng CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Nagbabalik ng 201 kasama ang task envelope
DELETE	/api/v1/agents/tasks?id=...	Mag-delete ng gawain
GET	/api/v1/agents/tasks/[id]	Basahin ang gawain — sini-synchronize ang pag-refresh ng status mula sa upstream cloud agent kapag nakatakda ang external_id
POST	/api/v1/agents/tasks/[id]	Aksiyong may pantukoy: {action: "approve"}, {action: "message", message}, o {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Mag-delete ng partikular na gawain ayon sa id

Auth: kinakailangan ang management auth sa bawat paraan (requireCloudAgentManagementAuth). Bago ang v3.8.0, hindi nangangailangan ng authentication ang mga ito — tingnan ang commit 588a0333 para sa breaking change.

# Gumawa ng Claude Code cloud task
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":"..."}}'

---

Mga Management Proxy

Mga outbound HTTP(S)/SOCKS proxy na maaaring italaga sa mga provider, account, o sa pangkalahatan.

Paraan	Path	Paglalarawan
GET	/api/v1/management/proxies	Ilista ang mga proxy (kapag may ?id=, isa ang ibinabalik; kapag may ?id=&where_used=1, ibinabalik ang assignment graph)
POST	/api/v1/management/proxies	Gumawa ng proxy — bina-validate ang body ng createProxyRegistrySchema
PATCH	/api/v1/management/proxies	I-update ang proxy — bina-validate ang body ng updateProxyRegistrySchema (nangangailangan ng id)
DELETE	/api/v1/management/proxies?id=...&force=1	Mag-delete ng proxy (gamitin ang force=1 upang alisin ang mga assignment)
GET	/api/v1/management/proxies/assignments	Ilista ang mga assignment — maaaring i-filter ayon sa proxy_id, scope, scope_id; ipasa ang resolve_connection_id=<id> upang tukuyin ang aktibong proxy para sa isang koneksyon
PUT	/api/v1/management/proxies/assignments	Magtalaga — bina-validate ang body ng proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Nililinis ang dispatcher cache
PUT	/api/v1/management/proxies/bulk-assign	Maramihang magtalaga — bina-validate ang body ng bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Pinagsama-samang kalagayan ng proxy (bilang ng tagumpay/pagkabigo, latency) sa loob ng isang yugto

Auth: management session/API key sa bawat route (requireManagementAuth).

Ang POST /api/v1/management/proxies/[id]/assignments at POST /api/v1/management/proxies/[id]/health sa paglalarawan ng gawain ay sineserbisyuhan ng mga flat na route na /assignments at /health na ipinapakita sa itaas — walang mga per-id na subroute sa codebase.

---

Katatagan (pinalawak)

Nagbibigay ang OmniRoute ng tatlong magkakahiwalay na mekanismo para sa mga pansamantalang pagkabigo; hinahayaan ng mga management endpoint sa ibaba ang mga operator na basahin at i-override ang mga ito:

Saklaw	Imbakan ng estado	Pagbasa	Pag-reset / pag-clear
Breaker ng provider	domain_circuit_breakers + nasa memorya	/api/monitoring/health	POST /api/resilience/reset
Cooldown ng koneksyon	rateLimitedUntil sa mga koneksyon ng provider	/api/rate-limits, /api/providers/[id]	(muling pinapagana nang lazy; i-clear sa pamamagitan ng provider PUT)
Lockout ng modelo	Registry ng availability ng modelo na nasa memorya	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

Tumatanggap ang PATCH /api/resilience ng mga override sa breaker ng provider sa ilalim ng providerBreaker.oauth at providerBreaker.apikey. Sinusuportahan ng bawat profile ang degradationThreshold, failureThreshold, at resetTimeoutMs; makikita rin ang parehong mga field sa Dashboard → Settings → Resilience.

# I-clear ang lockout ng isang modelo
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"}'

# Burahin ang lahat ng lockout
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Para sa kumpletong konseptuwal na sanggunian at mga default ng breaker: tingnan ang CLAUDE.md → "Estado ng Resilience Runtime".

---

Mga Skill

Framework ng skill para palawakin ang OmniRoute gamit ang mga custom na executable handler, kasama ang mga marketplace integration.

Paraan	Path	Paglalarawan
GET	/api/skills	Ilista ang mga naka-install na skill — maaaring i-filter ayon sa ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, may pagination
GET	/api/skills/[id]	Kunin ang isang skill
PUT	/api/skills/[id]	I-update ang skill (pangalan, paglalarawan, mode, schema, handler, mga tag)
DELETE	/api/skills/[id]	I-uninstall ang isang skill
POST	/api/skills/install	Mag-install ng skill mula sa raw manifest — body: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Ilista ang mga kamakailang execution ng skill (audit trail na may mga input/output/tagal)
GET	/api/skills/marketplace?q=...	Maghanap/listahan ng mga popular na skill mula sa SkillsMP marketplace (nangangailangan ng setting na skillsmpApiKey)
POST	/api/skills/marketplace/install	Mag-install ng skill ayon sa id mula sa SkillsMP
GET	/api/skills/skillssh?q=&limit=	Maghanap sa registry ng skills.sh
POST	/api/skills/skillssh/install	Mag-install ng skill ayon sa id mula sa skills.sh

Auth: management session/API key. Tumatanggap ang mga route sa paghahanap sa marketplace ng management auth o Bearer API key (isAuthenticated).

---

Memorya

Persistenteng imbakan ng memoryang pang-usapan/paktuwal, na nakasaklaw sa bawat API key / session.

Paraan	Path	Paglalarawan
GET	/api/memory	Ilista ang mga memorya — ?apiKeyId=, ?type=, ?sessionId=, ?q=, na may offset/limit o page/limit na pagination
POST	/api/memory	Gumawa ng memorya — body na vina-validate ng Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Kunin ang isang memorya
DELETE	/api/memory/[id]	Magtanggal ng memorya
GET	/api/memory/health	Kalagayan ng subsystem ng memorya (konektibidad ng DB, embeddings backend, katayuan ng vector index)

Awtorisasyon: management session/API key (requireManagementAuth). type enum: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (tingnan ang MemoryType sa src/lib/memory/types.ts).

---

MCP Server

May kasamang naka-embed na Model Context Protocol server ang OmniRoute na may 3 transport (stdio, SSE, streamable-http) at mga tool na may saklaw. Binabasa ng mga dashboard endpoint sa ibaba ang data ng katayuan/audit at pini-proxy ang mga HTTP transport.

Paraan	Path	Paglalarawan
GET	/api/mcp/status	Heartbeat, transport, online na katayuan, huling tawag, mga nangungunang tool, 24h na antas ng tagumpay
GET	/api/mcp/tools	Listahan ng mga MCP tool na may name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Magbukas ng SSE stream para sa SSE transport (nagbabalik ng 503 kung naka-disable ang MCP o hindi tugma ang transport)
POST	/api/mcp/sse	Magpadala ng JSON-RPC frame sa SSE transport
GET	/api/mcp/stream	Magbukas ng SSE side ng Streamable HTTP transport (mga mensaheng sinimulan ng server)
POST	/api/mcp/stream	Magpadala ng JSON-RPC frame sa Streamable HTTP transport
DELETE	/api/mcp/stream	Tapusin ang isang Streamable HTTP session
GET	/api/mcp/audit	Mag-query sa audit log — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Pinagsama-samang mga istatistika ng audit (mga kabuuan, antas ng tagumpay, karaniwang tagal, mga nangungunang tool)

Awtorisasyon: sinusunod ng mga sse/stream transport ang auth surface na partikular sa MCP (Bearer API key na may saklaw na mcp); mababasa mula sa dashboard ang mga route na status/tools/audit* (walang kinakailangang karagdagang awtorisasyon bukod sa pag-abot sa dashboard host).

Ang parehong HTTP transport ay kinokontrol ng settings.mcpEnabled at settings.mcpTransport — ang hindi pagtugma ng transport ay nagbabalik ng 400, at ang naka-disable na katayuan ng MCP ay nagbabalik ng 503.

---

Server ng A2A

Naglalantad ang OmniRoute ng A2A (Agent-to-Agent) JSON-RPC 2.0 endpoint at isang REST wrapper para sa inspeksiyon/paggamit sa dashboard.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # opsyonal maliban kung nakatakda ang OMNIROUTE_API_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}

Mga suportadong method (lahat ay nakadepende sa settings.a2aEnabled):

Method	Paglalarawan
message/send	Sinkronos na pagpapatakbo ng skill; nagbabalik ng {task, artifacts, metadata}
message/stream	Streaming SSE na pagpapatakbo ng parehong hanay ng mga skill
tasks/get	Kunin ang isang task ayon sa taskId
tasks/cancel	Kanselahin ang isang task ayon sa taskId

Mga built-in na skill: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Card ng Ahente

GET /.well-known/agent.json

Ibinabalik ang pampublikong A2A agent card (pangalan, paglalarawan, mga kakayahan, catalog ng mga skill, auth scheme) — naka-cache nang pampubliko sa loob ng 1h. Hindi kailangan ng auth.

Mga REST helper

Method	Path	Paglalarawan
GET	/api/a2a/status	Naka-enable ang A2A + mga estadistika ng task + buod ng naka-cache na agent card
GET	/api/a2a/tasks	Ilista ang mga task — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Hindi ipinatupad bilang REST helper — gumawa sa pamamagitan ng JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Kunin ang isang task
POST	/api/a2a/tasks/[id]/cancel	Kanselahin ang isang task

Auth: tumatakbo ang mga REST helper nang walang management auth (nababasa ng dashboard); ginagamit ng JSON-RPC /a2a route ang Bearer OMNIROUTE_API_KEY kung naka-configure.

---

Cloud, Mga Eval at Pagtatasa

Method	Path	Paglalarawan
POST	/api/cloud/auth	Beripikahin ang isang Bearer key at ibalik ang mga naka-mask na koneksiyon ng provider + mga model alias para sa mga cloud sync client
POST	/api/cloud/credentials/update	I-update ang mga naka-encrypt na credential para sa isang cloud-synced na provider
POST	/api/cloud/model/resolve	I-resolve ang isang logical model id sa isang kongkretong provider/model gamit ang lokal na routing table
GET	/api/cloud/models/alias	Ilista ang mga model alias ayon sa pagkakalantad sa cloud sync
GET	/api/assess	Basahin ang pinakabagong mga kategorya ng pagtatasa (bawat provider/model)
POST	/api/assess	Magpatakbo ng pagtatasa — body: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Ilista ang mga built-in na eval suite + mga pinakabagong run
POST	/api/evals	Mag-trigger ng isang eval run
POST	/api/evals/suites	Gumawa ng custom na eval suite — bina-validate ang body ng evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Kunin ang isang custom na eval suite

Auth: direktang bina-validate ng /api/cloud/auth ang isang Bearer key; nangangailangan ang iba pang /api/cloud/*, /api/evals/*, at /api/assess route ng management session/API key. Gumagamit ang /api/assess POST ng validateBody na may discriminated-union scope schema.

---

Pamamahala ng ACP (Agent Client Protocol)

bilang mga child process. Pinamamahalaan ng mga endpoint na ito ang pagtukoy sa ACP agent at pagpaparehistro ng custom agent.

Paraan	Path	Paglalarawan
GET	/api/acp/agents	Ilista ang lahat ng kilalang CLI agent (built-in + custom), kasama ang status ng pag-install, version, at binary
POST	/api/acp/agents	Magparehistro ng custom ACP agent o i-refresh ang cache — body: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} o {action: "refresh"}
DELETE	/api/acp/agents	Mag-alis ng custom ACP agent — query param: ?id=<agentId>

Halimbawa ng tugon (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: Nangangailangan ng session sa pamamahala (auth_token cookie ng dashboard) o API key na may saklaw sa pamamahala.

Tingnan ang ACP Framework para sa kumpletong detalye.

---

Analytics at Observability

Mga real-time na analytics endpoint para sa pagsubaybay sa routing, compression, at pagkakaiba-iba ng provider. Ginagamit ng mga ito ang mga page na /dashboard/analytics/*.

Analytics ng auto-routing

Paraan	Path	Paglalarawan
GET	/api/analytics/auto-routing	Pinagsama-samang estadistika ng auto-routing: kabuuang tawag, distribusyon ng strategy, distribusyon ng tier, mga nangungunang provider
GET	/api/analytics/auto-routing?days=7	Mga estadistika ayon sa saklaw ng oras (default na 24h)

Halimbawa ng tugon:

{
  "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 }
  ]
}

Analytics ng compression

Paraan	Path	Paglalarawan
GET	/api/analytics/compression	Pinagsama-samang estadistika ng compression: mga natipid na token, porsiyento ng natipid, distribusyon ng mode, paggamit ng engine

Halimbawa ng tugon:

{
  "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
  }
}

Pagsubaybay sa pagkakaiba-iba ng provider

Paraan	Path	Paglalarawan
GET	/api/analytics/diversity	Pagsubaybay sa pagkakaiba-iba batay sa Shannon entropy: pinipigilan ang mga single point of failure sa pamamagitan ng pagsukat sa pagkakalat ng provider

Halimbawa ng tugon:

{
  "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"]
}

Auth: Nangangailangan ng session sa pamamahala o API key na may saklaw sa pamamahala.

---

Mga Operasyon ng Admin

Mga endpoint na para lamang sa admin para sa pamamahala ng operasyon.

Paraan	Path	Paglalarawan
GET	/api/admin/concurrency	Basahin ang kasalukuyang mga limitasyon sa concurrency (pangkalahatan + bawat provider)
POST	/api/admin/concurrency	I-update ang mga limitasyon sa concurrency — body: {global?: number, perProvider?: Record<string, number>}

Awtorisasyon: Nangangailangan ng session sa pamamahala na may saklaw na admin.

---

Pamamahala ng mga CLI Tool

Pamahalaan ang mga CLI tool na nagsasama sa OmniRoute (antigravity, chipotle, commandCode, devin-cli, atbp.). Tingnan ang Sanggunian ng Provider para sa kumpletong listahan.

Paraan	Path	Paglalarawan
GET	/api/cli-tools/all-statuses	Katayuan ng lahat ng CLI tool (naka-install, bersyon, huling nakita)
GET	/api/cli-tools/status	Mga detalye ng katayuan para sa isang CLI tool (?tool= query)
POST	/api/cli-tools/apply	Isulat ang nabuong config ng tool (nagbibigay ang dryRun ng preview; 422 + containerEphemeralTarget kapag nasa container; itinatala ng migration ang legacy na Codex YAML)
GET	/api/cli-tools/backups	Ilista ang mga backup ng configuration ng CLI tool
POST	/api/cli-tools/backups	Gumawa ng backup ng lahat ng configuration ng CLI tool
POST	/api/cli-tools/backups	I-restore: nire-restore ng parehong endpoint na may {tool, backupId} sa body ang backup na iyon
GET	/api/cli-tools/antigravity-mitm	Katayuan ng Antigravity MITM proxy (ang "antigravity-mitm" CLI tool)
POST	/api/cli-tools/antigravity-mitm/alias	I-configure ang mga alias ng antigravity-mitm

Awtorisasyon: Nangangailangan ng session sa pamamahala.

---

Mga Kasanayan ng Agent

Pamahalaan ang mga kasanayan ng AI agent (katulad ng mga custom GPT ng OpenAI ngunit para sa mga agent).

Paraan	Path	Paglalarawan
GET	/api/agent-skills	Ilista ang lahat ng kasanayan ng agent (built-in + custom)
GET	/api/agent-skills/[id]	Kunin ang isang partikular na kasanayan ng agent
POST	/api/agent-skills	Gumawa ng custom na kasanayan ng agent — body: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	I-update ang custom na kasanayan ng agent
DELETE	/api/agent-skills/[id]	Tanggalin ang custom na kasanayan ng agent
GET	/api/agent-skills/[id]/raw	Kunin ang raw na prompt + metadata (walang pagpapatupad)
POST	/api/agent-skills/generate	Bumuo gamit ang AI ng bagong kasanayan mula sa paglalarawan sa natural na wika

Awtorisasyon: Nangangailangan ng session sa pamamahala o API key na may saklaw sa pamamahala.

---

Pamamahala ng Cache

Pamahalaan ang semantic cache at reasoning cache.

Paraan	Path	Paglalarawan
GET	/api/cache	Pangkalahatang-ideya ng cache: kabuuang entry, hit rate, laki sa disk
GET	/api/cache/entries	Ilista ang mga naka-cache na entry (may pagination)
DELETE	/api/cache/entries	Tanggalin ang mga entry sa cache (i-filter ayon sa mga query parameter)
GET	/api/cache/stats	Detalyadong estadistika ng cache (bawat provider, bawat model)
GET	/api/cache/reasoning	Katayuan ng reasoning cache (para sa reasoning replay)
DELETE	/api/cache/reasoning	I-clear ang reasoning cache — mga query param: ?toolCallId=<id> (isa) o ?provider=<p> o walang param (lahat)

Awtorisasyon: Nangangailangan ng management session.

---

Sistema ng Memory

Pamahalaan ang persistent memory (FTS5 + vector embeddings).

Paraan	Path	Paglalarawan
GET	/api/memory	Ilista ang mga entry sa memory (i-filter ayon sa scope, type, at search query)
POST	/api/memory	Gumawa ng bagong entry sa memory — body: {scope, type, content, metadata?}
GET	/api/memory/[id]	Kunin ang isang partikular na entry sa memory
PUT	/api/memory/[id]	I-update ang isang entry sa memory
DELETE	/api/memory/[id]	Tanggalin ang isang entry sa memory
GET	/api/memory?q=	Maghanap sa memory (FTS5 + vector) — kasama ang stats sa parehong tugon

Awtorisasyon: Nangangailangan ng management session o API key na may management scope.

---

Mga Webhook

Pamahalaan ang mga subscription sa webhook para sa mga event.

Paraan	Path	Paglalarawan
GET	/api/webhooks	Ilista ang lahat ng subscription sa webhook
POST	/api/webhooks	Gumawa ng subscription sa webhook — body: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Kunin ang isang partikular na subscription sa webhook
PUT	/api/webhooks/[id]	I-update ang isang subscription sa webhook
DELETE	/api/webhooks/[id]	Tanggalin ang isang subscription sa webhook
GET	/api/webhooks/[id]/deliveries	Ilista ang kasaysayan ng delivery para sa isang webhook (log ng tagumpay/palya)
POST	/api/webhooks/[id]/test	Magpadala ng pansubok na event sa isang webhook

Awtorisasyon: Nangangailangan ng management session.

Tingnan ang Framework ng Mga Webhook para sa lahat ng uri ng event.

---

Framework ng Skills

Pamahalaan ang Skills (ang framework ng mga agentic extension).

Pamamaraan	Path	Paglalarawan
GET	/api/skills	Ilista ang lahat ng naka-install na skill (built-in + custom)
POST	/api/skills/install	Mag-install ng skill mula sa lokal na path o URL
DELETE	/api/skills/[id]	Mag-uninstall ng skill
PUT	/api/skills/[id]	I-enable o i-disable ang skill — body: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Magpatakbo ng skill — body: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Ilista ang kasaysayan ng pagpapatakbo para sa lahat ng skill (i-filter ayon sa ?apiKeyId=)

Auth: Nangangailangan ng session sa pamamahala o API key na may saklaw sa pamamahala.

Tingnan ang Framework ng Skills para sa kumpletong detalye.

---

Mga Plugin

Pamahalaan ang mga plugin ng OmniRoute (mga third-party extension).

Pamamaraan	Path	Paglalarawan
GET	/api/plugins	Ilista ang mga naka-install na plugin
POST	/api/plugins/marketplace/install	Mag-install ng plugin mula sa marketplace
DELETE	/api/plugins/[name]	Mag-uninstall ng plugin
POST	/api/plugins/[name]/activate	I-activate ang plugin
POST	/api/plugins/[name]/deactivate	I-deactivate ang plugin
GET	/api/plugins/[name]/config	Kunin ang configuration ng plugin
PUT	/api/plugins/[name]/config	I-update ang configuration ng plugin

Auth: Nangangailangan ng session sa pamamahala.

Tingnan ang Framework ng Mga Plugin para sa kumpletong detalye.

---

Shadow Routing

Ang shadow / A-B comparison ng mga provider ay hindi isang standalone na REST surface — kino-configure ito sa pamamagitan ng combo routing (tingnan ang Auto-Combo). Ang mga metric ng paghahambing sa bawat combo ay ibinibigay ng GET /api/combos/metrics.

---

Mga Guardrail

Suriin ang mga runtime guardrail (PII detection, prompt injection detection, vision bridging). Tumatakbo ang mga guardrail sa bawat request; ang pag-opt out sa bawat call ay sa pamamagitan ng x-omniroute-disabled-guardrails request header — walang naka-persist na surface para i-enable/i-disable ito.

Pamamaraan	Path	Paglalarawan
GET	/api/guardrails	Ilista ang mga nakarehistrong guardrail at ang status ng mga ito (pangalan / naka-enable / priyoridad)
POST	/api/guardrails/test	I-dry-run ang pre-call pipeline sa isang sample na input — body: {input, disabledGuardrails?}

Auth: Nangangailangan ng session sa pamamahala.

Tingnan ang Seguridad > Mga Guardrail para sa kumpletong detalye.

---

---

Pagpapatunay

Tingnan ang Pagpapatunay sa Pamamahala para sa apat na pamilya ng kredensyal (session ng dashboard, lokal na CLI token, oma_live_… Access Token, API key na may saklaw na pamamahala) at kung paano naiiba ang mga ito sa mga inference key.

• Gumagamit ang mga ruta ng dashboard (/dashboard/*) ng auth_token cookie
• Ginagamit sa pag-login ang naka-save na password hash; babalik sa INITIAL_PASSWORD kung hindi ito magagamit
• Maaaring i-toggle ang requireLogin sa pamamagitan ng /api/settings/require-login
• Maaaring mangailangan ang mga rutang /v1/* ng Bearer API key kapag REQUIRE_API_KEY=true
• Ang "token sa pamamahala" / "API key na may saklaw na pamamahala" sa sangguniang ito ay nangangahulugang isa sa mga pamilya sa gabay na iyon — hindi isang karagdagang uri ng sikretong hindi tinukoy

Hindi backward-compatible na pagbabago (v3.8.0) — Nangangailangan na ngayon ang /api/v1/agents/tasks/* at ang mga endpoint sa pamamahala ng cooldown ng pagpapatunay sa pamamahala (auth_token cookie ng dashboard o isang API key na may saklaw na pamamahala). Makakatanggap ang mga client na dating tumatawag sa mga rutang ito nang walang pagpapatunay ng 401 Unauthorized. Tingnan ang commit na 588a0333 (fix(auth): require management auth for agent and cooldown APIs).