REST API

概要

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

https://toolbox-api.jinba.io/v1

認証

すべてのAPIリクエスト（Exploreルートを除く）は、Bearer トークンによる認証が必要です。APIキーは組織にスコープされ、Memberレベルの権限で動作し、jtb_ プレフィックスの命名規則に従います。Webコンソールは代わりにJinbaAuthのセッショントークンで認証します。 Authorization ヘッダーにキーを含めてください：

Authorization: Bearer jtb_xxxxxxxxxxxx

一部のエンドポイントはAPIキーではなくサインイン済みユーザーを必要とし、キーで呼び出すと 401 を返します：GET /v1/orgs、GET /v1/orgs/:orgId、GET /v1/orgs/:orgId/members、.../test エンドポイント、APIキーの作成・表示・削除。Versionの公開をAPIキーで呼び出すと 400（“User context required”）で失敗します。

APIキーを作成する

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

キーを安全に保存する

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

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

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

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

組織ルート

これらのエンドポイントは組織メンバーシップが必要です。認証されたAPIキーは対象の組織に属している必要があります。:orgId には組織ID（またはスラッグ）を指定できます。

メソッド	エンドポイント	説明
GET	`/v1/orgs`	サインイン済みユーザーの組織一覧の取得（セッションのみ）
GET	`/v1/orgs/:orgId`	組織の詳細と自分のロールを取得（セッションのみ）

組織の作成・更新・削除はJinbaAuthで行います。これらのパスへの POST、PATCH、DELETE は 403 を返します（POST をAPIキーで呼び出した場合は 401）。

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の作成（`slug`、`name`、`description`、`code`）
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の削除

inputSchema と outputSchema はリクエストフィールドではありません。code が作成・更新されるたびに、APIはコードの input / output 定義から両方のスキーマを抽出し、抽出できない場合はリクエストを拒否します（400）。

実行ルート

メソッド	エンドポイント	説明
POST	`/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/run`	公開済みToolの実行（`input`、任意の `version`、任意の `environmentSlug`）
POST	`/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/test`	ドラフトコードでToolをテスト（`input`、任意の `code` 上書き、任意の `environmentSlug`。セッションのみ、クレジット消費なし）

Versionルート

メソッド	エンドポイント	説明
GET	`/v1/orgs/:orgId/toolsets/:slug/versions`	Version一覧と直近30日の実行回数を取得（`?environment=` でアクティブVersionを報告する環境を選択）
POST	`/v1/orgs/:orgId/toolsets/:slug/versions`	新しいVersionの公開（`version`、任意の `releaseNotes`、`setAsPublished` デフォルト `true`、`environmentSlug` デフォルト `default`。セッションのみ）
GET	`/v1/orgs/:orgId/toolsets/:slug/versions/:version`	Versionの詳細を取得
GET	`/v1/orgs/:orgId/toolsets/:slug/versions/:version/export`	公開済みVersionをZIPとしてダウンロード
PUT	`/v1/orgs/:orgId/toolsets/:slug/published-version`	アクティブVersionの設定（`version`、`environmentSlug` デフォルト `default`）

実行履歴ルート

メソッド	エンドポイント	説明
GET	`/v1/orgs/:orgId/runs`	Run一覧の取得（`?role=caller\|provider`、`?limit=1-100`、`?offset=`）
GET	`/v1/orgs/:orgId/runs/:runId`	Runの詳細を取得（呼び出し元の組織には完全な詳細、プロバイダーには限定的な詳細）

その他の組織ルート

メソッド	エンドポイント	説明
GET	`/v1/orgs/:orgId/api-keys`	APIキー一覧の取得
POST	`/v1/orgs/:orgId/api-keys`	APIキーの作成（`name`、`environmentSlug` デフォルト `default`。セッションのみ）
GET	`/v1/orgs/:orgId/api-keys/:keyId/reveal`	完全なキーの表示（セッションのみ）
DELETE	`/v1/orgs/:orgId/api-keys/:keyId`	APIキーの削除（セッションのみ）
GET	`/v1/orgs/:orgId/members`	メンバー一覧の取得（セッションのみ）
GET	`/v1/orgs/:orgId/webhooks`	Webhook一覧の取得（Webhook を参照）
GET	`/v1/orgs/:orgId/credits`	クレジット残高の取得
GET	`/v1/orgs/:orgId/credits/transactions`	クレジット取引一覧の取得
POST	`/v1/orgs/:orgId/toolsets/:slug/packages`	パッケージの追加・更新（`name`、任意の `version`）
GET / POST / PATCH / DELETE	`/v1/orgs/:orgId/toolsets/:slug/env`	環境変数の管理（`?environment=` / `environmentSlug`）
GET / POST / PATCH / DELETE	`/v1/orgs/:orgId/toolsets/:slug/environments`	環境プロファイルの管理
GET	`/v1/orgs/:orgId/toolsets/:slug/export`	ドラフトのToolSetをZIPとしてダウンロード
POST	`/v1/orgs/:orgId/toolsets/:slug/import`	ZIPからToolをインポート（multipart）

パブリックルート

パブリックルートにより、外部の利用者は組織メンバーシップのコンテキストなしに、APIキーを使用してToolを実行できます。:orgId にはプロバイダー組織の正規のIDを指定する必要があります（スラッグは使用できません）。公開ToolSetは有効な任意のAPIキーで呼び出せます。非公開ToolSetはその組織自身のキーでのみアクセスできます。クレジットは呼び出し元の組織に課金されます。

メソッド	エンドポイント	説明
POST	`/v1/public/:orgId/:toolsetSlug/run/:toolSlug`	Toolの実行（`input`）。成功時は `200`、Tool実行が失敗した場合は `500` を返す
POST	`/v1/public/:orgId/:toolsetSlug/mcp`	MCPエンドポイント（JSON-RPC）。ToolSetでMCPが有効である必要がある

Exploreルート

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

メソッド	エンドポイント	説明
GET	`/v1/explore/toolsets`	公開Versionを持つ公開ToolSet一覧の取得（`?q=`、`?tag=`、`?limit=` 最大100、`?offset=`）
GET	`/v1/explore/toolsets/:orgId/:toolsetSlug`	公開ToolSetの詳細（Toolはスキーマのみでコードは含まない）とVersion一覧を取得
GET	`/v1/explore/tags`	人気タグ一覧の取得

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

Toolの実行

リクエスト:

curl -X POST https://toolbox-api.jinba.io/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!"
    }
  }'

レスポンス（常に 200。success を確認してください）:

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

Toolが失敗した場合、success は false になり、output の代わりに error（{ name, message, traceback? }）が設定されます。

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

パブリックエンドポイントのレスポンスは同じ形式ですが、logs は含まれません。

curl -X POST https://toolbox-api.jinba.io/v1/public/{orgId}/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.io/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",
    "mcpEnabled": false,
    "tags": ["slack", "messaging"]
  }'

visibility は private または public です。resources.timeout はミリ秒単位（最大 3600000、省略時のデフォルトは15分）です。

Versionの公開

curl -X POST https://toolbox-api.jinba.io/v1/orgs/{orgId}/toolsets/slack-tools/versions \
  -H "Authorization: Bearer <JinbaAuth session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.3.0",
    "releaseNotes": "Added thread reply support"
  }'

"setAsPublished": false を渡すか別の environmentSlug を指定しない限り、新しいVersionは default 環境のアクティブVersionになります。公開にはサインイン済みセッションが必要です。

エラーハンドリング

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

{
  "type": "not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "ToolSet 'unknown-toolset' not found"
}

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

ステータス	意味
200	成功
201	作成完了
400	不正なリクエスト — 無効な入力または必須フィールドの欠落
401	未認証 — APIキーが欠落または無効
402	支払いが必要 — 呼び出し元の組織のクレジットが不足している
403	禁止 — APIキーにこの操作の権限がない
404	未検出 — リソースが存在しない
409	競合 — 例：そのバージョン番号が既に存在する

ベストプラクティス

APIキーを環境変数に保存する — ソースコードにハードコードしたり、バージョン管理にコミットしたりしないでください。
指数バックオフによるリトライロジックを実装する — 一時的な障害に対応してください。
パブリックエンドポイントを使用する（/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の公開

エラーハンドリング

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

ベストプラクティス

関連ドキュメント