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

API Reference (Polski)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇹 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

---

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

Podstawowa dokumentacja referencyjna interfejsu API OmniRoute. Obejmuje publiczne punkty końcowe /v1 oraz najczęściej używane punkty końcowe zarządzania; kompletnymi źródłami informacji są dokument docs/openapi.yaml w formacie przeznaczonym do odczytu maszynowego oraz drzewo tras w katalogu src/app/api/.

---

Spis treści

• Uzupełnienia czatu
• Wyłączne dzierżawy zarządzanych sesji
• Osadzenia
• Generowanie obrazów
• OCR dokumentów
• Lista modeli
• Manifest wtyczki dostawcy
• Punkty końcowe zgodności
• API plików
• API zadań wsadowych
• API wyszukiwania
• Strumieniowanie WebSocket
• Limity i zgłaszanie problemów
• Pamięć podręczna semantyczna
• Panel i zarządzanie
• Zarządzanie kombinacjami
• Webhooki
• Zarejestrowane klucze (automatyczne zarządzanie)
• Protokół agentów
• Serwery proxy zarządzania
• Odporność (rozszerzona)
• Umiejętności
• Pamięć
• Serwer MCP
• Serwer A2A
• Chmura, ewaluacje i ocena
• Przetwarzanie żądań
• Uwierzytelnianie

---

Uzupełnienia czatu

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
}

Nagłówki niestandardowe

Nagłówek	Kierunek	Opis
X-OmniRoute-No-Cache	Żądanie	Ustaw na true, aby ominąć pamięć podręczną
x-omniroute-no-memory	Żądanie	Ustaw na true, aby pominąć wstrzykiwanie pamięci i umiejętności dla tego żądania (działa analogicznie do opcji bez pamięci podręcznej; pozwala uniknąć narzutu tokenów i kosztów dla każdego wywołania)
X-OmniRoute-Progress	Żądanie	Ustaw na true, aby otrzymywać zdarzenia postępu
X-Session-Id	Żądanie	Stały klucz sesji dla zewnętrznego przypisania sesji
x_session_id	Żądanie	Akceptowany jest również wariant z podkreśleniami (bezpośredni HTTP)
X-OmniRoute-Session-Id	Żądanie	Znacznik sesji/konwersacji podany przez wywołującego (przekazywany również do pamięci). Jeśli jest obecny, zostaje zapisany bez zmian w call_logs.session_tag na potrzeby przypisywania kosztów do sesji (#8249) — nigdy nie jest generowany, gdy go brak
Idempotency-Key	Żądanie	Klucz deduplikacji (okno 5 s)
X-Request-Id	Żądanie	Alternatywny klucz deduplikacji
X-OmniRoute-Cache	Odpowiedź	HIT lub MISS (bez strumieniowania)
X-OmniRoute-Idempotent	Odpowiedź	true, jeśli wykonano deduplikację
X-OmniRoute-Progress	Odpowiedź	enabled, jeśli śledzenie postępu jest włączone
X-OmniRoute-Session-Id	Odpowiedź	Efektywny identyfikator sesji używany przez OmniRoute
X-OmniRoute-Request-Id	Odpowiedź	Identyfikator korelacji żądania (jeśli jest znany)
X-OmniRoute-Version	Odpowiedź	Wersja kompilacji OmniRoute (zawsze obecna)
X-OmniRoute-Cost-Saved	Odpowiedź	Kwota w USD zaoszczędzona dzięki pamięci podręcznej przy HIT (tylko trafienia w pamięci podręcznej)
X-OmniRoute-Decision	Odpowiedź	Ślad routingu: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> to strategia kombinacji lub single w przypadku żądania bez kombinacji) — zawsze obecny w odpowiedziach końcowych

Uwaga dotycząca Nginx: jeśli korzystasz z nagłówków zawierających podkreślenia (na przykład x_session_id), włącz underscores_in_headers on;.

Nagłówki telemetrii kosztów: odpowiedzi zakończone powodzeniem, które nie są strumieniowane, również zawierają zestaw nagłówków telemetrii kosztów X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, stała liczba 10 miejsc po przecinku; 0.0000000000 w przypadku usług bezpłatnych lub bez określonej ceny), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit oraz X-OmniRoute-Fallback-Attempts (tylko gdy > 0), a także X-OmniRoute-Request-Id i X-OmniRoute-Version. Są one emitowane przez uzupełnienia czatu, /v1/responses, /v1/messages, a także punkty końcowe multimediów — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations i /v1/moderations (koszt zawsze wynosi 0). Koszt multimediów jest obliczany według modalności (za obraz, sekundę, znak lub jednostkę wyszukiwania), jeśli cennik jest dostępny; w przeciwnym razie wynosi 0 (tryb fail-open).

Semantyka kosztów trafienia w pamięci podręcznej: w przypadku TRAFIENIA w semantycznej pamięci podręcznej (X-OmniRoute-Cache-Hit: true) nie jest wykonywane żadne wywołanie do dostawcy nadrzędnego, dlatego wartość X-OmniRoute-Response-Cost wynosi 0.0000000000 (przyrostowy koszt obsłużenia trafienia). Pierwotny koszt lub koszt, który zostałby poniesiony, jest raportowany oddzielnie w nagłówku X-OmniRoute-Cost-Saved. Systemy rozliczeniowe powinny sumować wartości X-OmniRoute-Response-Cost (trafienia nic nie kosztują), natomiast systemy analityczne pamięci podręcznej mogą agregować wartości X-OmniRoute-Cost-Saved.

Wyłączne dzierżawy zarządzanych sesji

Wyłączne dzierżawienie zarządzanych sesji to opcjonalny, niezależny od klienta kontrakt routingu: jeden aktywny właściciel utrzymuje jedno kwalifikujące się połączenie OmniRoute. Nie obejmuje ono dzierżawy modelu, nie wymaga OAuth, nie identyfikuje konkretnego klienta ani nie wymaga konkretnego dostawcy.

Uwierzytelniający klucz API musi mieć zakres lease:exclusive oraz jawną, niepustą listę allowedConnections. Granica mutacji bazy danych wymusza obecność obu pól zarówno podczas tworzenia klucza, jak i jego częściowych aktualizacji.

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

Pomyślne odpowiedzi na uzyskanie, odnowienie i zwolnienie dzierżawy zawierają znaczniki czasu, state oraz dokładną dodatnią wartość generation, ale nigdy wybrane połączenie ani dane uwierzytelniające. W przypadku odnowienia i zwolnienia generacja jest przekazywana w treści JSON:

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

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

Właściciel aktywnej dzierżawy może jawnie zażądać bezpiecznych pod względem prywatności metadanych wyświetlania dotyczących jego bieżącego powiązania:

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

Ta opcjonalna akcja sprawdzania stanu jest zabezpieczona przez nieprzejrzysty identyfikator właściciela, uwierzytelniony zarządzany klucz API oraz dokładną aktywną generację w ramach jednej transakcji bazy danych. displayName zawiera wyłącznie przyciętą skonfigurowaną nazwę połączenia; ma wartość null, gdy nie istnieje bezpieczna skonfigurowana nazwa. OmniRoute nigdy nie zastępuje jej adresem e-mail ani wygenerowaną tożsamością konta. Wartość dostawcy jest niewrażliwą etykietą wyświetlaną i nigdy nie jest wygenerowanym identyfikatorem kompatybilnego dostawcy. Dane uwierzytelniające, tokeny, pliki cookie, nieprzetworzone identyfikatory połączeń lub kluczy API, skróty właścicieli, sekrety odgradzające oraz wewnętrzne dane routingu są wykluczone.

Wyszukiwania z nieprawidłowym kluczem, nieprawidłowym właścicielem, nieaktualną generacją, a także dotyczące brakujących, wygasłych, zwolnionych lub unieważnionych dzierżaw zwracają ten sam błąd 409 LEASE_FENCE_STALE bez metadanych połączenia. Klient, który otrzymał odpowiedź nakazującą oczekiwanie na dostępność, nie ma aktywnego powiązania, które mógłby sprawdzić. Gdy routing przełącza aktywną dzierżawę, ta sama generacja pozostaje ważna, a stan niepodzielnie zwraca nowe powiązanie, nigdy stare. Istniejący klienci pozostają bez zmian, ponieważ odpowiedzi dotyczące uzyskania, odnowienia, zwolnienia i oczekiwania zachowują dotychczasowy format.

Ten kontrakt serwera nie zmienia standardowego punktu /status w OpenAI Codex. Standardowy Codex raportuje obecnie swojego dostawcę modelu oraz wbudowany stan uwierzytelniania/konta, ale nie wyświetla dowolnych niestandardowych metadanych konta dostawcy; przyszła integracja klienta musi wywołać tę akcję i zdecydować, jak wyświetlić connection.displayName.

Każde żądanie zarządzanego wnioskowania przekazuje następnie oba nagłówki sterujące:

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

Dokładny właściciel, generacja, aktywne połączenie oraz uwierzytelniony klucz API są weryfikowane bezpośrednio przed każdą obsługiwaną próbą wysłania żądania do usługi nadrzędnej. Ponowne użycie właściciela i generacji z innym kluczem kończy się niepowodzeniem, nawet gdy ten klucz zezwala na to samo połączenie. Nieprzetworzone identyfikatory właścicieli nie są utrwalane, rejestrowane, zachowywane w migawce żądania ani przekazywane do usługi nadrzędnej.

Tymczasowy konflikt zasobów zwraca HTTP 429 z nagłówkiem Retry-After oraz:

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

Ta odpowiedź oznacza jedynie, że zwykły zbiór kwalifikujących się połączeń był niepusty, a każdy wolny kandydat był zajęty przez obcą aktywną dzierżawę. Nieobsługiwane modele/dostawcy, niezgodność z zasadami, okresy oczekiwania, limity, stan działania oraz inne zwykłe niepowodzenia kwalifikacji zachowują dotychczasowe odpowiedzi OmniRoute.

x-omniroute-compression

Nadpisanie planu kompresji dla pojedynczego żądania. Ma najwyższy priorytet — zastępuje nadpisanie kombinacji routingu, aktywny profil, automatyczny wyzwalacz oraz ustawienie Default panelu. Wartości:

Wartość	Efekt
off	Brak kompresji dla tego żądania.
default	Profil Default pochodzący z panelu (ignoruje aktywny profil).
engine:<id>	Pojedynczy silnik, jeśli jest włączony, np. engine:rtk.
<combo>	Nazwana kombinacja, dopasowywana najpierw według nazwy (bez rozróżniania wielkości liter), a następnie według identyfikatora.

Uwagi:

• Nieznane wartości są ignorowane (żądanie nigdy nie jest odrzucane); rozstrzyganie przechodzi do standardowej kolejności priorytetów operatora.
• Jeśli wiele kombinacji ma tę samą nazwę, przekaż id kombinacji, aby uzyskać deterministyczne dopasowanie.
• Kombinacji o nazwie off lub default nie można wybrać według nazwy (te słowa kluczowe są interpretowane jako pierwsze); odwołuj się do takiej kombinacji za pomocą jej identyfikatora.
• Główny przełącznik kompresji stanowi bezwzględną blokadę: gdy kompresja jest globalnie wyłączona, ten nagłówek nie może jej włączyć.

Zastosowany plan jest zwracany w nagłówku odpowiedzi:

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

gdzie <source> przyjmuje jedną z wartości request-header, routing-override, active-profile, auto-trigger, default lub off.

---

Embeddingi

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

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

Dostępni dostawcy: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

Identyfikatory katalogowe mają postać provider/model (przykład: jina-ai/jina-embeddings-v5-omni-small). Same identyfikatory modeli Jina występujące w rejestrze (na przykład jina-embeddings-v5-text-small, jina-reranker-v3.5) również są rozpoznawane. Operacje embed/rerank/classify/segment Jina używają najpierw danych uwierzytelniających jina-ai z panelu; JINA_AI_API_KEY jest używany awaryjnie tylko wtedy, gdy w panelu nie ma klucza. Karta jina-reader służy wyłącznie do obsługi Reader / r.jina.ai (POST /v1/web/fetch) i nigdy nie udostępnia embeddingów ani ponownego rankingowania.

Modele w rejestrze deklarujące obsługę multimodalną akceptują również do 32 ustrukturyzowanych elementów niezależnych od dostawcy. Typy elementów multimedialnych to text, image, audio, video i document. Ich pole source ma postać {"type":"url","url":"https://..."} albo {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano oraz alias rodziny jina-ai/jina-embeddings-v5-omni → omni-small) akceptuje również natywne dokumenty EmbeddingsV5Request Jina i przekazuje je bez zmian do 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,..." }]
    }
  ]
}

Natywne wartości { image | audio | video | pdf } mogą być publicznym adresem URL HTTPS, identyfikatorem URI data: albo nieprzetworzonymi danymi base64. OmniRoute nie konwertuje tych obiektów na ciągi znaków ani nie pobiera natywnych adresów URL obrazów — Jina samodzielnie pobiera publiczne multimedia. Dodatkowe pola Jina (task, normalized, truncate, embedding_type) są przekazywane dalej. Jednostki SKU Jina obsługujące wyłącznie tekst nadal odrzucają dokumenty nietekstowe.

Ograniczenia bezpieczeństwa i transportu:

• Zdalne adresy URL multimediów muszą być publicznymi adresami HTTPS. Kanoniczne elementy {type,source:url} są pobierane po stronie serwera (ponowna walidacja przekierowań, limit czasu, limity rozmiaru, publiczny DNS, przypięcie połączenia) i osadzane przed wywołaniem dostawcy. Natywne elementy Jina {image:"https://..."} są przekazywane bez zmian po tej samej kontroli publicznego adresu HTTPS; Jina pobiera adres URL.
• Wbudowane multimedia base64 są ograniczone do 8 MiB zdekodowanych danych na element oraz 16 MiB zdekodowanych danych w całym żądaniu.

Tłumaczenie formatu dostawcy (elementy kanoniczne nigdy nie są przekazywane bez zmian):

• Modele multimodalne Jina: każdy element najwyższego poziomu staje się jednym obiektem z kluczem modalności (text / image / audio / video / pdf), używającym identyfikatorów URI danych dla wbudowanych multimediów; jeden wektor na element najwyższego poziomu.
• Rodzina Gemini Embedding 2: jedna tablica najwyższego poziomu staje się pojedynczym natywnym żądaniem models/{model}:embedContent z content.parts (text albo inline_data).
• Nieznane/dynamiczne modele bez jawnych metadanych modalności odrzucają ustrukturyzowane dane wejściowe z kodem 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"
}

Nieobsługiwane kombinacje modelu i modalności zwracają kod HTTP 400 zamiast wymuszać konwersję elementu. Pola rozszerzeń niezwiązane z danymi wejściowymi w starszych żądaniach zawierających ciągi znaków/tokeny nadal są przekazywane bez zmian.

# Wyświetl wszystkie modele embeddingów
GET /v1/embeddings

---

Generowanie obrazów

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

Dostępni dostawcy: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (lokalnie), ComfyUI (lokalnie).

# Wyświetl wszystkie modele obrazów
GET /v1/images/generations

---

OCR dokumentów

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 wybiera dostawcę OCR za pomocą prefiksu provider/model; sam identyfikator modelu (np. mistral-ocr-latest) jest przypisywany do zarejestrowanego dostawcy, a w przypadku pominięcia model domyślnie używany jest Mistral (mistral-ocr-latest). Zarejestrowani dostawcy (open-sse/config/ocrRegistry.ts):

Identyfikator dostawcy	Identyfikator modelu	Wartość model	Uwagi
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (lub samo mistral-ocr-latest)	Synchroniczny — odpowiedź jest zwracana bezpośrednio z pojedynczego wywołania usługi nadrzędnej.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Asynchroniczna usługa nadrzędna (analyze + odpytywanie) — patrz poniżej.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Synchroniczny, za pośrednictwem partnerskiego punktu końcowego Vertex AI openapi/chat/completions — informacje o uwierzytelnianiu/adresie URL znajdują się poniżej.

Wszyscy trzej dostawcy zwracają odpowiedź w tym samym formacie co Mistral:

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

Przepływ odpytywania Azure Document Intelligence

Interfejs API analyze usługi Azure Document Intelligence działa asynchronicznie: początkowe żądanie zwraca nagłówek Operation-Location zamiast treści, a następnie trzeba cyklicznie odpytywać o wynik. Procedura obsługi (open-sse/handlers/ocr.ts) odpytuje ten adres URL co sekundę, wykonując maksymalnie 30 prób, natychmiast kończy się błędem (bez dalszego odpytywania) w przypadku odpowiedzi odpytywania innej niż ok lub statusu "failed" oraz zwraca 504, jeśli operacja nadal trwa po wyczerpaniu limitu prób. Końcowa odpowiedź Azure jest normalizowana do tego samego formatu pages/markdown, którego używa Mistral, zanim zostanie zwrócona wywołującemu, dzięki czemu kod klienta nie musi obsługiwać tego dostawcy w sposób specjalny.

Uwierzytelnianie i rozpoznawanie punktu końcowego Vertex AI DeepSeek OCR

vertex-deepseek-ocr ponownie wykorzystuje ten sam mechanizm uwierzytelniania Vertex AI, który OmniRoute obsługuje już dla ruchu czatu/obrazów (open-sse/executors/vertex.ts): klucz API połączenia jest albo poświadczeniem JSON konta usługi (wymienianym na krótkotrwały token dostępu OAuth za pomocą przepływu JWT bearer), albo gotowym tokenem dostępu OAuth używanym bez zmian. Adresem URL punktu końcowego usługi nadrzędnej jest ogólny partnerski punkt końcowy Vertex openapi/chat/completions, utworzony na podstawie projektu i regionu połączenia — jawnie określone providerSpecificData.project/providerSpecificData.region zawsze mają pierwszeństwo; w przeciwnym razie projekt jest pobierany z project_id w danych JSON konta usługi, a domyślnym regionem jest us-central1. Oba te parametry są rozpoznawane w open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl) i używane przez src/app/api/v1/ocr/route.ts przed przekazaniem do handleOcr.

---

Lista modeli

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

→ Zwraca wszystkie modele czatu, osadzania i obrazów oraz ich kombinacje w formacie OpenAI

Prefiksy identyfikatorów modeli (?prefix=)

Większość modeli jest udostępniana z prefiksem dostawcy. To, który prefiks otrzymasz, jest kontrolowane przez flagę funkcji MODELS_CATALOG_PREFIX_MODE i może zostać nadpisane dla każdego żądania za pomocą parametru zapytania — jest to przydatne dla klienta, który chce otrzymać uporządkowaną listę bez zmieniania ustawienia obejmującego cały serwer dla wszystkich pozostałych użytkowników:

GET /v1/models?prefix=alias        # jeden identyfikator na model — krótki prefiks aliasu
GET /v1/models?prefix=dual         # obie formy (ustawienie domyślne serwera)
GET /v1/models?prefix=canonical    # tylko pełny prefiks identyfikatora dostawcy

Tryb	Zwraca	Uwagi
dual	cc/claude-sonnet-4-6 oraz claude/claude-sonnet-4-6	Domyślny. Oba identyfikatory kierują do tego samego modelu; zachowano je, aby konfiguracje klientów z zakodowaną na stałe dowolną z tych form nadal działały. W przybliżeniu podwaja rozmiar katalogu.
alias	cc/claude-sonnet-4-6	Jeden wpis na model. Dostawcy bez odrębnego aliasu nadal zwracają swój wpis, więc nic nie zostaje pominięte.
canonical	claude/claude-sonnet-4-6	Jeden wpis na model z pełnym prefiksem identyfikatora dostawcy. Dostawcy bez odrębnego aliasu (np. antigravity/…, agy/…) również zwracają tutaj swój pojedynczy identyfikator, więc nic nie zostaje pominięte.

Kopię lustrzaną działającą w trybie dual można również rozpoznać bez parametru zapytania: zawiera pole parent wskazujące główny identyfikator.

Klienci wyświetlający selektor modeli powinni wysyłać żądanie z ?prefix=alias — tak działa rozszerzenie OmniCopilot dla VS Code.

Warianty modeli bez rozumowania

W przypadku modeli Claude obsługujących rozumowanie endpoint /v1/models udostępnia również wariant bez rozumowania, którego identyfikator jest poprzedzony prefiksem claude-3-omniroute-no-thinking/:

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

Wybranie tego identyfikatora (np. w konfiguracji Claude Code, która zawsze dołącza blok thinking) powoduje ponowne wskazanie rzeczywistego modelu <provider>/<model> z wyłączonym rozumowaniem — przez thinking:{type:"disabled"} w ścieżce /v1/messages albo pominięcie pól reasoning/reasoning_effort w ścieżce /v1/chat/completions. Wariant jest wyświetlany tylko dla modeli z rodziny Claude, które obsługują rozumowanie i respektują wartość disabled (dlatego wykluczone są np. modele działające wyłącznie w trybie adaptacyjnym, które odrzucają disabled). Operatorzy mogą wymusić włączenie lub wyłączenie tego wariantu dla poszczególnych modeli za pomocą ModelSpec.noThinkingAlias.

---

Manifest wtyczki dostawcy

GET /api/v1/provider-plugin-manifest

Zwraca bezpieczny dla formatu JSON manifest wtyczek dostawców używany przez Bifrost, CLIProxyAPI i przyszłe routery typu sidecar. Odpowiedź jest generowana na podstawie rejestru dostawców TypeScript i celowo nie zawiera sekretów klientów OAuth, rozwiązywania środowiska wykonawczego, funkcji wykonawczych, nagłówków żądań ani danych kont.

Użyj tego punktu końcowego, gdy sidecar działa poza procesem i nie może bezpośrednio zaimportować pliku open-sse/config/providerPluginManifestRegistry.ts.

---

Punkty końcowe zgodności

Metoda	Ścieżka	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 (edycja/uzupełnianie)
POST	/v1/videos/generations	Generowanie wideo w stylu OpenAI
POST	/v1/music/generations	Generowanie muzyki w stylu OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (zwraca treść audio)
POST	/v1/rerank	Ponowne rankingowanie w stylu Cohere/Voyage
POST	/v1/classify	Klasyfikacja Jina (api.jina.ai)
POST	/v1/segment	Segmentator Jina (segment.jina.ai)
POST	/v1/moderations	OpenAI Moderations
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	Alias katalogu OpenAI
GET	/api/v1/vscode/{token}/models	Alias modeli OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Tokenizowany alias OpenAI
POST	/api/v1/vscode/{token}/responses	Tokenizowany alias OpenAI Responses
POST	/api/v1/vscode/{token}/api/chat	Tokenizowany alias Ollama
GET	/api/v1/vscode/{token}/api/tags	Tokenizowany alias tagów Ollama

Wszystkie trasy POST mają taką samą strukturę: Bearer your-api-key + treść JSON zweryfikowana przez Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema itd.; zobacz src/shared/validation/schemas.ts). W przypadku niepowodzenia walidacji schematu zwracany jest kod 4xx.

W przypadku klientów, które nie mogą dołączyć nagłówka Authorization: Bearer ..., OmniRoute akceptuje również klucze API w adresie URL — za pośrednictwem parametrów zapytania zapewniających zgodność (?token=..., ?apiKey=..., ?api_key=..., ?key=...) lub dedykowanych punktów końcowych /api/v1/vscode/{token}/... opisanych poniżej.

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

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

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

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

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

# TTS — zwraca treść audio/mpeg (lub w żądanym formacie)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

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

# Generowanie wideo / muzyki (identyfikator modelu z prefiksem dostawcy)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Dedykowane trasy dostawców

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

Prefiks dostawcy jest dodawany automatycznie, jeśli go brakuje. Niezgodne modele powodują zwrócenie kodu 400.

---

API plików

Endpoint plików zgodny z OpenAI, przeznaczony do wsadowych danych wejściowych/wyjściowych oraz przesyłania plików o określonym przeznaczeniu.

Metoda	Ścieżka	Opis
POST	/v1/files	Prześlij plik (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — maks. 512 MiB
GET	/v1/files	Wyświetl listę plików dla uwierzytelnionego klucza API
GET	/v1/files/[id]	Pobierz metadane pliku
DELETE	/v1/files/[id]	Usuń plik
GET	/v1/files/[id]/content	Prześlij strumieniowo surową zawartość pliku

Uwierzytelnianie: klucz API typu Bearer — pliki są przypisywane do poszczególnych kluczy API za pomocą getApiKeyRequestScope. Klucz może wyświetlać, pobierać i usuwać wyłącznie własne pliki; sesja panelu bez klucza ma dostęp do odczytu całej instancji; dostęp do pliku bez właściciela (przesłanego anonimowo lub w ramach sesji panelu) jest odrzucany dla każdego wywołującego bez sesji. GET /v1/files odrzuca anonimowego wywołującego — oraz podany klucz, którego nie można rozpoznać — z kodem 401, nawet gdy REQUIRE_API_KEY=false, zamiast wyświetlać pliki wszystkich dzierżawców (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

API przetwarzania wsadowego

Przetwarzanie wsadowe zgodne z OpenAI.

Metoda	Ścieżka	Opis
POST	/v1/batches	Utwórz zadanie wsadowe — treść weryfikowana przez v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Wyświetl listę zadań wsadowych
GET	/v1/batches/[id]	Pobierz stan zadania wsadowego oraz request_counts
DELETE	/v1/batches/[id]	Usuń ukończone lub zakończone niepowodzeniem zadanie wsadowe
POST	/v1/batches/[id]/cancel	Anuluj trwające zadanie wsadowe

Uwierzytelnianie: klucz API typu Bearer. Zadania wsadowe są przypisywane do poszczególnych kluczy API zgodnie z tą samą trójwariantową regułą co pliki: dostęp wyłącznie dla własnego klucza, dostęp do całej instancji dla sesji panelu, rekordy bez właściciela niedostępne dla każdego wywołującego bez sesji (pobieranie, usuwanie, anulowanie oraz sprawdzanie input_file_id podczas tworzenia). GET /v1/batches odrzuca anonimowego wywołującego z kodem 401, nawet gdy REQUIRE_API_KEY=false.

---

API wyszukiwania

Abstrakcja dostawców wyszukiwania internetowego (Tavily, Brave, Exa, Serper itd.).

Metoda	Ścieżka	Opis
GET	/v1/search	Wyświetla skonfigurowanych dostawców wyszukiwania i ich możliwości
POST	/v1/search	Wykonuje zapytanie wyszukiwania — treść walidowana przez v1SearchSchema, obsługuje pamięć podręczną i koalescencję
GET	/v1/search/analytics	Statystyki trafień, opóźnień i pamięci podręcznej dla poszczególnych dostawców

Uwierzytelnianie: Klucz API typu Bearer (extractApiKey + isValidApiKey). Zasady wyszukiwania są egzekwowane przez enforceApiKeyPolicy.

---

API pobierania stron internetowych

Wyodrębnia zawartość z adresu URL za pośrednictwem skonfigurowanego dostawcy pobierania stron internetowych (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Metoda	Ścieżka	Opis
POST	/v1/web/fetch	Pobiera/ekstrahuje adres URL — treść walidowana przez v1WebFetchSchema

Uwierzytelnianie: Klucz API typu Bearer (extractApiKey + isValidApiKey). Zasady są egzekwowane przez enforceApiKeyPolicy.

Mechanizm rezerwowy uwzględniający limity (#8297): gdy nie podano jawnie provider, pula (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) jest przechodzona w ustalonej kolejności priorytetów (fill-first) — skonfigurowany dostawca objęty limitem żądań jest pomijany zamiast natychmiastowego przerywania żądania, a ponawialny błąd dostawcy nadrzędnego lub przekroczenie limitu (HTTP 429 zawsze; 402/403 dla bezpłatnych planów Firecrawl/Tavily/TinyFish z limitami — nie dla Jina Reader i nigdy dla zwykłego błędnego żądania 400) powoduje przejście w czasie wykonywania żądania do następnego jeszcze niewypróbowanego dostawcy z poświadczeniami. Gdy wszyscy dostawcy w puli zostaną wyczerpani, punkt końcowy zwraca pojedynczy kod 429 (z nagłówkiem Retry-After) zamiast wcześniejszego ogólnego kodu 400. Gdy jawnie zażądano określonego provider, nie następuje niejawne przełączenie awaryjne — jawnie wskazany dostawca objęty limitem lub zgłaszający błąd zwraca własny błąd (429, jeśli objęty limitem, w przeciwnym razie status dostawcy nadrzędnego).

---

Strumieniowanie przez WebSocket

GET /v1/ws?handshake=1

Waliduje uzgadnianie aktualizacji połączenia do WebSocket i zwraca przykładowe komunikaty protokołu przewodowego (request, cancel). Rzeczywiste ramki WS są obsługiwane przez dołączony serwer WS poza tabelą tras Next.js.

Uwierzytelnianie: Klucz API typu Bearer podczas uzgadniania połączenia.

Responses API przez WebSocket (tylko codex)

# Ten sam host:port co API HTTP (domyślnie 20128); zaktualizuj połączenie:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (lub: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Pierwszą ramką MUSI być response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Serwer proxy Responses-API-over-WebSocket jest połączony wyłącznie z codex (backend ChatGPT). Nasłuchuje na tym samym porcie co API/pulpit na ścieżkach /v1/responses, /responses i /api/v1/responses. Po otrzymaniu pierwszej ramki response.create uwierzytelnia i przygotowuje połączenie za pośrednictwem wewnętrznego mostu codex-responses-ws, wybiera połączenie OAuth codex i tuneluje do wss://chatgpt.com/backend-api/codex/responses za pośrednictwem transportu wreq-js. Modele inne niż codex są odrzucane (codex_ws_provider_required). Do routingu udziałów limitu użyj model: "qtSd/<group>/codex/<model>". Zaimplementowano w app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Uwierzytelnianie: Klucz API typu Bearer podczas uzgadniania połączenia. Dołączony serwer HTTP (server-ws.mjs) musi być aktywnym punktem wejścia (jest nim domyślnie, gdy istnieje app/server-ws.mjs).

Identyfikator modelu: użyj samego identyfikatora ChatGPT (bez prefiksu codex/)

OpenAI Codex CLI waliduje nazwę modelu po stronie klienta, gdy supports_websockets = true, i odrzuca identyfikatory z prefiksem dostawcy, takie jak codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Wyślij sam identyfikator (np. gpt-5.5). Most OmniRoute obsługuje wyłącznie codex, dlatego przed tunelowaniem do dostawcy nadrzędnego ponownie rozpoznaje sam identyfikator jako model codex (resolveCodexWsModelInfo) — nawet jeśli sam identyfikator gpt-5.5 byłby w przeciwnym razie kierowany przez HTTP do innego dostawcy.

Konfigurowanie OpenAI Codex CLI

Skieruj Codex CLI do OmniRoute, dodając niestandardowego dostawcę z obsługą WebSocket do ~/.codex/config.toml (użyj osobnego CODEX_HOME, aby uniknąć modyfikowania istniejącej konfiguracji):

model = "gpt-5.5"                 # sam identyfikator — NIE "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # bez końcowego ukośnika; adres URL WS jest wyprowadzany automatycznie (w środowisku produkcyjnym użyj https/wss)
wire_api = "responses"                    # jedyna obsługiwana wartość od lutego 2026 r.
supports_websockets = true                # włącza transport Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # zawiera klucz API OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # klucz API OmniRoute (dowolny klucz, jeśli REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI aktualizuje base_url + /responses do połączenia WebSocket, a OmniRoute tuneluje je do wybranego połączenia OAuth codex. Zweryfikowano kompleksowo względem lokalnego serwera: ChatGPT zwraca codex.rate_limits + response.created i strumieniuje odpowiedź.

---

Limity i zgłaszanie problemów

Metoda	Ścieżka	Opis
GET	/v1/quotas/check	Wstępnie sprawdza limit dla provider + accountId przed wydaniem zarejestrowanego klucza
POST	/v1/issues/report	Zgłasza do GitHub błąd dotyczący limitu lub wydania klucza (wymaga GITHUB_ISSUES_REPO + tokenu)

Uwierzytelnianie: klucz API typu Bearer (isAuthenticated).

---

Samoobsługowe sprawdzanie użycia (/api/usage/om-usage)

Każdy klucz API może odczytywać własne użycie i limity — bez uwierzytelniania administracyjnego. Jest to punkt końcowy używany przez klienta (CLI, panel OmniCopilot) do wyświetlania właścicielowi klucza jego wydatków.

# Forma tekstowa (historyczny kontrakt — zwykły tekst przeznaczony dla terminala)
curl -H "Authorization: Bearer <twój-klucz-api>" \
  http://localhost:20128/api/usage/om-usage

# Forma ustrukturyzowana — używana przez interfejs użytkownika
curl -H "Authorization: Bearer <twój-klucz-api>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Klucz musi mieć włączoną opcję allowUsageCommand (domyślnie jest wyłączona — menedżer kluczy API w panelu przełącza ją osobno dla każdego klucza). Bez niej punkt końcowy odpowiada kodem 403.

?format=json zwraca rozróżnialną strukturę, dzięki czemu wywołujący nigdy nie odczytuje pola danych z odpowiedzi odmownej. W przypadku powodzenia:

{
  "allowed": true,
  // obecne tylko wtedy, gdy dla klucza włączono indywidualne limity użycia (dzienne/tygodniowe w USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // migawka limitu wybranego dostawcy lub null, jeśli nic nie znajduje się jeszcze w pamięci podręcznej:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // migawka każdego połączenia, aby interfejs użytkownika mógł wyświetlić kilku dostawców obok siebie:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

W przypadku odmowy (401 — nieprawidłowy klucz / 403 — brak uprawnień) ta sama trasa zwraca { "allowed": false, "error": { "message": "…" } } — obecne, ale puste pole personal/provider (klucz ma uprawnienia, ale nie uzyskano jeszcze żadnych danych) oznacza inny stan niż odmowa, a rozróżnia je wyłącznie forma JSON.

Uwierzytelnianie: własny klucz API typu Bearer wywołującego, weryfikowany za pomocą isValidApiKey — nie jest to interfejs administracyjny (/api/keys/…), który pozostaje chroniony przez requireManagementAuth.

---

Semantyczna pamięć podręczna

# Pobierz statystyki pamięci podręcznej
GET /api/cache/stats

# Wyczyść wszystkie pamięci podręczne
DELETE /api/cache/stats

Przykład odpowiedzi:

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

Wpływ na opóźnienie

TRAFIENIE w semantycznej pamięci podręcznej powoduje zwrócenie odpowiedzi z pamięci podręcznej bez wywołania usługi nadrzędnej, dlatego zgłaszana wartość X-OmniRoute-Response-Latency jest bliska zeru (niezależnie od pierwotnego opóźnienia usługi nadrzędnej). Klienci wrażliwi na opóźnienia (testy wydajności, monitorowanie p50/p99) powinni sprawdzać nagłówek odpowiedzi X-OmniRoute-Cache-Latency:

Wartość	Znaczenie
synthetic	Odpowiedź zwrócona z pamięci podręcznej; opóźnienie nie jest rzeczywistym czasem usługi nadrzędnej
(brak)	Odpowiedź z rzeczywistego wywołania usługi nadrzędnej

Pomijanie pamięci podręcznej dla poszczególnych kluczy

Klucze API mogą zrezygnować z odczytów semantycznej pamięci podręcznej za pomocą cacheDefaultMode:

Wartość	Zachowanie
legacy	Normalne działanie pamięci podręcznej (domyślne)
bypass	Całkowite pominięcie wyszukiwania w pamięci podręcznej; zawsze wywołuje usługę nadrzędną

Ustaw podczas tworzenia klucza (POST /api/keys) lub aktualizacji (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Pomijanie dla poszczególnych żądań

Każde żądanie może pominąć pamięć podręczną niezależnie od ustawień klucza:

X-OmniRoute-No-Cache: true

---

Panel i zarządzanie

Trasy zarządzania (/api/* z wyjątkiem publicznego uwierzytelniania/logowania) nie są autoryzowane za pomocą zwykłych kluczy API do wnioskowania. Rodziny poświadczeń, zakresy i przykłady curl: Uwierzytelnianie zarządzania.

Uwierzytelnianie

Punkt końcowy	Metoda	Opis
/api/auth/login	POST	Logowanie
/api/auth/logout	POST	Wylogowanie
/api/settings/require-login	GET/PUT	Włączanie wymogu logowania

Zarządzanie dostawcami

Punkt końcowy	Metoda	Opis
/api/providers	GET/POST	Wyświetlanie listy / tworzenie dostawców
/api/providers/[id]	GET/PUT/DELETE	Zarządzanie dostawcą
/api/providers/[id]/test	POST	Testowanie połączenia z dostawcą
/api/providers/[id]/models	GET	Wyświetlanie listy modeli dostawcy
/api/providers/validate	POST	Weryfikowanie konfiguracji dostawcy
/api/providers/bulk	POST	Zbiorcze dodawanie kluczy API dla JEDNEGO dostawcy
/api/providers/import	POST	Importowanie heterogenicznej LISTY dostawców z przeanalizowanego pliku CSV/JSON (#6836); wyniki częściowych niepowodzeń dla poszczególnych wierszy
/api/provider-nodes*	Różne	Zarządzanie węzłami dostawców
/api/provider-models	GET/POST/PATCH/DELETE	Modele niestandardowe (dodawanie, aktualizowanie, ukrywanie/pokazywanie, usuwanie)

Przepływy OAuth

Punkt końcowy	Metoda	Opis
/api/oauth/[provider]/[action]	Różne	OAuth specyficzny dla dostawcy

Routing i konfiguracja

Punkt końcowy	Metoda	Opis
/api/models/alias	GET/POST	Aliasy modeli
/api/models/catalog	GET	Wszystkie modele według dostawcy i typu
/api/combos*	Różne	Zarządzanie kombinacjami
/api/keys*	Różne	Zarządzanie kluczami API
/api/pricing	GET	Ceny modeli

Użycie i analityka

Punkt końcowy	Metoda	Opis
/api/usage/history	GET	Historia użycia
/api/usage/logs	GET	Dzienniki użycia
/api/usage/request-logs	GET	Dzienniki na poziomie żądań
/api/usage/[connectionId]	GET	Użycie dla poszczególnych połączeń
/api/usage/token-limits	GET/POST/DELETE	Budżety limitów tokenów dla poszczególnych kluczy API
/api/usage/model-latency-stats	GET	Kroczące zagregowane statystyki opóźnień według dostawcy/modelu (średnia/p50/p95/p99, współczynnik powodzenia); filtry: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Podsumowanie kondycji pamięci podręcznej promptów na podstawie call_logs — stosunek zapisów do odczytów, rozkład wielkości zapisów p50/p90/p99, koncentracja dużych zapisów, podział według modelu oraz ocena healthy/degraded/thrash/no-data; parametry zapytania range (1h|24h|7d|30d, domyślnie 24h) i opcjonalny model (#8827)

Ustawienia

Punkt końcowy	Metoda	Opis
/api/settings	GET/PUT/PATCH	Ustawienia ogólne
/api/settings/proxy	GET/PUT	Konfiguracja sieciowego serwera proxy
/api/settings/proxy/test	POST	Testowanie połączenia z serwerem proxy
/api/settings/ip-filter	GET/PUT	Lista dozwolonych/zablokowanych adresów IP
/api/settings/thinking-budget	GET/PUT	Tryb przepisywania żądań dotyczących budżetu myślenia/rozumowania (przekazywanie bez zmian / automatyczne usuwanie / niestandardowy / adaptacyjny). Niezależny od kompresji. Zobacz THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Globalny prompt systemowy
/api/settings/compression	GET/PUT	Globalna konfiguracja kompresji
/api/settings/purge-request-history	POST	Usuwanie wierszy dziennika żądań i lokalnych artefaktów dziennika wywołań

Kontekst i kompresja

Endpoint	Metoda	Opis
/api/compression/preview	POST	Podgląd kompresji off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Lista dostępnych pakietów językowych Caveman
/api/compression/rules	GET	Lista metadanych reguł Caveman
/api/context/caveman/config	GET/PUT	Alias ustawień specyficznych dla Caveman
/api/context/rtk/config	GET/PUT	Ustawienia specyficzne dla RTK, w tym filtry niestandardowe i przechowywanie surowych danych wyjściowych
/api/context/rtk/filters	GET	Katalog filtrów RTK i diagnostyka filtrów niestandardowych
/api/context/rtk/test	POST	Uruchomienie podglądu/testu RTK dla ładunku tekstowego
/api/context/rtk/raw-output/[id]	GET	Odczyt zachowanych, zredagowanych surowych danych wyjściowych według identyfikatora wskaźnika
/api/context/combos	GET/POST	Wyświetlanie/tworzenie kombinacji kompresji
/api/context/combos/[id]	GET/PUT/DELETE	Szczegóły/aktualizacja/usuwanie kombinacji kompresji
/api/context/combos/[id]/assignments	GET/PUT	Przypisywanie kombinacji kompresji do kombinacji routingu
/api/context/analytics	GET	Alias analityki kompresji

Monitorowanie

Endpoint	Metoda	Opis
/api/sessions	GET	Śledzenie aktywnych sesji
/api/rate-limits	GET	Limity żądań dla poszczególnych kont
/api/monitoring/health	GET	Kontrola stanu i podsumowanie dostawców (catalogCount, configuredCount, activeCount, monitoredCount). Widok zarządzania zawiera credentialHealth: wartości skalarne pamięci podręcznej sond, failedConnections, gdy failed>0, oraz staleDbNonOkCount (utrwalony w SQLite test_status, a nie wskaźnik). Zobacz MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Statystyki pamięci podręcznej / czyszczenie
/api/modality-bridge/stats	GET	Przechowywane w pamięci attempts, powodzenia/bridged, niepowodzenia, trafienia w pamięci podręcznej, totalLatencyMs, latencySamples, obliczana na podstawie liczby próbek wartość averageLatencyMs oraz czas ostatniego użycia (resetowane po ponownym uruchomieniu; uwierzytelnianie zarządcze)
/api/modality-bridge/video/runtime	GET	Ścisła kontrola zaufanego interfejsu loopback przed uwierzytelnianiem zarządczym/sondą; oczyszczone informacje o dostępności i wersjach FFmpeg/ffprobe (bez przechowywania)
/api/modality-bridge/video/extract	POST	Wewnętrzny, uwierzytelniony broker bajtów zaufanego interfejsu loopback; wejście 50 MiB, ograniczona kolejka/wyjście 32 MiB, 503 przy przekroczeniu pojemności, 499 przy rozłączeniu, 504 po przekroczeniu terminu; nie jest to publiczny interfejs API do przesyłania plików

Kopia zapasowa oraz eksport/import

Endpoint	Metoda	Opis
/api/db-backups	GET	Wyświetlenie dostępnych kopii zapasowych
/api/db-backups	PUT	Utworzenie ręcznej kopii zapasowej
/api/db-backups	POST	Przywrócenie z określonej kopii zapasowej
/api/db-backups/export	GET	Pobranie bazy danych jako pliku .sqlite
/api/db-backups/import	POST	Przesłanie pliku .sqlite w celu zastąpienia bazy danych
/api/db-backups/exportAll	GET	Pobranie pełnej kopii zapasowej jako archiwum .tar.gz

Synchronizacja z chmurą

Endpoint	Metoda	Opis
/api/sync/cloud	Różne	Operacje synchronizacji z chmurą
/api/sync/initialize	POST	Inicjalizacja synchronizacji
/api/cloud/*	Różne	Zarządzanie chmurą

Tunele

Endpoint	Metoda	Opis
/api/tunnels/cloudflared	GET	Odczyt stanu instalacji i działania Cloudflare Quick Tunnel na potrzeby panelu
/api/tunnels/cloudflared	POST	Włączenie lub wyłączenie Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Odczyt stanu działania ngrok Tunnel na potrzeby panelu
/api/tunnels/ngrok	POST	Włączenie lub wyłączenie ngrok Tunnel (action=enable/disable)

Narzędzia CLI

Endpoint	Metoda	Opis
/api/cli-tools/claude-settings	GET	Stan Claude CLI
/api/cli-tools/codex-settings	GET	Stan Codex CLI
/api/cli-tools/droid-settings	GET	Stan Droid CLI
/api/cli-tools/openclaw-settings	GET	Stan OpenClaw CLI
/api/cli-tools/runtime/[toolId]	GET	Ogólne środowisko wykonawcze CLI

Odpowiedzi CLI zawierają: installed, runnable, command, commandPath, runtimeMode, reason.

Agenci ACP

Endpoint	Metoda	Opis
/api/acp/agents	GET	Wyświetlenie wszystkich wykrytych agentów (wbudowanych i niestandardowych) wraz ze stanem
/api/acp/agents	POST	Dodanie niestandardowego agenta lub odświeżenie pamięci podręcznej wykrywania
/api/acp/agents	DELETE	Usunięcie niestandardowego agenta według parametru zapytania id

Odpowiedź GET zawiera agents[] (id, name, binary, version, installed, protocol, isCustom) oraz summary (total, installed, notFound, builtIn, custom).

Odporność i limity szybkości

Endpoint	Metoda	Opis
/api/resilience	GET/PATCH	Pobieranie lub aktualizowanie kolejki żądań, okresu oczekiwania połączenia, wyłącznika dostawcy i ustawień oczekiwania
/api/resilience/reset	POST	Resetowanie wyłączników obwodu dostawcy
/api/resilience/model-cooldowns	GET	Wyświetlenie aktywnych blokad dla poszczególnych kombinacji (dostawca, połączenie, model), posortowanych według pozostałego czasu
/api/resilience/model-cooldowns	DELETE	Usunięcie blokady modelu — treść {provider, model} lub {all: true}, aby usunąć wszystkie
/api/rate-limits	GET	Stan limitu szybkości dla poszczególnych kont
/api/rate-limit	GET	Globalna konfiguracja limitu szybkości

Wszystkie cztery trasy /api/resilience/* wymagają uwierzytelniania zarządzania (requireManagementAuth). Pełne omówienie różnic między wyłącznikiem dostawcy, okresem oczekiwania połączenia i blokadą modelu znajduje się w sekcji Odporność (rozszerzona).

Ewaluacje

Endpoint	Metoda	Opis
/api/evals	GET/POST	Wyświetlenie zestawów ewaluacyjnych / uruchomienie ewaluacji

Zasady

Endpoint	Metoda	Opis
/api/policies	GET/POST/DELETE	Zarządzanie zasadami routingu

Zgodność

Endpoint	Metoda	Opis
/api/compliance/audit-log	GET	Dziennik audytu zgodności (ostatnie N wpisów)

v1beta (zgodność z Gemini)

Endpoint	Metoda	Opis
/v1beta/models	GET	Wyświetlenie modeli w formacie Gemini
/v1beta/models/{...path}	POST	Endpoint Gemini generateContent

Te endpointy odzwierciedlają format API Gemini dla klientów wymagających natywnej zgodności z zestawem Gemini SDK.

Wewnętrzne/systemowe interfejsy API

Endpoint	Metoda	Opis
/api/init	GET	Kontrola inicjalizacji aplikacji (używana przy pierwszym uruchomieniu)
/api/tags	GET	Tagi modeli zgodne z Ollama (dla klientów Ollama)
/api/restart	POST	Wywołanie kontrolowanego ponownego uruchomienia serwera
/api/shutdown	POST	Wywołanie kontrolowanego wyłączenia serwera
/api/system/env/repair	POST	Naprawa zmiennych środowiskowych dostawcy OAuth

Uwaga: Te endpointy są używane wewnętrznie przez system lub w celu zapewnienia zgodności z klientami Ollama. Zazwyczaj nie są wywoływane przez użytkowników końcowych.

Naprawa środowiska OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

Naprawia brakujące lub uszkodzone zmienne środowiskowe OAuth dla określonego dostawcy. Zwraca:

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

---

Transkrypcja audio

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

Transkrybuj pliki audio przy użyciu dowolnego skonfigurowanego dostawcy STT. Pierwszy segment ścieżki wybiera natywnego dostawcę (openai/…, deepgram/…). Bramy, które ponownie udostępniają model innego dostawcy, używają kwalifikowanego identyfikatora (openrouter/deepgram/nova-3).

Żądanie:

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

Odpowiedź:

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

Przykładowe identyfikatory modeli: openai/whisper-1 (wymaga klucza OpenAI), openrouter/deepgram/nova-3 (wymaga klucza OpenRouter), deepgram/nova-3 (wymaga natywnego klucza Deepgram). Żądanie z samym deepgram/nova-3 nie korzysta z OpenRouter.

Obsługiwane formaty: mp3, wav, m4a, flac, ogg, webm.

---

Zgodność z Ollama

Dla klientów korzystających z formatu API Ollama:

# Punkt końcowy czatu (format Ollama)
POST /v1/api/chat

# Lista modeli (format Ollama)
GET /api/tags

Żądania są automatycznie tłumaczone między formatem Ollama a formatami wewnętrznymi.

Tokenizowane aliasy dla VS Code / aliasy bez nagłówków

Użyj tych aliasów, gdy integracja nie może dodać nagłówka Authorization i wymaga osadzenia klucza API w bazowym adresie URL.

# Alias katalogu w stylu OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Aliasy czatu w stylu OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Aliasy w stylu Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Przykład:

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

Uwagi:

• Tokenizowane aliasy korzystają ponownie z tych samych procedur obsługi co /v1/* i /api/tags; struktury odpowiedzi pozostają identyczne.
• Zawsze gdy klient obsługuje niestandardowe nagłówki, preferuj Authorization: Bearer ....
• Tokeny umieszczone w adresach URL mogą pojawiać się w logach odwrotnego serwera proxy, historii przeglądarki i telemetrii poza OmniRoute. Traktuj je jako opcję zapewniającą zgodność, a nie jako domyślny tryb uwierzytelniania.

---

Telemetria

# Pobierz podsumowanie telemetrii opóźnień (p50/p95/p99 dla każdego dostawcy)
GET /api/telemetry/summary

Odpowiedź:

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

---

Budżet

# Pobierz stan budżetu dla wszystkich kluczy API
GET /api/usage/budget

# Ustaw lub zaktualizuj budżet
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"
}

Uwagi dotyczące schematu (setBudgetSchema): pole apiKeyId jest wymagane; co najmniej jedno z pól dailyLimitUsd, weeklyLimitUsd lub monthlyLimitUsd musi mieć wartość większą od zera. Pola opcjonalne: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Starszy format {keyId, limit, period} zwraca błąd 400 Bad Request.

Limity tokenów

Budżety tokenów dla poszczególnych kluczy API (niezależne od powyższego budżetu opartego na USD). Są egzekwowane bezpośrednio podczas obsługi żądania: gdy użycie w bieżącym oknie dla danego klucza osiągnie limit, żądania są odrzucane z kodem 429 Too Many Requests. Limity mogą być ograniczone do konkretnego model, provider lub stosowane globalnie dla całego klucza; gdy do żądania pasuje kilka limitów, obowiązuje najbardziej restrykcyjny.

# Wyświetlenie limitów tokenów klucza (wraz z bieżącym użyciem w oknie)
GET /api/usage/token-limits?apiKeyId=key-123

# Utworzenie lub zaktualizowanie limitu tokenów
POST /api/usage/token-limits
Content-Type: application/json

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

# Usunięcie limitu tokenów według identyfikatora
DELETE /api/usage/token-limits?id=tl-abc

Uwagi dotyczące schematu (setTokenLimitSchema): apiKeyId i scopeType (model | provider | global) są wymagane. scopeValue jest wymagane, chyba że scopeType ma wartość global (np. identyfikator modelu dla zakresu model lub identyfikator dostawcy dla zakresu provider). tokenLimit musi być dodatnią liczbą całkowitą (wartość tekstowa zostanie przekonwertowana). Opcjonalne: id (pomiń, aby utworzyć; podaj, aby zaktualizować), resetInterval (daily | weekly | monthly, domyślnie monthly), resetTime (HH:MM), enabled (domyślnie true). Odpowiedzi GET uzupełniają każdy limit o pola tokensUsed, remaining, windowStart, periodStartAt i nextResetAt. Jest to punkt końcowy klasy zarządzania (uwierzytelnianie jest egzekwowane centralnie przez potok autoryzacji).

Przetwarzanie żądań

1. Klient wysyła żądanie do /v1/*
2. Procedura obsługi trasy wywołuje handleChat, handleEmbedding, handleAudioTranscription lub handleImageGeneration
3. Model zostaje ustalony (bezpośredni dostawca/model albo alias/kombinacja)
4. Poświadczenia są wybierane z lokalnej bazy danych z uwzględnieniem filtrowania dostępności kont
5. W przypadku czatu: handleChatCore sprawdza pamięć podręczną semantyczną/sygnatur i ustala ustawienia kompresji kombinacji
6. Gdy kompresja proaktywna jest włączona, jest wykonywana przed translacją do formatu dostawcy (lite, Caveman, RTK lub tryb warstwowy)
7. Moduł wykonawczy dostawcy wysyła żądanie do usługi nadrzędnej
8. Odpowiedź jest tłumaczona z powrotem na format klienta (czat) lub zwracana bez zmian (osadzenia/obrazy/dźwięk)
9. Rejestrowane są użycie, dane analityczne kompresji i dzienniki żądań
10. W przypadku błędów stosowany jest mechanizm rezerwowy zgodnie z regułami kombinacji

Pełna dokumentacja architektury: ARCHITECTURE.md

---

Zarządzanie kombinacjami

Kombinacje routingu wyższego poziomu (podsumowane już w sekcji /api/combos*) można również mapować w relacji 1:1 na podstawie wzorca identyfikatora modelu, co umożliwia przezroczyste przekierowanie identyfikatora modelu w stylu OpenAI do kombinacji.

Metoda	Ścieżka	Opis
GET	/api/model-combo-mappings	Wyświetlenie wszystkich mapowań model→kombinacja
POST	/api/model-combo-mappings	Utworzenie mapowania — treść: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Pobranie pojedynczego mapowania
PUT	/api/model-combo-mappings/[id]	Zaktualizowanie pól istniejącego mapowania
DELETE	/api/model-combo-mappings/[id]	Usunięcie mapowania

Uwierzytelnianie: sesja zarządzania/klucz API (requireManagementAuth).

---

Webhooki

Subskrypcje wychodzących webhooków dla zdarzeń OmniRoute (zakończenie żądania, wyczerpanie limitu, rotacja klucza itp.).

Metoda	Ścieżka	Opis
GET	/api/webhooks	Wyświetla webhooki (sekrety są maskowane do postaci <prefix>...)
POST	/api/webhooks	Tworzy webhook — treść: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Pobiera webhook
PUT	/api/webhooks/[id]	Aktualizuje url/events/secret/description
DELETE	/api/webhooks/[id]	Usuwa webhook
POST	/api/webhooks/[id]/test	Wysyła testowy ładunek pod adres URL webhooka i zwraca status dostarczenia

Uwierzytelnianie: sesja zarządzania/klucz API (requireManagementAuth).

---

Zarejestrowane klucze (automatyczne zarządzanie)

Używane przez podsystem automatycznego zarządzania kluczami do wystawiania i rotacji kluczy API u bazowego dostawcy/na koncie, z dziennymi/godzinowymi limitami.

Metoda	Ścieżka	Opis
GET	/api/v1/registered-keys	Wyświetla zarejestrowane klucze (tylko zamaskowany prefiks)
POST	/api/v1/registered-keys	Wystawia nowy zarejestrowany klucz — treść: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Zwraca nieprzetworzony klucz jednorazowo. Zwraca 429 w przypadku odmowy z powodu limitu.
GET	/api/v1/registered-keys/[id]	Pobiera metadane zarejestrowanego klucza (bez nieprzetworzonej wartości)
DELETE	/api/v1/registered-keys/[id]	Unieważnia zarejestrowany klucz
POST	/api/v1/registered-keys/[id]/revoke	Jawny punkt końcowy unieważniania (taki sam efekt jak DELETE)

Uwierzytelnianie: klucz API Bearer (isAuthenticated). Zobacz również /v1/quotas/check i /v1/issues/report.

---

Protokół agentów

Zadania agentów chmurowych (Claude Code, Codex Cloud, OpenHands itp.) wykonywane zdalnie w imieniu użytkowników OmniRoute.

Metoda	Ścieżka	Opis
GET	/api/v1/agents/tasks	Wyświetla zadania — opcjonalnie ?provider=, ?status=, ?limit= (1–500, domyślnie 50)
POST	/api/v1/agents/tasks	Tworzy zadanie — treść żądania walidowana przez CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Zwraca 201 z obwiednią zadania
DELETE	/api/v1/agents/tasks?id=...	Usuwa zadanie
GET	/api/v1/agents/tasks/[id]	Odczytuje zadanie — synchronicznie odświeża status z nadrzędnego agenta chmurowego, gdy ustawiono external_id
POST	/api/v1/agents/tasks/[id]	Akcja rozróżniana: {action: "approve"}, {action: "message", message} lub {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Usuwa określone zadanie według identyfikatora

Uwierzytelnianie: uwierzytelnianie zarządzania jest wymagane dla każdej metody (requireCloudAgentManagementAuth). Przed wersją v3.8.0 metody te nie wymagały uwierzytelniania — zmianę niekompatybilną wstecznie opisano w commicie 588a0333.

# Utwórz zadanie chmurowe Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

---

Serwery proxy zarządzania

Wychodzące serwery proxy HTTP(S)/SOCKS, które można przypisać do dostawców, kont lub globalnie.

Metoda	Ścieżka	Opis
GET	/api/v1/management/proxies	Wyświetla serwery proxy (z ?id= zwraca jeden; z ?id=&where_used=1 zwraca graf przypisań)
POST	/api/v1/management/proxies	Tworzy serwer proxy — treść żądania walidowana przez createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Aktualizuje serwer proxy — treść żądania walidowana przez updateProxyRegistrySchema (wymaga id)
DELETE	/api/v1/management/proxies?id=...&force=1	Usuwa serwer proxy (użyj force=1, aby odłączyć przypisania)
GET	/api/v1/management/proxies/assignments	Wyświetla przypisania — filtrowanie według proxy_id, scope, scope_id; przekaż resolve_connection_id=<id>, aby ustalić aktywny serwer proxy dla połączenia
PUT	/api/v1/management/proxies/assignments	Przypisuje — treść żądania walidowana przez proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Czyści pamięć podręczną dyspozytora
PUT	/api/v1/management/proxies/bulk-assign	Przypisuje zbiorczo — treść żądania walidowana przez bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Zbiorcze dane o stanie serwerów proxy (liczba sukcesów/niepowodzeń, opóźnienie) w określonym przedziale czasowym

Uwierzytelnianie: sesja zarządzania/klucz API na każdej trasie (requireManagementAuth).

Endpointy POST /api/v1/management/proxies/[id]/assignments i POST /api/v1/management/proxies/[id]/health z opisu zadania są obsługiwane przez przedstawione powyżej płaskie trasy /assignments i /health — w bazie kodu nie ma podtras dla poszczególnych identyfikatorów.

---

Odporność (rozszerzona)

OmniRoute udostępnia trzy niezależne mechanizmy obsługi tymczasowych awarii; poniższe punkty końcowe zarządzania umożliwiają operatorom odczytywanie i nadpisywanie ich ustawień:

Zakres	Przechowywanie stanu	Odczyt	Resetowanie / czyszczenie
Wyłącznik dostawcy	domain_circuit_breakers + pamięć operacyjna	/api/monitoring/health	POST /api/resilience/reset
Okres oczekiwania połączenia	rateLimitedUntil w połączeniach dostawcy	/api/rate-limits, /api/providers/[id]	(włącza się ponownie leniwie; wyczyść przez PUT dostawcy)
Blokada modelu	Rejestr dostępności modeli w pamięci operacyjnej	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience przyjmuje nadpisania wyłącznika dostawcy w providerBreaker.oauth i providerBreaker.apikey. Każdy profil obsługuje pola degradationThreshold, failureThreshold i resetTimeoutMs; te same pola są dostępne w Panel → Ustawienia → Odporność.

# Wyczyść blokadę pojedynczego modelu
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"}'

# Usuń wszystkie blokady
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Pełny opis koncepcyjny i domyślne ustawienia wyłączników: zobacz CLAUDE.md → „Stan środowiska wykonawczego odporności”.

---

Umiejętności

Struktura umożliwiająca rozszerzanie OmniRoute za pomocą niestandardowych wykonywalnych procedur obsługi oraz integracji z platformami handlowymi.

Metoda	Ścieżka	Opis
GET	/api/skills	Wyświetla zainstalowane umiejętności — filtrowanie według ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, z podziałem na strony
GET	/api/skills/[id]	Pobiera jedną umiejętność
PUT	/api/skills/[id]	Aktualizuje umiejętność (nazwa, opis, tryb, schemat, procedura obsługi, tagi)
DELETE	/api/skills/[id]	Odinstalowuje umiejętność
POST	/api/skills/install	Instaluje umiejętność z surowego manifestu — treść: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Wyświetla ostatnie wykonania umiejętności (dziennik audytu z danymi wejściowymi/wyjściowymi i czasem trwania)
GET	/api/skills/marketplace?q=...	Wyszukuje lub wyświetla listę popularnych pozycji z platformy SkillsMP (wymaga ustawienia skillsmpApiKey)
POST	/api/skills/marketplace/install	Instaluje umiejętność według identyfikatora z SkillsMP
GET	/api/skills/skillssh?q=&limit=	Przeszukuje rejestr skills.sh
POST	/api/skills/skillssh/install	Instaluje umiejętność według identyfikatora z skills.sh

Uwierzytelnianie: sesja zarządzania/klucz API. Trasy wyszukiwania na platformach handlowych akceptują uwierzytelnianie zarządzania lub klucz API Bearer (isAuthenticated).

---

Pamięć

Trwały magazyn pamięci konwersacyjnej/faktograficznej, ograniczony do klucza API / sesji.

Metoda	Ścieżka	Opis
GET	/api/memory	Wyświetlanie listy wspomnień — ?apiKeyId=, ?type=, ?sessionId=, ?q=, z paginacją offset/limit lub page/limit
POST	/api/memory	Tworzenie wspomnienia — treść żądania walidowana przez Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Pobieranie pojedynczego wspomnienia
DELETE	/api/memory/[id]	Usuwanie wspomnienia
GET	/api/memory/health	Stan podsystemu pamięci (łączność z bazą danych, backend osadzeń, stan indeksu wektorowego)

Uwierzytelnianie: sesja zarządzania/klucz API (requireManagementAuth). Wartości wyliczenia type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (zobacz MemoryType w src/lib/memory/types.ts).

---

Serwer MCP

OmniRoute zawiera wbudowany serwer Model Context Protocol z 3 mechanizmami transportu (stdio, SSE, streamable-http) oraz narzędziami o ograniczonym zakresie. Poniższe endpointy panelu odczytują dane o stanie/audycie i pośredniczą w obsłudze transportów HTTP.

Metoda	Ścieżka	Opis
GET	/api/mcp/status	Sygnał aktywności, transport, stan online, ostatnie wywołanie, najczęściej używane narzędzia, współczynnik powodzenia z 24 godz.
GET	/api/mcp/tools	Lista narzędzi MCP z polami name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Otwarcie strumienia SSE dla transportu SSE (zwraca 503, jeśli MCP jest wyłączony lub transport jest niezgodny)
POST	/api/mcp/sse	Wysłanie ramki JSON-RPC przez transport SSE
GET	/api/mcp/stream	Otwarcie strony SSE transportu Streamable HTTP (komunikaty inicjowane przez serwer)
POST	/api/mcp/stream	Wysłanie ramki JSON-RPC przez transport Streamable HTTP
DELETE	/api/mcp/stream	Zakończenie sesji Streamable HTTP
GET	/api/mcp/audit	Zapytanie do dziennika audytu — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Zagregowane statystyki audytu (sumy, współczynnik powodzenia, średni czas trwania, najczęściej używane narzędzia)

Uwierzytelnianie: transporty sse/stream korzystają z mechanizmu uwierzytelniania właściwego dla MCP (klucz API Bearer z zakresem mcp); trasy status/tools/audit* są dostępne do odczytu z panelu (nie wymagają dodatkowego uwierzytelniania poza dostępem do hosta panelu).

Oba transporty HTTP są kontrolowane przez settings.mcpEnabled i settings.mcpTransport — niezgodność transportu zwraca 400, a wyłączony stan MCP zwraca 503.

---

Serwer A2A

OmniRoute udostępnia punkt końcowy A2A (Agent-to-Agent) zgodny z JSON-RPC 2.0 oraz otoczkę REST przeznaczoną do inspekcji i użycia w panelu.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # opcjonalne, chyba że ustawiono 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"}]
  }
}

Obsługiwane metody (wszystkie zależne od settings.a2aEnabled):

Metoda	Opis
message/send	Synchroniczne wykonanie umiejętności; zwraca {task, artifacts, metadata}
message/stream	Strumieniowe wykonanie tego samego zestawu umiejętności za pomocą SSE
tasks/get	Pobiera zadanie według taskId
tasks/cancel	Anuluje zadanie według taskId

Wbudowane umiejętności: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Karta agenta

GET /.well-known/agent.json

Zwraca publiczną kartę agenta A2A (nazwa, opis, możliwości, katalog umiejętności, schemat uwierzytelniania) — buforowaną publicznie przez 1 godz. Uwierzytelnianie nie jest wymagane.

Pomocnicze punkty końcowe REST

Metoda	Ścieżka	Opis
GET	/api/a2a/status	Stan włączenia A2A, statystyki zadań i podsumowanie zbuforowanej karty agenta
GET	/api/a2a/tasks	Wyświetla listę zadań — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Nie zaimplementowano jako pomocniczego punktu końcowego REST — utwórz przez JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Pobiera jedno zadanie
POST	/api/a2a/tasks/[id]/cancel	Anuluje zadanie

Uwierzytelnianie: pomocnicze punkty końcowe REST działają bez uwierzytelniania administracyjnego (są dostępne do odczytu przez panel); trasa JSON-RPC /a2a używa tokenu Bearer OMNIROUTE_API_KEY, jeśli został skonfigurowany.

---

Chmura, ewaluacje i ocena

Metoda	Ścieżka	Opis
POST	/api/cloud/auth	Weryfikuje klucz Bearer i zwraca zamaskowane połączenia z dostawcami oraz aliasy modeli dla klientów synchronizacji z chmurą
POST	/api/cloud/credentials/update	Aktualizuje zaszyfrowane dane uwierzytelniające dostawcy synchronizowanego z chmurą
POST	/api/cloud/model/resolve	Rozwiązuje logiczny identyfikator modelu do konkretnego dostawcy/modelu przy użyciu lokalnej tabeli routingu
GET	/api/cloud/models/alias	Wyświetla aliasy modeli udostępniane synchronizacji z chmurą
GET	/api/assess	Odczytuje najnowsze kategoryzacje oceny (dla poszczególnych dostawców/modeli)
POST	/api/assess	Uruchamia ocenę — treść żądania: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Wyświetla wbudowane zestawy ewaluacyjne i najnowsze uruchomienia
POST	/api/evals	Uruchamia ewaluację
POST	/api/evals/suites	Tworzy niestandardowy zestaw ewaluacyjny — treść żądania walidowana przez evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Pobiera niestandardowy zestaw ewaluacyjny

Uwierzytelnianie: /api/cloud/auth bezpośrednio weryfikuje klucz Bearer; pozostałe trasy /api/cloud/*, /api/evals/* i /api/assess wymagają sesji administracyjnej/klucza API. Żądanie POST do /api/assess używa validateBody ze schematem zakresu będącym unią rozróżnianą.

---

Zarządzanie ACP (Agent Client Protocol)

jako procesami potomnymi. Te punkty końcowe służą do wykrywania agentów ACP i rejestrowania agentów niestandardowych.

Metoda	Ścieżka	Opis
GET	/api/acp/agents	Wyświetla wszystkich znanych agentów CLI (wbudowanych i niestandardowych) wraz ze stanem instalacji, wersją i plikiem binarnym
POST	/api/acp/agents	Rejestruje niestandardowego agenta ACP lub odświeża pamięć podręczną — treść: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} lub {action: "refresh"}
DELETE	/api/acp/agents	Usuwa niestandardowego agenta ACP — parametr zapytania: ?id=<agentId>

Przykład odpowiedzi (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
}

Uwierzytelnianie: Wymaga sesji zarządzania (pliku cookie auth_token panelu) lub klucza API z zakresem zarządzania.

Pełne informacje można znaleźć w dokumencie Struktura ACP.

---

Analityka i obserwowalność

Punkty końcowe analityki w czasie rzeczywistym do monitorowania routingu, kompresji i różnorodności dostawców. Obsługują strony /dashboard/analytics/*.

Analityka automatycznego routingu

Metoda	Ścieżka	Opis
GET	/api/analytics/auto-routing	Zbiorcze statystyki automatycznego routingu: łączna liczba wywołań, rozkład strategii, rozkład poziomów, główni dostawcy
GET	/api/analytics/auto-routing?days=7	Statystyki dla określonego przedziału czasowego (domyślnie 24 godz.)

Przykład odpowiedzi:

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

Analityka kompresji

Metoda	Ścieżka	Opis
GET	/api/analytics/compression	Zbiorcze statystyki kompresji: liczba zaoszczędzonych tokenów, procent oszczędności, rozkład trybów, użycie silników

Przykład odpowiedzi:

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

Śledzenie różnorodności dostawców

Metoda	Ścieżka	Opis
GET	/api/analytics/diversity	Śledzenie różnorodności oparte na entropii Shannona: zapobiega pojedynczym punktom awarii poprzez pomiar rozkładu dostawców

Przykład odpowiedzi:

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

Uwierzytelnianie: Wymaga sesji zarządzania lub klucza API z zakresem zarządzania.

---

Operacje administracyjne

Punkty końcowe dostępne wyłącznie dla administratorów, służące do zarządzania operacyjnego.

Metoda	Ścieżka	Opis
GET	/api/admin/concurrency	Odczytuje bieżące limity współbieżności (globalne i dla poszczególnych dostawców)
POST	/api/admin/concurrency	Aktualizuje limity współbieżności — treść: {global?: number, perProvider?: Record<string, number>}

Uwierzytelnianie: Wymaga sesji zarządzania z zakresem administratora.

---

Zarządzanie narzędziami CLI

Zarządzaj narzędziami CLI integrującymi się z OmniRoute (antigravity, chipotle, commandCode, devin-cli itp.). Pełna lista znajduje się w dokumencie Informacje o dostawcach.

Metoda	Ścieżka	Opis
GET	/api/cli-tools/all-statuses	Stan wszystkich narzędzi CLI (zainstalowanie, wersja, ostatnia aktywność)
GET	/api/cli-tools/status	Szczegółowy stan jednego narzędzia CLI (zapytanie ?tool=)
POST	/api/cli-tools/apply	Zapisuje wygenerowaną konfigurację narzędzia (dryRun wyświetla podgląd; 422 + containerEphemeralTarget w przypadku konteneryzacji; migration wskazuje starszy plik YAML Codex)
GET	/api/cli-tools/backups	Wyświetla kopie zapasowe konfiguracji narzędzi CLI
POST	/api/cli-tools/backups	Tworzy kopię zapasową konfiguracji wszystkich narzędzi CLI
POST	/api/cli-tools/backups	Przywraca kopię: ten sam punkt końcowy z {tool, backupId} w treści żądania przywraca wskazaną kopię
GET	/api/cli-tools/antigravity-mitm	Stan proxy MITM Antigravity (narzędzia CLI „antigravity-mitm”)
POST	/api/cli-tools/antigravity-mitm/alias	Konfiguruje aliasy antigravity-mitm

Uwierzytelnianie: Wymaga sesji zarządzania.

---

Umiejętności agentów

Zarządzaj umiejętnościami agentów AI (podobnymi do niestandardowych GPT OpenAI, ale przeznaczonymi dla agentów).

Metoda	Ścieżka	Opis
GET	/api/agent-skills	Wyświetla wszystkie umiejętności agentów (wbudowane i niestandardowe)
GET	/api/agent-skills/[id]	Pobiera określoną umiejętność agenta
POST	/api/agent-skills	Tworzy niestandardową umiejętność agenta — treść: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Aktualizuje niestandardową umiejętność agenta
DELETE	/api/agent-skills/[id]	Usuwa niestandardową umiejętność agenta
GET	/api/agent-skills/[id]/raw	Pobiera nieprzetworzony prompt i metadane (bez wykonywania)
POST	/api/agent-skills/generate	Generuje przy użyciu AI nową umiejętność na podstawie opisu w języku naturalnym

Uwierzytelnianie: Wymaga sesji zarządzania lub klucza API z zakresem zarządzania.

---

Zarządzanie pamięcią podręczną

Zarządzaj semantyczną pamięcią podręczną i pamięcią podręczną rozumowania.

Metoda	Ścieżka	Opis
GET	/api/cache	Przegląd pamięci podręcznej: łączna liczba wpisów, współczynnik trafień, rozmiar na dysku
GET	/api/cache/entries	Lista wpisów w pamięci podręcznej (z paginacją)
DELETE	/api/cache/entries	Usuwanie wpisów z pamięci podręcznej (filtrowanie według parametrów zapytania)
GET	/api/cache/stats	Szczegółowe statystyki pamięci podręcznej (według dostawcy i modelu)
GET	/api/cache/reasoning	Stan pamięci podręcznej rozumowania (na potrzeby odtwarzania rozumowania)
DELETE	/api/cache/reasoning	Czyszczenie pamięci podręcznej rozumowania — parametry zapytania: ?toolCallId=<id> (jeden wpis), ?provider=<p> lub brak parametrów (wszystkie wpisy)

Uwierzytelnianie: Wymaga sesji zarządzania.

---

System pamięci

Zarządzaj pamięcią trwałą (FTS5 + osadzenia wektorowe).

Metoda	Ścieżka	Opis
GET	/api/memory	Lista wpisów pamięci (filtrowanie według zakresu, typu i zapytania wyszukiwania)
POST	/api/memory	Tworzenie nowego wpisu pamięci — treść żądania: {scope, type, content, metadata?}
GET	/api/memory/[id]	Pobieranie określonego wpisu pamięci
PUT	/api/memory/[id]	Aktualizowanie wpisu pamięci
DELETE	/api/memory/[id]	Usuwanie wpisu pamięci
GET	/api/memory?q=	Przeszukiwanie pamięci (FTS5 + wektory) — statystyki są zawarte w tej samej odpowiedzi

Uwierzytelnianie: Wymaga sesji zarządzania lub klucza API z zakresem zarządzania.

---

Webhooki

Zarządzaj subskrypcjami webhooków dla zdarzeń.

Metoda	Ścieżka	Opis
GET	/api/webhooks	Lista wszystkich subskrypcji webhooków
POST	/api/webhooks	Tworzenie subskrypcji webhooka — treść żądania: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Pobieranie określonej subskrypcji webhooka
PUT	/api/webhooks/[id]	Aktualizowanie subskrypcji webhooka
DELETE	/api/webhooks/[id]	Usuwanie subskrypcji webhooka
GET	/api/webhooks/[id]/deliveries	Lista historii dostarczeń webhooka (dziennik powodzeń i niepowodzeń)
POST	/api/webhooks/[id]/test	Wysyłanie zdarzenia testowego do webhooka

Uwierzytelnianie: Wymaga sesji zarządzania.

Pełną listę typów zdarzeń zawiera dokument Platforma webhooków.

---

Framework umiejętności

Zarządzanie umiejętnościami (frameworkiem rozszerzeń agentowych).

Metoda	Ścieżka	Opis
GET	/api/skills	Wyświetla wszystkie zainstalowane umiejętności (wbudowane i niestandardowe)
POST	/api/skills/install	Instaluje umiejętność ze ścieżki lokalnej lub adresu URL
DELETE	/api/skills/[id]	Odinstalowuje umiejętność
PUT	/api/skills/[id]	Włącza lub wyłącza umiejętność — treść: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Uruchamia umiejętność — treść: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Wyświetla historię wykonań wszystkich umiejętności (filtrowanie według ?apiKeyId=)

Uwierzytelnianie: Wymaga sesji zarządzania lub klucza API z zakresem zarządzania.

Pełne informacje można znaleźć w dokumencie Framework umiejętności.

---

Wtyczki

Zarządzanie wtyczkami OmniRoute (rozszerzeniami innych firm).

Metoda	Ścieżka	Opis
GET	/api/plugins	Wyświetla zainstalowane wtyczki
POST	/api/plugins/marketplace/install	Instaluje wtyczkę z marketplace'u
DELETE	/api/plugins/[name]	Odinstalowuje wtyczkę
POST	/api/plugins/[name]/activate	Aktywuje wtyczkę
POST	/api/plugins/[name]/deactivate	Dezaktywuje wtyczkę
GET	/api/plugins/[name]/config	Pobiera konfigurację wtyczki
PUT	/api/plugins/[name]/config	Aktualizuje konfigurację wtyczki

Uwierzytelnianie: Wymaga sesji zarządzania.

Pełne informacje można znaleźć w dokumencie Framework wtyczek.

---

Routing równoległy

Równoległe porównywanie dostawców metodą A/B nie stanowi samodzielnego interfejsu REST — konfiguruje się je za pośrednictwem routingu combo (zobacz Auto-Combo). Metryki porównawcze dla poszczególnych combo są udostępniane przez GET /api/combos/metrics.

---

Mechanizmy ochronne

Inspekcja mechanizmów ochronnych środowiska uruchomieniowego (wykrywanie danych osobowych, wykrywanie wstrzykiwania promptów, obsługa pośrednia danych wizualnych). Mechanizmy ochronne są uruchamiane przy każdym żądaniu; rezygnacja dla pojedynczego wywołania odbywa się za pomocą nagłówka żądania x-omniroute-disabled-guardrails — nie istnieje trwały interfejs do ich włączania lub wyłączania.

Metoda	Ścieżka	Opis
GET	/api/guardrails	Wyświetla zarejestrowane mechanizmy ochronne oraz ich stan (nazwa / włączenie / priorytet)
POST	/api/guardrails/test	Przeprowadza testowe uruchomienie potoku przed wywołaniem na przykładowych danych — treść: {input, disabledGuardrails?}

Uwierzytelnianie: Wymaga sesji zarządzania.

Pełne informacje można znaleźć w dokumencie Bezpieczeństwo > Mechanizmy ochronne.

---

---

Uwierzytelnianie

Zobacz Uwierzytelnianie zarządzania, aby poznać cztery rodziny danych uwierzytelniających (sesja panelu, lokalny token CLI, token dostępu oma_live_…, klucz API z zakresem zarządzania) oraz różnice między nimi a kluczami wnioskowania.

• Trasy panelu (/dashboard/*) używają pliku cookie auth_token
• Logowanie używa zapisanego skrótu hasła; wartością zapasową jest INITIAL_PASSWORD
• Opcję requireLogin można przełączać za pomocą /api/settings/require-login
• Trasy /v1/* mogą opcjonalnie wymagać klucza API Bearer, gdy REQUIRE_API_KEY=true
• „token zarządzania” / „klucz API z zakresem zarządzania” w tej dokumentacji oznacza jedną z rodzin opisanych w tym przewodniku — nie niezdefiniowany, dodatkowy typ sekretu

Zmiana niekompatybilna wstecznie (v3.8.0) — /api/v1/agents/tasks/* oraz punkty końcowe zarządzania okresem karencji wymagają teraz uwierzytelniania zarządzania (pliku cookie auth_token panelu lub klucza API z zakresem zarządzania). Klienci, którzy wcześniej wywoływali te trasy bez uwierzytelnienia, otrzymają odpowiedź 401 Unauthorized. Zobacz commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).