A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Box API is how an app or AI agent works with a Box account: listing a folder, uploading and downloading files, copying, moving, and deleting content, searching, and sharing files through collaborations and shared links. Access is granted through an OAuth 2.0 access token, and the application scopes on that token, like reading all files or managing users, decide which actions it can take. Box can also notify an app when a file or folder changes, so an integration learns about activity without polling.
How an app or AI agent connects to Box determines what it can reach. There is the route for making calls, a webhook channel for being told when content changes, and a hosted server that exposes Box tools to agents, and each is governed by the access token behind it and the application scopes that token carries.
The Box Content API answers at https://api.box.com/2.0 and returns JSON. Uploads and downloads use a separate upload host at https://upload.box.com/api/2.0. A call authenticates with an OAuth 2.0 access token in the Authorization header, and an individual endpoint can be pinned to a dated version through the box-version header.
Box POSTs a payload to an HTTPS address registered on a file or folder when a chosen trigger fires, such as FILE.UPLOADED or COLLABORATION.CREATED. The payload carries the full object and the trigger name, the receiver verifies the BOX-SIGNATURE-PRIMARY header against the webhook's signing keys, and Box retries up to ten times on a failed delivery.
Box hosts a Model Context Protocol server at https://mcp.box.com that lets an AI agent use Box content through a single endpoint, with tools for search, Box AI, and folder and content actions. An admin enables it in the Box Admin Console, and agents authorize with OAuth. The earlier self-hosted community server is deprecated.
OAuth 2.0 is the standard three-legged flow where a Box user signs in and grants the application access, producing an access token that acts as that user and reaches only what the user can see. Refresh tokens keep the session alive. This is the route for an app acting on behalf of real Box users.
JWT is a server-to-server flow that needs no end-user sign-in. The application authenticates with a signed assertion and acts as a Service Account, an admin-like identity created when the app is authorized, which is why a Box admin must approve the app. It can also act as a managed or app user through the As-User header.
The Client Credentials Grant authenticates with a client id and client secret and no user sign-in. Setting box_subject_type to enterprise acts as the application's Service Account, while box_subject_type user acts as a chosen managed user or admin, once the app is configured for it in the Developer Console.
The Box API is split into areas an agent can act on, like files, folders, search, collaborations, shared links, and users. Each area has its own methods and its own application scopes, and writes in the files and folders areas move and delete real content.
Read a file's details, upload and download content, copy, update to rename, move, or lock, and delete a file.
Read a folder, list the items inside it, create a folder, update it to rename or move, and delete it.
Search across files, folders, and web links the authenticated user can reach.
Add a person or group as a collaborator on a file or folder, read, update, or remove a collaboration.
Create a shared link on a file or folder through its update method, and resolve a shared link to the item behind it.
Read the metadata on a file and apply a metadata template instance to it.
Read the authenticated user, list the enterprise's users, and create a managed user.
List the application's webhooks and create a webhook on a file or folder.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
FilesRead a file's details, upload and download content, copy, update to rename, move, or lock, and delete a file.6 | ||||||
| GET | /files/{file_id} | Retrieve the details about a file. | read | Read all files | Current | |
Application scope: Read all files and folders stored in Box (root_readonly). Read and write all files and folders (root_readwrite) also covers it. Acts onfile Permission (capability) Read all filesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /files/{file_id}/content | Return the contents of a file in binary format. The call returns a 302 redirect to a short-lived download URL on dl.boxcloud.com. | read | Read all files | Current | |
Application scope: Read all files and folders stored in Box (root_readonly). The download URL is not persistent, so the redirect must be followed. Acts onfile Permission (capability) Read all filesVersionAvailable since the API’s base version Webhook event file-downloadedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /files/content | Upload a small file to Box. For files over 50MB Box recommends the chunked upload API. This call goes to the upload host, https://upload.box.com/api/2.0. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). Uploads use the upload host, not the main api.box.com host. Acts onfile Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook event file-uploadedRate limit240 uploads per minute, per user SourceOfficial documentation ↗ | ||||||
| PUT | /files/{file_id} | Update a file. Used to rename or move a file, create a shared link on it, or lock it. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). A missing scope returns insufficient_scope. Acts onfile Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /files/{file_id}/copy | Create a copy of a file in a destination folder. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). The user needs access to the source file and the destination folder. Acts onfile Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook event file-copiedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /files/{file_id} | Delete a file, either permanently or by moving it to the trash. Enterprise settings decide which. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). Whether the file is trashed or permanently removed depends on enterprise settings. Acts onfile Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook event file-trashedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FoldersRead a folder, list the items inside it, create a folder, update it to rename or move, and delete it.5 | ||||||
| GET | /folders/{folder_id} | Retrieve a folder's details, including the first 100 items inside it. | read | Read all files | Current | |
Application scope: Read all files and folders stored in Box (root_readonly). The root folder is id 0. Acts onfolder Permission (capability) Read all filesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /folders/{folder_id}/items | Retrieve a page of items in a folder. Items can be files, folders, and web links. | read | Read all files | Current | |
Application scope: Read all files and folders stored in Box (root_readonly). Supports offset and marker pagination. Acts onfolder Permission (capability) Read all filesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /folders | Create a new empty folder within a specified parent folder. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). The user needs access to the parent folder. Acts onfolder Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook event folder-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /folders/{folder_id} | Update a folder. Used to rename or move it, create shared links, and update collaborations. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). A missing scope returns insufficient_scope. Acts onfolder Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /folders/{folder_id} | Delete a folder, either permanently or by moving it to the trash. A non-empty folder needs the recursive query parameter. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). Without recursive=true, deleting a non-empty folder returns folder_not_empty. Acts onfolder Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook event folder-trashedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchSearch across files, folders, and web links the authenticated user can reach.1 | ||||||
| GET | /search | Search for files, folders, web links, and shared files across the user's content or across the enterprise. | read | Read all files | Current | |
Application scope: Read all files and folders stored in Box (root_readonly). The scope parameter defaults to user_content; enterprise_content must be enabled by Box. Acts onsearch result Permission (capability) Read all filesVersionAvailable since the API’s base version Webhook eventNone Rate limit6 searches per second and 60 per minute, per user; 12 per second per enterprise SourceOfficial documentation ↗ | ||||||
CollaborationsAdd a person or group as a collaborator on a file or folder, read, update, or remove a collaboration.4 | ||||||
| POST | /collaborations | Add a collaboration for a single user or a single group to a file or folder, by email, user id, or group id. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). A group must be invitable, and information barriers can restrict who can be added. Acts oncollaboration Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook event collaboration-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /collaborations/{collaboration_id} | Retrieve a single collaboration. | read | Read all files | Current | |
Application scope: Read all files and folders stored in Box (root_readonly). Acts oncollaboration Permission (capability) Read all filesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /collaborations/{collaboration_id} | Update a collaboration. Used to change an item's owner or to accept a collaboration invite. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). Acts oncollaboration Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook event collaboration-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /collaborations/{collaboration_id} | Delete a single collaboration, removing that person or group's access to the item. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). Acts oncollaboration Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook event collaboration-removedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Shared linksCreate a shared link on a file or folder through its update method, and resolve a shared link to the item behind it.1 | ||||||
| GET | /shared_items | Return the file or folder represented by a shared link, whether from this enterprise or another. | read | Read all files | Current | |
Application scope: Read all files and folders stored in Box (root_readonly). The shared link, and any password, are passed in the boxapi header. Acts onshared link Permission (capability) Read all filesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MetadataRead the metadata on a file and apply a metadata template instance to it.2 | ||||||
| GET | /files/{file_id}/metadata | Retrieve all metadata instances on a file. | read | Read all files | Current | |
Application scope: Read all files and folders stored in Box (root_readonly). Acts onmetadata Permission (capability) Read all filesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /files/{file_id}/metadata/{scope}/{template_key} | Apply an instance of a metadata template to a file. The scope path part is global or enterprise. | write | Write all files | Current | |
Application scope: Read and write all files and folders stored in Box (root_readwrite). The scope path part names the template's namespace, global or enterprise. Acts onmetadata Permission (capability) Write all filesVersionAvailable since the API’s base version Webhook event metadata-instance-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead the authenticated user, list the enterprise's users, and create a managed user.3 | ||||||
| GET | /users/me | Retrieve the user who is currently authenticated. For a JWT app this is the service account by default. | read | — | Current | |
No extra scope beyond a valid token. The As-User header can run the call on behalf of another user. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users | Return a list of all users for the enterprise, with each user's user_id, public_name, and login. | read | Manage users | Current | |
Application scope: Manage users (manage_managed_users). The application and the authenticated user need permission to look up users across the enterprise. Acts onuser Permission (capability) Manage usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users | Create a new managed user in an enterprise. Only available to apps with admin permissions. | write | Manage users | Current | |
Application scope: Manage users (manage_managed_users). Creating users needs admin-level access. Acts onuser Permission (capability) Manage usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList the application's webhooks and create a webhook on a file or folder.2 | ||||||
| GET | /webhooks | Return all webhooks defined for the requesting application. | read | Manage webhooks | Current | |
Application scope: Manage webhooks (manage_webhook). Only returns webhooks on files or folders the authenticated user owns. Acts onwebhook Permission (capability) Manage webhooksVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhooks | Create a webhook on a file or folder for a chosen set of triggers. | write | Manage webhooks | Current | |
Application scope: Manage webhooks (manage_webhook). Up to 1000 webhooks per application, per user. Acts onwebhook Permission (capability) Manage webhooksVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Box can notify an app or AI agent when something happens to a file or folder, instead of the app repeatedly asking. Box posts a payload with the full object and the trigger that fired to an HTTPS address registered for the chosen events, and retries up to ten times if delivery fails.
| Event | What it signals | Triggered by |
|---|---|---|
FILE.UPLOADED | Fires when a file is uploaded to, or moved into, the monitored folder. | /files/content |
FILE.DOWNLOADED | Fires when a file is downloaded. | /files/{file_id}/content |
FILE.PREVIEWED | Fires when a file is previewed. | In-app only |
FILE.COPIED | Fires when a file is copied. | /files/{file_id}/copy |
FILE.TRASHED | Fires when a file is moved to the trash. | /files/{file_id} |
FILE.DELETED | Fires when a file is permanently deleted. | /files/{file_id} |
FOLDER.CREATED | Fires when a folder is created. | /folders |
FOLDER.DOWNLOADED | Fires when a folder is downloaded. | In-app only |
FOLDER.TRASHED | Fires when a folder is moved to the trash. | /folders/{folder_id} |
COLLABORATION.CREATED | Fires when a collaboration is created on a file or folder. | /collaborations |
COLLABORATION.ACCEPTED | Fires when a collaboration invite is accepted. | In-app only |
COLLABORATION.UPDATED | Fires when a collaboration is updated. | /collaborations/{collaboration_id} |
COLLABORATION.REMOVED | Fires when a collaboration is removed. | /collaborations/{collaboration_id} |
SHARED_LINK.CREATED | Fires when a shared link is created on a file or folder. | In-app only |
METADATA_INSTANCE.CREATED | Fires when a metadata template instance is associated with a file or folder. | /files/{file_id}/metadata/{scope}/{template_key} |
Box limits how fast an app or AI agent can call, by a per-user request rate measured per minute, with separate, tighter ceilings on uploads and on search.
Box meters requests per user, not by a per-method cost. A user gets 1,000 API requests per minute across the API, with tighter ceilings on the heavier operations: 240 file uploads per minute per user, and search held to 6 requests per second and 60 per minute per user, plus 12 per second per enterprise. Box Sign has its own limits, 100 create or resend requests per minute per user and 1,000 get requests per minute per user. Going over returns HTTP 429 with a retry-after header in seconds, and Box recommends exponential back-off rather than an immediate retry.
List endpoints use offset-based pagination through the limit and offset query parameters, and some endpoints also support marker-based pagination through a marker parameter for large or frequently changing collections. The list folder items endpoint returns a total_count and the entries for the requested page.
The simple upload endpoint is for small files; Box recommends the chunked upload API for files over 50MB. The list folder items endpoint returns up to 1,000 items per page. A webhook payload carries the full object that triggered it plus context, and Box retries a failed delivery up to ten times.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | The request body or parameters are malformed or invalid, such as a bad digest on an upload. | Read the message and code in the error object, correct the request, and resend. |
| 401 | unauthorized | The access token is missing, invalid, or expired. | Refresh or reissue the access token and resend with a valid Authorization header. |
| 403 | forbidden | The token is valid but the user or application is not permitted, often because the application lacks the right scope, returned as insufficient_scope. | Grant the missing application scope, or use an identity with access to the item. |
| 404 | not_found | The item does not exist, or the token cannot see it. Box returns 404 rather than 403 so it does not confirm a private item exists. | Confirm the id and that the token's identity has access to the item. |
| 409 | item_name_in_use | The request conflicts with the current state, such as a name already in use in the destination folder, or deleting a non-empty folder without recursive. | Resolve the conflict, for example by choosing a new name or passing recursive=true, then retry. |
| 412 | precondition_failed | An If-Match etag did not match because the item was changed since it was last read. | Refetch the item to get its current etag, then retry the write with that etag. |
| 429 | rate_limit_exceeded | A rate limit was exceeded, such as the per-user request, upload, or search ceiling. | Wait the seconds given in the retry-after header, then retry with exponential back-off. |
| 500 | internal_server_error | An error on Box's side, which can also appear as 502 or 503. | Retry with exponential back-off, honoring any Retry-After header. |
Box serves a single base API, version 2.0, in the path of every call. Individual endpoints can also carry a dated version, like 2025.0, requested through the box-version header, which defaults to 2024.0 when the header is absent.
Box serves a single base API, version 2.0, in the path of every call at https://api.box.com/2.0. On top of this, individual endpoints can carry a dated, year-based version requested through the box-version header, which defaults to 2024.0 when the header is absent. Year-based versions introduce breaking changes to specific endpoints, and each stable version is supported for at least 12 months.
Box shipped SDK releases across Node, .NET, Java, Python, and iOS adding new event types, AI extract structured parameters, and sign request schema updates.
Box AI added new models, including AWS Claude Opus 4.8, OpenAI GPT-5.4 mini, and Google Gemini 3.5 Flash, and retired twelve older models.
Box introduced year-based versioning for its public APIs. Every endpoint available at the end of 2024 was assigned 2024.0, the default when no box-version header is sent, and new endpoint versions ship under the calendar year of their release, like 2025.0, starting with the Sign Requests API.
Pin an endpoint's dated version through the box-version header and move up on a schedule that suits the integration.
Box API changelog ↗Bollard AI sits between a team's AI agents and Box. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.