API v1

Agents

Agents CRUD

Update Ai Agent

Update an existing AI agent's configuration, tools, or knowledge bases. Use deploy=true to apply changes immediately.

patch/v1/agents/{agent_id}

Request

Base URL
https://api.xpander.ai (the document declares no server; this is the origin it was published from)
Auth
API key in header x-api-key

Path parameters

agent_idstring required

Query parameters

deployboolean

Automatically deploy the agent after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call.

Request body

default_user_idstring nullable

Fallback organization user for unattended executions; also used for user budgets and usage attribution.

background_user_overridesobject nullable

organization_idstring nullable

Set automatically by the API service from the authenticated request.

agent_idstring nullable

Set automatically by the API service from the URL path parameter.

namestring nullable

Human-readable name for the agent.

descriptionstring nullable

A brief description of what the agent does.

iconstring nullable

Emoji icon displayed next to the agent name.

avatarstring nullable

Avatar identifier for the agent's visual representation.

type'manager' | 'regular' | 'a2a' | 'curl' | 'orchestration'

Enumeration of the agent types.

Attributes: Manager: marks the agent as a Managing agent. Regular: marks the agent as a regular agent. A2A: marks the agent as an external agent used via A2A protocol. Curl: marks the agent as an external agent used via a CURL. Orchestration: marks the agent as an Orchestration object.

status'DRAFT' | 'ACTIVE' | 'INACTIVE'

Enumeration of possible agent statuses.

Attributes: DRAFT: Agent is in a draft state. ACTIVE: Agent is active and operational. INACTIVE: Agent is inactive and not operational.

model_namestring nullable

The specific model identifier.

llm_reasoning_effort'low' | 'medium' | 'high' | 'xhigh'

llm_api_basestring nullable

Custom API base URL for the LLM provider.

llm_credentials_keystring nullable

Reference key to stored LLM API credentials.

llm_credentials_key_type'xpander' | 'custom'

llm_extra_headersobject nullable

Additional HTTP headers for LLM requests.

expected_outputstring nullable

Description of expected output format.

output_format'text' | 'markdown' | 'json' | 'voice'

output_schemaobject nullable

JSON Schema for structured output.

frameworkstring nullable

Execution framework.

deep_planningboolean nullable

Enable deep planning mode.

enforce_deep_planningboolean nullable

Force deep planning for all tasks.

deployment_type'serverless' | 'container'

access_scope'personal' | 'organizational' | 'project'

environment_idstring nullable

Target deployment environment.

voice_idstring nullable

Voice ID for TTS output.

using_nemoboolean nullable

Enable NeMo guardrails.

is_supervisedboolean nullable

Enable supervised mode.

is_autonomousboolean nullable

Run the agent in autonomous mode.

discoverableboolean nullable

Omni's entry on the agent's caller list: Omni finds the agent and can send it tasks. Changing it is for the agent owner or an organization admin.

with_auto_context_managementboolean nullable

Run the SDK automatic context optimizer.

developer_accessboolean nullable

Allow invocation from the developer API and webhooks.

should_stage_before_publishboolean nullable

Stage edits as a draft before publishing. Ignored for agents while drafts are off (the default): every edit saves to live.

gated_commandsobject[] nullable

Approval-required workspace commands: a list of {match, unless?, note?, approvers?, channels?}. match is the LITERAL command text (a plain substring, no regex, no escaping); unless names a safe variant that stays exempt (e.g. '--dry-run'). A workspace command containing a match is held for a person's approval before it runs - even on an autonomous/scheduled run. approvers ({user_ids, group_ids}) names who is asked; omit it and the agent's owner is asked. channels (e.g. ['slack']) routes the notification; omit it and each approver's own preferences decide.

can_self_scheduleboolean nullable

Allow the agent to schedule its own future runs.

can_archive_conversationsboolean nullable

Allow the agent to archive and restore its own conversations.

max_self_schedulesinteger nullable

Per-task lifetime cap on chained self-schedules.

on_prem_event_streamingboolean nullable

Enable event streaming.

use_oidc_pre_authboolean nullable

Enable OIDC pre-authentication.

pre_auth_audiencesstring[] nullable

Allowed OIDC audiences.

use_oidc_pre_auth_token_for_llmboolean nullable

Forward OIDC token to LLM.

oidc_pre_auth_token_llm_audiencestring nullable

OIDC audience for LLM access.

oidc_pre_auth_token_mcp_audiencestring nullable

OIDC audience for MCP access.

Response

Successful Response

idstring nullable

unique_namestring nullable

origin_templatestring nullable

environment_idstring nullable

runtime_environment_idstring nullable

deployment_type'serverless' | 'container'

promptsstring[] nullable

is_latestboolean nullable

has_pending_changesboolean nullable

deep_planningboolean nullable

enforce_deep_planningboolean nullable

use_agent_gatewayboolean nullable

namestring required

frameworkstring nullable

descriptionstring nullable

iconstring nullable

avatarstring nullable

access_scope'personal' | 'organizational' | 'project'

project_idstring nullable

oasobject nullable

is_omniboolean nullable

kind'gateway' | 'cloud_code'

A platform-made agent: the gateway one is hidden from lists, counts and delegation; every kind stays out of the agents quota.

skillsobject[] nullable

runtime_environmentobject nullable

company_brain_enabledboolean

agent_brainsstring[] nullable

secret_bindingsobject[] nullable

required_secretsobject[]

gated_commandsobject[] nullable

status'DRAFT' | 'ACTIVE' | 'INACTIVE'

Enumeration of possible agent statuses.

Attributes: DRAFT: Agent is in a draft state. ACTIVE: Agent is active and operational. INACTIVE: Agent is inactive and not operational.

versioninteger nullable

organization_idstring required

created_bystring nullable

default_user_idstring nullable

Organization user to run as when a non-UI invocation has no resolved user.

background_user_overridesobject

created_atstring date-time nullable

type'manager' | 'regular' | 'a2a' | 'curl' | 'orchestration'

Enumeration of the agent types.

using_nemoboolean nullable

deletableboolean nullable

model_namestring nullable

llm_reasoning_effort'low' | 'medium' | 'high' | 'xhigh'

llm_api_basestring nullable

output_format'text' | 'markdown' | 'json' | 'voice'

voice_idstring nullable

output_schemaobject nullable

llm_credentials_keystring nullable

llm_credentials_key_type'xpander' | 'custom'

llm_extra_headersobject nullable

expected_outputstring nullable

on_prem_event_streamingboolean nullable

is_supervisedboolean nullable

use_oidc_pre_authboolean nullable

pre_auth_audiencesstring[] nullable

use_oidc_pre_auth_token_for_llmboolean nullable

oidc_pre_auth_token_llm_audiencestring nullable

oidc_pre_auth_token_mcp_audiencestring nullable

can_self_scheduleboolean nullable

can_archive_conversationsboolean nullable

max_self_schedulesinteger nullable

use_dynamic_toolsboolean nullable

workspace_tools_enabledboolean nullable

live_surface_sharing_enabledboolean nullable

is_autonomousboolean nullable

discoverableboolean nullable

conversation_retentionAgentConversationRetention

with_auto_context_managementboolean nullable

developer_accessboolean nullable

should_stage_before_publishboolean nullable

webhook_urlstring required

Changes

No recorded changes to this operation across all 4 revisions of this API.

Update Ai Agent

Request

Path parameters

Query parameters

Request body

Response 200OK

Changes

Response