Start an Improve run
const url = 'https://example.com/v1/improve-runs';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"agentId":"example","projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","tiers":["settings"],"model":{"providerId":"example","model":"example"},"candidates":1,"groupWeights":"as-recorded","objective":"passRate","budget":{"maxCostUsd":1,"maxCandidates":1}}'};
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/improve-runs \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "agentId": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "tiers": [ "settings" ], "model": { "providerId": "example", "model": "example" }, "candidates": 1, "groupWeights": "as-recorded", "objective": "passRate", "budget": { "maxCostUsd": 1, "maxCandidates": 1 } }'Starts an Improve run for an agent in a project. From the version the project runs (pinned there, else its Latest), it looks for better wording (the prompt tier) or settings values (the settings tier) on the project’s test set, learning from the project’s open corrections sorted to improve, within the budget. Its best change is proven on every case of the test set, at the reference’s repetitions: when it passes more cases than that version and fails none that passed, it becomes a suggested change for a reviewer. It answers at once with the Improve run, running. Under kindgi dev, the run counts in its project (its corrections, its test set and its cost), and its suggested change is for the whole workspace (the tenant scope), which the pack’s files serve: pinning it writes its block into the pack’s files. The readiness check (POST /v1/improve-runs/check) runs first: when something the Improve run needs is missing, it’s refused with 409 improve-not-ready, listing every missing item at once (details.items, each with its fix); while the agent has a running Improve run in the project, with 409 improve-run-running (details.improveRunId). An Improve run going when its project is suspended ends cancelled, with the reason in cancelReason. Needs publish on the agent; for an agent more than one project serves, write where its versions are made. Without Improve runs in this runtime, 501 improve-unsupported.
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 workspace 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). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).
Request Bodyrequired
Section titled “Request Bodyrequired”Start an Improve run for an agent in a project, or check one first. It starts from the version the project runs, learns from the project’s corrections, and searches and proves on the project’s test set. A field not listed here is refused (400 bad-input, naming it).
object
The project the Improve run works in.
What it tries: prompt (a model drafts new wording for the prompt block; a template that reads or names anything the agent doesn’t have is refused, and a drafted suggested change always waits for a reviewer) and settings (values for the settings Improve may tune). Omit it for every tier that’s ready.
For the prompt tier: the workspace’s provider and model that drafts the templates. Omit it for the model of the version’s own model-settings block.
object
For the prompt tier: how many templates it drafts. Omit it for the runtime’s default.
Which corrections the Improve run learns from. Omit it for the default: everyone’s (as-recorded) until the workspace, the project, or the agent in the project has an expert group, then only corrections recorded under one (experts-only).
Default: $5 and 30 candidates.
object
Responses
Section titled “Responses”The Improve run, running.
An Improve run: the runtime looking for better wording or settings values for an agent in a project, on the project’s test set, within a budget. A candidate that does better becomes a suggested change.
object
The project it works in. Absent from older servers, and on a run started for a workspace or an org before Improve runs worked in a project.
The version an Improve run starts from: the one the project runs, pinned there (pin) or the agent’s latest (latest).
object
The version of the project’s test set it searches and proves on; absent until it’s frozen.
The test set’s cases set aside for the proof: cases of of. None with fewer than five. Absent from older servers.
object
The tiers it tries, the prompt tier first.
Which corrections its comparisons count.
For the prompt tier: the provider and model that drafts the templates.
object
For the prompt tier: how many templates it drafts.
object
The most the Improve run’s comparisons may cost, in US dollars.
The most candidates it compares.
user:<id> or service:<id>.
Candidates tried so far.
What its comparisons have cost so far (US dollars).
A change passed more cases than the version the run started from, and failed none that passed: the run wrote it as a suggested change for a reviewer to decide.
object
No change the run tried did better: reason says why, and holdOut has the best change’s numbers when one got that far.
object
The best change’s proof numbers, when one got that far: on every case, or on the set-aside part for a run stored before that.
object
The run reached its budget with nothing kept.
object
What it spent, in US dollars.
The run failed: message says why.
object
The ids of the corrections it took when it started. Absent from older servers.
Why a cancelled Improve run stopped when nobody cancelled it: a comparison’s test run was cancelled for it (that run’s cancelReason, e.g. project-suspended). It wrote no suggested change. Absent when it was cancelled.
Its comparisons so far, each a test run to open: reference (the version as it is, on each part: what the proof is held to, case by case), each candidate (the block and the values it changed, on the search part: what picks the change to suggest), and the proof (the suggested change, on all the cases at the reference’s repetitions: what keeps it or not; an Improve run from before 0.4 ran its proof on the hold-out part). Absent from older servers.
object
object
For a drafted template that was never compared: why the check refused it (what it reads or names that the agent doesn’t have, or its size).
object
For a drafted template: what the drafter meant it to change.
The improve schedule and fire that started it (GET /v1/schedules/{triggerId}/fires); absent for an Improve run a person started.
object
Example
{ "startsFrom": { "follows": "pin" }, "tiers": [ "settings" ], "objective": "passRate", "groupWeights": "as-recorded", "status": "running", "outcome": { "kind": "suggested" }, "comparisons": [ { "role": "reference", "part": "search" } ]}Malformed request body (bad-input): no projectId, or a field the body doesn’t have (scope, testSetId and fromVersion among them), named in the message.
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 workspace (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" }}improve-not-ready: something the Improve run needs is missing (details.items, as POST /v1/improve-runs/check lists them). improve-run-running: the agent has a running Improve run in the project (details.improveRunId); one runs at a time. Or registry-read-only: the agent registry is read-only and takes no versions an Improve run makes; the message says why. Or Idempotency-Key was reused with a different body.
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" }}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" }}improve-unsupported: this runtime runs no Improve runs.
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 Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.
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/improve-runs: List Improve runs- Kindgi 0.4.0
- Error code
bad-input - Error code
idempotency-store-unavailable - Error code
improve-not-ready - Error code
improve-run-running - Error code
improve-unsupported - Error code
project-not-found - Error code
registry-read-only - Error code
request-too-large - Every error code