API reference

Control Tower serves three APIs on one port:

• the gateway, which agents call with their own key;
• the admin API, which the console uses and you can script;
• health and metrics endpoints for your platform.

#Authentication

export CT=http://localhost:4000
export ADMIN="Authorization: Bearer $CT_ADMIN_KEY"
curl -s $CT/admin/api/keys -H "$ADMIN"

Errors are JSON: {"error": {"code": "…", "message": "…"}} (the gateway uses the envelope of the API the client speaks). An unexpected failure is 500 internal_error, with a message that gives the request id to look up in the server's log. Model, HTTP API and A2A responses carry x-ct-flight-id; MCP responses, /v1/models and /v1/messages/count_tokens don't. Every code is listed in Troubleshooting.

#Gateway

The OpenAI routes also answer without /v1. Requests may carry x-ct-tags, x-ct-customer, x-ct-region and x-ct-cache (tags and customers, caching), a W3C traceparent (Control Tower's spans join the agent's trace), x-ct-delegation (agents calling agents) and x-ct-session.

Requests held for approval are retried with x-ct-approval: <ticket> (MCP also takes params._meta.ct_approval, A2A params.metadata.ct_approval); the HTTP gateway also returns the ticket in an x-ct-approval-ticket header. On model calls, x-ct-session (or the request's user or metadata.user_id) names the agent's session: a duplicate retry within 5 seconds with the same ticket and session goes through on the same approval instead of asking for a new one. See Approvals.

#Admin API

All paths are under /admin/api. Approvers and viewers may read any of them (except /users and /audit); only admins change anything, except that approvers decide approvals and everyone may change their own password.

#Session

#Providers, models, aliases

#Keys and budgets

#Tool servers

#Policy and approvals

#Exports

#Guardrail services

#Alerts

#Traffic, spend and the map

#Setup helpers

#Key and model management API

With the admin key: POST /key/generate, GET /key/info, POST /key/update, GET /key/list, POST /key/delete, POST /key/block, POST /key/unblock, POST /key/regenerate (also /key/:key/regenerate), GET /model/info (also /v1/model/info), POST /model/new, POST /model/delete. See Keys.

POST /model/new takes one entry in the form of a config file's model_list: {model_name, params: {model: "<provider>/<model>", api_key?, api_base?, …}, model_info?}. Credentials it leaves out are read from the usual environment variables; it reuses a provider with the same endpoint and credentials, and returns the new model's model_id. POST /model/delete takes {id}.

#SCIM 2.0

/scim/v2/Users, /scim/v2/Groups, /scim/v2/ServiceProviderConfig, /scim/v2/ResourceTypes, /scim/v2/Schemas, with an identity provider's SCIM token as a bearer token (Enterprise). See SCIM provisioning.

#Health and metrics