Join BoxWorks 2024 to discover what's possible with content and AI!

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

Box AI AI model overrides

Request

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json

Request Body

ai_agentAI agent for extract requests objectin body

The AI agent to be used for extraction.

items object arrayin bodyrequired

The items that LLM will process. Currently, you can use files only.

[items].id stringin bodyrequired

example"123"

The ID of the file.

[items].type stringin bodyrequired

example"file"

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

Value is always file

[items].content stringin bodyoptional

example"This is file content."

The content of the item, often the text representation.

prompt stringin bodyrequired

example

"\"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

200application/jsonAI response

A response including the answer from the LLM.

500application/jsonClient error

An unexpected server error.

defaultapplication/jsonClient error

An unexpected error.

post

Extract metadata (freeform)

You can now try out some of our APIs live, right here in the documentation.

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)})));

Swift Gen (Beta)

try await client.ai.createAiExtract(requestBody: AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: [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"
}