Partial update. Omitted fields are left as they are. This is where most of an
agent’s configuration is set: everything beyond the handful of fields create
accepts is applied here.Two changes have effects worth knowing before you make them:
status: "paused" refuses the agent’s traffic with 503 agent_not_active
on /v1/ai, and JSON-RPC -32603 on /v1/mcp.
guardrail_webhook_url is 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.
Setting 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
OAuth2BearerAuthApiKeyAuth
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 agent UUID.
Body
application/json
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).
name
string
slug
string
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.
description
string | null
primary_route_id
string<uuid> | null
fallback_route_ids
string<uuid>[]
default_model
string | null
model_allowlist
string[]
model_denylist
string[]
model_rewrite
object
Map of requested model → substituted model. Values must be STRINGS (the server validates with a string map) and at most 100 entries.
Show child attributes
budget_daily_usd
number | null
budget_monthly_usd
number | null
budget_per_call_max_tokens
integer | null
budget_overage_action
enum<string>
What happens once a budget is exhausted. fallback needs fallback_agent_id; without one it behaves as block.
Available options:
block,
warn,
fallback
fallback_agent_id
string<uuid> | null
streaming_enabled
boolean
firewall_policy_id
string<uuid> | null
pii_redact_policy_id
string<uuid> | null
pii_detokenize_response
boolean
deprecated
AIGW-100 legacy alias for pii_response_mode (true -> detokenize, false -> redact). Still accepted; sending both with contradictory values is a 400.
pii_request_mode
enum<string>
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.
Available options:
off,
tokenize
pii_response_mode
enum<string>
What happens to the provider's answer. Default detokenize.
Available options:
redact,
detokenize
pii_streaming_holdback_chars
integer
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.
pii_streaming_mode
enum<string>
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.
Available options:
holdback,
buffer,
monitor
tags
object
FinOps attribution labels (cost_center/team/project/…) echoed onto this agent's usage rows.
cache_mode
enum<string>
semantic additionally needs cache_embedding_model; without one the cache reports itself degraded and serves nothing.
Available options:
off,
exact,
semantic
cache_ttl_seconds
integer
cache_similarity_threshold
number
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.
Required range: 0 <= x <= 1
cache_embedding_model
string | null
tool_allowlist
string[]
output_schema
object | null
JSON Schema the answer is validated against.
output_validation_action
enum<string>
Available options:
block,
retry,
warn
data_residency_region
string | null
cmek_key_id
string<uuid> | null
routing_policy
object
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.
Show child attributes
guardrail_webhook_url
string<uri> | null
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.
guardrail_webhook_secret_id
string<uuid> | null
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.
guardrail_webhook_mode
enum<string>
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.
Available options:
off,
request,
response,
both
guardrail_webhook_timeout_ms
integer
How long to wait for a verdict. Clamped, because a request waiting on your scanner is holding one of the gateway's API workers.
Required range: 100 <= x <= 10000
guardrail_webhook_failure_action
enum<string>
What 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.
Available options:
fail_open,
fail_closed
Response
The updated agent.
data
object
An agent under a gateway — the addressable unit an AI SDK points at.
{"docsConfig":{"theme":"luma","$schema":"https://mintlify.com/docs.json","name":"KnoxCall Docs","colors":{"primary":"#18181B","light":"#A1A1AA","dark":"#09090B"},"logo":{"light":"https://mintcdn.com/knoxcall/Hani9qeqybFGCQd1/logo/light.svg?fit=max\u0026auto=format\u0026n=Hani9qeqybFGCQd1\u0026q=85\u0026s=b6279c9a774c9ff9c8a87d6ac0065b14","dark":"https://mintcdn.com/knoxcall/Hani9qeqybFGCQd1/logo/dark.svg?fit=max\u0026auto=format\u0026n=Hani9qeqybFGCQd1\u0026q=85\u0026s=1e0163bf9bf7997f45842652ecdf4a96"},"favicon":"https://mintcdn.com/knoxcall/Hani9qeqybFGCQd1/favicon.svg?fit=max\u0026auto=format\u0026n=Hani9qeqybFGCQd1\u0026q=85\u0026s=7902c6a426671befdf8f7c01aacae604","api":{"openapi":"api-reference/openapi.yaml"},"appearance":{"default":"dark","strict":false},"navbar":{"links":[{"href":"https://app.knoxcall.com","label":"Dashboard"}],"primary":{"type":"button","label":"Get Started","href":"https://knoxcall.com/register"}},"icons":{"library":"lucide"},"styling":{"eyebrows":"breadcrumbs","codeblocks":"dark","latex":true},"navigation":{"global":{"anchors":[{"anchor":"Support","icon":"headset","href":"https://knoxcall.com"},{"anchor":"Community","icon":"message-circle","href":"https://discord.knoxcall.com"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"knoxcall","hasAudioNarration":false,"actualSubdomain":"knoxcall","customDomains":["docs.knoxcall.com"],"gitSource":{"type":"github","owner":"knoxcall","repo":"knoxcall","deployBranch":"main","contentDirectory":"wiki","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true},"entitlements":{},"buildId":"6b0269b53ca2a55c00662c42","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Documentation","count":175},{"language":"default","tag":"API Reference","count":128},{"language":"default","tag":"AI Gateway","count":75},{"language":"default","tag":"Integration Setup Guides","count":24},{"language":"default","tag":"Webhooks","count":14},{"language":"default","tag":"Workflows","count":12},{"language":"default","tag":"Secret Store Migrations","count":11},{"language":"default","tag":"Single Sign-On (SAML)","count":10},{"language":"default","tag":"Overview","count":9},{"language":"default","tag":"Secrets","count":9}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":":root[class~=\"dark\"]{--background: #09090B;--background-light: #111113}:root[class~=\"dark\"] #sidebar{background:#09090B;border-color:rgba(255, 255, 255, 0.06)}:root[class~=\"dark\"] #navbar{background:rgba(9, 9, 11, 0.88);backdrop-filter:blur(12px);-webkit-backdrop-filter:blur(12px);border-color:rgba(255, 255, 255, 0.06)}:root[class~=\"dark\"] .bg-card{background:#111113;border-color:rgba(255, 255, 255, 0.06)}:root[class~=\"dark\"] pre{background:#111113!important;border:1px solid rgba(255, 255, 255, 0.06)}:root[class~=\"dark\"] :not(pre)>code{background:rgba(255, 255, 255, 0.05);border:1px solid rgba(255, 255, 255, 0.06);color:#D4D4D8}:root:not([class~=\"dark\"]){--background: #FFFFFF;--background-light: #FAFAFA}:root:not([class~=\"dark\"]) #sidebar{background:#FFFFFF;border-color:rgba(0, 0, 0, 0.07)}:root:not([class~=\"dark\"]) #navbar{background:rgba(255, 255, 255, 0.88);backdrop-filter:blur(12px);-webkit-backdrop-filter:blur(12px);border-color:rgba(0, 0, 0, 0.07)}:root:not([class~=\"dark\"]) .bg-card{background:#FAFAFA;border-color:rgba(0, 0, 0, 0.07)}:root:not([class~=\"dark\"]) pre{background:#111113!important;border:1px solid rgba(0, 0, 0, 0.07)}:root:not([class~=\"dark\"]) [data-component-part=\"code-block-root\"]{background-color:#111113!important;border:1px solid rgba(0, 0, 0, 0.07)}:root:not([class~=\"dark\"]) :not(pre)>code{background:rgba(0, 0, 0, 0.04);border:1px solid rgba(0, 0, 0, 0.07);color:#18181B}#sidebar{width:20rem!important;min-width:20rem!important;max-width:20rem!important}code{font-family:'Geist Mono', 'JetBrains Mono', 'Fira Code', ui-monospace, monospace;font-size:0.8125em;border-radius:5px;padding:2px 6px}pre code{padding:0;border:none;background:transparent!important}#sidebar,#navbar,.bg-card,pre,code{transition:background-color 0.15s ease, border-color 0.15s ease}"}]}
{"page":{"pagePath":"api-reference/ai-gateway/agents-update","slug":"/api-reference/ai-gateway/agents-update","pageMetadata":{"title":"Update Agent","description":"Partially update an agent — routing, model policy, budgets, guardrails.","openapi":"PATCH /ai-gateway/agents/{id}","href":"/api-reference/ai-gateway/agents-update"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Partially update an agent — routing, model policy, budgets, guardrails.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components};return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Partial update. Omitted fields are left as they are. This is where most of an\nagent’s configuration is set: everything beyond the handful of fields create\naccepts is applied here.`}),`\n`,_jsx(_components.p,{children:`Two changes have effects worth knowing before you make them:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:_jsx(_components.code,{children:`status: \"paused\"`})}),` refuses the agent’s traffic with `,_jsx(_components.code,{children:`503 agent_not_active`}),`\non `,_jsx(_components.code,{children:`/v1/ai`}),`, and JSON-RPC `,_jsx(_components.code,{children:`-32603`}),` on `,_jsx(_components.code,{children:`/v1/mcp`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:_jsx(_components.code,{children:`guardrail_webhook_url`})}),` is resolved and refused at write time through the\nSSRF chokepoint, and may not carry credentials in the URL\n(`,_jsx(_components.code,{children:`https://user:pass@host/`}),`) — a credential written into a URL is stored in\nplaintext and leaks into every log line that echoes it.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`Setting `,_jsx(_components.code,{children:`firewall_policy_id`}),` to a policy with `,_jsx(_components.code,{children:`action: \"block\"`}),` is what makes\nthe firewall refuse rather than warn — see `,_jsx(_components.a,{href:`/ai-gateway/firewall`,children:`Prompt firewall`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`Requires the `,_jsx(_components.code,{children:`update`}),` capability on `,_jsx(_components.code,{children:`ai_gateway`}),`. See the `,_jsx(_components.a,{href:`/api-reference/ai-gateway/control-plane-overview#authentication`,children:`control-plane overview`}),` for authentication, the `,_jsx(_components.code,{children:`{data, meta}`}),` envelope, pagination and error types.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"codeStyling":"dark","config":{},"pageMetadata":{"title":"Update Agent","description":"Partially update an agent — routing, model policy, budgets, guardrails.","openapi":"PATCH /ai-gateway/agents/{id}","href":"/api-reference/ai-gateway/agents-update"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"updateAgent","summary":"Update an agent","description":"Partially update an agent — routing, model policy, budgets, guardrails.","tags":["AI Gateway"],"requestBody":"92de2dcf-9831-4d22-ae99-c7a05b8524a4","responses":{"200":"0647da30-02d3-4729-bfcc-b1693fa0d12c","400":"9d297979-f69e-4eae-bda9-3a6db41f1bdc","401":"17667207-4541-4826-9af6-1986095e2ae5","402":"b8c94c56-055f-4229-91d7-a1582ff5bba3","403":"2b392845-33c8-441b-b278-74a7fe97cdf7","404":"e7d805ea-b8fb-40b0-8dfd-2e522b9ab0a7","500":"c1657694-7a2a-46b5-b250-1f6f259486fb"},"method":"patch","type":"path","servers":["440891b5-f7c9-4d73-bdf4-4195929faed2","5671e780-1911-4eee-98e2-8258f0dc1ee7"],"security":["79bbac72-4d50-472b-8e81-6d6a28db36ba","ff38421b-cb89-429f-8392-601071260cc3","58b64ca8-afd4-45f9-9f3b-28ec18e9f92e"],"path":"/ai-gateway/agents/{id}","baseUrlOptions":["https://api.knoxcall.com/v1","https://sandbox.knoxcall.com/v1"],"title":"Update an agent","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"08296a22-2a53-459b-b1e9-6c10b3218757":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","isRequired":true,"description":"The AI agent UUID.","uniqueKey":"","typeLabel":"string\u003cuuid>"},"description":"The AI agent UUID."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"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).","properties":{"name":{"type":"string","uniqueKey":"name","typeLabel":"string"},"slug":{"type":"string","description":"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.","uniqueKey":"slug","typeLabel":"string"},"description":{"oneOf":[{"type":"string","uniqueKey":"description.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"description.oneOf.1","typeLabel":"null"}],"uniqueKey":"description","typeLabel":"string | null"},"primary_route_id":{"oneOf":[{"type":"string","format":"uuid","uniqueKey":"primary_route_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","uniqueKey":"primary_route_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"primary_route_id","typeLabel":"string\u003cuuid> | null"},"fallback_route_ids":{"type":"array","items":{"type":"string","format":"uuid","uniqueKey":"fallback_route_ids.items.[INDEX]","typeLabel":"string\u003cuuid>"},"uniqueKey":"fallback_route_ids","typeLabel":"string\u003cuuid>[]"},"default_model":{"oneOf":[{"type":"string","uniqueKey":"default_model.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"default_model.oneOf.1","typeLabel":"null"}],"uniqueKey":"default_model","typeLabel":"string | null"},"model_allowlist":{"type":"array","items":{"type":"string","uniqueKey":"model_allowlist.items.[INDEX]","typeLabel":"string"},"uniqueKey":"model_allowlist","typeLabel":"string[]"},"model_denylist":{"type":"array","items":{"type":"string","uniqueKey":"model_denylist.items.[INDEX]","typeLabel":"string"},"uniqueKey":"model_denylist","typeLabel":"string[]"},"model_rewrite":{"type":"object","additionalProperties":{"type":"string","uniqueKey":"model_rewrite.additionalProperties","typeLabel":"string"},"maxProperties":100,"description":"Map of requested model → substituted model. Values must be STRINGS (the server validates with a string map) and at most 100 entries.","uniqueKey":"model_rewrite","typeLabel":"object"},"budget_daily_usd":{"oneOf":[{"type":"number","uniqueKey":"budget_daily_usd.oneOf.0","typeLabel":"number"},{"type":"null","uniqueKey":"budget_daily_usd.oneOf.1","typeLabel":"null"}],"uniqueKey":"budget_daily_usd","typeLabel":"number | null"},"budget_monthly_usd":{"oneOf":[{"type":"number","uniqueKey":"budget_monthly_usd.oneOf.0","typeLabel":"number"},{"type":"null","uniqueKey":"budget_monthly_usd.oneOf.1","typeLabel":"null"}],"uniqueKey":"budget_monthly_usd","typeLabel":"number | null"},"budget_per_call_max_tokens":{"oneOf":[{"type":"integer","uniqueKey":"budget_per_call_max_tokens.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"budget_per_call_max_tokens.oneOf.1","typeLabel":"null"}],"uniqueKey":"budget_per_call_max_tokens","typeLabel":"integer | null"},"budget_overage_action":{"type":"string","enum":["block","warn","fallback"],"description":"What happens once a budget is exhausted. `fallback` needs `fallback_agent_id`; without one it behaves as `block`.","uniqueKey":"budget_overage_action","typeLabel":"enum\u003cstring>"},"fallback_agent_id":{"oneOf":[{"type":"string","format":"uuid","uniqueKey":"fallback_agent_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","uniqueKey":"fallback_agent_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"fallback_agent_id","typeLabel":"string\u003cuuid> | null"},"streaming_enabled":{"type":"boolean","uniqueKey":"streaming_enabled","typeLabel":"boolean"},"firewall_policy_id":{"oneOf":[{"type":"string","format":"uuid","uniqueKey":"firewall_policy_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","uniqueKey":"firewall_policy_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"firewall_policy_id","typeLabel":"string\u003cuuid> | null"},"pii_redact_policy_id":{"oneOf":[{"type":"string","format":"uuid","uniqueKey":"pii_redact_policy_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","uniqueKey":"pii_redact_policy_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"pii_redact_policy_id","typeLabel":"string\u003cuuid> | null"},"pii_detokenize_response":{"type":"boolean","deprecated":true,"description":"AIGW-100 legacy alias for `pii_response_mode` (`true` -> `detokenize`, `false` -> `redact`). Still accepted; sending both with contradictory values is a 400.","uniqueKey":"pii_detokenize_response","typeLabel":"boolean"},"pii_request_mode":{"type":"string","enum":["off","tokenize"],"description":"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.","uniqueKey":"pii_request_mode","typeLabel":"enum\u003cstring>"},"pii_response_mode":{"type":"string","enum":["redact","detokenize"],"description":"What happens to the provider's answer. Default `detokenize`.","uniqueKey":"pii_response_mode","typeLabel":"enum\u003cstring>"},"pii_streaming_holdback_chars":{"type":"integer","description":"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.","uniqueKey":"pii_streaming_holdback_chars","typeLabel":"integer"},"pii_streaming_mode":{"type":"string","enum":["holdback","buffer","monitor"],"description":"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.","uniqueKey":"pii_streaming_mode","typeLabel":"enum\u003cstring>"},"tags":{"type":"object","additionalProperties":true,"description":"FinOps attribution labels (cost_center/team/project/…) echoed onto this agent's usage rows.","uniqueKey":"tags","typeLabel":"object"},"cache_mode":{"type":"string","enum":["off","exact","semantic"],"description":"`semantic` additionally needs `cache_embedding_model`; without one the cache reports itself degraded and serves nothing.","uniqueKey":"cache_mode","typeLabel":"enum\u003cstring>"},"cache_ttl_seconds":{"type":"integer","uniqueKey":"cache_ttl_seconds","typeLabel":"integer"},"cache_similarity_threshold":{"type":"number","minimum":0,"maximum":1,"description":"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.","uniqueKey":"cache_similarity_threshold","typeLabel":"number"},"cache_embedding_model":{"oneOf":[{"type":"string","uniqueKey":"cache_embedding_model.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"cache_embedding_model.oneOf.1","typeLabel":"null"}],"uniqueKey":"cache_embedding_model","typeLabel":"string | null"},"tool_allowlist":{"type":"array","items":{"type":"string","uniqueKey":"tool_allowlist.items.[INDEX]","typeLabel":"string"},"uniqueKey":"tool_allowlist","typeLabel":"string[]"},"output_schema":{"oneOf":[{"type":"object","additionalProperties":true,"description":"JSON Schema the answer is validated against.","uniqueKey":"output_schema.oneOf.0","typeLabel":"object"},{"type":"null","additionalProperties":true,"description":"JSON Schema the answer is validated against.","uniqueKey":"output_schema.oneOf.1","typeLabel":"null"}],"uniqueKey":"output_schema","typeLabel":"object | null"},"output_validation_action":{"type":"string","enum":["block","retry","warn"],"uniqueKey":"output_validation_action","typeLabel":"enum\u003cstring>"},"data_residency_region":{"oneOf":[{"type":"string","uniqueKey":"data_residency_region.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"data_residency_region.oneOf.1","typeLabel":"null"}],"uniqueKey":"data_residency_region","typeLabel":"string | null"},"cmek_key_id":{"oneOf":[{"type":"string","format":"uuid","uniqueKey":"cmek_key_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","uniqueKey":"cmek_key_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"cmek_key_id","typeLabel":"string\u003cuuid> | null"},"routing_policy":{"type":"object","description":"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.\n\nEvery 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.\n","additionalProperties":false,"properties":{"retry_on":{"type":"array","description":"Which outcomes are retried on the SAME route before failing over. `429` also promotes a rate-limit response to a fail-over trigger; without it a 429 is returned to you immediately, unchanged.\n","items":{"type":"string","enum":["429","5xx","timeout"],"uniqueKey":"routing_policy.retry_on.items.[INDEX]","typeLabel":"enum\u003cstring>"},"uniqueKey":"routing_policy.retry_on","typeLabel":"enum\u003cstring>[]"},"max_attempts":{"type":"integer","minimum":1,"maximum":5,"description":"Attempts per candidate route, including the first. Forced to 1 when `retry_on` is empty, so a stored policy never claims a retry that cannot happen.\n","uniqueKey":"routing_policy.max_attempts","typeLabel":"integer"},"backoff_ms":{"type":"integer","minimum":0,"maximum":30000,"description":"Delay before the second attempt.","uniqueKey":"routing_policy.backoff_ms","typeLabel":"integer"},"backoff_multiplier":{"type":"number","minimum":1,"maximum":10,"uniqueKey":"routing_policy.backoff_multiplier","typeLabel":"number"},"max_backoff_ms":{"type":"integer","minimum":0,"maximum":30000,"uniqueKey":"routing_policy.max_backoff_ms","typeLabel":"integer"},"respect_retry_after":{"type":"boolean","description":"Default true. An upstream `Retry-After` is honoured when it asks for LONGER than the computed backoff — it can extend a wait, never shorten one.\n","uniqueKey":"routing_policy.respect_retry_after","typeLabel":"boolean"},"max_retry_after_ms":{"type":"integer","minimum":0,"maximum":60000,"description":"Ceiling on a honoured `Retry-After`.","uniqueKey":"routing_policy.max_retry_after_ms","typeLabel":"integer"},"jitter":{"type":"boolean","description":"Default true. Spreads each delay across 50–100% of its computed value so a fleet does not retry in lockstep.\n","uniqueKey":"routing_policy.jitter","typeLabel":"boolean"},"route_weights":{"type":"object","description":"`{route_id: weight}`. When present, the route that serves a request is chosen in proportion to its weight across the primary and every fallback, and the remainder stay in weighted order for fail-over. A route not named here keeps weight 1; a route weighted 0 is drained and receives no traffic at all, including fail-over traffic. The token's own capability scope is enforced on every candidate, so a weight can never reach a route the token was not granted.\n","additionalProperties":{"type":"integer","minimum":0,"maximum":1000,"uniqueKey":"routing_policy.route_weights.additionalProperties","typeLabel":"integer"},"uniqueKey":"routing_policy.route_weights","typeLabel":"object"}},"uniqueKey":"routing_policy","typeLabel":"object"},"guardrail_webhook_url":{"oneOf":[{"type":"string","format":"uri","description":"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.\n\nWhat 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.\n\nThe 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.\n","uniqueKey":"guardrail_webhook_url.oneOf.0","typeLabel":"string\u003curi>"},{"type":"null","format":"uri","description":"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.\n\nWhat 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.\n\nThe 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.\n","uniqueKey":"guardrail_webhook_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"guardrail_webhook_url","typeLabel":"string\u003curi> | null"},"guardrail_webhook_secret_id":{"oneOf":[{"type":"string","format":"uuid","description":"Secret holding the HMAC-SHA256 key deliveries are signed with. The signature covers `\u003ctimestamp>.\u003cbody>` 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.\n","uniqueKey":"guardrail_webhook_secret_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","description":"Secret holding the HMAC-SHA256 key deliveries are signed with. The signature covers `\u003ctimestamp>.\u003cbody>` 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.\n","uniqueKey":"guardrail_webhook_secret_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"guardrail_webhook_secret_id","typeLabel":"string\u003cuuid> | null"},"guardrail_webhook_mode":{"type":"string","enum":["off","request","response","both"],"description":"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.\n","uniqueKey":"guardrail_webhook_mode","typeLabel":"enum\u003cstring>"},"guardrail_webhook_timeout_ms":{"type":"integer","minimum":100,"maximum":10000,"description":"How long to wait for a verdict. Clamped, because a request waiting on your scanner is holding one of the gateway's API workers.\n","uniqueKey":"guardrail_webhook_timeout_ms","typeLabel":"integer"},"guardrail_webhook_failure_action":{"type":"string","enum":["fail_open","fail_closed"],"description":"What 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.\n\nA 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.\n","uniqueKey":"guardrail_webhook_failure_action","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"example":{"default_model":"claude-opus-4-8","streaming_enabled":true},"examples":{"Example":{"title":"Example","value":{"default_model":"claude-opus-4-8","streaming_enabled":true}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"0647da30-02d3-4729-bfcc-b1693fa0d12c":{"description":"The updated agent.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"An agent under a gateway — the addressable unit an AI SDK points at.","properties":{"id":{"type":"string","format":"uuid","isRequired":true,"uniqueKey":"data.id","typeLabel":"string\u003cuuid>"},"gateway_id":{"type":"string","format":"uuid","isRequired":true,"uniqueKey":"data.gateway_id","typeLabel":"string\u003cuuid>"},"name":{"type":"string","isRequired":true,"uniqueKey":"data.name","typeLabel":"string"},"slug":{"type":"string","isRequired":true,"uniqueKey":"data.slug","typeLabel":"string"},"status":{"type":"string","enum":["active","paused","archived"],"isRequired":true,"uniqueKey":"data.status","typeLabel":"enum\u003cstring>"},"created_at":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"data.created_at","typeLabel":"string\u003cdate-time>"},"updated_at":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"data.updated_at","typeLabel":"string\u003cdate-time>"},"agent_url":{"type":"string","description":"The data-plane base URL for this agent — `https://{tenant}.knoxcall.com/v1/ai/{slug}`.\nPoint an AI SDK's `base_url` here and give it a capability token as the API key.\n\nPresent on EVERY agent projection: create, get, update and the list rows (AIGW-160\nera it was create and get only, so a list row was shaped differently from the row\ncreate returned). It is server-computed rather than stored, so it MOVES when `slug`\nchanges — which is why `PATCH` returns it too.\n\nAn EMPTY STRING when the tenant slug cannot be resolved. Treat empty as \"not\navailable\", never as a URL.\n","isRequired":true,"uniqueKey":"data.agent_url","typeLabel":"string"},"tenant_id":{"type":"string","format":"uuid","uniqueKey":"data.tenant_id","typeLabel":"string\u003cuuid>"},"description":{"oneOf":[{"type":"string","uniqueKey":"data.description.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"data.description.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.description","typeLabel":"string | null"},"primary_route_id":{"oneOf":[{"type":"string","format":"uuid","uniqueKey":"data.primary_route_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","uniqueKey":"data.primary_route_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.primary_route_id","typeLabel":"string\u003cuuid> | null"},"fallback_route_ids":{"type":"array","items":{"type":"string","format":"uuid","uniqueKey":"data.fallback_route_ids.items.[INDEX]","typeLabel":"string\u003cuuid>"},"uniqueKey":"data.fallback_route_ids","typeLabel":"string\u003cuuid>[]"},"model_allowlist":{"type":"array","items":{"type":"string","uniqueKey":"data.model_allowlist.items.[INDEX]","typeLabel":"string"},"uniqueKey":"data.model_allowlist","typeLabel":"string[]"},"model_denylist":{"type":"array","items":{"type":"string","uniqueKey":"data.model_denylist.items.[INDEX]","typeLabel":"string"},"uniqueKey":"data.model_denylist","typeLabel":"string[]"},"default_model":{"oneOf":[{"type":"string","uniqueKey":"data.default_model.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"data.default_model.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.default_model","typeLabel":"string | null"},"model_rewrite":{"type":"object","additionalProperties":{"type":"string","uniqueKey":"data.model_rewrite.additionalProperties","typeLabel":"string"},"maxProperties":100,"description":"Map of requested model → substituted model. Values must be STRINGS (the server validates with a string map) and at most 100 entries.","uniqueKey":"data.model_rewrite","typeLabel":"object"},"budget_daily_usd":{"oneOf":[{"type":"number","uniqueKey":"data.budget_daily_usd.oneOf.0","typeLabel":"number"},{"type":"null","uniqueKey":"data.budget_daily_usd.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.budget_daily_usd","typeLabel":"number | null"},"budget_monthly_usd":{"oneOf":[{"type":"number","uniqueKey":"data.budget_monthly_usd.oneOf.0","typeLabel":"number"},{"type":"null","uniqueKey":"data.budget_monthly_usd.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.budget_monthly_usd","typeLabel":"number | null"},"budget_per_call_max_tokens":{"oneOf":[{"type":"integer","uniqueKey":"data.budget_per_call_max_tokens.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"data.budget_per_call_max_tokens.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.budget_per_call_max_tokens","typeLabel":"integer | null"},"budget_overage_action":{"type":"string","uniqueKey":"data.budget_overage_action","typeLabel":"string"},"fallback_agent_id":{"oneOf":[{"type":"string","format":"uuid","uniqueKey":"data.fallback_agent_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","uniqueKey":"data.fallback_agent_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.fallback_agent_id","typeLabel":"string\u003cuuid> | null"},"pii_redact_policy_id":{"oneOf":[{"type":"string","format":"uuid","uniqueKey":"data.pii_redact_policy_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","uniqueKey":"data.pii_redact_policy_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.pii_redact_policy_id","typeLabel":"string\u003cuuid> | null"},"pii_detokenize_response":{"type":"boolean","readOnly":true,"description":"AIGW-100 legacy alias. Read-only mirror of `pii_response_mode == \"detokenize\"`; the column is GENERATED in the database so the two can never disagree. Still ACCEPTED on create and update, where it is folded onto `pii_response_mode`.","uniqueKey":"data.pii_detokenize_response","typeLabel":"boolean"},"pii_request_mode":{"type":"string","enum":["off","tokenize"],"description":"What happens to the PROMPT before it leaves KnoxCall. `tokenize` (default) replaces detected entities with conversation-scoped, format-preserving tokens before the provider sees them; `off` forwards the prompt exactly as sent. Independent of `pii_response_mode` — before AIGW-100 request tokenization was gated on the response toggle, so an agent with a PII policy and `pii_detokenize_response: false` sent prompts verbatim.","uniqueKey":"data.pii_request_mode","typeLabel":"enum\u003cstring>"},"pii_response_mode":{"type":"string","enum":["redact","detokenize"],"description":"What happens to the provider's answer. `redact` runs the detector stack (fresh PII in the completion, canary tokens) and leaves `KC_*` tokens as tokens; `detokenize` (default) also swaps them back to this conversation's originals. There is no `off` — the detector stack runs on every 2xx.","uniqueKey":"data.pii_response_mode","typeLabel":"enum\u003cstring>"},"pii_streaming_holdback_chars":{"type":"integer","uniqueKey":"data.pii_streaming_holdback_chars","typeLabel":"integer"},"pii_streaming_mode":{"type":"string","uniqueKey":"data.pii_streaming_mode","typeLabel":"string"},"cache_mode":{"type":"string","uniqueKey":"data.cache_mode","typeLabel":"string"},"cache_ttl_seconds":{"type":"integer","uniqueKey":"data.cache_ttl_seconds","typeLabel":"integer"},"cache_similarity_threshold":{"oneOf":[{"type":"number","uniqueKey":"data.cache_similarity_threshold.oneOf.0","typeLabel":"number"},{"type":"null","uniqueKey":"data.cache_similarity_threshold.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.cache_similarity_threshold","typeLabel":"number | null"},"cache_embedding_model":{"oneOf":[{"type":"string","uniqueKey":"data.cache_embedding_model.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"data.cache_embedding_model.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.cache_embedding_model","typeLabel":"string | null"},"streaming_enabled":{"type":"boolean","uniqueKey":"data.streaming_enabled","typeLabel":"boolean"},"firewall_policy_id":{"oneOf":[{"type":"string","format":"uuid","uniqueKey":"data.firewall_policy_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","uniqueKey":"data.firewall_policy_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.firewall_policy_id","typeLabel":"string\u003cuuid> | null"},"tool_allowlist":{"type":"array","items":{"type":"string","uniqueKey":"data.tool_allowlist.items.[INDEX]","typeLabel":"string"},"uniqueKey":"data.tool_allowlist","typeLabel":"string[]"},"output_schema":{"oneOf":[{"type":"object","additionalProperties":true,"uniqueKey":"data.output_schema.oneOf.0","typeLabel":"object"},{"type":"null","additionalProperties":true,"uniqueKey":"data.output_schema.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.output_schema","typeLabel":"object | null"},"output_validation_action":{"type":"string","uniqueKey":"data.output_validation_action","typeLabel":"string"},"data_residency_region":{"oneOf":[{"type":"string","enum":["us","eu","uk","ca","au","jp","in",null],"description":"AIGW-53: pin this agent's upstream egress to a data-residency region. When set, a request whose upstream endpoint KnoxCall cannot classify as serving that region is refused on the data plane with HTTP 403 `residency_violation` — including a fallback route, which is where an unpinned failover would otherwise leave the region. `null` (the default) applies no residency constraint. See https://docs.knoxcall.com/ai-gateway/data-residency for the endpoints KnoxCall classifies and for what this control does and does not guarantee.","uniqueKey":"data.data_residency_region.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["us","eu","uk","ca","au","jp","in",null],"description":"AIGW-53: pin this agent's upstream egress to a data-residency region. When set, a request whose upstream endpoint KnoxCall cannot classify as serving that region is refused on the data plane with HTTP 403 `residency_violation` — including a fallback route, which is where an unpinned failover would otherwise leave the region. `null` (the default) applies no residency constraint. See https://docs.knoxcall.com/ai-gateway/data-residency for the endpoints KnoxCall classifies and for what this control does and does not guarantee.","uniqueKey":"data.data_residency_region.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.data_residency_region","typeLabel":"enum\u003cstring> | null"},"cmek_key_id":{"oneOf":[{"type":"string","format":"uuid","description":"AIGW-53: the `tenant_master_keys` id this agent's AI data (its PII token map) is encrypted under. Must be one of THIS tenant's keys and must be customer-managed (`wrap_method = customer_kms`, i.e. BYOK configured) — a KnoxCall-wrapped key is refused, because a CMEK the platform can unwrap is not a CMEK. If the key is missing, retired, revoked, or your KMS refuses to unwrap it, the data-plane request is refused with HTTP 503 `cmek_unavailable` rather than written under a different key.","uniqueKey":"data.cmek_key_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","description":"AIGW-53: the `tenant_master_keys` id this agent's AI data (its PII token map) is encrypted under. Must be one of THIS tenant's keys and must be customer-managed (`wrap_method = customer_kms`, i.e. BYOK configured) — a KnoxCall-wrapped key is refused, because a CMEK the platform can unwrap is not a CMEK. If the key is missing, retired, revoked, or your KMS refuses to unwrap it, the data-plane request is refused with HTTP 503 `cmek_unavailable` rather than written under a different key.","uniqueKey":"data.cmek_key_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.cmek_key_id","typeLabel":"string\u003cuuid> | null"},"paused_reason":{"oneOf":[{"type":"string","uniqueKey":"data.paused_reason.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"data.paused_reason.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.paused_reason","typeLabel":"string | null"},"tags":{"type":"object","additionalProperties":true,"description":"FinOps attribution labels (cost_center/team/project/…) echoed onto this agent's usage rows.","uniqueKey":"data.tags","typeLabel":"object"},"provider":{"oneOf":[{"type":"string","description":"The upstream shape this agent fronts — one of the values `CreateAiGatewayAgentRequest.provider` enumerates (the catalog has grown to fourteen; `ai_gateway_agents_provider_check` is the authority). Set once, at create time, and deliberately NOT patchable: changing it without re-pointing `primary_route_id` at a matching route would make the stored value a lie. `null` on an agent created before the field existed whose route shape the backfill did not recognise — render that as \"custom\", never as a guess.","uniqueKey":"data.provider.oneOf.0","typeLabel":"string"},{"type":"null","description":"The upstream shape this agent fronts — one of the values `CreateAiGatewayAgentRequest.provider` enumerates (the catalog has grown to fourteen; `ai_gateway_agents_provider_check` is the authority). Set once, at create time, and deliberately NOT patchable: changing it without re-pointing `primary_route_id` at a matching route would make the stored value a lie. `null` on an agent created before the field existed whose route shape the backfill did not recognise — render that as \"custom\", never as a guess.","uniqueKey":"data.provider.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.provider","typeLabel":"string | null"},"routing_policy":{"type":"object","description":"Returned on every agent read. `{}` — the default for every agent — means one attempt per route and fail-over to `fallback_route_ids` on 5xx only.\n","properties":{"retry_on":{"type":"array","description":"Which outcomes are retried on the SAME route before failing over. `429` also promotes a rate-limit response to a fail-over trigger; without it a 429 is returned to you immediately, unchanged.\n","items":{"type":"string","enum":["429","5xx","timeout"],"uniqueKey":"data.routing_policy.retry_on.items.[INDEX]","typeLabel":"enum\u003cstring>"},"uniqueKey":"data.routing_policy.retry_on","typeLabel":"enum\u003cstring>[]"},"max_attempts":{"type":"integer","minimum":1,"maximum":5,"description":"Attempts per candidate route, including the first. Forced to 1 when `retry_on` is empty, so a stored policy never claims a retry that cannot happen.\n","uniqueKey":"data.routing_policy.max_attempts","typeLabel":"integer"},"backoff_ms":{"type":"integer","minimum":0,"maximum":30000,"description":"Delay before the second attempt.","uniqueKey":"data.routing_policy.backoff_ms","typeLabel":"integer"},"backoff_multiplier":{"type":"number","minimum":1,"maximum":10,"uniqueKey":"data.routing_policy.backoff_multiplier","typeLabel":"number"},"max_backoff_ms":{"type":"integer","minimum":0,"maximum":30000,"uniqueKey":"data.routing_policy.max_backoff_ms","typeLabel":"integer"},"respect_retry_after":{"type":"boolean","description":"Default true. An upstream `Retry-After` is honoured when it asks for LONGER than the computed backoff — it can extend a wait, never shorten one.\n","uniqueKey":"data.routing_policy.respect_retry_after","typeLabel":"boolean"},"max_retry_after_ms":{"type":"integer","minimum":0,"maximum":60000,"description":"Ceiling on a honoured `Retry-After`.","uniqueKey":"data.routing_policy.max_retry_after_ms","typeLabel":"integer"},"jitter":{"type":"boolean","description":"Default true. Spreads each delay across 50–100% of its computed value so a fleet does not retry in lockstep.\n","uniqueKey":"data.routing_policy.jitter","typeLabel":"boolean"},"route_weights":{"type":"object","description":"`{route_id: weight}`. When present, the route that serves a request is chosen in proportion to its weight across the primary and every fallback, and the remainder stay in weighted order for fail-over. A route not named here keeps weight 1; a route weighted 0 is drained and receives no traffic at all, including fail-over traffic. The token's own capability scope is enforced on every candidate, so a weight can never reach a route the token was not granted.\n","additionalProperties":{"type":"integer","minimum":0,"maximum":1000,"uniqueKey":"data.routing_policy.route_weights.additionalProperties","typeLabel":"integer"},"uniqueKey":"data.routing_policy.route_weights","typeLabel":"object"}},"additionalProperties":false,"uniqueKey":"data.routing_policy","typeLabel":"object"},"guardrail_webhook_url":{"oneOf":[{"type":"string","format":"uri","description":"The external scanner this agent POSTs to for a verdict, or null when it has none. See `CreateAiGatewayAgentRequest.guardrail_webhook_url` for what the hook receives and how the destination is refused.\n","uniqueKey":"data.guardrail_webhook_url.oneOf.0","typeLabel":"string\u003curi>"},{"type":"null","format":"uri","description":"The external scanner this agent POSTs to for a verdict, or null when it has none. See `CreateAiGatewayAgentRequest.guardrail_webhook_url` for what the hook receives and how the destination is refused.\n","uniqueKey":"data.guardrail_webhook_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.guardrail_webhook_url","typeLabel":"string\u003curi> | null"},"guardrail_webhook_secret_id":{"oneOf":[{"type":"string","format":"uuid","description":"Secret holding the HMAC-SHA256 key deliveries are signed with, or null when deliveries are sent unsigned.\n","uniqueKey":"data.guardrail_webhook_secret_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","description":"Secret holding the HMAC-SHA256 key deliveries are signed with, or null when deliveries are sent unsigned.\n","uniqueKey":"data.guardrail_webhook_secret_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.guardrail_webhook_secret_id","typeLabel":"string\u003cuuid> | null"},"guardrail_webhook_mode":{"type":"string","enum":["off","request","response","both"],"description":"Which directions are inspected. `off` when the agent has no hook — the server returns the string, never a boolean.\n","uniqueKey":"data.guardrail_webhook_mode","typeLabel":"enum\u003cstring>"},"guardrail_webhook_timeout_ms":{"type":"integer","minimum":100,"maximum":10000,"description":"How long the gateway waits for a verdict. Defaults to 2000.","uniqueKey":"data.guardrail_webhook_timeout_ms","typeLabel":"integer"},"guardrail_webhook_failure_action":{"type":"string","enum":["fail_open","fail_closed"],"description":"What happens when the hook does not answer. Defaults to `fail_open`, the posture an agent already has with no hook at all.\n","uniqueKey":"data.guardrail_webhook_failure_action","typeLabel":"enum\u003cstring>"},"created_by":{"oneOf":[{"type":"string","uniqueKey":"data.created_by.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"data.created_by.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.created_by","typeLabel":"string | null"}},"required":["id","gateway_id","name","slug","status","agent_url","created_at","updated_at"],"uniqueKey":"data","typeLabel":"object"},"meta":{"type":"object","description":"Metadata included with every API response.","properties":{"request_id":{"type":"string","format":"uuid","description":"Unique identifier for this API request, useful for support and debugging.","example":"550e8400-e29b-41d4-a716-446655440000","isRequired":true,"uniqueKey":"meta.request_id","typeLabel":"string\u003cuuid>"}},"required":["request_id"],"uniqueKey":"meta","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"data":{"id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","gateway_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","name":"\u003cstring>","slug":"\u003cstring>","status":"active","created_at":"2023-11-07T05:31:56Z","updated_at":"2023-11-07T05:31:56Z","agent_url":"\u003cstring>","tenant_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","description":"\u003cstring>","primary_route_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","fallback_route_ids":["3c90c3cc-0d44-4b50-8888-8dd25736052a"],"model_allowlist":["\u003cstring>"],"model_denylist":["\u003cstring>"],"default_model":"\u003cstring>","model_rewrite":{},"budget_daily_usd":123,"budget_monthly_usd":123,"budget_per_call_max_tokens":123,"budget_overage_action":"\u003cstring>","fallback_agent_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","pii_redact_policy_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","pii_detokenize_response":true,"pii_request_mode":"off","pii_response_mode":"redact","pii_streaming_holdback_chars":123,"pii_streaming_mode":"\u003cstring>","cache_mode":"\u003cstring>","cache_ttl_seconds":123,"cache_similarity_threshold":123,"cache_embedding_model":"\u003cstring>","streaming_enabled":true,"firewall_policy_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","tool_allowlist":["\u003cstring>"],"output_schema":{},"output_validation_action":"\u003cstring>","data_residency_region":"us","cmek_key_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","paused_reason":"\u003cstring>","tags":{},"provider":"\u003cstring>","routing_policy":{"retry_on":["429"],"max_attempts":3,"backoff_ms":15000,"backoff_multiplier":5.5,"max_backoff_ms":15000,"respect_retry_after":true,"max_retry_after_ms":30000,"jitter":true,"route_weights":{}},"guardrail_webhook_url":"\u003cstring>","guardrail_webhook_secret_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","guardrail_webhook_mode":"off","guardrail_webhook_timeout_ms":5050,"guardrail_webhook_failure_action":"fail_open","created_by":"\u003cstring>"},"meta":{"request_id":"550e8400-e29b-41d4-a716-446655440000"}}}},"exampleType":"generated"}},"exampleType":"generated"},"9d297979-f69e-4eae-bda9-3a6db41f1bdc":{"description":"The request failed validation (always `400 validation_error`). A malformed idempotency key returns `400 invalid_idempotency_key`.","headers":{"X-Request-Id":{"description":"Unique identifier for this request (UUID). Present on **every** response and equal\nto the `request_id` field in the response body. Quote it when contacting support.\n","schema":{"type":"string","format":"uuid"},"example":"550e8400-e29b-41d4-a716-446655440000"},"KnoxCall-Version":{"description":"The dated API version (`YYYY-MM-DD`) that served this response. Equals the value\nof the `KnoxCall-Version` request header when supplied, otherwise the newest version.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-08-05T00:00:00.000Z"}},"content":{"application/json":{"schema":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Machine-readable error type. The set is OPEN — endpoints define specific types beyond the common ones below, so clients should branch on the types they know and fall back to the HTTP status class for anything unrecognized. Common values: authentication_required, invalid_api_key, wrong_key_type, subscription_inactive, rate_limit_exceeded, validation_error, forbidden, not_found, method_not_allowed (405, carries Allow), conflict, in_use, plan_limit, plan_feature, internal_error, dependency_unavailable (503, carries Retry-After), invalid_request, invalid_definition, not_cancellable, invalid_idempotency_key, idempotency_key_reuse, request_in_progress, system_client_protected, use_oauth, use_dpop_nonce (401 on /v1 and the data plane, 400 on POST /oauth/token; see \"DPoP sender-constrained tokens\").","example":"validation_error","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","example":"name and target_base_url are required.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","format":"uuid","description":"Unique identifier for this request.","example":"550e8400-e29b-41d4-a716-446655440000","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string\u003cuuid>"}},"required":["type","message","request_id"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"validation_error":{"title":"validation_error","summary":"Request body failed validation","value":{"error":{"type":"validation_error","message":"name and target_base_url are required.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}},"invalid_idempotency_key":{"title":"invalid_idempotency_key","summary":"Malformed idempotency key","value":{"error":{"type":"invalid_idempotency_key","message":"X-Idempotency-Key must be a non-empty string of at most 255 characters.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}}},"exampleType":"examples"}},"exampleType":"examples"},"17667207-4541-4826-9af6-1986095e2ae5":{"description":"Authentication is required or the provided API key is invalid.","headers":{"X-Request-Id":{"description":"Unique identifier for this request (UUID). Present on **every** response and equal\nto the `request_id` field in the response body. Quote it when contacting support.\n","schema":{"type":"string","format":"uuid"},"example":"550e8400-e29b-41d4-a716-446655440000"},"KnoxCall-Version":{"description":"The dated API version (`YYYY-MM-DD`) that served this response. Equals the value\nof the `KnoxCall-Version` request header when supplied, otherwise the newest version.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-08-05T00:00:00.000Z"}},"content":{"application/json":{"schema":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Machine-readable error type. The set is OPEN — endpoints define specific types beyond the common ones below, so clients should branch on the types they know and fall back to the HTTP status class for anything unrecognized. Common values: authentication_required, invalid_api_key, wrong_key_type, subscription_inactive, rate_limit_exceeded, validation_error, forbidden, not_found, method_not_allowed (405, carries Allow), conflict, in_use, plan_limit, plan_feature, internal_error, dependency_unavailable (503, carries Retry-After), invalid_request, invalid_definition, not_cancellable, invalid_idempotency_key, idempotency_key_reuse, request_in_progress, system_client_protected, use_oauth, use_dpop_nonce (401 on /v1 and the data plane, 400 on POST /oauth/token; see \"DPoP sender-constrained tokens\").","example":"validation_error","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","example":"name and target_base_url are required.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","format":"uuid","description":"Unique identifier for this request.","example":"550e8400-e29b-41d4-a716-446655440000","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string\u003cuuid>"}},"required":["type","message","request_id"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"missing_key":{"title":"missing_key","summary":"No API key provided","value":{"error":{"type":"authentication_required","message":"API key is required. Use Authorization: Bearer \u003capi_key> or x-api-key header.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}},"invalid_key":{"title":"invalid_key","summary":"Invalid API key","value":{"error":{"type":"invalid_api_key","message":"Invalid API key.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}}},"exampleType":"examples"}},"exampleType":"examples"},"b8c94c56-055f-4229-91d7-a1582ff5bba3":{"description":"Payment Required. The action exceeds your plan's limits. Two `error.type` values\nshare this status: `plan_limit` when a COUNTED resource quota was reached (routes,\nsecrets, AI agents, MCP servers), and `plan_feature` when the CAPABILITY itself is\nnot on your tier (custom PII redaction policies, compliance packs, custom\nprompt-firewall policies). Both mean \"upgrade to proceed\"; branch on `type` only if\nyou want to distinguish \"you have used your allowance\" from \"buy a bigger plan\".\n\nNeither ever revokes something you already have: a plan downgrade leaves existing\nagents, policies and installed packs in place and keeps working.\n","headers":{"X-Request-Id":{"description":"Unique identifier for this request (UUID). Present on **every** response and equal\nto the `request_id` field in the response body. Quote it when contacting support.\n","schema":{"type":"string","format":"uuid"},"example":"550e8400-e29b-41d4-a716-446655440000"},"KnoxCall-Version":{"description":"The dated API version (`YYYY-MM-DD`) that served this response. Equals the value\nof the `KnoxCall-Version` request header when supplied, otherwise the newest version.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-08-05T00:00:00.000Z"}},"content":{"application/json":{"schema":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Machine-readable error type. The set is OPEN — endpoints define specific types beyond the common ones below, so clients should branch on the types they know and fall back to the HTTP status class for anything unrecognized. Common values: authentication_required, invalid_api_key, wrong_key_type, subscription_inactive, rate_limit_exceeded, validation_error, forbidden, not_found, method_not_allowed (405, carries Allow), conflict, in_use, plan_limit, plan_feature, internal_error, dependency_unavailable (503, carries Retry-After), invalid_request, invalid_definition, not_cancellable, invalid_idempotency_key, idempotency_key_reuse, request_in_progress, system_client_protected, use_oauth, use_dpop_nonce (401 on /v1 and the data plane, 400 on POST /oauth/token; see \"DPoP sender-constrained tokens\").","example":"validation_error","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","example":"name and target_base_url are required.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","format":"uuid","description":"Unique identifier for this request.","example":"550e8400-e29b-41d4-a716-446655440000","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string\u003cuuid>"}},"required":["type","message","request_id"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"type":"plan_limit","message":"Route limit reached (10). Upgrade your plan to add more.","request_id":"550e8400-e29b-41d4-a716-446655440000"}},"examples":{"Example":{"title":"Example","value":{"error":{"type":"plan_limit","message":"Route limit reached (10). Upgrade your plan to add more.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}}},"exampleType":"examples"}},"exampleType":"examples"},"2b392845-33c8-441b-b278-74a7fe97cdf7":{"description":"The key is authenticated but not authorized for this action (missing scope), a plan\nlimit was reached, or the resource must be managed via OAuth (`use_oauth`) / is a\nprotected system client (`system_client_protected`).\n","headers":{"X-Request-Id":{"description":"Unique identifier for this request (UUID). Present on **every** response and equal\nto the `request_id` field in the response body. Quote it when contacting support.\n","schema":{"type":"string","format":"uuid"},"example":"550e8400-e29b-41d4-a716-446655440000"},"KnoxCall-Version":{"description":"The dated API version (`YYYY-MM-DD`) that served this response. Equals the value\nof the `KnoxCall-Version` request header when supplied, otherwise the newest version.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-08-05T00:00:00.000Z"}},"content":{"application/json":{"schema":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Machine-readable error type. The set is OPEN — endpoints define specific types beyond the common ones below, so clients should branch on the types they know and fall back to the HTTP status class for anything unrecognized. Common values: authentication_required, invalid_api_key, wrong_key_type, subscription_inactive, rate_limit_exceeded, validation_error, forbidden, not_found, method_not_allowed (405, carries Allow), conflict, in_use, plan_limit, plan_feature, internal_error, dependency_unavailable (503, carries Retry-After), invalid_request, invalid_definition, not_cancellable, invalid_idempotency_key, idempotency_key_reuse, request_in_progress, system_client_protected, use_oauth, use_dpop_nonce (401 on /v1 and the data plane, 400 on POST /oauth/token; see \"DPoP sender-constrained tokens\").","example":"validation_error","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","example":"name and target_base_url are required.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","format":"uuid","description":"Unique identifier for this request.","example":"550e8400-e29b-41d4-a716-446655440000","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string\u003cuuid>"}},"required":["type","message","request_id"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"forbidden":{"title":"forbidden","summary":"Missing scope","value":{"error":{"type":"forbidden","message":"This key is not authorized to list AI gateways.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}},"use_oauth":{"title":"use_oauth","summary":"Resource is OAuth-only","value":{"error":{"type":"use_oauth","message":"This resource must be managed with an OAuth 2.1 access token.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}},"system_client_protected":{"title":"system_client_protected","summary":"Protected system client","value":{"error":{"type":"system_client_protected","message":"This client is managed by the platform and cannot be modified.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}}},"exampleType":"examples"}},"exampleType":"examples"},"e7d805ea-b8fb-40b0-8dfd-2e522b9ab0a7":{"description":"The requested resource was not found.","headers":{"X-Request-Id":{"description":"Unique identifier for this request (UUID). Present on **every** response and equal\nto the `request_id` field in the response body. Quote it when contacting support.\n","schema":{"type":"string","format":"uuid"},"example":"550e8400-e29b-41d4-a716-446655440000"},"KnoxCall-Version":{"description":"The dated API version (`YYYY-MM-DD`) that served this response. Equals the value\nof the `KnoxCall-Version` request header when supplied, otherwise the newest version.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-08-05T00:00:00.000Z"}},"content":{"application/json":{"schema":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Machine-readable error type. The set is OPEN — endpoints define specific types beyond the common ones below, so clients should branch on the types they know and fall back to the HTTP status class for anything unrecognized. Common values: authentication_required, invalid_api_key, wrong_key_type, subscription_inactive, rate_limit_exceeded, validation_error, forbidden, not_found, method_not_allowed (405, carries Allow), conflict, in_use, plan_limit, plan_feature, internal_error, dependency_unavailable (503, carries Retry-After), invalid_request, invalid_definition, not_cancellable, invalid_idempotency_key, idempotency_key_reuse, request_in_progress, system_client_protected, use_oauth, use_dpop_nonce (401 on /v1 and the data plane, 400 on POST /oauth/token; see \"DPoP sender-constrained tokens\").","example":"validation_error","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","example":"name and target_base_url are required.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","format":"uuid","description":"Unique identifier for this request.","example":"550e8400-e29b-41d4-a716-446655440000","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string\u003cuuid>"}},"required":["type","message","request_id"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"type":"not_found","message":"Route not found.","request_id":"550e8400-e29b-41d4-a716-446655440000"}},"examples":{"Example":{"title":"Example","value":{"error":{"type":"not_found","message":"Route not found.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}}},"exampleType":"examples"}},"exampleType":"examples"},"c1657694-7a2a-46b5-b250-1f6f259486fb":{"description":"An unexpected server error occurred.","headers":{"X-Request-Id":{"description":"Unique identifier for this request (UUID). Present on **every** response and equal\nto the `request_id` field in the response body. Quote it when contacting support.\n","schema":{"type":"string","format":"uuid"},"example":"550e8400-e29b-41d4-a716-446655440000"},"KnoxCall-Version":{"description":"The dated API version (`YYYY-MM-DD`) that served this response. Equals the value\nof the `KnoxCall-Version` request header when supplied, otherwise the newest version.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-08-05T00:00:00.000Z"}},"content":{"application/json":{"schema":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Machine-readable error type. The set is OPEN — endpoints define specific types beyond the common ones below, so clients should branch on the types they know and fall back to the HTTP status class for anything unrecognized. Common values: authentication_required, invalid_api_key, wrong_key_type, subscription_inactive, rate_limit_exceeded, validation_error, forbidden, not_found, method_not_allowed (405, carries Allow), conflict, in_use, plan_limit, plan_feature, internal_error, dependency_unavailable (503, carries Retry-After), invalid_request, invalid_definition, not_cancellable, invalid_idempotency_key, idempotency_key_reuse, request_in_progress, system_client_protected, use_oauth, use_dpop_nonce (401 on /v1 and the data plane, 400 on POST /oauth/token; see \"DPoP sender-constrained tokens\").","example":"validation_error","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"message":{"type":"string","description":"Human-readable error message.","example":"name and target_base_url are required.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","format":"uuid","description":"Unique identifier for this request.","example":"550e8400-e29b-41d4-a716-446655440000","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string\u003cuuid>"}},"required":["type","message","request_id"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"type":"internal_error","message":"An unexpected error occurred.","request_id":"550e8400-e29b-41d4-a716-446655440000"}},"examples":{"Example":{"title":"Example","value":{"error":{"type":"internal_error","message":"An unexpected error occurred.","request_id":"550e8400-e29b-41d4-a716-446655440000"}}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"79bbac72-4d50-472b-8e81-6d6a28db36ba":{"OAuth2":{"type":"oauth2","description":"OAuth 2.1 authentication — recommended for new integrations. Access tokens\n(`kc_` prefix) are minted at the root-host token endpoint\n`https://api.knoxcall.com/oauth/token` and passed as `Authorization: Bearer \u003caccess_token>`.\nPublic clients must use PKCE with the `authorization_code` grant; confidential\nclients may use `client_credentials`. The first-party SDKs and the\n`knoxcall login` CLI handle token minting, caching, refresh, and DPoP for you.\n","flows":{"clientCredentials":{"tokenUrl":"https://api.knoxcall.com/oauth/token","refreshUrl":"https://api.knoxcall.com/oauth/token","scopes":{"routes:read":"Read routes.","routes:write":"Create, update, and delete routes.","wrap:manifest:self":"A server credential's (Connect a server) view of GET /v1/wrap/intercept-manifest and POST /v1/wrap/egress-observations. It answers only for the server the credential belongs to - the routes assigned to that server in the requested environment whose routes:invoke:id:\u003croute_id> scope the token holds - and never lists another server's routes or the workspace's. A server credential invokes routes with routes:invoke:id:\u003croute_id>, one route per scope, by the route's id (never re-used, unlike a slug).","secrets:read":"Read secret metadata. Does NOT include retrieving a live OAuth2 access token.","secrets:oauth_token":"Retrieve a live upstream OAuth2 access token (GET /v1/secrets/{id}/oauth2/token). Distinct from secrets:read because the call refreshes the credential at the provider.","secrets:write":"Create, update, and delete secrets.","vaults:detokenize":"Turn a vault token back into its original value. Required by GET /v1/vaults/{vault}/tokens/{token}, by a token template reference in a /v1/proxy body, and by creating a `detokenize` route action. Distinct from vaults:read, which lists vaults and token metadata and never returns a value.","transit:decrypt":"Open a portable `kc:` ciphertext with a tenant transit key. Required by creating a `decrypt` route action, which stores a standing instruction to open every matching field on every later request through that route. It is the same capability name the policy engine uses for POST /v1/decrypt. No routes scope satisfies it — managing a route is not permission to open the data flowing through it.","proxy:invoke":"Call the one-shot ephemeral proxy (any method on /v1/proxy). Required for EVERY verb — the proxy is one capability behind one handler, and a bodyless GET spends an escrowed credential exactly as a POST does. Neither proxy:read nor proxy:write satisfies it.","clients:read":"Read clients.","clients:write":"Manage clients.","webhooks:write":"Manage webhooks.","workflows:write":"Manage and execute workflows.","*:*":"Full access (all scopes)."}},"authorizationCode":{"authorizationUrl":"https://api.knoxcall.com/oauth/authorize","tokenUrl":"https://api.knoxcall.com/oauth/token","refreshUrl":"https://api.knoxcall.com/oauth/token","scopes":{"routes:read":"Read routes.","routes:write":"Create, update, and delete routes.","wrap:manifest:self":"A server credential's (Connect a server) view of GET /v1/wrap/intercept-manifest and POST /v1/wrap/egress-observations. It answers only for the server the credential belongs to - the routes assigned to that server in the requested environment whose routes:invoke:id:\u003croute_id> scope the token holds - and never lists another server's routes or the workspace's. A server credential invokes routes with routes:invoke:id:\u003croute_id>, one route per scope, by the route's id (never re-used, unlike a slug).","secrets:read":"Read secret metadata. Does NOT include retrieving a live OAuth2 access token.","secrets:oauth_token":"Retrieve a live upstream OAuth2 access token (GET /v1/secrets/{id}/oauth2/token). Distinct from secrets:read because the call refreshes the credential at the provider.","secrets:write":"Create, update, and delete secrets.","vaults:detokenize":"Turn a vault token back into its original value. Required by GET /v1/vaults/{vault}/tokens/{token}, by a token template reference in a /v1/proxy body, and by creating a `detokenize` route action. Distinct from vaults:read, which lists vaults and token metadata and never returns a value.","transit:decrypt":"Open a portable `kc:` ciphertext with a tenant transit key. Required by creating a `decrypt` route action, which stores a standing instruction to open every matching field on every later request through that route. It is the same capability name the policy engine uses for POST /v1/decrypt. No routes scope satisfies it — managing a route is not permission to open the data flowing through it.","proxy:invoke":"Call the one-shot ephemeral proxy (any method on /v1/proxy). Required for EVERY verb — the proxy is one capability behind one handler, and a bodyless GET spends an escrowed credential exactly as a POST does. Neither proxy:read nor proxy:write satisfies it.","clients:read":"Read clients.","clients:write":"Manage clients.","webhooks:write":"Manage webhooks.","workflows:write":"Manage and execute workflows.","*:*":"Full access (all scopes)."}}},"scopes":[],"schemeName":"OAuth2"}},"ff38421b-cb89-429f-8392-601071260cc3":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Legacy long-lived API key authentication via the Authorization header.\nPass your API key as: `Authorization: Bearer tk_xxx_yyy`.\n\nStandard keys (`tk_` prefix) are accepted on `api.knoxcall.com`.\nTest keys (type=test) are accepted on `sandbox.knoxcall.com`.\nEnterprise Access Keys (`AKE` prefix) are accepted on both.\n\nFully supported, but prefer the `OAuth2` scheme (or the SDKs, which handle\nOAuth for you) for new integrations.\n","scopes":[],"schemeName":"BearerAuth"}},"58b64ca8-afd4-45f9-9f3b-28ec18e9f92e":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Legacy API key authentication via the `x-api-key` header.\nThis is an alternative to Bearer token authentication for clients that cannot\nset the `Authorization` header. Prefer the `OAuth2` scheme for new integrations.\n","scopes":[],"schemeName":"ApiKeyAuth"}}},"servers":{"440891b5-f7c9-4d73-bdf4-4195929faed2":{"url":"https://api.knoxcall.com/v1","description":"Production"},"5671e780-1911-4eee-98e2-8258f0dc1ee7":{"url":"https://sandbox.knoxcall.com/v1","description":"Sandbox (test keys only)"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"oauth2","description":"OAuth 2.1 authentication — recommended for new integrations. Access tokens\n(`kc_` prefix) are minted at the root-host token endpoint\n`https://api.knoxcall.com/oauth/token` and passed as `Authorization: Bearer \u003caccess_token>`.\nPublic clients must use PKCE with the `authorization_code` grant; confidential\nclients may use `client_credentials`. The first-party SDKs and the\n`knoxcall login` CLI handle token minting, caching, refresh, and DPoP for you.\n","flows":{"clientCredentials":{"tokenUrl":"https://api.knoxcall.com/oauth/token","refreshUrl":"https://api.knoxcall.com/oauth/token","scopes":{"routes:read":"Read routes.","routes:write":"Create, update, and delete routes.","wrap:manifest:self":"A server credential's (Connect a server) view of GET /v1/wrap/intercept-manifest and POST /v1/wrap/egress-observations. It answers only for the server the credential belongs to - the routes assigned to that server in the requested environment whose routes:invoke:id:\u003croute_id> scope the token holds - and never lists another server's routes or the workspace's. A server credential invokes routes with routes:invoke:id:\u003croute_id>, one route per scope, by the route's id (never re-used, unlike a slug).","secrets:read":"Read secret metadata. Does NOT include retrieving a live OAuth2 access token.","secrets:oauth_token":"Retrieve a live upstream OAuth2 access token (GET /v1/secrets/{id}/oauth2/token). Distinct from secrets:read because the call refreshes the credential at the provider.","secrets:write":"Create, update, and delete secrets.","vaults:detokenize":"Turn a vault token back into its original value. Required by GET /v1/vaults/{vault}/tokens/{token}, by a token template reference in a /v1/proxy body, and by creating a `detokenize` route action. Distinct from vaults:read, which lists vaults and token metadata and never returns a value.","transit:decrypt":"Open a portable `kc:` ciphertext with a tenant transit key. Required by creating a `decrypt` route action, which stores a standing instruction to open every matching field on every later request through that route. It is the same capability name the policy engine uses for POST /v1/decrypt. No routes scope satisfies it — managing a route is not permission to open the data flowing through it.","proxy:invoke":"Call the one-shot ephemeral proxy (any method on /v1/proxy). Required for EVERY verb — the proxy is one capability behind one handler, and a bodyless GET spends an escrowed credential exactly as a POST does. Neither proxy:read nor proxy:write satisfies it.","clients:read":"Read clients.","clients:write":"Manage clients.","webhooks:write":"Manage webhooks.","workflows:write":"Manage and execute workflows.","*:*":"Full access (all scopes)."}},"authorizationCode":{"authorizationUrl":"https://api.knoxcall.com/oauth/authorize","tokenUrl":"https://api.knoxcall.com/oauth/token","refreshUrl":"https://api.knoxcall.com/oauth/token","scopes":{"routes:read":"Read routes.","routes:write":"Create, update, and delete routes.","wrap:manifest:self":"A server credential's (Connect a server) view of GET /v1/wrap/intercept-manifest and POST /v1/wrap/egress-observations. It answers only for the server the credential belongs to - the routes assigned to that server in the requested environment whose routes:invoke:id:\u003croute_id> scope the token holds - and never lists another server's routes or the workspace's. A server credential invokes routes with routes:invoke:id:\u003croute_id>, one route per scope, by the route's id (never re-used, unlike a slug).","secrets:read":"Read secret metadata. Does NOT include retrieving a live OAuth2 access token.","secrets:oauth_token":"Retrieve a live upstream OAuth2 access token (GET /v1/secrets/{id}/oauth2/token). Distinct from secrets:read because the call refreshes the credential at the provider.","secrets:write":"Create, update, and delete secrets.","vaults:detokenize":"Turn a vault token back into its original value. Required by GET /v1/vaults/{vault}/tokens/{token}, by a token template reference in a /v1/proxy body, and by creating a `detokenize` route action. Distinct from vaults:read, which lists vaults and token metadata and never returns a value.","transit:decrypt":"Open a portable `kc:` ciphertext with a tenant transit key. Required by creating a `decrypt` route action, which stores a standing instruction to open every matching field on every later request through that route. It is the same capability name the policy engine uses for POST /v1/decrypt. No routes scope satisfies it — managing a route is not permission to open the data flowing through it.","proxy:invoke":"Call the one-shot ephemeral proxy (any method on /v1/proxy). Required for EVERY verb — the proxy is one capability behind one handler, and a bodyless GET spends an escrowed credential exactly as a POST does. Neither proxy:read nor proxy:write satisfies it.","clients:read":"Read clients.","clients:write":"Manage clients.","webhooks:write":"Manage webhooks.","workflows:write":"Manage and execute workflows.","*:*":"Full access (all scopes)."}}},"scopes":[],"schemeName":"OAuth2"},"schema":{"title":"OAuth2 Auth","type":"string","isRequired":true,"description":"OAuth 2.1 authentication — recommended for new integrations. Access tokens\n(`kc_` prefix) are minted at the root-host token endpoint\n`https://api.knoxcall.com/oauth/token` and passed as `Authorization: Bearer \u003caccess_token>`.\nPublic clients must use PKCE with the `authorization_code` grant; confidential\nclients may use `client_credentials`. The first-party SDKs and the\n`knoxcall login` CLI handle token minting, caching, refresh, and DPoP for you.\n","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"OAuth2","name":"Authorization"}],"title":"OAuth2"},{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"Legacy long-lived API key authentication via the Authorization header.\nPass your API key as: `Authorization: Bearer tk_xxx_yyy`.\n\nStandard keys (`tk_` prefix) are accepted on `api.knoxcall.com`.\nTest keys (type=test) are accepted on `sandbox.knoxcall.com`.\nEnterprise Access Keys (`AKE` prefix) are accepted on both.\n\nFully supported, but prefer the `OAuth2` scheme (or the SDKs, which handle\nOAuth for you) for new integrations.\n","scopes":[],"schemeName":"BearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Legacy long-lived API key authentication via the Authorization header.\nPass your API key as: `Authorization: Bearer tk_xxx_yyy`.\n\nStandard keys (`tk_` prefix) are accepted on `api.knoxcall.com`.\nTest keys (type=test) are accepted on `sandbox.knoxcall.com`.\nEnterprise Access Keys (`AKE` prefix) are accepted on both.\n\nFully supported, but prefer the `OAuth2` scheme (or the SDKs, which handle\nOAuth for you) for new integrations.\n","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"BearerAuth","name":"Authorization"}],"title":"BearerAuth"},{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"x-api-key","description":"Legacy API key authentication via the `x-api-key` header.\nThis is an alternative to Bearer token authentication for clients that cannot\nset the `Authorization` header. Prefer the `OAuth2` scheme for new integrations.\n","scopes":[],"schemeName":"ApiKeyAuth"},"schema":{"title":"x-api-key","type":"string","description":"Legacy API key authentication via the `x-api-key` header.\nThis is an alternative to Bearer token authentication for clients that cannot\nset the `Authorization` header. Prefer the `OAuth2` scheme for new integrations.\n","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ApiKeyAuth","name":"x-api-key"}],"title":"ApiKeyAuth"}]},"originalFileLocation":"api-reference/openapi.yaml"},"subdomain":"knoxcall","siteName":"KnoxCall Docs","title":"Update Agent - KnoxCall Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-18T04:25:19.278Z","originalFileLocation":"api-reference/ai-gateway/agents-update.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Partially update an agent — routing, model policy, budgets, guardrails.\">\u003cmeta data-mint-head name=\"application-name\" content=\"KnoxCall Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Update Agent - KnoxCall Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Partially update an agent — routing, model policy, budgets, guardrails.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"KnoxCall Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://knoxcall.mintlify.site/_mintlify/api/og/v2?division=AI+Gateway\u0026amp;title=Update+Agent\u0026amp;description=Partially+update+an+agent+%E2%80%94+routing%2C+model+policy%2C+budgets%2C+guardrails.\u0026amp;theme=458e28fcdf805b9f0fa7d95d\u0026amp;signature=c189689ec24fcb3f9468f69be12eb11ad90f6f437343a965f4352b9f042f125e\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Update Agent - KnoxCall Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Partially update an agent — routing, model policy, budgets, guardrails.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://knoxcall.mintlify.site/_mintlify/api/og/v2?division=AI+Gateway\u0026amp;title=Update+Agent\u0026amp;description=Partially+update+an+agent+%E2%80%94+routing%2C+model+policy%2C+budgets%2C+guardrails.\u0026amp;theme=458e28fcdf805b9f0fa7d95d\u0026amp;signature=c189689ec24fcb3f9468f69be12eb11ad90f6f437343a965f4352b9f042f125e\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/knoxcall/_IxzHxtMRMl0O6k0/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"KnoxCall Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#18181B\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/ai-gateway/agents-update.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.knoxcall.com/#organization\",\"name\":\"KnoxCall Docs\",\"url\":\"https://docs.knoxcall.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/knoxcall/Hani9qeqybFGCQd1/logo/light.svg?fit=max\u0026auto=format\u0026n=Hani9qeqybFGCQd1\u0026q=85\u0026s=b6279c9a774c9ff9c8a87d6ac0065b14\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.knoxcall.com#website\",\"name\":\"KnoxCall Docs\",\"url\":\"https://docs.knoxcall.com\",\"publisher\":{\"@id\":\"https://docs.knoxcall.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update#webpage\",\"url\":\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update\",\"name\":\"Update Agent\",\"description\":\"Partially update an agent — routing, model policy, budgets, guardrails.\",\"dateModified\":\"2026-09-18T04:25:19.278Z\",\"isPartOf\":{\"@id\":\"https://docs.knoxcall.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"AI Gateway\",\"item\":\"https://docs.knoxcall.com/api-reference/ai-gateway/execute\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Update Agent\",\"item\":\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update#apireference\",\"headline\":\"Update Agent\",\"name\":\"Update Agent\",\"description\":\"Partially update an agent — routing, model policy, budgets, guardrails.\",\"url\":\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update\",\"mainEntityOfPage\":{\"@id\":\"https://docs.knoxcall.com/api-reference/ai-gateway/agents-update#webpage\"},\"dateModified\":\"2026-09-18T04:25:19.278Z\",\"publisher\":{\"@id\":\"https://docs.knoxcall.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.knoxcall.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"KnoxCall Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"KnoxCall Docs\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/ai-gateway/agents-update.md","siteName":"KnoxCall Docs","nav":{"global":{"anchors":[{"anchor":"Support","icon":"headset","href":"https://knoxcall.com"},{"anchor":"Community","icon":"message-circle","href":"https://discord.knoxcall.com"}]},"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/introduction"}]},{"tab":"API Reference","icon":"square-terminal","groups":[{"group":"Overview","icon":"book","pages":[{"title":"API Overview","href":"/api-reference/overview"},{"title":"Authentication","href":"/api-reference/authentication"},{"title":"Errors","href":"/api-reference/errors"},{"title":"The KnoxCall Response Block","href":"/api-reference/response-metadata"},{"title":"Request Headers KnoxCall Does Not Forward","href":"/api-reference/request-headers"},{"title":"Rate Limits","href":"/api-reference/rate-limits"},{"title":"Idempotency","href":"/api-reference/idempotency"},{"title":"Versioning","href":"/api-reference/versioning"},{"title":"SCIM 2.0 Provisioning","href":"/api-reference/scim"}]},{"group":"Workload Identity","icon":"id-badge","pages":[{"title":"GitHub Actions","href":"/api-reference/workload-identity/github-actions"},{"title":"Google Cloud (GCE, GKE, Cloud Run, Cloud Functions)","href":"/api-reference/workload-identity/gcp"},{"title":"AWS (Lambda, ECS, EC2, IRSA)","href":"/api-reference/workload-identity/aws"},{"title":"Azure (Functions, App Service, AKS, VMs)","href":"/api-reference/workload-identity/azure"},{"title":"Kubernetes (self-managed, EKS, GKE, AKS)","href":"/api-reference/workload-identity/kubernetes"},{"title":"HCP Terraform","href":"/api-reference/workload-identity/hcp-terraform"},{"title":"Vercel","href":"/api-reference/workload-identity/vercel"}]},{"group":"Routes","icon":"route","pages":[{"title":"List Routes","href":"/api-reference/routes/list"},{"title":"Get Route","href":"/api-reference/routes/get"},{"title":"Create Route","href":"/api-reference/routes/create"},{"title":"Update Route","href":"/api-reference/routes/update"},{"title":"Delete Route","href":"/api-reference/routes/delete"},{"title":"Get Route Logs","href":"/api-reference/routes/logs"},{"title":"Route Environments","href":"/api-reference/routes/environments"}]},{"group":"Secrets","icon":"key","pages":[{"title":"List Secrets","href":"/api-reference/secrets/list"},{"title":"Get Secret","href":"/api-reference/secrets/get"},{"title":"Create Secret","href":"/api-reference/secrets/create"},{"title":"Create OAuth2 Secret","href":"/api-reference/secrets/create-oauth2"},{"title":"Create Certificate Secret","href":"/api-reference/secrets/create-certificate"},{"title":"Update Secret Metadata","href":"/api-reference/secrets/update"},{"title":"Update Secret Value","href":"/api-reference/secrets/update-value"},{"title":"Delete Secret","href":"/api-reference/secrets/delete"},{"title":"Get OAuth2 Access Token","href":"/api-reference/secrets/oauth2-token"}]},{"group":"Clients","icon":"users","pages":[{"title":"List Clients","href":"/api-reference/clients/list"},{"title":"Get Client","href":"/api-reference/clients/get"},{"title":"Create Client","href":"/api-reference/clients/create"},{"title":"Update Client","href":"/api-reference/clients/update"},{"title":"Delete Client","href":"/api-reference/clients/delete"},{"title":"Client Credentials","href":"/api-reference/clients/credentials"}]},{"group":"Environments","icon":"layers","pages":[{"title":"List Environments","href":"/api-reference/environments/list"},{"title":"Create Environment","href":"/api-reference/environments/create"},{"title":"Update Environment","href":"/api-reference/environments/update"},{"title":"Delete Environment","href":"/api-reference/environments/delete"}]},{"group":"API Keys","icon":"key-round","pages":[{"title":"List API Keys","href":"/api-reference/api-keys/list"},{"title":"Create API Key","href":"/api-reference/api-keys/create"},{"title":"Revoke API Key","href":"/api-reference/api-keys/revoke"},{"title":"List Roles","href":"/api-reference/api-keys/roles"}]},{"group":"Webhooks","icon":"webhook","pages":[{"title":"List Webhooks","href":"/api-reference/webhooks/list"},{"title":"Get Webhook","href":"/api-reference/webhooks/get"},{"title":"Create Webhook","href":"/api-reference/webhooks/create"},{"title":"Update Webhook","href":"/api-reference/webhooks/update"},{"title":"Delete Webhook","href":"/api-reference/webhooks/delete"},{"title":"Get Webhook Logs","href":"/api-reference/webhooks/logs"},{"title":"List Event Types","href":"/api-reference/webhooks/event-types"},{"title":"Test Webhook","href":"/api-reference/webhooks/test"}]},{"group":"Ephemeral Proxy","icon":"zap","pages":[{"title":"Invoke Ephemeral Proxy","href":"/api-reference/ephemeral-proxy/invoke"}]},{"group":"AI Gateway","icon":"bot","pages":[{"title":"Execute AI Request","openapi":"POST /v1/ai/{agentSlug}/{upstreamPath}","href":"/api-reference/ai-gateway/execute"},{"title":"Control Plane (v1)","href":"/api-reference/ai-gateway/control-plane-overview"},{"title":"Gateways (v1)","href":"/api-reference/ai-gateway/gateways"},{"title":"Agents (v1)","href":"/api-reference/ai-gateway/agents"},{"title":"Tokens (v1)","href":"/api-reference/ai-gateway/tokens"},{"title":"Usage \u0026 Cost (v1)","openapi":"GET /ai-gateway/usage","href":"/api-reference/ai-gateway/usage"},{"title":"List Gateways","openapi":"GET /ai-gateway/gateways","href":"/api-reference/ai-gateway/gateways-list"},{"title":"Create Gateway","openapi":"POST /ai-gateway/gateways","href":"/api-reference/ai-gateway/gateways-create"},{"title":"Get Gateway","openapi":"GET /ai-gateway/gateways/{id}","href":"/api-reference/ai-gateway/gateways-get"},{"title":"Update Gateway","openapi":"PATCH /ai-gateway/gateways/{id}","href":"/api-reference/ai-gateway/gateways-update"},{"title":"Archive Gateway","openapi":"DELETE /ai-gateway/gateways/{id}","href":"/api-reference/ai-gateway/gateways-delete"},{"title":"Create Agent","openapi":"POST /ai-gateway/gateways/{gatewayId}/agents","href":"/api-reference/ai-gateway/agents-create"},{"title":"List Agents","openapi":"GET /ai-gateway/gateways/{gatewayId}/agents","href":"/api-reference/ai-gateway/agents-list"},{"title":"Get Agent","description":"Read one agent and its full configuration.","openapi":"GET /ai-gateway/agents/{id}","href":"/api-reference/ai-gateway/agents-get"},{"title":"Update Agent","openapi":"PATCH /ai-gateway/agents/{id}","href":"/api-reference/ai-gateway/agents-update"},{"title":"Archive Agent","description":"Take an agent out of service and disable the upstream route it orphans.","openapi":"DELETE /ai-gateway/agents/{id}","href":"/api-reference/ai-gateway/agents-delete"},{"title":"List Phantom Tokens","openapi":"GET /ai-gateway/agents/{agentId}/tokens","href":"/api-reference/ai-gateway/tokens-list"},{"title":"Mint Phantom Token","openapi":"POST /ai-gateway/agents/{agentId}/tokens","href":"/api-reference/ai-gateway/tokens-mint"},{"title":"Revoke Phantom Token","openapi":"DELETE /ai-gateway/agents/{agentId}/tokens/{tokenId}","href":"/api-reference/ai-gateway/tokens-revoke"},{"title":"Workload Token Exchange","href":"/api-reference/ai-gateway/oauth-token"},{"title":"List Gateway Tokens","openapi":"GET /ai-gateway/gateways/{gatewayId}/tokens","href":"/api-reference/ai-gateway/gateway-tokens-list"},{"title":"Revoke a Gateway Token","openapi":"DELETE /ai-gateway/gateways/{gatewayId}/tokens/{tokenId}","href":"/api-reference/ai-gateway/gateway-tokens-revoke"},{"title":"List Firewall Policies","openapi":"GET /ai-gateway/firewall-policies","href":"/api-reference/ai-gateway/firewall-policies-list"},{"title":"Create a Firewall Policy","openapi":"POST /ai-gateway/firewall-policies","href":"/api-reference/ai-gateway/firewall-policies-create"},{"title":"Test Firewall Rules","openapi":"POST /ai-gateway/firewall-policies/test","href":"/api-reference/ai-gateway/firewall-policies-test"},{"title":"Get a Firewall Policy","openapi":"GET /ai-gateway/firewall-policies/{id}","href":"/api-reference/ai-gateway/firewall-policies-get"},{"title":"Update a Firewall Policy","openapi":"PATCH /ai-gateway/firewall-policies/{id}","href":"/api-reference/ai-gateway/firewall-policies-update"},{"title":"Delete a Firewall Policy","openapi":"DELETE /ai-gateway/firewall-policies/{id}","href":"/api-reference/ai-gateway/firewall-policies-delete"},{"title":"List MCP Servers","openapi":"GET /ai-gateway/gateways/{gatewayId}/mcp-servers","href":"/api-reference/ai-gateway/mcp-servers-list"},{"title":"Create an MCP Server","openapi":"POST /ai-gateway/gateways/{gatewayId}/mcp-servers","href":"/api-reference/ai-gateway/mcp-servers-create"},{"title":"Get an MCP Server","openapi":"GET /ai-gateway/mcp-servers/{id}","href":"/api-reference/ai-gateway/mcp-servers-get"},{"title":"Update an MCP Server","openapi":"PATCH /ai-gateway/mcp-servers/{id}","href":"/api-reference/ai-gateway/mcp-servers-update"},{"title":"Archive an MCP Server","openapi":"DELETE /ai-gateway/mcp-servers/{id}","href":"/api-reference/ai-gateway/mcp-servers-delete"},{"title":"List MCP Tools","openapi":"GET /ai-gateway/mcp-servers/{id}/tools","href":"/api-reference/ai-gateway/mcp-tools-list"},{"title":"Add or Replace an MCP Tool","openapi":"POST /ai-gateway/mcp-servers/{id}/tools","href":"/api-reference/ai-gateway/mcp-tools-upsert"},{"title":"Update an MCP Tool","openapi":"PATCH /ai-gateway/mcp-servers/{id}/tools/{toolId}","href":"/api-reference/ai-gateway/mcp-tools-update"},{"title":"Delete an MCP Tool","openapi":"DELETE /ai-gateway/mcp-servers/{id}/tools/{toolId}","href":"/api-reference/ai-gateway/mcp-tools-delete"},{"title":"List MCP Connections","openapi":"GET /ai-gateway/mcp-servers/{id}/grants","href":"/api-reference/ai-gateway/mcp-grants-list"},{"title":"Revoke an MCP Connection","openapi":"DELETE /ai-gateway/mcp-servers/{id}/grants/{grantId}","href":"/api-reference/ai-gateway/mcp-grants-revoke"},{"title":"Revoke All MCP Connections","openapi":"DELETE /ai-gateway/mcp-servers/{id}/grants","href":"/api-reference/ai-gateway/mcp-grants-revoke-all"},{"title":"Export Usage (CSV)","openapi":"GET /ai-gateway/usage/export","href":"/api-reference/ai-gateway/usage-export"},{"title":"List PII Policies","openapi":"GET /ai-gateway/pii-policies","href":"/api-reference/ai-gateway/pii-policies-list"},{"title":"Create a PII Policy","openapi":"POST /ai-gateway/pii-policies","href":"/api-reference/ai-gateway/pii-policies-create"},{"title":"Get a PII Policy","openapi":"GET /ai-gateway/pii-policies/{id}","href":"/api-reference/ai-gateway/pii-policies-get"},{"title":"Update a PII Policy","openapi":"PATCH /ai-gateway/pii-policies/{id}","href":"/api-reference/ai-gateway/pii-policies-update"},{"title":"Delete a PII Policy","openapi":"DELETE /ai-gateway/pii-policies/{id}","href":"/api-reference/ai-gateway/pii-policies-delete"},{"title":"List PII Recognizers","openapi":"GET /ai-gateway/pii-recognizers","href":"/api-reference/ai-gateway/pii-recognizers-list"},{"title":"Create a PII Recognizer","openapi":"POST /ai-gateway/pii-recognizers","href":"/api-reference/ai-gateway/pii-recognizers-create"},{"title":"Test a Recognizer Pattern","openapi":"POST /ai-gateway/pii-recognizers/test","href":"/api-reference/ai-gateway/pii-recognizers-test"},{"title":"Get a PII Recognizer","openapi":"GET /ai-gateway/pii-recognizers/{id}","href":"/api-reference/ai-gateway/pii-recognizers-get"},{"title":"Update a PII Recognizer","openapi":"PATCH /ai-gateway/pii-recognizers/{id}","href":"/api-reference/ai-gateway/pii-recognizers-update"},{"title":"Delete a PII Recognizer","openapi":"DELETE /ai-gateway/pii-recognizers/{id}","href":"/api-reference/ai-gateway/pii-recognizers-delete"}]},{"group":"Audit Logs","icon":"file-text","pages":[{"title":"List Audit Logs","href":"/api-reference/audit-logs/list"},{"title":"SHA-256 Hash Chain — Critical Audit Chain","href":"/api-reference/audit-logs/chain"}]},{"group":"Account","icon":"building","pages":[{"title":"Get Account Info","href":"/api-reference/account/get"},{"title":"Get Current Usage","href":"/api-reference/account/usage"}]},{"group":"Tenant KMS","icon":"shield-check","pages":[{"title":"Onboard / Configure KMS","href":"/api-reference/tenant-kms/onboard"},{"title":"Get KMS Status","href":"/api-reference/tenant-kms/status"},{"title":"Unseal","href":"/api-reference/tenant-kms/unseal"},{"title":"Rotate Master Key","href":"/api-reference/tenant-kms/rotate"},{"title":"Revert to Operator-Managed Key","href":"/api-reference/tenant-kms/revert"},{"title":"Error Reference","href":"/api-reference/tenant-kms/errors"}]},{"group":"Secret Store Migrations","icon":"arrow-right-left","pages":[{"title":"List Migrations","href":"/api-reference/migrations/list"},{"title":"Create Migration","href":"/api-reference/migrations/create"},{"title":"Get Migration","href":"/api-reference/migrations/get"},{"title":"Cancel Migration","href":"/api-reference/migrations/cancel"},{"title":"Reveal Item Value","href":"/api-reference/migrations/items-reveal"},{"title":"Approve Migration Item","href":"/api-reference/migrations/items-approve"},{"title":"Reject Migration Item","href":"/api-reference/migrations/items-reject"},{"title":"Commit Migration","href":"/api-reference/migrations/commit"},{"title":"Verification Events","href":"/api-reference/migrations/verification-events"},{"title":"DB Proxy Routes","href":"/api-reference/migrations/db-proxy-routes"}]},{"group":"Changelog","icon":"history","pages":[{"title":"Changelog","href":"/api-reference/changelog"}]}]}]},"basePath":"","title":"Update Agent - KnoxCall Docs","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":["c2aa737661","b0f84f53ff","a9bb46feb3","2b790eda92"],"chunks":["OpenApiReferenceProvider-CiUHMMOm.js","snippetPresets-BgfXU7Bw.js","utils-DWvOwgy_.js","style-to-object-BY3JEAdk.js","utils-BN7RXSMJ.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-CFw8bq89.js","conditional-requirements-CFM0id0Q.js","cloneDeep-CAwdfOU2.js","_Uint8Array-BJr8e-ZL.js","isObject-FP1Yky1u.js","Page-CVJ-f_k1.js","CodeSnippet-D_HwgQO_.js","DynamicMarkdown-CQM9Bhbv.js","SectionHeading-DpbrP8nQ.js","icon-BPCgijHy.js","ApiExamples-XX0UgMZK.js","usePlaygroundInputsStore-DXDFSa1V.js","shallow-CdX5aREi.js","isEqual-CoOaxexF.js","CodeSnippets-Cg2wpzWm.js","getApiPlaygroundDisplay-CmCoerhe.js","MethodPill-GQ8DuY0c.js","getPastedJson-Cb5mT31m.js","Check2Icon-a7bUI6e8.js","axios-CsQoIw0U.js","Markdown-CX2QY19L.js","AssistantPageLink-CY3bFglh.js","dist-Dl6_zDnT.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}