Publish a release gate

POST

/v1/release-gates

const url = 'https://example.com/v1/release-gates';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"id":"example","version":"example","agentId":"example","scope":{"kind":"tenant"},"spec":{"comparison":{"maxAgeHours":1,"testSet":{"id":"example","version":"example"}},"evidence":{"minCases":1,"minWeight":1},"metrics":[{"name":"passRate","k":1,"minCandidate":1,"maxDrop":1}],"replay":{"maxDiverged":1,"maxErrors":1,"maxRefusedWrites":1,"maxStopped":1},"cases":{"minPassing":1,"noNewFailures":true},"approvals":{"role":"standard","separateApprover":true},"onlyExpertGroups":true},"description":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/release-gates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "example", "version": "example", "agentId": "example", "scope": { "kind": "tenant" }, "spec": { "comparison": { "maxAgeHours": 1, "testSet": { "id": "example", "version": "example" } }, "evidence": { "minCases": 1, "minWeight": 1 }, "metrics": [ { "name": "passRate", "k": 1, "minCandidate": 1, "maxDrop": 1 } ], "replay": { "maxDiverged": 1, "maxErrors": 1, "maxRefusedWrites": 1, "maxStopped": 1 }, "cases": { "minPassing": 1, "noNewFailures": true }, "approvals": { "role": "standard", "separateApprover": true }, "onlyExpertGroups": true }, "description": "example" }'

Registers a release gate, or a new version of one: what a pin of agentId for scope must show. One gate per agent and scope: another gate id for a scope that has one is refused with 409 release-gate-scope-taken (details.heldBy names it; publish a new version of that one instead), and a new version can’t change the agent or scope (409 release-gate-scope-changed). The spec is checked strictly: an unknown key is refused (400 validation-failed, details.issues). Needs admin on the tenant: whoever may pin can’t loosen their own gate.

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).

Request Body^required

application/json

object

required

Yours to choose, e.g. acme.drafting-prod.

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

version

required

string

/^\d+\.\d+\.\d+$/

agentId

required

string

scope

required

One of: discriminator: kind

The whole tenant.

object

kind

required

string

Allowed values: tenant

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

spec

required

What a pin must show. Every part is optional; an empty spec checks nothing. A pin must name a comparison (testRunId) exactly when the spec has comparison, evidence, metrics, replay, cases or onlyExpertGroups. Unknown keys are refused.

object

comparison

object

maxAgeHours

number

> 0

testSet

object

required

string

version

string

evidence

The evidence from corrections behind each gated metric; for a metric with maxDrop, the baseline’s too.

object

minCases

integer

minWeight

number

metrics

Array<object>

object

name

required

string

Allowed values: passRate caseCoverage weightedPrecisionAtK

weightedPrecisionAtK only: the summary’s k must be this.

integer

>= 1 <= 100

minCandidate

number

<= 1

maxDrop

How far the candidate may fall below the baseline (the pinned version).

number

<= 1

replay

Each knob left out of the block is 0. No block: no replay checks.

object

maxDiverged

integer

maxErrors

integer

maxRefusedWrites

At most this many tool calls the replay refused (the comparison summary’s refusedWrites). Reads count too, despite the name.

integer

maxStopped

integer

cases

The cases the comparison graded: each correction it checked is a case, and it passes when every repetition did.

object

minPassing

At least this many cases pass.

integer

noNewFailures

No case that passed before fails: none of the comparison’s corrections that are fixed now fails it. One the comparison didn’t grade isn’t counted; the check’s message says how many of the cases fixed now it graded.

boolean

approvals

A passing pin waits for a reviewer.

object

role

Default senior.

string

Allowed values: standard senior admin

separateApprover

Default true.

boolean

onlyExpertGroups

Only expert groups count: the comparison must be weighted experts-only, so a group anyone may assert can’t move the gate.

boolean

description

string

Responses

201

Release gate published.

application/json

object

required

string

version

required

string

agentId

required

string

scope

required

One of: discriminator: kind

The whole tenant.

object

kind

required

string

Allowed values: tenant

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

spec

required

object

comparison

object

maxAgeHours

number

> 0

testSet

object

required

string

version

string

evidence

The evidence from corrections behind each gated metric; for a metric with maxDrop, the baseline’s too.

object

minCases

integer

minWeight

number

metrics

Array<object>

object

name

required

string

Allowed values: passRate caseCoverage weightedPrecisionAtK

weightedPrecisionAtK only: the summary’s k must be this.

integer

>= 1 <= 100

minCandidate

number

<= 1

maxDrop

How far the candidate may fall below the baseline (the pinned version).

number

<= 1

replay

Each knob left out of the block is 0. No block: no replay checks.

object

maxDiverged

integer

maxErrors

integer

maxRefusedWrites

At most this many tool calls the replay refused (the comparison summary’s refusedWrites). Reads count too, despite the name.

integer

maxStopped

integer

cases

The cases the comparison graded: each correction it checked is a case, and it passes when every repetition did.

object

minPassing

At least this many cases pass.

integer

noNewFailures

boolean

approvals

A passing pin waits for a reviewer.

object

role

Default senior.

string

Allowed values: standard senior admin

separateApprover

Default true.

boolean

onlyExpertGroups

Only expert groups count: the comparison must be weighted experts-only, so a group anyone may assert can’t move the gate.

boolean

description

string

createdAt

required

string format: date-time

unregisteredAt

Present only on an unregistered version: a retired gate (every version unregistered) as GET /v1/release-gates?includeRetired=true lists it.

string format: date-time

Example

{
  "scope": {
    "kind": "tenant"
  },
  "spec": {
    "metrics": [
      {
        "name": "passRate"
      }
    ],
    "approvals": {
      "role": "standard"
    }
  }
}

400

Validation failed (see details.issues).

application/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.

application/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

release-gate-already-registered: that (id, version) exists. release-gate-scope-taken: another release gate gates the agent for the scope (details.heldBy). release-gate-scope-changed: the version would change the agent or scope. release-gate-scope-unpinned: the scope has no pinned version of its own; a gated scope holds its own pin (a pin above it is not enough, since a pin there would change this scope ungated), so pin a version for the scope first.

application/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).

application/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).

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

503

The Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.

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

Publish a release gate

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Examplegenerated

401

Examplegenerated

409

Examplegenerated

413

Examplegenerated

500

Examplegenerated

503

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated