Skip to main content

API stability and versioning policy

This page is the customer-facing contract for how the Zeridion Flare REST API evolves. It tells you which changes are safe to depend on, which changes require a new API version, and how much warning you get when an endpoint is going away.

This page is the binding contract for customers; nothing on it changes without the deprecation cadence described below.

Status of /flare/v1 and /platform/v1​

Both surfaces are General Availability (GA) today.

  • /flare/v1/* — the job-queue API consumed by every SDK and by direct HTTP callers. This is the surface your application code talks to.
  • /platform/v1/* — the dashboard-facing management API (auth, billing, account, projects, teams). You only call this directly if you are building tooling against your own tenant.

Each surface versions independently. A breaking change in /platform/v2 does not necessarily mean a breaking change in /flare/.

What counts as a breaking change​

Adding any of the following requires a new major URL segment (e.g. /flare/v2):

  • Removing a field from a response body, or renaming it.
  • Changing a field's type (e.g. int → string).
  • Removing or renaming an endpoint, or moving it to a different path.
  • Changing the meaning of an existing field's value (e.g. a status enum gains a non-superset case).
  • Changing authentication semantics — for example, requiring an additional header, or rejecting a previously-accepted key format.
  • Reordering positional parameters.
  • Tightening a previously-permissive validation rule such that previously valid requests now return 4xx.

Additive changes are NOT breaking and ship into the existing version:

  • Adding a new optional request field.
  • Adding a new response field.
  • Adding a new endpoint.
  • Adding a new value to an enum-shaped field where the API documentation already states the set is open-ended (such as new error.code values, new ActivityKind wire strings, new job states).
  • Loosening validation (accepting new shapes that used to 4xx).
  • Adding new HTTP response headers, or new optional query parameters.

In short: your client code should always tolerate additional response fields and new optional inputs. The JSON-strict-decode trap is yours to defend against — every official SDK does.

Deprecation signalling​

When a new major version ships (e.g. /flare/v2), the old version (/flare/v1) stays live for 12 calendar months from the day v2 becomes GA. During that window every response from /flare/v1 carries three headers:

  • Deprecation: true — RFC 9745 boolean. Treat as a hard signal to migrate.
  • Sunset: <RFC 3339 date-time> — RFC 8594 timestamp of the planned removal date (exactly 12 months after the new version's GA day).
  • Link: <https://docs.zeridion.com/migration/vN>; rel="deprecation" — pointer to the migration guide for that specific transition.

After the Sunset date, the deprecated endpoints return 410 Gone for 30 days before being removed entirely. There is no silent 404.

Subscribe to the API changelog — every major version launch is announced there, with the migration guide linked.

When /flare/v2 ships, the migration guide will live at migration/v1-to-v2.md (URL planned — the file does not exist yet because no v2 has been cut). The Link: <…>; rel="deprecation" header on every deprecated response will resolve to that page, so a client following the deprecation link automatically lands on the migration instructions.

SDK majors track API majors​

Every official SDK (Zeridion.Flare for .NET, @zeridion/flare for TypeScript, zeridion-flare for Python and Ruby, etc.) ships a major version with each API major version. So:

  • Zeridion.Flare 1.x targets /flare/v1.
  • When /flare/v2 ships, the SDKs cut 2.0.0. Their 1.x branches enter security-patch-only mode and follow the same 12-month sunset clock as the API.

You can pin to an SDK major and trust it will not break under you — the SDK will refuse to send requests against an API major it does not understand.

Pre-release endpoints and fields​

A small number of endpoints and fields are explicitly marked pre-release:

  • Endpoints whose path includes /preview/ (none today; reserved).
  • Response fields documented as "preview" or "experimental" in the API reference.
  • Features flagged behind a header (e.g. X-Zeridion-Preview: 2026-05-15).

Pre-release surfaces do not have the 12-month sunset guarantee. They can change shape or disappear with the next GA release; we will still announce material changes in the changelog. If you build production-critical behaviour on a preview surface, you accept the migration cost yourself.

There are no pre-release endpoints on the GA surface today. This section exists so you know what to expect when one ships.

What we do not guarantee​

A short, honest list of things that are out of scope for this contract:

  • Rate-limit numbers — the per-plan request budgets in rate-limits.md can be tuned without a version bump. We will not silently tighten them in a way that breaks live integrations, but we may raise or lower them as the platform scales.
  • Error message wording — the code field in error bodies is stable (see the "Error code stability" tip in errors.md); the human-readable message is not. Do not regex error messages — branch on code.
  • Response ordering for list endpoints — unless the endpoint documents a sort key, you should treat list order as undefined.
  • HTTP/2 vs HTTP/1.1, TLS cipher choice, server-side connection pooling, and other transport details — these are infrastructure, not contract.

Reporting a contract regression​

If you observe behaviour that you believe violates this policy — for example, a field that disappeared without a version bump, or an endpoint that returned 410 Gone without prior Deprecation headers — please:

  1. Capture the request id from the failing response (request_id in the error body, or the X-Request-Id header).
  2. Note the date, the path, the API version segment, and what changed.
  3. Email support@zeridion.com with subject API stability regression.

We will respond within one business day. Confirmed regressions are treated as outages.

See also​