Skip to content
Kindgi

List versions of an agent

GET
/v1/agents/{agentId}/versions
curl --request GET \
  --url 'https://example.com/v1/agents/example/versions?limit=25' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated. Sort order is binding-defined (built-in registry: semver asc).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
agentId
required
string

AgentId — dotted namespace (acme.drafting).

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.

Responses

Section titled “Responses”

200

Section titled “200”

Page of agent versions.

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

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