How to version API documentation

This becomes especially important when several versions remain live. Without versioned documentation, a developer can be looking at the latest parameters while their production requests still use a contract from two years ago.

How do you version API documentation?

Version the reference according to the API contract your clients actually use. Publish the supported versions, identify the default, mark versions that are retiring, and explain every migration that requires code changes. Keep shared guides shared where they are genuinely compatible; give version-specific instructions their own pages where they are not.

The guiding question is simple: if someone pastes a link to a GET /customers page into an incident ticket, can the next person tell exactly which version of that endpoint the page describes?

How do APIs choose a version?

A version can appear in the URL (/v2/customers), in a header (X-GitHub-Api-Version), or through an account-level default. Date-based versions are common; other systems use major version numbers or date-plus-name combinations.

Show the selection mechanism in the first request example, not on a separate page readers may never find. Also document what happens when the client sends no version, requests an unknown version, or continues using one that has passed its support date.

curl https://api.example.com/customers \
  -H 'Authorization: Bearer $EXAMPLE_TOKEN' \
  -H 'API-Version: 2026-08-01'

This is an illustrative API; API-Version is not a universal HTTP header. Your examples should use the exact mechanism your service supports.

Version the docs by API version

Documentation tools often expose several numbers at once: the API version, the OpenAPI document's info.version, the SDK package version, and the version of the docs publishing system. They describe different things.

An SDK can publish a bug fix without changing the server contract. A typo fix can republish the docs without changing either. The version selector on the API reference should normally follow the behavior the server guarantees to its clients, while SDK pages can separately state which API version their package targets.

If your team uses the same label in multiple places, make that convention explicit. Similar labels do not make the concepts interchangeable.

Decide what needs a new version

Stripe offers a particularly clear example of why this matters. In its engineering article APIs as infrastructure: future-proofing Stripe with versioning, the team describes replacing a bank-account verified boolean with a richer status field in 2014. Code checking the old boolean would fail if the field simply disappeared. Stripe used versioning to let its API evolve while preserving the response shape expected by existing clients.

The lesson is not that a status field is better than a boolean. It is that a seemingly modest schema improvement can invalidate a line of code written years earlier. Your docs should treat that as a contract change and tell the reader which version has which shape.

Removing an endpoint, changing a field's type, adding a required argument, or altering authentication requirements may be breaking. Adding an endpoint or an optional input is usually compatible, though some clients are sensitive to new enum values or new response fields. Apply your own compatibility policy consistently and publish it where developers can find it.

Stripe later introduced a more predictable release cadence, explained by its team in Introducing Stripe's new API release process. It paired scheduled breaking releases with non-breaking feature releases and redesigned the changelog to clarify which changes affect an integration. The lesson for your documentation is that versioning needs a communication policy, not just a number in a dropdown.

Keep one OpenAPI file per version

For separate supported contracts, publish separate machine-readable descriptions. That may mean maintaining snapshots such as:

openapi/
  2025-08-01.yaml
  2026-08-01.yaml

Each file should describe the endpoints, schemas and authentication that actually apply to that version. Generate each reference from the matching file. A renderer that always reads the latest spec cannot truthfully document older behavior merely by changing the page heading.

Compare versions with an OpenAPI diff tool like oasdiff. The comparison can seed a changelog and flag possible breaking changes, but a human still needs to explain what to do about them.

Decide what each version gets

The reference usually needs a copy per supported contract. A guide about conceptual topics, such as handling retries, can often be shared if the behavior is the same across versions. A tutorial that includes a renamed endpoint or a different OAuth flow cannot be shared without qualification.

Do not duplicate the entire site automatically. Every copy becomes another place a broken link or outdated instruction can survive. Prefer shared concept pages with clear applicability notes and a direct link to the relevant versioned reference. Reserve separate guides for real differences in the developer's steps.

Add a version switcher

A useful switcher preserves context. If a developer is reading the older version of GET /invoices, selecting the new version should take them to that endpoint if it exists. Otherwise, show a clear destination explaining that the operation is absent, not an unexplained 404.

Put the version in the URL so links remain reproducible. Mark versions as current, beta or deprecated. Resist quietly selecting a new version whenever a reader returns: during a migration, the old contract is precisely the one they need to inspect.

Mark beta and deprecated versions

Lifecycle language should describe consequences. A beta notice should say which behavior may still change. A deprecation notice should give the old version, its replacement, the migration guide and the date support ends.

Version 2025-08-01 is deprecated and scheduled to stop working
on 2027-08-01. Migrate to 2026-08-01 before that date.

Those dates are illustrative; a real site must use its published policy. Where applicable, the standard Deprecation and Sunset response headers can notify clients programmatically as well.

Write a migration guide for every breaking version

A changelog tells developers what changed. A migration guide tells them what to change in their code, preferably with before-and-after requests and responses.

Imagine a sample API replacing balance with balance_cents. Your migration guide should show the old response, the new response, how the unit changed, which SDK types are affected, and how to test the upgrade in staging. Telling readers only that a field has been renamed leaves the important question unanswered: will the old code compute the same result?

A good migration guide starts with who is affected, names the support deadline, lists breaking changes in the order they are likely to appear during a migration, and ends with a way to confirm success or roll back safely. Link it from version notices, changelogs and relevant endpoint pages.

Versioned docs and search engines

Search engines can surface older pages even after the current API has changed. Put a clear version label in the title or page chrome, keep stable URLs and use appropriate canonical signals for substantially duplicated content. Be careful with canonicalizing genuinely different endpoint versions: search engines may consolidate pages that still have unique value to readers. Test how your site indexes versioned URLs rather than relying on one blanket rule.

At sunset, consider whether an old reference should remain available as an archive or redirect to a migration guide. Make the decision based on actual developer needs and your support obligations, and avoid breaking links without a useful destination.

API documentation versioning best practices

The best systems allow old integrations to remain understandable while new ones adopt improvements. That means keeping the version mechanism visible, publishing a clear compatibility policy, making changes searchable, and giving each breaking release a migration path.

Avoid pretending every feature addition needs a new API version. Avoid using SDK patch numbers to switch server contracts. And avoid putting a retirement date only in a changelog when someone reading an old endpoint needs to see it immediately.

API documentation versioning checklist

• Is the active API version explicit on every reference page?
• Do request examples show how a client selects a version?
• Does each supported version use the correct OpenAPI snapshot?
• Are breaking and compatible changes defined and consistently reviewed?
• Does the switcher preserve the current endpoint when possible?
• Do deprecated versions show their replacement and sunset date?
• Does every breaking release have a before-and-after migration guide?
• Can old links still tell a reader which contract they describe?

Version API documentation with Octri

Octri API Studio can create separate references from imported OpenAPI versions and provide version selection, lifecycle notices and changelogs. Documentation versioning is available on Growth and higher plans. Guides can remain alongside the reference in the same publishing environment.

The tooling is useful because it makes version information visible where developers work. It still needs a deliberate version policy and well-written migrations. Stripe's experience shows why: a contract can evolve for years only if the people relying on it know which behavior their code is entitled to expect.