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 to send it traffic. These endpoints are the public /v1 control-plane equivalent of the dashboard agent pages. See the 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

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.

curl "https://api.knoxcall.com/v1/ai-gateway/gateways/3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10/agents" \
  -H "Authorization: Bearer tk_live_abc123..."

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

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.

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
  }'

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 }:

{
  "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

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.

curl https://api.knoxcall.com/v1/ai-gateway/agents/7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f \
  -H "Authorization: Bearer tk_live_abc123..."

Update an agent

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.

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

DELETE /v1/ai-gateway/agents/{agentId}

Soft-deletes (archives) the agent and stops it serving data-plane traffic. Requires the write capability.

curl -X DELETE https://api.knoxcall.com/v1/ai-gateway/agents/7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f \
  -H "Authorization: Bearer tk_live_abc123..."

Response

{
  "data": {
    "id": "7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f",
    "status": "archived"
  },
  "meta": {
    "request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
  }
}

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Agents (v1)

Agents

The agent object

List agents

Create an agent

Get an agent

Update an agent

Archive an agent

​Agents

​The agent object

​List agents

​Create an agent

​Get an agent

​Update an agent

​Archive an agent

Agents

The agent object

List agents

Create an agent

Get an agent

Update an agent

Archive an agent