chuan/CLIProxyAPI
1
0
Fork 0
mirror of https://github.com/router-for-me/CLIProxyAPI.git synced 2026-02-19 04:40:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update MANAGEMENT_API.md with expanded documentation for endpoints

Browse Source 
- Refined API documentation structure and enhanced clarity for various endpoints, including `/debug`, `/proxy-url`, `/quota-exceeded`, and authentication management.
- Added comprehensive examples for request and response bodies across endpoints.
- Detailed object-array API key management for Codex, Gemini, Claude, and OpenAI compatibility providers.
- Enhanced descriptions for request retry logic and request logging endpoints.
- Improved authentication key handling descriptions and updated examples for YAML configuration impacts.
This commit is contained in:
Luis Pater
2025-09-03 09:07:43 +08:00
parent c4a42eb1f0
commit caf386c877
2 changed files with 495 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

507
MANAGEMENT_API.md
View File

@@ -1,284 +1,511 @@
# Management API # Management API
Base URL: `http://localhost:8317/v0/management` Base path: `http://localhost:8317/v0/management`
This API manages runtime configuration and authentication files for the CLI Proxy API. All changes persist to the YAML config file and are hot‑reloaded by the server. This API manages the CLI Proxy API’s runtime configuration and authentication files. All changes are persisted to the YAML config file and hot‑reloaded by the service.
Note: The following options cannot be changed via API and must be edited in the config file, then restart if needed: Note: The following options cannot be modified via API and must be set in the config file (restart if needed):
- `allow-remote-management` - `allow-remote-management`
- `remote-management-key` (stored as bcrypt hash after startup if plaintext was provided) - `remote-management-key` (if plaintext is detected at startup, it is automatically bcrypt‑hashed and written back to the config)
## Authentication ## Authentication
- All requests (including localhost) must include a management key. - All requests (including localhost) must provide a valid management key.
- Remote access additionally requires `allow-remote-management: true` in config. - Remote access requires enabling remote management in the config: `allow-remote-management: true`.
- Provide the key via one of: - Provide the management key (in plaintext) via either:
- `Authorization: Bearer <plaintext-key>` - `Authorization: Bearer <plaintext-key>`
- `X-Management-Key: <plaintext-key>` - `X-Management-Key: <plaintext-key>`
If a plaintext key is present in the config on startup, it is bcrypt-hashed and written back to the config file automatically. If `remote-management-key` is empty, the Management API is entirely disabled (404 for `/v0/management/*`). If a plaintext key is detected in the config at startup, it will be bcrypt‑hashed and written back to the config file automatically.
## Request/Response Conventions ## Request/Response Conventions
- Content type: `application/json` unless noted. - Content-Type: `application/json` (unless otherwise noted).
- Boolean/int/string updates use body: `{ "value": <type> }`. - Boolean/int/string updates: request body is `{ "value": <type> }`.
- Array PUT bodies can be either a raw array (e.g. `["a","b"]`) or `{ "items": [ ... ] }`. - Array PUT: either a raw array (e.g. `["a","b"]`) or `{ "items": [ ... ] }`.
- Array PATCH accepts either `{ "old": "k1", "new": "k2" }` or `{ "index": 0, "value": "k2" }`. - Array PATCH: supports `{ "old": "k1", "new": "k2" }` or `{ "index": 0, "value": "k2" }`.
- Object-array PATCH supports either index or key match (documented per endpoint). - Object-array PATCH: supports matching by index or by key field (specified per endpoint).
## Endpoints ## Endpoints
### Debug ### Debug
- GET `/debug` — get current debug flag - GET `/debug` — Get the current debug state
- PUT/PATCH `/debug` — set debug (boolean) - Request:
Example (set true):
```bash ```bash
curl -X PUT \ curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/debug
```
- Response:
```json
{ "debug": false }
```
- PUT/PATCH `/debug` — Set debug (boolean)
- Request:
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-H 'Content-Type: application/json' \
-d '{"value":true}' \ -d '{"value":true}' \
http://localhost:8317/v0/management/debug http://localhost:8317/v0/management/debug
``` ```
Response: - Response:
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
### Proxy URL ### Proxy Server URL
- GET `/proxy-url` — get proxy URL string - GET `/proxy-url` — Get the proxy URL string
- PUT/PATCH `/proxy-url` — set proxy URL string - Request:
- DELETE `/proxy-url` — clear proxy URL
Example (set):
```bash ```bash
curl -X PATCH -H 'Content-Type: application/json' \ curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/proxy-url
```
- Response:
```json
{ "proxy-url": "socks5://user:pass@127.0.0.1:1080/" }
```
- PUT/PATCH `/proxy-url` — Set the proxy URL string
- Request (PUT):
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":"socks5://user:pass@127.0.0.1:1080/"}' \ -d '{"value":"socks5://user:pass@127.0.0.1:1080/"}' \
http://localhost:8317/v0/management/proxy-url http://localhost:8317/v0/management/proxy-url
``` ```
Response: - Request (PATCH):
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":"http://127.0.0.1:8080"}' \
http://localhost:8317/v0/management/proxy-url
```
- Response:
```json
{ "status": "ok" }
```
- DELETE `/proxy-url` — Clear the proxy URL
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE http://localhost:8317/v0/management/proxy-url
```
- Response:
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
### Quota Exceeded Behavior ### Quota Exceeded Behavior
- GET `/quota-exceeded/switch-project` - GET `/quota-exceeded/switch-project`
- PUT/PATCH `/quota-exceeded/switch-project` — boolean - Request:
- GET `/quota-exceeded/switch-preview-model` ```bash
- PUT/PATCH `/quota-exceeded/switch-preview-model` — boolean curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-project
```
Example: - Response:
```json
{ "switch-project": true }
```
- PUT/PATCH `/quota-exceeded/switch-project` — Boolean
- Request:
```bash ```bash
curl -X PUT -H 'Content-Type: application/json' \ curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":false}' \ -d '{"value":false}' \
http://localhost:8317/v0/management/quota-exceeded/switch-project http://localhost:8317/v0/management/quota-exceeded/switch-project
``` ```
Response: - Response:
```json
{ "status": "ok" }
```
- GET `/quota-exceeded/switch-preview-model`
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-preview-model
```
- Response:
```json
{ "switch-preview-model": true }
```
- PUT/PATCH `/quota-exceeded/switch-preview-model` — Boolean
- Request:
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":true}' \
http://localhost:8317/v0/management/quota-exceeded/switch-preview-model
```
- Response:
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
### API Keys (proxy server auth) ### API Keys (proxy service auth)
- GET `/api-keys` — return the full list - GET `/api-keys` — Return the full list
- PUT `/api-keys` — replace the full list - Request:
- PATCH `/api-keys` — update one entry (by `old/new` or `index/value`) ```bash
- DELETE `/api-keys` — remove one entry (by `?value=` or `?index=`) curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/api-keys
```
Examples: - Response:
```json
{ "api-keys": ["k1","k2","k3"] }
```
- PUT `/api-keys` — Replace the full list
- Request:
```bash ```bash
# Replace list
curl -X PUT -H 'Content-Type: application/json' \ curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '["k1","k2","k3"]' \ -d '["k1","k2","k3"]' \
http://localhost:8317/v0/management/api-keys http://localhost:8317/v0/management/api-keys
```
# Patch: replace k2 -> k2b - Response:
```json
{ "status": "ok" }
```
- PATCH `/api-keys` — Modify one item (`old/new` or `index/value`)
- Request (by old/new):
```bash
curl -X PATCH -H 'Content-Type: application/json' \ curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"old":"k2","new":"k2b"}' \ -d '{"old":"k2","new":"k2b"}' \
http://localhost:8317/v0/management/api-keys http://localhost:8317/v0/management/api-keys
```
# Delete by value - Request (by index/value):
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"index":0,"value":"k1b"}' \
http://localhost:8317/v0/management/api-keys
```
- Response:
```json
{ "status": "ok" }
```
- DELETE `/api-keys` — Delete one (`?value=` or `?index=`)
- Request (by value):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?value=k1' curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?value=k1'
``` ```
Response (GET): - Request (by index):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?index=0'
```
- Response:
```json ```json
{ "api-keys": ["k1","k2b","k3"] } { "status": "ok" }
``` ```
### Generative Language API Keys (Gemini) ### Gemini API Key (Generative Language)
- GET `/generative-language-api-key` - GET `/generative-language-api-key`
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/generative-language-api-key
```
- Response:
```json
{ "generative-language-api-key": ["AIzaSy...01","AIzaSy...02"] }
```
- PUT `/generative-language-api-key` - PUT `/generative-language-api-key`
- Request:
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '["AIzaSy-1","AIzaSy-2"]' \
http://localhost:8317/v0/management/generative-language-api-key
```
- Response:
```json
{ "status": "ok" }
```
- PATCH `/generative-language-api-key` - PATCH `/generative-language-api-key`
- Request:
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"old":"AIzaSy-1","new":"AIzaSy-1b"}' \
http://localhost:8317/v0/management/generative-language-api-key
```
- Response:
```json
{ "status": "ok" }
```
- DELETE `/generative-language-api-key` - DELETE `/generative-language-api-key`
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/generative-language-api-key?value=AIzaSy-2'
```
- Response:
```json
{ "status": "ok" }
```
Same request/response shapes as API keys. ### Codex API KEY (object array)
- GET `/codex-api-key` — List all
### Codex API Keys (OpenAI)
- GET `/codex-api-key`
- Request: - Request:
```bash ```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/codex-api-key curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/codex-api-key
``` ```
- Response: - Response:
```json ```json
{ "codex-api-key": ["sk-proj-01","sk-proj-02"] } { "codex-api-key": [ { "api-key": "sk-a", "base-url": "" } ] }
``` ```
- PUT `/codex-api-key` - PUT `/codex-api-key` — Replace the list
- Request: - Request:
```bash ```bash
curl -X PUT -H 'Content-Type: application/json' \ curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '["sk-proj-1","sk-proj-2"]' \ -d '[{"api-key":"sk-a"},{"api-key":"sk-b","base-url":"https://c.example.com"}]' \
http://localhost:8317/v0/management/codex-api-key http://localhost:8317/v0/management/codex-api-key
``` ```
- Response: - Response:
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
- PATCH `/codex-api-key` - PATCH `/codex-api-key` — Modify one (by `index` or `match`)
- Request (by index):
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com"}}' \
http://localhost:8317/v0/management/codex-api-key
```
- Request (by match):
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":""}}' \
http://localhost:8317/v0/management/codex-api-key
```
- Response:
```json
{ "status": "ok" }
```
- DELETE `/codex-api-key` — Delete one (`?api-key=` or `?index=`)
- Request (by api-key):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?api-key=sk-b2'
```
- Request (by index):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?index=0'
```
- Response:
```json
{ "status": "ok" }
```
### Request Retry Count
- GET `/request-retry` — Get integer
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-retry
```
- Response:
```json
{ "request-retry": 3 }
```
- PUT/PATCH `/request-retry` — Set integer
- Request: - Request:
```bash ```bash
curl -X PATCH -H 'Content-Type: application/json' \ curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"old":"sk-proj-1","new":"sk-proj-1b"}' \ -d '{"value":5}' \
http://localhost:8317/v0/management/codex-api-key http://localhost:8317/v0/management/request-retry
``` ```
- Response: - Response:
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
- DELETE `/codex-api-key`
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?value=sk-proj-2'
```
- Response:
```json
{ "status": "ok" }
```
### Request Logging
- GET `/request-log` — get boolean
- PUT/PATCH `/request-log` — set boolean
### Request Retry
- GET `/request-retry` — get integer
- PUT/PATCH `/request-retry` — set integer
### Allow Localhost Unauthenticated ### Allow Localhost Unauthenticated
- GET `/allow-localhost-unauthenticated` — get boolean - GET `/allow-localhost-unauthenticated` — Get boolean
- PUT/PATCH `/allow-localhost-unauthenticated` — set boolean - Request:
```bash
### Claude API Keys (object array) curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/allow-localhost-unauthenticated
- GET `/claude-api-key` — full list ```
- PUT `/claude-api-key` — replace list - Response:
- PATCH `/claude-api-key` — update one item (by `index` or `match` API key)
- DELETE `/claude-api-key` — remove one item (`?api-key=` or `?index=`)
Object shape:
```json ```json
{ { "allow-localhost-unauthenticated": false }
"api-key": "sk-...", ```
"base-url": "https://custom.example.com" // optional - PUT/PATCH `/allow-localhost-unauthenticated` — Set boolean
} - Request:
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":true}' \
http://localhost:8317/v0/management/allow-localhost-unauthenticated
```
- Response:
```json
{ "status": "ok" }
``` ```
Examples: ### Claude API KEY (object array)
- GET `/claude-api-key` — List all
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/claude-api-key
```
- Response:
```json
{ "claude-api-key": [ { "api-key": "sk-a", "base-url": "" } ] }
```
- PUT `/claude-api-key` — Replace the list
- Request:
```bash ```bash
# Replace list
curl -X PUT -H 'Content-Type: application/json' \ curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '[{"api-key":"sk-a"},{"api-key":"sk-b","base-url":"https://c.example.com"}]' \ -d '[{"api-key":"sk-a"},{"api-key":"sk-b","base-url":"https://c.example.com"}]' \
http://localhost:8317/v0/management/claude-api-key http://localhost:8317/v0/management/claude-api-key
```
# Patch by index - Response:
```json
{ "status": "ok" }
```
- PATCH `/claude-api-key` — Modify one (by `index` or `match`)
- Request (by index):
```bash
curl -X PATCH -H 'Content-Type: application/json' \ curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com"}}' \ -d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com"}}' \
http://localhost:8317/v0/management/claude-api-key http://localhost:8317/v0/management/claude-api-key
```
# Patch by match (api-key) - Request (by match):
```bash
curl -X PATCH -H 'Content-Type: application/json' \ curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":""}}' \ -d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":""}}' \
http://localhost:8317/v0/management/claude-api-key http://localhost:8317/v0/management/claude-api-key
```
# Delete by api-key - Response:
```json
{ "status": "ok" }
```
- DELETE `/claude-api-key` — Delete one (`?api-key=` or `?index=`)
- Request (by api-key):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?api-key=sk-b2' curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?api-key=sk-b2'
``` ```
Response (GET): - Request (by index):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?index=0'
```
- Response:
```json ```json
{ { "status": "ok" }
"claude-api-key": [
{ "api-key": "sk-a", "base-url": "" }
]
}
``` ```
### OpenAI Compatibility Providers (object array) ### OpenAI Compatibility Providers (object array)
- GET `/openai-compatibility` — full list - GET `/openai-compatibility` — List all
- PUT `/openai-compatibility` — replace list - Request:
- PATCH `/openai-compatibility` — update one item by `index` or `name` ```bash
- DELETE `/openai-compatibility` — remove by `?name=` or `?index=` curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/openai-compatibility
```
Object shape: - Response:
```json ```json
{ { "openai-compatibility": [ { "name": "openrouter", "base-url": "https://openrouter.ai/api/v1", "api-keys": [], "models": [] } ] }
"name": "openrouter", ```
"base-url": "https://openrouter.ai/api/v1", - PUT `/openai-compatibility` — Replace the list
"api-keys": ["sk-..."], - Request:
"models": [ {"name": "moonshotai/kimi-k2:free", "alias": "kimi-k2"} ]
}
```
Examples:
```bash ```bash
# Replace list
curl -X PUT -H 'Content-Type: application/json' \ curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-keys":["sk"],"models":[{"name":"m","alias":"a"}]}]' \ -d '[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-keys":["sk"],"models":[{"name":"m","alias":"a"}]}]' \
http://localhost:8317/v0/management/openai-compatibility http://localhost:8317/v0/management/openai-compatibility
```
# Patch by name - Response:
```json
{ "status": "ok" }
```
- PATCH `/openai-compatibility` — Modify one (by `index` or `name`)
- Request (by name):
```bash
curl -X PATCH -H 'Content-Type: application/json' \ curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"name":"openrouter","value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-keys":[],"models":[]}}' \ -d '{"name":"openrouter","value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-keys":[],"models":[]}}' \
http://localhost:8317/v0/management/openai-compatibility http://localhost:8317/v0/management/openai-compatibility
```
# Delete by index - Request (by index):
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"index":0,"value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-keys":[],"models":[]}}' \
http://localhost:8317/v0/management/openai-compatibility
```
- Response:
```json
{ "status": "ok" }
```
- DELETE `/openai-compatibility` — Delete (`?name=` or `?index=`)
- Request (by name):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?name=openrouter'
```
- Request (by index):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?index=0' curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?index=0'
``` ```
Response (GET): - Response:
```json ```json
{ "openai-compatibility": [ { "name": "openrouter", "base-url": "...", "api-keys": [], "models": [] } ] } { "status": "ok" }
``` ```
### Auth Files Management ### Auth File Management
List JSON token files under `auth-dir`, download/upload/delete. Manage JSON token files under `auth-dir`: list, download, upload, delete.
- GET `/auth-files` — list - GET `/auth-files` — List
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/auth-files
```
- Response: - Response:
```json ```json
{ "files": [ { "name": "acc1.json", "size": 1234, "modtime": "2025-08-30T12:34:56Z" } ] } { "files": [ { "name": "acc1.json", "size": 1234, "modtime": "2025-08-30T12:34:56Z" } ] }
``` ```
- GET `/auth-files/download?name=<file.json>` — download a single file - GET `/auth-files/download?name=<file.json>` — Download a single file
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -OJ 'http://localhost:8317/v0/management/auth-files/download?name=acc1.json'
```
- POST `/auth-files` — upload - POST `/auth-files` — Upload
- Multipart form: field `file` (must be `.json`) - Request (multipart):
- Or raw JSON body with `?name=<file.json>` ```bash
- Response: `{ "status": "ok" }` curl -X POST -F 'file=@/path/to/acc1.json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
http://localhost:8317/v0/management/auth-files
```
- Request (raw JSON):
```bash
curl -X POST -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d @/path/to/acc1.json \
'http://localhost:8317/v0/management/auth-files?name=acc1.json'
```
- Response:
```json
{ "status": "ok" }
```
- DELETE `/auth-files?name=<file.json>` — delete a single file - DELETE `/auth-files?name=<file.json>` — Delete a single file
- DELETE `/auth-files?all=true` — delete all `.json` files in `auth-dir` - Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/auth-files?name=acc1.json'
```
- Response:
```json
{ "status": "ok" }
```
- DELETE `/auth-files?all=true` — Delete all `.json` files under `auth-dir`
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/auth-files?all=true'
```
- Response:
```json
{ "status": "ok", "deleted": 3 }
```
## Error Responses ## Error Responses
Generic error shapes: Generic error format:
- 400 Bad Request: `{ "error": "invalid body" }` - 400 Bad Request: `{ "error": "invalid body" }`
- 401 Unauthorized: `{ "error": "missing management key" }` or `{ "error": "invalid management key" }` - 401 Unauthorized: `{ "error": "missing management key" }` or `{ "error": "invalid management key" }`
- 403 Forbidden: `{ "error": "remote management disabled" }` - 403 Forbidden: `{ "error": "remote management disabled" }`
@@ -287,6 +514,6 @@ Generic error shapes:
## Notes ## Notes
- Changes are written to the YAML configuration file and picked up by the server’s file watcher to hot-reload clients and settings. - Changes are written back to the YAML config file and hot‑reloaded by the file watcher and clients.
- `allow-remote-management` and `remote-management-key` must be edited in the configuration file and cannot be changed via the API. - `allow-remote-management` and `remote-management-key` cannot be changed via the API; configure them in the config file.

52
MANAGEMENT_API_CN.md
View File

@@ -233,67 +233,55 @@
{ "status": "ok" } { "status": "ok" }
``` ```
### Codex API Key（OpenAI） ### Codex API KEY（对象数组）
- GET `/codex-api-key` - GET `/codex-api-key` — 列出全部
- 请求： - 请求：
```bash ```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/codex-api-key curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/codex-api-key
``` ```
- 响应： - 响应：
```json ```json
{ "codex-api-key": ["sk-proj-01","sk-proj-02"] } { "codex-api-key": [ { "api-key": "sk-a", "base-url": "" } ] }
``` ```
- PUT `/codex-api-key` - PUT `/codex-api-key` — 完整改写列表
- 请求： - 请求：
```bash ```bash
curl -X PUT -H 'Content-Type: application/json' \ curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '["sk-proj-1","sk-proj-2"]' \ -d '[{"api-key":"sk-a"},{"api-key":"sk-b","base-url":"https://c.example.com"}]' \
http://localhost:8317/v0/management/codex-api-key http://localhost:8317/v0/management/codex-api-key
``` ```
- 响应： - 响应：
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
- PATCH `/codex-api-key` - PATCH `/codex-api-key` — 修改其中一个（按 `index` 或 `match`）
- 请求： - 请求（按索引）：
```bash ```bash
curl -X PATCH -H 'Content-Type: application/json' \ curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"old":"sk-proj-1","new":"sk-proj-1b"}' \ -d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com"}}' \
http://localhost:8317/v0/management/codex-api-key
```
- 请求（按匹配）：
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":""}}' \
http://localhost:8317/v0/management/codex-api-key http://localhost:8317/v0/management/codex-api-key
``` ```
- 响应： - 响应：
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
- DELETE `/codex-api-key` - DELETE `/codex-api-key` — 删除其中一个（`?api-key=` 或 `?index=`）
- 请求： - 请求（按 api-key）：
```bash ```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?value=sk-proj-2' curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?api-key=sk-b2'
``` ```
- 响应： - 请求（按索引）：
```json
{ "status": "ok" }
```
### 开启请求日志
- GET `/request-log` — 获取布尔值
- 请求：
```bash ```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-log curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?index=0'
```
- 响应：
```json
{ "request-log": true }
```
- PUT/PATCH `/request-log` — 设置布尔值
- 请求：
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":true}' \
http://localhost:8317/v0/management/request-log
``` ```
- 响应： - 响应：
```json ```json