> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> REST APIを通じてJinba Toolboxとプログラムでやり取りする

## 概要

Jinba ToolboxはHono.js上に構築されたREST APIを公開しています。組織、ToolSet、Tool、Version、Run、Webhook、APIキーなど、すべてのリソースは `/v1` プレフィックス配下の標準的なHTTPエンドポイントからアクセスできます。

**ベースURL**:

```
https://toolbox-api.jinba.dev/v1
```

## 認証

すべてのAPIリクエスト（Exploreルートを除く）は、**Bearer トークン**による認証が必要です。APIキーは組織にスコープされ、`jtb_` プレフィックスの命名規則に従います。

`Authorization` ヘッダーにキーを含めてください：

```bash theme={null}
Authorization: Bearer jtb_xxxxxxxxxxxx
```

<Steps>
  <Step title="APIキーを作成する">
    組織の設定画面に移動し、新しいAPIキーを作成します。`production` や `ci-cd` など、わかりやすい名前を付けてください。
  </Step>

  <Step title="キーを安全に保存する">
    作成直後にキーをコピーしてください。再度表示されることはありません。環境変数やシークレットマネージャーに保存してください。
  </Step>

  <Step title="リクエストにキーを含める">
    すべてのAPIリクエストで、キーをBearerトークンとして渡してください。
  </Step>
</Steps>

## エンドポイントリファレンス

### 組織ルート

これらのエンドポイントは組織メンバーシップが必要です。認証されたAPIキーは対象の組織に属している必要があります。

| メソッド   | エンドポイント           | 説明       |
| ------ | ----------------- | -------- |
| GET    | `/v1/orgs`        | 組織一覧の取得  |
| POST   | `/v1/orgs`        | 組織の作成    |
| GET    | `/v1/orgs/:orgId` | 組織の詳細を取得 |
| PATCH  | `/v1/orgs/:orgId` | 組織の更新    |
| DELETE | `/v1/orgs/:orgId` | 組織の削除    |

### ToolSetルート

| メソッド   | エンドポイント                          | 説明           |
| ------ | -------------------------------- | ------------ |
| GET    | `/v1/orgs/:orgId/toolsets`       | ToolSet一覧の取得 |
| POST   | `/v1/orgs/:orgId/toolsets`       | ToolSetの作成   |
| GET    | `/v1/orgs/:orgId/toolsets/:slug` | ToolSetの取得   |
| PATCH  | `/v1/orgs/:orgId/toolsets/:slug` | ToolSetの更新   |
| DELETE | `/v1/orgs/:orgId/toolsets/:slug` | ToolSetの削除   |

### Toolルート

| メソッド   | エンドポイント                                          | 説明                 |
| ------ | ------------------------------------------------ | ------------------ |
| GET    | `/v1/orgs/:orgId/toolsets/:slug/tools`           | ToolSet内のTool一覧を取得 |
| POST   | `/v1/orgs/:orgId/toolsets/:slug/tools`           | Toolの作成            |
| GET    | `/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug` | Toolの取得            |
| PATCH  | `/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug` | Toolの更新            |
| DELETE | `/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug` | Toolの削除            |

### 実行ルート

| メソッド | エンドポイント                                               | 説明                   |
| ---- | ----------------------------------------------------- | -------------------- |
| POST | `/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/run`  | 公開済みToolの実行          |
| POST | `/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/test` | Toolのテスト（ドラフトコードを実行） |

### Versionルート

| メソッド | エンドポイント                                            | 説明                 |
| ---- | -------------------------------------------------- | ------------------ |
| GET  | `/v1/orgs/:orgId/toolsets/:slug/versions`          | Version一覧の取得       |
| POST | `/v1/orgs/:orgId/toolsets/:slug/versions`          | 新しいVersionの公開      |
| GET  | `/v1/orgs/:orgId/toolsets/:slug/versions/:version` | Versionの詳細を取得      |
| PUT  | `/v1/orgs/:orgId/toolsets/:slug/published-version` | アクティブな公開Versionの設定 |

### 実行履歴ルート

| メソッド | エンドポイント                       | 説明        |
| ---- | ----------------------------- | --------- |
| GET  | `/v1/orgs/:orgId/runs`        | Run一覧の取得  |
| GET  | `/v1/orgs/:orgId/runs/:runId` | Runの詳細を取得 |

### その他の組織ルート

| メソッド | エンドポイント                    | 説明           |
| ---- | -------------------------- | ------------ |
| GET  | `/v1/orgs/:orgId/api-keys` | APIキー一覧の取得   |
| POST | `/v1/orgs/:orgId/api-keys` | APIキーの作成     |
| GET  | `/v1/orgs/:orgId/members`  | メンバー一覧の取得    |
| GET  | `/v1/orgs/:orgId/webhooks` | Webhook一覧の取得 |
| GET  | `/v1/orgs/:orgId/credits`  | クレジット残高の取得   |

### パブリックルート

パブリックルートにより、外部の利用者は組織メンバーシップのコンテキストなしに、APIキーを使用してToolを実行できます。

| メソッド | エンドポイント                                          | 説明                   |
| ---- | ------------------------------------------------ | -------------------- |
| POST | `/v1/public/:orgSlug/:toolsetSlug/run/:toolSlug` | Toolの実行              |
| POST | `/v1/public/:orgSlug/:toolsetSlug/mcp`           | MCPエンドポイント（JSON-RPC） |

### Exploreルート

Exploreルートは認証不要で、公開されたToolSetの閲覧が可能です。

| メソッド | エンドポイント                | 説明             |
| ---- | ---------------------- | -------------- |
| GET  | `/v1/explore/toolsets` | 公開ToolSet一覧の取得 |
| GET  | `/v1/explore/tags`     | 人気タグ一覧の取得      |

## リクエストとレスポンスの例

### Toolの実行

**リクエスト**:

```bash theme={null}
curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/tools/post-message/run \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "channel": "#general",
      "text": "Hello from Jinba Toolbox!"
    }
  }'
```

**レスポンス**（成功時）:

```json theme={null}
{
  "runId": "run_abc123",
  "version": "1.2.0",
  "success": true,
  "output": {
    "ts": "1234567890.123456",
    "channel": "C01234567"
  },
  "logs": {
    "stdout": [],
    "stderr": []
  },
  "durationMs": 1234
}
```

### パブリックエンドポイント経由の実行

```bash theme={null}
curl -X POST https://toolbox-api.jinba.dev/v1/public/my-org/slack-tools/run/post-message \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "channel": "#general",
      "text": "Hello!"
    }
  }'
```

### ToolSetの作成

```bash theme={null}
curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "slack-tools",
    "name": { "default": "Slack Tools" },
    "description": { "default": "A collection of Slack integration tools" },
    "sandbox": {
      "provider": "e2b",
      "language": "typescript",
      "packages": [{ "name": "@slack/web-api" }],
      "resources": { "timeout": 60000 }
    },
    "visibility": "private",
    "tags": ["slack", "messaging"]
  }'
```

### Versionの公開

```bash theme={null}
curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/versions \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.3.0",
    "releaseNotes": "Added thread reply support"
  }'
```

## エラーハンドリング

APIは **RFC 9457 Problem Details** 形式でエラーを返します：

```json theme={null}
{
  "type": "https://toolbox-api.jinba.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "ToolSet 'unknown-toolset' not found in organization."
}
```

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

| ステータス | 意味                             |
| ----- | ------------------------------ |
| 200   | 成功                             |
| 201   | 作成完了                           |
| 400   | 不正なリクエスト -- 無効な入力または必須フィールドの欠落 |
| 401   | 未認証 -- APIキーが欠落または無効           |
| 403   | 禁止 -- APIキーにこの操作の権限がない         |
| 404   | 未検出 -- リソースが存在しない              |
| 429   | リクエスト過多 -- レート制限を超過            |

## ベストプラクティス

* **APIキーを環境変数に保存する** -- ソースコードにハードコードしたり、バージョン管理にコミットしたりしないでください。
* **指数バックオフによるリトライロジックを実装する** -- 一時的な障害や429レスポンスに対応してください。
* **パブリックエンドポイントを使用する**（`/v1/public/...`） -- Toolの実行のみが必要な外部システムを統合する場合に使用してください。
* **特定のVersionを指定する** -- 再現性が重要な場合は、Runリクエストボディでバージョンを指定してください。

## 関連ドキュメント

* [SDK](/ja/pages/toolbox/developer/sdk) -- これらのエンドポイントをラップした型安全なクライアントライブラリ
* [MCP統合](/ja/pages/toolbox/developer/mcp) -- Model Context Protocolエンドポイント
* [Webhook](/ja/pages/toolbox/developer/webhooks) -- Toolの実行などのイベント通知を受信