Withdraw a non-terminal proposal

POST

/v1/proposals/{proposalId}/withdraw

curl --request POST \
  --url https://example.com/v1/proposals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/withdraw \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Supervisor-Id: example' \
  --data '{ "reason": "example" }'

• Same-origin — path relative to the deployment root.

Transitions the proposal to withdrawn. Legal from any non-terminal state (draft | dry-running | dry-run-passed | dry-run-failed | proposed-for-review). Terminal states surface as 409 proposal-invalid-state-transition.

Authorizations

• bearerAuth

Parameters

Path Parameters

proposalId

required

string format: uuid

FixProposalId — opaque branded string (a UUID).

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^required

Media typeapplication/json

object

reason

required

string

>= 1 characters

Example^generated

{
  "reason": "example"
}

Responses

200

Proposal withdrawn.

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

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

Example^generated

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

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

Example^generated

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

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

Example^generated

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

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

Example^generated

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

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

Example^generated

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