Skip to main content
POST
/
v3
/
agents
/
{agent_key}
/
schedules
curl --request POST \ --url https://api.orq.ai/v3/agents/{agent_key}/schedules \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "agent_tag": "v2", "expression": "0 0 9 * * mon-fri", "payload": { "input": "Generate the morning briefing for {{region}}", "memory_entity_id": "mem_entity_123", "metadata": { "run_source": "daily-briefing" }, "variables": { "region": "EMEA" } }, "type": "cron" } '
{
  "_id": "<string>",
  "agent_key": "<string>",
  "created": "2023-11-07T05:31:56Z",
  "created_by_id": "<string>",
  "expression": "<string>",
  "generation": 123,
  "is_active": true,
  "payload": {
    "input": "<unknown>",
    "memory_entity_id": "<string>",
    "metadata": {},
    "variables": {}
  },
  "trigger_count": 123,
  "updated": "2023-11-07T05:31:56Z",
  "agent_tag": "<string>",
  "last_triggered_at": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.orq.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
agent_key
string
required

The unique routing key of the agent the schedule belongs to.

Body

application/json
​
expression
string
required

Schedule expression. Examples: cron '0 0 9 * * mon-fri' (9am UTC weekdays), interval '@every 1h', once '@at 2026-05-01T09:00:00Z'. Minimum firing cadence is 1 hour for cron and interval.

​
payload
object
required

Invocation payload delivered to the agent on every firing.

​
type
enum<string>
required

Schedule type. cron uses 6-field cron expressions; interval uses @every ; once uses @at .

Available options:
cron,
once,
interval
​
agent_tag
string

Pin this schedule to a specific agent version. Omit to always use the active version.

Response

Schedule created.

​
_id
string
required

ULID identifying this schedule.

​
agent_key
string
required
​
created
string<date-time>
required
​
created_by_id
string
required

ID of the API key that created the schedule.

​
expression
string
required

Cron expression (6-field, seconds required), @every duration, @at RFC3339 timestamp, or a predefined descriptor like @hourly/@daily.

​
generation
integer<int64>
required

Monotonic counter bumped when the schedule's firing cadence changes. Used by the consumer to skip stale in-flight triggers.

​
is_active
boolean
required

Whether the schedule is currently firing. once schedules flip to false automatically after firing.

​
payload
object
required
​
trigger_count
integer<int64>
required

Total firings since creation or last expression/type change.

​
type
enum<string>
required

Schedule type.

Available options:
cron,
once,
interval
​
updated
string<date-time>
required
​
agent_tag
string

Pinned agent version. Omit to always run the agent's current active version.

​
last_triggered_at
string<date-time>

Timestamp of the most recent firing, if any.