REST API

概要

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

APIキーを作成する

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

キーを安全に保存する

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

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

すべての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リクエストボディでバージョンを指定してください。

Docs

概要

認証

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

組織ルート

ToolSetルート

Toolルート

実行ルート

Versionルート

実行履歴ルート

その他の組織ルート

パブリックルート

Exploreルート

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

Toolの実行

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

ToolSetの作成

Versionの公開

エラーハンドリング

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

ベストプラクティス

関連ドキュメント

​概要

​認証

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

​組織ルート

​ToolSetルート

​Toolルート

​実行ルート

​Versionルート

​実行履歴ルート

​その他の組織ルート

​パブリックルート

​Exploreルート

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

​Toolの実行

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

​ToolSetの作成

​Versionの公開

​エラーハンドリング

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

​ベストプラクティス

​関連ドキュメント

概要

認証

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

組織ルート

ToolSetルート

Toolルート

実行ルート

Versionルート

実行履歴ルート

その他の組織ルート

パブリックルート

Exploreルート

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

Toolの実行

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

ToolSetの作成

Versionの公開

エラーハンドリング

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

ベストプラクティス

関連ドキュメント