Create a schedule

POST /api/v1/forward/schedules Creates a Schedule that binds one Identity, one Template, initial input events, trigger policy, and execution policy. Each trigger creates a separate Schedule Run.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Optional idempotency key for unsafe requests.

Body parameters

Parameter	Type	Required	Description
`identity_id`	string	Yes	Forward Identity ID that owns the Schedule.
`template_id`	string	Yes	Forward Template ID to execute.
`name`	string	Yes	Schedule name.
`description`	string	No	Schedule description.
`initial_events`	array	Yes	Events injected at each execution. Current design supports `user.message`.
`execution`	object	No	Execution policy. Defaults are applied when omitted.
`trigger_policy`	object\|null	No	Trigger policy. Omitted or `null` becomes `{"type":"manual"}`.
`environment_id`	string	Yes	Execution environment.
`sinks`	array\|null	No	Up to one Pairing Sink. Omitted, `null`, or `[]` means no Sink.
`metadata`	object	No	Custom metadata for labels or pass-through data only.

Trigger policy

trigger_policy is a typed object. Create and update requests accept only configuration fields: type, expression, and timezone. upcoming_runs_at and last_run_at are response-only fields computed by Forward.

Field	Type	Required	Description
`type`	string	Yes	`cron`, `once`, `interval`, or `manual`.
`expression`	string	Conditional	Trigger expression. Required for `cron`, `once`, and `interval`; not needed for `manual`.
`timezone`	string	Conditional	IANA timezone, such as `Asia/Shanghai`. Required for `cron`; required for `once` only when `expression` has no offset; optional for `interval` and `manual`.
`upcoming_runs_at`	array	Response only	Upcoming trigger times in UTC ISO 8601. The current implementation returns `[]` or the next scheduled time only.
`last_run_at`	string\|null	Response only	Most recent trigger time.

`type`	Required input	Description
`cron`	`type`, `expression`, `timezone`	Repeats by a 5-field cron expression in the given IANA timezone.
`once`	`type`, `expression`, optional `timezone`	Runs once at an ISO 8601 time. `timezone` is required when the expression has no offset.
`interval`	`type`, `expression`	Repeats by an ISO 8601 duration, such as `PT15M`.
`manual`	`type`	Never runs automatically. Trigger with the Run Schedule endpoint.

`type`	`expression` format	Example	Notes
`cron`	Standard 5-field cron	`0 9 * * *`	Minute-level calendar schedule. Seconds and 6-field cron are not supported.
`once`	ISO 8601 absolute time	`2026-06-23T09:00:00` or `2026-06-23T01:00:00Z`	Runs once. The target time must be at least one minute in the future.
`interval`	ISO 8601 duration	`PT15M`, `PT1H`, `P1D`	Fixed interval schedule. Minimum interval is one minute.
`manual`	Omitted or empty	-	Does not create scheduled runs.

Execution policy

Field	Type	Default	Description
`session_mode`	string	`new_session`	`new_session` or `reuse_session`.
`max_concurrent_runs`	integer	1	Maximum concurrent runs for this Schedule.
`max_attempts`	integer	1	Maximum actual attempts per Run. Allowed values: `1` or `2`; values outside this range are rejected.
`timeout_ms`	integer	300000	Timeout for one attempt.

`session_mode`	Description
`new_session`	Creates a new execution Session for each trigger. Previous context is not reused.
`reuse_session`	Forward manages one fixed execution Session for this Schedule and reuses it across triggers. Callers cannot provide an arbitrary existing `session_id`.

max_attempts=2 means the server may automatically retry once after the first execution fails. Whether a retry actually happens depends on the failure type — parameter errors, permission errors, concurrency limits, timeouts, or connection interruptions are not guaranteed to be retried. Clients can check the attempt field on a Schedule Run to see how many attempts were made. Omitting execution.max_attempts at creation uses the default value 1. When explicitly provided, only integers 1 or 2 are accepted.

IM sink delivery

Use a Pairing ID to configure up to one im_channel Sink:

{
  "sinks": [
    {
      "type": "im_channel",
      "channel_pairing_id": "pair_019eabc123"
    }
  ]
}

Field	Type	Required	Description
`type`	string	Yes	Must be `im_channel`.
`channel_pairing_id`	string	Yes	An active Pairing ID owned by the current user. It must match the Identity and Template in this request.

Callers cannot submit channel_id, channel_type, an external channel user, Conversation, or other raw routing fields. Forward resolves the delivery route through the Pairing, and public responses return only type and channel_pairing_id.

`sinks` shape	Result
Omitted, `null`, or `[]`	Creates a Schedule without an explicit Sink and returns `[]`.
One valid Pairing Sink	Stores and returns the normalized Pairing Sink.
More than one item, invalid fields or type, or an unavailable Pairing	Returns `400 invalid_request_error / unsupported_sinks_input` without creating the Schedule.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/schedules' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "name": "Daily tech brief",
  "description": "Generate a daily technology news summary",
  "initial_events": [
    {
      "type": "user.message",
      "content": "Summarize current technology news in five bullet points."
    }
  ],
  "trigger_policy": {
    "type": "cron",
    "expression": "0 9 * * *",
    "timezone": "Asia/Shanghai"
  },
  "execution": {
    "session_mode": "new_session",
    "max_concurrent_runs": 1,
    "max_attempts": 2,
    "timeout_ms": 300000
  },
  "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
  "sinks": [
    {
      "type": "im_channel",
      "channel_pairing_id": "pair_019eabc123"
    }
  ]
}'

Example response

HTTP 200 OK

{
  "id": "sched_019f00112233445566778899aabbccdd",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "name": "Daily tech brief",
  "description": "Generate a daily technology news summary",
  "status": "active",
  "initial_events": [
    {
      "type": "user.message",
      "content": "Summarize current technology news in five bullet points."
    }
  ],
  "execution": {
    "session_mode": "new_session",
    "max_concurrent_runs": 1,
    "max_attempts": 2,
    "timeout_ms": 300000
  },
  "trigger_policy": {
    "type": "cron",
    "expression": "0 9 * * *",
    "timezone": "Asia/Shanghai",
    "upcoming_runs_at": [
      "2026-06-23T01:00:00Z"
    ]
  },
  "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
  "sinks": [
    {
      "type": "im_channel",
      "channel_pairing_id": "pair_019eabc123"
    }
  ],
  "metadata": {},
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T10:00:00Z"
}

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	`invalid_trigger_policy`	Trigger policy type or expression is invalid.
400	`invalid_request_error`	`trigger_policy_too_frequent`	Trigger interval is less than one minute.
400	`invalid_request_error`	`trigger_policy_time_too_soon`	`once` target time is too soon.
400	`invalid_request_error`	`invalid_request`	`execution.max_attempts` is not in the `1..2` range.
400	`invalid_request_error`	`unsupported_sinks_input`	Request body contains `sinks`.
404	`not_found_error`	`identity_not_found`	Identity does not exist.
404	`not_found_error`	`template_not_found`	Template does not exist.
401	`authentication_error`	`authentication_required`	The PAT or SAT is invalid or expired.

Notes

HTTP create requests do not accept sinks. Direct API-created schedules return sinks: [].
manual schedules can only be triggered with POST /api/v1/forward/schedules/{schedule_id}/run.
once schedules are automatically archived after their first scheduled run reaches a terminal state.

Create a schedule

Headers

Body parameters

Trigger policy

Execution policy

IM sink delivery

Example request

Example response

Errors

Notes

Run a schedule

List schedules

​Headers

​Body parameters

​Trigger policy

​Execution policy

​IM sink delivery

​Example request

​Example response

​Errors

​Notes

​Related

Run a schedule

List schedules

Headers

Body parameters

Trigger policy

Execution policy

IM sink delivery

Example request

Example response

Errors

Notes

Related