> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents (v1)
> List, create, read, update, and archive AI Gateway agents over the public /v1 Management API.
# Agents
An **agent** belongs to a gateway and defines how one class of AI traffic is proxied: the upstream route, default model and model policy, budgets, streaming, and firewall / PII policies. Once created, an agent is served on the data plane at `/v1/ai/{slug}` — see [Execute AI Request](/api-reference/ai-gateway/execute) to send it traffic.
These endpoints are the public `/v1` control-plane equivalent of the dashboard agent pages. See the [control-plane overview](/api-reference/ai-gateway/control-plane-overview) for authentication, the response envelope, pagination, and error types.
`/v1` never exposes KnoxCall-managed system agents (for example the Workflows system agent). Reads, updates, token operations, and deletes against a system agent return `404 not_found`.
## The agent object
An agent is returned with its full configuration. The most commonly used fields:
| Field | Type | Description |
| --------------------------- | --------------------- | ------------------------------------------------------------------------------------ |
| `id` | string (uuid) | Agent identifier. |
| `gateway_id` | string (uuid) | Parent gateway. |
| `name` | string | Display name. |
| `slug` | string | URL-safe handle, unique per tenant. The agent is served at `/v1/ai/{slug}`. |
| `description` | string \| null | Free-text description. |
| `primary_route_id` | string (uuid) \| null | Upstream route the agent proxies to. |
| `default_model` | string \| null | Default model when the request does not specify one. Drives the phantom-token scope. |
| `model_allowlist` | string\[] | Allowed models (empty = no allowlist restriction). |
| `model_denylist` | string\[] | Denied models. |
| `budget_daily_usd` | string \| null | Daily spend cap in USD (numeric, returned as a string). |
| `budget_monthly_usd` | string \| null | Monthly spend cap in USD. |
| `streaming_enabled` | boolean | Whether SSE streaming is allowed. Defaults to `true`. |
| `firewall_policy_id` | string (uuid) \| null | Attached prompt-injection firewall policy. |
| `pii_redact_policy_id` | string (uuid) \| null | Attached PII redaction policy. |
| `tool_allowlist` | string\[] | Tool names permitted through the agent. |
| `status` | string | One of `active`, `paused`, `archived`. |
| `created_at` / `updated_at` | string (ISO 8601) | Timestamps. |
The object also includes the remaining agent settings (`fallback_route_ids`, `model_rewrite`, `budget_overage_action`, `pii_detokenize_response`, `pii_streaming_holdback_chars`, `cache_mode`, `output_schema`, `output_validation_action`, and others) at their configured or default values.
## List agents
```http theme={"dark"}
GET /v1/ai-gateway/gateways/{gatewayId}/agents
```
Returns the agents in a gateway, paginated (`page`, `per_page`). Requires the `read` capability. Returns `404 not_found` if the gateway does not belong to your tenant.
```bash cURL theme={"dark"}
curl "https://api.knoxcall.com/v1/ai-gateway/gateways/3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10/agents" \
-H "Authorization: Bearer tk_live_abc123..."
```
```python Python theme={"dark"}
import requests
gw = "3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10"
resp = requests.get(
f"https://api.knoxcall.com/v1/ai-gateway/gateways/{gw}/agents",
headers={"Authorization": "Bearer tk_live_abc123..."},
)
agents = resp.json()["data"]
```
The response is a paginated list of agent objects wrapped in `{ data, meta }`.
## Create an agent
```http theme={"dark"}
POST /v1/ai-gateway/gateways/{gatewayId}/agents
```
Requires the `write` capability.
**Request body**
| Field | Type | Description |
| ---------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `name` | string | **Required.** Display name. |
| `slug` | string | **Required.** 2–64 lowercase alphanumerics/hyphens; unique per tenant. Becomes the data-plane path `/v1/ai/{slug}`. |
| `description` | string | Optional. |
| `primary_route_id` | string (uuid) | Optional. Upstream route to proxy to. Must belong to your tenant. |
| `default_model` | string | Optional default model. |
| `model_allowlist` | string\[] | Optional allowed-model list. |
| `model_denylist` | string\[] | Optional denied-model list. |
| `budget_daily_usd` | number | Optional daily spend cap. |
| `budget_monthly_usd` | number | Optional monthly spend cap. |
| `streaming_enabled` | boolean | Optional. Defaults to `true`. |
| `firewall_policy_id` | string (uuid) | Optional firewall policy. Must belong to your tenant. |
| `pii_redact_policy_id` | string (uuid) | Optional PII redaction policy. Must belong to your tenant. |
`primary_route_id`, `firewall_policy_id`, and `pii_redact_policy_id` must reference resources owned by your tenant. A reference to another tenant's resource (or a malformed id) returns `400 invalid_reference`.
```bash cURL theme={"dark"}
curl -X POST https://api.knoxcall.com/v1/ai-gateway/gateways/3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10/agents \
-H "Authorization: Bearer tk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"name": "Support Bot",
"slug": "support-bot",
"description": "Handles tier-1 support questions",
"default_model": "claude-sonnet-4-6",
"budget_daily_usd": 10.00,
"budget_monthly_usd": 200.00,
"streaming_enabled": true
}'
```
```python Python theme={"dark"}
import requests
gw = "3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10"
resp = requests.post(
f"https://api.knoxcall.com/v1/ai-gateway/gateways/{gw}/agents",
headers={"Authorization": "Bearer tk_live_abc123..."},
json={
"name": "Support Bot",
"slug": "support-bot",
"default_model": "claude-sonnet-4-6",
"budget_daily_usd": 10.00,
"budget_monthly_usd": 200.00,
},
)
agent = resp.json()["data"]
```
**Response** — the created agent wrapped in `{ data, meta }`:
```json theme={"dark"}
{
"data": {
"id": "7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f",
"tenant_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
"gateway_id": "3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10",
"name": "Support Bot",
"slug": "support-bot",
"description": "Handles tier-1 support questions",
"primary_route_id": null,
"fallback_route_ids": [],
"model_allowlist": [],
"model_denylist": [],
"default_model": "claude-sonnet-4-6",
"model_rewrite": {},
"budget_daily_usd": "10.00",
"budget_monthly_usd": "200.00",
"budget_per_call_max_tokens": null,
"budget_overage_action": "block",
"pii_redact_policy_id": null,
"pii_detokenize_response": true,
"pii_streaming_holdback_chars": 96,
"cache_mode": "off",
"streaming_enabled": true,
"firewall_policy_id": null,
"tool_allowlist": [],
"output_schema": null,
"output_validation_action": "warn",
"status": "active",
"paused_reason": null,
"created_at": "2026-07-06T12:00:00.000Z",
"updated_at": "2026-07-06T12:00:00.000Z",
"created_by": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e"
},
"meta": {
"request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
}
}
```
Missing `name` or `slug` returns `400 validation`; an invalid slug returns `422 invalid_slug`; a duplicate slug returns `409 conflict`.
## Get an agent
```http theme={"dark"}
GET /v1/ai-gateway/agents/{agentId}
```
Returns a single agent. Requires the `read` capability. Returns `404 not_found` if the agent does not belong to your tenant or is a system agent.
```bash theme={"dark"}
curl https://api.knoxcall.com/v1/ai-gateway/agents/7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f \
-H "Authorization: Bearer tk_live_abc123..."
```
## Update an agent
```http theme={"dark"}
PATCH /v1/ai-gateway/agents/{agentId}
```
Partial update — send only the fields you want to change. Requires the `write` capability. The `slug` cannot be changed.
**Updatable fields**
`name`, `description`, `primary_route_id`, `default_model`, `model_allowlist`, `model_denylist`, `budget_daily_usd`, `budget_monthly_usd`, `streaming_enabled`, `firewall_policy_id`, `pii_redact_policy_id`, `pii_detokenize_response`, `tool_allowlist`.
Reference fields (`primary_route_id`, `firewall_policy_id`, `pii_redact_policy_id`) are tenant-ownership checked exactly as on create.
```bash theme={"dark"}
curl -X PATCH https://api.knoxcall.com/v1/ai-gateway/agents/7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f \
-H "Authorization: Bearer tk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"default_model": "claude-opus-4-6",
"budget_daily_usd": 25.00,
"model_denylist": ["gpt-4o"]
}'
```
The response is the updated agent wrapped in `{ data, meta }`.
## Archive an agent
```http theme={"dark"}
DELETE /v1/ai-gateway/agents/{agentId}
```
Soft-deletes (archives) the agent and stops it serving data-plane traffic. Requires the `write` capability.
```bash theme={"dark"}
curl -X DELETE https://api.knoxcall.com/v1/ai-gateway/agents/7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f \
-H "Authorization: Bearer tk_live_abc123..."
```
**Response**
```json theme={"dark"}
{
"data": {
"id": "7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f",
"status": "archived"
},
"meta": {
"request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
}
}
```