Skip to main content
PATCH
Update an AI gateway
Partial update. Omitted fields are left as they are. Setting status to paused stops the gateway’s traffic: an agent under a paused gateway is refused with 503 gateway_not_active on /v1/ai, and with JSON-RPC -32603 on /v1/mcp. That has been true on both planes since 2026-08-27 — the MCP plane previously kept serving.
The dashboard twin. The same operation exists on the admin host as PATCH /admin/ai-gateway/{gatewayId}, session-authenticated with an X-Tenant-ID header and an owner/admin role. That is what the dashboard itself calls. Prefer the /v1 operation above for anything you write: it is the surface the five SDKs, the Postman collection and this spec cover.

Authorizations

Authorization
string
header
required

OAuth 2.1 authentication — recommended for new integrations. Access tokens (kc_ prefix) are minted at the root-host token endpoint https://api.knoxcall.com/oauth/token and passed as Authorization: Bearer <access_token>. Public clients must use PKCE with the authorization_code grant; confidential clients may use client_credentials. The first-party SDKs and the knoxcall login CLI handle token minting, caching, refresh, and DPoP for you.

Path Parameters

id
string<uuid>
required

The AI gateway UUID.

Body

application/json

Only the provided fields are changed.

name
string
description
string | null
budget_daily_usd
number | null
budget_monthly_usd
number | null
budget_overage_action
enum<string>

What happens when the gateway's cap is spent (AIGW-150). Defaults to block. No fallback — that action swaps an agent's route and model, which a gateway does not have.

Available options:
block,
warn
geo_velocity_action
enum<string>
Available options:
off,
warn,
block
model_aliases
object

Model aliases shared by every agent under this gateway (AIGW-42): {alias: real_model_id}. Name fast once here rather than in every call site of every service.

Resolved BEFORE the per-agent model policy, so an alias target is still subject to that agent's allow/deny list and model_rewrite — an alias is a naming convenience, never a way around a control. A chain resolves with a hop limit; a cycle degrades to the original model rather than looping. Max 100 entries.

Response

The updated gateway.

data
object

An AI gateway — the top-level container that agents are created under.

meta
object

Metadata included with every API response.