Skip to main content

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.

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 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.

​
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.
  • 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

ConstraintLimit
Prompt length10,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_genExactly 1 file
Items array for extract and extract_structuredExactly 1 file

​
Image limits

ConstraintLimit
Resolution1024 x 1024 pixels
Maximum images or pages per request5. If more are provided, only the first 5 are processed.

​
OCR and file format support

OCR is not available on all endpoints.
EndpointOCRSupported file formats
POST /ai/text_genNoText-based files
POST /ai/extractNoText-based files
POST /ai/extract_structuredYes (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 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

1

Get the default configuration

Call with the mode you want (ask, text_gen, extract, or extract_structured) to retrieve the current defaults.
2

Modify the configuration

Change the fields you need: model, prompt_template, system_message, llm_endpoint_params, or num_tokens_for_completion. Leave other fields unchanged.
3

Pass it back in your request

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:
EndpointAgent typeConfiguration keys
POST /ai/askai_agent_askbasic_text, basic_text_multi, long_text, long_text_multi
POST /ai/text_genai_agent_text_genbasic_gen
POST /ai/extractai_agent_extractbasic_text, long_text
POST /ai/extract_structuredai_agent_extract_structuredbasic_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:
ProviderParam typeKey difference
openai_paramsUse temperature or top_p, not both
google_paramstemperature works with top_p and top_k together
aws_paramsSame as Google: temperature works alongside top_p and top_k
For detailed override examples, see the guide and the .

​
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 . To avoid disruption, pin your agent configuration to a specific model version using overrides. For full details, see .

​
Box AI for UI Elements

The 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 track Box AI interactions. Box admins can filter for the following action types:
Action typeDescription
AI queryThe user queried Box AI and received a response
Failed AI queryThe user queried Box AI but did not receive a response

​
Guides in this section

Tutorials

Step-by-step guides for each endpoint: ask, text generation, extraction, and model overrides.

Model overrides

Override default models, prompts, and LLM parameters. Includes the default configuration reference and versioning policy.

Supported models

Full list of core and customer-enabled models with capability tiers, compliance badges, and API names.

Quick starts

Get up and running in minutes with Python SDK walkthroughs for summarization and extraction.