Skip to main content
POST
JavaScript
Every agent is created STATE_DRAFT. A draft agent cannot run an objective, and a schedule pointed at one records a skip instead of firing. Publishing is the single step that turns configuration into something that works.

Two guards, both worth knowing

An agent needs at least one variation. The agent holds a name and a selection mode; every setting that matters (model, prompt, tools, memory) lives on a variation. Publishing without one is a 400:
A draft agent cannot take work. Creating an objective against one is a 400, not a silent queue:
Both errors name their field, so a setup script can tell “I forgot to publish” apart from “I sent a bad ID.”

Publishing is a state, not a snapshot

This is the part that surprises people coming from deploy-style APIs. Publishing does not freeze your configuration. It flips a flag. Edit a published agent, add a variation, change a prompt: the agent stays STATE_PUBLISHED and the change is live on the next objective. There is no republish step, and no draft-versus-live divergence to reconcile. Add a second variation to a published agent and it serves traffic at once. Eight objectives against a VARIATION_SELECTION_MODE_RANDOM agent, immediately after the second variation was created:
No republish was called between creating the variation and running those objectives.
What is frozen is the objective. Each one copies the agent and its selected variation into configSnapshot at creation. Change the prompt afterward and running objectives keep the prompt they started with, while new ones pick up the change. Read configSnapshot.agentVariation to see exactly which variation served a given run.
Publishing twice is a no-op and returns 200, so a setup script can call it unconditionally.

Unpublish returns to draft

There is no separate “unpublished” state. :unpublish puts the agent back in STATE_DRAFT, where it stops accepting objectives:
That makes unpublish the kill switch for an agent misbehaving in production. Running objectives are unaffected, since they carry their own snapshot. New work is refused at the door. Schedules keep their own STATE_ACTIVE while the agent is a draft, and quietly produce nothing. The same 60-second interval schedule, measured either side of a publish:
So a schedule that never produces runs is usually an unpublished agent, not a broken schedule. Nothing on the schedule says so: its state reads STATE_ACTIVE either way, and totalFires does not count the fires it declined.

The lifecycle

archive and unarchive are a separate axis for retiring an agent while keeping its history. delete is permanent and discards the variations’ feedback history, which is why archiving exists.

Create an agent

variationSelectionMode, outputDefinition, and episodic memory.

Create a variation

The thing publish requires at least one of.

Create an objective

Where variationId pins a run to one variation.

Schedule an agent

Why an unpublished agent’s schedule records skips.

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

Publish 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