BObox
AI

Extract metadata (structured)

Changed on

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/ai/extract_structured

Request

  • Base URL
    https://api.box.com/2.0
  • URL
    https://api.box.com/2.0/ai/extract_structured
  • Auth
    OAuth 2
    Authorization code: https://account.box.com/api/oauth2/authorize
    Token URL: https://api.box.com/oauth2/token

Request body

include_confidence_scoreboolean

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.

include_referenceboolean

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 request

{
  "items": [
    {
      "id": "123",
      "type": "file",
      "content": "This is file content."
    }
  ],
  "metadata_template": {
    "template_key": "invoiceTemplate",
    "type": "metadata_template",
    "scope": "enterprise_12345"
  },
  "fields": [
    {
      "key": "name",
      "description": "The name of the person.",
      "displayName": "Name",
      "prompt": "Name is the first and last name from the email address",
      "type": "enum",
      "options": [
        {
          "key": "First Name"
        },
        {
          "key": "Last Name"
        }
      ],
      "fields": [
        {
          "key": "street_name",
          "description": "The street name of the address.",
          "displayName": "Street Name",
          "prompt": "The street name from the address section",
          "type": "string",
          "options": [
            {
              "key": "First Name"
            }
          ]
        }
      ],
      "taxonomy_key": "certification_taxonomy",
      "namespace": "enterprise_123",
      "options_rules": {
        "multi_select": true,
        "selectable_levels": [
          1
        ]
      }
    }
  ],
  "ai_agent": {
    "type": "ai_agent_id",
    "id": "14031"
  },
  "include_confidence_score": true,
  "include_reference": true,
  "taxonomy_sources": [
    {
      "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.

answerAiExtractResponse required

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

created_atstring date-time required

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

completion_reasonstring

The reason the response finishes.

confidence_scoreobject

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.

referenceobject

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

Example response

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

Changes

  • c4d5303fa5c3Revision changes
    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • info

      added the non-success response with the status