> ## 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.
# Create schedule
> Creates a schedule that runs the agent on a recurring or one-off cadence. The minimum firing interval is 1 hour for `cron` and `interval`; `once` schedules are exempt.
Schedules run an agent on a recurring or one-off cadence through the same execution path as [`POST /v3/router/responses`](/reference/responses/v3-create-response). Minimum firing interval is 1 hour for `cron` and `interval` types; `once` is exempt.
For a full guide on expressions, payloads, lifecycle, and worked examples see [Agent Schedules](/docs/agents/agent-schedules).
```bash Hourly interval theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/agents/customer_digest/schedules \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "interval",
"expression": "@every 1h",
"payload": {
"input": "Summarize new tickets from the last hour"
}
}'
```
```bash Daily cron theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/agents/ops_digest/schedules \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "cron",
"expression": "0 0 9 * * mon-fri",
"agent_tag": "v2",
"payload": {
"input": "Generate the morning briefing for {{region}}",
"variables": { "region": "EMEA" },
"metadata": { "run_source": "daily-briefing" }
}
}'
```
```bash One-off run theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/agents/support_bot/schedules \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "once",
"expression": "@at 2026-05-01T09:00:00Z",
"payload": {
"input": "Check in on ticket TICKET-123 and post a status update."
}
}'
```
```bash With memory and secret variables theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/agents/knowledge_sync/schedules \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "cron",
"expression": "0 0 3 * * *",
"payload": {
"input": "Sync new rows from {{table}} to the warehouse",
"memory_entity_id": "mem_entity_123",
"variables": {
"table": "orders",
"warehouse_token": { "secret": true, "value": "sk-secret-123" }
}
}
}'
```
```json 201 Created theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"_id": "01KPN29WWKSK0VDPJNTKZPVNRB",
"workspace_id": "cd185327-a8a5-4e55-ac9e-51c8e8b7f0e5",
"agent_key": "customer_digest",
"type": "interval",
"expression": "@every 1h",
"is_active": true,
"generation": 1,
"payload": {
"input": "Summarize new tickets from the last hour"
},
"created_by_id": "apk_01KPM5XHYF7NXZ1S3XK2J8Q4B7",
"created": "2026-04-20T10:00:00Z",
"updated": "2026-04-20T10:00:00Z",
"trigger_count": 0
}
```
```json 400 Sub-hour cadence theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"error": {
"code": "invalid_expression",
"message": "interval duration must be at least 1h0m0s, got: 5m"
}
}
```
```json 404 Agent not found theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"error": {
"code": "agent_not_found",
"message": "agent not found: customer_digest"
}
}
```
## OpenAPI
````yaml post /v3/agents/{agent_key}/schedules
openapi: 3.1.0
info:
title: orq.ai API
version: '2.0'
description: orq.ai API documentation
servers:
- url: https://api.orq.ai
security:
- ApiKey: []
tags:
- name: Guardrail Rules
- name: Policies
- name: Routing Rules
- name: Files
description: File upload and retrieval operations.
- name: FilesService
- name: Projects
description: Projects organize resources within a workspace
- name: ProjectsService
- name: Skills
description: >-
Skills are modular instructions you can use to codify processes and
conventions
- name: SkillsService
- name: Responses
- description: >-
Run agents on a cadence — cron, interval, or one-off. Minimum firing
interval is 1 hour.
name: Agent Schedules
- name: Reporting
description: >-
GenAI reporting API over canonical analytics rollups. Accepts a metric
name, time range, grain, group-by, and filters; returns a typed time
series and optional totals.
- name: ReportingService
description: |-
ReportingService exposes a single QueryReport RPC that maps allowlisted
analytics payloads onto safe rollup queries. Callers never send SQL;
the backend picks the rollup family and grain from the metric
catalogue, the requested range, and the requested grouping.
externalDocs:
url: https://docs.orq.ai
description: orq.ai Documentation
paths:
/v3/agents/{agent_key}/schedules:
post:
tags:
- Agent Schedules
summary: Create schedule
description: >-
Creates a schedule that runs the agent on a recurring or one-off
cadence. The minimum firing interval is 1 hour for `cron` and
`interval`; `once` schedules are exempt.
operationId: create-agent-schedule
parameters:
- description: The unique routing key of the agent the schedule belongs to.
in: path
name: agent_key
required: true
schema:
description: The unique routing key of the agent the schedule belongs to.
type: string
requestBody:
content:
application/json:
examples:
daily_cron:
summary: Daily cron at 9am UTC on weekdays
value:
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
hourly_interval:
summary: Hourly interval (minimum allowed cadence)
value:
expression: '@every 1h'
payload:
input: Summarize new tickets from the last hour
type: interval
once_future_at:
summary: One-off run at a specific time
value:
expression: '@at 2026-05-01T09:00:00Z'
payload:
input: Check in on ticket TICKET-123 and post a status update.
type: once
schema:
additionalProperties: false
properties:
agent_tag:
description: >-
Pin this schedule to a specific agent version. Omit to
always use the active version.
type: string
expression:
description: >-
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.
type: string
payload:
$ref: '#/components/schemas/PublicSchedulePayload'
description: Invocation payload delivered to the agent on every firing.
type:
description: >-
Schedule type. cron uses 6-field cron expressions; interval
uses @every ; once uses @at .
enum:
- cron
- once
- interval
type: string
required:
- type
- expression
- payload
type: object
required: true
responses:
'201':
content:
application/json:
schema:
additionalProperties: false
properties:
_id:
description: ULID identifying this schedule.
type: string
agent_key:
type: string
agent_tag:
description: >-
Pinned agent version. Omit to always run the agent's
current active version.
type: string
created:
format: date-time
type: string
created_by_id:
description: ID of the API key that created the schedule.
type: string
expression:
description: >-
Cron expression (6-field, seconds required), @every
duration, @at RFC3339 timestamp, or a predefined
descriptor like @hourly/@daily.
type: string
generation:
description: >-
Monotonic counter bumped when the schedule's firing
cadence changes. Used by the consumer to skip stale
in-flight triggers.
format: int64
type: integer
is_active:
description: >-
Whether the schedule is currently firing. once schedules
flip to false automatically after firing.
type: boolean
last_triggered_at:
description: Timestamp of the most recent firing, if any.
format: date-time
type: string
payload:
$ref: '#/components/schemas/PublicSchedulePayload'
trigger_count:
description: >-
Total firings since creation or last expression/type
change.
format: int64
type: integer
type:
description: Schedule type.
enum:
- cron
- once
- interval
type: string
updated:
format: date-time
type: string
required:
- _id
- agent_key
- type
- expression
- is_active
- generation
- payload
- created_by_id
- created
- updated
- trigger_count
type: object
description: Schedule created.
'400':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/PublicScheduleErrorDetail'
required:
- error
type: object
description: Invalid schedule type, expression, or sub-hour cadence.
'404':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/PublicScheduleErrorDetail'
required:
- error
type: object
description: Agent (or agent version, when agent_tag is set) not found.
components:
schemas:
PublicSchedulePayload:
additionalProperties: false
properties:
input:
description: >-
Input to pass to the agent on each firing. Same shape as the
Responses API input — a string or an array of input items.
memory_entity_id:
description: Optional memory store entity ID to attach to each run.
type: string
metadata:
additionalProperties: {}
description: >-
Opaque key/value pairs attached to every response generated by this
schedule.
type: object
variables:
additionalProperties: {}
description: >-
Template variables substituted into instructions. Supports secret
values: {"secret": true, "value": "..."}.
type: object
type: object
PublicScheduleErrorDetail:
additionalProperties: false
properties:
code:
description: >-
Stable error code, e.g. invalid_expression, schedule_not_found,
agent_not_found.
type: string
message:
description: Human-readable error description.
type: string
required:
- code
- message
type: object
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: JWT
````