> ## 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 Platform API agent playbook

> Authentication, core endpoints, SDKs, rate limits, and usage instructions for coding agents integrating with the Box API.

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](https://developer.box.com/llms.txt).

## Base URL

```text theme={null}
https://api.box.com/2.0/
```

Upload endpoints use a separate domain:

```text theme={null}
https://upload.box.com/api/2.0/
```

## Authentication

Every request carries an access token in the `Authorization` header:

```bash theme={null}
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](https://app.box.com/developers/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`.

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

Guide: [Authentication](/guides/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](/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:**

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

Rate-limit documentation: [Rate limits](/guides/api-calls/permissions-and-errors/rate-limits)

## Error handling

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

```json theme={null}
{
  "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](/guides/api-calls/permissions-and-errors/common-errors)

## Pagination

### Offset-based (default for most list endpoints)

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

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

<Note>
  Offset-based pagination caps at **10,000 items**. Switch to marker-based for larger sets.
</Note>

### Marker-based

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

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

Pagination guide: [Pagination](/guides/api-calls/pagination)

## SDKs

| Language | Package                                                       | Install                                        |
| -------- | ------------------------------------------------------------- | ---------------------------------------------- |
| Python   | [boxsdk](https://pypi.org/project/boxsdk/)                    | `pip install "boxsdk>=10"`                     |
| Node.js  | [box](https://www.npmjs.com/package/box)                      | `npm install box`                              |
| Java     | [box-java-sdk](https://github.com/box/box-java-sdk)           | `implementation 'com.box:box-java-sdk:10.9.0'` |
| .NET     | [Box.V2.Core](https://www.nuget.org/packages/Box.V2.Core)     | `Install-Package Box.V2.Core`                  |
| Swift    | [box-swift-sdk-gen](https://github.com/box/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](https://github.com/box/box-openapi)
* Bundled JSON: [openapi.json](https://developer.box.com/openapi/openapi.json)

## Quick links

| Resource               | URL                                                         |
| ---------------------- | ----------------------------------------------------------- |
| Developer docs         | [developer.box.com](https://developer.box.com)              |
| llms.txt               | [llms.txt](https://developer.box.com/llms.txt)              |
| API reference          | [API reference](/reference)                                 |
| Getting started        | [Getting started](/guides/getting-started)                  |
| Authentication         | [Authentication](/guides/authentication)                    |
| Box AI                 | [Box AI](/guides/box-ai)                                    |
| Changelog              | [Changelog](/changelog)                                     |
| Developer Console      | [Developer Console](https://app.box.com/developers/console) |
| Free developer account | [Sign up](https://account.box.com/signup/developer)         |