Extract metadata (structured)
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 need to use an already defined metadata template or a define a schema yourself. To learn more about creating templates, see Creating metadata templates in the Admin Console or use the metadata template API.
Request
Request Body
The AI agent to be used for structured extraction.
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.
"enum"The type of the field. It include but is not limited to string, float, date, enum, and multiSelect.
"The name of the person."A description of the field.
"Name"The display name of the field.
"name"A unique identifier for the field.
[{"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.
"First Name"A unique identifier for the field.
"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.
The items to be processed by the LLM. Currently you can use files only.
"123"The ID of the file.
"file"The type of the item. Currently the value can be file only.
Value is always file
"This is file content."The content of the item, often the text representation.
The metadata template containing the fields to extract.
For your request to work, you must provide either metadata_template or fields, but not both.
"metadata_template"Value is always metadata_template.
Value is always metadata_template
"enterprise_12345"40The 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.
"invoiceTemplate"The name of the metadata template.
Response
A successful response including the answer from the LLM.
An unexpected server error.
An unexpected error.
Request Example
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"
}
}
}'await client.ai.createAiExtractStructured({
metadataTemplate: {
templateKey: templateKey,
scope: 'enterprise',
} satisfies AiExtractStructuredMetadataTemplateField,
items: [new AiItemBase({ id: file.id })],
} satisfies AiExtractStructured);client.ai.create_ai_extract_structured(
[AiItemBase(id=file.id)],
metadata_template=CreateAiExtractStructuredMetadataTemplate(
template_key=template_key, scope="enterprise"
),
)await client.Ai.CreateAiExtractStructuredAsync(requestBody: new AiExtractStructured(items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})) { MetadataTemplate = new AiExtractStructuredMetadataTemplateField() { TemplateKey = templateKey, Scope = "enterprise" } });BoxAIExtractMetadataTemplate template = new BoxAIExtractMetadataTemplate("templateKey", "enterprise");
BoxAIExtractStructuredResponse result = BoxAI.extractMetadataStructured(
api,
Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)),
template
);
JsonObject sourceJson = result.getSourceJson();