Status, health, config & tools endpoints

These endpoints let you monitor a running Revka gateway, diagnose problems, and read or update its configuration over HTTP. Use them to wire up load-balancer health checks, scrape metrics into Prometheus, drive the dashboard’s status and config pages, or script operational tasks against the daemon.

Most routes on this page require a bearer token from the pairing flow. A few are intentionally unauthenticated so that load balancers, reverse proxies, and metrics scrapers can reach them without a token — those are called out explicitly. For the CLI equivalents of doctor and status, see revka doctor, status & self-test.

All /api/* routes share a 64 KiB request body cap and a configurable timeout (default 30 s, env REVKA_GATEWAY_TIMEOUT_SECS), with per-route overrides where noted.

Health check

Revka exposes health on two tiers. GET /health is the public liveness probe for load balancers and Docker HEALTHCHECK; it requires no auth, leaks no secrets, and always returns 200 OK even when components report errors — inspect the JSON body to read the real status. GET /api/health is the authenticated, richer snapshot for dashboards and alerting.

GET /health

GET /api/health
Authorization: Bearer <token>

GET /health wraps the snapshot under a runtime key alongside pairing fields:

{
  "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 wraps the same snapshot under a health key:

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

Each entry in components is a ComponentHealth with a status of starting, ok, or error, plus updated_at, optional last_ok / last_error, and a restart_count. Subsystems stamp themselves into the registry under conventional names such as gateway, scheduler, channel:<name>, and heartbeat.

Tip

Point your load balancer at GET /health (no auth) and your alerting at GET /api/health (auth, full detail). For scripted exit-code checks, revka status also reads this snapshot.

System status

GET /api/status returns runtime status with a two-tier response. Unauthenticated callers get a liveness view (uptime, health, pairing state); authenticated callers additionally get the active provider, model, memory backend, and channel list. The bearer token is optional but produces the richer response.

GET /api/status
Authorization: Bearer <token>

Authenticated response:

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

Use the unauthenticated form as a lightweight liveness check behind a reverse proxy, and the authenticated form to populate the dashboard’s status view.

Doctor — diagnostics

GET /api/doctor (or POST /api/doctor, supported for form compatibility) runs the same diagnostics suite as the revka doctor CLI and returns a structured report with per-check severity and a summary count.

GET /api/doctor
Authorization: Bearer <token>

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

Each result is a DiagResult with severity (ok, warn, or error), a category, and a human-readable message. The diagnostic categories cover config validity (provider, API keys, default model, temperature range, gateway port, routes, channels), workspace integrity, daemon freshness, environment tools, sidecars, and the Kumiho backend.

Run /api/doctor for a full point-in-time validation pass (config semantics, daemon freshness, sidecar checks); run GET /api/health when you only need the live component health snapshot. See revka doctor, status & self-test for the full category reference and stale-threshold details.

CLI tools discovery

GET /api/cli-tools returns the CLI tools discovered on the host by scanning the standard PATH entries. The dashboard’s Tools page uses this to show what is available for tool calls. Results vary by host OS; no configuration is needed.

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

Prometheus metrics

GET /metrics exposes Prometheus text-format metrics. The endpoint is always present but only emits real metrics when [observability] backend = "prometheus" is set in config and the binary was built with the observability-prometheus Cargo feature. Otherwise it returns a human-readable hint comment instead of metrics.

GET /metrics

The response uses Content-Type: text/plain; version=0.0.4; charset=utf-8. No auth is required. Representative metrics include:

Metric	Type	Labels
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 four-keys metrics (revka_deployments_total, revka_deployment_lead_time_seconds, revka_deployment_failure_rate, revka_recovery_time_seconds, revka_mttr_seconds) and hand-run metrics are also exported. The full metric set is documented in Observability & tracing.

Caution

/metrics is unauthenticated by design so a Prometheus server can scrape it. Do not expose it directly to the internet — put it behind a reverse-proxy ACL or restrict it at the network layer.

Admin — shutdown and pairing code

The admin surface is bound to the loopback interface: it accepts no bearer token and rejects remote callers with 403. These routes back the revka stop and revka gateway get-paircode commands.

POST /admin/shutdown          # graceful shutdown (localhost only)
GET  /admin/paircode          # return current pairing code
POST /admin/paircode/new      # generate a fresh pairing code

POST /admin/shutdown sends the daemon a graceful shutdown signal and is what revka stop calls. GET /admin/paircode returns the current outstanding pairing code; POST /admin/paircode/new rotates it and is invoked by the --new flag on revka gateway get-paircode. For the device-facing pairing endpoints and bearer-token exchange, see Pairing & authentication.

Config — get and update

GET /api/config returns the current config.toml as a string; PUT /api/config replaces it. Both require a bearer token.

GET /api/config
Authorization: Bearer <token>

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

Masked secrets

In GET responses, sensitive fields (API keys, tokens, passwords) are returned as ***MASKED***. Operators editing config through the dashboard never see plaintext credentials. On PUT, any field still carrying the masked value is silently restored from the live config, so submitting a masked value cannot accidentally clear a credential. To change a secret, replace the masked placeholder with the new plaintext value; to keep it, leave the placeholder untouched.

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

The PUT body is the full TOML config string. This route raises the body limit to 1 MB (larger than the default 64 KiB). A successful update responds with:

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

mcp_registry reports the MCP reconnect status after the config change, so callers can observe which servers came back up.

Supervised restart behavior

When Revka runs under a supervisor (launchd or systemd), a successful PUT /api/config schedules a restart — the daemon receives a SIGTERM and the supervisor revives it — so the new config is fully applied; this is why the response carries "restart": "scheduled". On an unmanaged process there is no supervisor to revive the daemon, so restart it manually after editing config. See Run as a background service for supervisor setup.

Caution

Because the daemon restarts on a successful config save, an in-flight PUT is the last request the current process serves. Persist the response before the connection drops.

Tools list

GET /api/tools returns the registered tool specifications — name, description, and JSON schema for parameters — for both built-in tools and any MCP-connected tools.

GET /api/tools
Authorization: Bearer <token>

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

This is how operators verify which tools agents can call. MCP tools appear only after the MCP registry has been successfully initialized. Note the deferred loading model: operator and Kumiho tools load eagerly, while others are loaded on demand via the tool-search mechanism. For host-discovered command-line binaries (as opposed to registered tool specs), use CLI tools discovery above. To browse the full built-in toolset, see Tools overview.

Integrations

GET /api/integrations lists all registered integrations — channels, providers, and external services — each with a current status. GET /api/integrations/settings returns a flatter settings map.

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

Integrations are registered statically from the integration registry. The status of each is one of:

Status	Meaning
Active	Configured and running
Available	Fully implemented and ready to use, but not yet configured
ComingSoon	Planned; not yet implemented

The serialized JSON value is the exact variant name (e.g. "Available", "ComingSoon").

The dashboard’s status badges map directly to these values. For the dashboard view, see Skills, tools & integrations pages.

Endpoint summary

Method & path	Auth	Purpose
GET /health	none	Public liveness snapshot
GET /api/health	bearer	Full component health snapshot
GET /api/status	optional bearer	Runtime status (richer when authed)
GET / POST /api/doctor	bearer	Diagnostics report
GET /api/cli-tools	bearer	Host CLI tools discovered on PATH
GET /metrics	none	Prometheus metrics (when enabled)
POST /admin/shutdown	localhost only	Graceful shutdown
GET /admin/paircode	localhost only	Current pairing code
POST /admin/paircode/new	localhost only	Rotate pairing code
GET /api/config	bearer	Read config (secrets masked)
PUT /api/config	bearer	Replace config (masked fields preserved)
GET /api/tools	bearer	Registered tool specs
GET /api/integrations	bearer	Integrations with status
GET /api/integrations/settings	bearer	Flat integration settings map

Related pages

• Gateway API overview — transports, auth model, and route conventions
• Pairing & authentication — get a bearer token and manage devices
• revka doctor, status & self-test — the CLI side of doctor and status
• Observability & tracing — metrics backends and the full Prometheus reference
• Cost, audit, ClawHub & credentials API — cost summary and audit log endpoints