> For the complete documentation index, see [llms.txt](https://docs.autoenhance.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autoenhance.ai/api-versions.md). # API Versions Our API is **versioned by date**. Each version is a snapshot of the API's behaviour on the day it was released. Your account is pinned to one version, so your integration keeps behaving exactly the same way until **you** decide to upgrade — new versions never change the behaviour of code already running against an older one. {% hint style="info" %} **Latest version:** `2026-07-01` Not sure which version you're on? Every API response includes an `x-api-version` header telling you the version that served the request. {% endhint %} ## How versioning works
What is an API version, and which one am I on? When you join Autoenhance, your account is automatically pinned to the version that is current at that time. Every request you make is served by that version, so responses and behaviour stay consistent. You can see the version serving any request in the `x-api-version` response header.
Will a new release change how my integration behaves? No. When we release a newer version, applications on older versions keep working exactly as before. Any breaking changes or behavioural differences are **isolated to the new version** — they never reach you until you explicitly upgrade. Where a new version changes a field, we translate transparently for older clients (for example, folding a renamed property back to its old name on requests and responses), so existing code needs no changes.
How do I test or switch to a different version? Send the `x-api-version` header with the version you want, e.g.: ```http x-api-version: 2026-07-01 ``` This lets you trial a newer version per-request without changing your account default. Once you're happy, contact support to pin your account to the new version. New features introduced in a later version only become available once you're on that version or newer.
What does a date in the changelog mean? Each dated entry below describes everything that changed in that version, newest first. To adopt the features in an entry, make sure your requests use that version (or a later one) via the `x-api-version` header.
## API Changelog ### **Version 2026-07-01** **A single property for sky control** We've consolidated sky control into one property, `restage.sky`, replacing the separate `sky_replacement` (boolean) and `cloud_type` (enum) fields. `restage.sky` accepts: * `AS_SHOT` — keep the original sky (equivalent to the old `sky_replacement: false`) * A cloud type (e.g. `CLEAR`, `LOW_CLOUD`, `HIGH_CLOUD`) — replace the sky with that style {% hint style="info" %} **No action needed for older clients.** On versions before `2026-07-01` we automatically fold your `sky_replacement` / `cloud_type` values into `restage.sky` on requests, and re-derive `sky_replacement` and `cloud_type` from `restage.sky` on responses — so existing integrations are unaffected. {% endhint %}
Migration: before & after **Before (`2026-06-02` and earlier):** ```json { "sky_replacement": true, "cloud_type": "LOW_CLOUD" } ``` **After (`2026-07-01`):** ```json { "restage": { "sky": "LOW_CLOUD" } } ``` To keep the original sky: ```json { "restage": { "sky": "AS_SHOT" } } ``` Deprecated cloud types that have no `restage.sky` equivalent continue to work on the legacy fields.
**New sky packs** Two new sky styles are now accepted as cloud types (and as `restage.sky` values): `WHISPY_CLOUD` and `DUSK_CLOUD`. These are additive — no changes required. {% hint style="info" %} The new sky packs are only produced by more recent AI versions. On older AI versions the request is still accepted, but the new styles won't be applied. See [AI Versions](/ai-version.md) to check or update your AI version. {% endhint %} **`max_width` now honoured** The `max_width` parameter on image downloads was previously ignored. It is now applied as documented. * Full-resolution downloads (`preview=false`): your `max_width` is applied as requested. * Preview downloads (`preview=true`): capped at **2048 px** width and **quality 50**. A larger requested `max_width` is clamped to 2048. See [Sky Replacement](/images/basic-enhancements/restaging/sky-replacement.md) and [Enhanced](/images/downloading-images/enhanced.md) for full details. ### **Version 2026-06-02** **`finetune` renamed to `finetuned`** The `finetune` query parameter has been renamed to `finetuned` for consistency. Clients on older API versions can keep sending `finetune` — we map it to `finetuned` automatically, so no changes are required until you upgrade. ### **Version 2026-05-20** **Automatic Deprecated AI Version Upgrades** * AI versions below `4.7` are now automatically upgraded to `4.7`. * All AI version `5` requests are now automatically upgraded to `stable`. **Rate Limits** We are introducing rate limits for the API. These will initially apply to customers who sign up after this date. For more details, see [Rate Limits](/rate-limits.md). Both of these changes will apply across all API versions. ### **Version 2026-02-01** **Re-staging** You can now use our new re-staging feature to go back in time to remove photogrpahers from your shots, light up all the fireplaces and black out those TVs. **Support for Next-Gen Formats** We have expanded our export capabilities to include the latest high-efficiency image standards. Images can now be exported in JPEG XL or AVIF formats. To utilize these new standards, simply append the following parameters to your request URL: * Use `?format=jxl` for JPEG XL * Use `?format=avif` for AVIF **Duplicate Image Detection** To ensure stability and help you identify issues in your integration logic, we have improved our rate limiting system. We can now detect faulty scripts that inadvertently upload the exact same image repeatedly. These redundant uploads will now be flagged and counted against your rate limits, preventing unnecessary bandwidth usage and processing queues. For more details about Re-Staging and Next-Gen Formats read our [Enhanced](/images/downloading-images/enhanced.md) guide. ### **Version 2025-08-31** **Introducing Window Pull Types** We are now introducing the ability to specify which style of Window Pull you would like. You have the option of setting our new "window\_pull\_type" property to "NONE" for no window pulls, "ONLY\_WINDOWS" for a normal window pull or "WITH\_SKIES" to add sky replacement. For customers integrated with one of our old API versions when you specify "window\_pull" as true our API will be treat it as if "window\_pull\_type" was "ONLY\_WINDOWS"..\ \ For older clients "window\_pull" will be true for any "window\_pull\_type" other than "NONE" **Rate Limits** To ensure stability for all customers, we have introduced rate limits to our API - You can now make up to 100K requests per day which should allow you to upload up to 300,000 images per month. ### **Version 2025-05-08** **Bracketing API and New Image Status**\ We’ve added official support for bracketing workflows with two new endpoints:\ `/orders/{id}/brackets` and `/brackets.` For more details read our [HDR Brackets](/getting-started/quickstart/hdr.md) guide. This enables workflows involving the uploading of pre-grouped brackets. Images waiting for their files to be uploaded will now return a `waiting` status. Older clients will see this as `processing` with the appropriate reason in `status_reason`. Finally, we will now return a response if you try to process an order before all of the brackets have been uploaded to avoid unexpected results. To take advantage of all of these new features, upgrade to the latest version of the API by specifying `2025-05-05` in the `x-api-version` header of your requests for your client . **Metadata Field Added**\ You can now attach and retrieve custom metadata with your images. In addition the AI will automatically adds metadata such as the MIME type. In the future we will expand this to expose additional information about your image. **Order Endpoint Changes**\ `/orders/{id}/merge` has been moved to `/orders/{id}/process`. The old path will continue to work for clients on our previous API version. **Upload Changes**\ When uploading images we no longer use the `content_type` field and you now only need to use `application/octet-stream as the` `Content-Type` header when uploading the file . As part of this change we've remove the `image_type` and `content_type` fields. In addition `s3ObjectUploadUrl` has been renamed to `upload_url` The `Content-Type` and `image_type` fields are deprecated but still supported for legacy clients using `s3ObjectUploadUrl`. For clients still using previous API version, these fields will be handled as usual, no changes need to be made to these clients. ### **Version 2024-12-01** **Deprecation of preview2 and watermark endpoints** These endpoints will now be redirected to the equivalent request using our new dynamic versioning API, you can request a watermarkt by passing `` `watermarkl=true` ``and you can specify your own custom output size using the new sizing options. ### **Version 2024-11-01** \ **Dynamic Image Rendering** In this release all image endpoints now support **dynamic rendering across original, edited, and preview versions**. This means you can control how images are rendered—regardless of version—by specifying parameters in the URL. **Example:**\ `/v3/images/{uuid}/preview?quality=75&format=webp` **Avaliable Options:** * **Size**: Modify the size on-the-fly by using `max_width` and `scale`, ideal for displaying images optimized for different screen sizes and layouts. * **Quality**: Customize quality by setting `quality` (1–100), enhancing control over file size and resolution for each use case. * **Watermark**: Add watermarks dynamically by setting `watermark=true` in the query, allowing seamless watermark application across image versions. * **Format**: Choose the output format (`format=jpeg`, `format=png`, etc.) based on your requirements, whether for compression, or quality retention. **Removal of `watermark` endpoint and `size` URL parameter** The `watermark` endpoint has been **removed** and is now integrated into this flexible preview structure. This allows you to access all transformations through a single endpoint without needing specific endpoints for each transformation type. In addition the size attribute for all endpoints have been deprecated and will have no effect on the output image.\ \ For applications using older versions of the API clients will continue to receive images in the same format from these endpoints. ### **Version 2024-10-01** **Support for returning AI Versions** * The `ai_version`field for images will now be returned as a **string** to support more flexible versioning, such as returning floating version numbers i.e "4.x". * For older clients that are not compatible with this format, the `ai_version` field will return **null**. #### **New Expired Status for Images:** * When an expired image is requested, the API will return `"status": "expired"` for applications using this version or later. * For applications using older versions of the API, expired images will return an `"error": true` response, with the `"status": "error"`. * **Recommendation**: Upgrade to the latest version to correctly handle the `"expired"` status and avoid misinterpreting expired images as general errors. #### **Custom Metadata Field:** * A new `metadata` field has been introduced, which includes specific metadata from your images, such as the Camera Model. #### **New `status_reason` Field for Error Context:** * We have added a `status_reason` field that provides more detailed information when an image’s `"status"` is set to `"error"` or `"expired"`. * This new field will clarify the specific reasons behind an error or expiration, making it easier to diagnose and manage various scenarios in your application. #### **Removal of `error` and `enhanced` Flags:** * The `error` and `enhanced` flags have been deprecated and removed in favor of the `status` field. * Instead of these flags, you should now use the `status` field, which will return `"error"` or `"processed"` to indicate the current state of an image. * **Action Required**: Update your application to accommodate this change. #### **Caching of Images:** * API now returns HTTP request caching headers for images, so applications that support this functionality will no longer need to refetch an image unless it has changed. This reduces unnecessary API calls and improves performance for image-heavy applications. #### Accelerated Uploads * This version introduces **accelerated uploads**, reducing the time required to upload images, especially for large files or high-volume uploads. With this enhancement, users will experience faster image processing times, improving the overall performance of the upload pipeline. ### **Version 2024-06-01** #### **Deprecations:** * **v2 Endpoints:**\ As of this release, all `/v2/` API endpoints have been fully deprecated. Requests to `/v2/` will no longer be supported, and there is no automatic redirection. If your application is still using `/v2/` endpoints, you must manually update your API requests to use `/v3/`: * **Update:**\ `/v2/` → `/v3/` Ensure that your application is using the `/v3/` endpoints to maintain functionality. * **Deprecation of Non-Pluralized Endpoints:**\ Non-pluralized endpoints under `/v3/` have been deprecated and replaced by their pluralized equivalents. If you're using non-pluralized endpoints (e.g., `/v3/image`, `/v3/order`), these will no longer work. Update your API calls to the following pluralized forms: * `/v3/image` → `/v3/images` * `/v3/order` → `/v3/orders` * `/v3/user` → `/v3/users` * `/v3/payment` → `/v3/payments` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.autoenhance.ai/api-versions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.