Box Developer Documentation
 
    Beta

    Extract metadata (structured)

    post
    https://api.box.com/2.0
    /ai/extract_structured

    This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

    Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs. For this request, you either need a metadata template or a list of fields you want to extract. Input is either a metadata template or a list of fields to ensure the structure. To learn more about creating templates, see Creating metadata templates in the Admin Console or use the metadata template API.

    Request

    bearer [ACCESS_TOKEN]
    application/json

    Request Body

    The AI agent to be used for structured extraction.

    object arrayin bodyoptional

    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.

    stringin bodyoptional
    "enum"

    The type of the field. It include but is not limited to string, float, date, enum, and multiSelect.

    stringin bodyoptional
    "The name of the person."

    A description of the field.

    stringin bodyoptional
    "Name"

    The display name of the field.

    stringin bodyconditionally required
    "name"

    A unique identifier for the field.

    object arrayin bodyoptional
    [{"key":"First Name"},{"key":"Last Name"}]

    A list of options for this field. This is most often used in combination with the enum and multiSelect field types.

    stringin bodyconditionally required
    "First Name"

    A unique identifier for the field.

    stringin bodyoptional
    "Name is the first and last name from the email address"

    The context about the key that may include how to find and format it.

    object arrayin bodyrequired

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

    stringin bodyrequired
    "123"

    The ID of the file.

    stringin bodyrequired
    "file"

    The type of the item. Currently the value can be file only.

    Value is always file

    stringin bodyoptional
    "This is file content."

    The content of the item, often the text representation.

    objectin body

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

    stringin bodyoptional
    "metadata_template"

    Value is always metadata_template.

    Value is always metadata_template

    stringin bodyoptional
    "enterprise_12345"
    40

    The scope of the metadata template that can either be global or enterprise.

    • The global scope is used for templates that are available to any Box enterprise.
    • The enterprise scope represents templates created within a specific enterprise, containing the ID of that enterprise.
    stringin bodyoptional
    "invoiceTemplate"

    The name of the metadata template.

    Response

    application/jsonAI response

    A successful response including the answer from the LLM.

    application/jsonClient error

    An unexpected server error.

    application/jsonClient error

    An unexpected error.

    post
    Extract metadata (structured)
    You can now try out some of our APIs live, right here in the documentation.
    Log in

    Request Example

    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",
              "long_text": {
                "model": "azure__openai__gpt_4o_mini"
                },
              "basic_text": {
                "model": "azure__openai__gpt_4o_mini"
             }
          }
       }'

    Response Example

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