Shadow Warden AI — Gateway v7.10 — Explore the API Reference

Shadow Warden AI API Versioning and Deprecation

How a change is announced before it can break a caller

Versioning

The version is in the URL path. The current and only version is v1. The OpenAPI 3.1 document at /openapi.json declares the v1 base URL in its servers block.

POST https://api.shadow-warden-ai.com/v1/filter     ← use this
POST https://api.shadow-warden-ai.com/filter        ← works, deprecated

What counts as a breaking change

Within v1 we do not remove or rename a field, change a type, tighten a validation rule, or remove an endpoint. Adding an optional field, an endpoint or a response header is not breaking, so clients must ignore fields they do not recognise. A breaking change ships as a new version beside v1, never in place.

How deprecation is signalled

A deprecated resource answers with standard headers a client can act on without reading this page. Today they are sent on every unversioned path. Unversioned paths are served until 2027-08-23.

Deprecation: @1787443200 RFC 9745
Sunset: Mon, 23 Aug 2027 00:00:00 GMT RFC 8594
Link: <successor>; rel="successor-version" RFC 8288
Link: <policy>; rel="deprecation" RFC 9745

Infrastructure and discovery paths (/health, /metrics, /docs, /openapi.json, /.well-known/*) are not versioned and not deprecated.

The timeline we commit to

  1. Announce — the Deprecation header and successor link appear, and the change is recorded in the changelog.
  2. Notice period — at least 180 days between the first Deprecation header and the Sunset date for any versioned resource.
  3. Sunset — after the date the resource may return 410 Gone.

The sunset date may be extended, never shortened. Related: developer portal, rate limits, authentication.