상태, 헬스, 구성, 도구 엔드포인트

이 엔드포인트들을 사용하면 실행 중인 Revka 게이트웨이를 모니터링하고, 문제를 진단하며, HTTP를 통해 구성을 읽거나 업데이트할 수 있습니다. 로드 밸런서 헬스 체크 연동, Prometheus 메트릭 수집, 대시보드의 상태 및 구성 페이지 구동, 또는 데몬에 대한 운영 작업 스크립팅에 활용하십시오.

이 페이지의 대부분 라우트는 페어링 흐름에서 발급받은 베어러 토큰이 필요합니다. 일부 라우트는 로드 밸런서, 리버스 프록시, 메트릭 수집기가 토큰 없이 접근할 수 있도록 의도적으로 인증을 요구하지 않으며, 해당 라우트는 명시적으로 표시되어 있습니다. doctor 및 status에 해당하는 CLI 명령어는 revka doctor, status & self-test를 참조하십시오.

모든 /api/* 라우트는 요청 본문 64 KiB 제한과 구성 가능한 타임아웃(기본값 30초, 환경 변수 REVKA_GATEWAY_TIMEOUT_SECS)을 공유하며, 일부 라우트는 개별적으로 재정의할 수 있습니다.

헬스 체크

Revka는 두 계층으로 헬스를 제공합니다. GET /health는 로드 밸런서와 Docker HEALTHCHECK를 위한 공개 liveness 프로브로, 인증이 필요 없고 비밀 값을 노출하지 않으며, 컴포넌트에 오류가 있더라도 항상 200 OK를 반환합니다 — 실제 상태를 확인하려면 JSON 본문을 확인하십시오. GET /api/health는 대시보드 및 알림용의 인증된 상세 스냅샷입니다.

GET /health

GET /api/health
Authorization: Bearer <token>

GET /health는 스냅샷을 runtime 키 아래, 페어링 필드와 함께 래핑합니다.

{
  "status": "ok",
  "paired": true,
  "require_pairing": false,
  "runtime": {
    "pid": 12345,
    "updated_at": "2026-06-18T10:00:00Z",
    "uptime_seconds": 3600,
    "components": {
      "gateway": {
        "status": "ok",
        "updated_at": "2026-06-18T10:00:00Z",
        "last_ok": "2026-06-18T10:00:00Z",
        "last_error": null,
        "restart_count": 0
      }
    }
  }
}

GET /api/health는 동일한 스냅샷을 health 키 아래 래핑합니다.

{
  "health": {
    "pid": 12345,
    "updated_at": "2026-06-18T10:00:00Z",
    "uptime_seconds": 3600,
    "components": { }
  }
}

components의 각 항목은 ComponentHealth로, status는 starting, ok, error 중 하나이며, updated_at, 선택적 last_ok / last_error, 그리고 restart_count를 포함합니다. 서브시스템은 gateway, scheduler, channel:<name>, heartbeat 등의 규약된 이름으로 레지스트리에 자신을 등록합니다.

팁

로드 밸런서는 GET /health(인증 없음)에, 알림 시스템은 GET /api/health(인증 필요, 전체 상세 정보)에 연결하십시오. 스크립트에서 종료 코드로 확인할 때는 revka status도 이 스냅샷을 읽습니다.

시스템 상태

GET /api/status는 두 계층의 런타임 상태 응답을 반환합니다. 인증되지 않은 호출자는 liveness 뷰(업타임, 헬스, 페어링 상태)를 받고, 인증된 호출자는 추가로 활성 공급자, 모델, 메모리 백엔드, 채널 목록을 받습니다. 베어러 토큰은 선택 사항이지만 제공하면 더 풍부한 응답을 받을 수 있습니다.

GET /api/status
Authorization: Bearer <token>

인증된 응답:

{
  "provider": "openrouter",
  "model": "anthropic/claude-sonnet-4",
  "temperature": 0.7,
  "uptime_seconds": 3600,
  "gateway_port": 8080,
  "memory_backend": "kumiho",
  "paired": true,
  "channels": { },
  "health": { }
}

인증되지 않은 형태는 리버스 프록시 뒤에서 간단한 liveness 체크로 사용하고, 인증된 형태는 대시보드의 상태 뷰를 채우는 데 사용하십시오.

Doctor — 진단

GET /api/doctor(또는 폼 호환성을 위해 POST /api/doctor)는 revka doctor CLI와 동일한 진단 스위트를 실행하고, 검사별 심각도와 요약 집계를 포함하는 구조화된 보고서를 반환합니다.

GET /api/doctor
Authorization: Bearer <token>

{
  "results": [
    { "severity": "ok", "category": "config", "message": "Provider 'openrouter' is valid" }
  ],
  "summary": { "ok": 12, "warnings": 2, "errors": 0 }
}

각 결과는 severity(ok, warn, error), category, 사람이 읽을 수 있는 message를 가진 DiagResult입니다. 진단 카테고리는 구성 유효성(공급자, API 키, 기본 모델, 온도 범위, 게이트웨이 포트, 라우트, 채널), 워크스페이스 무결성, 데몬 최신성, 환경 도구, 사이드카, Kumiho 백엔드를 포함합니다.

전체 시점 검증(구성 의미론, 데몬 최신성, 사이드카 확인)이 필요할 때는 /api/doctor를 실행하고, 라이브 컴포넌트 헬스 스냅샷만 필요할 때는 GET /api/health를 사용하십시오. 전체 카테고리 참조 및 오래됨 임계값 상세 정보는 revka doctor, status & self-test를 참조하십시오.

CLI 도구 검색

GET /api/cli-tools는 표준 PATH 항목을 스캔하여 호스트에서 검색된 CLI 도구를 반환합니다. 대시보드의 도구 페이지는 이를 사용하여 도구 호출에 사용 가능한 도구를 표시합니다. 결과는 호스트 OS에 따라 다르며, 별도 구성은 필요하지 않습니다.

GET /api/cli-tools
Authorization: Bearer <token>

Prometheus 메트릭

GET /metrics는 Prometheus 텍스트 형식의 메트릭을 제공합니다. 이 엔드포인트는 항상 존재하지만, 구성에서 [observability] backend = "prometheus"가 설정되고 바이너리가 observability-prometheus Cargo 피처로 빌드된 경우에만 실제 메트릭을 출력합니다. 그렇지 않으면 메트릭 대신 사람이 읽을 수 있는 힌트 주석을 반환합니다.

GET /metrics

응답은 Content-Type: text/plain; version=0.0.4; charset=utf-8을 사용합니다. 인증이 필요하지 않습니다. 대표적인 메트릭은 다음과 같습니다.

메트릭	타입	레이블
revka_agent_starts_total	counter	provider, model
revka_llm_requests_total	counter	provider, model, success
revka_tokens_input_total / revka_tokens_output_total	counter	provider, model
revka_agent_duration_seconds	histogram	provider, model
revka_tool_calls_total	counter	tool, success
revka_tool_duration_seconds	histogram	tool
revka_channel_messages_total	counter	channel, direction
revka_errors_total	counter	component
revka_cache_hits_total / revka_cache_misses_total	counter	cache_type
revka_active_sessions / revka_queue_depth	gauge	—

DORA 4가지 핵심 메트릭(revka_deployments_total, revka_deployment_lead_time_seconds, revka_deployment_failure_rate, revka_recovery_time_seconds, revka_mttr_seconds)과 수동 실행 메트릭도 내보냅니다. 전체 메트릭 목록은 관찰 가능성 및 트레이싱에서 확인하십시오.

주의

/metrics는 Prometheus 서버가 스크랩할 수 있도록 의도적으로 인증을 요구하지 않습니다. 인터넷에 직접 노출하지 마십시오 — 리버스 프록시 ACL 뒤에 배치하거나 네트워크 계층에서 제한하십시오.

Admin — 종료 및 페어링 코드

admin 인터페이스는 루프백 인터페이스에 바인딩되어 있습니다. 베어러 토큰을 허용하지 않으며 원격 호출자에게는 403을 반환합니다. 이 라우트들은 revka stop 및 revka gateway get-paircode 명령어를 지원합니다.

POST /admin/shutdown          # 정상 종료 (localhost 전용)
GET  /admin/paircode          # 현재 페어링 코드 반환
POST /admin/paircode/new      # 새 페어링 코드 생성

POST /admin/shutdown은 데몬에 정상 종료 신호를 보내며 revka stop이 호출하는 라우트입니다. GET /admin/paircode는 현재 유효한 페어링 코드를 반환하고, POST /admin/paircode/new는 코드를 교체하며 revka gateway get-paircode의 --new 플래그로 호출됩니다. 디바이스 측 페어링 엔드포인트 및 베어러 토큰 교환은 페어링 & 인증을 참조하십시오.

구성 — 읽기 및 업데이트

GET /api/config는 현재 config.toml을 문자열로 반환하고, PUT /api/config는 이를 교체합니다. 두 엔드포인트 모두 베어러 토큰이 필요합니다.

GET /api/config
Authorization: Bearer <token>

{ "format": "toml", "content": "<toml string with secrets masked>" }

비밀 값 마스킹

GET 응답에서 민감한 필드(API 키, 토큰, 비밀번호)는 ***MASKED***로 반환됩니다. 대시보드를 통해 구성을 편집하는 운영자는 평문 자격 증명을 볼 수 없습니다. PUT 시, 마스킹된 값이 그대로 포함된 필드는 조용히 라이브 구성의 값으로 복원되므로, 마스킹된 값을 제출해도 자격 증명이 실수로 삭제되지 않습니다. 비밀 값을 변경하려면 마스킹된 자리 표시자를 새 평문 값으로 교체하고, 유지하려면 자리 표시자를 그대로 두십시오.

PUT /api/config
Authorization: Bearer <token>
Content-Type: text/plain

PUT 본문은 전체 TOML 구성 문자열입니다. 이 라우트는 본문 제한을 기본값 64 KiB보다 큰 1 MB로 높입니다. 업데이트가 성공하면 다음으로 응답합니다.

{ "status": "ok", "mcp_registry": { }, "restart": "scheduled" }

mcp_registry는 구성 변경 후 MCP 재연결 상태를 보고하므로, 호출자는 어떤 서버가 복구되었는지 확인할 수 있습니다.

감독 재시작 동작

Revka가 감독자(launchd 또는 systemd) 하에서 실행 중일 때, 성공적인 PUT /api/config는 재시작을 예약합니다 — 데몬이 SIGTERM을 수신하고 감독자가 재시작하여 새 구성이 완전히 적용됩니다. 이것이 응답에 "restart": "scheduled"가 포함되는 이유입니다. 감독되지 않는 프로세스에서는 재시작할 감독자가 없으므로, 구성 편집 후 수동으로 재시작하십시오. 감독자 설정은 백그라운드 서비스로 실행을 참조하십시오.

주의

구성 저장이 성공하면 데몬이 재시작되므로, 진행 중인 PUT은 현재 프로세스가 처리하는 마지막 요청이 됩니다. 연결이 끊어지기 전에 응답을 저장하십시오.

도구 목록

GET /api/tools는 등록된 도구 명세 — 내장 도구 및 MCP 연결 도구의 이름, 설명, 파라미터 JSON 스키마 — 를 반환합니다.

GET /api/tools
Authorization: Bearer <token>

{
  "tools": [
    { "name": "shell", "description": "Run a shell command", "parameters": { } }
  ]
}

이를 통해 운영자는 에이전트가 호출할 수 있는 도구를 확인할 수 있습니다. MCP 도구는 MCP 레지스트리가 성공적으로 초기화된 후에만 표시됩니다. 지연 로딩 모델에 주의하십시오. operator 및 Kumiho 도구는 즉시 로드되지만, 나머지는 도구 검색 메커니즘을 통해 필요 시 로드됩니다. 등록된 도구 명세가 아닌 호스트에서 검색된 커맨드라인 바이너리는 위의 CLI 도구 검색을 사용하십시오. 전체 내장 도구 목록은 도구 개요를 참조하십시오.

인테그레이션

GET /api/integrations는 등록된 모든 인테그레이션 — 채널, 공급자, 외부 서비스 — 을 현재 상태와 함께 나열합니다. GET /api/integrations/settings는 더 단순한 설정 맵을 반환합니다.

GET /api/integrations           # { "integrations": [...] }
GET /api/integrations/settings  # { "settings": { name: { enabled, category, status } } }

인테그레이션은 인테그레이션 레지스트리에서 정적으로 등록됩니다. 각 상태는 다음 중 하나입니다.

상태	의미
Active	구성되어 실행 중
Available	완전히 구현되어 사용 가능하지만 아직 구성되지 않음
ComingSoon	계획 중이며 아직 구현되지 않음

직렬화된 JSON 값은 정확한 변형 이름입니다(예: "Available", "ComingSoon").

대시보드의 상태 배지는 이 값에 직접 매핑됩니다. 대시보드 뷰는 스킬, 도구 & 인테그레이션 페이지를 참조하십시오.

엔드포인트 요약

메서드 & 경로	인증	목적
GET /health	없음	공개 liveness 스냅샷
GET /api/health	bearer	전체 컴포넌트 헬스 스냅샷
GET /api/status	bearer 선택	런타임 상태 (인증 시 더 풍부한 정보)
GET / POST /api/doctor	bearer	진단 보고서
GET /api/cli-tools	bearer	PATH에서 검색된 호스트 CLI 도구
GET /metrics	없음	Prometheus 메트릭 (활성화 시)
POST /admin/shutdown	localhost 전용	정상 종료
GET /admin/paircode	localhost 전용	현재 페어링 코드
POST /admin/paircode/new	localhost 전용	페어링 코드 교체
GET /api/config	bearer	구성 읽기 (비밀 값 마스킹)
PUT /api/config	bearer	구성 교체 (마스킹된 필드 보존)
GET /api/tools	bearer	등록된 도구 명세
GET /api/integrations	bearer	상태 포함 인테그레이션 목록
GET /api/integrations/settings	bearer	단순 인테그레이션 설정 맵

관련 페이지

• 게이트웨이 API 개요 — 전송 방식, 인증 모델, 라우트 규약
• 페어링 & 인증 — 베어러 토큰 발급 및 디바이스 관리
• revka doctor, status & self-test — doctor 및 status의 CLI 측면
• 관찰 가능성 및 트레이싱 — 메트릭 백엔드 및 전체 Prometheus 참조
• 비용, 감사, ClawHub & 자격 증명 API — 비용 요약 및 감사 로그 엔드포인트