> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0037 — API versioning by the Stackra-Version date header

> Superseded by 0118 · 2026-10-19

> [!NOTE]
>
> Superseded by [0118](/adr/0118-api-versioning-dormant-package): versioning is a dormant
> response-transform package, pinned per API key or OAuth app; decisions 1 to 3 carry forward there.

## Context

The HTTP conventions rule says endpoints are immutable, with no `/v1` or `/v2`, and only events are versioned. That cannot absorb breaking changes to a response shape for external API consumers and OAuth apps. A date-pinned header (the Stripe model) keeps paths stable.

## Decision

1. **Breaking changes are versioned by a date**, sent as the `Stackra-Version` request header; the default for a client is the version pinned when it was created.
2. **Paths stay unversioned.** Events keep `.vN` names ([0033](/adr/0033-pubsub-cron-transactional-outbox)).
3. Each breaking change is a dated transform applied to the latest response.
4. **Open question:** implement as a versioning package (as reference implementations of webhooks and REST do) or as plain middleware. The owner will compare the references first; this ADR is not accepted until that is settled.

## Consequences

* External clients upgrade on their schedule; the transform list is a maintenance cost.
* The HTTP conventions rule line "no versions" must be reworded to point here.

## Enforcement

Planned — a contract test per dated transform; a check that no route path matches `/v\d+/`.

## Supersedes and sources

Supersedes: none. Amends the HTTP conventions rule (`.agents/rules/http-conventions.md`, "no versions"), which is not an ADR. Sources: owner decisions in chat, 2026-10-19.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.