REST API - jinba

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.io/v1

Authentication

All API requests (except explore routes) require authentication via a Bearer token. API keys are scoped to an organization, act with Member-level permissions, and follow the jtb_ prefix convention. The web console authenticates with a JinbaAuth session token instead. Include the key in the Authorization header:

Authorization: Bearer jtb_xxxxxxxxxxxx

A few endpoints need a signed-in user rather than an API key and return 401 when called with a key: GET /v1/orgs, GET /v1/orgs/:orgId, GET /v1/orgs/:orgId/members, the .../test endpoint, and creating, revealing or deleting API keys. Publishing a version with an API key fails with 400 (“User context required”).

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.

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.

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. :orgId accepts the organization ID (or its slug).

Method	Endpoint	Description
GET	`/v1/orgs`	List the signed-in user’s organizations (session only)
GET	`/v1/orgs/:orgId`	Get organization details and your role (session only)

Organizations are created, updated and deleted in JinbaAuth; POST, PATCH and DELETE on these paths return 403 (POST returns 401 when called with an API key).

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 (`slug`, `name`, `description`, `code`)
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

inputSchema and outputSchema are not request fields: whenever code is created or updated, the API extracts both schemas from the code’s input / output definitions and rejects the request (400) if they cannot be extracted.

Execution Routes

Method	Endpoint	Description
POST	`/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/run`	Execute a published tool (`input`, optional `version`, optional `environmentSlug`)
POST	`/v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/test`	Test a tool with draft code (`input`, optional `code` override, optional `environmentSlug`; session only, no credits consumed)

Version Routes

Method	Endpoint	Description
GET	`/v1/orgs/:orgId/toolsets/:slug/versions`	List versions with their 30-day run counts (`?environment=` selects the environment whose active version is reported)
POST	`/v1/orgs/:orgId/toolsets/:slug/versions`	Publish a new version (`version`, optional `releaseNotes`, `setAsPublished` default `true`, `environmentSlug` default `default`; session only)
GET	`/v1/orgs/:orgId/toolsets/:slug/versions/:version`	Get version details
GET	`/v1/orgs/:orgId/toolsets/:slug/versions/:version/export`	Download a published version as ZIP
PUT	`/v1/orgs/:orgId/toolsets/:slug/published-version`	Set the active version (`version`, `environmentSlug` default `default`)

Run History Routes

Method	Endpoint	Description
GET	`/v1/orgs/:orgId/runs`	List runs (`?role=caller\|provider`, `?limit=1-100`, `?offset=`)
GET	`/v1/orgs/:orgId/runs/:runId`	Get run details (full details for the caller organization, limited for the provider)

Other Organization Routes

Method	Endpoint	Description
GET	`/v1/orgs/:orgId/api-keys`	List API keys
POST	`/v1/orgs/:orgId/api-keys`	Create API key (`name`, `environmentSlug` default `default`; session only)
GET	`/v1/orgs/:orgId/api-keys/:keyId/reveal`	Reveal the full key (session only)
DELETE	`/v1/orgs/:orgId/api-keys/:keyId`	Delete API key (session only)
GET	`/v1/orgs/:orgId/members`	List members (session only)
GET	`/v1/orgs/:orgId/webhooks`	List webhooks (see Webhooks)
GET	`/v1/orgs/:orgId/credits`	Get credit balance
GET	`/v1/orgs/:orgId/credits/transactions`	List credit transactions
POST	`/v1/orgs/:orgId/toolsets/:slug/packages`	Add or update a package (`name`, optional `version`)
GET / POST / PATCH / DELETE	`/v1/orgs/:orgId/toolsets/:slug/env`	Manage environment variables (`?environment=` / `environmentSlug`)
GET / POST / PATCH / DELETE	`/v1/orgs/:orgId/toolsets/:slug/environments`	Manage environment profiles
GET	`/v1/orgs/:orgId/toolsets/:slug/export`	Download the draft ToolSet as ZIP
POST	`/v1/orgs/:orgId/toolsets/:slug/import`	Import tools from a ZIP (multipart)

Public Routes

Public routes allow external consumers to execute tools using an API key, without requiring organization membership context. :orgId must be the provider organization’s canonical ID (slugs are not accepted). Any valid API key can call a public ToolSet; a private ToolSet is only accessible with its own organization’s key. Credits are charged to the caller’s organization.

Method	Endpoint	Description
POST	`/v1/public/:orgId/:toolsetSlug/run/:toolSlug`	Execute a tool (`input`); responds `200` on success, `500` when the tool execution fails
POST	`/v1/public/:orgId/:toolsetSlug/mcp`	MCP endpoint (JSON-RPC); requires MCP to be enabled on the ToolSet

Explore Routes

Explore routes are unauthenticated and allow browsing public toolsets.

Method	Endpoint	Description
GET	`/v1/explore/toolsets`	List public toolsets that have a published version (`?q=`, `?tag=`, `?limit=` up to 100, `?offset=`)
GET	`/v1/explore/toolsets/:orgId/:toolsetSlug`	Get a public toolset with its tools (schemas only, no code) and versions
GET	`/v1/explore/tags`	List popular tags

Request & Response Examples

Execute a Tool

Request:

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

Response (always 200; check success):

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

When the tool fails, success is false and error ({ name, message, traceback? }) is set instead of output.

Execute via Public Endpoint

The public response has the same shape but omits 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!"
    }
  }'

Create a 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 is private or public; resources.timeout is in milliseconds (max 3600000, default 15 minutes when omitted).

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

The new version becomes the active version of the default environment unless you pass "setAsPublished": false or another environmentSlug. Publishing requires a signed-in session.

Error Handling

The API uses RFC 9457 Problem Details format for errors:

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

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
402	Payment Required — the caller organization has insufficient credits
403	Forbidden — API key lacks permission for this action
404	Not Found — resource does not exist
409	Conflict — e.g. the version number already exists

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.
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

​Overview

​Authentication

​Endpoint Reference

​Organization Routes

​ToolSet Routes

​Tool Routes

​Execution Routes

​Version Routes

​Run History Routes

​Other Organization Routes

​Public Routes

​Explore Routes

​Request & Response Examples

​Execute a Tool

​Execute via Public Endpoint

​Create a ToolSet

​Publish a Version

​Error Handling

​Common Status Codes

​Best Practices

​Related

Overview

Authentication

Endpoint Reference

Organization Routes

ToolSet Routes

Tool Routes

Execution Routes

Version Routes

Run History Routes

Other Organization Routes

Public Routes

Explore Routes

Request & Response Examples

Execute a Tool

Execute via Public Endpoint

Create a ToolSet

Publish a Version

Error Handling

Common Status Codes

Best Practices

Related