Skip to main content

Versioning and stability

The version is in the path​

https://api.flowbeacon.ai/api/public/v1/...
  • Additive changes (new optional fields, new endpoints, new optional headers) ship in place on v1 and are not considered breaking.
  • Breaking changes require a new path prefix (/v2) and a minimum 180-day parallel-operation window.
  • The platform's internal version (info.version in the OpenAPI document) tracks documentation updates; the path prefix is the stability promise.

Deprecation policy​

When a field or endpoint is scheduled for removal:

  1. A Deprecation response header is added, carrying the removal date in RFC 3339 format.
  2. A Sunset response header is added per RFC 8594.
  3. The Changelog is updated with the migration path.
  4. Existing integrations have at least 180 days from the first deprecation notice before removal.

Monitor these headers in your client and surface the deprecation date to engineers.

What's considered stable​

SurfaceStability
Response envelope shape ({ ok, data, meta })Stable. Cannot change without a major version bump.
Envelope.meta.watermarkOpaque token. Format can change.
Error envelope shape ({ ok: false, error, detail })Stable.
Documented error codesStable. New codes may be introduced; existing codes remain.
Documented endpoints and their request/response schemas in the OpenAPI documentStable additive evolution.
Policy shape — five fields exactlyStable. Clients should ignore additional fields.
Per-violation severity valueContextual — prefer catalog severity.
ScenarioResults.evaluation_statusStable since this revision.

What's intentionally undocumented​

  • The exact algorithm used to choose which policies apply to a scenario.
  • The internal evaluator output that produces violations.
  • Watermark generation seed.
  • Any field not listed in the OpenAPI document.

If you rely on something not in this site or the OpenAPI document, please raise it on partners@flowbeacon.ai so we can stabilise it formally.

Versioning infrastructure in these docs​

This documentation site has versioning infrastructure ready but does not yet cut snapshots. When v2 ships, we will run:

npm run docusaurus -- docs:version 1.1

to snapshot the current docs as 1.1, then continue iterating on v2 in current. Until then, the docs always reflect the latest v1 surface.

Next steps​