Skip to main content
POST
/
ai
/
extract_structured
cURL
curl -i -L 'https://api.box.com/2.0/ai/extract_structured' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <ACCESS_TOKEN>' \
     -d '{
        "items": [
          {
            "id": "12345678",
            "type": "file",
            "content": "This is file content."
          }
        ],
        "metadata_template": {
            "template_key": "",
            "type": "metadata_template",
            "scope": ""
        },
        "fields": [
            {
              "key": "name",
              "description": "The name of the person.",
              "displayName": "Name",
              "prompt": "The name is the first and last name from the email address.",
              "type": "string",
              "options": [
                {
                  "key": "First Name"
                },
                {
                  "key": "Last Name"
                }
              ]
            }
        ],
        "ai_agent": {
          "type": "ai_agent_extract_structured",
          "long_text": {
            "model": "azure__openai__gpt_4o_mini"
            },
          "basic_text": {
            "model": "azure__openai__gpt_4o_mini"
         }
      }
   }'
{
  "answer": {},
  "created_at": "2012-12-12T10:53:43-08:00",
  "completion_reason": "done",
  "confidence_score": {},
  "ai_agent_info": {
    "models": [
      {
        "name": "azure__openai__text_embedding_ada_002",
        "provider": "azure",
        "supported_purpose": "embedding"
      }
    ],
    "processor": "basic_text"
  }
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

AI Extract Structured Request object.

​
items
AI Item (Base) · object[]
required

The items to be processed by the LLM. Currently you can use files only.

Required array length: 1 - 25 elements
​
metadata_template
object

The metadata template containing the fields to extract. For your request to work, you must provide either metadata_template or fields, but not both.

​
fields
object[]

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.

Minimum array length: 1
​
include_confidence_score
boolean

A flag to indicate whether confidence scores for every extracted field should be returned.

Example:

true

​
ai_agent
AI agent reference · object

The AI agent to be used for the structured extraction. Defaults to the Standard Agent if not specified. If you want to use Enhanced Extract Agent, see Enhanced Extract Agent for details.

Response

A successful response including the answer from the LLM.

AI extract structured response.

​
answer
AI extract response · object
required

AI extract response. The content of this response may vary depending on the requested configuration.

​
created_at
string<date-time>
required

The ISO date formatted timestamp of when the answer to the prompt was created.

Example:

"2012-12-12T10:53:43-08:00"

​
completion_reason
string

The reason the response finishes.

Example:

"done"

​
confidence_score
object

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.

​
ai_agent_info
The information on the models and processors used in the request. · object

The information on the models and processors used in the request.