Cancel an improvement pass

POST

/v1/improvement-passes/{passId}/cancel

const url = 'https://example.com/v1/improvement-passes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

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/improvement-passes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel \
  --header 'Authorization: Bearer <token>'

A running pass stops and ends cancelled, writing no proposal. Needs publish on its agent.

Authorizations

bearerAuth

Parameters

Path Parameters

passId

required

string format: uuid

The improvement pass id (a UUID).

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

Responses

200

The pass, cancelled.

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

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.

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

No such pass.

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

improvement-pass-finished: it has ended already.

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"
  }
}

Cancel an improvement pass

Authorizations

Parameters

Path Parameters

Header Parameters

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

404

Examplegenerated

409

Examplegenerated

500

Examplegenerated

501

Examplegenerated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated