Propose new content for a data block
const url = 'https://example.com/v1/proposals';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"agentId":"example","fromVersion":"example","scope":{"kind":"tenant"},"tier":"settings-block","change":{"blockId":"example","content":{"values":{},"template":"example"}},"hypothesis":"example","evidence":{"judgmentIds":["example"]}}'};
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 \ --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
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 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
Section titled “Request Bodyrequired”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
The agent version the change applies to.
The agent’s default for the whole tenant.
object
An org’s projects.
object
One project.
object
A segment path within a project: it covers every run whose path starts with it.
object
object
Lowercase, like an identifier: company, contact-role.
What a proposal changes: a settings block (new values) or a prompt block (a new template) the agent version pins.
object
A block fromVersion pins, of the tier’s kind.
{ values } for a settings block (they must satisfy its schema), { template } for a prompt block.
object
object
object
Responses
Section titled “Responses”The same proposal, made before.
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
The agent version the change applies to.
The agent’s default for the whole tenant.
object
An org’s projects.
object
One project.
object
A segment path within a project: it covers every run whose path starts with it.
object
object
Lowercase, like an identifier: company, contact-role.
What a proposal changes: a settings block (new values) or a prompt block (a new template) the agent version pins.
object
The data block the change is to.
The block version the agent version pins: what’s being changed.
The new content: { values } for a settings block (its schema carries over), { template } for a prompt block (its parameters carry over).
object
object
What the change should improve, and why.
object
Who wrote the proposal: a person, or one of the runtime’s drafters.
object
For a person: user:<id> (or service:<id>).
For a drafter: the drafter’s version.
For a drafter that used a model: which.
object
For a drafter: the improvement pass that drafted it (GET /v1/improvement-passes/{passId}).
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.
The versions evaluating the proposal published. They serve no scope until a promotion makes the agent version live.
object
The derived agent version (its derivedFrom.proposalId names the proposal).
The block version published from the proposal’s content.
The comparison the proposal was evaluated with, and what it found on the objective metric (the full summary is the eval run’s).
object
The test set (a judged eval suite).
The eval run’s status. Absent when the run can’t be read.
The recorded outputs’ score; null without judged evidence.
The candidate’s score.
With more than one repetition: the candidate’s max − min, the noise a delta must beat.
Set once the comparison finished.
The promotion the proposal’s request made.
object
The approval a request in review waits on.
For a promoted proposal: whether its version still serves the scope.
object
The rollback’s own promotion row.
object
Example
{ "scope": { "kind": "tenant" }, "tier": "settings-block", "drafter": { "kind": "person" }, "status": "draft", "evaluation": { "objective": "weightedYesShare", "runStatus": "pending" }, "promotion": { "status": "promoted" }}The proposal, a draft.
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
The agent version the change applies to.
The agent’s default for the whole tenant.
object
An org’s projects.
object
One project.
object
A segment path within a project: it covers every run whose path starts with it.
object
object
Lowercase, like an identifier: company, contact-role.
What a proposal changes: a settings block (new values) or a prompt block (a new template) the agent version pins.
object
The data block the change is to.
The block version the agent version pins: what’s being changed.
The new content: { values } for a settings block (its schema carries over), { template } for a prompt block (its parameters carry over).
object
object
What the change should improve, and why.
object
Who wrote the proposal: a person, or one of the runtime’s drafters.
object
For a person: user:<id> (or service:<id>).
For a drafter: the drafter’s version.
For a drafter that used a model: which.
object
For a drafter: the improvement pass that drafted it (GET /v1/improvement-passes/{passId}).
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.
The versions evaluating the proposal published. They serve no scope until a promotion makes the agent version live.
object
The derived agent version (its derivedFrom.proposalId names the proposal).
The block version published from the proposal’s content.
The comparison the proposal was evaluated with, and what it found on the objective metric (the full summary is the eval run’s).
object
The test set (a judged eval suite).
The eval run’s status. Absent when the run can’t be read.
The recorded outputs’ score; null without judged evidence.
The candidate’s score.
With more than one repetition: the candidate’s max − min, the noise a delta must beat.
Set once the comparison finished.
The promotion the proposal’s request made.
object
The approval a request in review waits on.
For a promoted proposal: whether its version still serves the scope.
object
The rollback’s own promotion row.
object
Example
{ "scope": { "kind": "tenant" }, "tier": "settings-block", "drafter": { "kind": "person" }, "status": "draft", "evaluation": { "objective": "weightedYesShare", "runStatus": "pending" }, "promotion": { "status": "promoted" }}Malformed request 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" }}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" }}fromVersion isn’t an active version of the agent (agent-version-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" }}Idempotency-Key was reused with a different body, or resource-state conflict.
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" }}