Skip to main content
POST
/
ai
/
ask
cURL
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
         "mode": "single_item_qa",
         "prompt": "What is the value provided by public APIs based on this document?",
         "items": [
            {
            "type": "file",
            "id": "9842787262"
            }
         ],
         "dialogue_history": [
              {
              "prompt": "Make my email about public APIs sound more professional",
              "answer": "Here is the first draft of your professional email about public APIs",
              "created_at": "2013-12-12T10:53:43-08:00"
              }
          ],
          "include_citations": true,
          "ai_agent": {
            "type": "ai_agent_ask",
            "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"
           }
         }
      }'
{
  "answer": "Public APIs are important because of key and important reasons.",
  "created_at": "2012-12-12T10:53:43-08:00",
  "completion_reason": "done",
  "ai_agent_info": {
    "models": [
      {
        "name": "azure__openai__text_embedding_ada_002",
        "provider": "azure",
        "supported_purpose": "embedding"
      }
    ],
    "processor": "basic_text"
  },
  "citations": [
    {
      "content": "Public APIs are key drivers of innovation and growth.",
      "id": "123",
      "type": "file",
      "name": "The importance of public APIs.pdf"
    }
  ]
}

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.

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

AI ask request object.

​
mode
enum<string>
required

Box AI handles text documents with text representations up to 1MB in size, or a maximum of 25 files, whichever comes first. If the text file size exceeds 1MB, the first 1MB of text representation will be processed. Box AI handles image documents with a resolution of 1024 x 1024 pixels, with a maximum of 5 images or 5 pages for multi-page images. If the number of image or image pages exceeds 5, the first 5 images or pages will be processed. If you set mode parameter to single_item_qa, the items array can have one element only. Currently Box AI does not support multi-modal requests. If both images and text are sent Box AI will only process the text.

Available options:
multiple_item_qa,
single_item_qa
Example:

"multiple_item_qa"

​
prompt
string
required

The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.

Example:

"What is the value provided by public APIs based on this document?"

​
items
AI Item Ask · object[]
required

The items to be processed by the LLM, often files.

Required array length: 1 - 25 elements
​
dialogue_history
Dialogue history · object[]

The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response.

​
include_citations
boolean

A flag to indicate whether citations should be returned.

Example:

true

​
ai_agent
AI agent reference · object

The AI agent to be used to handle the request.

Response

A successful response including the answer from the LLM.

AI ask response.

​
answer
string
required

The answer provided by the LLM.

Example:

"Public APIs are important because of key and important reasons."

​
created_at
string<date-time>
required

The ISO date formatted timestamp of when the answer to the prompt was created.

Example:

"2012-12-12T10:53:43-08:00"

​
completion_reason
string

The reason the response finishes.

Example:

"done"

​
ai_agent_info
The information on the models and processors used in the request. · object

The information on the models and processors used in the request.

​
citations
The citation of the LLM's answer reference · object[]

The citations of the LLM's answer reference.