--- title: Compatibility & changelog url: https://base_url.placeholder/docs/changelog group: Reference --- # Compatibility & changelog There is one version: the `v1` in every path, in the OpenAPI document's `info.version` and in every webhook body's `apiVersion`. Inside it the API only grows; anything else is announced here first and runs beside what it replaces. There is no version header to negotiate and no version pinned per account. ## Additions are not announced Each of these is a minor change, and ships without notice: - a new field in a response, in a webhook event's `data` or in its envelope; - a new value of an enum the service sends — a job or item `status`, an error `code`, a webhook `type`, an op or a model in the catalogue; - a new endpoint, a new optional request field or query parameter. So a client **ignores fields it does not know** and **tolerates enum values it does not know**: an unknown `code` is handled by the `retryable` that comes with it ([error codes](https://base_url.placeholder/docs/errors#codes)), an unknown job `status` as "not settled yet", an event `type` it does not handle is answered `2xx` and dropped. A typed client that switches exhaustively over a generated union keeps a default branch — the union grows. ## Breaking changes are announced, and run side by side Removing or renaming a field, a code, an event type or a route, changing a field's type or its unit, and making an optional request field required are breaking. Inside `v1` one happens only this way: 1. The new shape is added beside the old one — a new field next to the field it replaces, a new route next to the route — and the two run side by side for **at least 90 days**. Where the two cannot coexist, the change is announced 90 days ahead instead. 2. For those days a response that still carries the old shape says so: `Deprecation` (RFC 9745, the date it was deprecated) and `Sunset` (RFC 8594, the date it goes) headers, with `Link: <…/docs/changelog>; rel="deprecation"`; the OpenAPI document marks the old field or operation `deprecated`. A webhook event is not a response and carries no headers: a key of its data that is going is marked in the OpenAPI document and announced in the changelog. 3. The change is an entry in the changelog below the day it is announced, with the date the old shape goes. The SDKs' own CHANGELOGs link their breaking entries here. ## What you send A field in a request body that the service does not know is **ignored, not refused** — a client newer than the service still gets an answer, and the field has no effect until the service knows it. Check a new field with a [dry run](https://base_url.placeholder/docs/jobs#price) before relying on it. Two things are checked by name instead: an op's or a model's `parameters` — an unknown key is `400 invalid_param`, because a misspelt parameter would otherwise run the op with its default — and a field that was removed when ignoring it would do something different from what its sender asked (`mode` on `POST /jobs` is `400 invalid_param`). ## Changelog Newest first. - 2026-10-14 · deprecated · Asset times become ISO-8601 strings An asset's createdAt, updatedAt, expiresAt and takenAt, a list row's createdAt and expiresAt, a collection's lastCreatedAt and a preview URL's expiresAt are epoch milliseconds today; every other time in the API is an ISO-8601 string. On the date below they become ISO-8601 date-time strings ("2027-01-12T09:30:00.000Z"): the same names and the same instants, a string instead of a number. The two cannot run side by side under one name, so this is the 90 days' notice. The takenFrom, takenTo, createdFrom and createdTo query parameters of GET /api/v1/assets keep taking both spellings. The SDKs, the CLI, the MCP server and the n8n node switch with the API. Goes on 2027-01-12. - 2026-10-14 · deprecated · A failed row is an ItemError: stage-upload's failure, an import's failures POST /api/v1/assets/stage-upload answers a file it will not stage with failure — {code, message, retryable, param}, the fields of an error: unsupported_format, payload_too_large or invalid_param on fileSize. POST /api/v1/presets/import and /api/v1/templates/import list each refused entry in failures, with its index and the same fields. The sentences they had — stage-upload's error, the imports' errors — stay beside them until the date below, then go: read failure and failures. The AssetError schema is now named ItemError (same fields, plus an optional param); the JSON did not change, generated type names did. Goes on 2027-01-12. - 2026-10-14 · deprecated · Webhook events: the job's names; jobId on a job event, creditsCharged and itemIndex go Event data now names each fact as GET /api/v1/jobs/{id} does, with the same value: id beside jobId and actualCredits beside creditsCharged on the job events, index beside itemIndex on the item events. New and staying: cancelledItems on the job events, op on all four. The old names go on the date below; an item event keeps jobId, its job. Goes on 2027-01-12. - 2026-10-14 · deprecated · GET /api/v1/ai-models: camelCase names, params; the snake_case names, parameters, supported_parameters and created go Each model now carries camelCase names beside the old snake_case ones — providerPrice, providerPriceRange, maxInputEdge, maxInputImages, inputModalities, outputModalities, contextLength, promptPrice, completionPrice, imageRequired; image_price_range is priceRange and support_structured_output is structuredOutput — and params, the parameters it takes in the shape of an op's params (name → type, enum, min, max, default, title, description). The old names, parameters, supported_parameters (the keys of params) and created (a constant, never a date) are deprecated: every answer carries Deprecation and Sunset headers until they go. Goes on 2027-01-12. - 2026-10-14 · added · Webhook events carry apiVersion Every webhook body has "apiVersion": "v1" beside its type — the version of the body's shape, the v1 of the paths. Nothing else in the body changed. - 2026-10-14 · added · The compatibility rules are published What may change inside /api/v1 without notice, and how a breaking change is announced — the rules at the top of this page.