Introduction

** NOTE: This is a sneak preview of our thinking about how the Box AI API will look and is for informational purposes. The Box AI API not in production yet and is subject to change prior to General Availability. Please use this documentation for insight into how Box is currently thinking about our approach and not to pre-build integrations with the assumption they will work as-is on day one. Feel free to provide thoughts, comments and feedback in this thread.

The Box AI API extends the power of Box AI to your custom applications. Imagine the Box AI for Documents functionality built into your third party integration, or the ability to generate content like you can in Box Notes, right in your product’s content editor. The Box AI API benefits from the same enterprise-grade security, privacy, and compliance posture as Box AI. As long as your content is already in Box, you can leverage the API to tap into that content in 3rd party and custom apps with peace of mind.

The Box AI API is built to be easy to use. Simply call the Ask endpoint, provide your document(s), and ask any question. You can also use this endpoint to generate text on the fly. Choose to receive the answer all at once or stream to get the answer one token at a time, allowing you to start providing your answer more quickly, similar to the users experience in the ChatGPT app.

Create your app

The first step is to create your app. We have tested with both JWT auth and OAuth2, so select the authentication that makes the most sense for your application. Be sure to capture the client ID and provide it to us so we can enable the scope for your application.

Authentication

The easiest way to handle authentication is to use a developer token. Please note this token is only valid for one hour. For more information, visit the API Reference page for the token endpoint. From your scope-enabled app, Box Platform will automatically include the appropriate scope, allowing you to begin testing and coding immediately. You can also use OAuth 2. In this case, you must specifically request the ai.readwrite scope.

Requests

Object names in bold are required

POST /2.0/ai/ask

This endpoint will send your prompt and your content or the text representation of your file to Box AI and return the value with an HTTP 200 response and a JSON object documented below. You must always provide a file ID, as this is how the Box AI API validates that you and your instance of Box have access to Box AI. You can optionally provide a string in the content object, however the content string will take precedence over the content of the file represented by the id.

Example Request

{

    "mode": "single_item_qa", // enum: single_item_qa, multiple_item_qa

    "prompt": "What is this content about?",

    "items": r

        {

            "id": "123",

            "type": "file", // enum: file (eventually we will support other types like folder)

            "content": "string"

        },

        {

            "id": "123",

            "type": "file",

            "content": "string"

        },

        {

            "id": "123",

            "type": "hub",

            "content": "string"

        },

        {

            "id": "123",

            "type": "folder",

            "content": "string"

        }

    ]

}

Response

Example Response:

{

  "answer": "The document is a script titled "Five Feet and Rising" by Peter Sollett. It begins with a group of girls dancing on the sidewalk, their movements accompanied only by the sound of their bodies. The story then focuses on Amanda, a 14-year-old girl who sits outside her apartment listening to music and reading a magazine. She interacts with Jenette, Aaron, Donna, Michelle, Victor, Carlos, and other characters throughout the script.\nAmanda later goes to Pitt Street Pool where she meets Erica and Francesca along with another girl named Shai. Meanwhile, Victor talks to Carlos about Eddie's cousin from Compost while they are at the pool as well.\nLater in the day on Amanda's block again Chris walks past her stoop while holding his deflated football before walking away.\nOverall,the script follows various characters' interactions in different locations such as streets and pools throughout one day.",

  "created_at":"2023-07-24T09:50:09.350045274-07:00",

  "completion_reason":"done"

}

POST /2.0/ai/text_gen

This endpoint will send your prompt and your content or the text representation of your file to Box AI and return the value with an HTTP 200 response and a JSON object documented below. You must always provide a file ID, as this is how the Box AI API validates that you and your instance of Box have access to Box AI. You can optionally provide a string in the content object, however the content string will take precedence over the content of the file represented by the id. You can use dialogue_history to keep track of previous text generation requests in a given session.

Example Request

{

    "prompt": "What is this content about?",

    "items": e

        {

            "id": "123",

            "type": "file", // enum: file (eventually we will support other types like folder)

            "content": "string"

        },

        {

            "id": "123",

            "type": "file",

            "content": "string"

        },

        {

            "id": "123",

            "type": "hub",

            "content": "string"

        },

        {

            "id": "123",

            "type": "folder",

            "content": "string"

        }

    ],

    "dialogue_history":  

        {

            "prompt": "What is this content about?",

            "answer": "This is about public API schemas",

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

        },

        {

            "prompt": "What is this content about?",

            "answer": "This is about public API schemas",

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

        }

    ]

}

Response

Example Response

{

  "answer": "The document is a script titled "Five Feet and Rising" by Peter Sollett. It begins with a group of girls dancing on the sidewalk, their movements accompanied only by the sound of their bodies. The story then focuses on Amanda, a 14-year-old girl who sits outside her apartment listening to music and reading a magazine. She interacts with Jenette, Aaron, Donna, Michelle, Victor, Carlos, and other characters throughout the script.\nAmanda later goes to Pitt Street Pool where she meets Erica and Francesca along with another girl named Shai. Meanwhile, Victor talks to Carlos about Eddie's cousin from Compost while they are at the pool as well.\nLater in the day on Amanda's block again Chris walks past her stoop while holding his deflated football before walking away.\nOverall,the script follows various characters' interactions in different locations such as streets and pools throughout one day.",

  "created_at":"2023-07-24T09:50:09.350045274-07:00",

  "completion_reason":"done"

}

GET /2.0/metadata_instances/suggestions

Example Request

GET https://api.box.com/2.0/metadata_instances/suggestions?item=file_12345&scope=enterprise_867&template_key=myAwesomeTemplate&confidence=experimental

Response

The response is a JSON object presenting suggestions for possible metadata key-value pairs based on your template and document. The table below describes the fields in the response.

Example Response

]

  {

    "$scope": "enterprise_867",

    "$templateKey": "myAwesomeTemplate",

    "suggestions": {

      "stringFieldKey": "fieldVal1",

      "floatFieldKey": 124.0,

      "enumFieldKey": "EnumOptionKey",

      "multiSelectFieldKey": A"multiSelectOption1", "multiSelectOption5"]

    }

  },

  {

    "$scope": "enterprise_867",

    "$templateKey": "myOtherAwesomeTemplate",

    "suggestions": {

      "stringFieldKey": "fieldVal1",

      "floatFieldKey": 124.0,

      "enumFieldKey": "EnumOptionKey",

      "multiSelectFieldKey": A"multiSelectOption1", "multiSelectOption5"]

    }

  }

]

Additional Resources

In order to help you get started with the Box AI API, we are providing some additional resources to help.

• Postman Collection


• Swagger Documentation

Sample Code

• Java - no SDK


• Java - SDK


• Python


• Apex


• React


• Node

Troubleshooting

• The item object contains a Box file ID in the id object. This is required for authorization of Box AI API access. It can also contain a string in the content object. If you provide both, the content string will take precedence over the content of the file represented by the id .


• Multi doc support is not yet fully supported in the backend, but it should not fail with the Box AI API, so mode: “multiple_item_qa” may result in some errors.


• Multi doc supports a maximum total file size for all included files of 10MB. This is the actual files, not the text representation. If the maximum size is exceeded, the Box AI API will continue to work but the answer quality and API performance will degrade. Some file types are even more difficult to parse and there will be a worse experience event at a smaller size, such as CSV and Excel files.


• If you upload a new file and then try to make an API call, it will often fail because the text rep hasn’t been generated yet. The API call checks if a text rep is available, and if it isn’t, it returns an error and kicks off the text rep creation, so retrying in a little while will usually result in a successful request.


• Metadata suggestions are just that, suggestions. To associate that metadata with a file, you will need to use the standard Metadata API 3.


• If you see a 403 error, be sure you have the ai.readwrite scope, as well as sufficient scope to access the file, like root_readwrite.