List versions of an agent
const url = 'https://example.com/v1/agents/example/versions?limit=25&includeTombstoned=false';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/v1/agents/example/versions?limit=25&includeTombstoned=false' \ --header 'Authorization: Bearer <token>'Cursor-paginated. Sort order is binding-defined (built-in registry: semver asc). Defaults to active versions only. Pass ?includeTombstoned=true to include unregistered versions too, each with unregisteredAt: a retired agent (every version unregistered) answers too, with its versions to reinstate.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”AgentId — dotted namespace (acme.drafting).
Query Parameters
Section titled “Query Parameters”1..100. Default 25.
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.
When true, the response includes soft-tombstoned versions in addition to active ones. Tombstoned rows carry an unregisteredAt ISO timestamp; active rows omit the field. Default: false (active-only).
Responses
Section titled “Responses”Page of agent versions.
object
object
AgentId — dotted namespace (e.g. acme.drafting).
Semver.
The agent’s project: every version of an agent 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.
object
Default value used when the caller omits this parameter.
Settings blocks the agent reads, by range: tools read them as ToolContext.settings['<id>'], templates as settings["<id>"]. Pinned at publish (pins.settings).
A settings block an agent reads, by id and semver range.
object
The settings block id.
A semver range (^1.0.0, 1.2.0).
A model-settings block by range: its temperature and maxOutputTokens go into the turn’s model calls. Pinned at publish.
object
The settings block id.
A semver range (^1.0.0, 1.2.0).
Capability declaration — see @kindgi/capabilities. Additional properties are permitted so new capability kinds do not require a wire change.
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
object
What it reads: facts (the default), or messages of this agent’s earlier conversations, quoted in the turn’s <memory> block as earlier conversation, never as turns.
The fact types it retrieves: required for facts; not used for conversations.
For conversations: whose messages it recalls. Default ['user'], the people’s own words. Adding agent recalls the agent’s earlier answers too, which can carry its mistakes: they are quoted as unverified earlier answers, and publishing warns recall-agent-answers.
What the intent selects within what the run may see. Facts: this conversation’s; the run’s end user’s only (same-user: none when the run names no participantId); the run’s project’s (none without a project); or every fact of the type it may see (tenant). Conversations: this end user’s other conversations with the agent (same-user: none when the run names no participantId); this conversation’s messages older than the history window (same-conversation); conversations in the run’s segment path (same-segment) or its project (same-project), whoever had them: those two quote other people’s conversations, so publishing warns and their messages are marked as another person’s. same-segment is for conversations only, tenant for facts only.
With the user’s message as the query: full-text, by meaning (fails the turn with semantic-unavailable on a runtime without embeddings), or both fused by rank (without embeddings, the keyword half). Absent: the newest facts.
How the agent uses what it retrieves.
object
Fact types that are instructions for this agent: a retrieved, verified fact of one of these types goes into the system message under ‘Policies (verified)’. Default: none.
Lets the agent remember: its turns offer the built-in tool kindgi_remember (built-in tools are kindgi_<verb>; an agent cannot list one in tools, and a published tool cannot use the prefix). The model picks the type, the text (up to 2,000 characters), an optional slot key and when it stops being true; the scope comes from here and the run. Every remembered fact is unverified, attributed to the agent version and the call that wrote it, and expires after keepDays unless a person verifies it. A person approves it before any read sees it when the scope is wider than one person (same-project, tenant) or the text reads like an instruction.
object
The fact types it may write.
Where its facts go: the conversation’s end user (else the user the run acts for), the conversation, the run’s project, or the tenant. Each but tenant includes the run’s project.
Days an unverified fact is kept. Default 30.
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.
Soft hint at the model level (ModelInfo.name, e.g. claude-sonnet-5-5). 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.
object
object
object
JSON Schema (draft 2020-12) the final answer must match.
object
A name for the output, shown to the model and in errors. Default output.
How many times the model is asked to repair an invalid answer. Default 1.
object
Failed calls sent back to the model per turn. Default 1.
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.
The exact block versions an agent version runs: its lockfile. Set by the runtime when the version is published, never in the publish body: each tool range resolves once to the version every run of that agent version uses, so a new tool version reaches the agent only through a new agent version. Absent on a version published before pins existed (its ranges resolve per run).
object
Tool id → exact version.
object
Prompt block id → exact version.
object
Settings block id → exact version.
object
Set by the runtime on an agent or flow version a deploy registered in place of the definition’s version, which was registered already with other pins or content (versions never change). Never in the publish body.
object
The version the definition names.
pins-changed: a block it uses has a new version; unpinned: the definition’s version was published before pins existed; version-taken: the definition’s version holds another definition; edited: derived from version with some data-block pins swapped (POST /v1/agents/{agentId}/versions).
For edited: a short label for the version.
For edited: who derived it (user:<id>).
For edited: the improvement proposal it was derived for. Such a version serves no scope until a promotion makes it live.
Present only on an unregistered version (GET …/versions/{version} reads those too). Unregister stops a version being chosen, not the pins that hold it: a new run naming it is refused, while a resumed run and a published version that pins it still run it.
Set by the runtime with pins: sha256:<hex> of the pins’ canonical JSON (sorted keys, no whitespace). Two agent versions with the same digest run the same blocks.
Opaque cursor for the next page. Absent when hasMore: false.
Example
{ "data": [ { "parameters": [ { "type": "string" } ], "retrieval": [ { "source": "facts", "roles": [ "user" ], "scope": "same-conversation", "mode": "keyword" } ], "memory": { "remember": { "scope": "same-user" } }, "toolErrors": { "retryOn": [ "invalid-arguments" ] }, "derivedFrom": { "reason": "pins-changed" } } ]}bad-input: a cursor this list didn’t issue.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}No agent was ever registered with that id under this tenant.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}See also
POST /v1/agents/{agentId}/versions: Derive an agent version with data-block pins swappedGET /v1/agents/{agentId}: Fetch the latest version of an agentGET /v1/agents/{agentId}/versions/{version}: Fetch a specific agent versionPOST /v1/agents/{agentId}/versions/{version}/unregister: Unregister a specific agent version- Error code
bad-input - Every error code