Fetch a specific tool version

GET

/v1/tools/{toolId}/versions/{version}

curl --request GET \
  --url https://example.com/v1/tools/example/versions/example \
  --header 'Authorization: Bearer <token>'

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

Authorizations

• bearerAuth

Parameters

Path Parameters

toolId

required

string

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

version

required

string

Exact semver of the tool version.

Responses

200

Tool manifest at the requested version.

Media typeapplication/json

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

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

Present only on an unregistered version: a retired tool (every version unregistered) as GET /v1/tools?includeRetired=true lists it.

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

Example

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

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 at that (id, version) 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: List all versions of a tool
• 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
• Every error code