Management API - GPT-Load

The management UI uses these endpoints itself. Use them directly when scripting Group and key management.

Authentication §

Protected endpoints under /api use Bearer authentication:

Request header

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 redacted 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.

Authentication failure lockout §

Do not repeatedly retry an invalid key from a script

After five failed management authentications from the same direct peer address within 30 minutes, that peer is locked for 30 minutes. While locked, the API returns 429 and Retry-After; a successful authentication with the correct AUTH_KEY clears the failure count.

Response Convention §

Responses use one structure; code distinguishes success from failure:

Success.

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

Failure

{
  "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.

Write preconditions §

Request header	Required by	Contract
Idempotency-Key	`POST /api/groups` `POST /api/groups/{group_id}/credentials/import` `POST /api/groups/{group_id}/credentials/connect` `POST /api/groups/{group_id}/credentials/{credential_id}/reset-credits/consume` `POST /api/access-keys` `POST /api/access-keys/{id}/rotate`	Exactly one value is required, formatted as a canonical lowercase UUID v4; reuse it when retrying the same logical operation
If-Match	`PUT /api/settings`	Read `ETag` from the settings response and send it back unchanged; on conflict, read the latest settings and merge again.

JSON request bodies use a strict contract

Endpoints that declare a JSON body accept exactly one object. Unknown fields, duplicate fields, and a trailing second JSON value are rejected. Parameterless operations using the empty-object contract accept only an empty body or {}.

Main resources §

Path	Purpose
/api/auth/session	Confirm the current Bearer principal type
/api/home	Home summary, statistics, and subscription-account overview
/api/health	Runtime health
/api/logs	Request-log list and detail
/api/usage	Usage and cost statistics
/api/settings	Global runtime settings
/api/system	Deployment information and release update check
/api/route/inspect	Read-only route inspection
/api/channels	Channel descriptors, fields, and capabilities
/api/models	Project model list and upstream model discovery
/api/model-prices	Query, sync, update, reset, and delete model prices
/api/groups	Group listing, creation, details, settings, models, and deletion
/api/groups/{group_id}/credentials	Credential management, includes batch import, viewing actual values, downloading
/api/credential-stages	Subscription credential authorization, import, polling, and staged state
/api/access-keys	AccessKey, including quota and view real value

Pin a version in automation

This table records stable resource boundaries without copying every evolving endpoint field. The complete route contract for the current version is defined by internal/control/http_routes.go in the code. Automation should pin an exact GPT-Load version and regression-test real calls after upgrades.

A few examples §

List all Groups.

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

Check health status

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

Route checking: which path this request will take

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.

Import credentials with an idempotency key

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 expose to the public network

The management API can read the real values of all channel credentials (endpoints such as /reveal do this). A leaked AUTH_KEY exposes every upstream key.
The source must be restricted; see Security and production for configuration.

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.