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

API Reference (Suomi)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇷 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

---

🌐 Kielet: 🇺🇸 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 APIn keskeinen viitedokumentaatio. Se kattaa julkisen /v1-rajapinnan ja käytetyimmät hallintapäätepisteet; koneellisesti luettava docs/openapi.yaml ja hakemiston src/app/api/ alla oleva reittipuu ovat kattavat lähteet.

---

Sisällysluettelo

• Keskustelutäydennykset
• Yksinomaiset hallittujen istuntojen varaukset
• Upotukset
• Kuvien luonti
• Asiakirjojen OCR
• Mallien luettelo
• Palveluntarjoajaliitännäisen manifesti
• Yhteensopivuuspäätepisteet
• Files API
• Batches API
• Search API
• WebSocket-suoratoisto
• Kiintiöt ja ongelmien raportointi
• Semanttinen välimuisti
• Hallintapaneeli ja hallinta
• Yhdistelmien hallinta
• Webhookit
• Rekisteröidyt avaimet (automaattinen hallinta)
• Agenttiprotokolla
• Hallintavälityspalvelimet
• Vikasietoisuus (laajennettu)
• Taidot
• Muisti
• MCP-palvelin
• A2A-palvelin
• Pilvipalvelut, arvioinnit ja arviointi
• Pyyntöjen käsittely
• Todennus

---

Keskustelutäydennykset

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
}

Mukautetut otsakkeet

Otsake	Suunta	Kuvaus
X-OmniRoute-No-Cache	Pyyntö	Aseta arvoksi true välimuistin ohittamiseksi
x-omniroute-no-memory	Pyyntö	Aseta arvoksi true, jotta muistin ja taitojen lisääminen ohitetaan tässä pyynnössä (vastaa välimuistin ohittamista ja välttää kutsukohtaisen tunniste- ja kustannuslisän)
X-OmniRoute-Progress	Pyyntö	Aseta arvoksi true edistymistapahtumien saamiseksi
X-Session-Id	Pyyntö	Pysyvä istuntoavain ulkoista istuntokohdistusta varten
x_session_id	Pyyntö	Myös alaviivallinen muunnelma hyväksytään (suora HTTP)
X-OmniRoute-Session-Id	Pyyntö	Kutsujan antama istunto-/keskustelutunniste (syötetään myös muistiin). Kun se on mukana, se tallennetaan sellaisenaan kenttään call_logs.session_tag istuntokohtaista kustannusten kohdistamista varten (#8249) — sitä ei koskaan muodosteta, jos se puuttuu
Idempotency-Key	Pyyntö	Kaksoiskappaleiden poistoavain (5 sekunnin aikaikkuna)
X-Request-Id	Pyyntö	Vaihtoehtoinen kaksoiskappaleiden poistoavain
X-OmniRoute-Cache	Vastaus	HIT tai MISS (ei-suoratoistettava)
X-OmniRoute-Idempotent	Vastaus	true, jos kaksoiskappale poistettiin
X-OmniRoute-Progress	Vastaus	enabled, jos edistymisen seuranta on käytössä
X-OmniRoute-Session-Id	Vastaus	OmniRouten käyttämä tosiasiallinen istuntotunnus
X-OmniRoute-Request-Id	Vastaus	Pyynnön korrelaatiotunnus (kun tiedossa)
X-OmniRoute-Version	Vastaus	OmniRoute-koontiversio (aina mukana)
X-OmniRoute-Cost-Saved	Vastaus	Välimuistin HIT-osumalla säästämä USD-määrä (vain välimuistiosumat)
X-OmniRoute-Decision	Vastaus	Reititysjälki: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> on yhdistelmästrategia tai single, jos pyyntö ei ole yhdistelmäpyyntö) — aina mukana valmistumisvastauksissa

Nginx-huomautus: jos käytät alaviivoja sisältäviä otsakkeita (esimerkiksi x_session_id), ota käyttöön underscores_in_headers on;.

Kustannustelemetrian otsakkeet: muut kuin suoratoistettavat onnistuneet vastaukset sisältävät myös X-OmniRoute-*-kustannustelemetriajoukon — X-OmniRoute-Response-Cost (USD, kiinteästi 10 desimaalia; 0.0000000000 ilmaisille/hinnoittelemattomille), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit ja X-OmniRoute-Fallback-Attempts (vain kun > 0) sekä X-OmniRoute-Request-Id ja X-OmniRoute-Version. Näitä palautetaan keskustelutäydennyksissä, /v1/responses-, /v1/messages- ja mediapäätepisteissä — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations ja /v1/moderations (kustannus aina 0). Median kustannus lasketaan modaliteettikohtaisesti (kuvaa, sekuntia, merkkiä tai hakuyksikköä kohden), kun hinnoittelu on saatavilla; muutoin kustannus on 0 (fail-open).

Välimuistiosuman kustannussemantiikka: semanttisen välimuistin OSUMAN yhteydessä (X-OmniRoute-Cache-Hit: true) ylävirran kutsua ei tehdä, joten X-OmniRoute-Response-Cost on 0.0000000000 (osuman palvelemisen lisäkustannus). Alkuperäinen tai ilman osumaa syntynyt kustannus ilmoitetaan erikseen otsakkeessa X-OmniRoute-Cost-Saved. Laskutusta käsittelevien järjestelmien tulee laskea yhteen X-OmniRoute-Response-Cost-arvot (osumat eivät maksa mitään); välimuistianalytiikassa voidaan koostaa X-OmniRoute-Cost-Saved-arvot.

Eksklusiiviset hallitut istuntovuokrat

Eksklusiivinen hallittu istuntovuokraus on valinnainen, asiakasohjelmasta riippumaton reitityssopimus: yksi aktiivinen omistaja hallitsee yhtä kelvollista OmniRoute-yhteyttä. Se ei vuokraa mallia, edellytä OAuth-todennusta, yksilöi tiettyä asiakasohjelmaa eikä edellytä tiettyä palveluntarjoajaa.

Todentamiseen käytettävällä API-avaimella on oltava käyttöoikeusalue lease:exclusive ja eksplisiittinen, ei-tyhjä allowedConnections-luettelo. Tietokantamutaatioiden rajapinta valvoo molempia kenttiä yhdessä avainta luotaessa ja osittaisia päivityksiä tehtäessä.

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

Onnistuneet hankinta-, uusimis- ja vapautusvastaukset sisältävät aikaleimat, state-arvon ja täsmällisen positiivisen generation-arvon, mutta eivät koskaan valittua yhteyttä tai tunnistetietoja. Uusimis- ja vapautuspyynnöissä sukupolvi annetaan JSON-rungossa:

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

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

Aktiivisen vuokran omistaja voi eksplisiittisesti pyytää yksityisyyden suojaavia näyttömetatietoja nykyisestä sidoksestaan:

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

Tämä valinnainen tilatoiminto suojataan läpinäkymättömällä omistajatunnisteella, todennetulla hallitulla API-avaimella ja aktiivisen sukupolven täsmällisellä arvolla yhdessä tietokantatapahtumassa. displayName on vain määritetyn yhteyden nimi ilman alun tai lopun tyhjemerkkejä; sen arvo on null, jos turvallista määritettyä nimeä ei ole. OmniRoute ei koskaan korvaa sitä sähköpostiosoitteella tai luodulla käyttäjätilin tunnisteella. Palveluntarjoajan arvo on ei-arkaluonteinen näyttötunniste eikä koskaan luotu yhteensopivan palveluntarjoajan tunniste. Tunnistetiedot, tunnukset, evästeet, käsittelemättömät yhteys- tai API-avaintunnisteet, omistajien tiivisteet, suojaussalaisuudet ja sisäiset reititystiedot jätetään pois.

Väärällä avaimella tai omistajalla tehdyt, vanhentuneen sukupolven sisältävät sekä puuttuvaan, vanhentuneeseen, vapautettuun tai mitätöityyn vuokraan kohdistuvat haut palauttavat kaikki saman 409 LEASE_FENCE_STALE -virheen ilman yhteyden metatietoja. Kapasiteetin odotusvastauksen saaneella asiakasohjelmalla ei ole tarkastettavaa aktiivista sidosta. Kun reititys siirtää aktiivisen vuokran, sama sukupolvi säilyy voimassa ja tilakysely palauttaa atomisesti uuden sidoksen, ei koskaan vanhaa. Nykyisten asiakasohjelmien toiminta ei muutu, koska hankinta-, uusimis-, vapautus- ja odotusvastaukset säilyttävät aiemmat rakenteensa.

Tämä palvelinsopimus ei muuta vakioidun OpenAI Codexin /status-toimintoa. Vakio-Codex raportoi tällä hetkellä mallinsa palveluntarjoajan sekä sisäänrakennetun todennus- ja käyttäjätilan tilan, mutta ei esitä mielivaltaisia mukautetun palveluntarjoajan käyttäjätilin metatietoja. Myöhemmän asiakasintegraation on kutsuttava tätä toimintoa ja päätettävä, miten connection.displayName näytetään.

Jokainen hallittu päättelypyyntö sisältää tämän jälkeen molemmat ohjausotsakkeet:

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

Täsmällinen omistaja, sukupolvi, aktiivinen yhteys ja todennettu API-avain suojataan välittömästi ennen jokaista tuettua ylävirran yritystä. Omistajan ja sukupolven uudelleenkäyttö toisella avaimella epäonnistuu, vaikka kyseinen avain sallisi saman yhteyden. Käsittelemättömiä omistajatunnisteita ei tallenneta pysyvästi, kirjata lokiin, säilytetä pyynnön tilannevedoksessa eikä välitetä ylävirtaan.

Tilapäinen resurssikilpailu palauttaa HTTP-tilan 429, Retry-After-otsakkeen sekä seuraavan sisällön:

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

Tämä vastaus tarkoittaa vain, että tavallinen kelvollisten yhteyksien joukko ei ollut tyhjä ja kaikki vapaat ehdokkaat olivat ulkopuolisten aktiivisten vuokrien hallussa. Mallien tai palveluntarjoajien tuen puuttuminen, käytäntöristiriidat, jäähdytysjaksot, kiintiöt, toimintakunto ja muut tavalliset kelpoisuusvirheet säilyttävät nykyiset OmniRoute-vastauksensa.

x-omniroute-compression

Pyyntökohtainen pakkaussuunnitelman ohitus. Sillä on korkein prioriteetti — se ohittaa reititysyhdistelmän ohituksen, aktiivisen profiilin, automaattisen käynnistyksen ja paneelin oletusasetuksen. Arvot:

Arvo	Vaikutus
off	Tätä pyyntöä ei pakata.
default	Paneelista johdettu oletusprofiili (aktiivinen profiili ohitetaan).
engine:<id>	Yksittäinen käytössä oleva moottori, esimerkiksi engine:rtk.
<combo>	Nimetty yhdistelmä, joka täsmäytetään ensin nimen perusteella kirjainkoosta riippumatta ja sitten tunnisteen perusteella.

Huomautukset:

• Tuntemattomat arvot ohitetaan (pyyntöä ei koskaan hylätä); ratkaisu jatkuu normaalin operaattoriprioriteetin mukaisesti.
• Jos useilla yhdistelmillä on sama nimi, anna yhdistelmän id, jotta täsmäys on deterministinen.
• Yhdistelmää, jonka nimi on off tai default, ei voi valita nimen perusteella (nämä avainsanat tulkitaan ensin); viittaa tällaiseen yhdistelmään sen tunnisteella.
• Pakkauksen pääkytkin toimii ehdottomana estona: kun pakkaus on poistettu käytöstä yleisesti, tämä otsake ei voi ottaa sitä käyttöön.

Käytetty suunnitelma palautetaan vastauksen otsakkeessa:

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

jossa <source> on jokin seuraavista: request-header, routing-override, active-profile, auto-trigger, default tai off.

---

Upotukset

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

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

Saatavilla olevat palveluntarjoajat: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

Luettelotunnisteet ovat muotoa provider/model (esimerkki: jina-ai/jina-embeddings-v5-omni-small). Rekisterissä esiintyvät Jinan pelkät mallitunnisteet (esimerkiksi jina-embeddings-v5-text-small, jina-reranker-v3.5) selvitetään myös. Jinan embed/rerank/classify/segment käyttää ensisijaisesti hallintapaneelin jina-ai-tunnistetietoja; JINA_AI_API_KEY toimii varavaihtoehtona vain, jos hallintapaneelin avainta ei ole. jina-reader-kortti on tarkoitettu vain Readerille / r.jina.ai:lle (POST /v1/web/fetch), eikä se koskaan tarjoa upotuksia tai uudelleenjärjestystä.

Rekisterimallit, jotka ilmoittavat tukevansa multimodaalisuutta, hyväksyvät myös enintään 32 palveluntarjoajasta riippumatonta rakenteista kohdetta. Mediakohteiden tyypit ovat text, image, audio, video ja document. Niiden median source on joko {"type":"url","url":"https://..."} tai {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano ja tuoteperheen alias jina-ai/jina-embeddings-v5-omni → omni-small) hyväksyy myös Jinan natiivit EmbeddingsV5Request-dokumentit ja välittää ne muuttamattomina osoitteeseen 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,..." }]
    }
  ]
}

Natiivien { image | audio | video | pdf }-arvot voivat olla julkinen HTTPS-URL-osoite, data:-URI tai käsittelemätön base64-data. OmniRoute ei muunna näitä objekteja merkkijonoiksi eikä nouda natiivien kuvien URL-osoitteita — Jina noutaa julkisen median itse. Jinan lisäkentät (task, normalized, truncate, embedding_type) välitetään eteenpäin. Vain tekstiä tukevat Jina-tuoteversiot hylkäävät edelleen muut kuin tekstidokumentit.

Tietoturva- ja siirtorajoitukset:

• Etämedian URL-osoitteiden on oltava julkisia HTTPS-osoitteita. Kanoniset {type,source:url}-kohteet noudetaan palvelinpuolella (uudelleenohjausten uudelleenvalidointi, aikakatkaisu, kokorajoitukset, julkinen DNS ja yhteyden kiinnitys) ja upotetaan ennen palveluntarjoajakutsua. Jinan natiivit {image:"https://..."}-kohteet välitetään sellaisinaan saman julkista HTTPS-osoitetta koskevan tarkistuksen jälkeen; Jina noutaa URL-osoitteen.
• Sisäisen base64-median purettu koko on rajoitettu 8 MiB:iin kohdetta kohti ja yhteensä 16 MiB:iin pyyntöä kohti.

Palveluntarjoajakohtainen muunnos (kanonisia kohteita ei koskaan välitetä muuttamattomina):

• Jinan multimodaaliset mallit: jokaisesta ylätason kohteesta tulee yksi modaliteettiavaimella varustettu objekti (text / image / audio / video / pdf), joka käyttää sisäiselle medialle data-URI-tunnisteita; yksi vektori kutakin ylätason kohdetta kohti.
• Gemini Embedding 2 -tuoteperhe: yhdestä ylätason taulukosta muodostetaan yksi natiivi models/{model}:embedContent-pyyntö, jossa on content.parts (text tai inline_data).
• Tuntemattomat/dynaamiset mallit, joilla ei ole eksplisiittisiä modaliteettien metatietoja, hylkäävät rakenteisen syötteen HTTP 400 -vastauksella.

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

Mallit ja modaliteetit, joiden yhdistelmää ei tueta, palauttavat HTTP 400 -vastauksen kohteen pakkomuuntamisen sijaan. Vanhojen merkkijono-/tunnistepyyntöjen muut kuin syötekenttiin liittyvät laajennuskentät välitetään edelleen muuttamattomina.

# Luettele kaikki upotusmallit
GET /v1/embeddings

---

Kuvien generointi

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

{
  "model": "openai/gpt-image-2",
  "prompt": "Kaunis auringonlasku vuorten yllä",
  "size": "1024x1024"
}

Saatavilla olevat palveluntarjoajat: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (paikallinen), ComfyUI (paikallinen).

# Luettele kaikki kuvamallit
GET /v1/images/generations

---

Asiakirjojen 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 valitsee OCR-palveluntarjoajan provider/model-etuliitteen avulla; pelkkä mallitunnus (esim. mistral-ocr-latest) yhdistetään sen rekisteröityyn palveluntarjoajaan, ja jos model jätetään pois, oletuksena käytetään Mistralia (mistral-ocr-latest). Rekisteröidyt palveluntarjoajat (open-sse/config/ocrRegistry.ts):

Palveluntarjoajan tunnus	Mallin tunnus	model-arvo	Huomautukset
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (tai pelkkä mistral-ocr-latest)	Synkroninen — vastaus palautetaan suoraan yhdestä ulkoiselle palvelulle tehdystä kutsusta.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Asynkroninen ulkoinen palvelu (analyze + kysely) — katso jäljempänä.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Synkroninen, Vertex AI:n openapi/chat/completions-kumppanirajapinnan kautta — katso jäljempänä todennus ja URL-osoite.

Kaikki kolme palveluntarjoajaa vastaavat samalla Mistral-muotoisella rungolla:

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

Azure Document Intelligencen kyselyprosessi

Azure Document Intelligencen analyze-API on asynkroninen: ensimmäinen pyyntö palauttaa rungon sijaan Operation-Location-otsakkeen, ja tulosta on kyseltävä toistuvasti. Käsittelijä (open-sse/handlers/ocr.ts) kyselee kyseistä URL-osoitetta sekunnin välein enintään 30 kertaa, keskeyttää heti (eikä jatka kyselyä), jos kyselyvastaus ei ole ok tai tila on "failed", ja palauttaa koodin 504, jos toiminto on yhä käynnissä yritysrajan täytyttyä. Lopullinen Azure-vastaus normalisoidaan samaan Mistralin käyttämään pages/markdown-muotoon ennen sen palauttamista kutsujalle, joten asiakaskoodissa palveluntarjoajaa ei tarvitse käsitellä erikoistapauksena.

Vertex AI DeepSeek OCR:n todennus ja päätepisteen määritys

vertex-deepseek-ocr käyttää uudelleen samaa Vertex AI -todennusta, jota OmniRoute jo tukee keskustelu- ja kuvaliikenteessä (open-sse/executors/vertex.ts): yhteyden API-avain on joko Service Account JSON -tunnistetieto (joka vaihdetaan lyhytikäiseen OAuth-käyttöoikeustunnukseen JWT bearer -prosessin kautta) tai valmiiksi luotu OAuth-käyttöoikeustunnus, jota käytetään sellaisenaan. Ulkoisen palvelun päätepisteen URL-osoite on Vertexin yleinen openapi/chat/completions-kumppanipäätepiste, joka muodostetaan yhteyden projektista ja alueesta — eksplisiittinen providerSpecificData.project/ providerSpecificData.region on aina ensisijainen; muussa tapauksessa projekti johdetaan Service Account JSONin project_id-arvosta ja alueen oletusarvo on us-central1. Molemmat määritykset tehdään tiedostossa open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), ja src/app/api/v1/ocr/route.ts käyttää niitä ennen pyynnön välittämistä handleOcr-käsittelijälle.

---

Mallien luettelo

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

→ Palauttaa kaikki keskustelu-, upotus- ja kuvamallit sekä yhdistelmät OpenAI-muodossa

Mallitunnusten etuliitteet (?prefix=)

Useimmat mallit julkaistaan palveluntarjoajan etuliitteellä. Käytettävää etuliitettä ohjaa MODELS_CATALOG_PREFIX_MODE-ominaisuuslippu, ja se voidaan ohittaa pyyntökohtaisesti kyselyparametrilla — tästä on hyötyä asiakkaalle, joka haluaa selkeän luettelon muuttamatta palvelimen laajuista asetusta kaikille muille:

GET /v1/models?prefix=alias        # yksi tunnus mallia kohden — lyhyt alias-etuliite
GET /v1/models?prefix=dual         # molemmat muodot (palvelimen oletus)
GET /v1/models?prefix=canonical    # vain täydellinen palveluntarjoajatunnuksen etuliite

Tila	Tuottaa	Huomautukset
dual	cc/claude-sonnet-4-6 ja claude/claude-sonnet-4-6	Oletus. Molemmat tunnukset reititetään samaan malliin; ne säilytetään, jotta jommankumman muodon kiinteästi määrittäneet asiakaskokoonpanot toimivat edelleen. Luettelon koko kasvaa suunnilleen kaksinkertaiseksi.
alias	cc/claude-sonnet-4-6	Yksi merkintä mallia kohden. Palveluntarjoajat, joilla ei ole erillistä aliasta, tuottavat silti merkintänsä, joten mitään ei menetetä.
canonical	claude/claude-sonnet-4-6	Yksi merkintä mallia kohden täydellisellä palveluntarjoajatunnuksen etuliitteellä. Palveluntarjoajat, joilla ei ole erillistä aliasta (esim. antigravity/…, agy/…), tuottavat tässäkin yksittäisen tunnuksensa, joten mitään ei menetetä.

dual-tilassa toimivan peilin voi tunnistaa myös ilman kyselyparametria: se sisältää ensisijaiseen tunnukseen osoittavan parent-kentän.

Mallivalitsimen näyttävien asiakkaiden kannattaa pyytää ?prefix=alias — näin toimii myös OmniCopilotin VS Code -laajennus.

Ajatteluttomat mallivariantit

Ajattelukykyisille Claude-malleille /v1/models julkaisee myös ajatteluttoman variantin, jonka tunnuksen etuliite on claude-3-omniroute-no-thinking/:

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

Tämän tunnuksen valitseminen (esimerkiksi Claude Code -kokoonpanossa, joka lisää aina thinking-lohkon) muunnetaan takaisin todelliseksi <provider>/<model>-malliksi päättely poistettuna käytöstä — /v1/messages-reitillä käytetään thinking:{type:"disabled"}-määritystä, tai /v1/chat/completions-reitillä reasoning- ja reasoning_effort-kentät jätetään pois. Variantti luetellaan vain Claude-perheen malleille, jotka tukevat ajattelua ja noudattavat disabled-asetusta (joten esimerkiksi vain mukautuvaa tilaa tukevat mallit, jotka hylkäävät disabled-asetuksen, jätetään pois). Operaattorit voivat pakottaa variantin käyttöön tai pois käytöstä mallikohtaisesti ModelSpec.noThinkingAlias-asetuksella.

---

Palveluntarjoajaliitännäisen manifesti

GET /api/v1/provider-plugin-manifest

Palauttaa JSON-turvallisen palveluntarjoajaliitännäisen manifestin, jota käyttävät Bifrost, CLIProxyAPI ja tulevat rinnakkaisreitittimet. Vastaus luodaan TypeScript-palveluntarjoajarekisteristä, ja siitä jätetään tarkoituksella pois OAuth-asiakasohjelmien salaisuudet, ajonaikaisen ympäristön selvitys, suoritusfunktiot, pyyntöotsakkeet ja tilitiedot.

Käytä tätä päätepistettä, kun rinnakkaisprosessi suoritetaan pääprosessin ulkopuolella eikä se voi tuoda open-sse/config/providerPluginManifestRegistry.ts-tiedostoa suoraan.

---

Yhteensopivuuspäätepisteet

Menetelmä	Polku	Muoto
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 (muokkaus/täyttö)
POST	/v1/videos/generations	OpenAI-tyylinen videon luonti
POST	/v1/music/generations	OpenAI-tyylinen musiikin luonti
POST	/v1/audio/transcriptions	OpenAI Audio (puhe tekstiksi)
POST	/v1/audio/speech	OpenAI TTS (palauttaa äänirungon)
POST	/v1/rerank	Cohere/Voyage-tyylinen uudelleenjärjestys
POST	/v1/classify	Jina-luokittelu (api.jina.ai)
POST	/v1/segment	Jina-segmentoija (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-luettelon alias
GET	/api/v1/vscode/{token}/models	OpenAI-mallien alias
POST	/api/v1/vscode/{token}/chat/completions	OpenAI:n tunnisteellinen alias
POST	/api/v1/vscode/{token}/responses	OpenAI Responses -tunnistealias
POST	/api/v1/vscode/{token}/api/chat	Ollama-tunnistealias
GET	/api/v1/vscode/{token}/api/tags	Ollama-tunnisteiden alias

Kaikki POST-reitit noudattavat samaa rakennetta: Bearer your-api-key + Zod-validoitu JSON-runko (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema jne.; katso src/shared/validation/schemas.ts). Skeeman epäonnistuessa palautetaan 4xx.

Asiakasohjelmille, jotka eivät voi liittää Authorization: Bearer ... -otsaketta, OmniRoute hyväksyy API-avaimet myös URL-osoitteessa joko kyselymerkkijonoyhteensopivuuden (?token=..., ?apiKey=..., ?api_key=..., ?key=...) tai alla dokumentoitujen erillisten /api/v1/vscode/{token}/...-päätepisteiden kautta.

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

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

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

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

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

# TTS — palauttaa audio/mpeg-rungon (tai pyydetyn muodon)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

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

# Videon / musiikin luonti (palveluntarjoajan etuliitteellä varustettu mallitunnus)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Palveluntarjoajakohtaiset reitit

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

Palveluntarjoajan etuliite lisätään automaattisesti, jos se puuttuu. Yhteensopimattomat mallit palauttavat vastauksen 400.

---

Files API

OpenAI-yhteensopiva tiedostojen päätepiste eräajojen syötteille ja tulosteille sekä käyttötarkoituksen mukaan määritettäville latauksille.

Menetelmä	Polku	Kuvaus
POST	/v1/files	Lataa tiedosto (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — enintään 512 MiB
GET	/v1/files	Luettele todennettuun API-avaimeen liittyvät tiedostot
GET	/v1/files/[id]	Nouda tiedoston metatiedot
DELETE	/v1/files/[id]	Poista tiedosto
GET	/v1/files/[id]/content	Suoratoista tiedoston käsittelemätön sisältö takaisin

Todennus: Bearer-API-avain — tiedostot rajataan API-avainkohtaisesti getApiKeyRequestScope-toiminnolla. Avain näkee, lataa ja poistaa vain omat tiedostonsa; hallintapaneeli-istunto ilman avainta voi lukea koko instanssin tiedostot; tiedostoon, jolla ei ole omistajaa (anonyymi lataus tai hallintapaneeli-istunnon lataus), ei ole pääsyä yhdelläkään istuntoon kuulumattomalla kutsujalla. GET /v1/files hylkää anonyymin kutsujan — sekä annetun avaimen, jota ei voida selvittää — vastauksella 401, vaikka REQUIRE_API_KEY=false, sen sijaan että se luettelisi kaikkien vuokralaisten tiedostot (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches API

OpenAI-yhteensopiva eräkäsittely.

Menetelmä	Polku	Kuvaus
POST	/v1/batches	Luo erä — pyynnön runko validoidaan v1BatchCreateSchema-skeemalla (input_file_id, endpoint, completion_window)
GET	/v1/batches	Luettele erät
GET	/v1/batches/[id]	Nouda erän tila ja request_counts
DELETE	/v1/batches/[id]	Poista valmis tai epäonnistunut erä
POST	/v1/batches/[id]/cancel	Peruuta käynnissä oleva erä

Todennus: Bearer-API-avain. Erät rajataan API-avainkohtaisesti samalla kolmitahoisella säännöllä kuin tiedostot: vain oma avain, hallintapaneeli-istunnolle koko instanssi ja omistajattomat tietueet estetään kaikilta istuntoon kuulumattomilta kutsujilta (nouto, poisto, peruutus sekä luonnin yhteydessä tehtävä input_file_id-tarkistus). GET /v1/batches hylkää anonyymin kutsujan vastauksella 401, vaikka REQUIRE_API_KEY=false.

---

Haku-API

Verkko-/hakupalveluntarjoajien abstraktio (Tavily, Brave, Exa, Serper jne.).

Menetelmä	Polku	Kuvaus
GET	/v1/search	Luettelee määritetyt hakupalveluntarjoajat ja niiden ominaisuudet
POST	/v1/search	Suorittaa hakukyselyn — runko validoidaan v1SearchSchema-skeemalla, tukee välimuistitusta/yhdistämistä
GET	/v1/search/analytics	Palveluntarjoajakohtaiset osuma-, viive- ja välimuistitilastot

Todennus: Bearer-API-avain (extractApiKey + isValidApiKey). Hakukäytäntö pakotetaan enforceApiKeyPolicy-toiminnolla.

---

Verkkosisällön haku-API

Poimi sisältöä URL-osoitteesta määritetyn verkkosisällön hakupalveluntarjoajan avulla (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Menetelmä	Polku	Kuvaus
POST	/v1/web/fetch	Hakee/raapii URL-osoitteen — runko validoidaan v1WebFetchSchema-skeemalla

Todennus: Bearer-API-avain (extractApiKey + isValidApiKey). Käytäntö pakotetaan enforceApiKeyPolicy-toiminnolla.

Kiintiöt huomioiva varamenettely (#8297): kun eksplisiittistä provider-arvoa ei anneta, pooli (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) käydään läpi kiinteässä prioriteettijärjestyksessä (ensimmäinen täytetään ensin) — nopeusrajoitettu mutta määritetty palveluntarjoaja ohitetaan sen sijaan, että pyyntö keskeytettäisiin, ja uudelleen yritettävästä/kiintiöön liittyvästä ylävirran virheestä (HTTP 429 aina; 402/403 Firecrawl-/Tavily-/TinyFish-palvelujen kiintiötyylisillä ilmaisilla tasoilla — ei Jina Readerille eikä koskaan tavalliselle virheellistä pyyntöä tarkoittavalle 400-virheelle) siirrytään pyynnön aikana seuraavaan vielä kokeilemattomaan palveluntarjoajaan, jolle on määritetty tunnistetiedot. Kun kaikki poolin palveluntarjoajat on käytetty loppuun, päätepiste palauttaa yhden 429-vastauksen (Retry-After-otsakkeen kanssa) aiemman yleisen 400-vastauksen sijaan. Kun eksplisiittistä provider-arvoa pyydetään, hiljaista varamenettelyä ei ole — nopeusrajoitettu tai epäonnistuva eksplisiittinen palveluntarjoaja välittää oman virheensä (429, jos sitä on nopeusrajoitettu, muussa tapauksessa ylävirran tilakoodin).

---

WebSocket-suoratoisto

GET /v1/ws?handshake=1

Validoi WebSocket-päivityksen kättelyn ja palauttaa verkkoprotokollan esimerkkiviestit (request, cancel). Varsinaiset WS-kehykset käsittelee mukana toimitettu WS-palvelin Next.js-reittitaulukon ulkopuolella.

Todennus: Bearer-API-avain kättelyn aikana.

Responses-API WebSocketin kautta (vain codex)

# Sama isäntä:portti kuin HTTP-API:lla (oletuksena 20128); päivitä yhteys:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (tai: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Ensimmäisen kehyksen TÄYTYY olla response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Responses-API:n WebSocket-välityspalvelin on yhdistetty yksinomaan codex-palveluun (ChatGPT- taustajärjestelmä). Se kuuntelee samassa portissa kuin API/hallintapaneeli poluissa /v1/responses, /responses ja /api/v1/responses. Ensimmäisen response.create-kehyksen yhteydessä se todentaa ja valmistelee pyynnön sisäisen codex-responses-ws-sillan kautta, valitsee codex OAuth -yhteyden ja tunneloi osoitteeseen wss://chatgpt.com/backend-api/codex/responses wreq-js-siirtotavan kautta. Muut kuin codex-mallit hylätään (codex_ws_provider_required). Käytä kiintiöosuuteen perustuvaan reititykseen arvoa model: "qtSd/<group>/codex/<model>". Toteutus sijaitsee tiedostoissa app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Todennus: Bearer-API-avain kättelyn aikana. Mukana toimitetun HTTP-palvelimen (server-ws.mjs) on oltava aktiivinen aloituspiste (kuten oletusarvoisesti on, kun app/server-ws.mjs on olemassa).

Mallitunnus: käytä pelkkää ChatGPT-tunnusta (ei codex/-etuliitettä)

OpenAI Codex CLI validoi mallin nimen asiakaspuolella, kun supports_websockets = true, ja hylkää palveluntarjoajan etuliitteellä varustetut tunnukset, kuten codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Lähetä pelkkä tunnus (esim. gpt-5.5). OmniRouten silta on vain codexia varten, joten se tulkitsee pelkän tunnuksen uudelleen codex-malliksi (resolveCodexWsModelInfo) ennen ylävirtaan tunnelointia — vaikka pelkkä gpt-5.5 reititettäisiin muuten toiselle palveluntarjoajalle HTTP:n kautta.

OpenAI Codex CLI:n määrittäminen

Ohjaa Codex CLI OmniRouteen lisäämällä WebSocket- tuella varustettu mukautettu palveluntarjoaja tiedostoon ~/.codex/config.toml (käytä erillistä CODEX_HOME-hakemistoa, jotta olemassa olevaan määritykseen ei kosketa):

model = "gpt-5.5"                 # pelkkä tunnus — EI "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # ei lopussa olevaa vinoviivaa; WS-URL johdetaan tästä (käytä tuotannossa https/wss)
wire_api = "responses"                    # ainoa tuettu arvo helmikuusta 2026 lähtien
supports_websockets = true                # ottaa Responses-over-WS-siirtotavan käyttöön
env_key = "OMNIROUTE_API_KEY"             # sisältää OmniRoute-API-avaimen (Bearer)

export OMNIROUTE_API_KEY=sk-...           # OmniRoute-API-avain (mikä tahansa avain, jos REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI päivittää osoitteen base_url + /responses WebSocket-yhteydeksi, ja OmniRoute tunneloi sen valittuun codex OAuth -yhteyteen. Toiminta on validoitu päästä päähän paikallista palvelinta vasten: ChatGPT palauttaa codex.rate_limits + response.created ja suoratoistaa vastauksen.

---

Kiintiöt ja ongelmien raportointi

Menetelmä	Polku	Kuvaus
GET	/v1/quotas/check	Esivalidoi provider- ja accountId-kiintiö ennen rekisteröidyn avaimen myöntämistä
POST	/v1/issues/report	Raportoi kiintiön tai avaimen myöntämisen epäonnistuminen GitHubiin (edellyttää GITHUB_ISSUES_REPO-muuttujaa ja tunnusta)

Todennus: Bearer-API-avain (isAuthenticated).

---

Itsepalvelukäyttö (/api/usage/om-usage)

Mikä tahansa API-avain voi lukea oman käyttönsä ja kiintiönsä — hallinnan todennusta ei tarvita. Tätä päätepistettä asiakas (CLI, OmniCopilot-paneeli) käyttää näyttääkseen avaimen haltijalle tämän kulutuksen.

# Tekstimuoto (historiallinen sopimus — pelkkää tekstiä päätettä varten)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Rakenteinen muoto — käyttöliittymän käyttämä muoto
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Avaimella on oltava allowUsageCommand käytössä (oletusarvoisesti pois käytöstä — hallintapaneelin API-avainten hallinta ottaa sen käyttöön tai poistaa sen käytöstä avainkohtaisesti). Ilman sitä päätepiste vastaa koodilla 403.

?format=json palauttaa erottelevan rakenteen, jotta kutsuja ei koskaan lue tietokenttää hylkäysvastauksesta. Onnistunut vastaus:

{
  "allowed": true,
  // mukana vain, kun avaimelle on otettu käyttöön avainkohtaiset käyttörajat (päivittäinen/viikoittainen USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // valitun palveluntarjoajan kiintiön tilannevedos tai null, kun välimuistissa ei vielä ole mitään:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // jokaisen yhteyden tilannevedos, jotta käyttöliittymä voi näyttää useita palveluntarjoajia rinnakkain:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Hylkäystilanteessa (401 virheellinen avain / 403 ei sallittu) sama reitti palauttaa { "allowed": false, "error": { "message": "…" } } — olemassa oleva mutta tyhjä personal/provider (avain sallittu, mutta mitään ei ole vielä saatu selville) on eri tila kuin hylkäys, ja vain JSON-muoto erottaa ne toisistaan.

Todennus: kutsujan oma Bearer-API-avain, joka validoidaan isValidApiKey-funktiolla — tämä ei ole hallintarajapinta (/api/keys/…), jonka suojauksena säilyy requireManagementAuth.

---

Semanttinen välimuisti

# Hae välimuistin tilastot
GET /api/cache/stats

# Tyhjennä kaikki välimuistit
DELETE /api/cache/stats

Esimerkkivastaus:

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

Vaikutus viiveeseen

Semanttisen välimuistin OSUMA palauttaa vastauksen välimuistista ilman kutsua ylävirran palveluun, joten ilmoitettu X-OmniRoute-Response-Latency on lähes nolla (riippumatta alkuperäisestä ylävirran viiveestä). Viiveelle herkkien asiakkaiden (vertailumittaukset, p50/p99-valvonta) tulee tarkistaa X-OmniRoute-Cache-Latency-vastausotsake:

Arvo	Merkitys
synthetic	Vastaus palautettiin välimuistista; viive ei ole todellinen ylävirran aika
(puuttuu)	Vastaus todellisesta ylävirran kutsusta

Avainkohtainen välimuistin ohitus

API-avaimet voivat ohittaa semanttisen välimuistin luvut cacheDefaultMode-asetuksen avulla:

Arvo	Toiminta
legacy	Normaali välimuistin toiminta (oletus)
bypass	Ohita välimuistihaku kokonaan; kutsu aina ylävirran palvelua

Aseta avaimen luonnin yhteydessä (POST /api/keys) tai päivitä (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Pyyntökohtainen ohitus

Mikä tahansa pyyntö voi ohittaa välimuistin avaimen asetuksista riippumatta:

X-OmniRoute-No-Cache: true

---

Hallintapaneeli ja hallinta

Hallintareittejä (/api/*, lukuun ottamatta julkista todennusta/kirjautumista) ei valtuuteta tavallisilla päättelyrajapinnan API-avaimilla. Tunnistetietoperheet, käyttöalueet ja curl-esimerkit: Hallinnan todennus.

Todennus

Päätepiste	Menetelmä	Kuvaus
/api/auth/login	POST	Kirjautuminen
/api/auth/logout	POST	Uloskirjautuminen
/api/settings/require-login	GET/PUT	Pakollisen kirjautumisen vaihto

Palveluntarjoajien hallinta

Päätepiste	Menetelmä	Kuvaus
/api/providers	GET/POST	Palveluntarjoajien luettelointi / luominen
/api/providers/[id]	GET/PUT/DELETE	Palveluntarjoajan hallinta
/api/providers/[id]/test	POST	Palveluntarjoajayhteyden testaaminen
/api/providers/[id]/models	GET	Palveluntarjoajan mallien luettelointi
/api/providers/validate	POST	Palveluntarjoajan määritysten validointi
/api/providers/bulk	POST	API-avainten lisääminen eränä YHDELLE palveluntarjoajalle
/api/providers/import	POST	Heterogeenisen palveluntarjoajaluettelon tuonti jäsennetystä CSV-/JSON-tiedostosta (#6836); rivikohtaiset osittaisen epäonnistumisen tulokset
/api/provider-nodes*	Useita	Palveluntarjoajasolmujen hallinta
/api/provider-models	GET/POST/PATCH/DELETE	Mukautetut mallit (lisääminen, päivittäminen, piilottaminen/näyttäminen, poistaminen)

OAuth-työnkulut

Päätepiste	Menetelmä	Kuvaus
/api/oauth/[provider]/[action]	Useita	Palveluntarjoajakohtainen OAuth

Reititys ja määritykset

Päätepiste	Menetelmä	Kuvaus
/api/models/alias	GET/POST	Mallien aliakset
/api/models/catalog	GET	Kaikki mallit palveluntarjoajan ja tyypin mukaan
/api/combos*	Useita	Yhdistelmien hallinta
/api/keys*	Useita	API-avainten hallinta
/api/pricing	GET	Mallien hinnoittelu

Käyttö ja analytiikka

Päätepiste	Menetelmä	Kuvaus
/api/usage/history	GET	Käyttöhistoria
/api/usage/logs	GET	Käyttölokit
/api/usage/request-logs	GET	Pyyntötason lokit
/api/usage/[connectionId]	GET	Yhteyskohtainen käyttö
/api/usage/token-limits	GET/POST/DELETE	API-avainkohtaiset token-rajoitusbudjetit
/api/usage/model-latency-stats	GET	Liukuva palveluntarjoaja-/mallikohtainen viivekooste (keskiarvo/p50/p95/p99, onnistumisaste); suodattimet: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	call_logs-tietoihin perustuva kehotevälimuistin kunnon yhteenveto — kirjoitus-/lukusuhde, kirjoituskoon p50/p90/p99-jakauma, suurten kirjoitusten keskittyminen, mallikohtainen erittely sekä healthy/degraded/thrash/no-data-arvio; kyselyparametrit range (1h|24h|7d|30d, oletus 24h) ja valinnainen model (#8827)

Asetukset

Päätepiste	Menetelmä	Kuvaus
/api/settings	GET/PUT/PATCH	Yleiset asetukset
/api/settings/proxy	GET/PUT	Verkon välityspalvelimen määritys
/api/settings/proxy/test	POST	Testaa välityspalvelinyhteys
/api/settings/ip-filter	GET/PUT	IP-osoitteiden sallittujen/estettyjen luettelo
/api/settings/thinking-budget	GET/PUT	Ajattelu-/päättelypyynnön request-uudelleenkirjoitustila (läpivienti / automaattinen poisto / mukautettu / adaptiivinen). Pakkaamisesta riippumaton. Katso THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Globaali järjestelmäkehote
/api/settings/compression	GET/PUT	Globaali pakkausmääritys
/api/settings/purge-request-history	POST	Tyhjennä pyyntölokin rivit ja paikalliset kutsulokiartifaktit

Konteksti ja pakkaus

Päätepiste	Menetelmä	Kuvaus
/api/compression/preview	POST	off/lite/standard/aggressive/ultra/RTK/stacked-pakkauksen esikatselu
/api/compression/language-packs	GET	Luettele saatavilla olevat Caveman-kielipaketit
/api/compression/rules	GET	Luettele Caveman-sääntöjen metatiedot
/api/context/caveman/config	GET/PUT	Caveman-kohtaisten asetusten alias
/api/context/rtk/config	GET/PUT	RTK-kohtaiset asetukset, mukaan lukien mukautetut suodattimet ja raakatuotoksen säilytys
/api/context/rtk/filters	GET	RTK-suodatinluettelo ja mukautettujen suodattimien diagnostiikka
/api/context/rtk/test	POST	Suorita RTK-esikatselu/-testi tekstihyötykuormalle
/api/context/rtk/raw-output/[id]	GET	Lue säilytetty, peitetty raakatuotos osoittimen tunnuksen perusteella
/api/context/combos	GET/POST	Pakkausyhdistelmien luettelo / luonti
/api/context/combos/[id]	GET/PUT/DELETE	Pakkausyhdistelmän tiedot / päivitys / poisto
/api/context/combos/[id]/assignments	GET/PUT	Määritä pakkausyhdistelmiä reititysyhdistelmille
/api/context/analytics	GET	Pakkausanalytiikan alias

Valvonta

Päätepiste	Menetelmä	Kuvaus
/api/sessions	GET	Aktiivisten istuntojen seuranta
/api/rate-limits	GET	Tilikohtaiset nopeusrajoitukset
/api/monitoring/health	GET	Kuntotarkistus + palveluntarjoajien yhteenveto (catalogCount, configuredCount, activeCount, monitoredCount). Hallintanäkymä sisältää credentialHealth-tiedot: koevälimuistin skalaariarvot, failedConnections, kun failed>0, sekä staleDbNonOkCount (SQLiten pysyvä test_status, ei mittari). Katso MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Välimuistitilastot / tyhjennys
/api/modality-bridge/stats	GET	Muistissa olevat attempts, onnistumiset/bridged, epäonnistumiset, välimuistiosumat, totalLatencyMs, latencySamples, otosmäärään perustuva averageLatencyMs ja viimeisen käytön aika (nollataan uudelleenkäynnistyksen yhteydessä; hallinnan todennus)
/api/modality-bridge/video/runtime	GET	Tiukka luotetun loopback-yhteyden tarkistus ennen hallinnan todennusta/koetta; siistityt FFmpeg-/ffprobe-saatavuus- ja versiotiedot (no-store)
/api/modality-bridge/video/extract	POST	Sisäinen todennettu luotetun loopback-yhteyden tavuvälittäjä; 50 MiB:n syöte, rajattu jono / 32 MiB:n tuloste, 503 kapasiteetille, 499 yhteyden katkaisulle, 504 määräajalle; ei julkinen tiedostojen lähetysrajapinta

Varmuuskopiointi ja vienti/tuonti

Päätepiste	Menetelmä	Kuvaus
/api/db-backups	GET	Luettele saatavilla olevat varmuuskopiot
/api/db-backups	PUT	Luo manuaalinen varmuuskopio
/api/db-backups	POST	Palauta tietystä varmuuskopiosta
/api/db-backups/export	GET	Lataa tietokanta .sqlite-tiedostona
/api/db-backups/import	POST	Korvaa tietokanta lataamalla .sqlite-tiedosto
/api/db-backups/exportAll	GET	Lataa täydellinen varmuuskopio .tar.gz-arkistona

Pilvisynkronointi

Päätepiste	Menetelmä	Kuvaus
/api/sync/cloud	Useita	Pilvisynkronointitoiminnot
/api/sync/initialize	POST	Alusta synkronointi
/api/cloud/*	Useita	Pilvipalvelun hallinta

Tunnelit

Päätepiste	Menetelmä	Kuvaus
/api/tunnels/cloudflared	GET	Lue Cloudflare Quick Tunnelin asennus- ja ajonaikainen tila koontinäyttöä varten
/api/tunnels/cloudflared	POST	Ota Cloudflare Quick Tunnel käyttöön tai poista se käytöstä (action=enable/disable)
/api/tunnels/ngrok	GET	Lue ngrok Tunnelin ajonaikainen tila koontinäyttöä varten
/api/tunnels/ngrok	POST	Ota ngrok Tunnel käyttöön tai poista se käytöstä (action=enable/disable)

CLI-työkalut

Päätepiste	Menetelmä	Kuvaus
/api/cli-tools/claude-settings	GET	Claude CLI:n tila
/api/cli-tools/codex-settings	GET	Codex CLI:n tila
/api/cli-tools/droid-settings	GET	Droid CLI:n tila
/api/cli-tools/openclaw-settings	GET	OpenClaw CLI:n tila
/api/cli-tools/runtime/[toolId]	GET	Yleinen CLI-ajoaikainen tila

CLI-vastaukset sisältävät: installed, runnable, command, commandPath, runtimeMode, reason.

ACP-agentit

Päätepiste	Menetelmä	Kuvaus
/api/acp/agents	GET	Luettele kaikki havaitut agentit (sisäänrakennetut ja mukautetut) tiloineen
/api/acp/agents	POST	Lisää mukautettu agentti tai päivitä tunnistusvälimuisti
/api/acp/agents	DELETE	Poista mukautettu agentti id-kyselyparametrin perusteella

GET-vastaus sisältää agents[]-taulukon (id, name, binary, version, installed, protocol, isCustom) ja summary-objektin (total, installed, notFound, builtIn, custom).

Vikasietoisuus ja nopeusrajoitukset

Päätepiste	Menetelmä	Kuvaus
/api/resilience	GET/PATCH	Nouda tai päivitä pyyntöjono-, yhteyden jäähdytys-, palveluntarjoajan katkaisija- ja odotusasetukset
/api/resilience/reset	POST	Nollaa palveluntarjoajien virtapiirikatkaisijat
/api/resilience/model-cooldowns	GET	Luettele aktiiviset palveluntarjoaja-, yhteys- ja mallikohtaiset estot jäljellä olevan ajan mukaan lajiteltuina
/api/resilience/model-cooldowns	DELETE	Poista mallin esto — runko {provider, model} tai {all: true} kaiken poistamiseksi
/api/rate-limits	GET	Tilikohtainen nopeusrajoitusten tila
/api/rate-limit	GET	Yleinen nopeusrajoitusmääritys

Kaikki neljä /api/resilience/*-reittiä edellyttävät hallinnan todennusta (requireManagementAuth). Katso kohdasta Vikasietoisuus (laajennettu) palveluntarjoajan katkaisijan, yhteyden jäähdytyksen ja mallin eston täydellinen erittely.

Arvioinnit

Päätepiste	Menetelmä	Kuvaus
/api/evals	GET/POST	Luettele arviointikokonaisuudet / suorita arviointi

Käytännöt

Päätepiste	Menetelmä	Kuvaus
/api/policies	GET/POST/DELETE	Hallitse reitityskäytäntöjä

Vaatimustenmukaisuus

Päätepiste	Menetelmä	Kuvaus
/api/compliance/audit-log	GET	Vaatimustenmukaisuuden tarkastusloki (viimeiset N merkintää)

v1beta (Gemini-yhteensopiva)

Päätepiste	Menetelmä	Kuvaus
/v1beta/models	GET	Luettele mallit Gemini-muodossa
/v1beta/models/{...path}	POST	Geminin generateContent-päätepiste

Nämä päätepisteet jäljittelevät Geminin API-muotoa asiakkaille, jotka edellyttävät natiivia yhteensopivuutta Gemini SDK:n kanssa.

Sisäiset API:t / järjestelmä-API:t

Päätepiste	Metodi	Kuvaus
/api/init	GET	Sovelluksen alustuksen tarkistus (käytetään ensimmäisellä suorituskerralla)
/api/tags	GET	Ollama-yhteensopivat mallitunnisteet (Ollama-asiakasohjelmille)
/api/restart	POST	Käynnistä palvelin hallitusti uudelleen
/api/shutdown	POST	Sammuta palvelin hallitusti
/api/system/env/repair	POST	Korjaa OAuth-palveluntarjoajan ympäristömuuttujat

Huomautus: Järjestelmä käyttää näitä päätepisteitä sisäisesti tai Ollama-asiakasohjelmien yhteensopivuutta varten. Loppukäyttäjät eivät yleensä kutsu niitä.

OAuth-ympäristön korjaus (v3.6.1+)

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

{
  "provider": "claude-code"
}

Korjaa tietyn palveluntarjoajan puuttuvat tai vioittuneet OAuth-ympäristömuuttujat. Palauttaa:

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

---

Äänen litterointi

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

Litteroi äänitiedostoja millä tahansa määritetyllä STT-palveluntarjoajalla. Polun ensimmäinen segmentti valitsee natiivin palveluntarjoajan (openai/…, deepgram/…). Yhdyskäytävät, jotka tarjoavat uudelleen toisen toimittajan mallin, käyttävät tarkennettua tunnistetta (openrouter/deepgram/nova-3).

Pyyntö:

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

Vastaus:

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

Esimerkkejä mallitunnisteista: openai/whisper-1 (vaatii OpenAI-avaimen), openrouter/deepgram/nova-3 (vaatii OpenRouter-avaimen), deepgram/nova-3 (vaatii natiivin Deepgram-avaimen). Pelkkä deepgram/nova-3-pyyntö ei käytä OpenRouteria.

Tuetut muodot: mp3, wav, m4a, flac, ogg, webm.

---

Ollama-yhteensopivuus

Asiakkaille, jotka käyttävät Ollaman API-muotoa:

# Keskustelupäätepiste (Ollama-muoto)
POST /v1/api/chat

# Mallien luettelo (Ollama-muoto)
GET /api/tags

Pyynnöt muunnetaan automaattisesti Ollama-muodon ja sisäisten muotojen välillä.

Tunnukselliset VS Code -aliakset / otsakkeettomat aliakset

Käytä näitä aliaksia, kun integraatio ei voi lisätä Authorization-otsaketta ja API-avain on sisällytettävä perus-URL-osoitteeseen.

# OpenAI-tyylinen luetteloalias
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI-tyyliset keskustelualiakset
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama-tyyliset aliakset
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Esimerkki:

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

Huomautukset:

• Tunnukselliset aliakset käyttävät samoja käsittelijöitä kuin /v1/* ja /api/tags; vastausten rakenteet pysyvät samoina.
• Käytä ensisijaisesti Authorization: Bearer ... -otsaketta aina, kun asiakas tukee mukautettuja otsakkeita.
• URL-pohjaiset tunnukset voivat näkyä käänteisen välityspalvelimen lokeissa, selainhistoriassa ja OmniRouten ulkopuolisessa telemetriassa. Käsittele niitä yhteensopivuusvaihtoehtona, älä oletusarvoisena todennustapana.

---

Telemetria

# Hae viivetelemetrian yhteenveto (p50/p95/p99 palveluntarjoajittain)
GET /api/telemetry/summary

Vastaus:

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

---

Budjetti

# Hae kaikkien API-avainten budjettitila
GET /api/usage/budget

# Aseta tai päivitä budjetti
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"
}

Skeemahuomautukset (setBudgetSchema): apiKeyId on pakollinen; vähintään yhden kentistä dailyLimitUsd, weeklyLimitUsd tai monthlyLimitUsd arvon on oltava suurempi kuin nolla. Valinnaiset kentät: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Vanha {keyId, limit, period}-rakenne palauttaa vastauksen 400 Bad Request.

Tokenirajat

API-avainkohtaiset tokenbudjetit (erillään yllä olevasta USD-pohjaisesta budjetista). Ne pakotetaan käyttöön suoraan pyynnön käsittelypolulla: kun avaimen nykyisen aikajakson käyttö saavuttaa rajan, pyynnöt hylätään vastauksella 429 Too Many Requests. Rajat voidaan kohdistaa tiettyyn model-malliin, provider-palveluntarjoajaan tai niitä voidaan soveltaa global-tasolla koko avaimeen. Kun useampi raja vastaa pyyntöä, tiukinta rajaa sovelletaan.

# Luettele avaimen tokenrajat (sisältää nykyisen aikajakson reaaliaikaisen käytön)
GET /api/usage/token-limits?apiKeyId=key-123

# Luo tai päivitä tokenraja
POST /api/usage/token-limits
Content-Type: application/json

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

# Poista tokenraja tunnisteen perusteella
DELETE /api/usage/token-limits?id=tl-abc

Skeemaa koskevat huomautukset (setTokenLimitSchema): apiKeyId ja scopeType (model | provider | global) ovat pakollisia. scopeValue on pakollinen, ellei scopeType ole global (esimerkiksi mallin tunniste model-kohdistukselle tai palveluntarjoajan tunniste provider-kohdistukselle). tokenLimit-arvon on oltava positiivinen kokonaisluku (merkkijono muunnetaan automaattisesti). Valinnaiset: id (jätä pois luotaessa, anna päivitettäessä), resetInterval (daily | weekly | monthly, oletus monthly), resetTime (HH:MM), enabled (oletus true). GET-vastaukset täydentävät jokaista rajaa kentillä tokensUsed, remaining, windowStart, periodStartAt ja nextResetAt. Tämä on hallintaluokan päätepiste (todennus pakotetaan keskitetysti authz-käsittelyketjussa).

Pyyntöjen käsittely

1. Asiakas lähettää pyynnön polkuun /v1/*
2. Reitinkäsittelijä kutsuu funktiota handleChat, handleEmbedding, handleAudioTranscription tai handleImageGeneration
3. Malli selvitetään (suora palveluntarjoaja/malli tai alias/yhdistelmä)
4. Tunnistetiedot valitaan paikallisesta tietokannasta tilien saatavuussuodatuksella
5. Keskustelupyynnöissä handleChatCore tarkistaa semanttisen/allekirjoitusvälimuistin ja selvittää yhdistelmän pakkausasetukset
6. Ennakoiva pakkaus suoritetaan ennen palveluntarjoajamuunnosta, kun se on käytössä (lite, Caveman, RTK tai pinottu)
7. Palveluntarjoajan suorittaja lähettää pyynnön ylävirtaan
8. Vastaus muunnetaan takaisin asiakasmuotoon (keskustelu) tai palautetaan sellaisenaan (upotukset/kuvat/ääni)
9. Käyttö, pakkausanalytiikka ja pyyntölokit tallennetaan
10. Virhetilanteissa käytetään varavaihtoehtoa yhdistelmän sääntöjen mukaisesti

Täydellinen arkkitehtuuriviite: ARCHITECTURE.md

---

Yhdistelmien hallinta

Korkeamman tason reititysyhdistelmät (jotka on jo tiivistetty kohdassa /api/combos*) voidaan myös yhdistää yksi yhteen mallitunnisteen mallineesta, mikä mahdollistaa OpenAI-tyylisen mallitunnisteen läpinäkyvän uudelleenohjauksen yhdistelmään.

Menetelmä	Polku	Kuvaus
GET	/api/model-combo-mappings	Luettele kaikki malli→yhdistelmä-määritykset
POST	/api/model-combo-mappings	Luo määritys — runko: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Nouda yksittäinen määritys
PUT	/api/model-combo-mappings/[id]	Päivitä olemassa olevan määrityksen kenttiä
DELETE	/api/model-combo-mappings/[id]	Poista määritys

Todennus: hallintaistunto/API-avain (requireManagementAuth).

---

Webhookit

Lähtevien webhookien tilaukset OmniRoute-tapahtumille (pyynnön valmistuminen, kiintiön loppuminen, avaimen kierrätys jne.).

Menetelmä	Polku	Kuvaus
GET	/api/webhooks	Luettele webhookit (salaisuudet peitetään muotoon <prefix>...)
POST	/api/webhooks	Luo webhook — runko: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Hae webhook
PUT	/api/webhooks/[id]	Päivitä url/events/secret/description
DELETE	/api/webhooks/[id]	Poista webhook
POST	/api/webhooks/[id]/test	Lähetä testihyötykuorma webhookin URL-osoitteeseen ja palauta toimituksen tila

Todennus: hallintaistunto/API-avain (requireManagementAuth).

---

Rekisteröidyt avaimet (automaattinen hallinta)

Automaattinen avaintenhallinnan alijärjestelmä käyttää näitä API-avainten myöntämiseen ja kierrättämiseen taustalla olevan palveluntarjoajan/tilin kautta päivä- ja tuntikiintiöitä noudattaen.

Menetelmä	Polku	Kuvaus
GET	/api/v1/registered-keys	Luettele rekisteröidyt avaimet (vain peitetty etuliite)
POST	/api/v1/registered-keys	Myönnä uusi rekisteröity avain — runko: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Palauttaa käsittelemättömän avaimen kerran. Palauttaa 429, jos kiintiö estää pyynnön.
GET	/api/v1/registered-keys/[id]	Hae rekisteröidyn avaimen metatiedot (ei käsittelemätöntä avainmateriaalia)
DELETE	/api/v1/registered-keys/[id]	Peruuta rekisteröity avain
POST	/api/v1/registered-keys/[id]/revoke	Erillinen peruutuspäätepiste (sama vaikutus kuin DELETE-komennolla)

Todennus: Bearer API -avain (isAuthenticated). Katso myös /v1/quotas/check ja /v1/issues/report.

---

Agenttiprotokolla

OmniRoute-käyttäjien puolesta etänä suoritettavat pilviagenttitehtävät (Claude Code, Codex Cloud, OpenHands jne.).

Menetelmä	Polku	Kuvaus
GET	/api/v1/agents/tasks	Listaa tehtävät — valinnaiset ?provider=, ?status=, ?limit= (1–500, oletus 50)
POST	/api/v1/agents/tasks	Luo tehtävä — pyynnön runko validoidaan CreateCloudAgentTaskSchema-skeemalla (providerId, prompt, source, options?). Palauttaa 201 ja tehtäväkääreen
DELETE	/api/v1/agents/tasks?id=...	Poistaa tehtävän
GET	/api/v1/agents/tasks/[id]	Lukee tehtävän — päivittää tilan synkronisesti ulkoiselta pilviagentilta, kun external_id on asetettu
POST	/api/v1/agents/tasks/[id]	Erotteleva toiminto: {action: "approve"}, {action: "message", message} tai {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Poistaa tietyn tehtävän tunnuksen perusteella

Todennus: hallinnan todennus vaaditaan jokaiselle menetelmälle (requireCloudAgentManagementAuth). Ennen versiota v3.8.0 nämä eivät vaatineet todennusta — katso yhteensopivuuden rikkonut muutos commitista 588a0333.

# Luo Claude Code -pilvitehtävä
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":"..."}}'

---

Hallintavälityspalvelimet

Lähtevän HTTP(S)/SOCKS-liikenteen välityspalvelimet, jotka voidaan määrittää palveluntarjoajille, tileille tai yleisesti.

Menetelmä	Polku	Kuvaus
GET	/api/v1/management/proxies	Listaa välityspalvelimet (?id= palauttaa yhden; ?id=&where_used=1 palauttaa määrityskaavion)
POST	/api/v1/management/proxies	Luo välityspalvelimen — pyynnön runko validoidaan createProxyRegistrySchema-skeemalla
PATCH	/api/v1/management/proxies	Päivittää välityspalvelimen — pyynnön runko validoidaan updateProxyRegistrySchema-skeemalla (vaatii id-kentän)
DELETE	/api/v1/management/proxies?id=...&force=1	Poistaa välityspalvelimen (irrota määritykset käyttämällä force=1)
GET	/api/v1/management/proxies/assignments	Listaa määritykset — suodatettavissa arvoilla proxy_id, scope ja scope_id; selvitä yhteyden aktiivinen välityspalvelin välittämällä resolve_connection_id=<id>
PUT	/api/v1/management/proxies/assignments	Määrittää — pyynnön runko validoidaan proxyAssignmentSchema-skeemalla ({scope, scopeId?, proxyId?}). Tyhjentää välittäjän välimuistin
PUT	/api/v1/management/proxies/bulk-assign	Joukkomäärittää — pyynnön runko validoidaan bulkProxyAssignmentSchema-skeemalla ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Koostaa välityspalvelinten kuntotiedot (onnistuneiden ja epäonnistuneiden pyyntöjen määrät sekä viiveen) tietyltä ajanjaksolta

Todennus: hallintaistunto tai API-avain jokaisella reitillä (requireManagementAuth).

Tehtävän kuvauksen reittejä POST /api/v1/management/proxies/[id]/assignments ja POST /api/v1/management/proxies/[id]/health palvelevat yllä esitetyt yhtenäiset /assignments- ja /health-reitit — koodikannassa ei ole tunnuskohtaisia alireittejä.

---

Vikasietoisuus (laajennettu)

OmniRoute tarjoaa kolme toisistaan riippumatonta tilapäisten häiriöiden käsittelymekanismia. Alla olevien hallintapäätepisteiden avulla operaattorit voivat tarkastella ja ohittaa niitä:

Laajuus	Tilan tallennus	Lukeminen	Nollaus / tyhjennys
Palveluntarjoajan katkaisin	domain_circuit_breakers + muistiin tallennettu	/api/monitoring/health	POST /api/resilience/reset
Yhteyden jäähdytysjakso	rateLimitedUntil palveluntarjoajayhteyksissä	/api/rate-limits, /api/providers/[id]	(otetaan uudelleen käyttöön viiveellä; tyhjennä palveluntarjoajan PUT-pyynnöllä)
Mallin lukitus	Muistiin tallennettu mallien saatavuusrekisteri	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience hyväksyy palveluntarjoajan katkaisimen ohitukset kohdissa providerBreaker.oauth ja providerBreaker.apikey. Kukin profiili tukee kenttiä degradationThreshold, failureThreshold ja resetTimeoutMs. Samat kentät ovat käytettävissä kohdassa Hallintapaneeli → Asetukset → Vikasietoisuus.

# Tyhjennä yksittäisen mallin lukitus
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"}'

# Tyhjennä kaikki lukitukset
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Täydellinen käsitteellinen viite ja katkaisimen oletusarvot: katso CLAUDE.md → "Resilience Runtime State".

---

Taidot

Taitokehys OmniRouten laajentamiseen mukautetuilla suoritettavilla käsittelijöillä sekä kauppapaikkaintegraatioilla.

Menetelmä	Polku	Kuvaus
GET	/api/skills	Luettele asennetut taidot — suodatettavissa parametreilla ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, sivutettu
GET	/api/skills/[id]	Nouda yksi taito
PUT	/api/skills/[id]	Päivitä taito (nimi, kuvaus, tila, skeema, käsittelijä, tunnisteet)
DELETE	/api/skills/[id]	Poista taidon asennus
POST	/api/skills/install	Asenna taito käsittelemättömästä manifestista — runko: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Luettele viimeisimmät taitojen suoritukset (kirjausketju syötteineen, tuloksineen ja kestoineen)
GET	/api/skills/marketplace?q=...	Hae SkillsMP-kauppapaikasta tai näytä sen suosittujen taitojen luettelo (edellyttää skillsmpApiKey-asetusta)
POST	/api/skills/marketplace/install	Asenna taito SkillsMP:stä tunnisteen perusteella
GET	/api/skills/skillssh?q=&limit=	Hae skills.sh-rekisteristä
POST	/api/skills/skillssh/install	Asenna taito skills.sh:sta tunnisteen perusteella

Todennus: hallintaistunto/API-avain. Kauppapaikan hakureitit hyväksyvät joko hallintatodennuksen tai Bearer API -avaimen (isAuthenticated).

---

Muisti

Pysyvä keskustelu- ja faktamuisti, jonka näkyvyys rajataan API-avaimen tai istunnon mukaan.

Menetelmä	Polku	Kuvaus
GET	/api/memory	Listaa muistot — ?apiKeyId=, ?type=, ?sessionId=, ?q=, sivutus parametreilla offset/limit tai page/limit
POST	/api/memory	Luo muiston — Zodin validoima runko: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Hae yksi muisto
DELETE	/api/memory/[id]	Poista muisto
GET	/api/memory/health	Muistialijärjestelmän tila (tietokantayhteys, upotusten taustajärjestelmä, vektori-indeksin tila)

Todennus: hallintaistunto/API-avain (requireManagementAuth). type-luettelo: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (katso MemoryType tiedostossa src/lib/memory/types.ts).

---

MCP-palvelin

OmniRoute sisältää integroidun Model Context Protocol -palvelimen, jossa on 3 siirtotapaa (stdio, SSE, streamable-http) ja käyttöoikeusalueilla rajatut työkalut. Alla olevat hallintapaneelin päätepisteet lukevat tila- ja auditointitietoja sekä välittävät HTTP-siirtotapojen liikenteen.

Menetelmä	Polku	Kuvaus
GET	/api/mcp/status	Syke, siirtotapa, verkkotila, viimeisin kutsu, käytetyimmät työkalut, 24 tunnin onnistumisaste
GET	/api/mcp/tools	MCP-työkalujen luettelo, joka sisältää kentät name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Avaa SSE-virta SSE-siirtotapaa varten (palauttaa 503, jos MCP on poistettu käytöstä tai siirtotapa ei täsmää)
POST	/api/mcp/sse	Lähetä JSON-RPC-kehys SSE-siirtotavalla
GET	/api/mcp/stream	Avaa Streamable HTTP -siirtotavan SSE-puoli (palvelimen käynnistämät viestit)
POST	/api/mcp/stream	Lähetä JSON-RPC-kehys Streamable HTTP -siirtotavalla
DELETE	/api/mcp/stream	Päätä Streamable HTTP -istunto
GET	/api/mcp/audit	Hae auditointilokia — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Koostetut auditointitilastot (kokonaismäärät, onnistumisaste, keskimääräinen kesto, käytetyimmät työkalut)

Todennus: sse/stream-siirtotavat noudattavat MCP-kohtaista todennuskäytäntöä (Bearer API-avain, jolla on mcp-käyttöoikeusalue); status/tools/audit*-reitit ovat luettavissa hallintapaneelista (hallintapaneelin isäntäkoneen saavuttamisen lisäksi ei vaadita muuta todennusta).

Molempien HTTP-siirtotapojen käyttöä hallitsevat settings.mcpEnabled ja settings.mcpTransport — siirtotavan yhteensopimattomuus palauttaa 400, ja MCP:n käytöstä poistettu tila palauttaa 503.

---

A2A-palvelin

OmniRoute tarjoaa A2A (Agent-to-Agent) JSON-RPC 2.0 -päätepisteen sekä REST-kääreen tarkastelua ja koontinäyttökäyttöä varten.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # valinnainen, ellei OMNIROUTE_API_KEY ole asetettu
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Reititä tämä ohjelmointitehtävä"}]
  }
}

Tuetut metodit (kaikkien käyttö riippuu settings.a2aEnabled-asetuksesta):

Metodi	Kuvaus
message/send	Synkroninen taidon suoritus; palauttaa {task, artifacts, metadata}
message/stream	Saman taitojoukon suoratoistettu SSE-suoritus
tasks/get	Hakee tehtävän taskId-tunnuksella
tasks/cancel	Peruuttaa tehtävän taskId-tunnuksella

Sisäänrakennetut taidot: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Agenttikortti

GET /.well-known/agent.json

Palauttaa julkisen A2A-agenttikortin (nimi, kuvaus, ominaisuudet, taitoluettelo, todennusmenetelmä) — tallennetaan julkiseen välimuistiin 1 tunniksi. Todennusta ei vaadita.

REST-aputoiminnot

Metodi	Polku	Kuvaus
GET	/api/a2a/status	A2A:n käyttötila + tehtävätilastot + välimuistiin tallennetun agenttikortin yhteenveto
GET	/api/a2a/tasks	Listaa tehtävät — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Ei toteutettu REST-aputoimintona — luo JSON-RPC:n message/send-metodilla)
GET	/api/a2a/tasks/[id]	Hakee yhden tehtävän
POST	/api/a2a/tasks/[id]/cancel	Peruuttaa tehtävän

Todennus: REST-aputoiminnot toimivat ilman hallinnan todennusta (koontinäytön luettavissa); JSON-RPC-reitti /a2a käyttää Bearer OMNIROUTE_API_KEY -avainta, jos se on määritetty.

---

Pilvi, evaluaatiot ja arviointi

Metodi	Polku	Kuvaus
POST	/api/cloud/auth	Vahvistaa Bearer-avaimen ja palauttaa peitetyt palveluntarjoajayhteydet sekä pilvisynkronointiasiakkaiden mallialiakset
POST	/api/cloud/credentials/update	Päivittää pilveen synkronoidun palveluntarjoajan salatut tunnistetiedot
POST	/api/cloud/model/resolve	Selvittää loogista mallitunnusta vastaavan konkreettisen palveluntarjoajan ja mallin paikallisen reititystaulukon avulla
GET	/api/cloud/models/alias	Listaa pilvisynkronoinnille tarjotut mallialiakset
GET	/api/assess	Lukee uusimmat arviointiluokitukset (palveluntarjoaja- ja mallikohtaisesti)
POST	/api/assess	Suorittaa arvioinnin — runko: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Listaa sisäänrakennetut evaluaatiokokonaisuudet ja uusimmat suoritukset
POST	/api/evals	Käynnistää evaluaatiosuorituksen
POST	/api/evals/suites	Luo mukautetun evaluaatiokokonaisuuden — runko validoidaan evalSuiteSaveSchema-skeemalla
GET	/api/evals/suites/[id]	Hakee mukautetun evaluaatiokokonaisuuden

Todennus: /api/cloud/auth vahvistaa Bearer-avaimen suoraan; muut /api/cloud/*-, /api/evals/*- ja /api/assess-reitit edellyttävät hallintaistuntoa tai API-avainta. /api/assess-reitin POST käyttää validateBody-funktiota erotellun unionin scope-skeeman kanssa.

---

ACP:n (Agent Client Protocol) hallinta

aliprosesseina. Nämä päätepisteet hallitsevat ACP-agenttien tunnistusta ja mukautettujen agenttien rekisteröintiä.

Menetelmä	Polku	Kuvaus
GET	/api/acp/agents	Luettele kaikki tunnetut CLI-agentit (sisäänrakennetut ja mukautetut) sekä niiden asennustila, versio ja binääritiedosto
POST	/api/acp/agents	Rekisteröi mukautettu ACP-agentti tai päivitä välimuisti — runko: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} tai {action: "refresh"}
DELETE	/api/acp/agents	Poista mukautettu ACP-agentti — kyselyparametri: ?id=<agentId>

Vastausesimerkki (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
}

Todennus: Edellyttää hallintaistuntoa (hallintapaneelin auth_token-eväste) tai hallinnan laajuisen API-avaimen.

Täydelliset tiedot ovat kohdassa ACP-kehys.

---

Analytiikka ja havainnoitavuus

Reaaliaikaiset analytiikan päätepisteet reitityksen, pakkauksen ja palveluntarjoajien monipuolisuuden seurantaan. Ne tuottavat tiedot /dashboard/analytics/*-sivuille.

Automaattisen reitityksen analytiikka

Menetelmä	Polku	Kuvaus
GET	/api/analytics/auto-routing	Automaattisen reitityksen koostetut tilastot: kutsujen kokonaismäärä, strategia- ja tasojakaumat sekä suosituimmat palveluntarjoajat
GET	/api/analytics/auto-routing?days=7	Aikaikkunaan rajatut tilastot (oletusarvoisesti 24 h)

Vastausesimerkki:

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

Pakkausanalytiikka

Menetelmä	Polku	Kuvaus
GET	/api/analytics/compression	Pakkauksen koostetut tilastot: säästetyt tokenit, säästöprosentti, tilajakauma ja pakkausmoottorien käyttö

Vastausesimerkki:

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

Palveluntarjoajien monipuolisuuden seuranta

Menetelmä	Polku	Kuvaus
GET	/api/analytics/diversity	Shannonin entropiaan perustuva monipuolisuuden seuranta: ehkäisee yksittäisiä vikaantumispisteitä mittaamalla liikenteen jakautumista palveluntarjoajien kesken

Vastausesimerkki:

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

Todennus: Edellyttää hallintaistuntoa tai hallinnan laajuista API-avainta.

---

Ylläpitotoiminnot

Vain ylläpitäjille tarkoitetut operatiivisen hallinnan päätepisteet.

Menetelmä	Polku	Kuvaus
GET	/api/admin/concurrency	Lue nykyiset rinnakkaisuusrajat (globaalit + palveluntarjoajakohtaiset)
POST	/api/admin/concurrency	Päivitä rinnakkaisuusrajat — pyyntörunko: {global?: number, perProvider?: Record<string, number>}

Todennus: Edellyttää ylläpitäjän käyttöoikeustason hallintaistuntoa.

---

CLI-työkalujen hallinta

Hallitse OmniRouteen integroituvia CLI-työkaluja (antigravity, chipotle, commandCode, devin-cli jne.). Täydellinen luettelo on kohdassa Palveluntarjoajien viite.

Menetelmä	Polku	Kuvaus
GET	/api/cli-tools/all-statuses	Kaikkien CLI-työkalujen tila (asennettu, versio, viimeksi havaittu)
GET	/api/cli-tools/status	Yhden CLI-työkalun yksityiskohtainen tila (?tool=-kysely)
POST	/api/cli-tools/apply	Kirjoita työkalun luotu määritys (dryRun näyttää esikatselun; säilössä suoritettaessa 422 + containerEphemeralTarget; migration ilmoittaa vanhasta Codex YAML -muodosta)
GET	/api/cli-tools/backups	Luettele CLI-työkalujen määritysten varmuuskopiot
POST	/api/cli-tools/backups	Luo varmuuskopio kaikkien CLI-työkalujen määrityksistä
POST	/api/cli-tools/backups	Palauta: sama päätepiste palauttaa kyseisen varmuuskopion, kun pyyntörungossa on {tool, backupId}
GET	/api/cli-tools/antigravity-mitm	Antigravity MITM -välityspalvelimen tila (CLI-työkalu "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Määritä antigravity-mitm-aliakset

Todennus: Edellyttää hallintaistuntoa.

---

Agenttitaidot

Hallitse tekoälyagenttien taitoja (samankaltaisia kuin OpenAI:n mukautetut GPT:t, mutta agenteille).

Menetelmä	Polku	Kuvaus
GET	/api/agent-skills	Luettele kaikki agenttitaidot (sisäänrakennetut + mukautetut)
GET	/api/agent-skills/[id]	Hae tietty agenttitaito
POST	/api/agent-skills	Luo mukautettu agenttitaito — pyyntörunko: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Päivitä mukautettu agenttitaito
DELETE	/api/agent-skills/[id]	Poista mukautettu agenttitaito
GET	/api/agent-skills/[id]/raw	Hae käsittelemätön kehote + metatiedot (ei suoritusta)
POST	/api/agent-skills/generate	Luo uusi taito tekoälyllä luonnollisen kielen kuvauksen perusteella

Todennus: Edellyttää hallintaistuntoa tai hallintakäyttöön rajattua API-avainta.

---

Välimuistin hallinta

Hallitse semanttista välimuistia ja päättelyvälimuistia.

Menetelmä	Polku	Kuvaus
GET	/api/cache	Välimuistin yleiskatsaus: merkintöjen kokonaismäärä, osumaprosentti ja koko levyllä
GET	/api/cache/entries	Luettele välimuistissa olevat merkinnät (sivutuksella)
DELETE	/api/cache/entries	Poista välimuistimerkintöjä (suodata kyselyparametrien perusteella)
GET	/api/cache/stats	Yksityiskohtaiset välimuistitilastot (palveluntarjoajittain ja malleittain)
GET	/api/cache/reasoning	Päättelyvälimuistin tila (päättelyn uudelleentoistoa varten)
DELETE	/api/cache/reasoning	Tyhjennä päättelyvälimuisti — kyselyparametrit: ?toolCallId=<id> (yksi), ?provider=<p> tai ei parametreja (kaikki)

Todennus: Edellyttää hallintaistuntoa.

---

Muistijärjestelmä

Hallitse pysyvää muistia (FTS5 + vektoriupotukset).

Menetelmä	Polku	Kuvaus
GET	/api/memory	Luettele muistimerkinnät (suodata laajuuden, tyypin tai hakukyselyn perusteella)
POST	/api/memory	Luo uusi muistimerkintä — runko: {scope, type, content, metadata?}
GET	/api/memory/[id]	Hae tietty muistimerkintä
PUT	/api/memory/[id]	Päivitä muistimerkintä
DELETE	/api/memory/[id]	Poista muistimerkintä
GET	/api/memory?q=	Hae muistista (FTS5 + vektori) — tilastot sisältyvät samaan vastaukseen

Todennus: Edellyttää hallintaistuntoa tai hallintalaajuista API-avainta.

---

Webhookit

Hallitse tapahtumien webhook-tilauksia.

Menetelmä	Polku	Kuvaus
GET	/api/webhooks	Luettele kaikki webhook-tilaukset
POST	/api/webhooks	Luo webhook-tilaus — runko: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Hae tietty webhook-tilaus
PUT	/api/webhooks/[id]	Päivitä webhook-tilaus
DELETE	/api/webhooks/[id]	Poista webhook-tilaus
GET	/api/webhooks/[id]/deliveries	Luettele webhookin toimitushistoria (onnistuneiden ja epäonnistuneiden toimitusten loki)
POST	/api/webhooks/[id]/test	Lähetä testitapahtuma webhookiin

Todennus: Edellyttää hallintaistuntoa.

Katso kaikki tapahtumatyypit kohdasta Webhook-kehys.

---

Skills-kehys

Hallitse Skills-laajennuksia (agenttilaajennusten kehys).

Menetelmä	Polku	Kuvaus
GET	/api/skills	Luettele kaikki asennetut Skills-laajennukset (sisäänrakennetut ja mukautetut)
POST	/api/skills/install	Asenna Skill paikallisesta polusta tai URL-osoitteesta
DELETE	/api/skills/[id]	Poista Skill-asennus
PUT	/api/skills/[id]	Ota Skill käyttöön tai poista se käytöstä — runko: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Suorita Skill — runko: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Luettele kaikkien Skills-laajennusten suoritushistoria (suodata parametrilla ?apiKeyId=)

Todennus: Edellyttää hallintaistuntoa tai hallinnan laajuuden sisältävää API-avainta.

Katso täydelliset tiedot kohdasta Skills-kehys.

---

Liitännäiset

Hallitse OmniRoute-liitännäisiä (kolmannen osapuolen laajennuksia).

Menetelmä	Polku	Kuvaus
GET	/api/plugins	Luettele asennetut liitännäiset
POST	/api/plugins/marketplace/install	Asenna liitännäinen markkinapaikasta
DELETE	/api/plugins/[name]	Poista liitännäisen asennus
POST	/api/plugins/[name]/activate	Aktivoi liitännäinen
POST	/api/plugins/[name]/deactivate	Poista liitännäinen käytöstä
GET	/api/plugins/[name]/config	Hae liitännäisen määritykset
PUT	/api/plugins/[name]/config	Päivitä liitännäisen määritykset

Todennus: Edellyttää hallintaistuntoa.

Katso täydelliset tiedot kohdasta Liitännäiskehys.

---

Varjoreititys

Palveluntarjoajien varjo- tai A/B-vertailu ei ole itsenäinen REST-rajapinta — se määritetään yhdistelmäreitityksen kautta (katso Auto-Combo). Yhdistelmäkohtaiset vertailumittarit tarjoaa GET /api/combos/metrics.

---

Suojaukset

Tarkastele ajonaikaisia suojauksia (henkilötietojen tunnistus, kehotesyötteen manipuloinnin tunnistus ja kuvankäsittelyn silloitus). Suojaukset suoritetaan jokaiselle pyynnölle. Yksittäisen kutsun suojaukset voi poistaa käytöstä x-omniroute-disabled-guardrails-pyyntöotsakkeella — pysyvää käyttöönotto- tai käytöstäpoistorajapintaa ei ole.

Menetelmä	Polku	Kuvaus
GET	/api/guardrails	Luettele rekisteröidyt suojaukset ja niiden tila (nimi / käytössä / prioriteetti)
POST	/api/guardrails/test	Koekäytä kutsua edeltävä käsittelyketju esimerkkisyötteellä — runko: {input, disabledGuardrails?}

Todennus: Edellyttää hallintaistuntoa.

Katso täydelliset tiedot kohdasta Tietoturva > Suojaukset.

---

---

Todennus

Katso kohdasta Hallinnan todennus neljä tunnistetietoperhettä (hallintapaneelin istunto, paikallinen CLI-tunnus, oma_live_…-käyttöoikeustunnus, hallinnan käyttöoikeusalueen API-avain) ja niiden erot inferenssiavaimiin verrattuna.

• Hallintapaneelin reitit (/dashboard/*) käyttävät auth_token-evästettä
• Kirjautuminen käyttää tallennettua salasanatiivistettä; varajärjestelynä käytetään INITIAL_PASSWORD-arvoa
• requireLogin voidaan ottaa käyttöön tai poistaa käytöstä reitin /api/settings/require-login kautta
• /v1/*-reitit voivat edellyttää Bearer-API-avainta, kun REQUIRE_API_KEY=true
• Tässä viitteessä ”hallintatunnus” / ”hallinnan käyttöoikeusalueen API-avain” tarkoittaa yhtä kyseisessä oppaassa kuvatuista perheistä — ei erillistä määrittelemätöntä salaisuustyyppiä

Rikkova muutos (v3.8.0) — /api/v1/agents/tasks/* ja käyttökatkon hallintapäätepisteet edellyttävät nyt hallinnan todennusta (hallintapaneelin auth_token-evästettä tai hallinnan käyttöoikeusalueen API-avainta). Asiakasohjelmat, jotka aiemmin kutsuivat näitä reittejä ilman todennusta, saavat vastauksen 401 Unauthorized. Katso commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).