Tsumugi

外観

REST API ​

authを設定すると/api以下が有効になります。設定していない場合はすべて404です。

認証は/api/*にのみ適用されます。
HTML自体はデータを含まないため未認証でも返します。ダッシュボードはこの状態でトークンの入力欄を表示します。

機械可読な仕様は/api/openapi.jsonが返します。

共通のレスポンス ​

状態意味
401認証に失敗した
501その操作が構成されていない
503構成が完了していない、または一時的に利用できない

503の応答本文には理由が含まれます。
未適用のマイグレーションがある場合は未適用のファイル名が、bindingが不足している場合は不足の一覧が含まれます。
一時的な障害の場合は、時間を置いて再試行してください。

Flowを登録していない構成では、Runの開始と再開と取り消しが501になります。

/api/openapi.jsonは構成が完了していなくても取得可能です。

GET /api/jobs ​

一覧を取得します。

クエリパラメータ ​

名前既定内容
stateなし状態での絞り込み
bindingなしbinding名での絞り込み
idなしジョブIDの完全一致
unique_keyなしuniqueKeyの完全一致
concurrency_keyなしconcurrencyKeyの完全一致
created_fromなしcreated_atの下限。epochミリ秒で、その値を含む
created_toなしcreated_atの上限。epochミリ秒で、その値を含む
limit20最大100
offset0
sortupdated_atupdated_at created_at binding state priority attempts
orderdescascを指定したときだけ昇順

複数の条件を指定した場合は、全てを満たす行のみが返ります。

キーの一致は完全一致のみです。部分一致は索引が利用されず、件数が増えると全表走査になるため受け付けません。

sortとorderに不正な値が来ても400にはせず、既定値を採用します。ダッシュボードの表示が止まらないようにするためです。
期間に数値以外が来た場合も同様に、その条件を無視します。

レスポンス ​

json
{
  "jobs": [
    {
      "id": "MAIL#0:xxxxxxxxxxxxxxxxxxxxxxxx",
      "binding": "MAIL",
      "state": "FAILED",
      "priority": 0,
      "attempts": 3,
      "max_attempts": 3,
      "created_at": 1753000000000,
      "updated_at": 1753000060000,
      "dispatched_at": 1753000030000,
      "retryable": true
    }
  ],
  "total": 1
}

retryableは保持期間から算出した近似値です。
実際の可否は要求の時点で判定され、保持期間を過ぎたジョブへのリトライは410を返します。

GET /api/jobs/:id ​

1件の詳細を取得します。

json
{
  "job": {
    "id": "MAIL#0:xxxxxxxxxxxxxxxxxxxxxxxx",
    "binding": "MAIL",
    "state": "FAILED",
    "payload": "{\"to\":\"a@example.com\"}",
    "result": null,
    "priority": 0,
    "attempts": 3,
    "max_attempts": 3,
    "progress": null,
    "concurrency_key": "domain:example.com",
    "unique_key": null,
    "guarantee": "at-least-once",
    "created_at": 1753000000000,
    "updated_at": 1753000060000,
    "dispatched_at": 1753000030000,
    "run_after": null,
    "expires_at": null,
    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
    "retryable": true,
    "logs": [
      {
        "attempt": 1,
        "timestamp": 1753000011000,
        "message": "Payment requested"
      }
    ],
    "attempts_log": [
      {
        "attempt": 1,
        "state": "FAILED",
        "started_at": 1753000010000,
        "finished_at": 1753000012000,
        "error": "payment failed: 502"
      }
    ]
  }
}

resultはperformの戻り値で、成功時のみ値が含まれます。それ以外はnullです。
run_afterは予約済みジョブの実行予定時刻です。
expires_atは実行開始の期限で、期限を過ぎたジョブは実行されずCANCELLEDになります。at-least-onceの重複配送が期限をまたいだ場合、実行されたジョブがCANCELLEDと記録されることがあります。
attempts_logは新しい試行から順に並びます。
logsは受信順のログで、各項目に試行回数、記録時刻(epochミリ秒)、本文が含まれます。未記録の場合は空配列です。
リトライを含む1ジョブ全体で最新の20件まで保持し、本文はJavaScriptの文字列長で2,000文字が上限です。保存間隔の下限は1,000msです。
traceparentは投入時に指定したトレース情報で、未指定の場合はnullになります。

見つからない場合は404です。

POST /api/jobs ​

ジョブを投入します。

json
{
  "binding": "MAIL",
  "payload": { "to": "a@example.com", "subject": "hi" },
  "maxAttempts": 5,
  "delayMs": 60000,
  "expiresInMs": 600000,
  "priority": 10,
  "concurrencyKey": "domain:example.com",
  "uniqueKey": "mail:a@example.com:hi",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

bindingとpayloadが必須です。
performersにないbindingは受け付けません。投入できても実行時に必ず失敗するためです。

expiresInMsは投入時刻からの相対の期限です。期限を過ぎたジョブは実行されずCANCELLEDになります。

traceparentは任意。本文に指定が無い場合はtraceparentヘッダーを利用し、両方存在する場合は本文を優先します。
採用した値がW3C Trace Contextのversion 00の形式に合わない場合は400を返します。形式の詳細はジョブの投入を参照してください。
指定した値はリトライ時にも保持され、performerのctx.traceparentへ渡されます。

指定できるのは上記の項目のみです。timeoutMsやbackoffなどは指定できず、既定値が使われます。
partitionKeyも指定できないため、分割したbindingへの投入には利用できません。

成功すると201で{ "id": "..." }が返ります。
uniqueKeyが既存のジョブと衝突した場合も201です。新規には作成されず、応答には既存のジョブIDが含まれます。

状態意味
201作成した
400JSONが不正、または検証に失敗した
501投入経路が構成されていない

POST /api/jobs/:id/retry ​

FAILEDかSTALLEDのジョブをSCHEDULEDへ戻します。

状態意味
200受け付けた
400ジョブIDの形式が不正
409現在の状態では受け付けない
410保持期間を過ぎて削除されている

409と410は対処が異なります。409は状態の変化を待って再実行し、410はそのジョブの再開が不可能です。

POST /api/jobs/:id/cancel ​

ジョブを取り消します。対象はSCHEDULEDのジョブのみです。

QUEUED以降は既に実行されている可能性があるため409を返します。

返る状態はretryと同様です。

POST /api/jobs/bulk-retry ​

POST /api/jobs/bulk-cancel ​

複数のジョブをまとめて処理します。対象はIDの列挙か、絞り込み条件のいずれかで指定します。

IDで指定する場合はidsのみを渡します。

json
{ "ids": ["MAIL#0:xxxxxxxxxxxxxxxxxxxxxxxx", "MAIL#0:yyyyyyyyyyyyyyyyyyyyyyyy"] }

条件で指定する場合はidsを省略します。

json
{ "binding": "MAIL", "state": "FAILED", "created_from": 1753000000000, "limit": 200 }
項目必須説明
ids任意ジョブIDの配列。1件以上200件以下
binding任意binding名での絞り込み
state任意操作が受け付ける状態のみ指定できます
unique_key任意完全一致
concurrency_key任意完全一致
created_from任意created_atの下限
created_to任意created_atの上限
limit任意1回で処理する件数。1以上、既定と最大はいずれも200

idsを指定した場合、他の条件は無視されます。

条件で指定しstateを省略した場合、bulk-retryはFAILEDとSTALLED、bulk-cancelはSCHEDULEDを対象とします。
これ以外の状態を指定した場合は400を返します。対象が減らず、繰り返しても終わらないためです。

レスポンス ​

json
{
  "ok": ["MAIL#0:xxxxxxxxxxxxxxxxxxxxxxxx"],
  "failed": [{ "id": "MAIL#0:yyyyyyyyyyyyyyyyyyyyyyyy", "reason": "gone" }],
  "remaining": 320
}

一部が失敗しても全体は200です。全体を失敗にすると、成功した分まで再送されるためです。

reasonは個別のリトライと取り消しが返す理由に対応します。invalid-stateは409、goneは410に相当します。
idsにジョブIDとして不正な値が含まれていた場合、その要素はinvalid-idとしてfailedに含まれます。

remainingは条件で指定した場合に、上限で処理しきれなかった件数です。0になるまで同じ要求を繰り返します。
一覧への反映は数秒遅れるため、この値は見積りです。idsで指定した場合は常に0です。

対象は一覧の条件で選びますが、状態は要求の時点で改めて判定します。
一覧に表示されていても、その時点で条件に合わないジョブはfailedに含まれます。

POST /api/jobs/:id/reschedule ​

予約済みジョブの実行時刻を変更します。対象はSCHEDULEDのジョブのみです。

json
{ "runAt": 1753003600000, "priority": 10 }
項目必須説明
runAt条件絶対時刻。delayMsとは排他
delayMs条件現在時刻からの相対。runAtとは排他
priority任意同時に変更する場合に指定

runAtとdelayMsはどちらか一方が必要です。両方を指定すると400を返します。

ジョブIDは変わりません。取り消して再投入する場合と異なり、uniqueKeyの予約も解放されません。

返る状態はretryと同様です。

GET /api/stats ​

状態別の件数を返します。

json
{
  "byState": { "SCHEDULED": 12, "RUNNING": 3, "COMPLETED": 480, "FAILED": 2 },
  "oldestScheduledMs": 45000
}

oldestScheduledMsは最も古いSCHEDULEDのジョブが投入から待機している時間です。対象が無い場合はnullです。

GET /api/metrics ​

Analytics Engineに書いた時系列から、binding別の失敗率と所要時間を返します。

クエリパラメータ ​

名前既定内容
hours24遡る時間。1以上720以下
bindingなしbinding名での絞り込み

レスポンス ​

json
{
  "hours": 24,
  "bindings": [
    {
      "binding": "MAIL",
      "total": 1200,
      "failed": 18,
      "failureRate": 0.015,
      "avgDurationMs": 820,
      "maxDurationMs": 5400,
      "p95DurationMs": 2100,
      "avgAttempts": 1.04
    }
  ],
  "series": [{ "at": 1753000000000, "total": 50, "failed": 1, "avgDurationMs": 810 }]
}

件数と所要時間はサンプリングの重みを反映して集計するため、サンプリングが有効になった区間でも実際の件数に近い値が返ります。

hoursが範囲外、またはbindingが不正な名前の場合は400になります。
metricsを設定していない構成では501を返します。
Analytics Engineが要求を拒否した場合と応答が無い場合は502を返し、本文に理由が含まれます。

GET /api/diagnostics ​

bindingごとに、実行待ちのジョブが待機している原因を取得します。

json
{
  "shard": 0,
  "bindings": {
    "MAIL": {
      "active": 2,
      "outbox": 0,
      "blocked": { "paused": false, "capacity": true, "tokens": false, "perKey": false, "perKeyTokens": false },
      "policy": {
        "paused": false,
        "concurrency": 100,
        "perKeyConcurrency": 1,
        "rate": null,
        "perKeyRate": null,
        "agingIntervalMs": 60000,
        "reaperGraceMs": 30000
      }
    }
  }
}
項目意味
active実行中の件数
outbox一覧への反映を待っている件数
blocked実行待ちのジョブがどの制約で待機しているかの内訳
policy現在適用されている実行量の設定

blockedの内訳は、pausedが一時停止、capacityが同時実行数、tokensがレート、perKeyがキー単位の同時実行数、perKeyTokensがキー単位のレートに対応します。

対象はshard 0のみです。分割している場合、他のshardは含まれません。

POST /api/bindings/:binding/policy ​

実行量の設定を実行時に変更します。

json
{ "paused": true, "concurrency": 5 }
項目説明
paused投入の一時停止。実行中のジョブの監視は継続します
concurrency同時実行数。0以上の整数
perKeyConcurrencyキー単位の同時実行数。0以上の整数
rate{ tokens, intervalMs }。nullでレート制限を解除します
perKeyRate{ tokens, intervalMs }。キー単位のレート制限。nullで解除します
agingIntervalMsエージングの間隔。nullで無効
reaperGraceMs無応答と判定するまでの猶予。0以上の整数

明示した項目のみが変更されます。省略した項目は変更されません。

成功すると、変更後の設定と適用したshard数が返ります。

json
{
  "binding": "MAIL",
  "shards": 1,
  "policy": {
    "paused": true,
    "concurrency": 5,
    "perKeyConcurrency": 1,
    "rate": null,
    "perKeyRate": null,
    "agingIntervalMs": 60000,
    "reaperGraceMs": 30000
  }
}

変更はbindingのすべてのshardへ適用されます。

分割している場合、一部のshardにのみ適用されることがあります。
その場合は500になり、適用されなかったshardの番号が応答に含まれます。

json
{ "error": "the change reached 3 of 4 shards, send the same request again", "binding": "MAIL", "shards": 4, "failed": [2] }

同じ要求を繰り返し送っても結果は変わりません。

この変更はbindingsの静的な設定より優先され、以降の投入では静的な設定が無視されます。

POST /api/bindings/:binding/policy/reset ​

実行時の変更を捨てて、静的な設定へ戻します。

json
{ "ok": true }

次の投入からbindingsに書いた設定が再び有効となります。

一部のshardにのみ適用された場合は、変更と同じく500とfailedが返ります。

GET /api/schedules ​

定期実行の一覧を取得します。ジョブの一覧と異なり、反映の遅れはありません。

json
{
  "schedules": [
    {
      "name": "nightly",
      "kind": "flow",
      "target": "REPORT",
      "every_ms": null,
      "cron": "0 3 * * *",
      "time_zone": "Asia/Tokyo",
      "overlap": "skip",
      "paused": false,
      "next_run_at": 1767722400000,
      "last_run_at": 1767636000000,
      "last_fired_at": 1767636001200,
      "last_job_id": null,
      "last_run_id": "REPORT:nightly-1767636000000",
      "last_skipped_at": null,
      "skipped_count": 0,
      "last_error": null
    }
  ]
}
項目意味
nameスケジュールの名前。schedulesのキー
kindjobまたはflow
targetbinding名またはFlow名
every_ms固定間隔。cronを指定した場合はnull
croncron式。everyMsを指定した場合はnull
time_zonecronと表示に使うIANAタイムゾーン。固定間隔ではUTC
overlapskipまたはoverlap
paused一時停止中か。停止中は定期の発火なし
next_run_at次回の実行予定
last_run_at直近の発火の予定時刻。一度も発火していない場合はnull
last_fired_at直近の発火の実時刻。last_run_atとの差が遅れ
last_job_id直近の発火で投入したジョブ。kindがflowの場合はnull
last_run_id直近の発火で開始したRun。kindがjobの場合はnull
last_skipped_at直近で発火しなかった時刻。一度も該当がない場合はnull
skipped_count前回が終わっていないために発火しなかった回数
last_error直近の発火が失敗した理由。成功した場合はnull

末尾が_atの項目はエポックミリ秒です。

schedulesを定義していない構成では501になります。詳細は定期実行を参照してください。

POST /api/schedules/:name/pause ​

スケジュールを一時停止します。停止中は定期の発火がありません。

json
{ "ok": true }

停止前の発火で投入済みのジョブには影響しません。

POST /api/schedules/:name/resume ​

一時停止中のスケジュールを再開します。

json
{ "ok": true }

停止中に経過した回はすべて破棄され、次回は再開時点から次の境界になります。

POST /api/schedules/:name/trigger ​

スケジュールを1回だけ即時に発火します。

json
{ "id": "REPORT:nightly-1767650000000-1-manual", "kind": "flow" }

idは投入したジョブのIDまたは開始したRunのIDで、kindはその区別です。

一時停止中でも可能で、overlapの判定は行いません。次回の定期の発火時刻への影響はありません。
発火に失敗した場合は500とエラー詳細が返され、一覧のlast_errorにも同様の内容が記録されます。

これら全ての操作はschedulesを定義していない構成では501になります。

GET /api/bindings ​

投入先の選択肢と絞り込み用のbinding名を返します。

json
{ "bindings": ["CHARGE", "MAIL"] }

一度も実行されていないbindingも含めて、performersに登録された全てのbindingを返します。

GET /api/flows ​

登録済みのFlow名を取得します。

json
{ "flows": ["GREETINGS", "PIPELINE"] }

一度も実行されていないFlowも含めて、flowsに登録された全てのFlow名を取得できます。

GET /api/runs ​

Runの一覧を返します。

クエリパラメータ ​

名前既定説明
stateなしRUNNING COMPLETED FAILED CANCELLED
flowなしFlow名による絞り込み
limit20最大100
offset0ページング

レスポンス ​

json
{
  "runs": [
    {
      "id": "GREETINGS:cl9x0a1b2c3d",
      "flow": "GREETINGS",
      "state": "RUNNING",
      "node_total": 6,
      "node_done": 4,
      "node_failed": 0,
      "created_at": 1767225600000,
      "updated_at": 1767225603000
    }
  ],
  "total": 1
}

GET /api/runs/:id ​

1つのRunと、そのノードを並び順で返します。

json
{
  "run": {
    "id": "GREETINGS:cl9x0a1b2c3d",
    "flow": "GREETINGS",
    "state": "RUNNING",
    "input": "{\"prefix\":\"hello\"}",
    "node_total": 6,
    "node_done": 4,
    "node_failed": 0,
    "created_at": 1767225600000,
    "updated_at": 1767225603000,
    "parent_run_id": null,
    "parent_node_id": null,
    "retryable": false
  },
  "nodes": [
    {
      "id": "greet",
      "binding": "GREET",
      "state": "RUNNING",
      "container": true,
      "parent": null,
      "origin": "static",
      "after": ["list"],
      "job_id": null,
      "child_run_id": null,
      "result": null,
      "error": null,
      "position": 1,
      "created_at": 1767225600000,
      "updated_at": 1767225603000
    }
  ]
}

containerはfan-outノードを示します。ジョブを持たないのでjob_idはnullで、resultには子ノードの集計値が含まれます。
parentを持つノードは実行時に追加されたノードで、originはfanOutまたはspawnになります。
subflowとして起動されたRunでは、parent_run_idとparent_node_idに親のRunとノードのIDが含まれます。
subflowのノードでは、起動した子のrunIdがchild_run_idに含まれます。

POST /api/runs ​

Runを開始します。

json
{ "flow": "GREETINGS", "input": { "prefix": "hello" }, "id": "order-1234" }
項目必須説明
flow必須登録済みのFlow名。未登録は400
input必須任意のJSON。型検査は適用されません
id任意runIdのローカル部。同じIDの2回目は既存のrunIdを返します
deadlineMs任意Run全体の期限(ミリ秒)。正の整数。超過したRunは中断されFAILEDになります。Flow定義の期限より優先されます

成功すると201でrunIdが返ります。

json
{ "id": "GREETINGS:order-1234" }

POST /api/runs/:id/retry ​

失敗したRunを再開します。
完了したノードの結果はそのまま使われ、FAILED STALLED SKIPPED CANCELLEDのノードは未実行の状態に戻り、改めて実行されます。

再開できるのはFAILEDのRunのみです。それ以外は409、保持期間を過ぎたRunは410になります。
runIdの形式が不正な場合は400です。

POST /api/runs/:id/cancel ​

未実行のノードを停止します。実行中のジョブは停止しないので、それらが終わるまで待ちます。

取り消しできるのはRUNNINGのRunのみです。それ以外は409になります。
runIdの形式が不正な場合は400です。

GET /api/openapi.json ​

OpenAPI 3.1の定義を返します。全エンドポイントのパラメータと応答の形を記述したものです。

Copyright © 2026 chan-mai All Rights Reserved.