Skip to main content

​
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.
MethodEndpointDescription
GET/v1/orgsList organizations
POST/v1/orgsCreate organization
GET/v1/orgs/:orgIdGet organization details
PATCH/v1/orgs/:orgIdUpdate organization
DELETE/v1/orgs/:orgIdDelete organization

​
ToolSet Routes

MethodEndpointDescription
GET/v1/orgs/:orgId/toolsetsList toolsets
POST/v1/orgs/:orgId/toolsetsCreate toolset
GET/v1/orgs/:orgId/toolsets/:slugGet toolset
PATCH/v1/orgs/:orgId/toolsets/:slugUpdate toolset
DELETE/v1/orgs/:orgId/toolsets/:slugDelete toolset

​
Tool Routes

MethodEndpointDescription
GET/v1/orgs/:orgId/toolsets/:slug/toolsList tools in a toolset
POST/v1/orgs/:orgId/toolsets/:slug/toolsCreate tool
GET/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlugGet tool
PATCH/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlugUpdate tool
DELETE/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlugDelete tool

​
Execution Routes

MethodEndpointDescription
POST/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/runExecute a published tool
POST/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/testTest a tool (runs draft code)

​
Version Routes

MethodEndpointDescription
GET/v1/orgs/:orgId/toolsets/:slug/versionsList versions
POST/v1/orgs/:orgId/toolsets/:slug/versionsPublish a new version
GET/v1/orgs/:orgId/toolsets/:slug/versions/:versionGet version details
PUT/v1/orgs/:orgId/toolsets/:slug/published-versionSet the active published version

​
Run History Routes

MethodEndpointDescription
GET/v1/orgs/:orgId/runsList runs
GET/v1/orgs/:orgId/runs/:runIdGet run details

​
Other Organization Routes

MethodEndpointDescription
GET/v1/orgs/:orgId/api-keysList API keys
POST/v1/orgs/:orgId/api-keysCreate API key
GET/v1/orgs/:orgId/membersList members
GET/v1/orgs/:orgId/webhooksList webhooks
GET/v1/orgs/:orgId/creditsGet credit balance

​
Public Routes

Public routes allow external consumers to execute tools using an API key, without requiring organization membership context.
MethodEndpointDescription
POST/v1/public/:orgSlug/:toolsetSlug/run/:toolSlugExecute a tool
POST/v1/public/:orgSlug/:toolsetSlug/mcpMCP endpoint (JSON-RPC)

​
Explore Routes

Explore routes are unauthenticated and allow browsing public toolsets.
MethodEndpointDescription
GET/v1/explore/toolsetsList public toolsets
GET/v1/explore/tagsList 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

StatusMeaning
200Success
201Created
400Bad Request — invalid input or missing required fields
401Unauthorized — missing or invalid API key
403Forbidden — API key lacks permission for this action
404Not Found — resource does not exist
429Too 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.
  • SDK — Type-safe client library wrapping these endpoints
  • MCP Integration — Model Context Protocol endpoints
  • Webhooks — Receive event notifications for tool runs and more