# Propose new content for a data block

POST

/v1/proposals

```sh
curl --request POST \
  --url https://example.com/v1/proposals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "agentId": "example", "fromVersion": "example", "scope": { "kind": "tenant" }, "tier": "settings-block", "change": { "blockId": "example", "content": { "values": {}, "template": "example" } }, "hypothesis": "example", "evidence": { "judgmentIds": [ "example" ] } }'
```

A hand-written proposal: new settings values or a new prompt template for a block `fromVersion` pins, for a live scope. Checked as publishing that block version would be (its schema carries over), and refused when it equals the pinned content. The same change from the same version for the same scope is one proposal: answered `200` with `X-Proposal-Deduped: true`. Needs `publish` on the agent.

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.1.9/reference/api.md#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 Bodyrequired

application/json

A hand-written proposal: new content for a data block that `fromVersion` pins, for a live scope. The same change from the same version for the same scope is one proposal (answered with `X-Proposal-Deduped: true`).

object

**agentId**

required

string

**fromVersion**

required

The agent version the change applies to.

string

**scope**

required

One of: discriminator: kind

- **object**

  The agent’s default for the whole tenant.

  object

  **kind**

  required

  string

  Allowed values: tenant

- **object**

  An org’s projects.

  object

  **kind**

  required

  string

  Allowed values: org

  **orgId**

  required

  string format: uuid

- **object**

  One project.

  object

  **kind**

  required

  string

  Allowed values: project

  **projectId**

  required

  string format: uuid

- **object**

  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

**tier**

required

What a proposal changes: a settings block (new values) or a prompt block (a new template) the agent version pins.

string

Allowed values: settings-block prompt-block

**change**

required

object

**blockId**

required

A block `fromVersion` pins, of the tier’s kind.

string

**content**

required

`{ values }` for a settings block (they must satisfy its schema), `{ template }` for a prompt block.

object

**values**

object

**_key_**

additional properties

any

**template**

string

**hypothesis**

required

string

\>= 1 characters <= 2000 characters

**evidence**

object

**judgmentIds**

Array\<string>

## Responses

### 200

The same proposal, made before.

application/json

An improvement proposal: a change to one data block an agent version pins, for one live scope, taken through the same comparison, gate and promotion as any other version.

object

**id**

required

string format: uuid

**agentId**

required

string

**fromVersion**

required

The agent version the change applies to.

string

**scope**

required

One of: discriminator: kind

- **object**

  The agent’s default for the whole tenant.

  object

  **kind**

  required

  string

  Allowed values: tenant

- **object**

  An org’s projects.

  object

  **kind**

  required

  string

  Allowed values: org

  **orgId**

  required

  string format: uuid

- **object**

  One project.

  object

  **kind**

  required

  string

  Allowed values: project

  **projectId**

  required

  string format: uuid

- **object**

  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

**tier**

required

What a proposal changes: a settings block (new values) or a prompt block (a new template) the agent version pins.

string

Allowed values: settings-block prompt-block

**change**

required

object

**blockId**

required

The data block the change is to.

string

**fromVersion**

required

The block version the agent version pins: what’s being changed.

string

**content**

required

The new content: `{ values }` for a settings block (its schema carries over), `{ template }` for a prompt block (its parameters carry over).

object

**values**

object

**_key_**

additional properties

any

**template**

string

**hypothesis**

required

What the change should improve, and why.

string

**evidence**

object

**judgmentIds**

Array\<string>

**drafter**

required

Who wrote the proposal: a person, or one of the runtime’s drafters.

object

**kind**

required

string

Allowed values: person settings-optimizer prompt-drafter

**by**

For a person: `user:<id>` (or `service:<id>`).

string

**version**

For a drafter: the drafter’s version.

string

**model**

For a drafter that used a model: which.

object

**providerId**

required

string

**model**

required

string

**passId**

For a drafter: the improvement pass that drafted it (`GET /v1/improvement-passes/{passId}`).

string

**status**

required

Where a proposal stands, from its comparison and its promotion (never stored). `draft`: not evaluated yet. `evaluating`: its comparison is queued or running. `evaluated`: the candidate beat the recorded outputs on the objective metric by more than the noise (the spread, with more than one repetition). `not-better`: it didn’t. `evaluation-failed`: the comparison failed or was cancelled. `in-review`: requested; the gate passed and an approval is open. `promoted`: live for the scope (`promotion.liveNow` says whether it still serves it). `refused`: the gate refused it. `rejected`: the reviewer rejected it. `expired`: the approval expired undecided. `superseded`: approved after the scope’s live version or policy changed. `rolled-back`: rolled back through the proposal. `withdrawn`: withdrawn.

string

Allowed values: draft evaluating evaluated not-better evaluation-failed in-review promoted refused rejected expired superseded rolled-back withdrawn

**candidate**

The versions evaluating the proposal published. They serve no scope until a promotion makes the agent version live.

object

**agentVersion**

required

The derived agent version (its `derivedFrom.proposalId` names the proposal).

string

**blockVersion**

required

The block version published from the proposal’s content.

string

**pinsDigest**

required

string

**evaluation**

The comparison the proposal was evaluated with, and what it found on the objective metric (the full summary is the eval run’s).

object

**evalRunId**

required

string format: uuid

**suiteId**

required

The test set (a judged eval suite).

string

**objective**

required

string

Allowed values: weightedYesShare weightedPrecisionAtK

**startedAt**

required

string format: date-time

**runStatus**

The eval run’s status. Absent when the run can’t be read.

string

Allowed values: pending running completed failed cancelled

**baseline**

The recorded outputs’ score; `null` without judged evidence.

number | null

**candidate**

The candidate’s score.

number | null

**delta**

number | null

**spread**

With more than one repetition: the candidate’s max − min, the noise a delta must beat.

number

**cases**

integer

**better**

Set once the comparison finished.

boolean

**promotion**

The promotion the proposal’s request made.

object

**id**

required

string

**status**

required

string

Allowed values: promoted pending-approval refused superseded rejected expired

**approvalId**

The approval a request in review waits on.

string

**liveNow**

For a promoted proposal: whether its version still serves the scope.

boolean

**rolledBack**

object

**at**

required

string format: date-time

**promotionId**

required

The rollback’s own promotion row.

string

**by**

required

string

**reason**

string

**withdrawn**

object

**at**

required

string format: date-time

**by**

required

string

**reason**

required

string

**createdAt**

required

string format: date-time

**updatedAt**

required

string format: date-time

##### Example

```json
{
  "scope": {
    "kind": "tenant"
  },
  "tier": "settings-block",
  "drafter": {
    "kind": "person"
  },
  "status": "draft",
  "evaluation": {
    "objective": "weightedYesShare",
    "runStatus": "pending"
  },
  "promotion": {
    "status": "promoted"
  }
}
```

### 201

The proposal, a `draft`.

application/json

An improvement proposal: a change to one data block an agent version pins, for one live scope, taken through the same comparison, gate and promotion as any other version.

object

**id**

required

string format: uuid

**agentId**

required

string

**fromVersion**

required

The agent version the change applies to.

string

**scope**

required

One of: discriminator: kind

- **object**

  The agent’s default for the whole tenant.

  object

  **kind**

  required

  string

  Allowed values: tenant

- **object**

  An org’s projects.

  object

  **kind**

  required

  string

  Allowed values: org

  **orgId**

  required

  string format: uuid

- **object**

  One project.

  object

  **kind**

  required

  string

  Allowed values: project

  **projectId**

  required

  string format: uuid

- **object**

  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

**tier**

required

What a proposal changes: a settings block (new values) or a prompt block (a new template) the agent version pins.

string

Allowed values: settings-block prompt-block

**change**

required

object

**blockId**

required

The data block the change is to.

string

**fromVersion**

required

The block version the agent version pins: what’s being changed.

string

**content**

required

The new content: `{ values }` for a settings block (its schema carries over), `{ template }` for a prompt block (its parameters carry over).

object

**values**

object

**_key_**

additional properties

any

**template**

string

**hypothesis**

required

What the change should improve, and why.

string

**evidence**

object

**judgmentIds**

Array\<string>

**drafter**

required

Who wrote the proposal: a person, or one of the runtime’s drafters.

object

**kind**

required

string

Allowed values: person settings-optimizer prompt-drafter

**by**

For a person: `user:<id>` (or `service:<id>`).

string

**version**

For a drafter: the drafter’s version.

string

**model**

For a drafter that used a model: which.

object

**providerId**

required

string

**model**

required

string

**passId**

For a drafter: the improvement pass that drafted it (`GET /v1/improvement-passes/{passId}`).

string

**status**

required

Where a proposal stands, from its comparison and its promotion (never stored). `draft`: not evaluated yet. `evaluating`: its comparison is queued or running. `evaluated`: the candidate beat the recorded outputs on the objective metric by more than the noise (the spread, with more than one repetition). `not-better`: it didn’t. `evaluation-failed`: the comparison failed or was cancelled. `in-review`: requested; the gate passed and an approval is open. `promoted`: live for the scope (`promotion.liveNow` says whether it still serves it). `refused`: the gate refused it. `rejected`: the reviewer rejected it. `expired`: the approval expired undecided. `superseded`: approved after the scope’s live version or policy changed. `rolled-back`: rolled back through the proposal. `withdrawn`: withdrawn.

string

Allowed values: draft evaluating evaluated not-better evaluation-failed in-review promoted refused rejected expired superseded rolled-back withdrawn

**candidate**

The versions evaluating the proposal published. They serve no scope until a promotion makes the agent version live.

object

**agentVersion**

required

The derived agent version (its `derivedFrom.proposalId` names the proposal).

string

**blockVersion**

required

The block version published from the proposal’s content.

string

**pinsDigest**

required

string

**evaluation**

The comparison the proposal was evaluated with, and what it found on the objective metric (the full summary is the eval run’s).

object

**evalRunId**

required

string format: uuid

**suiteId**

required

The test set (a judged eval suite).

string

**objective**

required

string

Allowed values: weightedYesShare weightedPrecisionAtK

**startedAt**

required

string format: date-time

**runStatus**

The eval run’s status. Absent when the run can’t be read.

string

Allowed values: pending running completed failed cancelled

**baseline**

The recorded outputs’ score; `null` without judged evidence.

number | null

**candidate**

The candidate’s score.

number | null

**delta**

number | null

**spread**

With more than one repetition: the candidate’s max − min, the noise a delta must beat.

number

**cases**

integer

**better**

Set once the comparison finished.

boolean

**promotion**

The promotion the proposal’s request made.

object

**id**

required

string

**status**

required

string

Allowed values: promoted pending-approval refused superseded rejected expired

**approvalId**

The approval a request in review waits on.

string

**liveNow**

For a promoted proposal: whether its version still serves the scope.

boolean

**rolledBack**

object

**at**

required

string format: date-time

**promotionId**

required

The rollback’s own promotion row.

string

**by**

required

string

**reason**

string

**withdrawn**

object

**at**

required

string format: date-time

**by**

required

string

**reason**

required

string

**createdAt**

required

string format: date-time

**updatedAt**

required

string format: date-time

##### Example

```json
{
  "scope": {
    "kind": "tenant"
  },
  "tier": "settings-block",
  "drafter": {
    "kind": "person"
  },
  "status": "draft",
  "evaluation": {
    "objective": "weightedYesShare",
    "runStatus": "pending"
  },
  "promotion": {
    "status": "promoted"
  }
}
```

### 400

Malformed request body, or the change fails validation. Or `reference-out-of-scope`: a project or segment scope whose project doesn’t reach the agent, or a block the agent’s project doesn’t reach (`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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

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

### 404

`fromVersion` isn’t an active version of the agent (`agent-version-not-found`).

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

##### Examplegenerated

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

### 409

Idempotency-Key was reused with a different body, or resource-state conflict.

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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

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

## See also

- [`GET /v1/proposals`: List improvement proposals](https://docs.kindgi.com/v0.1.9/reference/api/operations/proposalslist.md)
- [Error code `agent-version-not-found`](https://docs.kindgi.com/v0.1.9/reference/errors.md#agent-version-not-found)
- [Error code `reference-out-of-scope`](https://docs.kindgi.com/v0.1.9/reference/errors.md#reference-out-of-scope)
- [Error code `request-too-large`](https://docs.kindgi.com/v0.1.9/reference/errors.md#request-too-large)
- [Every error code](https://docs.kindgi.com/v0.1.9/reference/errors.md)