Dry-run a proposal against an eval dataset

POST

/v1/proposals/{proposalId}/dry-run

curl --request POST \
  --url https://example.com/v1/proposals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/dry-run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Supervisor-Id: example' \
  --data '{ "datasetId": "example", "datasetVersion": "example", "criterion": { "kind": "min-pass-rate", "minPassRate": 1 } }'

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

Runs the candidate agent against the caller-supplied dataset + criterion. Transitions the proposal to dry-run-passed or dry-run-failed. Legal only from draft or dry-run-failed.

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

datasetId

required

string

>= 1 characters

datasetVersion

required

string

>= 1 characters

criterion

required

One of:

object

object

kind

required

string

Allowed value: min-pass-rate

minPassRate

required

number

<= 1

object

object

kind

required

string

Allowed value: strict-improvement

baselinePassRate

required

number

<= 1

minDelta

required

number

Responses

200

Dry-run completed.

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

passed

required

True when the candidate met the criterion — proposal moves to dry-run-passed. False → dry-run-failed (still a legitimate response, not an error).

boolean

Example

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

422

Baseline mismatch, apply-change failure, or runtime dry-run error.

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