chuan/CLIProxyAPI
1
0
Fork 0
mirror of https://github.com/router-for-me/CLIProxyAPI.git synced 2026-02-18 20:30:51 +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

655
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)
Example (set true):
```bash
curl -X PUT \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-H 'Content-Type: application/json' \
-d '{"value":true}' \
http://localhost:8317/v0/management/debug
```
Response:
```json
{ "status": "ok" }
```
### Proxy URL
- GET `/proxy-url` — get proxy URL string
- PUT/PATCH `/proxy-url` — set proxy URL string
- DELETE `/proxy-url` — clear proxy URL
Example (set):
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":"socks5://user:pass@127.0.0.1:1080/"}' \
http://localhost:8317/v0/management/proxy-url
```
Response:
```json
{ "status": "ok" }
```
### Quota Exceeded Behavior
- GET `/quota-exceeded/switch-project`
- PUT/PATCH `/quota-exceeded/switch-project` — boolean
- GET `/quota-exceeded/switch-preview-model`
- PUT/PATCH `/quota-exceeded/switch-preview-model` — boolean
Example:
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":false}' \
http://localhost:8317/v0/management/quota-exceeded/switch-project
```
Response:
```json
{ "status": "ok" }
```
### API Keys (proxy server auth)
- GET `/api-keys` — return the full list
- PUT `/api-keys` — replace the full list
- PATCH `/api-keys` — update one entry (by `old/new` or `index/value`)
- DELETE `/api-keys` — remove one entry (by `?value=` or `?index=`)
Examples:
```bash
# Replace list
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '["k1","k2","k3"]' \
http://localhost:8317/v0/management/api-keys
# Patch: replace k2 -> k2b
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"old":"k2","new":"k2b"}' \
http://localhost:8317/v0/management/api-keys
# Delete by value
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?value=k1'
```
Response (GET):
```json
{ "api-keys": ["k1","k2b","k3"] }
```
### Generative Language API Keys (Gemini)
- GET `/generative-language-api-key`
- PUT `/generative-language-api-key`
- PATCH `/generative-language-api-key`
- DELETE `/generative-language-api-key`
Same request/response shapes as API keys.
### 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/debug
``` ```
- Response: - Response:
```json ```json
{ "codex-api-key": ["sk-proj-01","sk-proj-02"] } { "debug": false }
``` ```
- PUT `/codex-api-key` - PUT/PATCH `/debug` — Set debug (boolean)
- 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 '{"value":true}' \
http://localhost:8317/v0/management/codex-api-key http://localhost:8317/v0/management/debug
``` ```
- Response: - Response:
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
- PATCH `/codex-api-key`
### Proxy Server URL
- GET `/proxy-url` — Get the proxy URL string
- Request:
```bash
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>' \
-d '{"value":"socks5://user:pass@127.0.0.1:1080/"}' \
http://localhost:8317/v0/management/proxy-url
```
- 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
{ "status": "ok" }
```
### Quota Exceeded Behavior
- GET `/quota-exceeded/switch-project`
- Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-project
```
- Response:
```json
{ "switch-project": true }
```
- PUT/PATCH `/quota-exceeded/switch-project` — Boolean
- Request:
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":false}' \
http://localhost:8317/v0/management/quota-exceeded/switch-project
```
- 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: - 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":true}' \
http://localhost:8317/v0/management/codex-api-key http://localhost:8317/v0/management/quota-exceeded/switch-preview-model
``` ```
- Response: - Response:
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
- DELETE `/codex-api-key`
### API Keys (proxy service auth)
- GET `/api-keys` — Return the full list
- Request: - Request:
```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>' http://localhost:8317/v0/management/api-keys
```
- Response:
```json
{ "api-keys": ["k1","k2","k3"] }
```
- PUT `/api-keys` — Replace the full list
- Request:
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '["k1","k2","k3"]' \
http://localhost:8317/v0/management/api-keys
```
- 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' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"old":"k2","new":"k2b"}' \
http://localhost:8317/v0/management/api-keys
```
- 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'
```
- Request (by index):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?index=0'
``` ```
- Response: - Response:
```json ```json
{ "status": "ok" } { "status": "ok" }
``` ```
### Request Logging ### Gemini API Key (Generative Language)
- GET `/request-log` — get boolean - GET `/generative-language-api-key`
- PUT/PATCH `/request-log` — set boolean - 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`
- 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`
- 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`
- 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" }
```
### Request Retry ### Codex API KEY (object array)
- GET `/request-retry` — get integer - GET `/codex-api-key` — List all
- PUT/PATCH `/request-retry` — set integer - Request:
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/codex-api-key
```
- Response:
```json
{ "codex-api-key": [ { "api-key": "sk-a", "base-url": "" } ] }
```
- PUT `/codex-api-key` — Replace the list
- Request:
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '[{"api-key":"sk-a"},{"api-key":"sk-b","base-url":"https://c.example.com"}]' \
http://localhost:8317/v0/management/codex-api-key
```
- Response:
```json
{ "status": "ok" }
```
- 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:
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"value":5}' \
http://localhost:8317/v0/management/request-retry
```
- Response:
```json
{ "status": "ok" }
```
### 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
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/allow-localhost-unauthenticated
```
- Response:
```json
{ "allow-localhost-unauthenticated": false }
```
- 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" }
```
### Claude API Keys (object array) ### Claude API KEY (object array)
- GET `/claude-api-key` — full list - GET `/claude-api-key` — List all
- PUT `/claude-api-key` — replace list - Request:
- PATCH `/claude-api-key` — update one item (by `index` or `match` API key) ```bash
- DELETE `/claude-api-key` — remove one item (`?api-key=` or `?index=`) curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/claude-api-key
```
Object shape: - Response:
```json ```json
{ { "claude-api-key": [ { "api-key": "sk-a", "base-url": "" } ] }
"api-key": "sk-...", ```
"base-url": "https://custom.example.com" // optional - PUT `/claude-api-key` — Replace the list
} - Request:
``` ```bash
curl -X PUT -H 'Content-Type: application/json' \
Examples: -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
```bash -d '[{"api-key":"sk-a"},{"api-key":"sk-b","base-url":"https://c.example.com"}]' \
# Replace list http://localhost:8317/v0/management/claude-api-key
curl -X PUT -H 'Content-Type: application/json' \ ```
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ - Response:
-d '[{"api-key":"sk-a"},{"api-key":"sk-b","base-url":"https://c.example.com"}]' \ ```json
http://localhost:8317/v0/management/claude-api-key { "status": "ok" }
```
# Patch by index - PATCH `/claude-api-key` — Modify one (by `index` or `match`)
curl -X PATCH -H 'Content-Type: application/json' \ - Request (by index):
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ ```bash
-d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com"}}' \ curl -X PATCH -H 'Content-Type: application/json' \
http://localhost:8317/v0/management/claude-api-key -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com"}}' \
# Patch by match (api-key) http://localhost:8317/v0/management/claude-api-key
curl -X PATCH -H 'Content-Type: application/json' \ ```
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ - Request (by match):
-d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":""}}' \ ```bash
http://localhost:8317/v0/management/claude-api-key curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
# Delete by api-key -d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":""}}' \
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?api-key=sk-b2' http://localhost:8317/v0/management/claude-api-key
``` ```
Response (GET): - Response:
```json ```json
{ { "status": "ok" }
"claude-api-key": [ ```
{ "api-key": "sk-a", "base-url": "" } - 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'
```
- Request (by index):
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?index=0'
```
- Response:
```json
{ "status": "ok" }
```
### 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
```
- Response:
```json
{ "openai-compatibility": [ { "name": "openrouter", "base-url": "https://openrouter.ai/api/v1", "api-keys": [], "models": [] } ] }
```
- PUT `/openai-compatibility` — Replace the list
- Request:
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-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
```
- 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' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-d '{"name":"openrouter","value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-keys":[],"models":[]}}' \
http://localhost:8317/v0/management/openai-compatibility
```
- 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'
```
- Response:
```json
{ "status": "ok" }
```
Object shape: ### Auth File Management
```json
{
"name": "openrouter",
"base-url": "https://openrouter.ai/api/v1",
"api-keys": ["sk-..."],
"models": [ {"name": "moonshotai/kimi-k2:free", "alias": "kimi-k2"} ]
}
```
Examples: Manage JSON token files under `auth-dir`: list, download, upload, delete.
```bash
# Replace list
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-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
# Patch by name - GET `/auth-files` — List
curl -X PATCH -H 'Content-Type: application/json' \ - Request:
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ ```bash
-d '{"name":"openrouter","value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-keys":[],"models":[]}}' \ curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/auth-files
http://localhost:8317/v0/management/openai-compatibility ```
# Delete by index
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?index=0'
```
Response (GET):
```json
{ "openai-compatibility": [ { "name": "openrouter", "base-url": "...", "api-keys": [], "models": [] } ] }
```
### Auth Files Management
List JSON token files under `auth-dir`, download/upload/delete.
- GET `/auth-files` — list
- 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.

120
MANAGEMENT_API_CN.md
View File

@@ -233,72 +233,60 @@
{ "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 http://localhost:8317/v0/management/codex-api-key
``` ```
- 响应： - 请求（按匹配）：
```json ```bash
{ "status": "ok" } curl -X PATCH -H 'Content-Type: application/json' \
``` -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
- DELETE `/codex-api-key` -d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":""}}' \
- 请求： http://localhost:8317/v0/management/codex-api-key
```bash ```
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?value=sk-proj-2' - 响应：
``` ```json
- 响应： { "status": "ok" }
```json ```
{ "status": "ok" } - DELETE `/codex-api-key` — 删除其中一个（`?api-key=` 或 `?index=`）
``` - 请求（按 api-key）：
```bash
### 开启请求日志 curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?api-key=sk-b2'
- 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 ```json
{ "request-log": true } { "status": "ok" }
``` ```
- 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
{ "status": "ok" }
```
### 请求重试次数 ### 请求重试次数
- GET `/request-retry` — 获取整数 - GET `/request-retry` — 获取整数