Fetch the latest version of an agent
const url = 'https://example.com/v1/agents/example';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 \ --header 'Authorization: Bearer <token>'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”AgentId — dotted namespace (acme.drafting).
Query Parameters
Section titled “Query Parameters”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”Agent.
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.
Example
{ "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" }}projectId is not a project id (a UUID).
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 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
GET /v1/agents/{agentId}/versions: List versions of an agentPOST /v1/agents/{agentId}/versions: Derive an agent version with data-block pins swappedGET /v1/agents/{agentId}/versions/{version}: Fetch a specific agent versionPOST /v1/agents/{agentId}/versions/{version}/unregister: Unregister a specific agent version- Every error code