v1

latestOpenAPI 3.1.02026-07-267154122.0 KB

Scheduled agents

Create a scheduled agent (disabled by default)

Requires workspaceId/name/prompt/cron. Invalid cron → INVALID_CRON / CRON_TOO_FREQUENT.

post/scheduled-agents

Headers

Idempotency-Keystring

Transport-level replay protection — any v2 POST may send it (1–255 printable ASCII characters; UUIDs recommended). The first response for a key is recorded and replayed verbatim for retries with the same key + method/path/body for 24 hours; replayed responses carry the Idempotency-Replay: true response header. Reusing a key with a different request — or retrying while the original is still in flight — returns 409 IDEMPOTENCY_ERROR. 5xx responses are never recorded (the retry re-executes).

Response

The created scheduled agent.

object'scheduled_agent' required

idstring uuid required

workspaceIdstring uuid required

slugstring required

namestring required

descriptionstring nullable required

promptstring required

cronstring required

modelstring nullable required

enabledboolean required

planBlockedboolean required

True when the org cannot currently run scheduled tasks (gated at dispatch).

nextRunAtstring date-time nullable required

lastRunAtstring date-time nullable required

urlstring uri required

handoffobject

Present when planBlocked — points the caller at the upgrade flow.