Update a Forward Schedule.
POST /api/v1/forward/schedules/{schedule_id}
This page describes the HTTP update endpoint. To change a name, execution content, or time rules in a conversation, use natural-language Schedule updates. The tool's instruction and trigger_policy subfield patch semantics are not part of this HTTP request body.
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. |
resources | array|null | No | Schedule-specific files. Omit to preserve; null or [] clears; an array replaces the entire set. At most 100 files. See File resources for the structure. |
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. |
File resources
resources replaces the entire Schedule-specific file configuration; it does not merge by file_id. Omit the field to preserve the current value; pass null or [] to clear it. Each item in a nonempty array requires type: "file" and file_id, with an optional mount_path. Files must first be uploaded, and accessible to the current caller.
For example, to clear dedicated files, send:
resources does not increment initial_events_version or interrupt the current execution. Subsequent executions apply additions, removals, and path changes for the selected files, including synchronization with reuse_session. Clearing does not remove files inherited from the Template / Identity Config. See File resources for details.
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 | The target time must be later than the server's current time; one-time tasks are exempt from the 1-minute minimum interval. |
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:
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.
Pair mode delivery
First pair the channel, then obtain the id of an active record from List channel pairings and configure it as channel_pairing_id in sinks:
identity_id and template_id must match the pairing. After the pairing is unbound, delivery to that binding stops.
Example request
Example response
HTTP 200 OK
Response fields
Returns the updated Schedule object.
Errors
| HTTP | Type | Code | Trigger |
|---|---|---|---|
| 400 | invalid_request_error | invalid_trigger_policy | The trigger policy is invalid. |
| 400 | invalid_request_error | trigger_policy_too_frequent | The updated cron trigger granularity or interval is less than 1 minute. |
| 400 | invalid_request_error | trigger_policy_time_too_soon | The updated once target time or supplied stop_at is not later than the server's current time. |
| 400 | invalid_request_error | invalid_request | The name, description, initial events, or execution policy is invalid; a string contains unsupported control characters; or the new Template / Environment does not exist, is inaccessible, or is in an unavailable state; or the file count exceeds the limit, an ID / mount path is invalid, IDs / explicit paths are duplicated, or a referenced file does not exist, is inaccessible, or is not a File. |
| 400 | invalid_request_error | invalid_request_body | The request body is empty, JSON syntax or a field type is invalid, the resources structure or a field type is invalid, an item contains an unknown field (such as enabled), or top-level files is supplied. |
| 400 | invalid_request_error | unsupported_sinks_input | The number, type, or fields of sinks are invalid, or a fixed Channel is unavailable or does not match the final Identity/Template. |
| 404 | not_found_error | schedule_not_found | The Schedule does not exist or does not belong to the current owner. |
| 409 | invalid_request_error | schedule_archived | The Schedule is archived. |
| 401 | authentication_error | - | The PAT or SAT is invalid or expired. |
| 403 | permission_error | identity_mismatch | An Identity-bound SAT requests or operates on a Schedule outside its bound Identity. |
Notes
- The response field
initial_events_versionincrements only when the normalizedinitial_eventscontent actually changes. Omittinginitial_eventsor submitting identical content does not increment it. See Input version. - Response
resourcescontains only the updated Schedule's own file configuration, sorted byfile_id; clearing returns[]. - Omit
sinksto preserve the current value; passnullor[]to clear it, for compatibility with nullable-field serialization. reuse_sessionmeans Forward manages a fixed execution Session for this Schedule; callers cannot provide an arbitrary existingsession_id.