Update a schedule

POST /api/v1/forward/schedules/{schedule_id} Uses merge-patch semantics. Fields present in the request are updated; omitted fields remain unchanged.

Headers

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

Path parameters

Parameter	Type	Required	Description
`schedule_id`	string	Yes	Forward Schedule ID.

Body parameters

Parameter	Type	Required	Description
`name`	string	No	New Schedule name.
`description`	string	No	New Schedule description.
`template_id`	string	No	New Forward Template ID.
`initial_events`	array	No	Replaces the initial event list.
`execution`	object	No	Merge updates the execution policy.
`trigger_policy`	object\|null	No	Updates the trigger policy. `null` changes it to manual.
`environment_id`	string	No	New execution environment.
`sinks`	array\|null	No	Delivery targets for execution results. The array form is retained for compatibility; currently, at most one item is allowed.
`metadata`	object	No	Merge updates metadata. `null` values delete metadata keys.

Trigger policy

trigger_policy is a typed object. Create and update requests accept only configuration fields: type, expression, and timezone. Passing null changes the Schedule to {"type":"manual"}. 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

execution is merge-updated. Omitted fields keep their current values.

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, passing execution=null, passing an empty object, or passing a partial execution without max_attempts all preserve the current max_attempts value. Explicitly passing execution.max_attempts=null is treated as a type error and does not reset to default.

Delivery targets

The sinks field retains its array form for compatibility and currently allows at most one item. Each item must use one of these public formats:

{
  "type": "im_channel",
  "channel_id": "channel_xxx",
  "target": {
    "type": "user",
    "external_id": "536769"
  }
}

{
  "type": "im_channel",
  "channel_id": "channel_xxx",
  "target": {
    "type": "group",
    "external_id": "cid_group_123"
  }
}

target uses the channel-native user or group external_id. Threads and topics are not supported. Send /target in a channel IM conversation to obtain the target configuration for that conversation. Omit sinks to preserve its current value, pass null or [] to clear it, or pass one item to replace it. Delivery failures are recorded in the corresponding Run's push_status.

Example request

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/schedules/sched_019f00112233445566778899aabbccdd' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Weekday tech brief",
  "trigger_policy": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "Asia/Shanghai"
  },
  "execution": {
    "max_attempts": 2
  },
  "sinks": [
    {
      "type": "im_channel",
      "channel_id": "channel_xxx",
      "target": {
        "type": "user",
        "external_id": "536769"
      }
    }
  ]
}'

Example response

HTTP 200 OK

{
  "id": "sched_019f00112233445566778899aabbccdd",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "name": "Weekday 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 * * 1-5",
    "timezone": "Asia/Shanghai",
    "upcoming_runs_at": [
      "2026-06-23T01:00:00Z"
    ]
  },
  "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
  "sinks": [
    {
      "type": "im_channel",
      "channel_id": "channel_xxx",
      "target": {
        "type": "user",
        "external_id": "536769"
      }
    }
  ],
  "metadata": {},
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T10:30:00Z"
}

Response fields

Returns the updated Schedule object.

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	`invalid_trigger_policy`	Trigger policy is invalid.
400	`invalid_request_error`	`invalid_request`	`execution.max_attempts` is not in the `1..2` range.
400	`invalid_request_error`	`unsupported_sinks_input`	The number, type, or fields of `sinks` are invalid, or the fixed Channel is unavailable, belongs to another user, or does not match the final execution context.
404	`not_found_error`	`schedule_not_found`	Schedule does not exist.
409	`invalid_request_error`	`schedule_archived`	Schedule is archived.
401	`authentication_error`	`authentication_required`	The PAT is invalid or expired.

Notes

Omit sinks to preserve the current value; pass null or [] to clear it.
reuse_session means Forward manages a fixed execution Session for this Schedule; callers cannot provide an arbitrary existing session_id.

Update a schedule

Headers

Path parameters

Body parameters

Trigger policy

Execution policy

Delivery targets

Example request

Example response

Response fields

Errors

Notes

Get a schedule

Pause a schedule

​Headers

​Path parameters

​Body parameters

​Trigger policy

​Execution policy

​Delivery targets

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

Get a schedule

Pause a schedule

Headers

Path parameters

Body parameters

Trigger policy

Execution policy

Delivery targets

Example request

Example response

Response fields

Errors

Notes

Related