メインコンテンツへスキップ

​
概要

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 ヘッダーにキーを含めてください： 
Authorization: Bearer jtb_xxxxxxxxxxxx
1

APIキーを作成する

組織の設定画面に移動し、新しいAPIキーを作成します。production や ci-cd など、わかりやすい名前を付けてください。
2

キーを安全に保存する

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

リクエストにキーを含める

すべてのAPIリクエストで、キーをBearerトークンとして渡してください。

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

​
組織ルート

これらのエンドポイントは組織メンバーシップが必要です。認証されたAPIキーは対象の組織に属している必要があります。
メソッドエンドポイント説明
GET/v1/orgs組織一覧の取得
POST/v1/orgs組織の作成
GET/v1/orgs/:orgId組織の詳細を取得
PATCH/v1/orgs/:orgId組織の更新
DELETE/v1/orgs/:orgId組織の削除

​
ToolSetルート

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

​
Toolルート

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

​
実行ルート

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

​
Versionルート

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

​
実行履歴ルート

メソッドエンドポイント説明
GET/v1/orgs/:orgId/runsRun一覧の取得
GET/v1/orgs/:orgId/runs/:runIdRunの詳細を取得

​
その他の組織ルート

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

​
パブリックルート

パブリックルートにより、外部の利用者は組織メンバーシップのコンテキストなしに、APIキーを使用してToolを実行できます。
メソッドエンドポイント説明
POST/v1/public/:orgSlug/:toolsetSlug/run/:toolSlugToolの実行
POST/v1/public/:orgSlug/:toolsetSlug/mcpMCPエンドポイント（JSON-RPC）

​
Exploreルート

Exploreルートは認証不要で、公開されたToolSetの閲覧が可能です。
メソッドエンドポイント説明
GET/v1/explore/toolsets公開ToolSet一覧の取得
GET/v1/explore/tags人気タグ一覧の取得

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

​
Toolの実行

リクエスト: 
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!"
    }
  }'
レスポンス（成功時）: 
{
  "runId": "run_abc123",
  "version": "1.2.0",
  "success": true,
  "output": {
    "ts": "1234567890.123456",
    "channel": "C01234567"
  },
  "logs": {
    "stdout": [],
    "stderr": []
  },
  "durationMs": 1234
}

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

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の作成

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の公開

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 形式でエラーを返します： 
{
  "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 — これらのエンドポイントをラップした型安全なクライアントライブラリ
  • MCP統合 — Model Context Protocolエンドポイント
  • Webhook — Toolの実行などのイベント通知を受信