Ask questions to Box AI

Guides Box AI Ask questions to Box AI

Ask questions to Box AI

Box AI API is currently a beta feature offered subject to Box’s Main Beta Agreement, and the available capabilities may change. Box AI API is available to all Enterprise Plus customers.

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.

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

cURL

curl -i -L 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_3_5_turbo_16k",
              "system_message": "You are a helpful travel assistant specialized in budget travel",
              "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
              "num_tokens_for_completion": 8400,
              "llm_endpoint_params": {
                "type": "openai_params",
                "temperature": 0.0,
                "top_p": 1.0,
                "frequency_penalty": 1.5,
                "presence_penalty": 1.5,
                "stop": "<|im_end|>"
              },
              "embeddings": {
                "model": "openai__text_embedding_ada_002",
                "strategy": {
                  "id": "basic",
                  "num_tokens_per_chunk": 8400
                }
              }
            },
            "basic_text": {
              "model": ""azure__openai__gpt_3_5_turbo_16k"",
              "system_message": "You are a helpful travel assistant specialized in budget travel",
              "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
              "num_tokens_for_completion": 8400,
              "llm_endpoint_params": {
                "type": "openai_params",
                "temperature": 0.0,
                "top_p": 1.0,
                "frequency_penalty": 1.5,
                "presence_penalty": 1.5,
                "stop": "<|im_end|>"
              }
            },
              "long_text_multi": {
                "model": "azure__openai__gpt_3_5_turbo_16k",
                "system_message": "You are a helpful travel assistant specialized in budget travel",
                "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
                "num_tokens_for_completion": 8400,
                "llm_endpoint_params": {
                  "type": "openai_params",
                  "temperature": 0.0,
                  "top_p": 1.0,
                  "frequency_penalty": 1.5,
                  "presence_penalty": 1.5,
                  "stop": "<|im_end|>"
                },
                "embeddings": {
                  "model": "openai__text_embedding_ada_002",
                  "strategy": {
                    "id": "basic",
                    "num_tokens_per_chunk": 8400
                  }
                }
              },
              "basic_text_multi": {
                "model": ""azure__openai__gpt_3_5_turbo_16k"",
                "system_message": "You are a helpful travel assistant specialized in budget travel",
                "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
                "num_tokens_for_completion": 8400,
                  "llm_endpoint_params": {
                    "type": "openai_params",
                    "temperature": 0.0,
                    "top_p": 1.0,
                    "frequency_penalty": 1.5,
                    "presence_penalty": 1.5,
                    "stop": "<|im_end|>"
                  }
        }
      }'

TypeScript Gen

await client.ai.createAiAsk({
  mode: 'multiple_item_qa' as AiAskModeField,
  prompt: 'Which direction sun rises?',
  items: [
    new AiItemBase({
      id: fileToAsk1.id,
      type: 'file' as AiItemBaseTypeField,
      content: 'Earth goes around the sun',
    }),
    new AiItemBase({
      id: fileToAsk2.id,
      type: 'file' as AiItemBaseTypeField,
      content: 'Sun rises in the East in the morning',
    }),
  ],
} satisfies AiAsk);

Python Gen

client.ai.create_ai_ask(
    CreateAiAskMode.MULTIPLE_ITEM_QA.value,
    "Which direction sun rises?",
    [
        AiItemBase(
            id=file_to_ask_1.id,
            type=AiItemBaseTypeField.FILE.value,
            content="Earth goes around the sun",
        ),
        AiItemBase(
            id=file_to_ask_2.id,
            type=AiItemBaseTypeField.FILE.value,
            content="Sun rises in the East in the morning",
        ),
    ],
)

.NET Gen

await client.Ai.CreateAiAskAsync(requestBody: new AiAsk(mode: AiAskModeField.MultipleItemQa, prompt: "Which direction sun rises?", items: Array.AsReadOnly(new [] {new AiItemBase(id: fileToAsk1.Id, type: AiItemBaseTypeField.File) { Content = "Earth goes around the sun" },new AiItemBase(id: fileToAsk2.Id, type: AiItemBaseTypeField.File) { Content = "Sun rises in the East in the morning" }})));

Java

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

Python

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)

.NET

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

Node

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"
        } */
    });

Make sure you have generated the developer token to authorize your app. See prerequisites for using Box AI for details.

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. It can be a question about a single file or a set of files. For a single file, Box AI API supports up to 1MB of text representation. If the file size exceeds 1MB, the first 1MB of text representation will be processed. If you want to list multiple files, the limit is 25 files. If you set `mode` to `single_item_qa`, the `items` array can list only one element.	`single_item_qa`, `multiple_item_qa`	`single_item_qa`
`prompt`	The question about your document or content. The prompt's length cannot exceed 10000 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 Box file ID you want to provide as input.		`112233445566`
`items.type`	The type of the provided input. Currently, it can be a single file or multiple files.	`file`	`file`
`items.content`	The content of the item, often 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`	The AI agent used to override the default agent configuration. You can use this parameter replace the default LLM with a custom one using the `model` parameter for shorter and longer texts, 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.

Related APIs

postAsk question

Ask questions to Box AI

Ask questions to Box AI

Send a request

Authentication

Parameters

Related APIs

Related Guides