Skip to navigation
Runtype APIAgent Aliases

Roll a release alias back to its previous version

Re-aim an alias at the version recorded as previousVersionId on its most recent pointer-moving receipt, walking steps receipts back. Writes a rollback receipt. Rolling back live follows the same scope and If-Match rules as activation, and restores configuration only: external data and side effects are not rolled back.

Authentication

AuthorizationBearer
API key or Clerk session token

Path parameters

idstringRequired
aliasstringRequired

Headers

if-matchstringOptional

The alias revision this write expects. Required on a live alias that already exists (428 without it) and refused with 412 when the stored revision has moved on. Optional on preview aliases and on the first live deployment, which has no revision yet.

idempotency-keystringOptional<=255 characters
Replay key. Repeating an activation with the same key returns the receipt the first call produced instead of moving the pointer twice.

Request

This endpoint expects an object.
reasonstringOptional<=2000 characters
stepsintegerOptional1-50Defaults to 1

Response

Alias rolled back
aliasstring
bindingNameslist of strings

Per-alias secret binding names in force after this activation. Names only, never values.

changedboolean
receiptIdstring
revisiondouble
versionIdstring
versionNumberdouble or null
_warningslist of stringsOptional

Non-blocking advisories, e.g. SCHEDULE_AGENT_CONFIG_UNSUPPORTED when moving live makes active schedules unrunnable.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
412
Precondition Failed Error
422
Unprocessable Entity Error
428
Precondition Error
500
Internal Server Error