REST API

auth를 설정하면 Tsumugi는 /api 이하 엔드포인트로 들어오는 요청을 처리합니다.
설정하지 않은 경우 모든 요청에 404로 응답합니다.
인증은 /api/*에만 적용됩니다.
대시보드의 HTML은 작업 데이터를 포함하지 않으므로 인증을 요구하지 않고 제공됩니다.
대시보드는 인증되지 않은 경우 토큰 입력란을 표시합니다.
OpenAPI 정의는 GET /api/openapi.json으로 가져옵니다.

공통 응답

503의 본문에는 이유가 포함됩니다.
적용되지 않은 마이그레이션이 있는 경우 미적용 파일 이름이 본문에 포함됩니다.
binding이 부족한 경우 부족한 binding 목록이 본문에 포함됩니다.
일시적으로 사용할 수 없는 경우에는 잠시 후 다시 시도하세요.

Flow를 등록하지 않은 구성에서는 Run의 시작, 재개, 취소 엔드포인트가 501로 응답합니다.
/api/openapi.json은 구성이 완료되지 않아도 응답합니다.
runId 형식이 올바르지 않으면 /api/runs/:id를 포함한 엔드포인트는 400으로 응답합니다.

작업

GET /api/jobs

작업 목록을 가져옵니다.
응답은 작업 배열과 전체 건수를 포함합니다.

쿼리 파라미터

여러 조건을 지정한 경우 모든 조건을 만족하는 작업이 목록에 포함됩니다.
키 검색은 완전 일치이며 부분 일치는 사용할 수 없습니다.
sort와 order에 올바르지 않은 값을 지정한 경우 400이 아니라 기본 정렬 순서로 응답합니다.
created_from과 created_to에 정수가 아닌 값을 지정한 경우 해당 조건은 무시됩니다.

{
  "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건의 상세 정보를 가져옵니다.
작업을 찾을 수 없는 경우 404로 응답합니다.

{
  "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,
    "cancel_requested_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"
      }
    ]
  }
}

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",
  "partitionKey": "tenant-42",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

binding과 payload는 필수이며, performers에 등록된 binding을 지정합니다.
maxAttempts, delayMs, expiresInMs, priority는 정수로 지정하세요.
위 예시에 없는 항목(timeoutMs, backoff 등)은 무시되며 기본값이 사용됩니다.

expiresInMs는 작업 투입 시각부터 계산한 실행 기한입니다.
기한이 지난 작업은 실행되지 않고 CANCELLED로 전환됩니다.
partitionKey는 shards를 2 이상으로 설정한 binding에서 투입할 shard를 결정하기 위한 키이며, 해당 binding에서는 필수입니다.

traceparent는 선택 사항입니다.
본문에서 지정하지 않으면 traceparent 헤더의 값이 사용되고, 둘 다 지정한 경우 본문의 값이 우선합니다.
값에는 작업 투입에서 설명하는 W3C Trace Context version 00 형식을 사용하세요.
지정한 값은 재시도할 때도 이어지며 performer의 ctx.traceparent로 전달됩니다.

uniqueKey가 기존 작업과 같은 경우에도 201로 응답하며, 새 작업은 만들어지지 않고 본문에는 기존 작업 ID가 포함됩니다.

POST /api/jobs/:id/retry

FAILED 또는 STALLED 상태의 작업을 SCHEDULED 상태로 전환합니다.
보존 기간이 지나 삭제된 작업은 재시도할 수 없습니다.

409인 경우 작업 상태가 바뀐 뒤에 다시 요청하세요.

POST /api/jobs/:id/cancel

작업을 취소합니다.
대상은 SCHEDULED, QUEUED, RUNNING 상태의 작업입니다.

SCHEDULED 작업은 즉시 CANCELLED로 전환됩니다.
QUEUED와 RUNNING 작업은 이미 실행 중일 수 있으므로 취소 요청으로 기록됩니다.
이 경우 응답에 requested: true가 포함됩니다.
작업은 performer가 요청을 확인하고 종료한 경우, 또는 요청 후 reaperGraceMs(기본 30초)가 지나도 결과가 보고되지 않은 경우에 CANCELLED로 전환됩니다.
자세한 내용은 실행 중 취소를 참조하세요.

{ "ok": true, "requested": true }

이미 취소를 요청한 작업에 다시 요청한 경우에도 requested: true로 응답합니다.
종료된 작업에 대한 요청에는 409로 응답합니다.
그 밖의 응답은 retry와 같습니다.

POST /api/jobs/bulk-retry

POST /api/jobs/bulk-cancel

여러 작업을 한꺼번에 재시도하거나 취소합니다.
대상은 작업 ID 배열 또는 필터 조건 중 하나로 지정합니다.

작업 ID로 지정하는 경우 ids를 지정하고, 필터 조건으로 지정하는 경우 ids를 생략합니다.

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

{ "binding": "MAIL", "state": "FAILED", "created_from": 1753000000000, "limit": 200 }

ids를 지정한 경우 다른 조건은 무시됩니다.
created_from, created_to, limit에는 정수를 지정하세요.

조건에서 state를 생략하면 bulk-retry의 대상은 FAILED와 STALLED 작업이고, bulk-cancel의 대상은 SCHEDULED, QUEUED, RUNNING 작업입니다.
이 외의 상태를 지정한 경우 400으로 응답합니다.
bulk-retry에서는 failedRetentionMs가 지난 작업이 대상에서 제외됩니다.
bulk-cancel에서는 이미 취소를 요청한 작업이 CANCELLED로 확정될 때까지 대상에서 제외됩니다.
ids로 작업을 직접 지정한 경우에는 이미 요청한 작업에 다시 요청해도 이중으로 처리되지 않습니다.

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

일부 작업의 처리에 실패한 경우에도 상태 코드는 200입니다.
bulk-cancel에서는 취소 요청으로 기록된 작업도 ok에 포함됩니다.
failed의 reason은 작업별 재시도 및 취소 엔드포인트가 응답하는 오류에 대응합니다.
invalid-state와 gone은 각각 409와 410에 해당합니다.
ids에 작업 ID로 올바르지 않은 값이 포함된 경우 해당 값은 invalid-id로 failed에 포함됩니다.

remaining은 조건으로 지정했을 때 limit을 넘어 처리되지 않은 건수입니다.
0이 될 때까지 같은 요청을 다시 보내세요.
ids로 지정한 경우 remaining은 항상 0입니다.
요청 시점에 조건에 맞지 않는 작업은 목록에 표시되어 있더라도 failed에 포함됩니다.

POST /api/jobs/:id/reschedule

예약한 작업의 실행 시각을 변경합니다.
대상은 SCHEDULED 작업입니다.

{ "runAt": 1753003600000, "priority": 10 }

runAt과 delayMs 중 하나만 지정하세요.
둘 다 지정한 경우와 둘 다 지정하지 않은 경우에는 400으로 응답합니다.
runAt, delayMs, priority는 정수로 지정하세요.

작업 ID는 바뀌지 않습니다.
uniqueKey에 의한 중복 판정도 계속 유지됩니다.
상태 코드는 retry와 같습니다.

집계와 진단

GET /api/stats

상태별 건수를 가져옵니다.

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

oldestScheduledMs는 가장 오래된 SCHEDULED 작업이 투입된 후 경과한 시간을 밀리초로 나타냅니다.
SCHEDULED 작업이 없으면 값은 null입니다.

GET /api/metrics

기록된 메트릭을 바탕으로 binding별 실패율과 소요 시간을 가져옵니다.

쿼리 파라미터

{
  "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로 응답합니다.
502는 메트릭을 가져오지 못한 경우의 응답이며 본문에 이유가 포함됩니다.

GET /api/diagnostics

binding별로 실행 대기 중인 작업이 실행되지 않는 원인을 가져옵니다.
실행 중인 작업의 건수와 현재 실행량 설정도 포함됩니다.

{
  "bindings": {
    "MAIL": {
      "active": 2,
      "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
      }
    }
  }
}

blocked

GET /api/bindings

작업을 투입할 binding 이름 목록을 가져옵니다.
한 번도 실행되지 않은 binding을 포함해 performers에 등록한 모든 binding 이름이 대상입니다.

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

실행량 설정

POST /api/bindings/:binding/policy

실행량 설정을 실행 중에 변경합니다.
변경은 bindings의 설정보다 우선합니다.

{ "paused": true, "concurrency": 5 }

지정한 항목만 변경되고 생략한 항목은 유지됩니다.
성공하면 변경 후 설정과 적용된 shard 수가 응답에 포함됩니다.
다음은 paused와 concurrency를 변경한 경우의 예시입니다.

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

변경은 대상 binding에 속한 모든 shard에 적용됩니다.
shard를 분할한 경우 네트워크 단절이나 일시적인 장애로 일부 shard에 변경을 적용하지 못할 수 있습니다.
이 경우 HTTP 상태 코드 500으로 응답하며 본문에 실패한 shard 번호가 포함됩니다.

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

같은 요청을 다시 보내면 나머지 shard에 변경이 적용됩니다.
몇 번을 보내도 설정 결과는 같습니다.
변경한 뒤에는 bindings의 설정이 적용되지 않습니다.

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

실행 중에 한 변경을 버리고 bindings의 설정으로 되돌립니다.
다음 투입부터 bindings의 설정이 다시 적용됩니다.

{ "ok": true }

일부 shard에 적용하지 못한 경우 policy 변경과 마찬가지로 500으로 응답하며 failed가 본문에 포함됩니다.

정기 실행

schedules를 정의하지 않은 구성에서는 이 섹션의 엔드포인트가 501로 응답합니다.
자세한 내용은 정기 실행을 참조하세요.

GET /api/schedules

정기 실행 목록을 가져옵니다.
작업 목록과 달리 상태가 실시간으로 반영됩니다.

{
  "schedules": [
    {
      "name": "nightly",
      "kind": "flow",
      "target": "REPORT",
      "every_ms": null,
      "cron": "0 3 * * *",
      "time_zone": "Asia/Tokyo",
      "overlap": "skip",
      "paused": false,
      "next_occurrence_at": 1767722400000,
      "last_occurrence_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
    }
  ]
}

이름이 _at으로 끝나는 항목은 epoch 밀리초입니다.

POST /api/schedules/:name/pause

일시 중지 중에는 정기 실행이 이루어지지 않습니다.
중지 전에 투입된 작업은 영향을 받지 않습니다.

{ "ok": true }

POST /api/schedules/:name/resume

일시 중지 중인 스케줄을 재개합니다.
중지 중에 지나간 회차는 실행되지 않습니다.
재개 후 다음 실행은 재개한 시점 이후의 첫 번째 예정 시각입니다.

{ "ok": true }

POST /api/schedules/:name/trigger

스케줄을 즉시 1회 실행합니다.

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

id는 투입한 작업의 ID 또는 시작한 Run의 ID입니다.
kind는 id가 작업과 Run 중 무엇을 가리키는지 나타냅니다.
일시 중지 중에도 실행되며 overlap 판정은 이루어지지 않습니다.
다음 정기 실행 시각은 변경되지 않습니다.
실행에 실패한 경우 500과 오류 상세 정보로 응답합니다.
목록의 last_error 값은 이 오류 상세 정보와 같습니다.

Run

GET /api/flows

등록된 Flow 이름을 가져옵니다.
실행 여부와 관계없이 flows에 등록한 모든 Flow 이름이 대상입니다.

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

GET /api/runs

Run 목록을 가져옵니다.
각 Run에 대해 node의 진행 상황이 포함됩니다.

쿼리 파라미터

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

Run 1건과 해당 Run에 포함된 node를 가져옵니다.
node에는 사전에 정의된 정적 node와 실행 중에 동적으로 추가된 node가 모두 포함됩니다.

{
  "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가 true인 node는 fan-out node입니다.
fan-out node는 작업을 갖지 않으므로 job_id는 null입니다.
result는 자식 node의 집계값을 포함합니다.
parent를 가진 node는 실행 중에 추가된 node입니다.
origin은 fanOut 또는 spawn입니다.
subflow로 시작된 Run에서는 parent_run_id와 parent_node_id에 부모 Run과 node의 ID가 포함됩니다.
subflow node에서는 child_run_id에 시작한 자식 Run의 runId가 포함됩니다.

POST /api/runs

Run을 시작합니다.
요청 본문은 Flow 이름과 입력을 포함한 JSON입니다.

{ "flow": "GREETINGS", "input": { "prefix": "hello" }, "id": "order-1234" }

성공하면 201로 응답하며 본문은 시작한 Run의 runId를 포함합니다.
다음 예시의 runId는 flow와 id로 만들어진 GREETINGS:order-1234입니다.

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

POST /api/runs/:id/retry

실패한 Run을 재개합니다.
완료된 node의 결과는 그대로 이어받습니다.
FAILED, STALLED, SKIPPED, CANCELLED 상태의 node는 미실행 상태로 보고 다시 실행합니다.
fan-out으로 만들어진 자식 node 중 다시 실행되는 것은 Run의 기한이 지나 중단된 자식 node뿐입니다.
실행했다가 실패한 자식 node는 다시 실행하지 않습니다.

재개 대상은 FAILED 상태의 Run뿐입니다.
그 밖의 상태인 Run에는 409로 응답합니다.
존재하지 않는 Run과 보존 기간이 지난 Run에는 410으로 응답합니다.

POST /api/runs/:id/cancel

Run을 취소합니다.
아직 실행되지 않은 node는 시작되지 않으며, 실행 중인 node에는 취소 요청이 전송됩니다.
실행 중인 작업은 강제로 중지되지 않습니다.
Run은 performer가 요청을 확인하고 종료한 경우, 또는 요청 후 reaperGraceMs(기본 30초)가 지나도 결과가 보고되지 않은 경우에 CANCELLED로 전환됩니다.
취소 대상은 RUNNING 상태의 Run뿐입니다.

GET /api/openapi.json

모든 엔드포인트의 파라미터와 응답 형식을 기술한 OpenAPI 3.1 정의를 가져옵니다.