Update Agent
Partially update an agent — routing, model policy, budgets, guardrails.
status: "paused"refuses the agent’s traffic with503 agent_not_activeon/v1/ai, and JSON-RPC-32603on/v1/mcp.guardrail_webhook_urlis resolved and refused at write time through the SSRF chokepoint, and may not carry credentials in the URL (https://user:pass@host/) — a credential written into a URL is stored in plaintext and leaks into every log line that echoes it.
firewall_policy_id to a policy with action: "block" is what makes
the firewall refuse rather than warn — see Prompt firewall.
Requires the update capability on ai_gateway. See the control-plane overview for authentication, the {data, meta} envelope, pagination and error types.Authorizations
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
The AI agent UUID.
Body
Only the provided fields are changed. Every writable column on an agent appears here — this schema is what the typed SDKs are generated and reviewed against, so a field missing from it becomes a field missing from them (AIGW-161).
RENAMES the agent, which MOVES its data-plane URL: agent_url is computed from the slug rather than stored, so every caller pointed at the old URL gets a 404 from the moment this returns. The new URL is on this response — read it rather than reconstructing it.
Map of requested model → substituted model. Values must be STRINGS (the server validates with a string map) and at most 100 entries.
What happens once a budget is exhausted. fallback needs fallback_agent_id; without one it behaves as block.
block, warn, fallback AIGW-100 legacy alias for pii_response_mode (true -> detokenize, false -> redact). Still accepted; sending both with contradictory values is a 400.
What happens to the PROMPT before it leaves KnoxCall. Default tokenize. Set off only for an agent whose payload must reach the provider byte-for-byte (structured tool-use JSON, for example) — it means prompts are forwarded unscanned.
off, tokenize What happens to the provider's answer. Default detokenize.
redact, detokenize How many characters of a STREAMED answer are held back while a detector decides. Larger catches an entity split across more chunks; smaller is lower latency.
How a streamed answer is rewritten. holdback releases text behind a sliding window; buffer withholds the whole answer until it is complete; monitor REPORTS detections without rewriting, so the raw value reaches the client — an observability mode, not a redaction one.
holdback, buffer, monitor FinOps attribution labels (cost_center/team/project/…) echoed onto this agent's usage rows.
semantic additionally needs cache_embedding_model; without one the cache reports itself degraded and serves nothing.
off, exact, semantic Cosine floor for a semantic cache hit, 0–1. Lower means more hits, and more wrong ones. NOT nullable: the column is NOT NULL and the validator is non-nullable, so an explicit null is a 400.
0 <= x <= 1JSON Schema the answer is validated against.
block, retry, warn How this agent retries and spreads load (AIGW-42). An empty object — the default for every agent — means one attempt per route and fail-over to fallback_route_ids on 5xx only, which is the behaviour the gateway has always had.
Every field is clamped server-side. A request parked waiting to retry occupies an API worker, so max_attempts caps at 5, any single delay at 30s, a honoured Retry-After at 60s, and the total sleep for one request at 60s regardless of how the fields combine.
HTTPS endpoint your own scanner listens on (AIGW-45). Every prompt — and, in response/both mode, every response — is POSTed to it for a verdict before it moves.
What it receives is the REDACTED, post-tokenization body: the same bytes the provider would get, never a resolved provider credential and never your KnoxCall token. Shipping raw PHI to a third party to ask whether it contains PHI would be the leak the gateway exists to prevent.
The destination is resolved and refused at write time AND on every call — a private, loopback, link-local or cloud-metadata address is a 400, because DNS is not a promise.
Secret holding the HMAC-SHA256 key deliveries are signed with. The signature covers <timestamp>.<body> and travels in x-knox-guardrail-signature with the timestamp in x-knox-guardrail-timestamp, so a captured delivery is not replayable. Omit to send unsigned — the receiver then cannot prove the call came from KnoxCall.
Which directions are inspected. response and both evaluate the complete buffered response before it is sent, so an agent in those modes REFUSES a streaming request (400 guardrail_streaming_unsupported) rather than serving one past a control that could not run on it.
off, request, response, both How long to wait for a verdict. Clamped, because a request waiting on your scanner is holding one of the gateway's API workers.
100 <= x <= 10000What happens when the hook does not answer. Applies identically to EVERY non-answer — timeout, refused connection, refused destination, non-2xx, unparseable body, an action verb we do not recognise. Defaults to fail_open, which is the posture an agent already has with no hook at all.
A hook responds 200 with {"action":"allow"|"block"|"flag","reason":"…"}. block refuses the request with 400 guardrail_block and your reason in the message; flag serves it and records the outcome.
fail_open, fail_closed