Skip to main content

API Changelog

All notable changes to the Zeridion Flare API are recorded here. The format follows Keep a Changelog 1.1.0; versioning follows Semantic Versioning 2.0.0. For the binding contract on what counts as a breaking change and how deprecation is signalled, see the API stability and versioning policy.

Unreleased​

Added​

  • GET /flare/v1/jobs/{id}/events — Server-Sent Events stream for sub-second job progress updates.
  • GET /flare/v1/activity — Audit activity feed with cursor pagination.
  • GET|POST|PUT|DELETE /flare/v1/alerts — Alert notification settings CRUD.
  • POST /flare/v1/workers/{register,poll,ack,heartbeat} — Worker protocol endpoints (previously undocumented).
  • GET /flare/v1/metrics/job-types — Top-N job types by volume with per-type success rates and average durations.
  • POST /flare/v1/jobs/export — Bulk job export as NDJSON or CSV with keyset pagination and a 90-day window cap. Tenant-scoped, API-key auth, rate-limited to 1 request per minute per tenant.
  • GET /flare/v1/projects/{projectId}/audit-log/export — Audit log export (renamed/moved from /flare/v1/audit-log/export). Streams CSV or NDJSON with keyset pagination; JWT + admin/owner role; rate-limited to 1 request per minute per tenant.
  • p50_ms, p95_ms, p99_ms latency percentiles on every GET /flare/v1/metrics/throughput bucket (linear-interpolated over jobs that completed inside the bucket).

Changed​

  • API port corrected from 5000 to 5100 across all documentation and HTTP test files.
  • Idempotency-Key header is now RFC-style on every mutating /flare/v1 endpoint: a same-key replay returns the original response's status code (e.g. 201 Created for a job create) together with Idempotent-Replay: true. Mismatched body on the same key returns 409 idempotency_key_reuse.
  • Body-field idempotency (POST /flare/v1/jobs with idempotency_key in the JSON body) is now status-aligned with the header path: same-body replay returns 201 Created + Idempotent-Replay: true (previously returned 200 OK); mismatched body returns 409 idempotency_key_reuse. The body-field path is deprecated and will be removed in /flare/v2 — adopt the Idempotency-Key header instead.
  • The older idempotency_conflict error code has been unified into idempotency_key_reuse and is no longer emitted anywhere in the API surface.

Removed​

  • Deprecated /flare/v1/auth and /flare/v1/billing compatibility wrappers. Use /platform/v1/auth and /platform/v1/billing.
  • flare.zeridion.com host alias. The canonical API host is api.zeridion.com.

Security​

  • Per-account login lockout: failed logins are now counted per-account in addition to the existing per-IP counter, defending against multi-IP credential stuffing. Threshold is 10 failures per 15-minute sliding window, returns 429 account_locked with Retry-After. The check fires before password verification so lockout latency does not leak password-complexity timing. The counter resets to 0 on the next successful login.
  • Encryption at rest for stored TOTP secrets and webhook signing secrets via AES-GCM with per-environment keys. Rotation procedure is operator-managed.

0.1.0-beta.1 — 2026-04-14​

Initial beta release of the Zeridion Flare platform.

Added​

  • POST /flare/v1/jobs — Create a background job.
  • GET /flare/v1/jobs — List jobs with cursor-based pagination and filtering by state, queue, and job type.
  • GET /flare/v1/jobs/{id} — Get full job details including payload, error info, and tags.
  • POST /flare/v1/jobs/{id}/cancel — Cancel a pending or scheduled job, with cascade to continuation children.
  • POST /flare/v1/jobs/{id}/retry — Manually retry a failed or dead-lettered job.
  • POST /flare/v1/workers/poll — Dequeue jobs matching a worker's queues and capacity.
  • POST /flare/v1/workers/ack — Acknowledge job completion (success or failure) with error detail and duration.
  • POST /flare/v1/workers/register — Register a worker at startup; upserts recurring schedules declared via [JobConfig].
  • POST /flare/v1/workers/heartbeat — Keep a long-running job alive and report progress.
  • GET /flare/v1/recurring — List all recurring job schedules.
  • PUT /flare/v1/recurring/{id} — Create or update a recurring job schedule.
  • DELETE /flare/v1/recurring/{id} — Delete a recurring job schedule.
  • GET /flare/v1/metrics/summary — Aggregated job counts by state.
  • GET /flare/v1/metrics/throughput — Time-series throughput data (p50/p95/p99 latencies).
  • GET /flare/v1/metrics/queues — Per-queue depth and oldest-job age.
  • GET /flare/v1/activity — Audit activity feed.
  • GET|POST|PUT|DELETE /flare/v1/alerts — Alert notification settings.
  • Job continuations (parent_job_id) with parent-succeeds-activates-children / parent-cancelled-cascades semantics.
  • Idempotency key support: body-field idempotency_key on POST /flare/v1/jobs plus the RFC-style Idempotency-Key HTTP header on every state-changing endpoint (replays the original response + Idempotent-Replay: true, body-mismatch returns 409 idempotency_key_reuse, 24 h TTL).
  • Authorization: Bearer <api_key> authentication for all /flare/v1/* endpoints.
  • Public health probes at GET /flare/health/live and GET /flare/health/ready.
  • Durable PostgreSQL-backed job queue with separate read and write paths and an outbox-pattern delivery layer.
  • Sliding-window rate limiter with Redis backing in production and an in-memory fallback for local development.
  • Zeridion.Flare NuGet SDK (0.1.0-beta.1, targets net10.0 + netstandard2.1).

See also​

  • Stability Policy — deprecation cadence and v1 → v2 sunset commitments
  • Errors — error code catalog and what changes count as breaking
  • Installation — pin the SDK version compatible with each release