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 API-key-authenticated 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, API-key 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

Use a production key (tk_live_… or AKE…).

Sandbox

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

Use a test key (tk_test_…).

Authentication

Authenticate exactly as you do for the rest of the Management API — either a long-lived API key or an OAuth 2.1 access token. See the Authentication guide for the full picture.

Method	Header	Notes
API key	`Authorization: Bearer tk_live_…` or `x-api-key: tk_live_…`	Tenant is resolved from the key.
OAuth 2.1	`Authorization: Bearer kc_live_…` + `X-Tenant-ID: <tenant>`	Short-lived token minted via `POST /oauth/token`; the SDKs send `X-Tenant-ID` for you.

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 key. The live/test distinction lives in the phantom token: a token minted with a test key is a test-environment token (kc_test_…), and a token minted with a live key is a live token (kc_live_…). There is no environment parameter on any request — the server derives it from the key you used to mint.

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

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