Extract metadata from file (freeform)
Extract metadata from file (freeform)
Box AI API allows you to query a document and extract metadata based on a provided prompt. Freeform means that the prompt can include a stringified version of formats such as JSON or XML, or even plain text.
Before you start
Make sure you followed the steps listed in getting started with Box AI to create a custom app and authenticate.
Send a request
To send a request, use the
POST /2.0/ai/extract endpoint.
curl -i -L 'https://api.box.com/2.0/ai/extract' \
-H 'content-type: application/json' \
-H 'authorization: Bearer <ACCESS_TOKEN>' \
-d '{
"prompt": "Extract data related to contract conditions",
"items": [
{
"type": "file",
"id": "1497741268097"
}
],
"ai_agent": {
"type": "ai_agent_extract",
"long_text": {
"model": "azure__openai__gpt_4o_mini",
"prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
},
"basic_text": {
"model": "azure__openai__gpt_4o_mini",
}
}
}'await client.ai.createAiExtract({
prompt: 'firstName, lastName, location, yearOfBirth, company',
items: [new AiItemBase({ id: file.id })],
} satisfies AiExtract);client.ai.create_ai_extract(
"firstName, lastName, location, yearOfBirth, company",
[AiItemBase(id=file.id)],
ai_agent=ai_extract_agent_config,
)await client.Ai.CreateAiExtractAsync(requestBody: new AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})));BoxAIResponse response = BoxAI.extractMetadataFreeform(
api,
"firstName, lastName, location, yearOfBirth, company",
Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE))
);Parameters
To make a call, you must pass the following parameters. Mandatory parameters are in bold.
| Parameter | Description | Example |
|---|---|---|
prompt | The request for Box AI to generate or refine the text. The prompt's length cannot exceed 10000 characters. | Create a meeting agenda for a weekly sales meeting. |
items.id | Box file ID of the document. The ID must reference an actual file with an extension. | 1233039227512 |
items.type | The type of the supplied input. | file |
items.content | The content of the item, often the text representation. | This article is about Box AI. |
ai_agent | The AI agent used to override the default agent configuration. This parameter allows you to, for example, replace the default LLM with a custom one using the model parameter, tweak the base prompt to allow for a more customized user experience, or change an LLM parameter, such as temperature, to make the results more or less creative. Before you use the ai_agent parameter, you can get the default configuration using the GET 2.0/ai_agent_default request. For specific use cases, see the AI model overrides tutorial. |
Use cases
This example shows you how to extract metadata from a sample invoice.
Create the request
To get the response from Box AI, call POST /2.0/ai/extract endpoint with the following parameters:
promptthat can be a query, or a structured or unstructured list of fields to extract.typeandidof the file to extract the data from.
Create the prompt
Depending on the use case and the level of detail, you can construct various prompts.
Use plain text
Because this endpoint allows freeform prompts, you can use plain text to get the information.
curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
"prompt": "find the document type (invoice or po), vendor, total, and po number",
"items": [
{
"type": "file",
"id": "1443721424754"
}
]
}'
In such a case, the response will be based on the keywords included in the text:
{
"answer": "{\"Document Type\": \"Invoice\", \"Vendor\": \"Quasar Innovations\", \"Total\": \"$1,050\", \"PO Number\": \"003\"}",
"created_at": "2024-05-31T10:30:51.223-07:00",
"completion_reason": "done"
}
Use specific terms
If you don't want to write the entire sentence, the prompt can consist of terms that you expect to find in an invoice:
curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: <ACCESS_TOKEN>' \
--data '{
"prompt": "{\"vendor\",\"total\",\"doctype\",\"date\",\"PO\"}",
"items": [
{
"type": "file",
"id": "1443721424754"
}
]
}'
Using this approach results in a list of terms provided in the request and their values:
{
"answer": "{\"vendor\": \"Quasar Innovations\", \"total\": \"$1,050\", \"doctype\": \"Invoice\", \"PO\": \"003\"}",
"created_at": "2024-05-31T10:28:51.906-07:00",
"completion_reason": "done"
}
Use key-value pairs
The prompt can also be a list of key-value pairs that helps Box AI to come up with the metadata structure. This approach requires listing the key-value pairs within a fields array.
curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
"prompt": "{\"fields\": [{\"key\":\"vendor\",\"displayName\":\"Vendor\",\"type\":\"string\",\"description\":\ "Vendorname\"},{\"key\":\"documentType\",\"displayName\":\"Type\",\"type\":\"string\",\"description\":\"\"}]}",
"items": [
{
"type": "file",
"id": "1443721424754"
}
]
}'
The response includes the fields present in the file, along with their values:
{
"answer": "{\"vendor\": \"Quasar Innovations\", \"documentType\": \"Invoice\"}",
"created_at": "2024-05-31T10:15:38.17-07:00",
"completion_reason": "done"
}