Box Developer Documentation
Log in
Beta

Extract metadata (freeform)

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

Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs. Freeform metadata extraction does not require any metadata template setup before sending the request.

Related Guides

Request

bearer [ACCESS_TOKEN]
application/json

Request Body

AI agent for extract requests objectin body

The AI agent to be used for extraction.

object arrayin bodyrequired

The items that LLM will process. 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.

stringin bodyrequired
"\"fields\":[{\"type\":\"string\",\"key\":\"name\",\"displayName\":\"Name\",\"description\":\"The customer name\",\"prompt\":\"Name is always the first word in the document\"},{\"type\":\"date\",\"key\":\"last_contacted_at\",\"displayName\":\"Last Contacted At\",\"description\":\"When this customer was last contacted at\"}]"

The prompt provided to a Large Language Model (LLM) in the request. The prompt can be up to 10000 characters long and it can be an XML or a JSON schema.

Response

application/jsonAI response

A response including the answer from the LLM.

application/jsonClient error

An unexpected server error.

application/jsonClient error

An unexpected error.

post
Extract metadata (freeform)
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' \
     -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",
          }
        }
      }'
TypeScript Gen
await client.ai.createAiExtract({
  prompt: 'firstName, lastName, location, yearOfBirth, company',
  items: [new AiItemBase({ id: file.id })],
} satisfies AiExtract);
Python Gen
client.ai.create_ai_extract(
    "firstName, lastName, location, yearOfBirth, company",
    [AiItemBase(id=file.id)],
    ai_agent=ai_extract_agent_config,
)
.NET Gen
await client.Ai.CreateAiExtractAsync(requestBody: new AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})));
Java
BoxAIResponse response = BoxAI.extractMetadataFreeform(
    api,
    "firstName, lastName, location, yearOfBirth, company",
    Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE))
);

Response Example

{
  "answer": "Public APIs are important because of key and important reasons.",
  "completion_reason": "done",
  "created_at": "2012-12-12T10:53:43-08:00"
}