List all versions of a tool

GET

/v1/tools/{toolId}/versions

curl --request GET \
  --url 'https://example.com/v1/tools/example/versions?limit=25&includeTombstoned=false' \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

Cursor-paginated list of tool versions. Defaults to active versions only. Pass ?includeTombstoned=true to include soft-tombstoned rows too; tombstoned rows carry unregisteredAt (ISO string), active rows do not.

Authorizations

• bearerAuth

Parameters

Path Parameters

toolId

required

string

ToolId — dotted namespace (acme.lookup-order).

Query Parameters

limit

integer

default: 25 >= 1 <= 100

1..100. Default 25.

cursor

string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

includeTombstoned

boolean

When true, the response includes soft-tombstoned versions in addition to active ones. Tombstoned rows carry an unregisteredAt ISO timestamp; active rows omit the field. Default: false (active-only).

Responses

200

Page of tool versions.

Media typeapplication/json

object

data

required

Array<object>

object

id

required

ToolId — dotted namespace (e.g. acme.verify-citation).

string

>= 1 characters

projectId

The tool’s project: every version of a tool is in the one project. Absent when the runtime doesn’t record it: a pack kindgi dev serves from disk, or a runtime before Kindgi 0.1.6.

string format: uuid

description

required

string

>= 1 characters

version

string

/^\d+\.\d+\.\d+$/

input

required

JSON Schema (Draft 2020-12) for the tool input.

object

key

additional properties

any

output

required

JSON Schema (Draft 2020-12) for the tool output.

object

key

additional properties

any

needs

Array<object>

object

name

required

string

>= 1 characters

optional

boolean

effects

Array<object>

object

kind

required

string

Allowed values: reads writes deletes network spawns-run emits-event external-side-effect sensitive-data-egress

resource

string

notes

string

transport

string

Allowed values: auto native mcp

mcpEndpoint

string

metadata

object

key

additional properties

any

mutating

Semantic marker: true when this tool causes observable side effects (writes state, calls external APIs with mutations, sends messages). Read-only tools set false. Absent defaults to true. Consumed by the HITL default classifier — a read-only tool passes straight through, a mutating tool asks on first use.

boolean

needsApprovalWhenUnattended

true: in a run no person started (one whose startedBy isn’t person), every call of this tool waits for a person’s yes, whatever the agent’s approval rules say, and a flow’s tool step that calls it is refused. Absent means false.

boolean

sandbox

Isolation posture the runtime enforces around the handler. Optional additive field.

string

Allowed values: none context-isolated strict

limits

Sandbox-enforced resource caps at dispatch. Optional additive field.

object

memMB

required

integer

>= 1

cpuMs

required

integer

>= 1

network

One of:

object

Network egress policy. Optional additive field. Discriminated on kind.

object

kind

required

string

Allowed values: none unrestricted

object

Network egress policy. Optional additive field. Discriminated on kind.

object

kind

required

string

Allowed value: allowlist

hosts

required

Array<string>

needsSpec

Typed discriminated needs (env / secrets / config / capabilities / bindings). Optional additive field.

object

env

object

key

additional properties

object

secrets

object

key

additional properties

object

config

object

key

additional properties

object

capabilities

Array<string>

bindings

Array<string>

codeArtifactRef

One of:

object

object

kind

required

Allowed value: oci

imageRef

required

string

>= 1 characters

modulePath

required

string

>= 1 characters

artifactVersion

required

string

>= 1 characters

object

object

kind

required

Allowed value: filesystem

modulePath

required

string

>= 1 characters

spec

One of:

object

Declarative HTTP-invocation spec. Attached to ToolManifest.spec under the discriminant kind: 'http'. The runtime Tool.handler is synthesized by the ‘http’ spec synthesizer to perform URL-template substitution, secret-ref resolution via ToolContext.resolveSecret, and the outbound fetch. All fields serialize cleanly to JSON.

object

kind

required

Allowed value: http

method

required

string

Allowed values: GET POST PUT PATCH DELETE

urlTemplate

required

URL template with {param} placeholders substituted from the tool’s input at invoke time.

string

>= 1 characters

headers

Array<object>

object

name

required

string

>= 1 characters

value

required

string

authorization

One of:

object

object

kind

required

Allowed value: bearer

secretRef

required

object

envName

required

string

>= 1 characters

name

required

string

>= 1 characters

object

object

kind

required

Allowed value: header

headerName

required

string

>= 1 characters

secretRef

required

object

envName

required

string

>= 1 characters

name

required

string

>= 1 characters

requestBody

One of:

object

object

kind

required

Allowed value: json-input

object

object

kind

required

Allowed value: input-passthrough

object

object

kind

required

Allowed value: text

template

required

string

timeoutMs

Wall-clock timeout in ms. Default 30000.

integer

>= 1

parseJson

When true (default), the response body is parsed as JSON before returning to the invoker.

boolean

successStatus

object

min

required

integer

>= 100 <= 599

max

required

integer

>= 100 <= 599

unregisteredAt

ISO 8601 timestamp — present iff this version has been soft-tombstoned via POST /versions/:v/unregister. Absent on active versions.

string format: date-time

secretScopes

Where each secret it names is read, by name: recorded by the server when it was registered, never sent by a caller. null: none usable (the registrant administers no scope the secret could be read at), until an admin records it again: a tool by publishing a new version, an MCP endpoint by unregistering it and registering it again. Absent on items registered before it was recorded, or on a runtime without a secrets store.

object

key

additional properties

One of:

object

One of:

object

object

kind

required

string

Allowed value: tenant

object

object

kind

required

string

Allowed value: org

orgId

required

string format: uuid

object

object

kind

required

string

Allowed value: project

projectId

required

string format: uuid

null

null

nextCursor

Opaque cursor for the next page. Absent when hasMore: false.

string

hasMore

required

boolean

Example

{
  "data": [
    {
      "effects": [
        {
          "kind": "reads"
        }
      ],
      "transport": "auto",
      "sandbox": "none",
      "network": {
        "kind": "none"
      },
      "codeArtifactRef": {
        "kind": "oci"
      },
      "spec": {
        "kind": "http",
        "method": "GET",
        "authorization": {
          "kind": "bearer"
        },
        "requestBody": {
          "kind": "json-input"
        }
      },
      "secretScopes": {
        "additionalProperty": {
          "kind": "tenant"
        }
      }
    }
  ]
}

400

bad-input: a cursor this list didn’t issue.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No tool with that id under this tenant.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also

• GET /v1/tools/{toolId}: Fetch a tool manifest (latest active version)
• GET /v1/tools/{toolId}/versions/{version}: Fetch a specific tool version
• POST /v1/tools/{toolId}/versions/{version}/unregister: Unregister a specific tool version
• POST /v1/tools/{toolId}/versions/{version}/reinstate: Reinstate a specific tombstoned tool version
• Error code bad-input
• Every error code