Admin API

Reload configuration, inspect status, manage key state, test credentials, and read route traces.

Authentication

Admin routes use bearer authentication when server.admin.require_auth is true. The token is loaded from the environment variable configured by server.auth_token_env.

curl

curl http://127.0.0.1:8787/admin/status \
  -H "Authorization: Bearer $MODELMUX_AUTH_TOKEN"

Endpoint reference

Method	Path	Purpose
`POST`	`/admin/reload`	Reload configuration without restarting the process.
`POST`	`/admin/keys/{id}/enable`	Enable a key and update config/runtime state.
`POST`	`/admin/keys/{id}/disable`	Disable a key and update config/runtime state.
`POST`	`/admin/keys/{id}/test`	Test provider connectivity using one key.
`GET`	`/admin/status`	Read a summary of providers, models, keys, and server state.
`GET`	`/admin/traces/{id}`	Read a stored AI route trace when tracing is enabled.

Reload configuration

curl

curl -X POST http://127.0.0.1:8787/admin/reload \
  -H "Authorization: Bearer $MODELMUX_AUTH_TOKEN"

Validate the file before reload. A reload replaces the active routing configuration without requiring a full process restart.

Enable, disable, and test keys

curl

curl -X POST http://127.0.0.1:8787/admin/keys/provider-a-primary/disable \
  -H "Authorization: Bearer $MODELMUX_AUTH_TOKEN"

curl -X POST http://127.0.0.1:8787/admin/keys/provider-a-primary/enable \
  -H "Authorization: Bearer $MODELMUX_AUTH_TOKEN"

curl -X POST http://127.0.0.1:8787/admin/keys/provider-a-primary/test \
  -H "Authorization: Bearer $MODELMUX_AUTH_TOKEN"

Disable a credential before maintenance, revocation, or provider troubleshooting. Testing a key makes an upstream call and may consume a small amount of provider capacity.

Read server status

curl

curl http://127.0.0.1:8787/admin/status \
  -H "Authorization: Bearer $MODELMUX_AUTH_TOKEN"

The status endpoint provides an operational summary. Treat its response as sensitive because it can reveal configured resource names and key state.

Read route traces

curl

curl http://127.0.0.1:8787/admin/traces/<trace-id> \
  -H "Authorization: Bearer $MODELMUX_AUTH_TOKEN"

Trace records are available when AI route tracing is enabled and the trace has been stored. The response header X-ModelMux-Route-Trace-ID identifies the relevant trace.

Exposure guidance

Do not rely on localhost detection behind a proxy

Reverse-proxied requests can appear to originate locally. Keep admin authentication enabled and restrict these routes at the reverse proxy or network layer.