API versioning

Versioning model

The API uses URL versioning:

https://api.aidomination.app/v1/...

Breaking changes are shipped under a new major version (v2, v3). Within a major version, we add fields but never remove or rename them, and we never change response semantics.

v1 stability commitment

We commit to v1 stability for at least 24 months after the v1 GA date (May 2026). That means:

• Every endpoint that exists in v1 today still works, with the same response shape, for 24 months minimum.
• New endpoints added during v1 follow the same compatibility rules.
• Fields are only added, never removed or renamed.

What counts as a breaking change

• Removing or renaming a field in a response.
• Removing or renaming a field in a request.
• Changing a field's type or format.
• Changing default sort, default pagination size, or default include set.
• Changing error codes for existing failure cases.
• Tightening validation (rejecting input we previously accepted).

What does NOT count as breaking:

• Adding a new field to a response. (Always be permissive in what your client accepts.)
• Adding a new optional field to a request.
• Adding a new endpoint.
• Adding a new error code for a previously-impossible failure mode.
• Performance improvements that change response time but not shape.

Deprecation policy

When we plan to deprecate something inside a major version (rare, but possible — e.g. a field that proved misleading):

1. We announce on /changelog with at least 6 months of notice.
2. Responses include a Sunset header pointing to the deprecation date.
3. Responses include a Deprecation header naming the deprecated field or endpoint.
4. The dashboard shows a banner if any of your keys are calling deprecated endpoints.

On the sunset date, the deprecated thing stops working and returns 410 Gone with a code naming the replacement.

Migrating to v2

When v2 ships, v1 remains supported for at least 12 months after v2 GA. The 12-month window plus the 24-month v1 commitment means: even if v2 ships immediately, v1 is supported for at least 24 months total.

We'll publish a migration guide on /docs/api/v2-migration when the time comes. The guide will include code-mod scripts where the change is mechanical.

Per-endpoint version negotiation

We do NOT support per-endpoint version negotiation via headers. The URL prefix is the only versioning surface. This simplifies client code (one base URL, never a per-call header).

Beta endpoints

New endpoints sometimes ship under /v1-beta/ for an initial period. Beta endpoints:

• Do NOT carry the stability guarantees of v1.
• Are subject to breaking changes with 14 days' notice.
• Are clearly marked in the docs reference.

When a beta endpoint stabilises, it migrates to /v1/ and we sunset the beta path with a 6-month deprecation window.

Discovering what's available

The OpenAPI spec is at:

https://api.aidomination.app/v1/openapi.json

It's the canonical reference. We update it on every release. Your CI can diff against the last-known version to detect any additions.

Test-mode and versioning

Both ad_live_ and ad_test_ keys access the same versioned URLs. There's no "beta tier" of keys.

Version-related metadata

Every response includes:

• X-AID-API-Version — the version that served the response (always matches the URL prefix).
• X-AID-API-Release — our internal release identifier. Useful for support tickets when behaviour changes mid-day during a rollout.