Versioning

What the Tanqory spec declares about versioning today — URL-path versioning, per-service info.version.

Tanqory currently versions APIs via the URL path (/api/v1/...), not via a request header. No endpoint in the OpenAPI spec declares a version header parameter, and no operation is yet marked deprecated. This page documents only what is verifiable; the policy for future breaking changes will be amended into the spec ([FOUNDER TO CONFIRM] for the canonical policy + sunset header contract).

The state of the spec

We searched all three OpenAPI documents for versioning indicators. Findings:

Service	OpenAPI version	`info.version` (from spec)	Path prefix
Admin	`3.0.0`	`1.0.0`	`/api/v1/...`
AI	`3.0.0`	`1.0`	`/api/v1/...`
Store	`3.1.0`	`0.0.0-pending`	`/api/v1/...`

The Store API's 0.0.0-pending marker reflects that its spec is still in progress — the runtime exists, the OpenAPI export does not.

Pinning a version

Tanqory's only versioning mechanism today is the URL prefix v1:

curl https://api.tanqory.com/api/v1/stores \
  -H "Authorization: Bearer $TANQORY_API_KEY"

When a v2 is introduced, it will be exposed under /api/v2/... with v1 continuing to serve unchanged until its sunset window closes.

No request-header versioning exists today. If you see code samples elsewhere that send a Tanqory-Version header, they were written against a planning document — the runtime ignores the header and the spec does not declare it.

Deprecation policy

[FOUNDER TO CONFIRM] — the canonical deprecation window + notice cadence needs to be confirmed with legal before this section becomes a real contract. A typical commerce/AI-platform policy is:

Stage	Industry-standard window	Tanqory commitment
Announcement	Public changelog + email at announcement	`[FOUNDER TO CONFIRM]`
Support window	Minimum 12 months from announcement to removal	`[FOUNDER TO CONFIRM]`
Sunset header on responses	`Sunset` + `Deprecation` per RFC 8594 / RFC 8594-draft	Not yet emitted
Reminder cadence	T-6 mo / T-3 mo / T-30 d / T-7 d	`[FOUNDER TO CONFIRM]`

Until the policy is signed off, treat v1 as the only contract surface and pin to it explicitly in client code.

Per-operation deprecation

When a single endpoint within a major version is replaced, it is marked deprecated: true in the spec and the dev portal renders a "Deprecated" chip on the operation page. Zero operations are marked deprecated today across all three services — every endpoint in the current spec is live.

What is not yet documented (deliberate gaps)

Gap	Status
`Sunset` / `Deprecation` response header per RFC 8594	Not yet emitted; not declared in spec.
Per-version changelog	Tracked outside the spec; URL `[FOUNDER TO CONFIRM]`.
Replacement pointer (`x-replaced-by` on deprecated ops)	No deprecated ops yet, so no `x-replaced-by` mappings.
Header-based versioning fallback	Not implemented; URL path is the only mechanism.

Next steps

Topic	When to read it
Errors	If a future request to a sunset URL returns a deprecation-related error.
Authentication	Auth scheme will be versioned alongside the API.
Trust Center	Lifecycle commitments may appear in security + privacy posture.