Management API: server info, providers, and config endpoints

MonoRelay exposes a management API at /api/ for programmatic administration — the same API the dashboard frontend uses internally. These endpoints let you inspect server status, manage provider configuration, test connectivity, control the response cache, and track per-client usage without touching the config file directly.

Authentication

Most /api/ endpoints require a valid JWT token issued after login. Pass the token as a Bearer header:

Authorization: Bearer <jwt>

Endpoints marked public do not require a token and are accessible immediately after server start.

Server information

GET /api/info

Returns the server’s network addresses, connection info, and live system resource metrics. This endpoint is public and requires no authentication.

curl http://localhost:8787/api/info

local_ip

string

The server’s detected public or local IP address.

host

string

The bind host from server configuration.

port

integer

The port the server is listening on (default 8787).

base_url

string

The constructed OpenAI-compatible base URL clients should point to, e.g. http://1.2.3.4:8787/v1.

access_key_enabled

boolean

Whether static access-key authentication is enabled in addition to JWT.

system

object

Live resource snapshot:

cpu_percent — CPU utilization (0–100)
memory_total / memory_used / memory_percent — RAM in bytes and percent
disk_total / disk_used / disk_percent — disk in bytes and percent

Example response:

{
  "local_ip": "1.2.3.4",
  "host": "0.0.0.0",
  "port": 8787,
  "base_url": "http://1.2.3.4:8787/v1",
  "access_key_enabled": true,
  "system": {
    "cpu_percent": 4.2,
    "memory_total": 8589934592,
    "memory_used": 2147483648,
    "memory_percent": 25.0,
    "disk_total": 107374182400,
    "disk_used": 32212254720,
    "disk_percent": 30.0
  }
}

GET /health

Lightweight health check. Returns 200 OK with provider status when the server is running. Public endpoint.

status

string

Always "ok" when the server is healthy.

providers

object

One entry per configured provider:

enabled — whether the provider is active
keys — number of configured API keys
base_url — the upstream endpoint

{
  "status": "ok",
  "providers": {
    "openrouter": {
      "enabled": true,
      "keys": 3,
      "base_url": "https://openrouter.ai/api"
    },
    "anthropic": {
      "enabled": true,
      "keys": 1,
      "base_url": "https://api.anthropic.com"
    }
  }
}

Providers

GET /api/providers

List all configured providers with their current status, key inventory, and routing settings. This endpoint is public. Query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`page_size`	integer	`20`	Items per page

success

boolean

true on a successful response.

data

object

Map of provider name to provider info:

enabled — whether the provider is active
provider_type — "api" or "web_reverse"
base_url — upstream API base URL
keys — array of key summaries (key value, label, weight, enabled)
rate_limit_cooldown — cooldown in seconds after a rate-limit hit
timeout — per-request timeout in seconds
models — include/exclude model filter lists
test_model — model used for connectivity tests

{
  "success": true,
  "data": {
    "openrouter": {
      "enabled": true,
      "provider_type": "api",
      "base_url": "https://openrouter.ai/api",
      "keys": [
        {"key": "sk-or-...", "label": "primary", "weight": 1, "enabled": true}
      ],
      "rate_limit_cooldown": 60,
      "timeout": 120,
      "models": {"include": [], "exclude": []},
      "test_model": "openai/gpt-4o-mini"
    }
  },
  "metadata": {"page": 1, "page_size": 20, "total": 1}
}

POST /api/providers//test

Send a minimal test request to the specified provider to verify API key validity and network reachability.

curl -X POST http://localhost:8787/api/providers/anthropic/test \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-3-haiku-20240307"}'

status

string

"ok" on success, "error" on failure.

message

string

Human-readable result message.

POST /api/providers//verify

Run a deeper multi-probe verification against a provider. Runs text generation, tool calling, and streaming probes in parallel and returns per-probe results. Request body:

probe_types

array

List of probes to run. Accepted values: "text-gen", "tool-call", "streaming". Defaults to all three.

model

string

Override the model used for probing. Falls back to the provider’s test_model or a built-in default.

overall_status

string

"pass" if all probes succeeded, "partial" if some are unsupported, "fail" if any probe failed.

probes

object

Per-probe result with status, latency_ms, error, and summary fields.

Configuration

GET /api/config

Return the raw YAML config file content, preserving comments. Requires authentication.

content

string

Raw YAML string of the current config.yml.

PUT /api/config

Update the config file with new YAML content and hot-reload all components without restarting. Validates YAML syntax and the MonoRelay config schema before writing.

content

string

required

Complete YAML config file content to write. Must be valid YAML that parses into a valid AppConfig.

GET /api/config/full

Return the full configuration as a parsed JSON object, including secrets (admin-only). Requires admin privileges.

PUT /api/config/full

Replace the full configuration from a JSON body (admin-only). Accepts the same structure returned by GET /api/config/full. Secrets are stored separately in the secrets manager.

Response cache

GET /api/cache/stats

Return current response cache statistics.

hits

integer

Number of cache hits since last clear.

misses

integer

Number of cache misses.

size

integer

Current number of cached entries.

max_size

integer

Maximum cache capacity.

POST /api/cache/clear

Invalidate the response cache. Pass an optional model query parameter to clear only entries for a specific model.

# Clear all
curl -X POST http://localhost:8787/api/cache/clear \
  -H "Authorization: Bearer <jwt>"

# Clear for one model
curl -X POST "http://localhost:8787/api/cache/clear?model=claude-opus-4-5" \
  -H "Authorization: Bearer <jwt>"

POST /api/cache/enable

Enable or reconfigure the response cache at runtime.

Query param	Type	Description
`enabled`	boolean	Enable (`true`) or disable (`false`) caching
`ttl_seconds`	integer	Cache entry lifetime in seconds (default `300`)
`max_size`	integer	Maximum number of cached responses (default `1000`)

Per-client usage

GET /api/usage/stats

Return usage statistics tracked per client identity. Pass client_id to scope results to one client.

curl "http://localhost:8787/api/usage/stats?client_id=alice" \
  -H "Authorization: Bearer <jwt>"

POST /api/usage/clear

Reset usage stats. Pass client_id to clear only that client’s counters.

Overview

OpenAI-Compatible

Anthropic-Compatible

Management API

Management API: server info, providers, and config endpoints

Authentication

Server information

GET /api/info

GET /health

Providers

GET /api/providers

POST /api/providers//test

POST /api/providers//verify

Configuration

GET /api/config

PUT /api/config

GET /api/config/full

PUT /api/config/full

Response cache

GET /api/cache/stats

POST /api/cache/clear

POST /api/cache/enable

Per-client usage

GET /api/usage/stats

POST /api/usage/clear

Build docs developers (and LLMs) love

Overview

OpenAI-Compatible

Anthropic-Compatible

Management API

Documentation Index

​Authentication

​Server information

​GET /api/info

​GET /health

​Providers

​GET /api/providers

​POST /api/providers//test

​POST /api/providers//verify

​Configuration

​GET /api/config

​PUT /api/config

​GET /api/config/full

​PUT /api/config/full

​Response cache

​GET /api/cache/stats

​POST /api/cache/clear

​POST /api/cache/enable

​Per-client usage

​GET /api/usage/stats

​POST /api/usage/clear

Build docs developers (and LLMs) love

Authentication

Server information

GET /api/info

GET /health

Providers

GET /api/providers

POST /api/providers//test

POST /api/providers//verify

Configuration

GET /api/config

PUT /api/config

GET /api/config/full

PUT /api/config/full

Response cache

GET /api/cache/stats

POST /api/cache/clear

POST /api/cache/enable

Per-client usage

GET /api/usage/stats

POST /api/usage/clear