Management API

Authentication §

Protected endpoints under /api use Bearer authentication:

Authorization: Bearer  your AUTH_KEY or AccessKey 

• AUTH_KEY — grants administrative access to read and write configuration and perform sensitive operations such as Reveal
• AccessKey — may only read its scoped home page, models, usage, and request logs; it cannot change configuration or view upstream credentials

Use AUTH_KEY for write operations and route inspection.

An AccessKey currently has read access only to /api/auth/session, /api/home, /api/home/statistics, /api/models, /api/usage, /api/logs, and /api/logs/{request_id}; other management routes return 403.

GET /api/logs/{request_id} returns request_body when recorded, including state, original_bytes, and body. Administrators and sessions using the key that sent the request can read it. The original body is not a redacted summary and is not hidden merely because the session uses an access key. record_request_body is a per-key boolean setting, defaulting to false, not a global runtime setting.

Authentication failure lockout §

Response Convention §

Responses use one structure; code distinguishes success from failure:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

{
  "code":  "Error identifier" ,
  "message":  "Human-readable instructions" 
}

On success, code is the number 0; on failure, it is a string identifier—check the type.

data is optional in both success and error responses. It is omitted when there is no data, so do not assume it always exists or is always an object. message is localized according to Accept-Language.

Programs should evaluate code and structured data, not parse localized message. See Errors and recovery for the complete catalog and recovery guidance.

When a credential test completes, the management API can return code=0 even if the upstream rejects the request. Read data.outcome and data.reason to determine the test result. The optional data.error_detail contains redacted diagnostic text and may be truncated or omitted. Use it for troubleshooting, not programmatic decisions.

Write preconditions §

PUT /api/settings saves the submitted settings directly without requiring If-Match. For the same setting, the last successful save wins.

Main resources §

POST /api/settings/request-redaction/preview requires the administrator AUTH_KEY. It accepts a rules array and a text string and returns match_count and segments. It only checks the submitted draft; it does not save settings or samples or call upstream services.

Preview request bodies are limited to 1 MiB, samples to 64 KiB in UTF-8, and merged matches to 200 segments. Oversized request bodies return 413 REQUEST_TOO_LARGE. Invalid rules or text, or too many matches, return 400 VALIDATION_FAILED. Encrypted segments return rule and original-text information without generating real ciphertext.

A few examples §

curl http://127.0.0.1:3001/api/groups \
  -H "Authorization: Bearer $AUTH_KEY"

curl http://127.0.0.1:3001/api/health \
  -H "Authorization: Bearer $AUTH_KEY"

curl -X POST http://127.0.0.1:3001/api/route/inspect \
  -H "Authorization: Bearer $AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"protocol":"openai-completions","external_model":"gpt-4o","access_key_id":1}'

access_key_id is the numeric ID of the AccessKey in the management UI. Route inspection only evaluates candidates under the current configuration; it does not send a real upstream request.

curl -X POST http://127.0.0.1:3001/api/groups/1/credentials/import \
  -H "Authorization: Bearer $AUTH_KEY" \
  -H "Idempotency-Key: 7f6a7f86-3f58-4ae3-a1a1-46d3b8d17b71" \
  -H "Content-Type: application/json" \
  -d '{"credentials":"sk-example"}'

Notes §

• Do not hardcode AUTH_KEY in the script — Use environment variables or a secrets manager.
• Interfaces will adjust with versions — Re-run validation after upgrading an automation script.
• Do not change an idempotency key on your own — reuse the original value when the outcome is unknown; generate a new value for a new logical operation.