Check a promotion against its gate

POST

/v1/agents/{agentId}/promotions/check

curl --request POST \
  --url https://example.com/v1/agents/example/promotions/check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "version": "example", "scope": { "kind": "tenant" }, "reason": "example", "evalRunId": "example" }'

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

What POST …/promotions with the same body would do, with nothing recorded: would-promote, needs-approval (with the approval it needs) or gate-failed, with every check. For a pipeline: evaluate, check, promote. Needs read on the agent.

Authorizations

• bearerAuth

Parameters

Path Parameters

agentId

required

string

AgentId — dotted namespace (acme.drafting).

Request Body^required

Media typeapplication/json

object

version

required

The agent version to make live (registered, active).

string

scope

required

One of: discriminator: kind

object

The agent’s default for the whole tenant.

object

kind

required

string

Allowed values: tenant

object

An org’s projects.

object

kind

required

string

Allowed values: org

orgId

required

string format: uuid

object

One project.

object

kind

required

string

Allowed values: project

projectId

required

string format: uuid

object

A segment path within a project: it covers every run whose path starts with it.

object

kind

required

string

Allowed values: segment

projectId

required

string format: uuid

path

required

Array<object>

>= 1 items <= 8 items

object

key

required

Lowercase, like an identifier: company, contact-role.

string

/^[a-z][a-z0-9_-]{0,63}$/

value

required

string

>= 1 characters <= 256 characters

reason

string

<= 2000 characters

evalRunId

The comparison this promotion was judged on.

string

Responses

200

The gate’s answer.

Media typeapplication/json

What the gate would say about a promotion. Nothing is recorded.

object

outcome

required

string

Allowed values: would-promote needs-approval gate-failed

policy

required

One of:

object

object

id

required

string

version

required

string

null

null

checks

required

Array<object>

One of a gate’s checks, as the promotion records it.

object

name

required

Stable: comparison.required, comparison.status, comparison.freshness, comparison.suite, sameContents, baselineIsLive, scopeCovered, evidence.<metric>.minCases|minWeight|baselineMinCases|baselineMinWeight, metric.<metric>.k|minCandidate|maxDrop, replay.maxDiverged|maxErrors|maxRefusedWrites|maxStopped, classWeights.restrictedOnly.

string

passed

required

boolean

message

required

A plain sentence: what was found against what the policy asks.

string

value

number | string

threshold

number | string

approval

The approval a passing promotion waits for.

object

role

required

string

Allowed values: standard senior admin

count

required

integer

>= 1

separateApprover

required

Whoever asked for the promotion may not approve it.

boolean

Example

{
  "outcome": "would-promote",
  "approval": {
    "role": "standard"
  }
}

400

Malformed body, or the eval run is not a finished comparison. Or reference-out-of-scope: a project scope whose project doesn’t reach the agent (details.issues).

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

The version, the agent or the eval run is not found.

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

413

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

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

See also

• GET /v1/agents/{agentId}: Fetch the latest version of an agent
• GET /v1/agents/{agentId}/versions: List versions of an agent
• POST /v1/agents/{agentId}/versions: Derive an agent version with data-block pins swapped
• GET /v1/agents/{agentId}/versions/{version}: Fetch a specific agent version
• Error code reference-out-of-scope
• Error code request-too-large
• Every error code