CLIProxyAPI

https://help.router-for.me
Admin
CLIProxyAPI is an OpenAI/Gemini/Claude/Codex compatible API service that supports multiple protocols...
Tokens:89,714
Snippets:691
Trust Score:2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### List and build plugin examples

Source: https://help.router-for.me/plugin/development

Start development by listing and building the plugin examples in the repository.

```bash
make -C examples/plugin list
make -C examples/plugin build
```

--------------------------------

### Install and start CLIProxyAPI with Homebrew

Source: https://help.router-for.me/introduction/quick-start

Installs CLIProxyAPI via Homebrew and starts it as a background service with brew services.

```bash
brew install cliproxyapi
brew services start cliproxyapi
```

--------------------------------

### Create CLIProxyAPI config from example

Source: https://help.router-for.me/introduction/quick-start

Creates the required configuration file by copying the example config from the cli-proxy-api-bin package. A configuration file is required before starting the service.

```bash
mkdir -p ~/.cli-proxy-api
cp /usr/share/doc/cli-proxy-api-bin/config.example.yaml ~/.cli-proxy-api/config.yaml
```

--------------------------------

### Install PI CLIProxyAPI provider plugin

Source: https://help.router-for.me/agent-client/pi

Installs the official PI provider plugin for CLIProxyAPI. Run this after starting the CLIProxyAPI server.

```bash
pi install npm:@router-for-me/pi-cliproxyapi-provider
```

--------------------------------

### Run server with custom config file

Source: https://help.router-for.me/configuration/basic

Starts the server with a custom configuration file. The default configuration file is config.yaml in the project root. On macOS installed via Homebrew and running with brew services, the default config path is $(brew --prefix)/etc/cliproxyapi.conf (typically /opt/homebrew/etc/cliproxyapi.conf on Apple Silicon and /usr/local/etc/cliproxyapi.conf on Intel Macs). If you prefer ~/.cli-proxy-api/config.yaml, make the Homebrew path a symlink to that file and ensure the target exists before brew services start.

```bash
./cli-proxy-api --config /path/to/your/config.yaml
```

--------------------------------

### Start OAuth login with GET /oauth/auth-url

Source: https://help.router-for.me/management/apiv8

Starts a provider login and returns the browser URL. The response includes status, url, and state. is_webui=true reuses the management UI callback forwarder for providers that support it; device-code providers can also return flow, user_code, and expires_in.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  'http://localhost:8317/v8/management/oauth/auth-url?provider=claude&is_webui=true'
```

```json
{ "status": "ok", "url": "https://...", "state": "anth-1716206400" }
```

--------------------------------

### Install CLIProxyAPI on Linux with one-click installer

Source: https://help.router-for.me/introduction/quick-start

Downloads and runs the one-click installer script for CLIProxyAPI on Linux.

```bash
curl -fsSL https://raw.githubusercontent.com/router-for-me/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash
```

--------------------------------

### Copy example configuration to config.yaml

Source: https://help.router-for.me/docker/docker-compose

Creates a config.yaml file by copying the example configuration. Windows users can use 'copy config.example.yaml config.yaml' in CMD or PowerShell.

```bash
cp config.example.yaml config.yaml
```

--------------------------------

### GET /plugins/store

Source: https://help.router-for.me/management/apiv8

Returns the store catalog, source errors, install state, and update availability.

```APIDOC
## GET /plugins/store

### Description
Returns the store catalog, source errors, install state, and update availability.

### Method
GET

### Endpoint
/plugins/store

### Response
#### Success Response (200)
- **catalog** (array) - List of available plugins.
- **source_errors** (array) - Errors from plugin sources.
- **install_state** (object) - Current install state.
- **updates** (array) - Available updates.

#### Response Example
```json
{
  "catalog": [],
  "source_errors": [],
  "install_state": {},
  "updates": []
}
```
```

--------------------------------

### Start service with Docker Compose

Source: https://help.router-for.me/docker/docker-compose

Starts the service using the pre-built image from Docker Hub in the background. Recommended for most users.

```bash
docker compose up -d
```

--------------------------------

### GET /plugin-store

Source: https://help.router-for.me/plugin/development

Lists plugins available in the plugin store and their local installation status.

```APIDOC
## GET /v0/management/plugin-store

### Description
Lists plugins in the plugin store and their local installation state.

### Method
GET

### Endpoint
/v0/management/plugin-store

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **plugins** (array) - List of plugins with their local installation state.

#### Response Example
[]
```

--------------------------------

### Install plugin from store with curl and response

Source: https://help.router-for.me/management/apiv8

Installs or updates a plugin from the store using the management API. The response shows the installed plugin details, including the source ID, version, path, and whether a restart is required.

```bash
curl -X POST -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"version":"1.2.3"}' \
  'http://localhost:8317/v8/management/plugins/store/example-plugin/install?source=official'
```

```json
{
  "status": "installed",
  "source_id": "official",
  "id": "example-plugin",
  "version": "1.2.3",
  "path": "/abs/path/plugins/example-plugin.so",
  "restart_required": false
}
```

--------------------------------

### Install Git on Debian

Source: https://help.router-for.me/hands-on/tutorial-5

Installs Git on a Debian-based server. Run as root or with sudo privileges.

```bash
apt update && apt install git -y
```

--------------------------------

### Install Docker with Official Script

Source: https://help.router-for.me/hands-on/tutorial-5

Installs Docker using the official one-click script. Requires curl to be available.

```bash
bash <(curl -fsSL https://get.docker.com)
```

--------------------------------

### GET /oauth/auth-url

Source: https://help.router-for.me/management/apiv8

Starts a provider login and returns the browser URL.

```APIDOC
## GET /oauth/auth-url

### Description
Starts a provider login and returns the browser URL.

### Method
GET

### Endpoint
/oauth/auth-url

### Parameters
#### Query Parameters
- **provider** (string) - Required - Provider name (e.g., `claude`, `codex`, `antigravity`, `kimi`, `kimi-ai`, `xai`, `devin`, `meta`, or a plugin-registered OAuth provider).
- **is_webui** (boolean) - Optional - If `true`, reuses the management UI callback forwarder for providers that support it.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  'http://localhost:8317/v8/management/oauth/auth-url?provider=claude&is_webui=true'
```

### Response
#### Success Response (200)
- **status** (string) - "ok".
- **url** (string) - Browser URL for login.
- **state** (string) - State token.
- **flow** (string) - Optional - Flow type for device-code providers.
- **user_code** (string) - Optional - User code for device-code providers.
- **expires_in** (integer) - Optional - Expiration time in seconds for device-code providers.

#### Response Example
```json
{ "status": "ok", "url": "https://...", "state": "anth-1716206400" }
```

### Error Handling
- **400** - `{ "error": "provider is required" }` if provider missing.
- **404** - `{ "error": "provider_not_found" }` if provider unknown and not handled by a plugin.
```

--------------------------------

### Install CLIProxyAPI from AUR with yay or paru

Source: https://help.router-for.me/introduction/quick-start

Installs the cli-proxy-api-bin package from the AUR using either yay or paru.

```bash
# Using yay
yay -S cli-proxy-api-bin

# Using paru
paru -S cli-proxy-api-bin
```

--------------------------------

### Plugin File Path Example

Source: https://help.router-for.me/plugin/development

Example plugin file path. The plugin ID is derived from the file name without the extension, e.g., example-provider.

```text
plugins/darwin/arm64/example-provider.dylib
```

--------------------------------

### Run Docker to start the server

Source: https://help.router-for.me/docker/docker

Starts the CLI Proxy API server on port 8317. Mounts config, auth, and plugins directories for persistence.

```bash
docker run --rm -p 8317:8317 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api -v /path/to/your/plugins-dir:/CLIProxyAPI/plugins eceasy/cli-proxy-api:latest
```

--------------------------------

### Clone CLIProxyAPI and Initialize Configuration

Source: https://help.router-for.me/hands-on/tutorial-5

Clones the CLIProxyAPI repository, enters the directory, and copies the example configuration to config.yaml.

```bash
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
cp config.example.yaml config.yaml
```

--------------------------------

### Read configuration via GET /config, /config/<path>, and /config.yaml

Source: https://help.router-for.me/management/apiv8

Read the full v8 configuration document as JSON, a nested node, or YAML. The nested node example returns the value of the routing/strategy key, shown as "round-robin". YAML responses use Content-Type: application/yaml; charset=utf-8 and include fields omitted from JSON reads.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v8/management/config
```

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v8/management/config/routing/strategy
```

```text
"round-robin"
```

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -H 'Accept: application/yaml' \
  http://localhost:8317/v8/management/config.yaml
```

--------------------------------

### Start AIStudioBuildWS with Docker Compose

Source: https://help.router-for.me/hands-on/tutorial-11

Builds and starts the AIStudioBuildWS service in detached mode using Docker Compose. After successful deployment, logs appear in CLIProxyAPI.

```bash
docker compose up -d --build
```

--------------------------------

### Symlink Homebrew config to ~/.cli-proxy-api/config.yaml

Source: https://help.router-for.me/introduction/quick-start

Creates a symlink from the Homebrew config path to ~/.cli-proxy-api/config.yaml, backing up any existing regular file. The service is started only after the symlink points to an existing config; otherwise an error is printed and the service is not started.

```bash
brew_conf="$(brew --prefix)/etc/cliproxyapi.conf"
home_conf="$HOME/.cli-proxy-api/config.yaml"

brew services stop cliproxyapi
mkdir -p "$HOME/.cli-proxy-api"

# Copy and back up only a regular file; leave symlinks alone.
# Timestamped backup avoids clobbering an existing .bak.
if [ -f "$brew_conf" ] && [ ! -L "$brew_conf" ]; then
  if [ -f "$home_conf" ] || cp "$brew_conf" "$home_conf"; then
    mv "$brew_conf" "${brew_conf}.bak.$(date +%Y%m%d-%H%M%S)"
  fi
fi

# Start only after the Homebrew path safely points to an existing config.
if [ ! -f "$home_conf" ]; then
  echo "No config file found at $home_conf; service was not started." >&2
elif [ -e "$brew_conf" ] && [ ! -L "$brew_conf" ]; then
  echo "Could not safely replace $brew_conf; service was not started." >&2
elif ln -sfn "$home_conf" "$brew_conf"; then
  brew services start cliproxyapi
else
  echo "Could not create the config symlink; service was not started." >&2
fi
```

--------------------------------

### Example final resource path

Source: https://help.router-for.me/plugin/management-api

Text snippet showing the final resource path format for a plugin resource page.

```text
/v0/resource/plugins/example/status
```

--------------------------------

### POST /plugin-store/{pluginID}/install

Source: https://help.router-for.me/plugin/development

Installs or updates a plugin from the plugin store. Optionally specify a source ID when ambiguous.

```APIDOC
## POST /v0/management/plugin-store/{pluginID}/install

### Description
Installs or updates a plugin from the plugin store. Use `?source=<sourceID>` when multiple sources have the same plugin ID.

### Method
POST

### Endpoint
/v0/management/plugin-store/{pluginID}/install

### Parameters
#### Path Parameters
- **pluginID** (string) - Required - The ID of the plugin to install or update.

#### Query Parameters
- **source** (string) - Optional - The source ID to use when multiple sources have the same plugin ID.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
No specific response fields documented.

#### Response Example
{}
```

--------------------------------

### UsageRecord content example

Source: https://help.router-for.me/plugin/usage-plugin

Example UsageRecord structure containing provider, model, authentication, timing, and token usage details. Failed requests include Failed: true and a Failure field.

```json
{
  "Provider": "codex",
  "ExecutorType": "codex",
  "Model": "gpt-5.5",
  "Alias": "gpt-5.5",
  "APIKey": "client-key-id",
  "AuthID": "auth-1",
  "AuthIndex": "0",
  "AuthType": "oauth",
  "Source": "openai",
  "ReasoningEffort": "high",
  "ServiceTier": "priority",
  "RequestedAt": "2026-06-15T12:00:00Z",
  "Latency": 1234567890,
  "TTFT": 120000000,
  "Failed": false,
  "Detail": {
    "InputTokens": 10,
    "OutputTokens": 20,
    "ReasoningTokens": 0,
    "CachedTokens": 0,
    "TotalTokens": 30
  },
  "ResponseHeaders": {}
}
```

--------------------------------

### GET /oauth/callback

Source: https://help.router-for.me/management/apiv8

Handles OAuth callback via GET.

```APIDOC
## GET /oauth/callback

### Description
Handles OAuth callback via GET. Accepts a callback only for a pending state whose provider matches the session.

### Method
GET

### Endpoint
/oauth/callback

### Parameters
#### Query Parameters
- **provider** (string) - Required - Provider name.
- **state** (string) - Required - State token.
- **code** (string) - Optional - Authorization code.
- **error** (string) - Optional - Error code.
- **error_description** (string) - Optional - Error description.

### Request Example
```bash
curl 'http://localhost:8317/v8/management/oauth/callback?provider=codex&state=codex-...&code=AUTHORIZATION_CODE'
```

### Response
#### Success Response (200)
- Redirect or success response.
```

--------------------------------

### auth.login.start

Source: https://help.router-for.me/plugin/auth-provider

Starts a login flow and returns the URL and polling state for the user.

```APIDOC
## auth.login.start

### Description
Starts a login flow and returns the URL and polling state for the user.

### Method
auth.login.start

### Response
#### Success Response
- **Provider** (string) - The provider identifier.
- **URL** (string) - The login URL for the user.
- **State** (string) - Opaque state for polling.
- **ExpiresAt** (string) - Expiration timestamp for the login flow.
- **Metadata** (object) - Additional metadata.

#### Response Example
{
  "Provider": "plugin-example",
  "URL": "https://example.com/login",
  "State": "opaque-state",
  "ExpiresAt": "2026-06-15T12:05:00Z",
  "Metadata": {}
}
```

--------------------------------

### GET /credentials/models

Source: https://help.router-for.me/management/apiv8

Gets model definitions for a credential.

```APIDOC
## GET /credentials/models

### Description
Returns model definitions for one credential.

### Method
GET

### Endpoint
/credentials/models

### Parameters
#### Query Parameters
- **name** (string) - Required - Credential file name or ID.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  'http://localhost:8317/v8/management/credentials/models?name=file-or-id'
```

### Response
#### Success Response (200)
- **models** (array) - Model definitions.

#### Response Example
```json
{ "models": [ ... ] }
```
```

--------------------------------

### GET /config

Source: https://help.router-for.me/management/apiv8

Retrieves the full v8 configuration document.

```APIDOC
## GET /config

### Description
Retrieves the full v8 configuration document.

### Method
GET

### Endpoint
/config

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token with the management key.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v8/management/config
```

### Response
#### Success Response (200)
- **body** (object) - The full v8 configuration document.

#### Response Example
```json
{
  "routing": {
    "strategy": "round-robin"
  }
}
```

### Error Handling
- **500** - `{ "error": "read_failed" }` or `{ "error": "invalid_config" }` when no usable configuration can be read.
```

--------------------------------

### model.register response example

Source: https://help.router-for.me/plugin/model-registrar

Example of the model.register response returning ModelRegistrationResponse. Provider must be stable, Models must be complete, and ID is the model name used by client requests.

```json
{
  "Provider": "plugin-example",
  "Models": [
    {
      "ID": "plugin-example-model",
      "Object": "model",
      "OwnedBy": "plugin-example",
      "DisplayName": "Plugin Example Model",
      "SupportedGenerationMethods": ["chat"],
      "ContextLength": 8192,
      "MaxCompletionTokens": 1024,
      "UserDefined": true
    }
  ]
}
```

--------------------------------

### host.model.execute

Source: https://help.router-for.me/plugin/host-callbacks

Starts a non-streaming model request.

```APIDOC
## host.model.execute

### Description
Starts a non-streaming model request.

### Method
host.model.execute

### Parameters
#### Request Body
- **entry_protocol** (string) - Required - The protocol for the entry point.
- **exit_protocol** (string) - Required - The protocol for the exit point.
- **model** (string) - Required - The model identifier.
- **stream** (boolean) - Required - Whether the request is streaming.
- **body** (string) - Required - Base64-encoded request body.
- **headers** (object) - Required - HTTP headers.
- **query** (object) - Required - Query parameters.
- **alt** (string) - Required - Alternative configuration.

### Request Example
```json
{
  "entry_protocol": "openai",
  "exit_protocol": "openai",
  "model": "gpt-5.5",
  "stream": false,
  "body": "base64-request-body",
  "headers": {},
  "query": {},
  "alt": ""
}
```

### Response
No response details are provided in the source.
```

--------------------------------

### GET /config.yaml

Source: https://help.router-for.me/management/apiv8

Retrieves the same v8 configuration view as YAML.

```APIDOC
## GET /config.yaml

### Description
Retrieves the same v8 configuration view as YAML.

### Method
GET

### Endpoint
/config.yaml

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token with the management key.
- **Accept** (string) - Optional - Set to `application/yaml` to receive YAML.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -H 'Accept: application/yaml' \
  http://localhost:8317/v8/management/config.yaml
```

### Response
#### Success Response (200)
- **body** (string) - The configuration in YAML format.

#### Response Example
```yaml
routing:
  strategy: round-robin
```

### Error Handling
- **500** - `{ "error": "read_failed" }` or `{ "error": "invalid_config" }` when no usable configuration can be read.
```

--------------------------------

### GET /config/plugins

Source: https://help.router-for.me/management/apiv8

Reads the plugin configuration section.

```APIDOC
## GET /config/plugins

### Description
Reads the plugin section of the configuration.

### Method
GET

### Endpoint
/config/plugins

### Response
#### Success Response (200)
- **status** (string) - Always "ok" when successful.

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### GET /plugins

Source: https://help.router-for.me/plugin/development

Lists all discovered, configured, and registered plugins, returning status flags such as plugins_enabled, effective_enabled, and configuration details.

```APIDOC
## GET /v0/management/plugins

### Description
Lists discovered, configured, and registered plugins, and returns plugin metadata and configuration fields including `plugins_enabled`, `effective_enabled`, menus, and metadata.

### Method
GET

### Endpoint
/v0/management/plugins

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **plugins_enabled** (boolean) - Global plugin switch.
- **effective_enabled** (boolean) - Actual enabled state after global switch, individual switch, and registration state are satisfied.
- **registered** (boolean) - Dynamic library has been loaded and registration completed.
- **enabled** (boolean) - Individual plugin configuration switch.
- **menus** (array) - Menu definitions for plugin resources.
- **metadata** (object) - Plugin metadata.
- **configuration fields** (object) - Configuration fields for each plugin.

#### Response Example
{
  "plugins_enabled": true,
  "effective_enabled": true,
  "registered": true,
  "enabled": true,
  "menus": [],
  "metadata": {},
  "configuration fields": {}
}
```

--------------------------------

### Manage CLIProxyAPI service with systemctl

Source: https://help.router-for.me/introduction/quick-start

Manages the CLIProxyAPI service via systemd user units: starts it and enables auto-start on boot.

```bash
# Start the service
systemctl --user start cli-proxy-api

# Enable auto-start on boot
systemctl --user enable cli-proxy-api
```

--------------------------------

### GET /credentials/download

Source: https://help.router-for.me/management/apiv8

Downloads a credential file.

```APIDOC
## GET /credentials/download

### Description
Downloads one on-disk credential.

### Method
GET

### Endpoint
/credentials/download

### Parameters
#### Query Parameters
- **name** (string) - Required - Name of the credential file to download.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  'http://localhost:8317/v8/management/credentials/download?name=file.json'
```

### Response
#### Success Response (200)
- The credential file content.
```

--------------------------------

### GET /credentials

Source: https://help.router-for.me/management/apiv8

Lists credential files and runtime records.

```APIDOC
## GET /credentials

### Description
Lists credential files and runtime records.

### Method
GET

### Endpoint
/credentials

### Parameters
#### Query Parameters
- **name** (string) - Optional - Filter by credential name.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v8/management/credentials
```

### Response
#### Success Response (200)
- **files** (array) - List of credential records.
- **files[].id** (string) - Credential ID.
- **files[].auth_index** (string) - Auth index.
- **files[].name** (string) - Credential file name.
- **files[].provider** (string) - Provider name.
- **files[].status** (string) - Status (e.g., "ready").
- **files[].disabled** (boolean) - Whether disabled.
- **files[].unavailable** (boolean) - Whether unavailable.
- **files[].runtime_only** (boolean) - Whether runtime-only.
- **files[].source** (string) - Source (e.g., "file").

#### Response Example
```json
{
  "files": [
    {
      "id": "claude-user@example.com",
      "auth_index": "a1b2c3d4e5f67890",
      "name": "claude-user@example.com.json",
      "provider": "claude",
      "status": "ready",
      "disabled": false,
      "unavailable": false,
      "runtime_only": false,
      "source": "file"
    }
  ]
}
```
```

--------------------------------

### GET /observability/logs/errors

Source: https://help.router-for.me/management/apiv8

Lists error log files.

```APIDOC
## GET /observability/logs/errors

### Description
Lists `error-*.log` files.

### Method
GET

### Endpoint
/observability/logs/errors

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v8/management/observability/logs/errors
```

### Response
#### Success Response (200)
- **files** (array of objects) - Each object contains:
  - **name** (string) - The filename.
  - **size** (integer) - The file size in bytes.
  - **modified** (integer) - The Unix timestamp of last modification.

#### Response Example
```json
{ "files": [{ "name": "error-2026-05-05.log", "size": 12345, "modified": 1777982400 }] }
```
```

--------------------------------

### GET /observability/usage/api-keys

Source: https://help.router-for.me/management/apiv8

Returns in-memory usage statistics for API-key credentials.

```APIDOC
## GET /observability/usage/api-keys

### Description
Returns in-memory success and failure buckets for API-key credentials, grouped by provider and keyed by `base_url|api_key`.

### Method
GET

### Endpoint
/observability/usage/api-keys

### Response
#### Success Response (200)
An object containing usage buckets.
```

--------------------------------

### Replace or merge configuration via PATCH /config, PUT /config/<path>, and PUT /config.yaml

Source: https://help.router-for.me/management/apiv8

Replace or merge configuration using PATCH /config, PUT /config/<path>, PATCH /config/<path>, and PUT /config.yaml. The PATCH /config example deep-merges a JSON object; PUT /config/<path> replaces a node with a raw JSON value; PUT /config.yaml replaces the file from a v8 YAML document. There is no PATCH for /config.yaml.

```bash
curl -X PATCH -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"routing":{"retry":{"request-retry":0}},"oauth":{"providers":{"aistudio":{"ws-auth":false}}}}' \
  http://localhost:8317/v8/management/config
```

```bash
curl -X PUT -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -H 'Content-Type: application/json' \
  -d '"direct"' \
  http://localhost:8317/v8/management/config/requests/proxy-url
```

```bash
curl -X PUT -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -H 'Content-Type: application/json' \
  -d '["client-key-1","client-key-2"]' \
  http://localhost:8317/v8/management/config/access/api-keys
```

```bash
curl -X PATCH -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true,"priority":10}' \
  http://localhost:8317/v8/management/config/plugins/configs/example-plugin
```

```bash
curl -X PUT -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -H 'Content-Type: application/yaml' \
  --data-binary @config.yaml \
  http://localhost:8317/v8/management/config.yaml
```

--------------------------------

### GET /config/<path>

Source: https://help.router-for.me/management/apiv8

Retrieves a specific configuration node identified by the path, returning it as JSON.

```APIDOC
## GET /config/<path>

### Description
Retrieves a specific configuration node identified by the path, returning it as JSON.

### Method
GET

### Endpoint
/config/<path>

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the configuration node.

### Response
#### Success Response (200)
- Returns the YAML node at the specified path as JSON.

#### Error Response (404)
- **error** (string) - Error code, e.g., "not_found" when the path does not exist.

#### Response Example
{
  "error": "not_found"
}
```

--------------------------------

### GET /observability/usage/queue

Source: https://help.router-for.me/management/apiv8

Pops usage records from the in-memory queue.

```APIDOC
## GET /observability/usage/queue

### Description
Pops up to `count` usage records from the in-memory queue. Records are removed from the queue.

### Method
GET

### Endpoint
/observability/usage/queue

### Parameters
#### Query Parameters
- **count** (integer) - Optional - Maximum number of records to pop. Defaults to `1` and must be a positive integer.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  'http://localhost:8317/v8/management/observability/usage/queue?count=10'
```

### Response
#### Success Response (200)
An array of usage records. An empty queue returns `[]`.
```

--------------------------------

### GET /observability/logs

Source: https://help.router-for.me/management/apiv8

Reads log lines from the application log.

```APIDOC
## GET /observability/logs

### Description
Reads log lines from the application log.

### Method
GET

### Endpoint
/observability/logs

### Parameters
#### Query Parameters
- **after** (integer) - Optional - Unix timestamp. Return only newer lines.
- **limit** (integer) - Optional - Maximum number of lines. With `limit` and no `after`, the newest lines are returned.
- **cursor** (string) - Optional - Opaque cursor from a previous `next-cursor`.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  'http://localhost:8317/v8/management/observability/logs?limit=2'
```

### Response
#### Success Response (200)
- **lines** (array of strings) - The log lines.
- **line-count** (integer) - The number of lines returned.
- **latest-timestamp** (integer) - The Unix timestamp of the latest line.
- **next-cursor** (string) - Opaque cursor for the next page.

#### Response Example
```json
{
  "lines": ["2026-05-05 12:00:00 info request accepted"],
  "line-count": 1,
  "latest-timestamp": 1777982400,
  "next-cursor": "<OPAQUE_CURSOR>"
}
```

### Error Handling
- **400** - If file logging is disabled, returns `{ "error": "logging to file disabled" }`.
```

--------------------------------

### Example config.yaml with all settings

Source: https://help.router-for.me/configuration/basic

Example configuration file for the server. It shows all available settings with their defaults and comments. The server reads this YAML file from the project root by default. Key behaviors: host empty binds all interfaces; port defaults to 8317; TLS is disabled by default; remote management is disabled by default and requires a key; leaving secret-key empty disables the Management API entirely (404 for all /v0/management routes); request-retry retries on 403, 408, 500, 502, 503, or 504; routing strategy defaults to round-robin; session-affinity defaults to false with a TTL of 1h; codex-instructions-enabled defaults to false.

```yaml
# Server host/interface to bind to. Default is empty ("") to bind all interfaces (IPv4 + IPv6).
# Use "127.0.0.1" or "localhost" to restrict access to local machine only.
host: ""

# Server port
port: 8317

# TLS settings for HTTPS. When enabled, the server listens with the provided certificate and key.
tls:
  enable: false
  cert: ""
  key: ""

# Management API settings
remote-management:
  # Whether to allow remote (non-localhost) management access.
  # When false, only localhost can access management endpoints (a key is still required).
  allow-remote: false

  # Management key. If a plaintext value is provided here, it will be hashed on startup.
  # All management requests (even from localhost) require this key.
  # Leave empty to disable the Management API entirely (404 for all /v0/management routes).
  secret-key: ""

  # Disable the bundled management control panel asset download and HTTP route when true.
  disable-control-panel: false

  # GitHub repository for the management control panel. Accepts a repository URL or releases API URL.
  panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center"

# Authentication directory (supports ~ for home directory)
auth-dir: "~/.cli-proxy-api"

# API keys for authentication
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"
  - "your-api-key-3"

# Enable debug logging
debug: false

# When true, disable high-overhead HTTP middleware features to reduce per-request memory usage under high concurrency.
commercial-mode: false

# When true, write application logs to rotating files instead of stdout
logging-to-file: false

# Maximum total size (MB) of log files under the logs directory. When exceeded, the oldest log
# files are deleted until within the limit. Set to 0 to disable.
logs-max-total-size-mb: 0

# When false, disable in-memory usage statistics aggregation
usage-statistics-enabled: false

# Proxy URL. Supports socks5/http/https protocols. Example: socks5://user:pass@192.168.1.1:1080/
proxy-url: ""

# When true, unprefixed model requests only use credentials without a prefix (except when prefix == model name).
force-model-prefix: false

# Number of times to retry a request. Retries will occur if the HTTP response code is 403, 408, 500, 502, 503, or 504.
request-retry: 3

# Maximum wait time in seconds for a cooled-down credential before triggering a retry.
max-retry-interval: 30

# disable-image-generation supports: false (default), true, or "chat".
# - true: disable image_generation everywhere (also returns 404 for /v1/images/generations and /v1/images/edits).
# - "chat": disable image_generation injection on non-images endpoints, but keep /v1/images/generations and /v1/images/edits enabled.
disable-image-generation: false

# Quota exceeded behavior
quota-exceeded:
  switch-project: true # Whether to automatically switch to another project when a quota is exceeded
  switch-preview-model: true # Whether to automatically switch to a preview model when a quota is exceeded
  antigravity-credits: true # Whether to use credits as last-resort fallback when all free-tier auths are exhausted for Claude models

# Routing strategy for selecting credentials when multiple match.
routing:
  strategy: "round-robin" # round-robin (default), fill-first
  # Enable universal session-sticky routing for all clients.
  # Session IDs are extracted from: metadata.user_id (Claude Code session format),
  # X-Session-ID, Session_id (Codex),
  # X-Client-Request-Id (PI), conversation_id, or first few messages hash.
  # Automatic failover is always enabled when bound auth becomes unavailable.
  session-affinity: false # default: false
  # How long session-to-auth bindings are retained. Default: 1h
  session-affinity-ttl: "1h"

# When true, enable authentication for the WebSocket API (/v1/ws).
ws-auth: false

# When > 0, emit blank lines every N seconds for non-streaming responses to prevent idle timeouts.
nonstream-keepalive-interval: 0

# When true, enable official Codex instructions injection for Codex API requests.
# When false (default), CodexInstructionsForModel returns immediately without modification.
codex-instructions-enabled: false
```

--------------------------------

### GET /server/latest-version

Source: https://help.router-for.me/management/apiv8

Retrieves the latest GitHub release tag for the project. It does not download assets.

```APIDOC
## GET /server/latest-version

### Description
Retrieves the latest GitHub release tag for the project. It does not download assets.

### Method
GET

### Endpoint
`/server/latest-version`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token with the management key.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v8/management/server/latest-version
```

### Response
#### Success Response (200)
- **latest-version** (string) - The latest GitHub release tag.

#### Response Example
```json
{ "latest-version": "v1.2.3" }
```
```

--------------------------------

### GET /config

Source: https://help.router-for.me/management/apiv8

Retrieves the entire configuration as a JSON representation of the YAML root node.

```APIDOC
## GET /config

### Description
Retrieves the entire configuration as a JSON representation of the YAML root node.

### Method
GET

### Endpoint
/config

### Response
#### Success Response (200)
- Returns the YAML root node as JSON.

#### Error Response (404)
- **error** (string) - Error code, e.g., "not_found" when the path does not exist.

#### Response Example
{
  "error": "not_found"
}
```

--------------------------------

### GET /plugins/:id/quota

Source: https://help.router-for.me/management/apiv8

Retrieves the quota for a specific plugin and auth index.

```APIDOC
## GET /plugins/:id/quota

### Description
Retrieves the quota for a specific plugin and auth index.

### Method
GET

### Endpoint
/plugins/:id/quota

### Parameters
#### Path Parameters
- **id** (string) - Required - The plugin identifier.

#### Query Parameters
- **auth_index** (string) - Required - The auth index. Alias: authIndex.

### Response
#### Success Response (200)
- **quota** (object) - The quota information.

#### Error Response (404)
- **error** (string) - Error message when quota provider is missing.

#### Error Response (502)
- **error** (string) - Error message when quota provider fails.

#### Response Example
```json
{
  "quota": {}
}
```
```

--------------------------------

### GET /observability/logs/errors/:name

Source: https://help.router-for.me/management/apiv8

Downloads a specific error log file.

```APIDOC
## GET /observability/logs/errors/:name

### Description
Downloads one error log file.

### Method
GET

### Endpoint
/observability/logs/errors/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - The error log filename. Must be an existing `error-*.log` filename without path separators.

### Response
#### Success Response (200)
The file content.
```
Tokens:
Raw