Sample - Box Platform API
POST/ai/extract

Extract freeform metadata with Box AI

Extracts freeform metadata as key-value pairs from one or more files using a supported large language model. Supply prompt and items to describe the metadata to extract and the files to process; no metadata template is required. You can optionally select an AI agent for the extraction.

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

3 body fields

Optional freeform metadata extraction request containing extraction instructions, source files, and optional agent configuration. prompt and items are required.

promptstringrequired
The prompt provided to a Large Language Model (LLM) in the request. The prompt can be up to 10000 characters long and it can be an XML or a JSON schema.
itemsarray<AIItemBase>required
The items that LLM will process. Currently, you can use files only.
ai_agentobjectoptional
The AI agent configuration to use for metadata extraction.

3 status codes
200Returns the extracted metadata answer with its creation timestamp, completion reason, and information about the models and processors used.
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.
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 and items are required. prompt must not exceed 10,000 characters, and items must contain 1 to 25 unique file items with id and type, where type must be file. A 500 is returned for an unexpected server error.