--- title: "AI Content Drop API Versioning and Deprecation Policy | AI Content Drop" description: "How the AI Content Drop API is versioned, what counts as a breaking change, and how retirement is signalled with Deprecation and Sunset headers." canonical: "https://aicontentdrop.com/docs/versioning" source: "https://aicontentdrop.com/docs/versioning" --- # 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`](https://aicontentdrop.com/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: ; rel="deprecation" ``` `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html)) says the announcement date. `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)) 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](#changelog), the `deprecated` flag in [`/openapi.json`](https://aicontentdrop.com/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: | Element | Replacement | Announced | Earliest future-major removal | Why | | --- | --- | --- | --- | --- | | `Model.credits` | `Model.creditCost` | 2026-08-26 | 2027-02-22 | Renamed for clarity. | | `JobStatus.PENDING` | `JobStatus.GENERATING` | 2026-08-26 | 2027-02-22 | Merged into GENERATING; a job is never reported as PENDING. | | `Query.generation` | `Query.job` | 2026-08-26 | 2027-02-22 | Renamed to make the asynchronous polling contract explicit. | 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`](https://aicontentdrop.com/.well-known/mcp.json) is generated from the same tool, resource, and prompt descriptors as the live endpoint. ## Changelog | Date | Change | Breaking | | --- | --- | --- | | 2026-08-24 | `Retry-After` on every 429; `API-Version` on every public response; `/v1` errors typed in the spec | No | | 2026-08-23 | MCP HTTP+SSE compatibility transport added; it now uses `/mcp/sse` so headerless Streamable GETs remain unambiguous | No | | 2026-08-22 | `POST /v1/batch`, sandbox mode without a key, cursor paging on `/v1/videos` | No | | 2026-08-19 | `/v1` public REST API and `acd_live_` API keys introduced | No | ## Questions Anything not answered here: [support@aicontentdrop.com](mailto:support@aicontentdrop.com), or [/contact](https://aicontentdrop.com/contact).