POST /api/v1/forward/schedules
1 つの Identity、1 つの Template、初期入力イベント、トリガーポリシー、実行ポリシーを束ねる Schedule を作成します。各トリガーは個別の Schedule Run を作成します。
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT> |
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 | 実行環境。 |
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 | 予約済み。現在の実装では記録および検証されますが、実行は 1 回のみです。 |
timeout_ms | integer | 300000 | 1 回の試行のタイムアウト。 |
session_mode | Description |
|---|---|
new_session | トリガーごとに新しい実行 Session を作成します。以前のコンテキストは再利用されません。 |
reuse_session | Forward がこの Schedule 用に固定された 1 つの実行 Session を管理し、トリガー間で再利用します。呼び出し側が任意の既存 session_id を指定することはできません。 |
Example request
Example response
HTTP 200 OKErrors
| 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 | unsupported_sinks_input | リクエストボディに sinks が含まれています。 |
| 404 | not_found_error | identity_not_found | Identity が存在しません。 |
| 404 | not_found_error | template_not_found | Template が存在しません。 |
Notes
- HTTP 作成リクエストでは
sinksを受け付けません。API で直接作成したスケジュールはsinks: []を返します。 manualスケジュールはPOST /api/v1/forward/schedules/{schedule_id}/runでのみトリガーできます。onceスケジュールは、最初の予定実行が終了状態に達すると自動的にアーカイブされます。