Skip to main content
POST
Publish an agent
A publish puts the whole draft live, not only the guidelines. Any unpublished change made in Studio goes live with it. If other people edit the agent, check Review Changes in Studio, or needs_publish from Get guidelines, before you publish.

Update and Publish Guidelines

1

Replace the guidelines

Send the new text with Replace guidelines. It saves to the draft.
2

Publish

Call this endpoint. It answers 202 straight away with the new version’s version_id and number, and a poll_url.
3

Wait for it to finish

Call the poll_url every few seconds until status is published or failed. A publish that makes no progress for about 15 minutes is ended and reads failed. See Get publish status.
4

Check what's live

Once it is published, new phone calls, website chats and emails use the new version, and each of them records its version_id in interaction.AGENT_VERSION_ID. Get live version tells you which version is live.
  • Nothing to publish. If the draft is the same as the live version, you get a 400 naming the live version, and no version is created.
  • One publish at a time. A publish started while another is running gets a 409 with the running one’s poll_url. Wait for that publish to finish, then call this endpoint again: a publish includes only what was saved before it started, so a change saved while it ran is still waiting. If nothing is left to publish, you get the 400.
  • A failed publish changes nothing. What was live stays live, the new version is never created and its number is skipped.
  • It’s recorded. The publish appears in Audit Logs with the key’s creator as the Actor, and the new version appears in Version History in Studio.
  • Going back is in Studio. To put an earlier version live again, use Make this version active in Studio.

Authorizations

X-API-Key
string
header
required

An API key from Manage → API Keys in Studio. See Authentication.

Path Parameters

assistantId
string<uuid>
required

The agent's ID. Open the agent in Studio and select Copy ID in its header.

Body

application/json
version_name
string | null

A name for the version this publish creates, shown in Version History, up to 120 characters once spaces at the start and end are removed. Leave it out, or send null, an empty string or only spaces, and Studio shows Version N. This is the only field accepted; any other field returns a 400.

Maximum string length: 120

Response

The publish started.

success
boolean
required
data
object
required