Skip to main content

Update a schedule

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

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key for unsafe requests.

Path parameters

ParameterTypeRequiredDescription
schedule_idstringYesForward Schedule ID.

Body parameters

ParameterTypeRequiredDescription
namestringNoNew Schedule name.
descriptionstringNoNew Schedule description.
template_idstringNoNew Forward Template ID.
initial_eventsarrayNoReplaces the initial event list.
resourcesarray|nullNoSchedule-specific files. Omit to preserve; null or [] clears; an array replaces the entire set. At most 100 files. See File resources for the structure.
executionobjectNoMerge updates the execution policy.
trigger_policyobject|nullNoUpdates the trigger policy. null changes it to manual.
environment_idstringNoNew execution environment.
sinksarray|nullNoDelivery targets for execution results. The array form is retained for compatibility; currently, at most one item is allowed.
metadataobjectNoMerge 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": []
}
Changing 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.
FieldTypeRequiredDescription
typestringYescron, once, interval, or manual.
expressionstringConditionalTrigger expression. Required for cron, once, and interval; not needed for manual.
timezonestringConditionalIANA timezone, such as Asia/Shanghai. Required for cron; required for once only when expression has no offset; optional for interval and manual.
upcoming_runs_atarrayResponse onlyUpcoming trigger times in UTC ISO 8601. The current implementation returns [] or the next scheduled time only.
last_run_atstring|nullResponse onlyMost recent trigger time.
typeRequired inputDescription
crontype, expression, timezoneRepeats by a 5-field cron expression in the given IANA timezone.
oncetype, expression, optional timezoneRuns once at an ISO 8601 time. timezone is required when the expression has no offset.
intervaltype, expressionRepeats by an ISO 8601 duration, such as PT15M.
manualtypeNever runs automatically. Trigger with the Run Schedule endpoint.
typeexpression formatExampleNotes
cronStandard 5-field cron0 9 * * *Minute-level calendar schedule. Seconds and 6-field cron are not supported.
onceISO 8601 absolute time2026-06-23T09:00:00 or 2026-06-23T01:00:00ZThe target time must be later than the server's current time; one-time tasks are exempt from the 1-minute minimum interval.
intervalISO 8601 durationPT15M, PT1H, P1DFixed interval schedule. Minimum interval is one minute.
manualOmitted or empty-Does not create scheduled runs.

Execution policy

execution is merge-updated. Omitted fields keep their current values.
FieldTypeDefaultDescription
session_modestringnew_sessionnew_session or reuse_session.
max_concurrent_runsinteger1Maximum concurrent runs for this Schedule.
max_attemptsinteger1Maximum actual attempts per Run. Allowed values: 1 or 2; values outside this range are rejected.
timeout_msinteger300000Timeout for one attempt.
session_modeDescription
new_sessionCreates a new execution Session for each trigger. Previous context is not reused.
reuse_sessionForward 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.

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:
{
  "sinks": [
    {
      "type": "im_channel",
      "channel_pairing_id": "pair_019eabc123"
    }
  ]
}
Results are sent to the private or group chat bound to that pairing. The Schedule's identity_id and template_id must match the pairing. After the pairing is unbound, delivery to that binding stops.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/schedules/sched_019f00112233445566778899aabbccdd' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Weekday tech brief",
  "resources": [
    {
      "type": "file",
      "file_id": "file_weekday_sources",
      "mount_path": "/data/news-sources.csv"
    }
  ],
  "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",
  "source": "api",
  "source_session_id": null,
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "name": "Weekday tech brief",
  "description": "Generate a daily technology news summary",
  "status": "active",
  "resources": [
    {
      "type": "file",
      "file_id": "file_weekday_sources",
      "mount_path": "/data/news-sources.csv"
    }
  ],
  "initial_events_version": 1,
  "initial_events": [
    {
      "type": "user.message",
      "content": "Read /data/news-sources.csv and 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

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_trigger_policyThe trigger policy is invalid.
400invalid_request_errortrigger_policy_too_frequentThe updated cron trigger granularity or interval is less than 1 minute.
400invalid_request_errortrigger_policy_time_too_soonThe updated once target time or supplied stop_at is not later than the server's current time.
400invalid_request_errorinvalid_requestThe 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.
400invalid_request_errorinvalid_request_bodyThe 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.
400invalid_request_errorunsupported_sinks_inputThe number, type, or fields of sinks are invalid, or a fixed Channel is unavailable or does not match the final Identity/Template.
404not_found_errorschedule_not_foundThe Schedule does not exist or does not belong to the current owner.
409invalid_request_errorschedule_archivedThe Schedule is archived.
401authentication_error-The PAT or SAT is invalid or expired.
403permission_erroridentity_mismatchAn Identity-bound SAT requests or operates on a Schedule outside its bound Identity.

Notes

  • The response field initial_events_version increments only when the normalized initial_events content actually changes. Omitting initial_events or submitting identical content does not increment it. See Input version.
  • Response resources contains only the updated Schedule's own file configuration, sorted by file_id; clearing returns [].
  • Omit sinks to preserve the current value; pass null or [] to clear it, for compatibility with nullable-field serialization.
  • reuse_session means Forward manages a fixed execution Session for this Schedule; callers cannot provide an arbitrary existing session_id.