Skip to navigation
Runtype APIAgent Versions

Publish a specific agent version

Apply an immutable version to the live agent row and move the live release alias, in one transaction. Until the omitted-selector cutover this is the writer that changes what actually executes, so it is the verb a live deployment uses; the alias activate route owns preview pointers. Supplying If-Match opts this call into the same protected-live compare-and-swap the alias routes enforce.

Authentication

AuthorizationBearer
API key or Clerk session token

Path parameters

agentIdstringRequired

Headers

if-matchstringOptional

The live alias revision this publish expects. Optional: omitting it keeps the historical last-writer-wins behavior for existing callers. When present and stale, the publish is refused with 412 and nothing is written.

idempotency-keystringOptional<=255 characters
Replay key. Repeating a publish 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
deploymentobjectOptional
onConflictenumOptionalDefaults to error

Use overwrite only after confirming replacement of a code-managed agent.

Allowed values:

Response

Version published
agentIdstring
lastModifiedSourceenum
Allowed values:
messagestring
successboolean
versionIdstring
warningslist of strings
appliedmap from strings to booleansOptional

Which fields of the live agent row this publish wrote. Omitted when an Idempotency-Key replayed an earlier publish, which applies nothing itself and cannot reconstruct what the original wrote.

Errors

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