Skip to content
Kindgi

List agents

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

Cursor-paginated list of the latest version per agent id. Optional ?name= filters by prefix on agent id.

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

Opaque cursor from a prior response. Absent → first page.

name
string

Prefix match on agent 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/…).

Responses

Section titled “Responses”

200

Section titled “200”

Page of agents.

Media typeapplication/json
object
data
required
Array<object>
object
id
required

AgentId — dotted namespace (e.g. acme.drafting).

string
version
required

Semver.

string
name
required
string
description
string
instructions
required
string
parameters
Array<object>
object
name
required
string
description
string
type
required
string
Allowed values: string number boolean date
required
boolean
default

Default value used when the caller omits this parameter.

capabilities
required
Array<object>

Capability declaration — see @kindgi/capabilities. Additional properties are permitted so new capability kinds do not require a wire change.

object
key
additional properties
any
tools
required
Array<object>

Typed tool reference. version is a semver range (npm-style: 1.2.3 exact pin, ^1.2.3 compatible-updates, ~1.2.3 patch-updates-only, >=1.0.0 <2.0.0 explicit range). Dispatch resolves the range to a concrete active version via semver.maxSatisfying at run start. No implicit “latest” — every tool ref names both id and range.

object
id
required
string
>= 1 characters
version
required
string
>= 1 characters
retrieval
required
Array<object>
object
types
required
Array<string>
>= 1 items
scope
required
string
Allowed values: same-conversation same-project tenant
limit
integer
>= 1
mode
string
Allowed values: keyword semantic both
guardrails
required
Array<string>
preferredProvider

Soft hint — the router prefers this provider by id (e.g. anthropic) when at least one of its models satisfies capabilities.needs + tenant policy. Combine with preferredModel to pin the exact (provider, model) tuple. Falls back to capability-based ranking when the pinned provider is unregistered or filtered out.

string
>= 1 characters
preferredModel

Soft hint at the model level (ModelInfo.name, e.g. claude-sonnet-4-6). Combined with preferredProvider: both set → promote the exact tuple; only preferredModel → promote any provider exposing that model; only preferredProvider → promote every model of that provider.

string
>= 1 characters
conversationPolicy
object
historyLimit
integer
>= 1
autoCloseAfterInactiveSeconds
integer
>= 1
hitlAfterTurns
integer
>= 1
budget
object
maxSteps
integer
>= 1
maxCostUsd
number
maxWallMs
integer
>= 1
tags
Array<string>
output
object
schema
required

JSON Schema (draft 2020-12) the final answer must match.

object
name

A name for the output, shown to the model and in errors. Default output.

string
>= 1 characters
maxRepairs

How many times the model is asked to repair an invalid answer. Default 1.

integer
toolErrors
object
maxRetries

Failed calls sent back to the model per turn. Default 1.

integer
<= 10
retryOn

Which failures are sent back: arguments that don’t fit the input schema (invalid-arguments), a tool the agent doesn’t have (unknown-tool), a tool that ran and failed (tool-error). Default invalid-arguments, unknown-tool.

Array<string>
unique items
Allowed values: invalid-arguments unknown-tool tool-error
nextCursor

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

string
hasMore
required
boolean
Example
{
  "data": [
    {
      "parameters": [
        {
          "type": "string"
        }
      ],
      "retrieval": [
        {
          "scope": "same-conversation",
          "mode": "keyword"
        }
      ],
      "toolErrors": {
        "retryOn": [
          "invalid-arguments"
        ]
      }
    }
  ]
}

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