Versioning & Publishing

Overview

Jinba Toolbox uses a semver-based versioning system with immutable snapshots. Each toolset maintains a draft (the editable working copy) and a list of published versions. When you publish, a complete snapshot of the toolset — including all tool code, schemas, and sandbox configuration — is frozen as an immutable version that can never be modified. This design ensures reproducibility: running version 1.0.0 always executes the same code, regardless of when or where it is called.

Concepts

Draft vs. Versions

ToolSet
├── Draft (editable working copy)
└── Versions (immutable releases)
    ├── v1.2.0 [published]
    ├── v1.1.0
    └── v1.0.0

State	Description
Draft	The editable working copy. Modified through the web UI or API. Can only be executed via the `test` endpoint (console session only).
Version	An immutable release. Once published, it cannot be changed. Used by the `run` and MCP endpoints.
Published	The currently active version served by the API. Each ToolSet environment (`default` plus any you add) has its own active version; `latestVersion` is shared.

Immutable Snapshots

Each version captures a complete snapshot of the toolset at the time of publishing:

All tool code and entrypoints
Input and output schemas
Tool names and descriptions
Sandbox configuration (provider, language, packages, resources)

This means even if you later update the draft, existing versions remain unchanged.

Publishing Workflow

Edit the draft

Make changes to tools in the draft through the web console or the API, and verify the behavior with the Test panel in the console. The underlying endpoint is POST /v1/orgs/{orgId}/toolsets/slack-tools/tools/post-message/test with { "input": { ... } }; it requires a signed-in user session, so it cannot be called with an API key.

Publish a new version

When the draft is ready, publish it with a semver version number and optional release notes (publishing also requires a signed-in session; use the console’s New Version dialog):

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

An API key (jtb_...) is rejected here with 400 (“User context required”), and the SDK’s publishVersion() sends the API key, so it fails the same way.

Set the published version

A newly published version automatically becomes the active version of the environment given by environmentSlug (default default), unless you pass "setAsPublished": false. To activate a different version later — or to activate a version in another environment — set it explicitly:

curl -X PUT https://toolbox-api.jinba.io/v1/orgs/{orgId}/toolsets/slack-tools/published-version \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "version": "1.3.0", "environmentSlug": "default" }'

The change takes effect immediately. In the console, use Set Active on the Versions tab.

Continue developing

The draft remains intact after publishing, so you can keep iterating on the next version without affecting the live published version.

Version Resolution

When a tool is executed via the run endpoint, Jinba Toolbox resolves which version to use:

If the request body includes a version field, that exact version is used.
Otherwise, the active version of the ToolSet environment is used. The environment comes from the request’s environmentSlug field, or else from the environment bound to the API key (default for session requests).
If that environment has no active version, the organization run and MCP endpoints fall back to latestVersion; the public endpoints do not and respond with “No published version available”.

# Uses the published version
curl -X POST .../tools/post-message/run \
  -d '{ "input": { "channel": "#general", "text": "Hello" } }'

# Uses a specific version
curl -X POST .../tools/post-message/run \
  -d '{ "input": { "channel": "#general", "text": "Hello" }, "version": "1.2.0" }'

Rollback

Rolling back is simply a matter of changing the active version of an environment to a previous one:

# Switch the default environment back to v1.2.0
curl -X PUT https://toolbox-api.jinba.io/v1/orgs/{orgId}/toolsets/slack-tools/published-version \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "version": "1.2.0", "environmentSlug": "default" }'

Because versions are immutable, no data is lost during a rollback. The newer version remains available and can be re-activated at any time.

Version API

Method	Endpoint	Description
GET	`/v1/orgs/:orgId/toolsets/:slug/versions`	List all versions (with `runCount` for the last 30 days, the active version per environment and `hasUnpublishedChanges`)
POST	`/v1/orgs/:orgId/toolsets/:slug/versions`	Publish a new version (`version`, `releaseNotes?`, `setAsPublished` = `true`, `environmentSlug` = `default`); session only
GET	`/v1/orgs/:orgId/toolsets/:slug/versions/:version`	Get version details (`isPublished`, `isLatest`)
GET	`/v1/orgs/:orgId/toolsets/:slug/versions/:version/export`	Download the version as a ZIP archive
PUT	`/v1/orgs/:orgId/toolsets/:slug/published-version`	Set the active version of an environment (`version`, `environmentSlug` = `default`)

Version Data Model

Each published version stores a full snapshot:

interface ToolSetVersion {
  id: string;
  toolSetId: string;
  version: string;              // Semver string (e.g., "1.3.0")
  sandbox: SandboxConfig;       // Frozen sandbox configuration
  tools: ToolSnapshot[];        // Frozen tool definitions and code
  releaseNotes?: string | null;
  publishedBy: string;          // User ID of the publisher
  publishedAt: string;          // ISO 8601 timestamp
}

interface ToolSnapshot {
  id: string;
  slug: string;
  name: LocalizedText;
  description: LocalizedText;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
  code: string;
  entrypoint?: string;
}

Usage Tracking

Jinba Toolbox counts the runs of each version over the last 30 days. The console shows this count next to every version on the Versions tab, and the version list endpoint returns it as runCount. For a complete history, retrieve runs through the API:

const runs = await client.listRuns();
// Filter by `toolSetVersion` in your application logic

Usage data helps you determine when it is safe to deprecate older versions.

Best Practices

Follow semantic versioning — use major bumps for breaking schema changes, minor bumps for new tools or features, and patch bumps for fixes.
Write release notes — they help your team understand what changed between versions.
Test before publishing — use the test endpoint to validate the draft before creating an immutable version.
Do not skip the publish step for MCP — MCP endpoints serve the published version, not the draft.
Monitor per-version usage — before deprecating a version, verify that no consumers still depend on it.

REST API — Full endpoint reference including version routes
SDK — Programmatic version management
Security & Access Control — Who can publish versions

​Overview

​Concepts

​Draft vs. Versions

​Immutable Snapshots

​Publishing Workflow

​Version Resolution

​Rollback

​Version API

​Version Data Model

​Usage Tracking

​Best Practices

​Related