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

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/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の実行

リクエスト:

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の実行などのイベント通知を受信