> ## 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. ## 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: - description: List models available through the AI Router. name: Models - name: Guardrail Rules - name: Policies - name: Routing Rules - name: API keys description: >- API keys authenticate programmatic access to the workspace. The unified key model exposes opaque tokens, per-domain access grants, and budget / rate-limit constraints (see ADR 0001 and ADR 0002). - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, api-key, provider, and model. A budget is hierarchical and defense-in-depth — every applicable budget is a hard gate, and the most restrictive one wins per dimension (see ADR 0007). - name: Documentation description: >- Search the orq.ai documentation. Proxies the workspace's query to the hosted docs search index. - name: Files description: File upload and retrieval operations. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Projects description: Projects organize resources within a workspace - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - 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. 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 ````