Box Platform API agent playbook

Use this page when building integrations against the Box API. It covers authentication, core endpoints, SDKs, rate limits, error handling, pagination, and common pitfalls. For full page-by-page navigation, see llms.txt.

Base URL

https://api.box.com/2.0/

Upload endpoints use a separate domain:

https://upload.box.com/api/2.0/

Authentication

Every request carries an access token in the Authorization header:

curl https://api.box.com/2.0/users/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

Methods

Method	When to use	Credentials
OAuth 2.0	User-facing apps where people sign in with Box	Client ID, client secret, redirect URI
Client Credentials Grant (CCG)	Backend services, automations, unattended code	Client ID, client secret, enterprise or user ID
JWT	Server apps that need keypair-based verification	Client ID, client secret, public/private keypair
Developer Token	Quick testing only (expires in 1 hour)	Generated in the Developer Console

Token lifecycle

Access tokens expire after 60 minutes (expires_in in the response).
OAuth 2.0 returns a refresh token (valid 60 days, single use). Exchange it before it expires.
CCG and JWT apps request a new token with the same credentials.
All methods request tokens from POST https://api.box.com/oauth2/token.

Never commit credentials. Store client secrets, private keys, and tokens in environment variables or a secrets manager.

Guide: Authentication

Core endpoints

Resource	Key operations
Files	`GET /files/{id}` · `POST /files/content` (upload ≤ 50 MB) · `PUT /files/{id}` · `DELETE /files/{id}` · `GET /files/{id}/content` (download)
Folders	`GET /folders/{id}` · `POST /folders` · `PUT /folders/{id}` · `DELETE /folders/{id}` · `GET /folders/{id}/items`
Uploads	Direct: `POST https://upload.box.com/api/2.0/files/content` · Chunked: create session → upload parts → commit
Search	`GET /search` (full text) · `POST /metadata_queries/execute_read` (metadata)
Metadata	`GET /files/{id}/metadata` · `POST /files/{id}/metadata/{scope}/{template}` · templates, instances, cascade policies
Collaborations	`POST /collaborations` · `GET /files/{id}/collaborations` · `GET /folders/{id}/collaborations`
Webhooks	`POST /webhooks` · `GET /webhooks` · `PUT /webhooks/{id}` · `DELETE /webhooks/{id}`
Events	`GET /events` (user or enterprise stream)
Box AI	`POST /ai/ask` · `POST /ai/text_gen` · `POST /ai/extract` · `POST /ai/extract_structured`

Reference: API reference

Rate limits and retry strategy

The API returns HTTP 429 when you exceed rate limits. The response includes a retry-after header with the number of seconds to wait. Strategy:

Check for 429 status on every response.
Read the retry-after header value.
Wait at least that many seconds before retrying.
Use exponential backoff with jitter for concurrent requests.
Do not retry more than 5 times for the same request.

Rate-limit documentation: Rate limits

Error handling

Box returns errors as JSON with a type, status, code, and message:

{
  "type": "error",
  "status": 409,
  "code": "item_name_in_use",
  "message": "Item with the same name already exists."
}

Common status codes

Status	Meaning	Action
`400`	Bad request — malformed payload or missing required field	Fix the request body
`401`	Unauthorized — expired or invalid token	Refresh or re-authenticate
`403`	Forbidden — insufficient scopes or permissions	Check app scopes and user access
`404`	Not found — item does not exist or user lacks access	Verify the item ID and token
`409`	Conflict — name collision or version conflict	Use a unique name or check `etag`
`429`	Rate limited	Retry after the `retry-after` header value

Common-errors guide: Common errors

Pagination

Offset-based (default for most list endpoints)

Use offset and limit query parameters. The response includes total_count.

curl "https://api.box.com/2.0/folders/0/items?offset=0&limit=100" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Offset-based pagination caps at 10,000 items. Switch to marker-based for larger sets.

Marker-based

Use usemarker=true and pass the next_marker value from the previous response.

curl "https://api.box.com/2.0/folders/0/items?usemarker=true&limit=1000" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Pagination guide: Pagination

SDKs

Language	Package	Install
Python	boxsdk	`pip install "boxsdk>=10"`
Node.js	box	`npm install box`
Java	box-java-sdk	`implementation 'com.box:box-java-sdk:10.9.0'`
.NET	Box.V2.Core	`Install-Package Box.V2.Core`
Swift	box-swift-sdk-gen	Swift Package Manager

All SDKs are v10+. Do not use deprecated generated packages (box-typescript-sdk-gen, box-sdk-gen, or other *-sdk-gen artifacts).

Common gotchas

Folder 0 is root. All folder trees start at ID 0. Do not assume any other folder ID exists.
Service Accounts start empty. Invite them as collaborators to access existing content.
Scopes restrict tokens. A user may have access to a file, but the token still fails if the app lacks the required scope.
Uploads use a different domain. upload.box.com, not api.box.com.
Chunked uploads require exact part sizes except for the last part.
Webhook handlers must return 2xx within 30 seconds. Process events asynchronously if needed.
Webhook delivery is not ordered. Process events idempotently.
Metadata templates must exist before you apply instances to files.
Metadata queries are case-sensitive for template keys and field names.
Box AI endpoints require the “Manage AI” scope enabled on the app.

OpenAPI specification

The full OpenAPI 3.1 spec is published at:

Source: box-openapi
Bundled JSON: openapi.json

Quick links

Resource	URL
Developer docs	developer.box.com
llms.txt	llms.txt
API reference	API reference
Getting started	Getting started
Authentication	Authentication
Box AI	Box AI
Changelog	Changelog
Developer Console	Developer Console
Free developer account	Sign up

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Box Platform API agent playbook

Base URL

Authentication

Methods

Token lifecycle

Core endpoints

Rate limits and retry strategy

Error handling

Common status codes

Offset-based (default for most list endpoints)

Marker-based

SDKs

Common gotchas

OpenAPI specification

Quick links

​Base URL

​Authentication

​Methods

​Token lifecycle

​Core endpoints

​Rate limits and retry strategy

​Error handling

​Common status codes

​Pagination

​Offset-based (default for most list endpoints)

​Marker-based

​SDKs

​Common gotchas

​OpenAPI specification

​Quick links

Base URL

Authentication

Methods

Token lifecycle

Core endpoints

Rate limits and retry strategy

Error handling

Common status codes

Pagination

Offset-based (default for most list endpoints)

Marker-based

SDKs

Common gotchas

OpenAPI specification

Quick links