スケジュールを更新する

POST /api/v1/forward/schedules/{schedule_id} merge-patch セマンティクスを使用します。リクエストに含まれるフィールドは更新され、省略されたフィールドは変更されません。

Headers

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

Path parameters

Parameter	Type	Required	Description
`schedule_id`	string	Yes	Forward Schedule ID。

Body parameters

Parameter	Type	Required	Description
`name`	string	No	新しい Schedule 名。
`description`	string	No	新しい Schedule の説明。
`template_id`	string	No	新しい Forward Template ID。
`initial_events`	array	No	初期イベントリストを置き換えます。
`execution`	object	No	実行ポリシーをマージ更新します。
`trigger_policy`	object\|null	No	トリガーポリシーを更新します。`null` は manual に変更します。
`environment_id`	string	No	新しい実行環境。
`sinks`	array\|null	No	実行結果の配信先。互換性のため配列形式を維持し、現在は最大 1 件を指定できます。
`metadata`	object	No	メタデータをマージ更新します。`null` 値はメタデータキーを削除します。

Trigger policy

trigger_policy は型付きオブジェクトです。作成および更新リクエストでは、設定フィールドである type、expression、timezone のみを受け付けます。null を渡すと Schedule は {"type":"manual"} に変更されます。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

execution はマージ更新されます。省略されたフィールドは現在の値を保持します。

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 を省略、execution=null を渡す、空オブジェクトを渡す、または max_attempts を含まない部分的な execution を渡す場合、現在の max_attempts 値が保持されます。execution.max_attempts=null を明示的に渡すとパラメータ型エラーとして処理され、デフォルト値へのリセットを意味しません。

配信先

sinks は互換性のため配列形式を維持しており、現在は最大 1 件を指定できます。各要素は次の公開形式のいずれかにする必要があります。

{
  "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 にはチャネル固有のユーザーまたはグループの external_id を指定します。thread と topic はサポートしません。チャネルの IM 会話で /target を送信すると、その会話の target 設定を取得できます。 sinks を省略すると現在の値を保持し、null または [] を渡すと削除し、要素を 1 件渡すと置換します。配信失敗は対応する Run の push_status に記録されます。

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/sched_019f00112233445566778899aabbccdd' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Weekday tech brief",
  "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",
  "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 * * 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

更新後の Schedule オブジェクトを返します。

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	`invalid_trigger_policy`	トリガーポリシーが無効です。
400	`invalid_request_error`	`invalid_request`	`execution.max_attempts` が `1..2` の範囲外。
400	`invalid_request_error`	`unsupported_sinks_input`	`sinks` の件数、型、またはフィールドが無効か、fixed Channel が利用不可、または最終的な Identity/Template と不一致です。
404	`not_found_error`	`schedule_not_found`	Schedule が存在しません。
409	`invalid_request_error`	`schedule_archived`	Schedule はアーカイブ済みです。
401	`authentication_error`	`authentication_required`	PAT または SAT が無効または有効期限切れです。

Notes

sinks を省略すると現在の値を保持し、null または [] を渡すと削除します。これにより、null 許容フィールドのシリアライズに対応します。
reuse_session は Forward がこの Schedule 用に固定された実行 Session を管理することを意味します。呼び出し側が任意の既存 session_id を指定することはできません。

スケジュールを更新する

Headers

Path parameters

Body parameters

Trigger policy

Execution policy

配信先

Pair モードの配信

Example request

Example response

Response fields

Errors

Notes

スケジュールを取得する

スケジュールを一時停止する

​Headers

​Path parameters

​Body parameters

​Trigger policy

​Execution policy

​配信先

​Pair モードの配信

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

スケジュールを取得する

スケジュールを一時停止する

Headers

Path parameters

Body parameters

Trigger policy

Execution policy

配信先

Pair モードの配信

Example request

Example response

Response fields

Errors

Notes

Related