> ## 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エージェントプレイブック

> Box APIと統合するエージェントのコーディングに役立つ認証、主要エンドポイント、SDK、レート制限、および使用手順。

Box APIに対して統合を構築する場合は、このページを参考にしてください。認証、主要エンドポイント、SDK、レート制限、エラー処理、ページネーション、よくある落とし穴について解説しています。

ドキュメントの各ページへのリンク一覧については、[llms.txt](https://developer.box.com/llms.txt)を参照してください。

## ベースURL

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

個別のドメインを使用してエンドポイントをアップロードします。

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

## 認証

すべてのリクエストの`Authorization`ヘッダーにアクセストークンが含まれています。

```bash theme={null}
curl https://api.box.com/2.0/users/me \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

### メソッド

| メソッド | 使用するタイミング | 資格情報 |
| - | - | - |
| **OAuth 2.0** | Boxでサインインするユーザー向けアプリ | クライアントID、クライアントシークレット、リダイレクトURI |
| **クライアント資格情報許可 (CCG)** | バックエンドサービス、自動化、自動実行コード | クライアントID、クライアントシークレット、Enterprise IDまたはユーザーID |
| **JWT** | キーペアベースの認証を必要とするサーバーアプリ | クライアントID、クライアントシークレット、公開/秘密キーペア |
| **開発者トークン** | 簡易テストのみ (1時間で有効期限切れ) | [開発者コンソール](https://app.box.com/developers/console)で生成 |

### トークンのライフサイクル

* アクセストークンは、**60分** (レスポンス内の`expires_in`) 後に期限切れになります。
* OAuth 2.0から更新トークン (60日間有効、1回のみ使用可能) が返されます。期限切れになる前に交換してください。
* CCGおよびJWTアプリが、同じ資格情報で新しいトークンをリクエストします。
* すべてのメソッドが、`POST https://api.box.com/oauth2/token`にトークンをリクエストします。

<Warning>
  資格情報をコミットしないでください。クライアントシークレット、秘密キー、トークンは環境変数またはシークレットマネージャに格納します。
</Warning>

ガイド: [認証](/guides/authentication)

## 主要エンドポイント

| リソース | 主な操作 |
| - | - |
| **ファイル** | `GET /files/{id}` · `POST /files/content` (50 MB以下のアップロード) · `PUT /files/{id}` · `DELETE /files/{id}` · `GET /files/{id}/content` (ダウンロード) |
| **フォルダ** | `GET /folders/{id}` · `POST /folders` · `PUT /folders/{id}` · `DELETE /folders/{id}` · `GET /folders/{id}/items` |
| **アップロード** | 直接: `POST https://upload.box.com/api/2.0/files/content` · 分割: セッションの作成 → パーツのアップロード → コミット |
| **検索** | `GET /search` (テキスト全体) · `POST /metadata_queries/execute_read` (メタデータ) |
| **メタデータ** | `GET /files/{id}/metadata` · `POST /files/{id}/metadata/{scope}/{template}` · テンプレート、インスタンス、カスケードポリシー |
| **コラボレーション** | `POST /collaborations` · `GET /files/{id}/collaborations` · `GET /folders/{id}/collaborations` |
| **Webhook** | `POST /webhooks` · `GET /webhooks` · `PUT /webhooks/{id}` · `DELETE /webhooks/{id}` |
| **イベント** | `GET /events` (ユーザーまたは企業のストリーム) |
| **Box AI** | `POST /ai/ask` · `POST /ai/text_gen` · `POST /ai/extract` · `POST /ai/extract_structured` |

参考情報: [APIリファレンス](/reference)

## レート制限と再試行戦略

レート制限を超えた場合に、APIから**HTTP 429**が返されます。レスポンスには、`retry-after`ヘッダーと待機する秒数が含まれます。

**戦略:**

1. すべてのレスポンスで`429`ステータスを確認します。
2. `retry-after`ヘッダー値を読みます。
3. ヘッダー値の秒数以上待ってから再試行します。
4. 同時に実行されるリクエスト用にジッターによる指数バックオフを使用します。
5. 同じリクエストでの再試行が5回を超えないようにしてください。

レート制限に関するドキュメント: [レート制限](/guides/api-calls/permissions-and-errors/rate-limits)

## エラー処理

Boxは、`type`、`status`、`code`、および`message`が含まれるJSONとしてエラーを返します。

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

### 一般的なステータスコード

| ステータス | 意味 | 動作 |
| - | - | - |
| `400` | Bad request (不正なリクエスト) — ペイロードの形式が正しくないか、必須フィールドが欠落している | リクエスト本文を修正する |
| `401` | Unauthorized (未承認) — 期限切れまたは無効なトークン | 更新または再認証を行う |
| `403` | Forbidden (禁止) — スコープまたは権限が不足している | アプリのスコープとユーザーのアクセス権限を確認する |
| `404` | Not found (見つからない) — 項目が存在しないか、ユーザーがアクセス権限を持っていない | 項目IDとトークンを確認する |
| `409` | Conflict (競合) — 名前またはバージョンの競合 | 一意の名前を使用するか、`etag`を確認する |
| `429` | Rate limited (レート制限) | `retry-after`ヘッダー値が経過してから再試行する |

一般的なエラーのガイド: [一般的なエラー](/guides/api-calls/permissions-and-errors/common-errors)

## ページネーション

### オフセットベース (ほとんどのリストエンドポイントでのデフォルト設定)

`offset`および`limit`クエリパラメータを使用します。レスポンスには、`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>
  オフセットベースのページネーションの上限は、**10,000項目**です。これを超える項目数のセットの場合は、マーカーベースに切り替えてください。
</Note>

### マーカーベース

`usemarker=true`を使用し、前のレスポンスの`next_marker`値を渡します。

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

ページネーションのガイド: [ページネーション](/guides/api-calls/pagination)

## SDK

| 言語 | パッケージ | インストール |
| - | - | - |
| 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 |

すべてのSDKが、v10以上です。非推奨の生成済みパッケージ (`box-typescript-sdk-gen`、`box-sdk-gen`、またはその他の`*-sdk-gen`アーティファクト) は使用しないでください。

## よくある落とし穴

* **フォルダ0はルートです。**すべてのフォルダツリーがID `0`から開始されます。その他のフォルダIDの存在を想定しないようにしてください。
* **サービスアカウントは、最初は空の状態です。**既存のコンテンツにアクセスできるようにするには、コラボレータとして招待します。
* **トークンはスコープによって制限されます。**ユーザーがファイルへのアクセス権限を持っていても、アプリに必須スコープが設定されていない場合、トークンは失敗します。
* **アップロードには異なるドメインが使用されます。**使用されるのは`upload.box.com`であり、`api.box.com`ではありません。
* **分割アップロードには、正確なパーツサイズが必要です** (最後のパーツを除く)。
* **Webhookハンドラは、30秒以内に2xxを返す必要があります。**必要に応じて、イベントを非同期で処理してください。
* **Webhookは順不同で配信されます。**冪等性のある方法でイベントを処理してください。
* **インスタンスをファイルに適用する前に、メタデータテンプレートが存在している必要があります。**
* **メタデータクエリのテンプレートキーとフィールド名では、大文字と小文字が区別されます。**
* **Box AIエンドポイントを使用するには、アプリで \[AIを管理する] スコープが有効になっている必要があります。**

## OpenAPI仕様

詳細なOpenAPI 3.1仕様は、以下の場所で公開されています。

* ソース: [box-openapi](https://github.com/box/box-openapi)
* バンドルされたJSON: [openapi.json](https://developer.box.com/openapi/openapi.json)

## クイックリンク

| リソース | URL |
| - | - |
| Developerドキュメント | [developer.box.com/ja](https://developer.box.com) |
| llms.txt | [llms.txt](https://developer.box.com/llms.txt) |
| APIリファレンス | [APIリファレンス](/reference) |
| はじめに | [はじめに](/guides/getting-started) |
| 認証 | [認証](/guides/authentication) |
| Box AI | [Box AI](/guides/box-ai) |
| 変更ログ | [変更ログ](/changelog) |
| 開発者コンソール | [開発者コンソール](https://app.box.com/developers/console) |
| 無料のDeveloperアカウント | [サインアップ](https://account.box.com/signup/developer) |