REST API

Interact with Jinba Toolbox programmatically through the REST API

Overview

Jinba Toolbox exposes a REST API built on Hono.js. Every resource — organizations, toolsets, tools, versions, runs, webhooks, and API keys — is accessible through conventional HTTP endpoints under the /v1 prefix.

Base URL:

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

Authentication

All API requests (except explore routes) require authentication via a Bearer token. API keys are scoped to an organization and follow the jtb_ prefix convention.

Include the key in the Authorization header:

Authorization: Bearer jtb_xxxxxxxxxxxx

1. Create an API key

   Navigate to your organization settings and create a new API key. Give it a descriptive name such as production or ci-cd.

2. Store the key securely

   Copy the key immediately after creation — it will not be displayed again. Store it in an environment variable or secrets manager.

3. Include the key in requests

   Pass the key as a Bearer token in every API request.

Endpoint Reference

Organization Routes

These endpoints require organization membership. The authenticated API key must belong to the target organization.

Method	Endpoint	Description
GET	/v1/orgs	List organizations
POST	/v1/orgs	Create organization
GET	/v1/orgs/:orgId	Get organization details
PATCH	/v1/orgs/:orgId	Update organization
DELETE	/v1/orgs/:orgId	Delete organization

ToolSet Routes

Method	Endpoint	Description
GET	/v1/orgs/:orgId/toolsets	List toolsets
POST	/v1/orgs/:orgId/toolsets	Create toolset
GET	/v1/orgs/:orgId/toolsets/:slug	Get toolset
PATCH	/v1/orgs/:orgId/toolsets/:slug	Update toolset
DELETE	/v1/orgs/:orgId/toolsets/:slug	Delete toolset

Tool Routes

Method	Endpoint	Description
GET	/v1/orgs/:orgId/toolsets/:slug/tools	List tools in a toolset
POST	/v1/orgs/:orgId/toolsets/:slug/tools	Create tool
GET	/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug	Get tool
PATCH	/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug	Update tool
DELETE	/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug	Delete tool

Execution Routes

Method	Endpoint	Description
POST	/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/run	Execute a published tool
POST	/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/test	Test a tool (runs draft code)

Version Routes

Method	Endpoint	Description
GET	/v1/orgs/:orgId/toolsets/:slug/versions	List versions
POST	/v1/orgs/:orgId/toolsets/:slug/versions	Publish a new version
GET	/v1/orgs/:orgId/toolsets/:slug/versions/:version	Get version details
PUT	/v1/orgs/:orgId/toolsets/:slug/published-version	Set the active published version

Run History Routes

Method	Endpoint	Description
GET	/v1/orgs/:orgId/runs	List runs
GET	/v1/orgs/:orgId/runs/:runId	Get run details

Other Organization Routes

Method	Endpoint	Description
GET	/v1/orgs/:orgId/api-keys	List API keys
POST	/v1/orgs/:orgId/api-keys	Create API key
GET	/v1/orgs/:orgId/members	List members
GET	/v1/orgs/:orgId/webhooks	List webhooks
GET	/v1/orgs/:orgId/credits	Get credit balance

Public Routes

Public routes allow external consumers to execute tools using an API key, without requiring organization membership context.

Method	Endpoint	Description
POST	/v1/public/:orgSlug/:toolsetSlug/run/:toolSlug	Execute a tool
POST	/v1/public/:orgSlug/:toolsetSlug/mcp	MCP endpoint (JSON-RPC)

Explore Routes

Explore routes are unauthenticated and allow browsing public toolsets.

Method	Endpoint	Description
GET	/v1/explore/toolsets	List public toolsets
GET	/v1/explore/tags	List popular tags

Request & Response Examples

Execute a Tool

Request:

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!"
    }
  }'

Response (success):

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

Execute via Public Endpoint

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!"
    }
  }'

Create a 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"]
  }'

Publish a 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"
  }'

Error Handling

The API uses RFC 9457 Problem Details format for errors:

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

Common Status Codes

Status	Meaning
200	Success
201	Created
400	Bad Request — invalid input or missing required fields
401	Unauthorized — missing or invalid API key
403	Forbidden — API key lacks permission for this action
404	Not Found — resource does not exist
429	Too Many Requests — rate limit exceeded

Best Practices

• Store API keys in environment variables — never hard-code them in source code or commit them to version control.
• Implement retry logic with exponential backoff for transient failures and 429 responses.
• Use the public endpoint (/v1/public/...) when integrating external systems that only need to execute tools.
• Pin a specific version in the run request body when reproducibility matters.

Related

• SDK — Type-safe client library wrapping these endpoints
• MCP Integration — Model Context Protocol endpoints
• Webhooks — Receive event notifications for tool runs and more