AI Content Drop API Versioning and Deprecation Policy

The short version: /v1 will not break under you. Anything that would break a working integration ships as /v2 at a new path, and anything being retired announces itself in headers with at least 180 days of runway.

How the API is versioned

Versioning is in the URL. https://aicontentdrop.com/v1 is the compatibility promise — a client written against it today keeps working against it.

Every response also carries the dated build:

API-Version: 2026-08-24

A date, not a semver, on purpose: the path major already carries the compatibility contract, and a second number beside it would imply breaking changes /v1 does not permit. Use it for support conversations and for pinning what you tested against, not for feature detection — detect features by reading /openapi.json, which is regenerated with the surface.

Observe it with no credential:

curl -sD - https://aicontentdrop.com/v1 -o /dev/null | grep -i api-version

What is a breaking change

Breaking — never happens inside /v1:

• Removing an endpoint, a field, or an enum value
• Renaming anything a client reads
• Narrowing a type, or making an optional request field required
• Changing the meaning of an existing status code

Not breaking — expect these at any time:

• New endpoints
• New fields in a response
• New optional request parameters
• New enum values on a field documented as extensible
• New error code values within an existing status code

That second list is the contract you have to hold up your end of: ignore fields you do not recognise, and do not treat an unknown error.code as fatal. A client that rejects unknown fields turns our additive change into your outage. Match on the status code first and the code second.

How retirement is signalled

Nothing on /v1 is deprecated today. When something is, it announces itself on its own responses before it stops working:

Deprecation: @1793404800
Sunset: Sat, 21 Feb 2026 00:00:00 GMT
Link: <https://aicontentdrop.com/docs/versioning>; rel="deprecation"

Deprecation (RFC 9745) says the announcement date. Sunset (RFC 8594) says the earliest date it may stop working. The endpoint keeps working normally the whole time — a deprecated route returns the same responses it always did, with two extra headers.

The runway is at least 180 days between Deprecation and Sunset. If you log these two headers, that is the entire monitoring burden.

The retirement itself is announced in three more places, so a client that never reads headers still finds out: the changelog on this page, the deprecated flag in /openapi.json, and an email to the address on any account whose key called the route in the previous 30 days.

GraphQL

GraphQL signals retirement in the schema rather than in headers, because that is where a GraphQL client already looks:

All deprecated elements remain operational on /graphql while that major endpoint is supported. The removal date is not an in-place deletion date: it is the earliest a future major schema such as /graphql/v2 may omit the element. If the endpoint itself is ever retired, it receives the same Deprecation, Sunset, and Link headers and 180-day minimum notice as a REST major version.

Read deprecated fields with __type(name: "Query") { fields(includeDeprecated: true) { name isDeprecated deprecationReason } } — note includeDeprecated defaults to false, so a plain introspection query does not show them at all.

The live register is also queryable as apiInfo { deprecations }, which is the same data this page renders.

MCP

The MCP tool surface follows the REST policy: a tool is never removed from tools/list without a deprecation window, and its description carries the replacement during that window. The compatibility discovery manifest at /.well-known/mcp.json is generated from the same tool, resource, and prompt descriptors as the live endpoint.

Changelog

Questions

Anything not answered here: [email protected], or /contact.