Skip to navigation
Runtype APIAgent Aliases

Activate a version at a release alias

Aim one alias at one immutable version of the same agent, appending a deployment receipt in the same transaction. Moving an existing live pointer requires the AGENTS:DEPLOY:LIVE scope and an If-Match revision; preview aliases require AGENTS:DEPLOY:PREVIEW. Dependency references the version names are fingerprinted first, and an unresolvable reference refuses the activation. Activating a preview alias renews its 14-day expiry; live never expires.

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.
versionIdstringRequired>=1 character
promotionobjectOptional

Source-organization ids and hashes this version was promoted from, linked on the receipt. Provenance only: it never authorizes anything, and the target credentials alone decide what the activation may do.

reasonstringOptional<=2000 characters

Why this deployment happened, recorded on the receipt for humans. Context only: nothing branches on it.

Response

Alias activated
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
409
Conflict Error
412
Precondition Failed Error
422
Unprocessable Entity Error
428
Precondition Error
500
Internal Server Error