Skip to main content
PATCH
JavaScript
Edit a live schedule: retime it, change what each fire says, or adjust its overlap policy.
Everything on spec is editable: the schedule rules (timezone, calendars, intervals), firstUserMessage, systemPromptData, overlapPolicy, and the pinned variationId. The update merges, so send only what you are changing. The new cadence takes effect from the next computed fire.
state is read-only and not part of spec, so you cannot pause or resume through this endpoint. A PATCH that sets spec.status returns 200 and changes nothing, because no such field exists. Use the :pause and :resume actions.
An archived schedule cannot be updated, a PATCH against one is a 400. Update an active or paused schedule instead.

Create a schedule

Every field you can set here, explained.

Pause a schedule

Change state, which an update cannot.

List schedules

Confirm the new nextFireAt.

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"

agentId
string
required

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

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

id
string
required

Schedule ID. Accepts the canonical as_… form or the external_id:<value> form.

Example:

"as_01HXKD2E5NQM3T9AYWCFMZZZBD"

Body

application/json

Update agent schedule request.

metadata
object

UpdateResourceMetadata contains the user-provided fields for updating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

spec
object

AgentScheduleSpec is the user-provided configuration for a schedule.

updateMask
string<field-mask>

Fields to update.

Response

OK

AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence.

metadata
object
required

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

spec
object
required

AgentScheduleSpec is the user-provided configuration for a schedule.

state
enum<string>
required
read-only

The current lifecycle state of the schedule. Output only. Schedules are created STATE_ACTIVE; use the :pause, :resume, and :archive actions to transition between states.

Available options:
STATE_UNSPECIFIED,
STATE_ACTIVE,
STATE_PAUSED,
STATE_ARCHIVED
info
object

AgentScheduleInfo provides read-only runtime data about a schedule.