chuan/CLIProxyAPI
1
0
Fork 0
mirror of https://github.com/router-for-me/CLIProxyAPI.git synced 2026-02-19 12:50: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

607
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:
```bash
Example (set true): curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/debug
```bash ```
curl -X PUT \ - Response:
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ ```json
-H 'Content-Type: application/json' \ { "debug": false }
```
- PUT/PATCH `/debug` — Set debug (boolean)
- Request:
```bash
curl -X PUT -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
-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 ```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/proxy-url
Example (set): ```
```bash - Response:
curl -X PATCH -H 'Content-Type: application/json' \ ```json
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ { "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/"}' \ -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):
```json ```bash
{ "status": "ok" } 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 ### 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:
```bash ```json
curl -X PUT -H 'Content-Type: application/json' \ { "switch-project": true }
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ ```
- 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}' \ -d '{"value":false}' \
http://localhost:8317/v0/management/quota-exceeded/switch-project http://localhost:8317/v0/management/quota-exceeded/switch-project
``` ```
Response: - Response:
```json ```json
{ "status": "ok" } { "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
{ "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:
```bash ```json
# Replace list { "api-keys": ["k1","k2","k3"] }
curl -X PUT -H 'Content-Type: application/json' \ ```
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ - 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"]' \ -d '["k1","k2","k3"]' \
http://localhost:8317/v0/management/api-keys http://localhost:8317/v0/management/api-keys
```
# Patch: replace k2 -> k2b - Response:
curl -X PATCH -H 'Content-Type: application/json' \ ```json
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ { "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"}' \ -d '{"old":"k2","new":"k2b"}' \
http://localhost:8317/v0/management/api-keys 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:
```json
{ "status": "ok" }
```
# Delete by value ### Gemini API Key (Generative Language)
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` - 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
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
# Replace list
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"}]' \ -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:
curl -X PATCH -H 'Content-Type: application/json' \ ```json
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ { "status": "ok" }
```
- PATCH `/claude-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"}}' \ -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):
curl -X PATCH -H 'Content-Type: application/json' \ ```bash
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ curl -X PATCH -H 'Content-Type: application/json' \
-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:
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?api-key=sk-b2' ```json
``` { "status": "ok" }
Response (GET): ```
```json - DELETE `/claude-api-key` — Delete one (`?api-key=` or `?index=`)
{ - Request (by api-key):
"claude-api-key": [ ```bash
{ "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'
] ```
} - 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
```
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"} ] ```bash
} curl -X PUT -H 'Content-Type: application/json' \
``` -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
Examples:
```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"}]}]' \ -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:
curl -X PATCH -H 'Content-Type: application/json' \ ```json
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \ { "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":[]}}' \ -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
```
- 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" }
```
# Delete by index ### Auth File Management
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 Manage JSON token files under `auth-dir`: list, download, upload, delete.
List JSON token files under `auth-dir`, download/upload/delete. - GET `/auth-files` — List
- Request:
- GET `/auth-files` — list ```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