API Versioning

API versioning as a spec annotation, not a config file.

Declare your entire version lifecycle in x-apistaq-version annotations: current version, deprecated versions, sunset dates, and breaking-change gate behavior. Apistaq enforces the policy — automated deprecation headers, backward-compatibility diffs, and per-version docs — on every spec sync.

Get started free Read the docs

versioning.yaml

            x-apistaq-version:
              current: v3
              deprecated: [v1]
              sunset:
                v1: "2026-09-01"
              breaking_changes: warn
          

How it works

Version lifecycle managed from your spec, not a dashboard.

Semver lifecycle declared in-spec

Add x-apistaq-version annotations to declare which version is current, which is deprecated, and when each sunset fires. Apistaq reads these on every spec sync and generates per-version docs, deprecation headers, and migration guides automatically. No dashboard clicks required to change policy.

Breaking-change detection before deployment

Every spec update is diffed against the previous published version. Removed fields, changed parameter types, and deleted endpoints are classified as breaking. Configure your gate as warn (logs only) or block (halts SDK publish and portal update) per your release tolerance.

RFC 8594-compliant Sunset headers

Set a sunset date in your spec. Apistaq automatically injects RFC 8594 Sunset and RFC 8288 Deprecation response headers on deprecated endpoint responses — machine-readable warnings that SDK clients and gateway observability tools can act on without parsing docs.

version-check output

              # Apistaq diff check v2 → v3
              ✓ GET /orders — compatible
              ✓ POST /orders — compatible
              ⚠ DELETE /orders/{id}
                  field 'force' removed (breaking)
              ℹ v1 sunset in 91 days
              # 1 breaking change, gate: warn
            

Stop managing version policy in three places at once.

Free plan includes versioning for up to 3 versions per API. Builder and Platform unlock unlimited versions, breaking-change gates, and full sunset automation.

Start free