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 on the dev timeline and publish it, send version_id to publish an existing version from the dev timeline or an open branch, 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. Publishing does not run or wait for evaluations, and production does not move. Required evaluations are enforced when you promote. To check a version before it reaches staging, start a run with Start Check Run and gate on its result yourself. 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 of this agent to publish without saving anything new. It can be on the dev timeline or on an open branch; a branch version publishes without merging the branch, and the branch stays open. Returns 404 VERSION_NOT_FOUND if the ID is not one of this agent’s versions, and 409 BRANCH_CLOSED if its branch was merged or archived. Ignored when snapshot is present.
string
The branch you are publishing from. Optional. When set, version_id must be a version saved on that branch, or the request returns 404 VERSION_NOT_FOUND. Sending branch_id without version_id returns 400 INVALID_BRANCH. 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 the version to publish (named by version_id, or the newest dev version when the body has neither field) is 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 dev versions, and 409 PUBLISH_IN_PROGRESS when another publish for the same agent is still running; retry after a moment. Publishing an existing version of an agent connected to a GitHub repository returns 409 REPOSITORY_RELEASE_REQUIRED.

Docs for agents: llms.txt