Derive an agent version with data-block pins swapped
const url = 'https://example.com/v1/agents/example/versions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"from":"example","pins":{"prompts":{"additionalProperty":"example"},"settings":{"additionalProperty":"example"}},"label":"example","projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/agents/example/versions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "from": "example", "pins": { "prompts": { "additionalProperty": "example" }, "settings": { "additionalProperty": "example" } }, "label": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'An expert’s edit, without a code change: a new agent version that is from’s bag with some prompt or settings pins swapped (derivedFrom: { version, reason: 'edited', label, by }), numbered the next free patch after the agent’s highest version. Only blocks from already references swap, to a published, active version of the right kind (model settings for the model-settings block); tool pins come from code. Needs publish on the agent.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”AgentId — dotted namespace (acme.drafting).
Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).
Request Bodyrequired
Section titled “Request Bodyrequired”Derive a new agent version from a pinned one with some data-block pins swapped: an expert’s edit reaching an agent with no code change.
object
The version to derive from (it must be pinned).
The data-block pins to swap, by block id → exact version. Only blocks the version already references; tool pins come from code.
object
Prompt block id → exact version.
object
Settings block id → exact version.
object
A short label for the new version.
The agent’s project, when the runtime doesn’t record it on the version.
Examplegenerated
{ "from": "example", "pins": { "prompts": { "additionalProperty": "example" }, "settings": { "additionalProperty": "example" } }, "label": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}Responses
Section titled “Responses”An active version already holds this definition and these pins (the same swap derived before, or a deploy that registered it): that version, unchanged.
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" }}The derived agent version.
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" }}validation-failed: from has no pins, a swap names a block it doesn’t reference, or a version that isn’t published, active or the right kind (see details.issues); or projectId isn’t 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" }}agent-not-found: no agent at from; or projectId names no project of this tenant (project-not-found).
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" }}Idempotency-Key was reused with a different body, or resource-state conflict. Or agent-project-mismatch: the agent belongs to another project than the body’s projectId (agents never move; the message doesn’t name the project). Or registry-read-only: this registry takes no writes (under kindgi dev, the pack’s files are the source); the message says what to do instead.
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" }}Server error (unmapped domain code or framework crash).
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" }}