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"
         }
      }
   }'

client.ai.create_ai_extract_structured(
    [AiItemBase(id=file.id)],
    fields=[
        CreateAiExtractStructuredFields(
            key="firstName",
            display_name="First name",
            description="Person first name",
            prompt="What is the your first name?",
            type="string",
        ),
        CreateAiExtractStructuredFields(
            key="lastName",
            display_name="Last name",
            description="Person last name",
            prompt="What is the your last name?",
            type="string",
        ),
        CreateAiExtractStructuredFields(
            key="dateOfBirth",
            display_name="Birth date",
            description="Person date of birth",
            prompt="What is the date of your birth?",
            type="date",
        ),
        CreateAiExtractStructuredFields(
            key="age",
            display_name="Age",
            description="Person age",
            prompt="How old are you?",
            type="float",
        ),
        CreateAiExtractStructuredFields(
            key="hobby",
            display_name="Hobby",
            description="Person hobby",
            prompt="What is your hobby?",
            type="multiSelect",
            options=[
                CreateAiExtractStructuredFieldsOptionsField(key="guitar"),
                CreateAiExtractStructuredFieldsOptionsField(key="books"),
            ],
        ),
        CreateAiExtractStructuredFields(
            key="address",
            display_name="Address",
            description="Person address",
            type="struct",
            prompt="Extract the full mailing address.",
            fields=[
                AiExtractSubField(key="street", display_name="Street", type="string"),
                AiExtractSubField(key="city", display_name="City", type="string"),
                AiExtractSubField(key="state", display_name="State", type="string"),
                AiExtractSubField(key="zip", display_name="Zip", type="string"),
                AiExtractSubField(key="country", display_name="Country", type="string"),
            ],
        ),
        CreateAiExtractStructuredFields(
            key="work_history",
            display_name="Work history",
            description="Person work history",
            type="table",
            prompt="Extract each job as a row.",
            fields=[
                AiExtractSubField(
                    key="job_title", display_name="Job title", type="string"
                ),
                AiExtractSubField(key="company", display_name="Company", type="string"),
                AiExtractSubField(
                    key="start_year", display_name="Start year", type="string"
                ),
                AiExtractSubField(
                    key="end_year", display_name="End year", type="string"
                ),
            ],
        ),
    ],
    ai_agent=ai_extract_structured_agent_basic_text_config,
    include_confidence_score=True,
    include_reference=True,
)

await client.ai.createAiExtractStructured({
  fields: [
    {
      key: 'firstName',
      displayName: 'First name',
      description: 'Person first name',
      prompt: 'What is the your first name?',
      type: 'string',
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'lastName',
      displayName: 'Last name',
      description: 'Person last name',
      prompt: 'What is the your last name?',
      type: 'string',
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'dateOfBirth',
      displayName: 'Birth date',
      description: 'Person date of birth',
      prompt: 'What is the date of your birth?',
      type: 'date',
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'age',
      displayName: 'Age',
      description: 'Person age',
      prompt: 'How old are you?',
      type: 'float',
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'hobby',
      displayName: 'Hobby',
      description: 'Person hobby',
      prompt: 'What is your hobby?',
      type: 'multiSelect',
      options: [
        { key: 'guitar' } satisfies AiExtractStructuredFieldsOptionsField,
        { key: 'books' } satisfies AiExtractStructuredFieldsOptionsField,
      ],
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'address',
      displayName: 'Address',
      description: 'Person address',
      type: 'struct',
      prompt: 'Extract the full mailing address.',
      fields: [
        {
          key: 'street',
          displayName: 'Street',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'city',
          displayName: 'City',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'state',
          displayName: 'State',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'zip',
          displayName: 'Zip',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'country',
          displayName: 'Country',
          type: 'string',
        } satisfies AiExtractSubField,
      ],
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'work_history',
      displayName: 'Work history',
      description: 'Person work history',
      type: 'table',
      prompt: 'Extract each job as a row.',
      fields: [
        {
          key: 'job_title',
          displayName: 'Job title',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'company',
          displayName: 'Company',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'start_year',
          displayName: 'Start year',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'end_year',
          displayName: 'End year',
          type: 'string',
        } satisfies AiExtractSubField,
      ],
    } satisfies AiExtractStructuredFieldsField,
  ],
  items: [new AiItemBase({ id: file.id })],
  includeConfidenceScore: true,
  includeReference: true,
  aiAgent: aiExtractStructuredAgentBasicTextConfig,
} satisfies AiExtractStructured);

try await client.ai.createAiExtractStructured(requestBody: AiExtractStructured(fields: [AiExtractStructuredFieldsField(key: "firstName", displayName: "First name", description: "Person first name", prompt: "What is the your first name?", type: "string"), AiExtractStructuredFieldsField(key: "lastName", displayName: "Last name", description: "Person last name", prompt: "What is the your last name?", type: "string"), AiExtractStructuredFieldsField(key: "dateOfBirth", displayName: "Birth date", description: "Person date of birth", prompt: "What is the date of your birth?", type: "date"), AiExtractStructuredFieldsField(key: "age", displayName: "Age", description: "Person age", prompt: "How old are you?", type: "float"), AiExtractStructuredFieldsField(key: "hobby", displayName: "Hobby", description: "Person hobby", prompt: "What is your hobby?", type: "multiSelect", options: [AiExtractStructuredFieldsOptionsField(key: "guitar"), AiExtractStructuredFieldsOptionsField(key: "books")]), AiExtractStructuredFieldsField(key: "address", displayName: "Address", description: "Person address", type: "struct", prompt: "Extract the full mailing address.", fields: [AiExtractSubField(key: "street", displayName: "Street", type: "string"), AiExtractSubField(key: "city", displayName: "City", type: "string"), AiExtractSubField(key: "state", displayName: "State", type: "string"), AiExtractSubField(key: "zip", displayName: "Zip", type: "string"), AiExtractSubField(key: "country", displayName: "Country", type: "string")]), AiExtractStructuredFieldsField(key: "work_history", displayName: "Work history", description: "Person work history", type: "table", prompt: "Extract each job as a row.", fields: [AiExtractSubField(key: "job_title", displayName: "Job title", type: "string"), AiExtractSubField(key: "company", displayName: "Company", type: "string"), AiExtractSubField(key: "start_year", displayName: "Start year", type: "string"), AiExtractSubField(key: "end_year", displayName: "End year", type: "string")])], items: [AiItemBase(id: file.id)], includeConfidenceScore: true, includeReference: true))

client.getAi().createAiExtractStructured(new AiExtractStructured.Builder(Arrays.asList(new AiItemBase(file.getId()))).fields(Arrays.asList(new AiExtractStructuredFieldsField.Builder("firstName").description("Person first name").displayName("First name").prompt("What is the your first name?").type("string").build(), new AiExtractStructuredFieldsField.Builder("lastName").description("Person last name").displayName("Last name").prompt("What is the your last name?").type("string").build(), new AiExtractStructuredFieldsField.Builder("dateOfBirth").description("Person date of birth").displayName("Birth date").prompt("What is the date of your birth?").type("date").build(), new AiExtractStructuredFieldsField.Builder("age").description("Person age").displayName("Age").prompt("How old are you?").type("float").build(), new AiExtractStructuredFieldsField.Builder("hobby").description("Person hobby").displayName("Hobby").prompt("What is your hobby?").type("multiSelect").options(Arrays.asList(new AiExtractStructuredFieldsOptionsField("guitar"), new AiExtractStructuredFieldsOptionsField("books"))).build(), new AiExtractStructuredFieldsField.Builder("address").description("Person address").displayName("Address").prompt("Extract the full mailing address.").type("struct").fields(Arrays.asList(new AiExtractSubField.Builder("street").displayName("Street").type("string").build(), new AiExtractSubField.Builder("city").displayName("City").type("string").build(), new AiExtractSubField.Builder("state").displayName("State").type("string").build(), new AiExtractSubField.Builder("zip").displayName("Zip").type("string").build(), new AiExtractSubField.Builder("country").displayName("Country").type("string").build())).build(), new AiExtractStructuredFieldsField.Builder("work_history").description("Person work history").displayName("Work history").prompt("Extract each job as a row.").type("table").fields(Arrays.asList(new AiExtractSubField.Builder("job_title").displayName("Job title").type("string").build(), new AiExtractSubField.Builder("company").displayName("Company").type("string").build(), new AiExtractSubField.Builder("start_year").displayName("Start year").type("string").build(), new AiExtractSubField.Builder("end_year").displayName("End year").type("string").build())).build())).aiAgent(aiExtractStructuredAgentBasicTextConfig).includeConfidenceScore(true).includeReference(true).build())

await client.Ai.CreateAiExtractStructuredAsync(requestBody: new AiExtractStructured(items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})) { Fields = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsField(key: "firstName") { DisplayName = "First name", Description = "Person first name", Prompt = "What is the your first name?", Type = "string" },new AiExtractStructuredFieldsField(key: "lastName") { DisplayName = "Last name", Description = "Person last name", Prompt = "What is the your last name?", Type = "string" },new AiExtractStructuredFieldsField(key: "dateOfBirth") { DisplayName = "Birth date", Description = "Person date of birth", Prompt = "What is the date of your birth?", Type = "date" },new AiExtractStructuredFieldsField(key: "age") { DisplayName = "Age", Description = "Person age", Prompt = "How old are you?", Type = "float" },new AiExtractStructuredFieldsField(key: "hobby") { DisplayName = "Hobby", Description = "Person hobby", Prompt = "What is your hobby?", Type = "multiSelect", Options = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsOptionsField(key: "guitar"),new AiExtractStructuredFieldsOptionsField(key: "books")}) },new AiExtractStructuredFieldsField(key: "address") { DisplayName = "Address", Description = "Person address", Type = "struct", Prompt = "Extract the full mailing address.", Fields = Array.AsReadOnly(new [] {new AiExtractSubField(key: "street") { DisplayName = "Street", Type = "string" },new AiExtractSubField(key: "city") { DisplayName = "City", Type = "string" },new AiExtractSubField(key: "state") { DisplayName = "State", Type = "string" },new AiExtractSubField(key: "zip") { DisplayName = "Zip", Type = "string" },new AiExtractSubField(key: "country") { DisplayName = "Country", Type = "string" }}) },new AiExtractStructuredFieldsField(key: "work_history") { DisplayName = "Work history", Description = "Person work history", Type = "table", Prompt = "Extract each job as a row.", Fields = Array.AsReadOnly(new [] {new AiExtractSubField(key: "job_title") { DisplayName = "Job title", Type = "string" },new AiExtractSubField(key: "company") { DisplayName = "Company", Type = "string" },new AiExtractSubField(key: "start_year") { DisplayName = "Start year", Type = "string" },new AiExtractSubField(key: "end_year") { DisplayName = "End year", Type = "string" }}) }}), IncludeConfidenceScore = true, IncludeReference = true });

{
  "answer": {},
  "created_at": "2012-12-12T10:53:43-08:00",
  "completion_reason": "done",
  "confidence_score": {},
  "reference": {},
  "ai_agent_info": {
    "models": [
      {
        "name": "azure__openai__text_embedding_ada_002",
        "provider": "azure",
        "supported_purpose": "embedding"
      }
    ],
    "processor": "basic_text"
  }
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

Extract metadata (structured)

Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs.

To define the extraction structure, provide either a metadata template or a list of fields. To learn more about creating templates, see Creating metadata templates in the Admin Console or use the metadata template API.

This endpoint also supports Enhanced Extract Agent.

For information about supported file formats and languages, see the Extract metadata from file (structured) API guide.

POST

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"
         }
      }
   }'

client.ai.create_ai_extract_structured(
    [AiItemBase(id=file.id)],
    fields=[
        CreateAiExtractStructuredFields(
            key="firstName",
            display_name="First name",
            description="Person first name",
            prompt="What is the your first name?",
            type="string",
        ),
        CreateAiExtractStructuredFields(
            key="lastName",
            display_name="Last name",
            description="Person last name",
            prompt="What is the your last name?",
            type="string",
        ),
        CreateAiExtractStructuredFields(
            key="dateOfBirth",
            display_name="Birth date",
            description="Person date of birth",
            prompt="What is the date of your birth?",
            type="date",
        ),
        CreateAiExtractStructuredFields(
            key="age",
            display_name="Age",
            description="Person age",
            prompt="How old are you?",
            type="float",
        ),
        CreateAiExtractStructuredFields(
            key="hobby",
            display_name="Hobby",
            description="Person hobby",
            prompt="What is your hobby?",
            type="multiSelect",
            options=[
                CreateAiExtractStructuredFieldsOptionsField(key="guitar"),
                CreateAiExtractStructuredFieldsOptionsField(key="books"),
            ],
        ),
        CreateAiExtractStructuredFields(
            key="address",
            display_name="Address",
            description="Person address",
            type="struct",
            prompt="Extract the full mailing address.",
            fields=[
                AiExtractSubField(key="street", display_name="Street", type="string"),
                AiExtractSubField(key="city", display_name="City", type="string"),
                AiExtractSubField(key="state", display_name="State", type="string"),
                AiExtractSubField(key="zip", display_name="Zip", type="string"),
                AiExtractSubField(key="country", display_name="Country", type="string"),
            ],
        ),
        CreateAiExtractStructuredFields(
            key="work_history",
            display_name="Work history",
            description="Person work history",
            type="table",
            prompt="Extract each job as a row.",
            fields=[
                AiExtractSubField(
                    key="job_title", display_name="Job title", type="string"
                ),
                AiExtractSubField(key="company", display_name="Company", type="string"),
                AiExtractSubField(
                    key="start_year", display_name="Start year", type="string"
                ),
                AiExtractSubField(
                    key="end_year", display_name="End year", type="string"
                ),
            ],
        ),
    ],
    ai_agent=ai_extract_structured_agent_basic_text_config,
    include_confidence_score=True,
    include_reference=True,
)

await client.ai.createAiExtractStructured({
  fields: [
    {
      key: 'firstName',
      displayName: 'First name',
      description: 'Person first name',
      prompt: 'What is the your first name?',
      type: 'string',
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'lastName',
      displayName: 'Last name',
      description: 'Person last name',
      prompt: 'What is the your last name?',
      type: 'string',
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'dateOfBirth',
      displayName: 'Birth date',
      description: 'Person date of birth',
      prompt: 'What is the date of your birth?',
      type: 'date',
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'age',
      displayName: 'Age',
      description: 'Person age',
      prompt: 'How old are you?',
      type: 'float',
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'hobby',
      displayName: 'Hobby',
      description: 'Person hobby',
      prompt: 'What is your hobby?',
      type: 'multiSelect',
      options: [
        { key: 'guitar' } satisfies AiExtractStructuredFieldsOptionsField,
        { key: 'books' } satisfies AiExtractStructuredFieldsOptionsField,
      ],
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'address',
      displayName: 'Address',
      description: 'Person address',
      type: 'struct',
      prompt: 'Extract the full mailing address.',
      fields: [
        {
          key: 'street',
          displayName: 'Street',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'city',
          displayName: 'City',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'state',
          displayName: 'State',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'zip',
          displayName: 'Zip',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'country',
          displayName: 'Country',
          type: 'string',
        } satisfies AiExtractSubField,
      ],
    } satisfies AiExtractStructuredFieldsField,
    {
      key: 'work_history',
      displayName: 'Work history',
      description: 'Person work history',
      type: 'table',
      prompt: 'Extract each job as a row.',
      fields: [
        {
          key: 'job_title',
          displayName: 'Job title',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'company',
          displayName: 'Company',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'start_year',
          displayName: 'Start year',
          type: 'string',
        } satisfies AiExtractSubField,
        {
          key: 'end_year',
          displayName: 'End year',
          type: 'string',
        } satisfies AiExtractSubField,
      ],
    } satisfies AiExtractStructuredFieldsField,
  ],
  items: [new AiItemBase({ id: file.id })],
  includeConfidenceScore: true,
  includeReference: true,
  aiAgent: aiExtractStructuredAgentBasicTextConfig,
} satisfies AiExtractStructured);

try await client.ai.createAiExtractStructured(requestBody: AiExtractStructured(fields: [AiExtractStructuredFieldsField(key: "firstName", displayName: "First name", description: "Person first name", prompt: "What is the your first name?", type: "string"), AiExtractStructuredFieldsField(key: "lastName", displayName: "Last name", description: "Person last name", prompt: "What is the your last name?", type: "string"), AiExtractStructuredFieldsField(key: "dateOfBirth", displayName: "Birth date", description: "Person date of birth", prompt: "What is the date of your birth?", type: "date"), AiExtractStructuredFieldsField(key: "age", displayName: "Age", description: "Person age", prompt: "How old are you?", type: "float"), AiExtractStructuredFieldsField(key: "hobby", displayName: "Hobby", description: "Person hobby", prompt: "What is your hobby?", type: "multiSelect", options: [AiExtractStructuredFieldsOptionsField(key: "guitar"), AiExtractStructuredFieldsOptionsField(key: "books")]), AiExtractStructuredFieldsField(key: "address", displayName: "Address", description: "Person address", type: "struct", prompt: "Extract the full mailing address.", fields: [AiExtractSubField(key: "street", displayName: "Street", type: "string"), AiExtractSubField(key: "city", displayName: "City", type: "string"), AiExtractSubField(key: "state", displayName: "State", type: "string"), AiExtractSubField(key: "zip", displayName: "Zip", type: "string"), AiExtractSubField(key: "country", displayName: "Country", type: "string")]), AiExtractStructuredFieldsField(key: "work_history", displayName: "Work history", description: "Person work history", type: "table", prompt: "Extract each job as a row.", fields: [AiExtractSubField(key: "job_title", displayName: "Job title", type: "string"), AiExtractSubField(key: "company", displayName: "Company", type: "string"), AiExtractSubField(key: "start_year", displayName: "Start year", type: "string"), AiExtractSubField(key: "end_year", displayName: "End year", type: "string")])], items: [AiItemBase(id: file.id)], includeConfidenceScore: true, includeReference: true))

client.getAi().createAiExtractStructured(new AiExtractStructured.Builder(Arrays.asList(new AiItemBase(file.getId()))).fields(Arrays.asList(new AiExtractStructuredFieldsField.Builder("firstName").description("Person first name").displayName("First name").prompt("What is the your first name?").type("string").build(), new AiExtractStructuredFieldsField.Builder("lastName").description("Person last name").displayName("Last name").prompt("What is the your last name?").type("string").build(), new AiExtractStructuredFieldsField.Builder("dateOfBirth").description("Person date of birth").displayName("Birth date").prompt("What is the date of your birth?").type("date").build(), new AiExtractStructuredFieldsField.Builder("age").description("Person age").displayName("Age").prompt("How old are you?").type("float").build(), new AiExtractStructuredFieldsField.Builder("hobby").description("Person hobby").displayName("Hobby").prompt("What is your hobby?").type("multiSelect").options(Arrays.asList(new AiExtractStructuredFieldsOptionsField("guitar"), new AiExtractStructuredFieldsOptionsField("books"))).build(), new AiExtractStructuredFieldsField.Builder("address").description("Person address").displayName("Address").prompt("Extract the full mailing address.").type("struct").fields(Arrays.asList(new AiExtractSubField.Builder("street").displayName("Street").type("string").build(), new AiExtractSubField.Builder("city").displayName("City").type("string").build(), new AiExtractSubField.Builder("state").displayName("State").type("string").build(), new AiExtractSubField.Builder("zip").displayName("Zip").type("string").build(), new AiExtractSubField.Builder("country").displayName("Country").type("string").build())).build(), new AiExtractStructuredFieldsField.Builder("work_history").description("Person work history").displayName("Work history").prompt("Extract each job as a row.").type("table").fields(Arrays.asList(new AiExtractSubField.Builder("job_title").displayName("Job title").type("string").build(), new AiExtractSubField.Builder("company").displayName("Company").type("string").build(), new AiExtractSubField.Builder("start_year").displayName("Start year").type("string").build(), new AiExtractSubField.Builder("end_year").displayName("End year").type("string").build())).build())).aiAgent(aiExtractStructuredAgentBasicTextConfig).includeConfidenceScore(true).includeReference(true).build())

await client.Ai.CreateAiExtractStructuredAsync(requestBody: new AiExtractStructured(items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})) { Fields = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsField(key: "firstName") { DisplayName = "First name", Description = "Person first name", Prompt = "What is the your first name?", Type = "string" },new AiExtractStructuredFieldsField(key: "lastName") { DisplayName = "Last name", Description = "Person last name", Prompt = "What is the your last name?", Type = "string" },new AiExtractStructuredFieldsField(key: "dateOfBirth") { DisplayName = "Birth date", Description = "Person date of birth", Prompt = "What is the date of your birth?", Type = "date" },new AiExtractStructuredFieldsField(key: "age") { DisplayName = "Age", Description = "Person age", Prompt = "How old are you?", Type = "float" },new AiExtractStructuredFieldsField(key: "hobby") { DisplayName = "Hobby", Description = "Person hobby", Prompt = "What is your hobby?", Type = "multiSelect", Options = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsOptionsField(key: "guitar"),new AiExtractStructuredFieldsOptionsField(key: "books")}) },new AiExtractStructuredFieldsField(key: "address") { DisplayName = "Address", Description = "Person address", Type = "struct", Prompt = "Extract the full mailing address.", Fields = Array.AsReadOnly(new [] {new AiExtractSubField(key: "street") { DisplayName = "Street", Type = "string" },new AiExtractSubField(key: "city") { DisplayName = "City", Type = "string" },new AiExtractSubField(key: "state") { DisplayName = "State", Type = "string" },new AiExtractSubField(key: "zip") { DisplayName = "Zip", Type = "string" },new AiExtractSubField(key: "country") { DisplayName = "Country", Type = "string" }}) },new AiExtractStructuredFieldsField(key: "work_history") { DisplayName = "Work history", Description = "Person work history", Type = "table", Prompt = "Extract each job as a row.", Fields = Array.AsReadOnly(new [] {new AiExtractSubField(key: "job_title") { DisplayName = "Job title", Type = "string" },new AiExtractSubField(key: "company") { DisplayName = "Company", Type = "string" },new AiExtractSubField(key: "start_year") { DisplayName = "Start year", Type = "string" },new AiExtractSubField(key: "end_year") { DisplayName = "End year", Type = "string" }}) }}), IncludeConfidenceScore = true, IncludeReference = true });

{
  "answer": {},
  "created_at": "2012-12-12T10:53:43-08:00",
  "completion_reason": "done",
  "confidence_score": {},
  "reference": {},
  "ai_agent_info": {
    "models": [
      {
        "name": "azure__openai__text_embedding_ada_002",
        "provider": "azure",
        "supported_purpose": "embedding"
      }
    ],
    "processor": "basic_text"
  }
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

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

Show child attributes

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.

Show child attributes

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

Show child attributes

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.

AI agent reference
AI agent for structured extract request

Show child attributes

include_confidence_score

boolean

A flag to indicate whether confidence scores for every extracted field should be returned. Estimates the likelihood that an extracted metadata field value is accurate and correct. Displays a numerical and categorical confidence score to help users and automated systems quickly determine extraction reliability.

Example:

true

include_reference

boolean

A flag to indicate whether references for every extracted field should be returned. References and bounding boxes show where the agent extracted the metadata from. They help you check for accuracy and fix any mistakes. References are short, exact quotes from the original document used to verify results. Bounding boxes highlight the specific areas on the page where that text is found.

Example:

true

taxonomy_sources

(AI Taxonomy Reference · object | AI Taxonomy File Reference · object)[]

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.

A taxonomy source to be used for the structured extraction. For your request to work, fields must also be provided.

AI Taxonomy Reference
AI Taxonomy File Reference

Show child attributes

Example:

[
  {
    "type": "taxonomy",
    "taxonomy_key": "certification_taxonomy",
    "namespace": "enterprise_123"
  },
  {
    "type": "file",
    "taxonomy_key": "industry_taxonomy",
    "id": "1234567890"
  }
]

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.

Show child attributes

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.

Show child attributes

reference

object

The reference for each extracted field as a JSON dictionary. This can be empty if no field could be extracted.

Show child attributes

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.

Show child attributes

Last modified on January 23, 2026

API reference

API reference

API reference

Extract metadata (structured)

Authorizations

Body

Response