> ## 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.
# Box AI
> Technical reference for Box AI request handling, input limits, model behavior, and the agent override system.
export const SignupCTA = ({children}) => {
return
;
};
export const Link = ({href, children, className, ...props}) => {
const localizedHref = localizeLink(href);
return
{children}
;
};
This section contains developer guides for working with Box AI. For a summary of API capabilities, quick starts, and reference links, see the [Box AI API](/ai/box-ai-api) page.
The below guides cover what you need to know before you start writing code: how Box AI processes requests, what limits apply to different endpoints, how to control model behavior through agent overrides, and where to find the specific tutorial for your use case.
A free developer account gives you access to the Box AI API, Developer Console, and everything you need to start building.
## How requests are processed
When you send a request to a Box AI endpoint, Box handles the model infrastructure for you. Your request flows through the following stages:
* **File retrieval**: Box reads the file content from the `items` array you provide. If you include the optional `content` parameter, that text is used as the primary input instead of the file's stored content. For `POST /ai/ask`, an `items` entry can also be a [Box Hub](/guides/hubs-api/index) (`"type": "hubs"`), in which case Box searches the hub's indexed content instead of a single file. See [Ask questions about a hub](/guides/box-ai/ai-tutorials/ask-questions#ask-questions-about-a-hub).
* **Representation generation**: For text-based files, Box converts the document into a text representation. For images, Box applies OCR automatically on supported endpoints.
* **Model routing**: Box routes the request to the default model for that endpoint and mode. You can override this with the `ai_agent` parameter.
* **Response generation**: The LLM processes your prompt against the file content and returns a result. Box handles token windowing for long documents (splitting content into chunks with embeddings for `long_text` configurations).
Box AI does not support multi-modal requests. If you send both images and text in the same request, only the text is processed.
## Input limits
The limits below apply across Box AI endpoints. Exceeding these limits does not produce an error in most cases; Box truncates to the limit and processes what it can.
### Text and prompt limits
| Constraint | Limit |
| -------------------------------------------------- | ----------------------------------------------- |
| Prompt length | 10,000 characters |
| Single file text representation (`single_item_qa`) | 2 MB of text. Content beyond 2 MB is truncated. |
| Multiple files (`multiple_item_qa`) | Up to 25 files |
| Items array for `text_gen` | Exactly 1 file |
| Items array for `extract` and `extract_structured` | Exactly 1 file |
### Image limits
| Constraint | Limit |
| ----------------------------------- | -------------------------------------------------------- |
| Resolution | 1024 x 1024 pixels |
| Maximum images or pages per request | 5. If more are provided, only the first 5 are processed. |
### OCR and file format support
OCR is **not** available on all endpoints.
| Endpoint | OCR | Supported file formats |
| ----------------------------- | --------------- | ---------------------- |
| `POST /ai/text_gen` | No | Text-based files |
| `POST /ai/extract` | No | Text-based files |
| `POST /ai/extract_structured` | Yes (automatic) | PDF, TIFF, PNG, JPEG |
### Language support
Box AI works in English, Japanese, French, Spanish, and many other languages. However, the underlying models are primarily trained on English, so prompts in other languages may return lower quality results.
The `extract_structured` endpoint has explicit multilingual support for:
* English, Japanese, Chinese, Korean
* Cyrillic-based languages (Russian, Ukrainian, Bulgarian, Serbian)
Switch the language to Japanese to get better results for this language.
## The `ai_agent` override system
The following Box AI endpoints accept an optional `ai_agent` parameter that lets you override the default model configuration: `POST /ai/ask`, `POST /ai/text_gen`, `POST /ai/extract`, and `POST /ai/extract_structured`. This is how you control which LLM runs, how it behaves, and what instructions it receives.
### When to use overrides
* **Pinning a model version**: Box updates default models regularly. If your downstream process depends on consistent output, pin to a specific model to avoid unexpected changes.
* **Switching models**: Different models produce different results. You can switch to any model in the supported models list to optimize for your use case.
* **Customizing prompts**: The `prompt_template` and `system_message` parameters let you steer the LLM's behavior without changing your application code.
* **Tuning creativity**: Adjust `temperature` and other `llm_endpoint_params` to control how deterministic or creative the output is.
### How it works
Call `GET /2.0/ai_agent_default` with the `mode` you want (`ask`, `text_gen`, `extract`, or `extract_structured`) to retrieve the current defaults.
Change the fields you need: `model`, `prompt_template`, `system_message`, `llm_endpoint_params`, or `num_tokens_for_completion`. Leave other fields unchanged.
Include the modified configuration as the `ai_agent` parameter in your `POST` request. Box uses your overrides for that request only.
### Configuration structure by endpoint
The `ai_agent` object structure varies by endpoint because each handles content differently:
| Endpoint | Agent type | Configuration keys |
| ----------------------------- | ----------------------------- | ---------------------------------------------------------------- |
| `POST /ai/ask` | `ai_agent_ask` | `basic_text`, `basic_text_multi`, `long_text`, `long_text_multi` |
| `POST /ai/text_gen` | `ai_agent_text_gen` | `basic_gen` |
| `POST /ai/extract` | `ai_agent_extract` | `basic_text`, `long_text` |
| `POST /ai/extract_structured` | `ai_agent_extract_structured` | `basic_text`, `long_text` |
The `ask` endpoint has four configuration keys because it handles both single-item and multi-item modes, and both short and long documents. When using `multiple_item_qa` mode, the `_multi` variants apply.
For `long_text` configurations, Box splits the content into chunks using an embeddings model. You can configure the embeddings model and chunking strategy as part of the override.
### LLM parameter differences by provider
The `llm_endpoint_params` options depend on the model provider:
| Provider | Param type | Key difference |
| ----------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------- |
| OpenAI | `openai_params` | Use `temperature` **or** `top_p`, not both |
| Google | `google_params` | `temperature` works with `top_p` and `top_k` together |
| AWS | `aws_params` | Same as Google: `temperature` works alongside `top_p` and `top_k` |
For detailed override examples, see the AI model overrides guide and the override tutorial.
### Model versioning
Box guarantees each AI agent configuration snapshot for at least 12 months, with a 6-month transition window when a new version is released. Default model changes are posted in the developer changelog. To avoid disruption, pin your agent configuration to a specific model version using overrides.
For full details, see AI agent configuration versioning.
## Box AI for UI Elements
The Box AI for UI Elements integration embeds question-answering directly into Content Preview within your application. This lets end users interact with Box AI without leaving your UI.
## User Activity Reports
[User Activity Reports][uar] track Box AI interactions. Box admins can filter for the following action types:
| Action type | Description |
| ------------------- | ------------------------------------------------------ |
| **AI query** | The user queried Box AI and received a response |
| **Failed AI query** | The user queried Box AI but did not receive a response |
[uar]: https://support.box.com/hc/en-us/articles/4415012490387-User-Activity-Report
## Guides in this section
Step-by-step guides for each endpoint: ask, text generation, extraction,
and model overrides.
Override default models, prompts, and LLM parameters. Includes the
default configuration reference and versioning policy.
Full list of core and customer-enabled models with capability tiers,
compliance badges, and API names.
Get up and running in minutes with Python SDK walkthroughs for
summarization and extraction.
## See Box AI in action
These end-to-end tutorials show how to combine Box AI with other platform capabilities to build production-ready automations.
Use Box AI Extract and metadata to automate accounts payable - extract vendors, totals, and dates from every invoice.
Build an AI-powered knowledge base with Box Hubs and let sales reps query approved proposals in natural language.