REST API リファレンス

FastAPI が /docs で OpenAPI Swagger UI を、/openapi.json でスキーマを自動配信します。全ての業務エンドポイントは /api/v1/... 配下です (既定 http://localhost:8000)。以下は主要なものです。

システム

ワークロード

ワーカー

この他、worker daemon が使う内部エンドポイント (heartbeat / claim / complete / fail / runs / config poll / admin-cmd) が /api/v1/workers/{id}/... 配下にあります。

Dashboard / Flow

プラグイン

その他

リクエスト/レスポンス例

代表的なボディの形です。正確な全フィールドは /openapi.json が権威です。

ワークロードを作る (POST /workloads)

ボディは WorkloadCreate (未知キーは拒否)。最小構成の例:

curl -X POST http://localhost:8000/api/v1/workloads \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "url-check",
    "name": "URL Check",
    "enabled": true,
    "executor_type": "python_module",
    "executor_config": {
      "source_path": "plugins/url_check",
      "module": "main",
      "init_kwargs": { "timeout_secs": 10 }
    },
    "priority": 100,
    "batch_size": 10,
    "lease_secs": 300,
    "max_attempts": 5
  }'

成功は 201 で作成された workload を返します。slug が既存なら 409 です。

キュー件数を見る (GET /workloads/{slug}/queue)

{ "pending": 3, "claimed": 1, "failed": 0, "total": 4 }

run 履歴を見る (GET /workloads/{slug}/runs)

1件の run は概ね次の形です (成功なら output_json、失敗なら error/stderr が入ります)。

{
  "runs": [
    {
      "run_id": 1287,
      "pk": "https://example.com",
      "attempt": 1,
      "success": true,
      "worker_id": "host-a:12345",
      "started_at": "2026-07-11T09:00:01Z",
      "duration_ms": 83,
      "output_json": { "url": "https://example.com", "status": 200, "bytes": 1256 },
      "stdout": "", "stderr": "", "error": null
    }
  ]
}

典型的な自動化フロー

外部システムから使う場合の定番は「投入 → ポーリング」です。

① POST /workloads/{slug}/tasks/batch   … 対象をまとめて投入
② GET  /workloads/{slug}/queue         … pending が捌けるのを監視
③ GET  /workloads/{slug}/runs?limit=N  … 結果 (output_json) を回収
④ POST /workloads/{slug}/queue/reset-failed … 失敗分をまとめて再試行 (必要なら)

タスク投入例

curl -X POST http://localhost:8000/api/v1/workloads/echo-sample/tasks \
  -H "Content-Type: application/json" \
  -d '{"pk": "task-001", "extra": {"foo": "bar"}}'

バルク投入例

curl -X POST http://localhost:8000/api/v1/workloads/echo-sample/tasks/batch \
  -H "Content-Type: application/json" \
  -d '{"items": [{"pk": "t1"}, {"pk": "t2"}, {"pk": "t3"}]}'