Skip to navigation
Runtype APIAgent Aliases

Replace the secret bindings of a release alias

Replace the complete set of {{secret:NAME}} values executions resolve when they reach this agent through this pointer. A binding wins over the organization secret of the same name, so one preview per pull request can aim its HTTP tools at that pull request environment while the version content stays byte-identical to what live runs. Whole-set replacement: a name you stop sending stops resolving. Values are encrypted at rest and never returned. Names beginning RUNTYPE_, PLATFORM_, CLOUDFLARE_ or INTERNAL_ are refused because they are platform-resolved before the alias plane. A change bumps the alias revision and appends a bind receipt; an identical set writes nothing. Requires the same deploy scope as activating this alias.

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.
bindingsmap from strings to stringsRequired
The complete binding set, NAME to value. An empty object clears every binding.
reasonstringOptional<=2000 characters
Why this binding write happened, recorded on the receipt for humans.

Response

Bindings replaced
aliasstring
nameslist of strings
revisiondouble
changedbooleanOptional

Present on a write: false when the set was already identical and nothing moved.

receiptIdstring or nullOptional

The bind receipt this write appended, or null when it changed nothing.

Errors

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