Ask questions to Box AI

Box AI API is available to all customers Business and above.

Box AI API allows you to ask a question about a supplied file or a set of files, and get a response based on the content. For example, while viewing a document in Box, you can ask Box AI to summarize the content. You can also ask questions against a . When you pass a hub as the item, Box AI searches the hub’s indexed content and returns answers grounded in the curated documents the querying user has access to. See below.

Before you start

Make sure you followed the steps listed in to create a platform app and authenticate.

Send a request

To send a request containing your question, use the POST /2.0/ai/ask endpoint and provide the mandatory parameters.

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": "openai__gpt_5_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": "openai__gpt_5_mini",
           }
         }
      }'

await client.ai.createAiAsk({
  mode: 'single_item_qa' as AiAskModeField,
  prompt: 'which direction sun rises',
  items: [
    {
      id: fileToAsk.id,
      type: 'file' as AiItemAskTypeField,
      content: 'Sun rises in the East',
    } satisfies AiItemAsk,
  ],
  aiAgent: aiAskAgentConfig,
} satisfies AiAsk);

client.ai.create_ai_ask(
    CreateAiAskMode.SINGLE_ITEM_QA,
    "which direction sun rises",
    [
        AiItemAsk(
            id=file_to_ask.id,
            type=AiItemAskTypeField.FILE,
            content="Sun rises in the East",
        )
    ],
    ai_agent=ai_ask_agent_config,
)

await client.Ai.CreateAiAskAsync(requestBody: new AiAsk(mode: AiAskModeField.SingleItemQa, prompt: "which direction sun rises", items: Array.AsReadOnly(new [] {new AiItemAsk(id: fileToAsk.Id, type: AiItemAskTypeField.File) { Content = "Sun rises in the East" }})));

try await client.ai.createAiAsk(requestBody: AiAsk(mode: AiAskModeField.singleItemQa, prompt: "which direction sun rises", items: [AiItemAsk(id: fileToAsk.id, type: AiItemAskTypeField.file, content: "Sun rises in the East")]))

client.getAi().createAiAsk(new AiAsk.Builder(AiAskModeField.SINGLE_ITEM_QA, "which direction sun rises", Arrays.asList(new AiItemAsk.Builder(fileToAsk.getId(), AiItemAskTypeField.FILE).content("Sun rises in the East").build())).aiAgent(aiAskAgentConfig).build())

BoxAIResponse response = BoxAI.sendAIRequest(
    api,
    "What is the content of the file?",
    Collections.singletonList("123456", BoxAIItem.Type.FILE),
    BoxAI.Mode.SINGLE_ITEM_QA
);

items = [{
    "id": "1582915952443",
    "type": "file",
    "content": "More information about public APIs"
}]
ai_agent = {
    'type': 'ai_agent_ask',
    'basic_text_multi': {
        'model': 'openai__gpt_3_5_turbo'
    }
}
answer = client.send_ai_question(
    items=items, 
    prompt="What is this file?",
    mode="single_item_qa",
    ai_agent=ai_agent
)
print(answer)

BoxAIResponse response = await client.BoxAIManager.SendAIQuestionAsync(
    new BoxAIAskRequest
    {
        Prompt = "What is the name of the file?",
        Items = new List<BoxAIAskItem>() { new BoxAIAskItem() { Id = "12345" } },
        Mode = AiAskMode.single_item_qa
    };
);

client.ai.ask(
    {
        prompt: 'What is the capital of France?',
        items: [
            {
                type: 'file',
                id: '12345'
            }
        ],
        mode: 'single_item_qa'
    })
    .then(response => {
        /* response -> {
            "answer": "Paris",
            "created_at": "2021-10-01T00:00:00Z",
            "completion_reason": "done"
        } */
    });

Parameters

To make a call, you need to pass the following parameters. Mandatory parameters are in bold.

Parameter	Description	Available values	Example
`mode`	The type of request. Use `single_item_qa` for a single file (the `items` array must contain exactly one element) or `multiple_item_qa` for up to 25 files. For full details on file size, image, and prompt limits, see .	`single_item_qa`, `multiple_item_qa`	`single_item_qa`
`prompt`	The question about your document or content. Maximum 10,000 characters.		`What is this document about?`
`dialogue_history.prompt`	The prompt previously provided by the client and answered by the Large Language Model (LLM).	`Make my email about public APIs sound more professional`
`dialogue_history.answer`	The answer previously provided by the LLM.	`Here is a draft of your professional email about public APIs.`
`dialogue_history.created_at`	The ISO date formatted timestamp of when the previous answer to the prompt was created.	`2012-12-12T10:53:43-08:00`
`include_citations`	Specifies if the citations should be returned in the answer.	`true`, `false`	`true`
`items.id`	The ID of the file or hub you want to provide as input.		`112233445566`
`items.type`	The type of the provided input. Use `file` for one or more files, or `hubs` to query a Box Hub. A `hubs` item must be the only item in the request.	`file`, `hubs`	`file`
`items.content`	The content of the item. Usually it is the text representation.		`An application programming interface (API) is a way for two or more computer programs or components to communicate with each other. It is a type of software interface...`
`ai_agent`	Override the default model configuration. Lets you change the model, prompt template, system message, or LLM parameters. See for how it works and for examples.

Use cases

Ask questions about an item

This example shows how to ask a question about one or more items using the POST ask/ai API. When using this endpoint, remember to specify the mode parameter depending on the number of items you want to supply.

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",
    "items": [
        {
            "id": "12345678",
            "type": "file"
        }
    ],
    "prompt": "List the guidelines on creating questions in Box AI for Documents"
}'

The response will be as follows:

{
    "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview.\n2. If questions fall outside the scope of the document, Box AI will inform you that it cannot answer.\n3. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n4. Aim to stay within the scope of the document.\n5. Focus on text-based responses only.",
    "created_at": "2024-11-04T02:30:09.557-08:00",
    "completion_reason": "done"
}

Ask questions about a hub

Instead of supplying individual files, you can point Box AI at an entire and ask questions across all of its curated content. This is useful for knowledge bases such as RFP answer banks, policy libraries, and product documentation portals, where you want natural language answers grounded in an approved set of materials without managing file IDs yourself. To query a hub, set items.type to hubs and items.id to the hub ID. A hub must be supplied as the only item in the request. The example below uses single_item_qa mode, which is the pattern shown in the .

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",
    "items": [
        {
            "id": "98765432",
            "type": "hubs"
        }
    ],
    "prompt": "What is our standard SLA for enterprise support?"
}'

Box AI searches the hub’s indexed content and returns an answer grounded in your approved materials. Because hubs inherit Box permissions, Box AI only references documents the querying user has access to. The hub must have AI features enabled (see ). For an end-to-end walkthrough that provisions a hub, populates it with content, and queries it with Box AI, see the tutorial.

Ask questions with `content` parameter

If you use the content parameter as the source of input for Box AI, it will use it as the primary source.

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",
    "items": [
        {
            "id": "12345678",
            "type": "file",
            "content": "This is a document about Box AI For documents. It consists of the functionality summary and guidelines on how to work with Box AI. Additionally, it provides a set of best practices for creating questions."
        }
    ],
    "prompt": "List the guidelines on creating questions in Box AI for Documents"
}'

The response to this request is based on the content parameter instead of the file’s content:

{
    "answer": "The document does not provide specific guidelines on working with questions in Box AI for Documents. It only mentions that it includes a set of best practices for creating questions, but the details of those guidelines are not included in the text provided. If you have more information or another document, I can help further!",
    "created_at": "2024-11-04T02:31:51.125-08:00",
    "completion_reason": "done"
}

Ask questions with `citations` parameter

Setting the citations parameter to true causes the response to include excerpts from source file or files Box AI used to compile the answer.

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": "multiple_item_qa",
    "include_citations": true,
    "items": [
        {
            "id": "12345678",
            "type": "file"
        }
    ],
    "prompt": "List the guidelines on working with responses in Box AI for Documents"
}'

The resulting answer includes the source file and direct content citations.

{
    "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview, and cannot answer questions outside its scope.\n2. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n3. Examples of better phrasing include asking for a numbered list of key points instead of just \"list key points,\" and requesting a succinct outline of important points rather than a general inquiry about the document's purpose.\n4. Stay within the scope of the document and focus on text-based responses only.",
    "created_at": "2024-11-04T02:35:00.578-08:00",
    "completion_reason": "done",
    "citations": [
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "Guidelines for Box AI questions\nBox AI pulls information only from the document you loaded in preview."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "If you ask any questions outside of the scope of the document, Box AI informs you that it cannot answer the question with the information provided."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "As you ask Box AI to analyze your document, consider these suggestions:\n· Be as specific as possible."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "Box AI for Documents\n\nWhen viewing a document in Box, you can ask Box AI to summarize document content, search key points, and write outline drafts based on your document files."
        }
    ]
}

​Before you start

​Send a request

​Parameters

​Use cases

​Ask questions about an item

​Ask questions about a hub

​Ask questions with content parameter

​Ask questions with citations parameter

Before you start

Send a request

Parameters

Use cases

Ask questions about an item

Ask questions about a hub

Ask questions with `content` parameter

Ask questions with `citations` parameter