Skip to main content

スケジュールを作成する

繰り返し実行または手動トリガーの Template 実行設定を作成します。

POST /api/v1/forward/schedules 1 つの Identity、1 つの Template、初期入力イベント、トリガーポリシー、実行ポリシーを束ねる Schedule を作成します。各トリガーは個別の Schedule Run を作成します。 本ページは HTTP 直接作成インターフェイスを説明します。Session 経由で create_forward_schedule を呼び出す場合のエラーコードと応答構造は、自然言語による作成失敗とエラーコードを参照してください。

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT または SAT>
Content-TypeYesapplication/json
Idempotency-KeyNo安全でないリクエスト向けの任意のべき等キー。

Body parameters

ParameterTypeRequiredDescription
identity_idstringYesSchedule を所有する Forward Identity ID。
template_idstringYes実行する Forward Template ID。
namestringYesSchedule 名。
descriptionstringNoSchedule の説明。
initial_eventsarrayYes各実行時に注入されるイベント。現在の設計では user.message をサポートします。
resourcesarray|nullいいえSchedule 専用ファイル。最大 100 件。省略、null、[] は専用ファイルを設定しません。構造はファイルリソースを参照してください。
executionobjectNo実行ポリシー。省略時はデフォルトが適用されます。
trigger_policyobject|nullNoトリガーポリシー。省略または null の場合は {"type":"manual"} になります。
environment_idstringYes実行環境。
sinksarray|nullNo実行結果の配信先。互換性のため配列形式を維持し、現在は最大 1 件を指定できます。
metadataobjectNoラベルまたはパススルーデータ専用のカスタムメタデータ。

Trigger policy

trigger_policy は型付きオブジェクトです。作成および更新リクエストでは、設定フィールドである type、expression、timezone のみを受け付けます。upcoming_runs_at と last_run_at は Forward が算出するレスポンス専用フィールドです。
FieldTypeRequiredDescription
typestringYescron、once、interval、または manual。
expressionstringConditionalトリガー式。cron、once、interval では必須。manual では不要です。
timezonestringConditionalAsia/Shanghai などの IANA タイムゾーン。cron では必須。once では expression にオフセットがない場合のみ必須。interval と manual では任意です。
upcoming_runs_atarrayResponse onlyUTC ISO 8601 形式の今後のトリガー時刻。現在の実装では [] または次回の予定時刻のみを返します。
last_run_atstring|nullResponse only直近のトリガー時刻。
typeRequired inputDescription
crontype, expression, timezone指定した IANA タイムゾーンで 5 フィールドの cron 式に従って繰り返します。
oncetype, expression, optional timezoneISO 8601 時刻に 1 回実行します。式にオフセットがない場合は timezone が必須です。
intervaltype, expressionPT15M などの ISO 8601 期間に従って繰り返します。
manualtype自動的には実行されません。Run Schedule エンドポイントでトリガーします。
typeexpression formatExampleNotes
cron標準の 5 フィールド cron0 9 * * *分単位のカレンダースケジュール。秒および 6 フィールドの cron はサポートされません。
onceISO 8601 絶対時刻2026-06-23T09:00:00 または 2026-06-23T01:00:00Z対象時刻はサーバーの現在時刻より後である必要があります。1 回限りのタスクには 1 分の最小間隔制限はありません。
intervalISO 8601 期間PT15M、PT1H、P1D固定間隔スケジュール。最小間隔は 1 分です。
manual省略または空-スケジュール実行を作成しません。

Execution policy

FieldTypeDefaultDescription
session_modestringnew_sessionnew_session または reuse_session。
max_concurrent_runsinteger1この Schedule の最大同時実行数。
max_attemptsinteger1単一 Run の実際の試行回数上限。許容値は 1 または 2。範囲外の値は拒否されます。
timeout_msinteger3000001 回の試行のタイムアウト。
session_modeDescription
new_sessionトリガーごとに新しい実行 Session を作成します。以前のコンテキストは再利用されません。
reuse_sessionForward がこの Schedule 用に固定された 1 つの実行 Session を管理し、トリガー間で再利用します。呼び出し側が任意の既存 session_id を指定することはできません。
max_attempts=2 は、同一の Schedule Run が最初の実行に失敗した後、サーバーが自動的に最大1回再試行することを意味します。再試行されるかどうかはサーバーが失敗タイプに基づいて判断します。パラメータエラー、権限エラー、同時実行制限、タイムアウト、接続中断などのシナリオでは再試行が保証されません。クライアントは Schedule Run の attempt フィールドで実際の試行回数を確認できます。 作成時に execution.max_attempts を省略するとデフォルト値 1 が使用されます。明示的に指定する場合、整数 1 または 2 のみ受け付けます。

ファイルリソース

まず File をアップロードして file_id を取得し、resources で参照します。各要素には type: "file" と file_id が必須で、mount_path は任意です。パスを省略すると /data/workspace/<filename> を使用し、同じファイルをすでに継承している場合はそのパスを使用します。現在の呼び出し元がアクセスできる Forward File として登録済みである必要があります。 Schedule ファイルは Template / Identity Config のファイルとマージされ、new_session と reuse_session の両方をサポートします。パラメーターの制限、パスの競合、適用タイミング、削除制限はファイルリソースを参照してください。HTTP API による Schedule の設定・実行に、自然言語 Schedule 管理ツールの有効化は必要ありません。

配信先

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": "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

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

Errors

HTTPTypeCode発生条件
400invalid_request_errorinvalid_trigger_policyトリガーポリシーの種類または式が不正です。
400invalid_request_errortrigger_policy_too_frequentトリガーの粒度が 1 分未満です。
400invalid_request_errortrigger_policy_time_too_soononce の対象時刻または指定した stop_at がサーバーの現在時刻以前です。
400invalid_request_errorinvalid_requesttemplate_id、name、environment_id のいずれかが未指定、名前・説明・初期イベント・実行ポリシーが不正、文字列に未対応の制御文字が含まれる、Template / Environment が存在しない・アクセス不可・利用できない状態です。または、ファイル数が上限を超える、ID / マウントパスが不正、ID / 明示的なパスが重複する、参照ファイルが存在しない・アクセス不可・File ではありません。
400invalid_request_errorinvalid_request_bodyリクエストボディが空、JSON 構文またはフィールドの型が不正、resources の構造またはフィールドの型が不正、要素に未知のフィールド(enabled など)が含まれる、またはトップレベルの files が指定されています。
400invalid_request_errorunsupported_sinks_inputsinks の数・型・フィールドが不正、または固定 Channel が利用不可、所有者が一致しない、もしくは実行コンテキストが一致しません。
400invalid_request_errorinvalid_identityidentity_id が未指定、または Identity が存在しない、アクセスできない、もしくは無効化されています。
401authentication_error-PAT または SAT が無効または期限切れです。
403permission_erroridentity_mismatchIdentity-bound SAT が、バインドされた Identity 以外の Schedule を要求または操作しています。

Notes

  • レスポンスの initial_events_version はサーバーが管理する読み取り専用の入力バージョンで、作成時は 1 です。入力バージョンを参照してください。
  • レスポンスの resources はSchedule 自身のファイル設定のみを file_id 順で含みます。専用ファイルがなければ [] で、継承ファイルは展開しません。
  • sinks を省略、null、または [] にすると、作成された Schedule は sinks: [] を返します。
  • manual スケジュールは POST /api/v1/forward/schedules/{schedule_id}/run でのみトリガーできます。
  • once スケジュールは、最初の予定実行が終了状態に達すると自動的にアーカイブされます。