Replay API

Drive persisted replay work over HTTP.

Phase 4 adds a backend contract for replay creation, preview, start, cancellation, and status reads. The API uses the same SQLite job store and replay engine as the CLI, including timestamp-window job creation, replay throttling, derived progress metrics, and running-job cancellation.

Endpoints

• POST /api/jobs
• GET /api/jobs
• GET /api/jobs/:jobId
• GET /api/jobs/:jobId/preview
• POST /api/jobs/:jobId/start
• POST /api/jobs/:jobId/cancel

Create and Preview

curl -X POST http://localhost:3000/api/jobs \
  -H "content-type: application/json" \
  -d '{"source":"orders","destination":"orders-replay","partition":"0","start":"10","end":"25","messages-per-second":"10","job-id":"incident-2026-04-28"}'
curl http://localhost:3000/api/jobs/incident-2026-04-28/preview

Create From Time Window

curl -X POST http://localhost:3000/api/jobs \
  -H "content-type: application/json" \
  -d '{"source":"orders","destination":"orders-replay","partition":"0","start-timestamp":"2026-04-28T14:03:00.000Z","end-timestamp":"2026-04-28T14:08:00.000Z","job-id":"incident-window-2026-04-28"}'

Timestamp job creation resolves the window to concrete offsets before the draft is stored. The start timestamp is inclusive and the end timestamp is exclusive.

Replay Throttling

Add messages-per-second to the create payload to store a write cap on the job. The cap is enforced when the replay starts and writes to the destination topic.

Start and Poll

curl -X POST http://localhost:3000/api/jobs/incident-2026-04-28/start
curl http://localhost:3000/api/jobs/incident-2026-04-28

Start requests return the job in running state and launch the replay worker in the app process. Progress is written back to SQLite and can be polled by job id.

Cancel

curl -X POST http://localhost:3000/api/jobs/incident-2026-04-28/cancel

Draft, failed, and running jobs can be cancelled. API-started running jobs are aborted through the in-process replay runner; CLI-started jobs observe the persisted cancelled state during progress checks.

Progress Object

Job reads include a derived progress object with replayed count, total count, remaining count, percent complete, current offset, elapsed time, average messages per second, and estimated remaining time for running jobs.

Status Codes

• 200 for reads, previews, and cancellation
• 201 for creation
• 202 for start
• 400 for validation errors
• 404 when the job id does not exist
• 409 for invalid state transitions
• 502 for Kafka-side replay failures surfaced through the API

For repo-facing details, see docs/REPLAY_API.md.