Manage serving (rollout, status, targeting)

Ramp, pause, resume, roll back or target a release from CI - no dashboard needed. Identified by app + channel + version. The same invariants as the dashboard apply (shared code): the rollout percentage only increases once the release has been offered (422), label targeting only broadens once offered (422), match expressions are frozen once offered (422), and a rolled-back release can never be re-served (409). Applied in order: targets, rollout, status.

Authorization

bearerAuth

AuthorizationBearer <token>

Mint keys from the dashboard (API keys). Shown once, stored hashed.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

app*string

channel*string

version*string

rollout?integer

Range0 <= value <= 100

status?string

paused halts (temporary), published resumes, rolled_back is permanent (serves the fallback below as a downgrade), deprecated marks end of life (not served, reversible; devices still on it receive their next update as required)

Value in

"published"
"paused"
"rolled_back"
"deprecated"

targets?

{ matchLabels: { key: [values] }, matchExpressions: [{ key, operator, values }] }; null clears targeting. Expression keys are label keys or the reserved $version / $platform / $arch fields (resolved from the request itself). Operators: In, NotIn, Exists, DoesNotExist, and VersionGte / VersionLt ($version only, semver-aware). All operators except DoesNotExist fail closed when the key cannot be resolved. Labels may only broaden once the release has been offered; expressions are FROZEN then (422) - cut a new release to change them.

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/releases" \  -H "Content-Type: application/json" \  -d '{    "app": "qsxsicotpbmtf8ag",    "channel": "stable",    "version": "2.1.0",    "rollout": 50  }'

{  "release": {    "app": "qsxsicotpbmtf8ag",    "channel": "stable",    "version": "2.1.0",    "rolloutPct": 50,    "status": "published",    "targets": null  }}

{  "error": "devices.0.version: Invalid version"}

{  "error": "Invalid or revoked API key"}

{  "error": "Unknown app"}

{  "error": "A rolled-back release cannot be re-served"}

{  "error": "2.1.0 has already been offered at 25% - the rollout can only increase now. Pause to stop offering, roll back to pull the release."}

{  "error": "Rate limit exceeded"}

Manage serving (rollout, status, targeting)

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

404application/json

409application/json

422application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`