Skip to content
Kindgi

Fetch a tool manifest (latest active version)

View as Markdown
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). An item more than one project serves (an environment order carries it to later environments) answers its newest active version that can run in a project the caller reads, and 404 when there is none. projectId narrows that to one project. An item with one project answers its latest active version.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
toolId
required
string

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

Query Parameters

Section titled “Query Parameters”
projectId
string format: uuid

The newest active version that can run in this project, a project the caller reads; 404 when there’s none, or when the caller doesn’t read the project. An item with one project answers its latest version for its own project and 404 for any other; one that names no project (under kindgi dev, a pack’s agents, flows and tools) answers it for any. With authorization off, the caller reads every project. An older runtime ignores it and answers the latest version.

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

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
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:
One of:
object
kind
required
string
Allowed value: tenant
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"
    }
  }
}

400

Section titled “400”

projectId is not a project id (a UUID).

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

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

See also