Start an improvement pass

POST

/v1/proposals/improve

const url = 'https://example.com/v1/proposals/improve';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"agentId":"example","fromVersion":"example","scope":{"kind":"tenant"},"suiteId":"example","tiers":["settings"],"model":{"providerId":"example","model":"example"},"candidates":3,"classWeights":"as-recorded","objective":"weightedYesShare","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/proposals/improve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "agentId": "example", "fromVersion": "example", "scope": { "kind": "tenant" }, "suiteId": "example", "tiers": [ "settings" ], "model": { "providerId": "example", "model": "example" }, "candidates": 3, "classWeights": "as-recorded", "objective": "weightedYesShare", "budget": { "maxCostUsd": 1, "maxCandidates": 1 } }'

The runtime looks for better values for the version’s tunable settings (keys its settings blocks’ schemas mark x-kindgi-tunable) on the test set, within the budget, and writes its best candidate as an improvement proposal, which waits for a reviewer when requested. It answers at once with the pass, running. Checked first: the version is active and pins a settings block with tunable keys (400 validation-failed), the agent registry takes writes (409 registry-read-only), and the agent has a live version for the whole tenant (409 proposal-needs-pin). No pass starts for an agent whose project is suspended (409 project-suspended), and a pass going when it is ends cancelled, with the reason in cancelReason. Needs publish on the agent. Without improvement passes in this runtime, 501 improve-unsupported.

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

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 Body^required

application/json

Start an improvement pass.

object

agentId

required

string

fromVersion

The version whose settings it tunes. Default: the one serving scope.

string

scope

required

One of: discriminator: kind

The agent’s default for the whole tenant.

object

kind

required

string

Allowed values: tenant

A segment path within a project: it covers every run whose path starts with it.

object

kind

required

string

Allowed values: segment

projectId

required

string format: uuid

path

required

Array<object>

>= 1 items <= 8 items

object

key

required

Lowercase, like an identifier: company, contact-role.

string

/^[a-z][a-z0-9_-]{0,63}$/

value

required

string

>= 1 characters <= 256 characters

suiteId

required

The test set (a judged eval suite). The pass splits it into a search part and a hold-out part, and proves its best candidate on the hold-out part.

string

tiers

['settings']: values for the tunable settings keys. ['prompt']: a model drafts templates for the prompt block (needs model); a template that reads or names anything the agent doesn’t have is refused, and a drafted proposal always waits for a reviewer.

Array<string>

default: settings >= 1 items <= 1 items

Allowed values: settings prompt

model

For a prompt pass: the tenant’s provider and model that drafts the templates.

object

providerId

required

string

model

required

string

candidates

For a prompt pass: how many templates it drafts.

integer

default: 3 >= 1 <= 5

classWeights

Which judgments the pass learns from: by default only those recorded under a restricted (trusted) judge class.

string

default: restricted-only

Allowed values: as-recorded restricted-only

objective

string

default: weightedYesShare

Allowed values: weightedYesShare weightedPrecisionAtK

budget

Default: $5 and 30 candidates.

object

maxCostUsd

number

> 0 <= 100

maxCandidates

integer

>= 1 <= 200

Responses

202

The pass, running.

application/json

An improvement pass: the runtime looking for better values for an agent version’s tunable settings (x-kindgi-tunable) on a test set, within a budget. Its best candidate becomes an improvement proposal.

object

required

string format: uuid

agentId

required

string

fromVersion

required

The version whose settings it tunes.

string

scope

required

One of: discriminator: kind

The agent’s default for the whole tenant.

object

kind

required

string

Allowed values: tenant

A segment path within a project: it covers every run whose path starts with it.

object

kind

required

string

Allowed values: segment

projectId

required

string format: uuid

path

required

Array<object>

>= 1 items <= 8 items

object

key

required

Lowercase, like an identifier: company, contact-role.

string

/^[a-z][a-z0-9_-]{0,63}$/

value

required

string

>= 1 characters <= 256 characters

suiteId

required

The test set it searches and proves on.

string

tiers

required

Array<string>

Allowed values: settings prompt

objective

required

string

Allowed values: weightedYesShare weightedPrecisionAtK

classWeights

Which judgments its comparisons count. Absent from older servers: restricted-only.

string

Allowed values: as-recorded restricted-only

model

For a prompt pass: the provider and model that drafts the templates.

object

providerId

required

string

model

required

string

candidates

For a prompt pass: how many templates it drafts.

integer

>= 1 <= 5

budget

required

object

maxCostUsd

required

The most the pass’s comparisons may cost, in US dollars.

number

> 0 <= 100

maxCandidates

required

The most candidates it compares.

integer

>= 1 <= 200

requestedBy

required

string

status

required

string

Allowed values: running completed failed cancelled

candidatesEvaluated

required

integer

costUsd

required

What its comparisons have cost so far (US dollars).

string

outcome

What a finished pass found. proposed: its best candidate beat the current values on the test set’s hold-out part, so it wrote an improvement proposal (proposalId) for a reviewer to decide. nothing-found: no candidate beat them by more than the noise, or within the budget (reason; holdOut has the best candidate’s numbers when one got that far). failed: message says why.

object

kind

required

string

Allowed values: proposed nothing-found failed

proposalId

string format: uuid

reason

string

holdOut

object

baseline

required

number | null

candidate

required

number | null

delta

required

number | null

spread

number

message

string

cancelReason

Why a cancelled pass stopped when nobody cancelled it: a comparison’s eval run was cancelled for it (that run’s cancelReason, e.g. project-suspended). It wrote no proposal. Absent when it was cancelled.

string

comparisons

Its comparisons so far, each an eval run to open: reference (the version as it is, on the search part), each candidate (the block and the values it changed, on the search part), and the proof (the proposal, on the hold-out part). Absent from older servers.

Array<object>

object

evalRunId

string format: uuid

role

required

string

Allowed values: reference candidate proof

part

required

string

Allowed values: search hold-out

blockId

string

changed

object

key

additional properties

any

score

number | null

failed

string

refused

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).

Array<object>

object

path

required

string

message

required

string

hypothesis

For a drafted template: what the drafter meant it to change.

string

trigger

The improve schedule and fire that started it (GET /v1/schedules/{triggerId}/fires); absent for a pass a person started.

object

triggerId

required

string

fireId

required

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

finishedAt

string format: date-time

Example

{
  "scope": {
    "kind": "tenant"
  },
  "tiers": [
    "settings"
  ],
  "objective": "weightedYesShare",
  "classWeights": "as-recorded",
  "status": "running",
  "outcome": {
    "kind": "proposed"
  },
  "comparisons": [
    {
      "role": "reference",
      "part": "search"
    }
  ]
}

400

Malformed request body, or validation-failed. Or reference-out-of-scope: the test set isn’t registered in the agent’s project, its org or the tenant, or a project or segment scope doesn’t reach the agent (details.issues).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

fromVersion (or the version serving the scope) is not an active version.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

registry-read-only, proposal-needs-pin, or project-suspended: the agent’s project is suspended. Or Idempotency-Key was reused with a different body.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

501

improve-unsupported: this runtime runs no improvement passes.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Start an improvement pass

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

202

Example

400

Examplegenerated

401

Examplegenerated

404

Examplegenerated

409

Examplegenerated

413

Examplegenerated

500

Examplegenerated

501

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated