---
title: "Versioning & deprecation"
description: "How the Imagen API is versioned, what counts as a backward-compatible change, and how deprecations are announced so your integration keeps working."
canonical: https://api-docs.imagen-ai.com/docs/reference/versioning/
last-updated: 2026-08-27
---

# Versioning & deprecation

## Versioning

The Imagen API is versioned in the URL path. The current version is **v1**, and
every endpoint lives under:

```curl
https://api.imagen-ai.com/v1/
```

A version number only changes when we make a breaking change. As long as you call
the `v1` base URL, your integration keeps talking to a stable, supported version.

## Backward-compatible changes

We add capabilities to `v1` over time. The following are considered
**backward-compatible** and can ship without a new version - write your client to
tolerate them:

- New endpoints and new optional request parameters
- New fields in response objects
- New values in existing enums (e.g. a new AI tool or photography type)
- New optional HTTP response headers

Practical rule: ignore fields you don't recognize, and don't hard-code an
exhaustive list of enum values. The [OpenAPI spec](/openapi.json) is the source
of truth for the current surface.

## Deprecation policy

When we need to retire an endpoint, field, or behavior, we aim to make the
transition predictable:

- Deprecations are announced ahead of removal, with the recommended replacement.
- The previous behavior continues to work during a migration window so you have
time to update.
- Breaking changes ship under a new version path (e.g. a future `v2`); `v1` is
not changed out from under you.

> **Planning a long-lived integration?** For advance notice of deprecations and migration guidance tailored to your usage, reach out via the [contact page](/contact) or [contact sales](https://imagen-ai.com/contact-sales/).