Copy

POST /api/v1/forward/schedules 1 つの Identity、1 つの Template、初期入力イベント、トリガーポリシー、実行ポリシーを束ねる Schedule を作成します。各トリガーは個別の Schedule Run を作成します。

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT または SAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	安全でないリクエスト向けの任意のべき等キー。

Body parameters

Parameter	Type	Required	Description
`identity_id`	string	Yes	Schedule を所有する Forward Identity ID。
`template_id`	string	Yes	実行する Forward Template ID。
`name`	string	Yes	Schedule 名。
`description`	string	No	Schedule の説明。
`initial_events`	array	Yes	各実行時に注入されるイベント。現在の設計では `user.message` をサポートします。
`execution`	object	No	実行ポリシー。省略時はデフォルトが適用されます。
`trigger_policy`	object\|null	No	トリガーポリシー。省略または `null` の場合は `{"type":"manual"}` になります。
`environment_id`	string	Yes	実行環境。
`sinks`	array\|null	No	実行結果の配信先。互換性のため配列形式を維持し、現在は最大 1 件を指定できます。
`metadata`	object	No	ラベルまたはパススルーデータ専用のカスタムメタデータ。

Trigger policy

trigger_policy は型付きオブジェクトです。作成および更新リクエストでは、設定フィールドである type、expression、timezone のみを受け付けます。upcoming_runs_at と last_run_at は Forward が算出するレスポンス専用フィールドです。

Field	Type	Required	Description
`type`	string	Yes	`cron`、`once`、`interval`、または `manual`。
`expression`	string	Conditional	トリガー式。`cron`、`once`、`interval` では必須。`manual` では不要です。
`timezone`	string	Conditional	`Asia/Shanghai` などの IANA タイムゾーン。`cron` では必須。`once` では `expression` にオフセットがない場合のみ必須。`interval` と `manual` では任意です。
`upcoming_runs_at`	array	Response only	UTC ISO 8601 形式の今後のトリガー時刻。現在の実装では `[]` または次回の予定時刻のみを返します。
`last_run_at`	string\|null	Response only	直近のトリガー時刻。

`type`	Required input	Description
`cron`	`type`, `expression`, `timezone`	指定した IANA タイムゾーンで 5 フィールドの cron 式に従って繰り返します。
`once`	`type`, `expression`, optional `timezone`	ISO 8601 時刻に 1 回実行します。式にオフセットがない場合は `timezone` が必須です。
`interval`	`type`, `expression`	`PT15M` などの ISO 8601 期間に従って繰り返します。
`manual`	`type`	自動的には実行されません。Run Schedule エンドポイントでトリガーします。

`type`	`expression` format	Example	Notes
`cron`	標準の 5 フィールド cron	`0 9 * * *`	分単位のカレンダースケジュール。秒および 6 フィールドの cron はサポートされません。
`once`	ISO 8601 絶対時刻	`2026-06-23T09:00:00` または `2026-06-23T01:00:00Z`	1 回実行します。対象時刻は少なくとも 1 分先である必要があります。
`interval`	ISO 8601 期間	`PT15M`、`PT1H`、`P1D`	固定間隔スケジュール。最小間隔は 1 分です。
`manual`	省略または空	-	スケジュール実行を作成しません。

Execution policy

Field	Type	Default	Description
`session_mode`	string	`new_session`	`new_session` または `reuse_session`。
`max_concurrent_runs`	integer	1	この Schedule の最大同時実行数。
`max_attempts`	integer	1	単一 Run の実際の試行回数上限。許容値は `1` または `2`。範囲外の値は拒否されます。
`timeout_ms`	integer	300000	1 回の試行のタイムアウト。

`session_mode`	Description
`new_session`	トリガーごとに新しい実行 Session を作成します。以前のコンテキストは再利用されません。
`reuse_session`	Forward がこの Schedule 用に固定された 1 つの実行 Session を管理し、トリガー間で再利用します。呼び出し側が任意の既存 `session_id` を指定することはできません。

max_attempts=2 は、同一の Schedule Run が最初の実行に失敗した後、サーバーが自動的に最大1回再試行することを意味します。再試行されるかどうかはサーバーが失敗タイプに基づいて判断します。パラメータエラー、権限エラー、同時実行制限、タイムアウト、接続中断などのシナリオでは再試行が保証されません。クライアントは Schedule Run の attempt フィールドで実際の試行回数を確認できます。作成時に execution.max_attempts を省略するとデフォルト値 1 が使用されます。明示的に指定する場合、整数 1 または 2 のみ受け付けます。

配信先

sinks は互換性のため配列形式を維持しています。省略、null、または [] を指定すると配信先なしで Schedule を作成します。有効な要素を 1 件指定すると配信が設定され、2 件以上を指定すると HTTP 400 unsupported_sinks_input が返されます。各要素は次の公開形式のいずれかを使用します。

{
  "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 はチャネル固有の不透明なユーザー ID またはグループ ID です。Schedule 作成時には到達可能性を確認しません。target.type=group はルートグループのみをサポートし、thread や topic はサポートしません。チャネルの IM 会話で /target を送信すると、その会話の target 設定を取得できます。実行時の配信エラーは対応する Run の push_status=failed に記録され、Agent Run のステータスは変更されません。

Pair モードの配信

まずペアリングを完了し、ペアリングの一覧から状態が active のレコードの id を取得して、sinks の channel_pairing_id に設定します:

{
  "sinks": [
    {
      "type": "im_channel",
      "channel_pairing_id": "pair_019eabc123"
    }
  ]
}

結果は、そのペアリングにバインドされた個人チャットまたはグループチャットに送信されます。Schedule の identity_id と template_id はペアリングと一致する必要があります。ペアリングを解除すると、そのバインディングへの配信は停止します。

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": "Summarize current technology news in five bullet points."
    }
  ],
  "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",
  "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 * * *",
    "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

作成後の完全な Schedule オブジェクトを返します。この API で作成すると source="api"、source_session_id=null になります。共通の意味は作成元を参照してください。

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	`invalid_trigger_policy`	トリガーポリシーの type または expression が無効です。
400	`invalid_request_error`	`trigger_policy_too_frequent`	トリガー間隔が 1 分未満です。
400	`invalid_request_error`	`trigger_policy_time_too_soon`	`once` の対象時刻が近すぎます。
400	`invalid_request_error`	`invalid_request`	`execution.max_attempts` が `1..2` の範囲外。
400	`invalid_request_error`	`unsupported_sinks_input`	`sinks` の件数、型、またはフィールドが無効か、fixed Channel が利用不可、別ユーザー所有、または実行コンテキストと不一致です。
404	`not_found_error`	`identity_not_found`	Identity が存在しません。
404	`not_found_error`	`template_not_found`	Template が存在しません。
401	`authentication_error`	`authentication_required`	PAT または SAT が無効または有効期限切れです。

Notes

sinks を省略、null、または [] にすると、作成された Schedule は sinks: [] を返します。
manual スケジュールは POST /api/v1/forward/schedules/{schedule_id}/run でのみトリガーできます。
once スケジュールは、最初の予定実行が終了状態に達すると自動的にアーカイブされます。

スケジュールを作成する

Headers

Body parameters

Trigger policy

Execution policy

配信先

Pair モードの配信

Example request

Example response

Response fields

Errors

Notes

スケジュールを実行する

スケジュールを一覧表示する

​Headers

​Body parameters

​Trigger policy

​Execution policy

​配信先

​Pair モードの配信

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

スケジュールを実行する

スケジュールを一覧表示する

Headers

Body parameters

Trigger policy

Execution policy

配信先

Pair モードの配信

Example request

Example response

Response fields

Errors

Notes

Related