Admin REST API¶

Continuum Router는 바이너리가 admin 기능으로 빌드된 경우 /admin 아래에 관리 API를 마운트합니다. 기본 기능 세트에는 admin이 포함됩니다.

Admin API는 신뢰할 수 있는 관리 네트워크용입니다. 인증은 기본적으로 활성화되지 않습니다. localhost 밖에 노출하기 전에 admin.auth를 설정하세요.

인증¶

Bearer 토큰¶

admin:
  auth:
    method: bearer
    bearer_token: "${ADMIN_TOKEN}"
    allowed_ips: []

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://127.0.0.1:8080/admin/health

bearer_token은 16자 이상이어야 합니다. allowed_ips는 선택 사항이며 개별 IPv4/IPv6 주소와 CIDR 범위를 받습니다.

HTTP Basic¶

admin:
  auth:
    method: basic
    basic_auth:
      username: admin
      password: "${ADMIN_PASSWORD}"

curl -u "admin:$ADMIN_PASSWORD" http://127.0.0.1:8080/admin/health

IP 허용 목록¶

admin:
  auth:
    method: ip_whitelist
    allowed_ips:
      - 127.0.0.1
      - 10.0.0.0/8

allowed_ips는 method: bearer 또는 method: basic과 함께 사용할 수도 있습니다. Unix 소켓 연결에는 피어 IP가 없으므로 IP 검사를 건너뜁니다.

API 키¶

admin:
  auth:
    method: api_key
    required_scope: admin
    allowed_ips: []

# Authorization: Bearer와 X-API-Key를 모두 허용합니다
curl -H "Authorization: Bearer $ADMIN_API_KEY" http://127.0.0.1:8080/admin/health
curl -H "X-API-Key: $ADMIN_API_KEY" http://127.0.0.1:8080/admin/health

method: api_key는 제시된 키를 일반 /v1 인증과 Admin 키 관리(/admin/api-keys)가 사용하는 것과 동일한 API 키 저장소로 검증합니다. 키는 활성 상태이고 만료되지 않았으며 required_scope(기본값 admin)를 가져야 합니다. 저장소를 공유하므로 키를 비활성화, 회전, 만료, 삭제하면 재시작 없이 즉시 Admin API 인증에서도 차단됩니다. 키가 없거나 잘못되면 401, 필요한 스코프가 없는 유효한 키나 화이트리스트에 없는 IP의 요청은 403을 반환합니다. 계층적 보안을 위해 allowed_ips를 method: api_key와 함께 사용할 수 있습니다.

Admin 인증 설정은 Admin 라우터를 구성할 때 캡처됩니다. admin.auth 자체(예: method나 required_scope 변경)를 바꾼 뒤에는 라우터를 재시작하세요. 개별 키 변경은 공유 저장소를 통해 즉시 반영됩니다.

감사 로그¶

admin:
  audit:
    enabled: true
    log_level: info
    include_headers: false
    include_body: false
    excluded_headers:
      - authorization
      - x-api-key
      - cookie

감사 로그는 기본적으로 활성화됩니다. 요청에 비밀 값이나 사용자 데이터가 포함될 수 있다면 본문 로깅을 사용하지 마세요.

엔드포인트 목록¶

아래 경로는 모두 라우터 원점을 기준으로 합니다.

기능 및 상태¶

백엔드 관리¶

백엔드 변경은 설정 업데이트 채널로 새 설정 스냅샷을 발행합니다. 모든 필드가 즉시 적용되는 것은 아닙니다. /admin/config/hot-reload-status를 확인하고 requires_restart 섹션은 재시작하세요.

POST /admin/backends/{name}/models/discover는 읽기 전용입니다. 설정된 백엔드 하나를 정확한 이름으로 찾고, 일반 집계가 쓰는 것과 같은 백엔드별 모델 fetcher를 재사용하며, 설정의 backends[].models 허용 목록을 적용하기 전의 실시간 카탈로그를 반환합니다. 관리 UI가 사용 가능한 모델 선택지를 채워야 하지만 라우팅에 쓰는 선택 모델 목록은 그대로 유지해야 할 때 사용하세요.

curl -X POST http://127.0.0.1:8080/admin/backends/provider-openai/models/discover \
  -H "Authorization: Bearer $ADMIN_TOKEN"

{
  "backend": "provider-openai",
  "object": "list",
  "data": [
    {
      "id": "gpt-5.5",
      "object": "model",
      "created": 1760000000,
      "owned_by": "openai"
    }
  ]
}

검색 응답은 설정을 쓰거나, 집계 모델 캐시를 무효화하거나, 백엔드 헬스와 서킷 브레이커 상태를 바꾸지 않습니다. Codex OAuth 백엔드는 일반 Codex 검색 경로와 동일하게 로드된 OAuth 전략, 토큰 갱신, chatgpt-account-id 처리, 계정 플랜 필터를 사용합니다. Codex가 아닌 OAuth 백엔드, 네이티브 Anthropic, Bedrock은 라우터가 조회할 공급자 네이티브 카탈로그가 없으므로 501과 error.code: "model_discovery_unsupported"를 반환합니다. 알 수 없는 백엔드 이름은 404와 error.code: "backend_not_found"를 반환합니다. 업스트림 실패는 backend_authentication_failed, backend_discovery_timeout, backend_discovery_network_error, backend_discovery_parse_error, backend_discovery_http_error, backend_discovery_response_too_large 중 하나로 구분됩니다. 응답 본문에는 액세스 토큰, 리프레시 토큰, 토큰 저장소 경로, 원본 인증 헤더가 들어가지 않습니다.

POST /admin/backends/probe는 백엔드 생성과 같은 후보 필드와 operations: ["health", "models"]를 받습니다. TCP와 Unix 소켓을 포함한 모든 Admin 전송에서 Admin 인증을 거치며, GET /admin/capabilities는 이 기능을 transient_backend_probe_v1로 광고합니다. 후보는 메모리에서만 검증되고 활성 설정, 설정 기록, 백엔드 풀, 헬스 상태, 서킷 브레이커, 집계 캐시, 환경 파일, 토큰 저장소에 추가되지 않습니다.

응답은 health와 catalog를 분리합니다. health.credential_status는 valid, invalid, unknown, not_required 중 하나입니다. 자격 증명이 전달되었더라도 인증이 필요 없는 헬스 엔드포인트가 정상이라고 해서 자격 증명을 증명하지 않으므로 unknown을 반환합니다. 임시 OAuth 후보는 수명 주기로 관리되는 인증 전략 없이 정상 상태를 만들어 내지 않고 health.status: "unknown"과 backend_probe_health_unsupported를 반환합니다. catalog.source는 live, curated, configured, unsupported 중 하나입니다. OpenAI 호환, Gemini, Ollama, vLLM, llama.cpp, MLX, LM Studio처럼 모델 목록 API가 있는 후보는 등록된 백엔드 검색과 같은 URL 구성, 인증 헤더, 응답 크기 제한, 파싱, 정규화, 모델 개수 제한을 사용합니다. Anthropic은 라우터 내장 카탈로그나 명시적인 models/model_configs를 반환할 수 있습니다. Bedrock과 OAuth 후보도 개수 제한이 적용된 이 설정 항목을 반환할 수 있으며, 항목이 없으면 타입이 지정된 unsupported 카탈로그를 반환합니다.

서킷 브레이커 상태¶

이 엔드포인트는 일반 LLM 프록시 요청이 구동하고 조회하는 것과 동일한 서킷 브레이커 상태 머신을 제어하므로, 일반 프록시 라우팅이 사용하는 상태를 보고하고 조정합니다(예: open은 백엔드가 회복될 때까지 선택에서 제외합니다).

설정 조회¶

GET /admin/config/full은 다음 봉투 구조를 반환합니다.

{
  "config": {},
  "hot_reload": {
    "enabled": true,
    "capabilities": {}
  },
  "metadata": {
    "retrieved_at": "2026-07-19T00:00:00Z",
    "version": 1
  }
}

설정하지 않은 섹션은 config에 명시적 null 값으로 남지 않고 아예 빠집니다. 개별 섹션 조회는 이 변경과 무관하게 그대로 동작합니다. GET /admin/config/{section}으로 아직 설정하지 않은 유효한 섹션(예: metrics, fallback)을 조회해도 여전히 404가 아니라 200과 "config": null을 반환합니다.

섹션 API가 받는 이름은 다음과 같습니다.

• server
• backends
• health_checks
• logging
• retry
• timeouts
• rate_limiting
• circuit_breaker
• global_prompts
• request_params
• admin
• fallback
• model_aliases
• files
• api_keys
• metrics
• routing

이는 관리용 부분집합이며 주 설정 스키마가 받는 모든 최상위 필드 목록이 아닙니다.

설정 검증 및 변경¶

PUT과 PATCH의 JSON 본문은 { "config": ... } 래퍼가 아니라 섹션 값 자체입니다.

curl -X PATCH http://127.0.0.1:8080/admin/config/rate_limiting \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true}'

성공한 섹션 변경 응답에는 version, requires_restart, hot_reload_capability가 포함됩니다. API는 메모리 내 스냅샷을 발행하며 원본 YAML/TOML 파일에는 쓰지 않습니다.

검증 본문:

{
  "content": "server:\n  bind_address: 127.0.0.1:8080\nbackends: []\n",
  "format": "yaml",
  "sections": []
}

sections가 비어 있으면 content는 완전한 설정이어야 합니다. 섹션 단위 검증에서는 content에 해당 최상위 섹션을 넣고 sections에도 그 이름을 나열합니다.

내보내기 본문:

{
  "format": "yaml",
  "include_sensitive": false,
  "sections": []
}

format은 yaml, json, toml 중 하나입니다. sections가 비어 있으면 전체 설정을 내보냅니다. include_sensitive: true는 평문 비밀 값을 반환하며 보안 감사 로그를 남깁니다.

format: "toml"은 이제 섹션 여러 개를 설정하지 않아도 성공합니다. 그런 섹션은 직렬화된 설정에서 null로 남지 않고 아예 빠지는데 TOML은 애초에 null 값을 표현하지 못합니다. 예전에는 설정하지 않은 섹션이 하나라도 있으면 TOML 내보내기가 전부 500 SERIALIZATION_ERROR로 실패했습니다.

가져오기 본문:

{
  "content": "server:\n  bind_address: 127.0.0.1:8080\nbackends: []\n",
  "format": "yaml",
  "apply": false,
  "dry_run": true
}

가져오기 본문은 1 MiB, 구조 중첩 깊이는 32로 제한됩니다. dry_run: true는 검증만 합니다. apply: true는 전체 후보 설정을 설정 업데이트 채널로 발행하고 기록 버전을 생성합니다. 재시작 전용 섹션은 여전히 재시작이 필요합니다.

내보내기에서 가져오기로 돌아올 때의 마스킹된 비밀 값¶

Admin API가 반환하는 마스킹 값은 어떤 엔드포인트든 똑같이 고정된 센티널 ***CONTINUUM-MASKED:<힌트>***로 감쌉니다. 힌트는 길이만 드러냅니다. 4자를 넘는 값은 앞 두 글자와 길이를 함께 보여주고(sk...(21 chars)), 4자 이하 값은 길이만 보여주며((4 chars)), 불리언이나 숫자를 마스킹하면 ***CONTINUUM-MASKED:hidden***으로 나옵니다. 예전 라우터 빌드는 4자 이하 값이면 길이조차 밝히지 않고 그대로 ***MASKED***만 돌려줬는데, 이번 변경으로 짧은 비밀 값도 길이는 드러나지만 내용은 여전히 드러나지 않습니다. 이 마스킹 규칙은 GET /admin/config/full, GET /admin/config/{section}, GET /admin/backends, GET /admin/config/history 스냅샷에도 똑같이 적용되며 내보내기에서만 쓰는 형식이 아닙니다.

include_sensitive: true를 넘기지 않으면 내보내기는 모든 자격 증명을 마스킹합니다. 따라서 편집해서 되돌려 보내는 문서에는 실제 비밀 값 대신 이 자리표시자가 들어 있습니다. 가져오기는 자리표시자를 "지금 적용된 값을 그대로 둔다"는 뜻으로 읽어 실행 중인 비밀 값을 다시 채워 넣고, 그대로 둔 경로를 모두 응답에 적습니다.

{
  "success": true,
  "applied": true,
  "version": 4,
  "preserved_secret_paths": ["backends[0].api_key", "admin.auth.bearer_token"],
  "validation": {
    "valid": true,
    "warnings": [
      {
        "section": "backends",
        "path": "backends[0].api_key",
        "message": "'backends[0].api_key' carried a masked placeholder, so the value currently in effect was kept. The submitted document did not change this secret.",
        "code": "MASKED_SECRET_PRESERVED"
      }
    ]
  }
}

POST /admin/config/validate도 같은 MASKED_SECRET_PRESERVED 경고를 내보냅니다. WebUI의 저장 전 예행 검증이 커밋 전에 어떤 값이 그대로 남는지 보여 준다는 뜻입니다.

설정 문서를 기록하는 모든 엔드포인트가 같은 복원 과정을 거치므로, 예행 검증이 약속한 결과가 실제 저장 결과와 같습니다. POST /admin/config/import, config 후보를 담은 POST /admin/config/apply, PUT/PATCH /admin/config/{section}이 여기에 해당합니다. 섹션 기록에서 자리표시자를 복원하지 못하면 success: false와 함께 실패한 경로를 path/code에 담아 거부합니다.

자리표시자는 실행 중인 설정에 그 값을 만들어 낸 원본이 아직 있을 때만 복원됩니다. 배열 항목은 위치가 아니라 id나 name으로 대응시키므로 backends 순서를 바꿔도 제대로 복원되지만, 이름을 바꾸면 복원되지 않습니다. guardrails.bypass_api_keys나 rate_limiting.bypass_keys처럼 문자열만 담는 목록은 id도 name도 없어 위치가 유일한 단서입니다. 그래서 항목을 하나 넣거나 빼면 추측하지 않고 거부합니다. 같은 공급자가 발급한 키는 접두사와 길이가 같아서, 한 칸 밀린 위치가 옆 키로 그대로 대응해 버리기 때문입니다. 이런 목록은 include_sensitive: true로 내보낸 문서에서 편집하거나 실제 값을 직접 넣으세요. 대응할 값을 찾지 못하면 옆에 있던 비밀 값을 엉뚱한 필드에 붙이는 대신 가져오기 전체를 거부하고 실패한 경로를 그대로 알려 줍니다.

이미 실행 중인 값과 같은 값은 생김새와 무관하게 그대로 둡니다. 예전 빌드에서 자격 증명이 손상되어 실행 중인 값 자체가 옛 자리표시자 형태인 설정도, 모든 비밀 값을 다시 입력하지 않고 섹션 단위로 계속 편집할 수 있습니다.

자리표시자가 아닌 값은 그대로 반영되므로 자격 증명 교체도 평소대로 됩니다. 자리표시자를 새 비밀 값으로 바꿔 가져오면 됩니다. 환경 변수 참조는 참조인 채로 왕복합니다. ${OPENAI_API_KEY}는 ***CONTINUUM-MASKED:${OPENAI_API_KEY}***로 내보내지고 ${OPENAI_API_KEY}로 복원되며, 해석된 값으로 바뀌지 않습니다.

적용 본문:

{
  "hot_reload": true,
  "description": "선택적 감사 메모",
  "config": { "...": "전체 설정 객체" }
}

POST /admin/config/apply는 전체 config 후보를 전달할 때만 실제로 동작합니다. 섹션 편집(PUT/PATCH), import, rollback은 이미 즉시 발행하므로:

• config 없음(또는 null): 명시적 no-op. 아무것도 발행하지 않고 기록 버전도 생성하지 않으며, 응답은 hot_reload_triggered: false와 빈 updated_sections를 반환합니다. 반복 호출해도 빈 기록 버전을 만들지 않습니다.
• config 있음, hot_reload: true: 후보를 검증하고 실행 중인 설정과 비교(diff)한 뒤, 차이가 있으면 설정 업데이트 채널로 원자적으로 발행합니다. 변경된 섹션으로 정확히 하나의 기록 버전을 생성합니다. hot_reload_triggered는 발행이 성공한 뒤에만 true이고, updated_sections와 requires_restart는 실제 diff를 반영합니다.
• config 있음, hot_reload: false: 미리보기 전용. 응답은 updated_sections/requires_restart diff를 반환하지만 아무것도 발행하지 않고 기록 버전도 생성하지 않습니다.

실행 중인 설정과 동일한 후보는 no-op으로 처리됩니다.

API 키¶

API 키 값은 생성 또는 회전 시에만 반환됩니다. 즉시 안전한 곳에 저장하세요.

프롬프트 및 통계¶

라우팅, 캐시, 가드레일 제어¶

파일, ACP, 컨트롤 플레인¶

상태 코드¶

• 200: 요청이 처리됨. 변경 응답 본문에 "success": false가 있을 수 있으므로 본문도 확인합니다.
• 400: 잘못된 요청 또는 HTTP 오류를 사용하는 처리기의 유효하지 않은 입력.
• 401: Bearer/Basic 자격 증명 누락 또는 불일치.
• 403: 허용되지 않은 IP 또는 권한 부족.
• 404: 없는 리소스, 런타임 기능 비활성, 또는 컴파일 기능이 없어 경로가 없음.
• 413: 업로드가 경로 본문 제한을 초과함.
• 500: 내부 실패 또는 인증 방식에 필요한 런타임 상태가 없음.