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

API Reference (한국어)

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

---

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

OmniRoute API의 핵심 참조 문서입니다. 공개 /v1 인터페이스와 가장 자주 사용되는 관리 엔드포인트를 다룹니다. 전체 내용은 기계 판독 가능한 docs/openapi.yaml과 src/app/api/ 아래의 라우트 트리를 참조하세요.

---

목차

• 채팅 완성
• 독점 관리형 세션 임대
• 임베딩
• 이미지 생성
• 문서 OCR
• 모델 목록
• 제공자 플러그인 매니페스트
• 호환성 엔드포인트
• Files API
• Batches API
• Search API
• WebSocket 스트리밍
• 할당량 및 문제 보고
• 시맨틱 캐시
• 대시보드 및 관리
• 콤보 관리
• 웹후크
• 등록된 키(자동 관리)
• 에이전트 프로토콜
• 관리 프록시
• 복원력(확장)
• 스킬
• 메모리
• MCP 서버
• A2A 서버
• 클라우드, 평가 및 검증
• 요청 처리
• 인증

---

채팅 완성

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "다음을 수행하는 함수를 작성하세요..."}
  ],
  "stream": true
}

사용자 지정 헤더

헤더	방향	설명
X-OmniRoute-No-Cache	요청	캐시를 우회하려면 true로 설정
x-omniroute-no-memory	요청	이 요청에서 메모리 및 스킬 주입을 건너뛰려면 true로 설정합니다(no-cache와 동일하게 동작하며, 호출별 토큰/비용 오버헤드를 방지함)
X-OmniRoute-Progress	요청	진행 이벤트를 받으려면 true로 설정
X-Session-Id	요청	외부 세션 선호도를 위한 고정 세션 키
x_session_id	요청	밑줄 변형도 허용됨(직접 HTTP)
X-OmniRoute-Session-Id	요청	호출자가 제공하는 세션/대화 태그(메모리에도 전달됨). 지정된 경우 세션별 비용 귀속을 위해 call_logs.session_tag에 그대로 저장됨(#8249) — 지정되지 않은 경우 절대 생성되지 않음
Idempotency-Key	요청	중복 제거 키(5초 범위)
X-Request-Id	요청	대체 중복 제거 키
X-OmniRoute-Cache	응답	HIT 또는 MISS(비스트리밍)
X-OmniRoute-Idempotent	응답	중복 제거된 경우 true
X-OmniRoute-Progress	응답	진행 상황 추적이 활성화된 경우 enabled
X-OmniRoute-Session-Id	응답	OmniRoute에서 사용한 유효 세션 ID
X-OmniRoute-Request-Id	응답	요청 상관관계 ID(알려진 경우)
X-OmniRoute-Version	응답	OmniRoute 빌드 버전(항상 포함됨)
X-OmniRoute-Cost-Saved	응답	HIT으로 인해 캐시가 절감한 USD 금액(캐시 적중 시에만 해당)
X-OmniRoute-Decision	응답	라우팅 추적: strategy=<name>; provider=<alias>; latency_ms=<n>(<name>은 콤보 전략이며, 비콤보 요청의 경우 single) — 완료 응답에 항상 포함됨

Nginx 참고: 밑줄 헤더(예: x_session_id)를 사용하는 경우 underscores_in_headers on;을 활성화하세요.

비용 텔레메트리 헤더: 비스트리밍 성공 응답에는 X-OmniRoute-* 비용 텔레메트리 세트도 포함됩니다. 이 세트에는 X-OmniRoute-Response-Cost(USD, 소수점 이하 10자리 고정; 무료/가격 미책정 시 0.0000000000), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit, X-OmniRoute-Fallback-Attempts(0보다 큰 경우에만)와 X-OmniRoute-Request-Id 및 X-OmniRoute-Version이 포함됩니다. 이러한 헤더는 채팅 완성, /v1/responses, /v1/messages뿐만 아니라 미디어 엔드포인트인 /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations, /v1/moderations(비용은 항상 0)에서도 제공됩니다. 미디어 비용은 가격 정보가 있는 경우 모달리티별(이미지당, 초당, 문자당, 검색 단위당)로 계산되며, 그렇지 않은 경우 0으로 처리됩니다(장애 허용).

캐시 적중 비용 의미: 시맨틱 캐시 적중(X-OmniRoute-Cache-Hit: true) 시에는 업스트림 호출이 발생하지 않으므로 X-OmniRoute-Response-Cost는 0.0000000000입니다(적중 결과 제공에 따른 증분 비용). 원래 발생했거나 발생했을 비용은 X-OmniRoute-Cost-Saved에 별도로 보고됩니다. 청구 시스템에서는 X-OmniRoute-Response-Cost를 합산해야 하며(캐시 적중 비용은 없음), 캐시 분석에서는 X-OmniRoute-Cost-Saved를 집계할 수 있습니다.

독점 관리형 세션 임대

독점 관리형 세션 임대는 선택적으로 사용하는 클라이언트 중립적 라우팅 계약입니다. 하나의 활성 소유자가 적격 OmniRoute 연결 하나를 점유합니다. 이는 모델을 임대하거나, OAuth를 요구하거나, 특정 클라이언트를 식별하거나, 특정 공급자를 요구하지 않습니다.

인증에 사용하는 API 키에는 lease:exclusive 범위와 명시적인 비어 있지 않은 allowedConnections 목록이 있어야 합니다. 데이터베이스 변경 경계는 키 생성 및 부분 업데이트 시 두 필드가 함께 존재하도록 강제합니다.

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

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

성공한 획득, 갱신 및 해제 응답은 타임스탬프, state, 정확한 양의 generation을 노출하지만, 선택된 연결이나 자격 증명은 절대 노출하지 않습니다. 갱신 및 해제 시에는 JSON 본문에 generation을 제공합니다.

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

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

활성 임대 소유자는 현재 바인딩에 대해 개인정보 보호에 안전한 표시 메타데이터를 명시적으로 요청할 수 있습니다.

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

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

이 선택적 상태 작업은 하나의 데이터베이스 트랜잭션에서 불투명한 소유자, 인증된 관리형 API 키 및 정확한 활성 generation으로 보호됩니다. displayName은 구성된 연결 이름에서 앞뒤 공백만 제거한 값이며, 안전한 구성 이름이 없으면 null입니다. OmniRoute는 이메일이나 생성된 계정 ID를 대신 사용하지 않습니다. 공급자 값은 민감하지 않은 표시 레이블이며, 생성된 호환 공급자 식별자가 아닙니다. 자격 증명, 토큰, 쿠키, 원시 연결 또는 API 키 ID, 소유자 해시, 펜싱 비밀 값 및 내부 라우팅 데이터는 제외됩니다.

잘못된 키, 잘못된 소유자, 오래된 generation, 존재하지 않거나 만료되거나 해제되거나 무효화된 조회는 모두 연결 메타데이터 없이 동일한 409 LEASE_FENCE_STALE 오류를 반환합니다. 용량 대기 응답을 받은 클라이언트에는 검사할 수 있는 활성 바인딩이 없습니다. 라우팅이 활성 임대를 전환할 때는 동일한 generation이 계속 유효하며, 상태 조회는 이전 바인딩이 아닌 새 바인딩을 원자적으로 반환합니다. 획득, 갱신, 해제 및 대기 응답은 기존 형식을 유지하므로 기존 클라이언트에는 변경 사항이 없습니다.

이 서버 계약은 기본 OpenAI Codex /status를 변경하지 않습니다. 현재 기본 Codex는 모델 공급자와 기본 제공 인증/계정 상태를 보고하지만 임의의 사용자 지정 공급자 계정 메타데이터는 렌더링하지 않습니다. 향후 클라이언트 통합에서는 이 작업을 호출하고 connection.displayName을 표시할 방법을 결정해야 합니다.

그런 다음 모든 관리형 추론 요청은 두 제어 헤더를 모두 제공합니다.

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

정확한 소유자, generation, 활성 연결 및 인증된 API 키는 지원되는 각 업스트림 시도 직전에 펜싱됩니다. 다른 키가 동일한 연결을 허용하더라도 해당 키를 사용해 소유자와 generation을 재사용하면 실패합니다. 원시 소유자 값은 영구 저장되거나, 로그에 기록되거나, 요청 스냅샷에 보존되거나, 업스트림으로 전달되지 않습니다.

일시적인 경합이 발생하면 HTTP 429가 Retry-After 및 다음 내용과 함께 반환됩니다.

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

이 응답은 일반 적격 집합이 비어 있지 않았으며 모든 사용 가능한 후보가 다른 소유자의 활성 임대에 의해 점유되었다는 의미일 뿐입니다. 지원되지 않는 모델/공급자, 정책 불일치, 쿨다운, 할당량, 상태 및 기타 일반적인 적격성 실패에는 기존 OmniRoute 응답이 그대로 유지됩니다.

x-omniroute-compression

요청별 압축 계획 재정의입니다. 우선순위가 가장 높으며 라우팅 조합 재정의, 활성 프로필, 자동 트리거 및 패널의 Default보다 우선합니다. 값은 다음과 같습니다.

값	효과
off	이 요청에는 압축을 적용하지 않습니다.
default	패널에서 파생된 Default 프로필입니다(활성 프로필을 무시함).
engine:<id>	활성화된 경우 단일 엔진입니다(예: engine:rtk).
<combo>	먼저 이름으로 대소문자 구분 없이 일치시키고, 그다음 id로 일치시키는 명명된 조합입니다.

참고:

• 알 수 없는 값은 무시되며 요청은 절대 거부되지 않습니다. 해석은 일반적인 연산자 우선순위에 따라 계속 진행됩니다.
• 여러 조합이 같은 이름을 공유하는 경우 결정론적으로 일치시키려면 조합의 id를 전달하십시오.
• 이름이 off 또는 default인 조합은 이름으로 선택할 수 없습니다. 해당 키워드가 먼저 해석되기 때문입니다. 이러한 조합은 id로 참조하십시오.
• 마스터 압축 스위치는 절대적인 게이트입니다. 압축이 전역적으로 비활성화되어 있으면 이 헤더로 활성화할 수 없습니다.

적용된 계획은 응답 헤더에 그대로 반환됩니다.

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

여기서 <source>는 request-header, routing-override, active-profile, auto-trigger, default 또는 off 중 하나입니다.

---

임베딩

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

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

사용 가능한 제공업체: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

카탈로그 ID는 provider/model 형식입니다(예: jina-ai/jina-embeddings-v5-omni-small). 레지스트리에 표시되는 Jina 모델 ID만으로도(예: jina-embeddings-v5-text-small, jina-reranker-v3.5) 확인할 수 있습니다. Jina의 임베딩/재순위화/분류/분할은 먼저 대시보드의 jina-ai 자격 증명을 사용하며, 대시보드 키가 없는 경우에만 JINA_AI_API_KEY를 대체 수단으로 사용합니다. jina-reader 카드는 Reader / r.jina.ai 전용이며(POST /v1/web/fetch), 임베딩이나 재순위화에는 사용되지 않습니다.

멀티모달 지원을 명시하는 레지스트리 모델은 제공업체에 종속되지 않는 구조화된 항목도 최대 32개까지 허용합니다. 미디어 항목 유형은 text, image, audio, video, document입니다. 해당 미디어의 source는 {"type":"url","url":"https://..."} 또는 {"type":"base64","data":"...","media_type":"..."}입니다.

Jina v5 Omni(jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano, 그리고 제품군 별칭 jina-ai/jina-embeddings-v5-omni → omni-small)는 Jina의 네이티브 EmbeddingsV5Request 문서도 허용하며, 이를 https://api.jina.ai/v1/embeddings로 변경 없이 전달합니다:

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

네이티브 { image | audio | video | pdf } 값은 공개 HTTPS URL, data: URI 또는 원시 base64일 수 있습니다. OmniRoute는 이러한 객체를 문자열로 변환하거나 네이티브 이미지 URL을 가져오지 않으며, Jina가 공개 미디어를 직접 가져옵니다. 추가 Jina 필드(task, normalized, truncate, embedding_type)도 전달됩니다. 텍스트 전용 Jina SKU는 여전히 텍스트가 아닌 문서를 거부합니다.

보안 및 전송 제한:

• 원격 미디어 URL은 공개 HTTPS여야 합니다. 표준 {type,source:url} 항목은 서버 측에서 가져온 후(리디렉션 재검증, 시간 제한, 크기 제한, 공개 DNS, 연결 고정) 제공업체 호출 전에 인라인으로 포함됩니다. Jina 네이티브 {image:"https://..."} 항목은 동일한 공개 HTTPS 검사를 거친 뒤 그대로 전달되며, Jina가 URL을 가져옵니다.
• 인라인 base64 미디어는 항목당 디코딩 후 8 MiB, 요청 전체에서 디코딩 후 16 MiB로 제한됩니다.

제공업체 변환(표준 항목은 변경 없이 전달되지 않음):

• Jina 멀티모달 모델: 각 최상위 항목은 인라인 미디어에 데이터 URI를 사용하여 하나의 모달리티 키 객체(text / image / audio / video / pdf)가 되며, 최상위 항목당 하나의 벡터가 생성됩니다.
• Gemini Embedding 2 제품군: 하나의 최상위 배열은 content.parts(text 또는 inline_data)를 사용하는 단일 네이티브 models/{model}:embedContent 요청이 됩니다.
• 명시적인 모달리티 메타데이터가 없는 알 수 없는/동적 모델은 구조화된 입력을 HTTP 400으로 거부합니다.

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

지원되지 않는 모델/모달리티 조합은 항목을 강제로 변환하는 대신 HTTP 400을 반환합니다. 레거시 문자열/토큰 요청의 입력 이외 확장 필드는 이전과 마찬가지로 변경 없이 전달됩니다.

# 모든 임베딩 모델 나열
GET /v1/embeddings

---

이미지 생성

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

{
  "model": "openai/gpt-image-2",
  "prompt": "산 너머로 펼쳐지는 아름다운 일몰",
  "size": "1024x1024"
}

사용 가능한 제공자: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (로컬), ComfyUI (로컬).

# 모든 이미지 모델 나열
GET /v1/images/generations

---

문서 OCR

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

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

model은 provider/model 접두사를 통해 OCR 제공자를 선택합니다. 제공자 접두사가 없는 모델 ID(예: mistral-ocr-latest)는 등록된 제공자로 확인되며, model을 생략하면 기본값으로 Mistral(mistral-ocr-latest)이 사용됩니다. 등록된 제공자(open-sse/config/ocrRegistry.ts):

제공자 ID	모델 ID	model 값	참고
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (또는 mistral-ocr-latest)	동기식 — 단일 업스트림 호출의 응답이 직접 반환됩니다.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	비동기 업스트림(analyze + 폴링) — 아래를 참조하세요.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Vertex AI의 openapi/chat/completions 파트너 엔드포인트를 통한 동기식 방식 — 인증/URL은 아래를 참조하세요.

세 제공자 모두 동일한 Mistral 형식의 본문으로 응답합니다.

{
  "pages": [{ "index": 0, "markdown": "# 추출된 텍스트..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Azure Document Intelligence 폴링 흐름

Azure Document Intelligence의 analyze API는 비동기식입니다. 초기 요청은 본문 대신 Operation-Location 헤더를 반환하며, 결과를 얻으려면 폴링해야 합니다. 핸들러 (open-sse/handlers/ocr.ts)는 해당 URL을 1초마다 최대 30회 폴링하고, ok가 아닌 폴링 응답이나 "failed" 상태가 발생하면 즉시 실패 처리하며(폴링을 계속하지 않음), 시도 횟수를 모두 소진한 후에도 작업이 계속 실행 중이면 504를 반환합니다. 최종 Azure 응답은 호출자에게 반환되기 전에 Mistral에서 사용하는 것과 동일한 pages/markdown 형식으로 정규화되므로, 클라이언트 코드에서 제공자별로 별도 처리할 필요가 없습니다.

Vertex AI DeepSeek OCR 인증 및 엔드포인트 확인

vertex-deepseek-ocr은 채팅/이미지 트래픽에 대해 OmniRoute가 이미 지원하는 것과 동일한 Vertex AI 인증(open-sse/executors/vertex.ts)을 재사용합니다. 연결의 API 키는 Service Account JSON 자격 증명(JWT bearer 흐름을 통해 수명이 짧은 OAuth 액세스 토큰으로 교환됨)이거나, 발급 완료된 OAuth 액세스 토큰(그대로 사용됨)입니다. 업스트림 엔드포인트 URL은 연결의 프로젝트와 리전으로 구성되는 Vertex의 범용 openapi/chat/completions 파트너 엔드포인트입니다. 명시적인 providerSpecificData.project/providerSpecificData.region이 항상 우선하며, 그렇지 않으면 프로젝트는 Service Account JSON의 project_id에서 가져오고 리전은 기본적으로 us-central1로 설정됩니다. 두 확인 작업 모두 open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl)에서 수행되며, handleOcr에 전달하기 전에 src/app/api/v1/ocr/route.ts에서 사용됩니다.

---

모델 목록 조회

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

→ OpenAI 형식으로 모든 채팅, 임베딩 및 이미지 모델과 조합을 반환

모델 ID 접두사 (?prefix=)

대부분의 모델은 제공자 접두사 아래에 표시됩니다. 어떤 접두사를 사용할지는 MODELS_CATALOG_PREFIX_MODE 기능 플래그로 제어하며, 쿼리 매개변수를 사용해 요청별로 재정의할 수 있습니다. 이는 다른 모든 사용자의 서버 전체 설정을 변경하지 않고 깔끔한 목록을 원하는 클라이언트에 유용합니다.

GET /v1/models?prefix=alias        # 모델당 하나의 ID — 짧은 별칭 접두사
GET /v1/models?prefix=dual         # 두 형식 모두(서버 기본값)
GET /v1/models?prefix=canonical    # 전체 제공자 ID 접두사만

모드	출력	참고
dual	cc/claude-sonnet-4-6 및 claude/claude-sonnet-4-6	기본값입니다. 두 ID 모두 동일한 모델로 라우팅되며, 두 형식 중 하나를 하드코딩한 클라이언트 설정이 계속 작동하도록 유지됩니다. 카탈로그 크기가 대략 두 배가 됩니다.
alias	cc/claude-sonnet-4-6	모델당 하나의 항목입니다. 고유한 별칭이 없는 제공자도 해당 항목을 계속 출력하므로 누락되는 것은 없습니다.
canonical	claude/claude-sonnet-4-6	전체 제공자 ID 접두사 아래에 모델당 하나의 항목을 출력합니다. 고유한 별칭이 없는 제공자(예: antigravity/…, agy/…)도 여기에서 단일 ID를 출력하므로 누락되는 것은 없습니다.

dual 모드 미러는 쿼리 매개변수 없이도 식별할 수 있습니다. 기본 ID를 가리키는 parent 필드가 포함되어 있기 때문입니다.

모델 선택기를 렌더링하는 클라이언트는 ?prefix=alias를 요청해야 합니다. 이는 OmniCopilot VS Code 확장 프로그램에서 사용하는 방식입니다.

비사고 모델 변형

사고 기능을 지원하는 Claude 모델의 경우 /v1/models는 ID 앞에 claude-3-omniroute-no-thinking/이 붙은 비사고 변형도 표시합니다.

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

이 ID를 선택하면(예: 항상 thinking 블록을 첨부하는 Claude Code 설정에서) 추론이 억제된 실제 <provider>/<model>로 다시 해석됩니다. /v1/messages 경로에서는 thinking:{type:"disabled"}가 적용되고, /v1/chat/completions 경로에서는 reasoning/reasoning_effort 필드가 제거됩니다. 이 변형은 사고 기능을 지원하면서 동시에 disabled를 준수하는 Claude 계열 모델에만 표시됩니다(따라서 예를 들어 disabled를 거부하고 적응형 모드만 지원하는 모델은 제외됩니다). 운영자는 ModelSpec.noThinkingAlias를 통해 모델별로 이 변형을 강제로 활성화하거나 비활성화할 수 있습니다.

---

제공자 플러그인 매니페스트

GET /api/v1/provider-plugin-manifest

Bifrost, CLIProxyAPI 및 향후 사이드카 라우터에서 사용하는 JSON 안전 제공자 플러그인 매니페스트를 반환합니다. 응답은 TypeScript 제공자 레지스트리에서 생성되며 OAuth 클라이언트 시크릿, 런타임 환경 해석, 실행자 함수, 요청 헤더 및 계정 데이터는 의도적으로 제외됩니다.

사이드카가 별도 프로세스로 실행되어 open-sse/config/providerPluginManifestRegistry.ts를 직접 가져올 수 없는 경우 이 엔드포인트를 사용하세요.

---

호환성 엔드포인트

메서드	경로	형식
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	OpenAI Responses
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	OpenAI Images
POST	/v1/images/edits	OpenAI Images(편집/인페인팅)
POST	/v1/videos/generations	OpenAI 스타일 비디오 생성
POST	/v1/music/generations	OpenAI 스타일 음악 생성
POST	/v1/audio/transcriptions	OpenAI Audio(STT)
POST	/v1/audio/speech	OpenAI TTS(오디오 본문 반환)
POST	/v1/rerank	Cohere/Voyage 스타일 재순위화
POST	/v1/classify	Jina 분류(api.jina.ai)
POST	/v1/segment	Jina 세그먼터(segment.jina.ai)
POST	/v1/moderations	OpenAI Moderations
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	OpenAI 카탈로그 별칭
GET	/api/v1/vscode/{token}/models	OpenAI 모델 별칭
POST	/api/v1/vscode/{token}/chat/completions	OpenAI 토큰화 별칭
POST	/api/v1/vscode/{token}/responses	OpenAI Responses 토큰화 별칭
POST	/api/v1/vscode/{token}/api/chat	Ollama 토큰화 별칭
GET	/api/v1/vscode/{token}/api/tags	Ollama 태그 토큰화 별칭

모든 POST 라우트는 Bearer your-api-key + Zod로 검증된 JSON 본문(v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema 등, src/shared/validation/schemas.ts 참조)이라는 동일한 형식을 따릅니다. 스키마 검증에 실패하면 4xx가 반환됩니다.

Authorization: Bearer ...를 첨부할 수 없는 클라이언트를 위해 OmniRoute는 쿼리 문자열 호환 방식(?token=..., ?apiKey=..., ?api_key=..., ?key=...)이나 아래에 설명된 전용 /api/v1/vscode/{token}/... 엔드포인트를 통해 URL의 API 키도 허용합니다.

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

# Jina 분류(Foundation API 자격 증명)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina 세그먼터
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina 검색(s.jina.ai; 제공자 별칭: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — audio/mpeg(또는 요청된 형식) 본문 반환
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# 이미지 편집(multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# 비디오/음악 생성(제공자 접두사가 붙은 모델 ID)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

전용 제공자 라우트

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

제공자 접두사가 없으면 자동으로 추가됩니다. 일치하지 않는 모델은 400을 반환합니다.

---

Files API

배치 입력/출력 및 파일 용도별 업로드를 위한 OpenAI 호환 파일 엔드포인트입니다.

메서드	경로	설명
POST	/v1/files	파일 업로드(multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — 최대 512 MiB
GET	/v1/files	인증된 API 키의 파일 목록 조회
GET	/v1/files/[id]	파일의 메타데이터 조회
DELETE	/v1/files/[id]	파일 삭제
GET	/v1/files/[id]/content	원시 파일 본문을 스트리밍하여 반환

인증: Bearer API 키 — 파일은 getApiKeyRequestScope를 통해 API 키별로 범위가 지정됩니다. 키는 자신의 파일만 조회, 다운로드 및 삭제할 수 있습니다. 키가 없는 대시보드 세션은 전체 인스턴스를 조회할 수 있습니다. 소유자가 없는 파일(익명 또는 대시보드 세션 업로드)은 모든 비세션 호출자의 접근이 거부됩니다. GET /v1/files는 REQUIRE_API_KEY=false인 경우에도 모든 테넌트의 파일을 나열하는 대신, 익명 호출자 및 제공되었지만 확인되지 않는 키에 대해 401을 반환합니다 (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches API

OpenAI 호환 배치 처리입니다.

메서드	경로	설명
POST	/v1/batches	배치 생성 — v1BatchCreateSchema로 본문 검증(input_file_id, endpoint, completion_window)
GET	/v1/batches	배치 목록 조회
GET	/v1/batches/[id]	배치 상태 + request_counts 조회
DELETE	/v1/batches/[id]	완료/실패한 배치 삭제
POST	/v1/batches/[id]/cancel	진행 중인 배치 취소

인증: Bearer API 키. 배치는 파일과 동일한 3가지 규칙에 따라 API 키별로 범위가 지정됩니다. 자신의 키에 속한 항목만 접근 가능하고, 대시보드 세션은 인스턴스 전체에 접근할 수 있으며, 소유자가 null인 레코드는 모든 비세션 호출자의 접근이 거부됩니다(조회, 삭제, 취소 및 생성 시 input_file_id 확인). GET /v1/batches는 REQUIRE_API_KEY=false인 경우에도 익명 호출자에게 401을 반환합니다.

---

검색 API

웹/검색 제공자 추상화(Tavily, Brave, Exa, Serper 등).

메서드	경로	설명
GET	/v1/search	구성된 검색 제공자 및 기능 목록 조회
POST	/v1/search	검색 쿼리 실행 — 본문은 v1SearchSchema로 검증되며 캐싱/병합 지원
GET	/v1/search/analytics	제공자별 적중률/지연 시간/캐시 통계

인증: Bearer API 키(extractApiKey + isValidApiKey). 검색 정책은 enforceApiKeyPolicy를 통해 적용됩니다.

---

웹 가져오기 API

구성된 웹 가져오기 제공자(Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract)를 통해 URL에서 콘텐츠를 추출합니다.

메서드	경로	설명
POST	/v1/web/fetch	URL 가져오기/스크레이핑 — 본문은 v1WebFetchSchema로 검증됨

인증: Bearer API 키(extractApiKey + isValidApiKey). 정책은 enforceApiKeyPolicy를 통해 적용됩니다.

할당량 인식 폴백(#8297): 명시적인 provider가 지정되지 않으면 풀 (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search)을 고정된 우선순위 순서(선순위 우선 소진)로 순회합니다. 속도 제한에 걸렸지만 구성되어 있는 제공자는 요청을 즉시 중단시키는 대신 건너뛰며, 재시도 가능/할당량 관련 업스트림 실패 (HTTP 429는 항상 해당; Firecrawl/Tavily/TinyFish의 할당량 방식 무료 티어에서는 402/403도 해당 — Jina Reader에는 적용되지 않으며, 일반적인 400 잘못된 요청에는 절대 적용되지 않음)가 발생하면 요청 시점에 아직 시도하지 않은 다음 자격 증명 보유 제공자로 넘어갑니다. 풀의 모든 제공자가 소진되면 엔드포인트는 이전의 일반적인 400 대신 단일 429 (Retry-After 헤더 포함)를 반환합니다. 명시적인 provider가 요청된 경우에는 자동 폴백이 없습니다. 속도 제한에 걸리거나 실패한 명시적 제공자는 자체 오류를 그대로 노출합니다(속도 제한이면 429, 그 외에는 업스트림 상태 코드).

---

WebSocket 스트리밍

GET /v1/ws?handshake=1

WebSocket 업그레이드 핸드셰이크를 검증하고 유선 프로토콜 예시 메시지(request, cancel)를 반환합니다. 실제 WS 프레임은 Next.js 라우트 테이블 외부의 번들된 WS 서버에서 처리됩니다.

인증: 핸드셰이크 중 Bearer API 키.

WebSocket을 통한 Responses API(codex 전용)

# HTTP API와 동일한 호스트:포트(기본값 20128)를 사용하고 연결을 업그레이드합니다.
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (또는: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# 첫 번째 프레임은 반드시 response.create여야 합니다.
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

WebSocket을 통한 Responses API 프록시는 codex에만 독점적으로 연결됩니다(ChatGPT 백엔드). 이 프록시는 API/대시보드와 동일한 포트에서 /v1/responses, /responses, /api/v1/responses 경로를 수신합니다. 첫 번째 response.create 프레임에서 내부 codex-responses-ws 브리지를 통해 인증 및 준비하고, codex OAuth 연결을 선택한 후 wreq-js 전송 계층을 통해 wss://chatgpt.com/backend-api/codex/responses로 터널링합니다. codex가 아닌 모델은 거부됩니다(codex_ws_provider_required). 할당량 공유 라우팅에는 model: "qtSd/<group>/codex/<model>"을 사용하세요. 구현 위치는 app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts입니다.

인증: 핸드셰이크 중 Bearer API 키. 번들된 HTTP 서버(server-ws.mjs)가 활성 진입점이어야 합니다(app/server-ws.mjs가 있으면 기본적으로 활성 진입점입니다).

모델 ID: codex/ 접두사 없이 ChatGPT 기본 ID 사용

OpenAI Codex CLI는 supports_websockets = true일 때 클라이언트 측에서 모델 이름을 검증하고 codex/gpt-5.5와 같은 제공자 접두사가 붙은 ID를 거부합니다 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). 기본 ID(예: gpt-5.5)를 전송하세요. OmniRoute의 브리지는 codex 전용이므로 업스트림으로 터널링하기 전에 기본 ID를 codex 모델로 다시 해석합니다(resolveCodexWsModelInfo). 이는 기본 gpt-5.5가 HTTP를 통해서는 다른 제공자로 라우팅될 수 있음에도 적용됩니다.

OpenAI Codex CLI 구성

WebSocket을 지원하는 사용자 지정 제공자를 ~/.codex/config.toml에 추가하여 Codex CLI가 OmniRoute를 가리키도록 설정하세요(기존 구성을 건드리지 않으려면 별도의 CODEX_HOME을 사용하세요).

model = "gpt-5.5"                 # 기본 ID — "codex/gpt-5.5"가 아님
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # 후행 슬래시 없음; WS URL은 여기에서 파생됨(프로덕션에서는 https/wss 사용)
wire_api = "responses"                    # 2026년 2월 이후 유일하게 지원되는 값
supports_websockets = true                # Responses-over-WS 전송 계층 활성화
env_key = "OMNIROUTE_API_KEY"             # OmniRoute API 키를 보관함(Bearer)

export OMNIROUTE_API_KEY=sk-...           # OmniRoute API 키(REQUIRE_API_KEY=false이면 아무 키나 사용 가능)
codex exec "Responda apenas: PONG"

CLI는 base_url + /responses를 WebSocket으로 업그레이드하며 OmniRoute는 이를 선택된 codex OAuth 연결로 터널링합니다. 로컬 서버를 대상으로 엔드투엔드 검증되었습니다. ChatGPT가 codex.rate_limits + response.created를 반환하고 완료 결과를 스트리밍합니다.

---

할당량 및 문제 보고

메서드	경로	설명
GET	/v1/quotas/check	등록된 키를 발급하기 전에 provider + accountId의 할당량을 사전 검증합니다
POST	/v1/issues/report	할당량/키 발급 실패를 GitHub에 보고합니다(GITHUB_ISSUES_REPO + 토큰 필요)

인증: Bearer API 키(isAuthenticated).

---

셀프서비스 사용량 조회(/api/usage/om-usage)

모든 API 키는 관리 인증 없이 자체 사용량과 할당량을 조회할 수 있습니다. 클라이언트(CLI, OmniCopilot 패널)는 이 엔드포인트를 사용해 키 보유자에게 지출액을 표시합니다.

# 텍스트 형식(기존 계약 — 터미널용 일반 텍스트)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# 구조화된 형식 — UI에서 사용하는 형식
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

키에는 **allowUsageCommand**가 활성화되어 있어야 합니다(기본값은 비활성화이며, 대시보드의 API 키 관리자가 키별로 이를 전환합니다). 활성화되어 있지 않으면 엔드포인트가 403을 반환합니다.

?format=json은 호출자가 거부 응답에서 데이터 필드를 읽지 않도록 판별 가능한 구조를 반환합니다. 성공 시:

{
  "allowed": true,
  // 키에서 키별 사용량 한도(일간/주간 USD)를 사용하도록 설정한 경우에만 존재:
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // 선택한 제공자의 할당량 스냅샷. 아직 캐시된 항목이 없으면 null:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // UI에서 여러 제공자를 나란히 렌더링할 수 있도록 모든 연결의 스냅샷 제공:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

거부 시(401: 잘못된 키 / 403: 허용되지 않음), 동일한 경로가 { "allowed": false, "error": { "message": "…" } }를 반환합니다. personal/provider가 존재하지만 비어 있는 상태(키는 허용되었으나 아직 확인된 정보가 없음)는 거부 상태와 다르며, JSON 형식만 이 둘을 구분합니다.

인증: isValidApiKey로 검증된 호출자 본인의 Bearer API 키입니다. 이는 requireManagementAuth로 계속 보호되는 관리 인터페이스(/api/keys/…)가 아닙니다.

---

시맨틱 캐시

# 캐시 통계 조회
GET /api/cache/stats

# 모든 캐시 삭제
DELETE /api/cache/stats

응답 예시:

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

지연 시간에 미치는 영향

시맨틱 캐시 HIT 시 업스트림 호출 없이 캐시에서 응답을 제공하므로, 보고되는 X-OmniRoute-Response-Latency는 원래 업스트림 지연 시간과 관계없이 거의 0에 가깝습니다. 지연 시간에 민감한 클라이언트(벤치마킹, p50/p99 모니터링)는 X-OmniRoute-Cache-Latency 응답 헤더를 확인해야 합니다.

값	의미
synthetic	캐시에서 제공된 응답이며, 지연 시간은 실제 업스트림 시간이 아님
(없음)	실제 업스트림 호출에서 제공된 응답

키별 캐시 우회

API 키는 cacheDefaultMode를 통해 시맨틱 캐시 읽기를 사용하지 않도록 설정할 수 있습니다.

값	동작
legacy	일반적인 캐시 동작(기본값)
bypass	캐시 조회를 완전히 건너뛰고 항상 업스트림을 호출

키 생성 시(POST /api/keys) 설정하거나 업데이트할 수 있습니다(PATCH /api/keys/[id]).

{ "cacheDefaultMode": "bypass" }

요청별 우회

모든 요청은 키 설정과 관계없이 캐시를 우회할 수 있습니다.

X-OmniRoute-No-Cache: true

---

대시보드 및 관리

관리 라우트(공개 인증/로그인을 제외한 /api/*)는 일반 추론 API 키로 인증되지 않습니다. 자격 증명 유형, 범위 및 curl 예시는 다음을 참조하세요. 관리 인증.

인증

엔드포인트	메서드	설명
/api/auth/login	POST	로그인
/api/auth/logout	POST	로그아웃
/api/settings/require-login	GET/PUT	로그인 필수 여부 전환

공급자 관리

엔드포인트	메서드	설명
/api/providers	GET/POST	공급자 목록 조회/생성
/api/providers/[id]	GET/PUT/DELETE	공급자 관리
/api/providers/[id]/test	POST	공급자 연결 테스트
/api/providers/[id]/models	GET	공급자 모델 목록 조회
/api/providers/validate	POST	공급자 구성 검증
/api/providers/bulk	POST	단일 공급자의 API 키 일괄 추가
/api/providers/import	POST	파싱된 CSV/JSON 파일에서 여러 유형의 공급자 목록 가져오기(#6836), 행별 부분 실패 결과 제공
/api/provider-nodes*	다양함	공급자 노드 관리
/api/provider-models	GET/POST/PATCH/DELETE	사용자 지정 모델(추가, 업데이트, 숨기기/표시, 삭제)

OAuth 흐름

엔드포인트	메서드	설명
/api/oauth/[provider]/[action]	다양함	공급자별 OAuth

라우팅 및 구성

엔드포인트	메서드	설명
/api/models/alias	GET/POST	모델 별칭
/api/models/catalog	GET	공급자 및 유형별 모든 모델
/api/combos*	다양함	콤보 관리
/api/keys*	다양함	API 키 관리
/api/pricing	GET	모델 요금

사용량 및 분석

엔드포인트	메서드	설명
/api/usage/history	GET	사용량 기록
/api/usage/logs	GET	사용량 로그
/api/usage/request-logs	GET	요청 수준 로그
/api/usage/[connectionId]	GET	연결별 사용량
/api/usage/token-limits	GET/POST/DELETE	API 키별 토큰 한도 예산
/api/usage/model-latency-stats	GET	공급자/모델별 이동 지연 시간 집계(avg/p50/p95/p99, 성공률); 필터: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	call_logs에 대한 프롬프트 캐시 상태 요약 — 쓰기/읽기 비율, p50/p90/p99 쓰기 크기 분포, 대량 쓰기 집중도, 모델별 분석 및 healthy/degraded/thrash/no-data 판정; 쿼리 매개변수 range (1h|24h|7d|30d, 기본값 24h) 및 선택적 model (#8827)

설정

엔드포인트	메서드	설명
/api/settings	GET/PUT/PATCH	일반 설정
/api/settings/proxy	GET/PUT	네트워크 프록시 구성
/api/settings/proxy/test	POST	프록시 연결 테스트
/api/settings/ip-filter	GET/PUT	IP 허용 목록/차단 목록
/api/settings/thinking-budget	GET/PUT	사고/추론 요청 재작성 모드(passthrough / auto-strip / custom / adaptive). 압축과는 별개입니다. THINKING_BUDGET.md를 참조하세요.
/api/settings/system-prompt	GET/PUT	전역 시스템 프롬프트
/api/settings/compression	GET/PUT	전역 압축 구성
/api/settings/purge-request-history	POST	요청 로그 행 및 로컬 호출 로그 아티팩트 삭제

컨텍스트 및 압축

엔드포인트	메서드	설명
/api/compression/preview	POST	off/lite/standard/aggressive/ultra/RTK/stacked 압축 미리보기
/api/compression/language-packs	GET	사용 가능한 Caveman 언어 팩 목록
/api/compression/rules	GET	Caveman 규칙 메타데이터 목록
/api/context/caveman/config	GET/PUT	Caveman 전용 설정 별칭
/api/context/rtk/config	GET/PUT	사용자 지정 필터 및 원시 출력 보존을 포함한 RTK 전용 설정
/api/context/rtk/filters	GET	RTK 필터 카탈로그 및 사용자 지정 필터 진단
/api/context/rtk/test	POST	텍스트 페이로드를 대상으로 RTK 미리보기/테스트 실행
/api/context/rtk/raw-output/[id]	GET	포인터 ID로 보존된 민감 정보 제거 원시 출력 읽기
/api/context/combos	GET/POST	압축 조합 목록/생성
/api/context/combos/[id]	GET/PUT/DELETE	압축 조합 상세 정보/업데이트/삭제
/api/context/combos/[id]/assignments	GET/PUT	라우팅 조합에 압축 조합 할당
/api/context/analytics	GET	압축 분석 별칭

모니터링

엔드포인트	메서드	설명
/api/sessions	GET	활성 세션 추적
/api/rate-limits	GET	계정별 요청 한도
/api/monitoring/health	GET	상태 확인 + 제공자 요약(catalogCount, configuredCount, activeCount, monitoredCount). 관리 보기에는 credentialHealth가 포함됩니다. 이는 프로브 캐시 스칼라, failed>0인 경우의 failedConnections, 그리고 staleDbNonOkCount(게이지가 아닌 SQLite 고정 test_status)로 구성됩니다. MONITORING_GUIDE.md를 참조하세요.
/api/cache/stats	GET/DELETE	캐시 통계 / 지우기
/api/modality-bridge/stats	GET	메모리 내 attempts, 성공 횟수/bridged, 실패 횟수, 캐시 적중 횟수, totalLatencyMs, latencySamples, 샘플 수를 분모로 계산한 averageLatencyMs, 마지막 사용 시간(재시작 시 초기화, 관리 인증 필요)
/api/modality-bridge/video/runtime	GET	관리 인증/프로브 전에 엄격한 신뢰된 루프백 검사 수행, 정제된 FFmpeg/ffprobe 가용성 및 버전(no-store)
/api/modality-bridge/video/extract	POST	내부 인증된 신뢰 루프백 바이트 브로커. 입력 50 MiB, 제한된 큐/출력 32 MiB, 용량 초과 시 503, 연결 해제 시 499, 기한 초과 시 504. 공개 업로드 API가 아님

백업 및 내보내기/가져오기

엔드포인트	메서드	설명
/api/db-backups	GET	사용 가능한 백업 목록 조회
/api/db-backups	PUT	수동 백업 생성
/api/db-backups	POST	특정 백업에서 복원
/api/db-backups/export	GET	데이터베이스를 .sqlite 파일로 다운로드
/api/db-backups/import	POST	데이터베이스를 교체할 .sqlite 파일 업로드
/api/db-backups/exportAll	GET	전체 백업을 .tar.gz 아카이브로 다운로드

클라우드 동기화

엔드포인트	메서드	설명
/api/sync/cloud	다양함	클라우드 동기화 작업
/api/sync/initialize	POST	동기화 초기화
/api/cloud/*	다양함	클라우드 관리

터널

엔드포인트	메서드	설명
/api/tunnels/cloudflared	GET	대시보드용 Cloudflare Quick Tunnel 설치/런타임 상태 조회
/api/tunnels/cloudflared	POST	Cloudflare Quick Tunnel 활성화 또는 비활성화(action=enable/disable)
/api/tunnels/ngrok	GET	대시보드용 ngrok Tunnel 런타임 상태 조회
/api/tunnels/ngrok	POST	ngrok Tunnel 활성화 또는 비활성화(action=enable/disable)

CLI 도구

엔드포인트	메서드	설명
/api/cli-tools/claude-settings	GET	Claude CLI 상태
/api/cli-tools/codex-settings	GET	Codex CLI 상태
/api/cli-tools/droid-settings	GET	Droid CLI 상태
/api/cli-tools/openclaw-settings	GET	OpenClaw CLI 상태
/api/cli-tools/runtime/[toolId]	GET	일반 CLI 런타임

CLI 응답에는 installed, runnable, command, commandPath, runtimeMode, reason이 포함됩니다.

ACP 에이전트

엔드포인트	메서드	설명
/api/acp/agents	GET	감지된 모든 에이전트(기본 제공 + 사용자 정의)와 상태 목록 조회
/api/acp/agents	POST	사용자 정의 에이전트 추가 또는 감지 캐시 새로 고침
/api/acp/agents	DELETE	id 쿼리 매개변수로 사용자 정의 에이전트 제거

GET 응답에는 agents[](id, name, binary, version, installed, protocol, isCustom)와 summary(total, installed, notFound, builtIn, custom)가 포함됩니다.

복원력 및 속도 제한

엔드포인트	메서드	설명
/api/resilience	GET/PATCH	요청 대기열, 연결 쿨다운, 제공자 차단기 및 대기 설정 조회/업데이트
/api/resilience/reset	POST	제공자 회로 차단기 재설정
/api/resilience/model-cooldowns	GET	활성화된 (제공자, 연결, 모델)별 잠금 목록을 남은 시간순으로 조회
/api/resilience/model-cooldowns	DELETE	모델 잠금 해제 — 본문에 {provider, model}을 사용하거나 모든 항목을 삭제하려면 {all: true} 사용
/api/rate-limits	GET	계정별 속도 제한 상태
/api/rate-limit	GET	전역 속도 제한 구성

네 개의 /api/resilience/* 경로는 모두 관리 인증(requireManagementAuth)이 필요합니다. 제공자 차단기, 연결 쿨다운, 모델 잠금 간의 차이에 대한 전체 설명은 복원력(확장)을 참조하세요.

평가

엔드포인트	메서드	설명
/api/evals	GET/POST	평가 스위트 목록 조회 / 평가 실행

정책

엔드포인트	메서드	설명
/api/policies	GET/POST/DELETE	라우팅 정책 관리

규정 준수

엔드포인트	메서드	설명
/api/compliance/audit-log	GET	규정 준수 감사 로그(최근 N개)

v1beta(Gemini 호환)

엔드포인트	메서드	설명
/v1beta/models	GET	Gemini 형식으로 모델 목록 조회
/v1beta/models/{...path}	POST	Gemini generateContent 엔드포인트

이러한 엔드포인트는 네이티브 Gemini SDK 호환성을 요구하는 클라이언트를 위해 Gemini의 API 형식을 그대로 따릅니다.

내부 / 시스템 API

엔드포인트	메서드	설명
/api/init	GET	애플리케이션 초기화 확인(최초 실행 시 사용)
/api/tags	GET	Ollama 호환 모델 태그(Ollama 클라이언트용)
/api/restart	POST	정상적인 서버 재시작 실행
/api/shutdown	POST	정상적인 서버 종료 실행
/api/system/env/repair	POST	OAuth 제공자 환경 변수 복구

참고: 이러한 엔드포인트는 시스템 내부에서 사용되거나 Ollama 클라이언트와의 호환성을 위해 사용됩니다. 일반적으로 최종 사용자가 직접 호출하지 않습니다.

OAuth 환경 복구 (v3.6.1+)

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

{
  "provider": "claude-code"
}

특정 제공자의 누락되거나 손상된 OAuth 환경 변수를 복구합니다. 다음을 반환합니다.

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

---

오디오 전사

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

구성된 STT 제공자를 사용하여 오디오 파일을 전사합니다. 첫 번째 경로 세그먼트는 기본 제공자(openai/…, deepgram/…)를 선택합니다. 다른 공급업체의 모델을 다시 제공하는 게이트웨이는 정규화된 ID를 사용합니다 (openrouter/deepgram/nova-3).

요청:

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

응답:

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

모델 ID 예시: openai/whisper-1(OpenAI 키 필요), openrouter/deepgram/nova-3(OpenRouter 키 필요), deepgram/nova-3(기본 Deepgram 키 필요). 정규화되지 않은 deepgram/nova-3 요청은 OpenRouter를 사용하지 않습니다.

지원 형식: mp3, wav, m4a, flac, ogg, webm.

---

Ollama 호환성

Ollama의 API 형식을 사용하는 클라이언트의 경우:

# 채팅 엔드포인트(Ollama 형식)
POST /v1/api/chat

# 모델 목록(Ollama 형식)
GET /api/tags

요청은 Ollama 형식과 내부 형식 간에 자동으로 변환됩니다.

토큰화된 VS Code / 헤더 없는 별칭

통합에서 Authorization 헤더를 삽입할 수 없어 API 키를 기본 URL에 포함해야 하는 경우 다음 별칭을 사용하세요.

# OpenAI 스타일 카탈로그 별칭
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI 스타일 채팅 별칭
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama 스타일 별칭
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

예시:

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

참고:

• 토큰화된 별칭은 /v1/* 및 /api/tags와 동일한 핸들러를 재사용하므로 응답 형식은 동일하게 유지됩니다.
• 클라이언트가 사용자 지정 헤더를 지원하는 경우 항상 Authorization: Bearer ...를 사용하는 것이 좋습니다.
• URL 기반 토큰은 OmniRoute 외부의 리버스 프록시 로그, 브라우저 기록 및 텔레메트리에 나타날 수 있습니다. 이를 기본 인증 방식이 아닌 호환성 옵션으로 취급하세요.

---

텔레메트리

# 지연 시간 텔레메트리 요약 가져오기(제공자별 p50/p95/p99)
GET /api/telemetry/summary

응답:

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

---

예산

# 모든 API 키의 예산 상태 가져오기
GET /api/usage/budget

# 예산 설정 또는 업데이트
POST /api/usage/budget
Content-Type: application/json

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

스키마 참고 사항 (setBudgetSchema): apiKeyId는 필수이며, dailyLimitUsd, weeklyLimitUsd, monthlyLimitUsd 중 하나 이상이 0보다 커야 합니다. 선택적 필드: warningThreshold(0–1), resetInterval(daily | weekly | monthly), resetTime(HH:MM). 기존 {keyId, limit, period} 형식은 400 Bad Request를 반환합니다.

토큰 한도

API 키별 토큰 예산입니다(위의 USD 기반 예산과는 별개). 요청 경로에서 인라인으로 적용됩니다. 키의 현재 기간 사용량이 한도에 도달하면 요청이 429 Too Many Requests로 거부됩니다. 한도는 특정 model, provider에 지정하거나 키 전체에 global로 적용할 수 있습니다. 하나의 요청에 여러 한도가 일치하면 가장 제한적인 한도가 적용됩니다.

# 키의 토큰 한도 목록 조회(현재 기간의 실시간 사용량 포함)
GET /api/usage/token-limits?apiKeyId=key-123

# 토큰 한도 생성 또는 업데이트
POST /api/usage/token-limits
Content-Type: application/json

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

# id로 토큰 한도 삭제
DELETE /api/usage/token-limits?id=tl-abc

스키마 참고 사항 (setTokenLimitSchema): apiKeyId와 scopeType(model | provider | global)은 필수입니다. scopeType이 global이 아닌 경우 scopeValue가 필수입니다(예: model 범위에는 모델 ID, provider 범위에는 제공자 ID). tokenLimit는 양의 정수여야 합니다(문자열에서 강제 변환됨). 선택 사항: id(생성 시 생략하고 업데이트 시 지정), resetInterval(daily | weekly | monthly, 기본값 monthly), resetTime(HH:MM), enabled(기본값 true). GET 응답에서는 각 한도에 tokensUsed, remaining, windowStart, periodStartAt, nextResetAt가 추가됩니다. 이는 관리 클래스 엔드포인트입니다(인증은 authz 파이프라인에서 중앙 집중식으로 적용됨).

요청 처리

1. 클라이언트가 /v1/*로 요청을 전송합니다
2. 라우트 핸들러가 handleChat, handleEmbedding, handleAudioTranscription 또는 handleImageGeneration을 호출합니다
3. 모델을 확인합니다(직접 지정한 제공자/모델 또는 별칭/콤보)
4. 계정 가용성 필터링을 사용하여 로컬 DB에서 자격 증명을 선택합니다
5. 채팅의 경우 handleChatCore가 의미론적/서명 캐시를 확인하고 콤보 압축 설정을 확인합니다
6. 활성화된 경우 제공자 형식으로 변환하기 전에 선제적 압축을 실행합니다(lite, Caveman, RTK 또는 스택 방식)
7. 제공자 실행기가 업스트림 요청을 전송합니다
8. 응답을 클라이언트 형식으로 다시 변환하거나(채팅), 그대로 반환합니다(임베딩/이미지/오디오)
9. 사용량, 압축 분석 및 요청 로그를 기록합니다
10. 오류 발생 시 콤보 규칙에 따라 폴백을 적용합니다

전체 아키텍처 참고 문서: ARCHITECTURE.md

---

콤보 관리

상위 수준의 라우팅 콤보(/api/combos*에서 이미 요약됨)는 모델 ID 패턴과 1:1로 매핑할 수도 있어, OpenAI 스타일의 모델 ID를 콤보로 투명하게 리디렉션할 수 있습니다.

메서드	경로	설명
GET	/api/model-combo-mappings	모든 모델→콤보 매핑 조회
POST	/api/model-combo-mappings	매핑 생성 — 본문: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	단일 매핑 조회
PUT	/api/model-combo-mappings/[id]	기존 매핑의 필드 업데이트
DELETE	/api/model-combo-mappings/[id]	매핑 삭제

인증: 관리 세션/API 키(requireManagementAuth).

---

웹훅

OmniRoute 이벤트(요청 완료, 할당량 소진, 키 교체 등)에 대한 아웃바운드 웹훅 구독입니다.

메서드	경로	설명
GET	/api/webhooks	웹훅 목록 조회(시크릿은 <prefix>... 형식으로 마스킹됨)
POST	/api/webhooks	웹훅 생성 — 본문: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	웹훅 조회
PUT	/api/webhooks/[id]	url/events/secret/description 업데이트
DELETE	/api/webhooks/[id]	웹훅 제거
POST	/api/webhooks/[id]/test	웹훅 URL로 테스트 페이로드를 전송하고 전달 상태 반환

인증: 관리 세션/API 키(requireManagementAuth).

---

등록된 키(자동 관리)

자동 키 관리 하위 시스템에서 기반 제공자/계정에 대해 일별/시간별 할당량을 적용하여 API 키를 발급하고 교체하는 데 사용됩니다.

메서드	경로	설명
GET	/api/v1/registered-keys	등록된 키 목록 조회(마스킹된 접두사만 표시)
POST	/api/v1/registered-keys	새 등록 키 발급 — 본문: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. 원본 키는 한 번만 반환됩니다. 할당량으로 인해 거부되면 429를 반환합니다.
GET	/api/v1/registered-keys/[id]	등록된 키의 메타데이터 조회(원본 키 자료 제외)
DELETE	/api/v1/registered-keys/[id]	등록된 키 폐기
POST	/api/v1/registered-keys/[id]/revoke	명시적 폐기 엔드포인트(DELETE와 동일한 효과)

인증: Bearer API 키(isAuthenticated). /v1/quotas/check 및 /v1/issues/report도 참조하세요.

---

에이전트 프로토콜

OmniRoute 사용자를 대신해 원격으로 실행되는 클라우드 에이전트 작업(Claude Code, Codex Cloud, OpenHands 등)입니다.

메서드	경로	설명
GET	/api/v1/agents/tasks	작업 목록 — 선택적 ?provider=, ?status=, ?limit=(1~500, 기본값 50)
POST	/api/v1/agents/tasks	작업 생성 — 본문은 CreateCloudAgentTaskSchema(providerId, prompt, source, options?)로 검증됩니다. 작업 엔벌로프와 함께 201을 반환합니다
DELETE	/api/v1/agents/tasks?id=...	작업 삭제
GET	/api/v1/agents/tasks/[id]	작업 조회 — external_id가 설정된 경우 업스트림 클라우드 에이전트에서 상태를 동기식으로 새로 고칩니다
POST	/api/v1/agents/tasks/[id]	구분된 작업: {action: "approve"}, {action: "message", message} 또는 {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	id로 특정 작업 삭제

인증: 모든 메서드에 관리 인증이 필요합니다(requireCloudAgentManagementAuth). v3.8.0 이전에는 인증이 필요하지 않았습니다. 호환성을 깨뜨리는 변경 사항은 커밋 588a0333을 참조하세요.

# Claude Code 클라우드 작업 생성
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

---

관리 프록시

프로바이더, 계정 또는 전역에 할당할 수 있는 아웃바운드 HTTP(S)/SOCKS 프록시입니다.

메서드	경로	설명
GET	/api/v1/management/proxies	프록시 목록 조회(?id=를 사용하면 하나를 반환하고, ?id=&where_used=1을 사용하면 할당 그래프를 반환합니다)
POST	/api/v1/management/proxies	프록시 생성 — 본문은 createProxyRegistrySchema로 검증됩니다
PATCH	/api/v1/management/proxies	프록시 업데이트 — 본문은 updateProxyRegistrySchema로 검증됩니다(id 필요)
DELETE	/api/v1/management/proxies?id=...&force=1	프록시 삭제(할당을 해제하려면 force=1 사용)
GET	/api/v1/management/proxies/assignments	할당 목록 — proxy_id, scope, scope_id로 필터링할 수 있습니다. 연결의 활성 프록시를 확인하려면 resolve_connection_id=<id>를 전달하세요
PUT	/api/v1/management/proxies/assignments	할당 — 본문은 proxyAssignmentSchema({scope, scopeId?, proxyId?})로 검증됩니다. 디스패처 캐시를 지웁니다
PUT	/api/v1/management/proxies/bulk-assign	일괄 할당 — 본문은 bulkProxyAssignmentSchema({scope, scopeIds[], proxyId?})로 검증됩니다
GET	/api/v1/management/proxies/health?hours=24	일정 기간의 프록시 상태 집계(성공/실패 횟수, 지연 시간)

인증: 모든 라우트에 관리 세션/API 키가 필요합니다(requireManagementAuth).

작업 설명의 POST /api/v1/management/proxies/[id]/assignments 및 POST /api/v1/management/proxies/[id]/health는 위에 표시된 플랫 /assignments 및 /health 라우트에서 처리됩니다. 코드베이스에는 id별 하위 라우트가 없습니다.

---

복원력(확장)

OmniRoute는 서로 독립적인 세 가지 일시적 장애 대응 메커니즘을 제공합니다. 아래 관리 엔드포인트를 통해 운영자는 해당 상태를 조회하고 재정의할 수 있습니다.

범위	상태 저장소	조회	재설정 / 해제
공급자 차단기	domain_circuit_breakers + 인메모리	/api/monitoring/health	POST /api/resilience/reset
연결 쿨다운	공급자 연결의 rateLimitedUntil	/api/rate-limits, /api/providers/[id]	(지연 방식으로 다시 활성화됨. 공급자 PUT을 통해 해제)
모델 잠금	인메모리 모델 가용성 레지스트리	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience는 providerBreaker.oauth 및 providerBreaker.apikey에서 공급자 차단기 재정의를 허용합니다. 각 프로필은 degradationThreshold, failureThreshold, resetTimeoutMs를 지원하며, 동일한 필드를 대시보드 → 설정 → 복원력에서도 사용할 수 있습니다.

# 단일 모델 잠금 해제
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# 모든 잠금 삭제
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

전체 개념 설명과 차단기 기본값은 CLAUDE.md → "복원력 런타임 상태"를 참조하세요.

---

스킬

사용자 정의 실행 가능 핸들러와 마켓플레이스 통합을 통해 OmniRoute를 확장하는 스킬 프레임워크입니다.

메서드	경로	설명
GET	/api/skills	설치된 스킬 목록 — ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local로 필터링 가능, 페이지네이션 지원
GET	/api/skills/[id]	스킬 하나 조회
PUT	/api/skills/[id]	스킬 업데이트(name, description, mode, schema, handler, tags)
DELETE	/api/skills/[id]	스킬 제거
POST	/api/skills/install	원시 매니페스트에서 스킬 설치 — 본문: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	최근 스킬 실행 목록(입력/출력/실행 시간이 포함된 감사 추적)
GET	/api/skills/marketplace?q=...	SkillsMP 마켓플레이스에서 검색/인기 목록 조회(skillsmpApiKey 설정 필요)
POST	/api/skills/marketplace/install	SkillsMP에서 id로 스킬 설치
GET	/api/skills/skillssh?q=&limit=	skills.sh 레지스트리 검색
POST	/api/skills/skillssh/install	skills.sh에서 id로 스킬 설치

인증: 관리 세션/API 키. 마켓플레이스 검색 경로는 관리 인증 또는 Bearer API 키(isAuthenticated)를 허용합니다.

---

메모리

API 키/세션별로 범위가 지정되는 영구 대화/사실 메모리 저장소입니다.

메서드	경로	설명
GET	/api/memory	메모리 목록 — ?apiKeyId=, ?type=, ?sessionId=, ?q=, offset/limit 또는 page/limit 페이지네이션
POST	/api/memory	메모리 생성 — Zod로 검증되는 본문: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	단일 메모리 조회
DELETE	/api/memory/[id]	메모리 삭제
GET	/api/memory/health	메모리 하위 시스템 상태(DB 연결, 임베딩 백엔드, 벡터 인덱스 상태)

인증: 관리 세션/API 키(requireManagementAuth). type 열거형: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL(src/lib/memory/types.ts의 MemoryType 참조).

---

MCP 서버

OmniRoute에는 3가지 전송 방식(stdio, SSE, streamable-http)과 범위가 지정된 도구를 지원하는 Model Context Protocol 서버가 내장되어 있습니다. 아래의 대시보드 엔드포인트는 상태/감사 데이터를 읽고 HTTP 전송을 프록시합니다.

메서드	경로	설명
GET	/api/mcp/status	하트비트, 전송 방식, 온라인 상태, 마지막 호출, 상위 도구, 24시간 성공률
GET	/api/mcp/tools	name, description, scopes, phase, auditLevel, sourceEndpoints가 포함된 MCP 도구 목록
GET	/api/mcp/sse	SSE 전송용 SSE 스트림 열기(MCP가 비활성화되었거나 전송 방식이 일치하지 않으면 503 반환)
POST	/api/mcp/sse	SSE 전송을 통해 JSON-RPC 프레임 전송
GET	/api/mcp/stream	Streamable HTTP 전송의 SSE 측 열기(서버에서 시작되는 메시지)
POST	/api/mcp/stream	Streamable HTTP 전송을 통해 JSON-RPC 프레임 전송
DELETE	/api/mcp/stream	Streamable HTTP 세션 종료
GET	/api/mcp/audit	감사 로그 조회 — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	집계된 감사 통계(총계, 성공률, 평균 소요 시간, 상위 도구)

인증: sse/stream 전송은 MCP 전용 인증 방식(mcp 범위가 있는 Bearer API 키)을 따릅니다. status/tools/audit* 경로는 대시보드에서 읽을 수 있습니다(대시보드 호스트에 접근하는 것 외에 추가 인증은 필요하지 않음).

두 HTTP 전송 모두 settings.mcpEnabled 및 settings.mcpTransport에 의해 제어됩니다. 전송 방식이 일치하지 않으면 400, MCP가 비활성화된 상태이면 503을 반환합니다.

---

A2A 서버

OmniRoute는 A2A(Agent-to-Agent) JSON-RPC 2.0 엔드포인트와 검사/대시보드용 REST 래퍼를 제공합니다.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # OMNIROUTE_API_KEY가 설정되지 않은 경우 선택 사항
Content-Type: application/json

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

지원되는 메서드(모두 settings.a2aEnabled에 의해 제어됨):

메서드	설명
message/send	동기식 스킬 실행; {task, artifacts, metadata}를 반환
message/stream	동일한 스킬 세트의 스트리밍 SSE 실행
tasks/get	taskId로 태스크 조회
tasks/cancel	taskId로 태스크 취소

기본 제공 스킬: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

에이전트 카드

GET /.well-known/agent.json

공개 A2A 에이전트 카드(이름, 설명, 기능, 스킬 카탈로그, 인증 체계)를 반환하며, 공개적으로 1시간 동안 캐시됩니다. 인증은 필요하지 않습니다.

REST 헬퍼

메서드	경로	설명
GET	/api/a2a/status	A2A 활성화 여부 + 태스크 통계 + 캐시된 에이전트 카드 요약
GET	/api/a2a/tasks	태스크 목록 — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(REST 헬퍼로 구현되지 않음 — JSON-RPC message/send를 통해 생성)
GET	/api/a2a/tasks/[id]	단일 태스크 조회
POST	/api/a2a/tasks/[id]/cancel	태스크 취소

인증: REST 헬퍼는 관리 인증 없이 실행됩니다(대시보드에서 읽기 가능). JSON-RPC /a2a 경로는 설정된 경우 Bearer OMNIROUTE_API_KEY를 사용합니다.

---

클라우드, 평가 및 진단

메서드	경로	설명
POST	/api/cloud/auth	Bearer 키를 검증하고 클라우드 동기화 클라이언트용으로 마스킹된 제공자 연결 + 모델 별칭 반환
POST	/api/cloud/credentials/update	클라우드와 동기화된 제공자의 암호화된 자격 증명 업데이트
POST	/api/cloud/model/resolve	로컬 라우팅 테이블을 사용하여 논리적 모델 ID를 구체적인 제공자/모델로 해석
GET	/api/cloud/models/alias	클라우드 동기화에 노출되는 모델 별칭 목록
GET	/api/assess	최신 진단 분류 결과 읽기(제공자/모델별)
POST	/api/assess	진단 실행 — 본문: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	기본 제공 평가 스위트 + 최신 실행 목록
POST	/api/evals	평가 실행 트리거
POST	/api/evals/suites	사용자 지정 평가 스위트 생성 — evalSuiteSaveSchema로 본문 검증
GET	/api/evals/suites/[id]	사용자 지정 평가 스위트 조회

인증: /api/cloud/auth는 Bearer 키를 직접 검증합니다. 그 외 /api/cloud/*, /api/evals/*, /api/assess 경로에는 관리 세션/API 키가 필요합니다. /api/assess POST는 판별 유니온 범위 스키마와 함께 validateBody를 사용합니다.

---

ACP(Agent Client Protocol) 관리

자식 프로세스로 실행됩니다. 이러한 엔드포인트는 ACP 에이전트 감지 및 사용자 지정 에이전트 등록을 관리합니다.

메서드	경로	설명
GET	/api/acp/agents	설치 상태, 버전, 바이너리를 포함하여 알려진 모든 CLI 에이전트(기본 제공 + 사용자 지정) 목록 조회
POST	/api/acp/agents	사용자 지정 ACP 에이전트 등록 또는 캐시 새로 고침 — 본문: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} 또는 {action: "refresh"}
DELETE	/api/acp/agents	사용자 지정 ACP 에이전트 제거 — 쿼리 매개변수: ?id=<agentId>

응답 예시 (GET /api/acp/agents):

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

인증: 관리 세션(대시보드 auth_token 쿠키) 또는 관리 범위 API 키가 필요합니다.

자세한 내용은 ACP 프레임워크를 참조하세요.

---

분석 및 관측 가능성

라우팅, 압축 및 제공자 다양성을 모니터링하기 위한 실시간 분석 엔드포인트입니다. 이러한 엔드포인트는 /dashboard/analytics/* 페이지를 지원합니다.

자동 라우팅 분석

메서드	경로	설명
GET	/api/analytics/auto-routing	자동 라우팅 통계 집계: 총 호출 수, 전략 분포, 티어 분포, 상위 제공자
GET	/api/analytics/auto-routing?days=7	기간별 통계(기본값 24시간)

응답 예시:

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

압축 분석

메서드	경로	설명
GET	/api/analytics/compression	압축 통계 집계: 절감된 토큰 수, 절감률(%), 모드 분포, 엔진 사용량

응답 예시:

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

제공자 다양성 추적

메서드	경로	설명
GET	/api/analytics/diversity	섀넌 엔트로피 기반 다양성 추적: 제공자 분산도를 측정하여 단일 장애 지점 방지

응답 예시:

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

인증: 관리 세션 또는 관리 범위 API 키가 필요합니다.

---

관리자 작업

운영 관리를 위한 관리자 전용 엔드포인트입니다.

메서드	경로	설명
GET	/api/admin/concurrency	현재 동시 실행 제한 조회(전역 + 제공자별)
POST	/api/admin/concurrency	동시 실행 제한 업데이트 — 본문: {global?: number, perProvider?: Record<string, number>}

인증: 관리자 범위가 있는 관리 세션이 필요합니다.

---

CLI 도구 관리

OmniRoute와 통합되는 CLI 도구(antigravity, chipotle, commandCode, devin-cli 등)를 관리합니다. 전체 목록은 제공자 참조를 확인하세요.

메서드	경로	설명
GET	/api/cli-tools/all-statuses	모든 CLI 도구의 상태(설치 여부, 버전, 마지막 확인 시점)
GET	/api/cli-tools/status	단일 CLI 도구의 상세 상태(?tool= 쿼리)
POST	/api/cli-tools/apply	도구에 대해 생성된 구성을 기록(dryRun으로 미리 보기, 컨테이너 환경에서는 422 + containerEphemeralTarget, migration은 레거시 Codex YAML을 나타냄)
GET	/api/cli-tools/backups	CLI 도구 구성 백업 목록 조회
POST	/api/cli-tools/backups	모든 CLI 도구 구성의 백업 생성
POST	/api/cli-tools/backups	복원: 동일한 엔드포인트의 본문에 {tool, backupId}를 포함하면 해당 백업을 복원
GET	/api/cli-tools/antigravity-mitm	Antigravity MITM 프록시 상태("antigravity-mitm" CLI 도구)
POST	/api/cli-tools/antigravity-mitm/alias	antigravity-mitm 별칭 구성

인증: 관리 세션이 필요합니다.

---

에이전트 스킬

AI 에이전트 스킬(에이전트용이라는 점을 제외하면 OpenAI의 사용자 지정 GPT와 유사)을 관리합니다.

메서드	경로	설명
GET	/api/agent-skills	모든 에이전트 스킬 목록 조회(기본 제공 + 사용자 지정)
GET	/api/agent-skills/[id]	특정 에이전트 스킬 조회
POST	/api/agent-skills	사용자 지정 에이전트 스킬 생성 — 본문: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	사용자 지정 에이전트 스킬 업데이트
DELETE	/api/agent-skills/[id]	사용자 지정 에이전트 스킬 삭제
GET	/api/agent-skills/[id]/raw	원시 프롬프트 + 메타데이터 조회(실행하지 않음)
POST	/api/agent-skills/generate	자연어 설명을 기반으로 AI를 사용해 새 스킬 생성

인증: 관리 세션 또는 관리 범위가 있는 API 키가 필요합니다.

---

캐시 관리

시맨틱 캐시와 추론 캐시를 관리합니다.

메서드	경로	설명
GET	/api/cache	캐시 개요: 전체 항목 수, 적중률, 디스크 사용량
GET	/api/cache/entries	캐시된 항목 목록 조회(페이지네이션 지원)
DELETE	/api/cache/entries	캐시 항목 삭제(쿼리 매개변수로 필터링)
GET	/api/cache/stats	상세 캐시 통계(제공자별, 모델별)
GET	/api/cache/reasoning	추론 캐시 상태(추론 재생용)
DELETE	/api/cache/reasoning	추론 캐시 삭제 — 쿼리 매개변수: ?toolCallId=<id>(단일), ?provider=<p>, 또는 매개변수 없음(전체)

인증: 관리 세션이 필요합니다.

---

메모리 시스템

영구 메모리(FTS5 + 벡터 임베딩)를 관리합니다.

메서드	경로	설명
GET	/api/memory	메모리 항목 목록 조회(범위, 유형, 검색 쿼리로 필터링)
POST	/api/memory	새 메모리 항목 생성 — 본문: {scope, type, content, metadata?}
GET	/api/memory/[id]	특정 메모리 항목 조회
PUT	/api/memory/[id]	메모리 항목 업데이트
DELETE	/api/memory/[id]	메모리 항목 삭제
GET	/api/memory?q=	메모리 검색(FTS5 + 벡터) — 동일한 응답에 통계 포함

인증: 관리 세션 또는 관리 범위 API 키가 필요합니다.

---

웹훅

이벤트에 대한 웹훅 구독을 관리합니다.

메서드	경로	설명
GET	/api/webhooks	모든 웹훅 구독 목록 조회
POST	/api/webhooks	웹훅 구독 생성 — 본문: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	특정 웹훅 구독 조회
PUT	/api/webhooks/[id]	웹훅 구독 업데이트
DELETE	/api/webhooks/[id]	웹훅 구독 삭제
GET	/api/webhooks/[id]/deliveries	웹훅 전송 기록 목록 조회(성공/실패 로그)
POST	/api/webhooks/[id]/test	웹훅에 테스트 이벤트 전송

인증: 관리 세션이 필요합니다.

전체 이벤트 유형은 웹훅 프레임워크를 참조하세요.

---

Skills 프레임워크

Skills(에이전트 확장 프레임워크)를 관리합니다.

메서드	경로	설명
GET	/api/skills	설치된 모든 skill(기본 제공 + 사용자 지정) 목록 조회
POST	/api/skills/install	로컬 경로 또는 URL에서 skill 설치
DELETE	/api/skills/[id]	skill 제거
PUT	/api/skills/[id]	skill 활성화 또는 비활성화 — 본문: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	skill 실행 — 본문: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	모든 skill의 실행 기록 조회 (?apiKeyId=로 필터링)

인증: 관리 세션 또는 관리 범위 API 키가 필요합니다.

자세한 내용은 Skills 프레임워크를 참조하세요.

---

플러그인

OmniRoute 플러그인(서드 파티 확장)을 관리합니다.

메서드	경로	설명
GET	/api/plugins	설치된 플러그인 목록 조회
POST	/api/plugins/marketplace/install	마켓플레이스에서 플러그인 설치
DELETE	/api/plugins/[name]	플러그인 제거
POST	/api/plugins/[name]/activate	플러그인 활성화
POST	/api/plugins/[name]/deactivate	플러그인 비활성화
GET	/api/plugins/[name]/config	플러그인 구성 조회
PUT	/api/plugins/[name]/config	플러그인 구성 업데이트

인증: 관리 세션이 필요합니다.

자세한 내용은 플러그인 프레임워크를 참조하세요.

---

섀도 라우팅

제공자에 대한 섀도/A-B 비교는 독립적인 REST 인터페이스가 아닙니다. 이는 콤보 라우팅을 통해 구성됩니다(Auto-Combo 참조). 콤보별 비교 지표는 GET /api/combos/metrics를 통해 제공됩니다.

---

가드레일

런타임 가드레일(PII 탐지, 프롬프트 인젝션 탐지, 비전 브리징)을 점검합니다. 가드레일은 모든 요청에서 실행되며, 호출별 제외는 x-omniroute-disabled-guardrails 요청 헤더를 통해 지정합니다. 지속적으로 저장되는 활성화/비활성화 인터페이스는 없습니다.

메서드	경로	설명
GET	/api/guardrails	등록된 가드레일 및 해당 상태(이름/활성화 여부/우선순위) 목록 조회
POST	/api/guardrails/test	샘플 입력에 대해 호출 전 파이프라인을 테스트 실행 — 본문: {input, disabledGuardrails?}

인증: 관리 세션이 필요합니다.

자세한 내용은 보안 > 가드레일을 참조하세요.

---

---

인증

네 가지 자격 증명 계열(대시보드 세션, 로컬 CLI 토큰, oma_live_… Access Token, 관리 범위 API 키)과 이들이 추론 키와 어떻게 다른지는 관리 인증을 참조하세요.

• 대시보드 경로(/dashboard/*)는 auth_token 쿠키를 사용합니다
• 로그인은 저장된 비밀번호 해시를 사용하며, 없으면 INITIAL_PASSWORD를 사용합니다
• requireLogin은 /api/settings/require-login을 통해 전환할 수 있습니다
• /v1/* 경로는 REQUIRE_API_KEY=true일 때 선택적으로 Bearer API 키를 요구합니다
• 이 문서에서 "관리 토큰" / "관리 범위 API 키"는 해당 가이드에 설명된 계열 중 하나를 의미하며, 별도로 정의되지 않은 추가 비밀 유형을 의미하지 않습니다

호환성을 깨뜨리는 변경 사항(v3.8.0) — 이제 /api/v1/agents/tasks/* 및 쿨다운 관리 엔드포인트에는 관리 인증(대시보드 auth_token 쿠키 또는 관리 범위 API 키)이 필요합니다. 이전에 인증 없이 이러한 경로를 호출하던 클라이언트는 401 Unauthorized를 받게 됩니다. 커밋 588a0333(fix(auth): 에이전트 및 쿨다운 API에 관리 인증 요구)을 참조하세요.