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

Get an AI agent

Retrieves an AI agent by its identifier. Use fields to limit the properties included in the response when you need only selected agent details. The response contains the agent's identity, origin, name, access state, and configured capabilities.

2 parameters
agent_idstringrequired
The unique identifier of the AI agent to retrieve.
fieldsarray<string>optional
The fields to include in the returned AI agent representation.

3 status codes
200Returns the full AI agent representation, including its identifier, origin, name, access state, 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 contains an unexpected client error.
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

agent_id must identify the AI agent to retrieve. Use fields to request specific response properties, and a 400 is returned for an unexpected client error while a 500 indicates an unexpected server error.