Sample - Box Platform API
PUT/ai_agents/{agent_id}

Update an AI agent

Updates an existing AI agent and its configured capabilities. Supply the agent identifier and include the fields you want to change, including the agent's access state and any capability configuration. The response contains the complete updated AI agent representation.

1 parameter · 8 body fields
agent_idstringrequired
The unique identifier of the AI agent to update.

AI agent configuration and capability settings. The top-level type, name, and access_state fields are required; capability objects require their own type, access_state, and description fields when provided.

typestringrequired
The type of agent used to handle queries.
Allowed:ai_agent
namestringrequired
The name of the AI Agent.
access_statestringrequired
The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`.
icon_referencestringoptional
The icon reference of the AI Agent. It should have format of the URL `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/<file_name>` where possible values of `file_name` are: `logo_boxAi.png`,`logo_stamp.png`,`logo_legal.png`,`logo_finance.png`,`logo_config.png`,`logo_handshake.png`,`logo_analytics.png`,`logo_classification.png`.
allowed_entitiesarray<TheEntityWithTypeAndID>optional
List of allowed users or groups.
askobjectoptional
The AI agent to be used to handle queries.
text_genobjectoptional
The AI agent to be used to generate text.
extractobjectoptional
The AI agent to be used for metadata extraction.

3 status codes
200Returns the complete updated AI agent, including its identifier, name, access state, allowed entities, audit fields, icon reference, and configured capabilities.
idstringrequired
The unique identifier of the AI Agent.
typestringoptional
The type of agent used to handle queries.
Allowed:ai_agent
originstringrequired
The provider of the AI Agent.
namestringrequired
The name of the AI Agent.
access_statestringrequired
The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`.
created_byobjectoptional
The user who created this agent.
created_atstringoptional
The ISO date-time formatted timestamp of when this AI agent was created.
modified_byobjectoptional
The user who most recently modified this agent.
modified_atstringoptional
The ISO date-time formatted timestamp of when this AI agent was recently modified.
icon_referencestringoptional
The icon reference of the AI Agent.
allowed_entitiesarray<TheEntityWithTypeAndID>optional
List of allowed users or groups.
askobjectoptional
The AI agent to be used to ask questions.
text_genobjectoptional
The AI agent to be used to generate text.
extractobjectoptional
The AI agent to be used for metadata extraction.
400Returned when the request body or one of its fields is invalid.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
500Returned when an unexpected server error occurs.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned when the request body or one of its fields is invalid. A 500 is returned when the service encounters an unexpected server error. agent_id, type, name, and access_state must be supplied as defined by the request schema, and icon_reference must contain at least one character.