Skip to content
Kindgi

Submit a dry-run-passed proposal for HITL review

POST
/v1/proposals/{proposalId}/submit-review
curl --request POST \
  --url https://example.com/v1/proposals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/submit-review \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Supervisor-Id: example' \
  --data '{ "requiredRole": "standard", "expiresAt": "2026-04-15T12:00:00Z" }'

Enqueues a HITL approval and transitions the proposal to proposed-for-review. Legal only from dry-run-passed. Body is optional; defaults auto-derive the reviewer role (meta-fixes → senior).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
proposalId
required
string format: uuid

FixProposalId — opaque branded string (a UUID).

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 Body

Section titled “Request Body”
Media typeapplication/json

Body is optional — omit to accept every default. requiredRole overrides the auto-derivation (meta-fixes → senior). expiresAt sets the HITL approval deadline.

object
requiredRole

Reviewer role class. Hierarchy: standard < senior < admin.

string
Allowed values: standard senior admin
expiresAt
string format: date-time

Responses

Section titled “Responses”

200

Section titled “200”

Review enqueued.

Media typeapplication/json
object
proposal
required
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
approvalId
required
string format: uuid
metaFix
required

True when the proposal targets one of the supervisor’s own agent ids — reviewer role auto-bumps to senior unless overridden.

boolean
Example
{
  "proposal": {
    "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"
  }
}

404

Section titled “404”

No proposal visible under this supervisor with that id.

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

422

Section titled “422”

Ground-layer guardrail violation.

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