Publish a gate policy

POST

/v1/gate-policies

const url = 'https://example.com/v1/gate-policies';
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,"suite":{"id":"example","version":"example"}},"evidence":{"minCases":1,"minWeight":1},"metrics":[{"name":"weightedYesShare","k":1,"minCandidate":1,"maxDrop":1}],"replay":{"maxDiverged":1,"maxErrors":1,"maxRefusedWrites":1,"maxStopped":1},"approvals":{"role":"standard","separateApprover":true},"onlyRestrictedClasses":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/gate-policies \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "example", "version": "example", "agentId": "example", "scope": { "kind": "tenant" }, "spec": { "comparison": { "maxAgeHours": 1, "suite": { "id": "example", "version": "example" } }, "evidence": { "minCases": 1, "minWeight": 1 }, "metrics": [ { "name": "weightedYesShare", "k": 1, "minCandidate": 1, "maxDrop": 1 } ], "replay": { "maxDiverged": 1, "maxErrors": 1, "maxRefusedWrites": 1, "maxStopped": 1 }, "approvals": { "role": "standard", "separateApprover": true }, "onlyRestrictedClasses": true }, "description": "example" }'

Registers a gate policy, or a new version of one: what a promotion of agentId for scope must show. One policy per agent and scope: another policy id for a scope that has one is refused with 409 gate-policy-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 gate-policy-scope-changed). The spec is checked strictly: an unknown key is refused (400 validation-failed, details.issues). Needs admin on the tenant: whoever may promote 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 agent’s default for 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 promotion must show. Every part is optional; an empty spec checks nothing. A promotion must name a comparison (evalRunId) exactly when the spec has comparison, evidence, metrics, replay or onlyRestrictedClasses. Unknown keys are refused.

object

comparison

object

maxAgeHours

number

> 0

suite

object

required

string

version

string

evidence

The judged evidence 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: weightedYesShare judgedCoverage 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 live 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

approvals

A passing promotion waits for a reviewer.

object

role

Default senior.

string

Allowed values: standard senior admin

separateApprover

Default true.

boolean

onlyRestrictedClasses

Only restricted judge classes count: the comparison must be weighted restricted-only, so a class anyone may assert can’t move the gate.

boolean

description

string

Responses

201

Gate policy published.

application/json

object

required

string

version

required

string

agentId

required

string

scope

required

One of: discriminator: kind

The agent’s default for 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

suite

object

required

string

version

string

evidence

The judged evidence 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: weightedYesShare judgedCoverage 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 live 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

approvals

A passing promotion waits for a reviewer.

object

role

Default senior.

string

Allowed values: standard senior admin

separateApprover

Default true.

boolean

onlyRestrictedClasses

Only restricted judge classes count: the comparison must be weighted restricted-only, so a class anyone may assert can’t move the gate.

boolean

description

string

createdAt

required

string format: date-time

unregisteredAt

string format: date-time

Example

{
  "scope": {
    "kind": "tenant"
  },
  "spec": {
    "metrics": [
      {
        "name": "weightedYesShare"
      }
    ],
    "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

gate-policy-already-registered: that (id, version) exists. gate-policy-scope-taken: another policy gates the agent for the scope (details.heldBy). gate-policy-scope-changed: the version would change the agent or scope. gate-policy-scope-unpinned: the scope has no live version of its own; a gated scope holds its own pin (a pin above it is not enough, since a promotion 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 gate policy

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