> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Extract metadata from file (freeform)
export const MultiRelatedLinks = ({sections = []}) => {
if (!sections || sections.length === 0) {
return null;
}
return
;
};
export const Link = ({href, children, className, ...props}) => {
const localizedHref = href;
return
{children}
;
};
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.
The **Extract metadata (freeform)** endpoint doesn't support OCR. To extract metadata from image files (TIFF, PNG, JPEG) or documents in languages other than English, use the Extract metadata (structured) endpoint.
## Before you start
Make sure you followed the steps listed in getting started with Box AI to create a platform app and authenticate.
## Send a request
To send a request, use the
`POST /2.0/ai/extract` endpoint.
```sh cURL theme={null}
curl -i -L 'https://api.box.com/2.0/ai/extract' \
-H 'content-type: application/json' \
-H 'authorization: Bearer ' \
-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",
}
}
}'
```
```typescript Node/TypeScript v10 theme={null}
await client.ai.createAiExtract({
prompt: 'firstName, lastName, location, yearOfBirth, company',
items: [new AiItemBase({ id: file.id })],
aiAgent: agentIgnoringOverridingEmbeddingsModel,
} satisfies AiExtract);
```
```python Python v10 theme={null}
client.ai.create_ai_extract(
"firstName, lastName, location, yearOfBirth, company",
[AiItemBase(id=file.id)],
ai_agent=agent_ignoring_overriding_embeddings_model,
)
```
```cs .NET v10 theme={null}
await client.Ai.CreateAiExtractAsync(requestBody: new AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})));
```
```swift Swift v10 theme={null}
try await client.ai.createAiExtract(requestBody: AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: [AiItemBase(id: file.id)]))
```
```java Java v10 theme={null}
client.getAi().createAiExtract(new AiExtract.Builder("firstName, lastName, location, yearOfBirth, company", Arrays.asList(new AiItemBase(file.getId()))).aiAgent(agentIgnoringOverridingEmbeddingsModel).build())
```
```java Java v5 theme={null}
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**.
The `items` array can have exactly one element.
| 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:
* `prompt` that can be a query, or a structured or unstructured list of fields to extract.
* `type` and `id` of 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.
```bash theme={null}
curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--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:
```bash theme={null}
{
"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:
```bash theme={null}
curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--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:
```bash theme={null}
{
"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.
```bash theme={null}
curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--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:
```bash theme={null}
{
"answer": "{\"vendor\": \"Quasar Innovations\", \"documentType\": \"Invoice\"}",
"created_at": "2024-05-31T10:15:38.17-07:00",
"completion_reason": "done"
}
```