AI Gateway control plane

The AI Gateway control plane lets you create and manage gateways, agents, and phantom tokens — and read cost/usage — over the public Management API at api.knoxcall.com/v1. These are the same resources you configure in the dashboard, exposed as REST endpoints so you can provision them from code, CI, or the KnoxCall SDKs.

This is the control plane — it configures the gateway. To actually send AI traffic through an agent, call the data plane described in Execute AI Request. The data plane lives on your tenant proxy subdomain and authenticates with a phantom token, not an API key.

The dashboard/admin surface documented on the List Gateways, Create Agent, and Mint Phantom Token pages performs the same operations from a session-authenticated /admin/ai-gateway host. The /v1/ai-gateway endpoints below are the public equivalent and are what the KnoxCall SDKs call.

Base URL

All control-plane endpoints are served under /v1/ai-gateway.

Production

https://api.knoxcall.com/v1/ai-gateway

Authenticate with a live-mode OAuth token (kc_live_…) or a legacy production key (tk_live_… / AKE…).

Sandbox

https://sandbox.knoxcall.com/v1/ai-gateway

Authenticate with a test-mode OAuth token (kc_test_…) or a legacy test key (tk_test_…).

Authentication

Authenticate exactly as you do for the rest of the Management API. The recommended path is the KnoxCall SDK — which mints, caches, and refreshes short-lived OAuth 2.1 access tokens for you — or a token you mint yourself; long-lived API keys remain supported as the legacy alternative. See the Authentication guide for the full picture.

Method	Header	Notes
OAuth 2.1 (use this)	`Authorization: Bearer kc_live_…`	Short-lived token minted via `POST /oauth/token`; tenant is resolved from the token. The SDKs handle minting and refresh for you, and every example on these pages uses it.
API key (legacy)	`Authorization: Bearer tk_live_…`	Tenant is resolved from the key. Long-lived: prefer OAuth for anything new, and reach for a key only where you cannot run a mint step.

The x-api-key header is also accepted on the Management API for backwards compatibility, but it is not shown in these examples and new integrations should not use it. Authorization: Bearer is the one header every credential family works with.Neither of these is the data-plane credential. /v1/ai/{slug} takes a phantom token (kp_…) — a different credential family entirely. See Execute AI Request.

The curl examples on the AI Gateway reference pages authenticate with $TOKEN, a 1-hour OAuth access token minted once:

# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

Required scope

Every endpoint is gated on the ai_gateway scope. The action determines the capability your key must hold:

Operation	HTTP	Capability on `ai_gateway`
List / read a gateway, agent, token, or usage	`GET`	`read`
Create / update / delete a gateway or agent	`POST` / `PATCH` / `DELETE`	`write`
Mint a phantom token	`POST …/tokens`	`mint`

A key that lacks the required capability receives 403 with error type forbidden. No other scope grants access to these endpoints.

Response envelope

Every response uses the standard Management API envelope. Single resource — { data, meta }:

{
  "data": {
    "id": "3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10",
    "name": "Production"
  },
  "meta": {
    "request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
  }
}

List — { data: [...], meta } with pagination fields:

{
  "data": [ /* … */ ],
  "meta": {
    "total": 3,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
  }
}

Error — { error }:

{
  "error": {
    "type": "not_found",
    "message": "Gateway not found.",
    "request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
  }
}

Pagination

List endpoints accept page and per_page query parameters and slice the full tenant result set.

Parameter	Default	Max
`page`	`1`	—
`per_page`	`20`	`100`

The meta object returns total, page, per_page, and total_pages.

Sandbox and phantom-token environments

Gateways and agents are not environment-partitioned — the same gateway and agent objects are visible whether you authenticate with a live or a test credential. The live/test distinction lives in the phantom token: a token minted with a test-mode credential is a test-environment token (kp_test_…), and a token minted with a live credential is a live token (kp_live_…). There is no environment parameter on any request — the server derives it from the credential you used to mint. Note the two prefixes are different credential families and are not interchangeable: kc_ is an OAuth 2.1 access token for this Management API, kp_ is a phantom token for the data plane (/v1/ai/{slug}). Presenting one where the other is expected is refused, not translated.

Idempotency

Mutating requests (POST, PATCH, DELETE) honour the router-level X-Idempotency-Key header. Send the same key to retry a request safely without creating duplicates.

Errors

In addition to the shared authentication errors, the control plane returns:

Type	HTTP	When
`validation`	400	A required field (e.g. `name`, `slug`, or `dpop_jkt` when `dpop_required`) is missing.
`invalid_reference`	400	`primary_route_id`, `firewall_policy_id`, or `pii_redact_policy_id` does not reference a resource owned by your tenant.
`invalid_id`	400	A path or query identifier is not a valid UUID.
`forbidden`	403	The key lacks the required `ai_gateway` capability.
`not_found`	404	The gateway, agent, or token does not exist for this tenant.
`conflict`	409	A gateway or agent with that slug already exists for this tenant.
`invalid_slug`	422	The slug is not 2–64 lowercase alphanumerics/hyphens starting and ending with an alphanumeric.
`internal_error`	500	Unexpected server error — contact support with the `request_id`.

Endpoint index

Method & path	Purpose
`GET /v1/ai-gateway/gateways`	List gateways
`POST /v1/ai-gateway/gateways`	Create a gateway
`GET /v1/ai-gateway/gateways/{id}`	Get a gateway
`PATCH /v1/ai-gateway/gateways/{id}`	Update a gateway
`DELETE /v1/ai-gateway/gateways/{id}`	Archive a gateway
`GET /v1/ai-gateway/gateways/{gatewayId}/agents`	List agents
`POST /v1/ai-gateway/gateways/{gatewayId}/agents`	Create an agent
`GET /v1/ai-gateway/agents/{agentId}`	Get an agent
`PATCH /v1/ai-gateway/agents/{agentId}`	Update an agent
`DELETE /v1/ai-gateway/agents/{agentId}`	Archive an agent
`GET /v1/ai-gateway/agents/{agentId}/tokens`	List tokens
`POST /v1/ai-gateway/agents/{agentId}/tokens`	Mint a token
`DELETE /v1/ai-gateway/agents/{agentId}/tokens/{tokenId}`	Revoke a token
`GET /v1/ai-gateway/usage`	Usage & cost

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

Control Plane (v1)

AI Gateway control plane

Base URL

Production

Sandbox

Authentication

Required scope

Response envelope

Sandbox and phantom-token environments

Idempotency

Errors

Endpoint index

​AI Gateway control plane

​Base URL

Production

Sandbox

​Authentication

​Required scope

​Response envelope

​Pagination

​Sandbox and phantom-token environments

​Idempotency

​Errors

​Endpoint index

AI Gateway control plane

Base URL

Authentication

Required scope

Response envelope

Pagination

Sandbox and phantom-token environments

Idempotency

Errors

Endpoint index