photoanalyzer/delivery_backlog/stories/US02-04-job-api-events.md

US02-04 — Expose Job APIs and Activity Events

Epic: E02

As a frontend client, I want versioned job commands, status APIs, and activity events so the browser can operate workflows without HTML responses or internal imports.

Acceptance criteria

• /api/v1 exposes typed job start, status, cancel, blocker, and event contracts.
• Operational endpoints return JSON; the event endpoint returns SSE with resumable IDs.
• SSE reconnects without duplicate/lost durable events and polling is sufficient as a fallback.
• Errors use the shared JSON envelope and correct status codes, including 409.

Automated tests

• OpenAPI/contract tests validate schemas, status codes, errors, and content types.
• Black-box tests cover SSE disconnect/reconnect, polling, idempotency, and cancellation.

Dependencies

• US02-02, US02-03