Skip to content
Kindgi

Draft a fix proposal

POST
/v1/proposals
curl --request POST \
  --url https://example.com/v1/proposals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Supervisor-Id: example' \
  --data '{ "agentId": "example", "agentVersion": "example", "tier": "prompt", "change": {}, "patternRefs": [ { "kind": "guardrail-violation", "key": "example", "count": 1, "firstSeenAt": "2026-04-15T12:00:00Z", "lastSeenAt": "2026-04-15T12:00:00Z", "sampleConversations": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] } ], "hypothesis": "example", "proposerRuleId": "example" }'

Inserts a new proposal in draft state. Duplicate proposals (same (supervisor, fingerprint) non-terminal) short-circuit to the pre-existing row and mark the response with X-Proposal-Deduped: true.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Supervisor-Id
required
string
>= 1 characters

SupervisorId scoping this request. Every /v1/proposals route requires this header — proposals are supervisor-owned, and the API does not derive supervisor scope from the token.

Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Draft a fix proposal for (agentId, agentVersion). The supervisor context comes from the X-Supervisor-Id header; the caller supplies the target agent + change payload + supporting evidence. Duplicate proposals (same (supervisor, fingerprint) in a non-terminal state) short-circuit to the pre-existing row and set X-Proposal-Deduped: true on the response.

object
agentId
required
string
agentVersion
required
string
tier
required
string
Allowed values: prompt retrieval tool-config
change
required

Polymorphic change payload. Shape depends on the sibling tier on the proposal (prompt / retrieval / tool-config).

object
key
additional properties
any
patternRefs
required
Array<object>
object
kind
required
string
Allowed values: guardrail-violation tool-error budget-exceeded model-error aborted
key
required
string
count
required
integer
>= 1
firstSeenAt
required
string format: date-time
lastSeenAt
required
string format: date-time
sampleConversations
required
Array<string>
hypothesis
required
string
>= 1 characters
proposerRuleId
required
string
>= 1 characters

Responses

Section titled “Responses”

201

Section titled “201”

Proposal drafted (or deduped).

Media typeapplication/json
object
id
required

FixProposalId.

string format: uuid
tenantId
required
string format: uuid
supervisorId
required
string
agentId
required
string
agentVersion
required

Semver of the baseline agent version.

string
tier
required
string
Allowed values: prompt retrieval tool-config
change
required

Polymorphic change payload. Shape depends on the sibling tier on the proposal (prompt / retrieval / tool-config).

object
key
additional properties
any
patternRefs
required
Array<object>
object
kind
required
string
Allowed values: guardrail-violation tool-error budget-exceeded model-error aborted
key
required
string
count
required
integer
>= 1
firstSeenAt
required
string format: date-time
lastSeenAt
required
string format: date-time
sampleConversations
required
Array<string>
hypothesis
required
string
proposerRuleId
required
string
status
required
string
Allowed values: draft dry-running dry-run-passed dry-run-failed proposed-for-review approved rejected applied rolled-back withdrawn
fingerprint
required

Sha256(tier + agentId + agentVersion + canonical(change)). Dedup key.

string
resolutionReason
string
reviewApprovalId

HITL approval id created when the proposal was submitted for review.

string format: uuid
appliedVersion

Semver of the new agent version the proposal materialized as. Present on applied and rolled-back proposals.

string
appliedAt
string format: date-time
rolledBackAt
string format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
resolvedAt
string format: date-time
Example
{
  "tier": "prompt",
  "patternRefs": [
    {
      "kind": "guardrail-violation"
    }
  ],
  "status": "draft"
}

400

Section titled “400”

Malformed request body.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

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

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}