Skip to content
Kindgi

Fetch a tool manifest (latest active version)

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

Returns the latest active version of the tool. When all versions are unregistered (retired), the head row still exists but has no active version — the response is 410 tool-gone with the id, distinct from 404 tool-not-found (never registered).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
toolId
required
string

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

Responses

Section titled “Responses”

200

Section titled “200”

Tool manifest.

Media typeapplication/json
object
id
required

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

string
>= 1 characters
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:

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

object
kind
required
string
Allowed values: none unrestricted
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
kind
required
Allowed value: oci
imageRef
required
string
>= 1 characters
modulePath
required
string
>= 1 characters
artifactVersion
required
string
>= 1 characters
spec
One of:

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
kind
required
Allowed value: bearer
secretRef
required
object
envName
required
string
>= 1 characters
name
required
string
>= 1 characters
requestBody
One of:
object
kind
required
Allowed value: json-input
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
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"
    }
  }
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

410

Section titled “410”

Tool retired (all versions unregistered).

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}