> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
Authorization: Bearer jtb_xxxxxxxxxxxx
```

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Include the key in requests">
    Pass the key as a Bearer token in every API request.
  </Step>
</Steps>

## 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**:

```bash theme={null}
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):

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

### Execute via Public Endpoint

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "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](/en/pages/toolbox/developer/sdk) -- Type-safe client library wrapping these endpoints
* [MCP Integration](/en/pages/toolbox/developer/mcp) -- Model Context Protocol endpoints
* [Webhooks](/en/pages/toolbox/developer/webhooks) -- Receive event notifications for tool runs and more