Skip to main content
POST
JavaScript
The reverse of publish. It takes a live agent offline so you can rework it, then publish again.

What it changes

Unpublishing moves the agent from STATE_PUBLISHED back to STATE_DRAFT. From there:
  • New objectives are refused. A create against a draft agent is a 400 ("agent must be published to create an objective"), the same as an agent that never published.
  • Schedules stop firing, but stay STATE_ACTIVE. This is the trap. Unpublishing does not pause the schedules; each fire records a skip instead of creating an objective, while the schedule still reads STATE_ACTIVE. So a schedule that has quietly stopped producing runs usually means its agent is unpublished, not that the schedule is off.
  • In-flight objectives keep running. An objective froze its agent and variation into a configSnapshot at creation, so unpublishing does not touch a run already underway.
Publishing again restores everything: STATE_PUBLISHED, objectives accepted, schedules firing.

Draft, not gone

Unpublish is not archive and not delete. The agent stays in the workspace, keeps its variations, feedback, and schedules, and still shows in the default agent list (which hides only archived agents). It is not runnable until you publish it again. Reach for archive to retire an agent you are done with, and unpublish to pause one you are still working on.

Publish an agent

Move it back to STATE_PUBLISHED so it can run.

Archive an agent

Retire an agent instead of pausing it.

List schedules

The schedules that go quiet while an agent is unpublished.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

id
string
required

Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

Body

application/json

Unpublish agent request

Response

OK

Agent resource

metadata
object
required

Resource metadata

spec
object
required

Agent specification

state
enum<string>
required
read-only

The current lifecycle state of the agent. Output only. Agents are created in STATE_DRAFT; use the :publish, :unpublish, :archive, and :unarchive actions to transition between states.

Available options:
STATE_UNSPECIFIED,
STATE_DRAFT,
STATE_PUBLISHED,
STATE_ARCHIVED
info
object

Agent information