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

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT>
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.
executionobjectNoMerge updates the execution policy.
trigger_policyobject|nullNoUpdates the trigger policy. null changes it to manual.
environment_idstringNoNew execution environment.
metadataobjectNoMerge 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.
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:00ZRuns once. The target time must be at least one minute in the future.
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_attemptsinteger1Reserved. Current implementation records and validates it but runs once.
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.

​
Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/schedules/sched_019f00112233445566778899aabbccdd' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekday tech brief",
    "trigger_policy": {
      "type": "cron",
      "expression": "0 9 * * 1-5",
      "timezone": "Asia/Shanghai"
    }
  }'

​
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",
  "paused_reason": null,
  "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": 1,
    "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": [],
  "metadata": {},
  "archived_at": null,
  "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_policyTrigger policy is invalid.
400invalid_request_errorunsupported_sinks_inputRequest body contains sinks.
404not_found_errorschedule_not_foundSchedule does not exist.
409invalid_request_errorschedule_archivedSchedule is archived.

​
Notes

  • HTTP update requests do not support updating sinks.
  • reuse_session means Forward manages a fixed execution Session for this Schedule; callers cannot provide an arbitrary existing session_id.

Get a schedule

Pause a schedule