Sample - Box Platform API
POST/ai/extract_structured

Extract structured metadata with Box AI

Extracts structured metadata from one or more files using a metadata template or a custom field definition. Supply items and exactly one of metadata_template or fields to define the extraction structure, and optionally provide taxonomy sources, confidence scores, references, or an AI agent. Use taxonomy_sources only with custom fields definitions.

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

7 body fields

Optional structured metadata extraction request containing source files and either a metadata template or custom fields. items is required, and exactly one of metadata_template or fields must be provided.

itemsarray<AIItemBase>required
The items to be processed by the LLM. Currently you can use files only.
metadata_templateobjectoptional
The metadata template containing the fields to extract. For your request to work, you must provide either `metadata_template` or `fields`, but not both.
fieldsarray<object>optional
The fields to be extracted from the provided items. For your request to work, you must provide either `metadata_template` or `fields`, but not both.
ai_agentobjectoptional
The AI agent configuration for structured extraction. The Standard Agent is used when this is omitted.
include_confidence_scorebooleanoptional
A flag to indicate whether confidence scores for every extracted field should be returned.
include_referencebooleanoptional
A flag to indicate whether references for every extracted field should be returned.
taxonomy_sourcesarray<AITaxonomySource>optional
The taxonomy sources to be used for the structured extraction. They can either be an existing file or a taxonomy. For your request to work, `fields` must also be provided. `taxonomy_sources` is not supported with `metadata_template`.

3 status codes
200Returns the extracted structured metadata with its creation timestamp, completion reason, and optional confidence scores, references, and AI agent information.
answerobjectrequired
AI extract response. The content of this response may vary depending on the requested configuration.
created_atstringrequired
The ISO date formatted timestamp of when the answer to the prompt was created.
completion_reasonstringoptional
The reason the response finishes.
confidence_scoreobjectoptional
The confidence score levels and numeric values for each extracted field as a JSON dictionary. This can be empty if no field could be extracted.
referenceobjectoptional
The reference for each extracted field as a JSON dictionary. This can be empty if no field could be extracted.
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

items is required and must contain 1 to 25 unique file items with id and type set to file. Provide either metadata_template or fields, but not both; fields must contain at least one field and each field requires key. Use taxonomy_sources only with fields, and a 500 is returned for an unexpected server error.