Skip to main content

Create a schedule

Create a repeatable or manually triggered Template execution configuration.

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. This page describes the HTTP direct-creation endpoint. For error codes and response structures when calling create_forward_schedule through a Session, see natural-language creation failures and error codes.

Headers

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

Body parameters

ParameterTypeRequiredDescription
identity_idstringYesForward Identity ID that owns the Schedule.
template_idstringYesForward Template ID to execute.
namestringYesSchedule name.
descriptionstringNoSchedule description.
initial_eventsarrayYesEvents injected at each execution. Current design supports user.message.
resourcesarray|nullNoSchedule-specific files, at most 100. Omitted, null, or [] configures no dedicated files. See File resources for the structure.
executionobjectNoExecution policy. Defaults are applied when omitted.
trigger_policyobject|nullNoTrigger policy. Omitted or null becomes {"type":"manual"}.
environment_idstringYesExecution environment.
sinksarray|nullNoDelivery targets for execution results. The array form is retained for compatibility; currently, at most one item is allowed.
metadataobjectNoCustom metadata for labels or pass-through data only.

File resources

First upload a File to obtain a file_id, then reference it in resources. Each item requires type: "file" and file_id, with an optional mount_path. An omitted path defaults to /data/workspace/<filename>; when the same file is already inherited, its path is reused. The file must be registered as a Forward File accessible to the current caller. Schedule files are merged with Template / Identity Config files, with support for both new_session and reuse_session. See File resources for parameter limits, path conflicts, application timing, and deletion restrictions. Configuring and running a Schedule through the HTTP API does not require enabling the natural-language Schedule managed tools.

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.
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

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.max_attempts at creation uses the default value 1. When explicitly provided, only integers 1 or 2 are accepted.

Delivery target

sinks retains its array form for compatibility. Omitting it, passing null, or passing [] creates a Schedule without a delivery target. One valid item configures delivery. Two or more items return HTTP 400 unsupported_sinks_input. 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"
  }
}
external_id is the channel-native opaque user or group ID. Reachability is not probed when the Schedule is created. target.type=group supports only a root group, not a thread or topic. Send /target in a channel IM conversation to obtain the target configuration for that conversation. Runtime delivery failures are recorded as push_status=failed on the corresponding Run and do not change the Agent Run 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' \
  -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": "Read /data/news-sources.csv and summarize current technology news in five bullet points."
    }
  ],
  "resources": [
    {
      "type": "file",
      "file_id": "file_news_sources",
      "mount_path": "/data/news-sources.csv"
    }
  ],
  "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_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": "Daily tech brief",
  "description": "Generate a daily technology news summary",
  "status": "active",
  "resources": [
    {
      "type": "file",
      "file_id": "file_news_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 * * *",
    "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:00:00Z"
}

Response fields

Returns the complete Schedule object after creation. When created through this endpoint, source="api" and source_session_id=null. See Creation source for shared source semantics.

Errors

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_trigger_policyThe trigger policy type or expression is invalid.
400invalid_request_errortrigger_policy_too_frequentThe trigger granularity is less than 1 minute.
400invalid_request_errortrigger_policy_time_too_soonThe once target time or supplied stop_at is not later than the server's current time.
400invalid_request_errorinvalid_requesttemplate_id, name, or environment_id is missing; the name, description, initial events, or execution policy is invalid; a string contains unsupported control characters; the 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, has mismatched ownership, or does not match the execution context.
400invalid_request_errorinvalid_identityidentity_id is missing, or the Identity does not exist, is inaccessible, or is disabled.
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 is a server-maintained, read-only input version, starting at 1 on creation. See Input version.
  • Response resources contains only the Schedule's own file configuration, sorted by file_id; [] when there are no dedicated files. Inherited files are not expanded.
  • Omitting sinks, passing null, or passing [] returns 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.