Skip to main content
POST
Publish Agent to Staging

Overview

Moves the agent’s staging pointer. The body picks one of three modes: send snapshot to save a new version and publish it, send version_id to publish an existing dev-timeline version, or send neither to publish the newest saved dev version. A version published for the first time is given a semver using bump; republishing a version that already has one re-records its original number. Move it on to production with Promote Agent to Production. Requires an admin, owner, operator, or prompter role.

Headers

string
required
Your API key for authentication.

Path Parameters

string
required
The agent’s unique identifier.

Body Parameters

object
A full agent configuration to save as a new version and publish, the same object accepted by Create Agent Version. Top-level keys: behavior ({ nodes, edges }), settings (displayName and systemPrompt strings, optional guardrails with at most 5 custom entries), contact (inboundNumbers array), and optional knowledge ({ kbIds: string[] }). Serialized size must not exceed 2 MB. Returns 400 INVALID_SNAPSHOT with one error entry per problem. Custom guardrails require an enterprise plan: a snapshot that adds one on another plan returns 403 ENTERPRISE_REQUIRED. When present, version_id is ignored.
string
ID of an existing version on the agent’s dev timeline to publish without saving anything new. Versions saved on a branch are not accepted; merge the branch first. Returns 404 VERSION_NOT_FOUND if the ID is not on the dev timeline. Ignored when snapshot is present.
string
default:"patch"
Which component to increment when this publish mints a new version number: patch, minor, or major. The increment is applied to the highest number ever minted for the agent, so a first publish yields 0.0.1, 0.1.0, or 1.0.0. Ignored when the version already has a number. Returns 400 INVALID_BUMP for any other value.

Response

Returns 201 on success. Returns 200 instead when version_id names the version already pinned to staging; nothing changes and the current number is returned.
object
The published version, including its full snapshot.
string
The version number recorded on this deployment, for example 1.4.0.
array
The agent’s three environments after the publish. Each has id, env_type (dev, staging, or production), and current_version_id (the pinned version, or null if unpinned).
string[]
Non-blocking advisories about the saved snapshot (for example a transfer step with no target). Only present in snapshot mode and only when there is at least one.
array
Present alongside warnings. Each entry has message and, when the advisory concerns a single step, nodeId.
null | array
null on success, or a list of error objects if the request failed. Returns 404 NOT_FOUND for an unknown agent, 400 NO_VERSIONS when the body has neither snapshot nor version_id and the agent has no saved versions, and 409 PUBLISH_IN_PROGRESS when another publish for the same agent is still running; retry after a moment.

Docs for agents: llms.txt