Versioning & deprecation

Versioning

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

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 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.