Skip to main content
PATCH
Update agent

Authorizations

Authorization
string
header
required

Bearer token: an organization API key (ak_…) created under Settings → API Keys, or a dashboard user session token. Agent keys (xe_…) are not accepted here. Endpoints marked as user-only in their description reject organization keys with 403.

Headers

X-Request-ID
string | null

Path Parameters

agent_id
string<uuid>
required

Body

application/json
name
string | null
description
string | null
system_prompt
string | null
purpose
string | null
Maximum string length: 4000
purpose_mode
enum<string> | null
Available options:
monitor,
enforce
source
enum<string> | null
Available options:
auto,
manual
provider_id
string<uuid> | null
owner_id
string<uuid> | null
deployment_id
string<uuid> | null
debug_payloads_until
string<date-time> | null

Response

Successful Response

id
string<uuid>
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
org_id
string<uuid>
required
owner_id
string<uuid> | null
required
name
string | null
required
description
string | null
required
system_prompt
string | null
required
status
enum<string>
required
Available options:
draft,
active
source
enum<string>
required
Available options:
auto,
manual
provider_id
string<uuid> | null
required
provider
AgentProviderSummary · object | null
required
agent_url
string
required
read-only

Endpoint base URL for this agent. Cloud agents render https://runtime.xenovia.io/{agent_id}/v1; hybrid agents render their deployment's ingress URL plus /{agent_id}/v1.

purpose
string | null
purpose_mode
enum<string>
default:monitor
Available options:
monitor,
enforce
coding_tool
string | null
platform
string | null
connected
boolean
default:false
deployment_id
string<uuid> | null
debug_payloads_until
string<date-time> | null
fallbacks
AgentFallbackRead · object[]
routing
AgentRouting · object

An agent's failover settings, always whole (every default filled).

primary_capabilities
ModelCapabilities · object | null

What a model can take, from the public model directory (models.dev); each member is null when the directory does not say (assume capable).

primary_residency
enum<string>
default:unknown
Available options:
us,
eu,
apac,
global,
unknown
hosted_tools
HostedTools · object | null

An agent's hosted tool allow-list: GET/PUT /agents/{agent_id}/hosted-tools, AgentRead.hosted_tools and the config snapshot's hosted_tools.

mode is what the runtime does with a hosted tool outside the list: enforce refuses the request, monitor records it and lets it through. mcp_servers may be set without mcp in families: it is kept and served, and the runtime allows no MCP tool while mcp is not in the families (so an admin can switch MCP off without losing the server list).

hosted_tool_families
string[]
coding_tool_hosted_tool_families
string[]
sub_agents_summary
SubAgentsSummary · object

AgentRead.sub_agents_summary: how many sub-agents of each kind.