Sample - Box Platform API
POST/ai/ask

Ask a question with Box AI

Submits a question to a supported large language model using files or Box Hub content as context. Supply prompt, items, and mode to define the question and the content to process, and optionally include dialogue history, citations, or an AI agent. When querying a Box Hub, its content must have been indexed before the request.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

6 body fields

Optional AI question request containing the prompt, source items, and optional conversation or agent configuration. prompt, items, and mode are required.

modestringrequired
Box AI handles text documents with text representations up to 2MB in size, or a maximum of 25 files, whichever comes first. If the text file size exceeds 2MB, the first 2MB of text representation will be processed. Box AI handles image documents with a resolution of 1024 x 1024 pixels, with a maximum of 5 images or 5 pages for multi-page images. If the number of image or image pages exceeds 5, the first 5 images or pages will be processed. If you set mode parameter to `single_item_qa`, the items array can have one element only. Currently Box AI does not support multi-modal requests. If both images and text are sent Box AI will only process the text.
Allowed:multiple_item_qasingle_item_qa
promptstringrequired
The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.
itemsarray<AIItemAsk>required
The items to be processed by the LLM, often files. To search across and ask questions about the contents of a Box Hub, pass a single item with `type` set to `hubs`. See the item `type` property for details.
dialogue_historyarray<DialogueHistory>optional
The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response.
include_citationsbooleanoptional
A flag to indicate whether citations should be returned.
ai_agentobjectoptional
The AI agent configuration to use for answering the question.

4 status codes
200Returns the model's answer with its creation timestamp, completion reason, AI agent information, and optional citations.
answerstringrequired
The answer provided by the LLM.
created_atstringrequired
The ISO date formatted timestamp of when the answer to the prompt was created.
completion_reasonstringoptional
The reason the response finishes.
ai_agent_infoobjectoptional
The information on the models and processors used in the request.
citationsarray<TheCitationOfTheLLMSAnswerReference>optional
The citations of the LLM's answer reference.
204Returned when the request targets a Box Hub whose content is not indexed and therefore cannot be used to answer the question.
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.
defaultAn unexpected 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.

Error handling

prompt, items, and mode are required. prompt must not exceed 10,000 characters, items must contain 1 to 25 unique items, and each item must include id and type; a hubs item must be the only item. A 204 is returned when a Hub request has no indexed content, and a 500 is returned for an unexpected server error.