Skip to content
Kindgi

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

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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
agentId
required
string

AgentId — dotted namespace (acme.drafting).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
version
required

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

string
scope
required
One of: discriminator: kind

The agent’s default for the whole tenant.

object
kind
required
string
Allowed values: tenant
reason
string
<= 2000 characters
evalRunId

The comparison this promotion was judged on.

string

Responses

Section titled “Responses”

200

Section titled “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
id
required
string
version
required
string
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

Section titled “400”

Malformed body, or the eval run is not a finished comparison.

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”

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