Skip to content
Kindgi

List tools

View as Markdown
GET
/v1/tools
curl --request GET \
  --url 'https://example.com/v1/tools?limit=25&scopeKind=tenant&inherit=true&includeRetired=false' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated list of registered tool manifests. Optional ?name= filters by prefix on tool id. A retired tool (every version unregistered) is listed only with ?includeRetired=true, as its highest version with unregisteredAt, so it can be found and a version reinstated.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “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.

name
string

Prefix match on the resource id.

scopeKind

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string
Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

scopeId
string
>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

inherit
boolean
default: true

Default true. false = literal-at-this-scope only (admin/audit view). Load-bearing for policy/config-scoped resources (mcp-endpoints); documented no-op for content-scoped resources (agents/flows/tools/…).

includeRetired
boolean

When true, retired items (every version unregistered) are listed too, each as its highest version with that version’s unregisteredAt. Default: false (items with an active version only).

Responses

Section titled “Responses”

200

Section titled “200”

Page of tools.

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. It also decides what runs together: calls to read-only tools that a model step asks for one after another run at the same time, up to 8 at once, unless the agent sets parallelToolCalls: false; a call to a mutating tool runs on its own, and so does a call to a read-only tool that pauses or declares connections, since it may wait.

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. A webhook trigger, a schedule or a mail trigger whose toolsAllowedUnattended names the tool (a project admin’s to set) lifts that, in its own runs only. A tool that uses a person’s connection, reads included, counts as declaring it. In a run a mail started, so does a tool that isn’t mutating: false, and one that uses the run’s own mailbox. Absent means false.

boolean
pauses

true when the tool may make its run wait for another system’s answer: each call gets a wait token, hands its link to that system, and answers pause; the system’s answer, valid against output, becomes the call’s result. The run waits at most 24 days (24 hours by default) and fails the call when the time passes. Only a pack tool with a handler can pause: not one with a declarative spec, nor an MCP tool. Absent means false.

boolean
resultIsOutsideData

true when the tool’s results are text from outside that nobody checked, such as a mail someone sent: an agent reads each result as data, not instructions, in that turn and in every later turn’s history. 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 / connections). 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>
connections

Accounts at other apps the tool acts with, by the tool’s own name for each (mail). The runtime resolves them per call into the context’s connections.

object
key
additional properties
object
app
required

The app’s entry id: google, github.

string
/^[a-z][a-z0-9-]{1,31}$/
permissions
required

The entry’s permission keys the call needs: gmail.send.

Array<string>
>= 1 items unique items
as
required

Whose connection: person, the run’s person (the one it acts for, who started it or owns its trigger); company, the tenant’s.

Allowed values: person company
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
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"
      },
      "needsSpec": {
        "connections": {
          "additionalProperty": {
            "as": "person"
          }
        }
      },
      "codeArtifactRef": {
        "kind": "oci"
      },
      "spec": {
        "kind": "http",
        "method": "GET",
        "authorization": {
          "kind": "bearer"
        },
        "requestBody": {
          "kind": "json-input"
        }
      },
      "secretScopes": {
        "additionalProperty": {
          "kind": "tenant"
        }
      }
    }
  ]
}

400

Section titled “400”

Malformed query parameter.

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

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

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