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":"example","parameters":[{"name":"example","description":"example","type":"string","required":true,"default":"example"}],"capabilities":[{}],"tools":[{"id":"example","version":"example"}],"retrieval":[{"types":["example"],"scope":"same-conversation","limit":1,"mode":"keyword"}],"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": "example", "parameters": [ { "name": "example", "description": "example", "type": "string", "required": true, "default": "example" } ], "capabilities": [ {} ], "tools": [ { "id": "example", "version": "example" } ], "retrieval": [ { "types": [ "example" ], "scope": "same-conversation", "limit": 1, "mode": "keyword" } ], "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. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).
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.
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
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
Examplegenerated
{ "agentId": "example", "version": "example"}Validation failed (see details.issues).
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 already registered at that (id, version).
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" }}