Publish an agent definition
const url = 'https://example.com/v1/agents';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"id":"example","version":"example","name":"example","description":"example","projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","instructions":{"prompt":"example","version":"example"},"parameters":[{"name":"example","description":"example","type":"string","required":true,"default":"example"}],"settings":[{"id":"example","version":"example"}],"modelSettings":{"id":"example","version":"example"},"capabilities":[{}],"tools":[{"id":"example","version":"example"}],"retrieval":[{"source":"facts","types":["example"],"roles":["user"],"scope":"same-conversation","limit":1,"mode":"keyword"}],"memory":{"instructionTypes":["example"],"remember":{"types":["example"],"scope":"same-user","keepDays":1}},"guardrails":["example"],"preferredProvider":"example","preferredModel":"example","conversationPolicy":{"historyLimit":1,"autoCloseAfterInactiveSeconds":1,"hitlAfterTurns":1},"budget":{"maxSteps":1,"maxCostUsd":1,"maxWallMs":1},"tags":["example"],"output":{"schema":{},"name":"example","maxRepairs":1},"toolErrors":{"maxRetries":1,"retryOn":["invalid-arguments"]}}'};
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 \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "id": "example", "version": "example", "name": "example", "description": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "instructions": { "prompt": "example", "version": "example" }, "parameters": [ { "name": "example", "description": "example", "type": "string", "required": true, "default": "example" } ], "settings": [ { "id": "example", "version": "example" } ], "modelSettings": { "id": "example", "version": "example" }, "capabilities": [ {} ], "tools": [ { "id": "example", "version": "example" } ], "retrieval": [ { "source": "facts", "types": [ "example" ], "roles": [ "user" ], "scope": "same-conversation", "limit": 1, "mode": "keyword" } ], "memory": { "instructionTypes": [ "example" ], "remember": { "types": [ "example" ], "scope": "same-user", "keepDays": 1 } }, "guardrails": [ "example" ], "preferredProvider": "example", "preferredModel": "example", "conversationPolicy": { "historyLimit": 1, "autoCloseAfterInactiveSeconds": 1, "hitlAfterTurns": 1 }, "budget": { "maxSteps": 1, "maxCostUsd": 1, "maxWallMs": 1 }, "tags": [ "example" ], "output": { "schema": {}, "name": "example", "maxRepairs": 1 }, "toolErrors": { "maxRetries": 1, "retryOn": [ "invalid-arguments" ] } }'Body is a full defineAgent spec. Server validates via @kindgi/agents.defineAgent before persisting.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”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”Full defineAgent spec. Validated server-side via @kindgi/agents.defineAgent — validation failures return 400 validation-failed with the issue list under details.issues.
object
Project this belongs to (its content scope). Required: missing, or not a project in the caller’s tenant → 400 bad-input.
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.
Soft hint at the model level (ModelInfo.name). Combined with preferredProvider to pin an exact tuple; alone to select a model across every provider that exposes it.
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.
Responses
Section titled “Responses”Agent published.
object
What the agent should know about this deployment before its first turn, e.g. semantic-unavailable (a retrieval intent searches by meaning and the deployment has no embeddings), remember-unavailable (the agent remembers and the deployment cannot store agent memories), recall-other-people (an intent recalls conversations in the run’s segment or project, whoever had them) or recall-unavailable (the deployment cannot recall earlier conversations).
object
Examplegenerated
{ "agentId": "example", "version": "example", "warnings": [ { "code": "example", "message": "example" } ]}Validation failed (see details.issues); or projectId isn’t a project id (a UUID). Or reference-out-of-scope: a tool, guardrail or data block it names isn’t registered in its project, its org or the tenant (details.issues, each with path, kind and id).
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" }}The body’s 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" }}agent-already-registered: that (id, version) is taken. Or agent-project-mismatch: the agent’s versions live in another project (an agent belongs to the project its first version was published into and never moves, though in a tenant with environment orders a version may be made in another project of that project’s order; the message doesn’t name the project). Or environment-takes-promotions: the project is a later environment of an environment order, which takes builds only by promotion from the one before it; publish in the order’s first environment instead (details.firstProjectId, when you can read that project; details.position, the project’s place from 0). Nothing is written. 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" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
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" }}rate-limit-exceeded with details.limit: "schema-compile-time", on a server with a compile budget (Kindgi Cloud): this tenant’s schemas spent details.budgetMs compiling in the last 60 seconds. Nothing was stored; Retry-After says when to send it again.
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" }}See also
GET /v1/agents: List agents- Agent and tool versions
- Kindgi 0.1.8
- Kindgi 0.1.9
- Error code
agent-already-registered - Error code
agent-project-mismatch - Error code
environment-takes-promotions - Error code
project-not-found - Error code
rate-limit-exceeded - Error code
reference-out-of-scope - Error code
registry-read-only - Error code
request-too-large - Every error code