Box Developer Documentation
 
    Latest version

    Ask question

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

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

    Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context.

    Request

    bearer [ACCESS_TOKEN]
    application/json

    Request Body

    The AI agent used to handle queries.

    object arrayin bodyoptional

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

    stringin bodyoptional
    "Here is the first draft of your professional email about public APIs."

    The answer previously provided by the LLM.

    string (date-time)in bodyoptional
    "2012-12-12T10:53:43-08:00"

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

    stringin bodyoptional
    "Make my email about public APIs sound more professional."

    The prompt previously provided by the client and answered by the LLM.

    booleanin bodyoptional
    true

    A flag to indicate whether citations should be returned.

    object arrayin bodyrequired

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

    Note: Box AI handles documents with text representations up to 1MB in size, or a maximum of 25 files, whichever comes first. If the file size exceeds 1MB, the first 1MB of text representation will be processed. If you set mode parameter to single_item_qa, the items array can have one element only.

    stringin bodyrequired
    "123"

    The ID of the file.

    stringin bodyrequired
    "file"

    The type of the item. A hubs item must be used as a single item.

    Value is one of file,hubs

    stringin bodyoptional
    "This is file content."

    The content of the item, often the text representation.

    stringin bodyrequired
    "multiple_item_qa"

    The mode specifies if this request is for a single or multiple items. If you select single_item_qa the items array can have one element only. Selecting multiple_item_qa allows you to provide up to 25 items.

    Value is one of multiple_item_qa,single_item_qa

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

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

    Response

    application/jsonAI response (Full)

    A successful response including the answer from the LLM.

    none

    No content is available to answer the question. This is returned when the request item is a hub, but content in the hubs is not indexed. To ensure content in the hub is indexed, make sure Box AI for Hubs in the Admin Console was enabled before hub creation.

    application/jsonClient error

    An unexpected server error.

    application/jsonClient error

    An unexpected error.

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

    Request Example

    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_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",
               }
             }
          }'

    Response Example

    {
      "ai_agent_info": {
        "models": [
          {
            "name": "azure__openai__text_embedding_ada_002",
            "provider": "azure",
            "supported_purpose": "embedding"
          }
        ]
      },
      "answer": "Public APIs are important because of key and important reasons.",
      "citations": [
        {
          "content": "Public APIs are key drivers of innovation and growth.",
          "id": "123",
          "name": "The importance of public APIs.pdf",
          "type": "file"
        }
      ],
      "completion_reason": "done",
      "created_at": "2012-12-12T10:53:43-08:00"
    }