Aesesdocs

Versioning

The Aeses API is versioned through the URL path (/v1/) and, optionally, through the Api-Version header. We avoid breaking changes within a path version. When we must make one, we ship it behind a new dated version that you opt into explicitly.

Path version

The current major path version is /v1/. We will introduce /v2/ only for breaking changes that cannot be expressed as a dated minor version — for example, a full overhaul of the resource model.

Whenever /v2/ ships, /v1/ continues to operate for at least 12 months after the deprecation announcement.

Dated minor versions

For additive or backwards-compatible changes we cut dated versions of the form YYYY-MM-DD. The default version of your account is set in the dashboard. To pin a request to a specific version, send the Api-Version header:

Pin a request to a version
curl https://api.aeses.io/v1/deposits \
-H "x-api-key: sk_live_..." \
-H "Api-Version: 2026-01-15"

The response includes the version that handled the request:

Aeses-Version: 2026-01-15

What counts as backwards compatible

These changes are not considered breaking and can ship in any version:

  • Adding a new endpoint, resource, or webhook event.
  • Adding a new optional request parameter.
  • Adding a new field to a response object.
  • Adding a new enum value (clients must handle unknown enum values gracefully).
  • Adding a new HTTP header.
  • Changing the human-readable message of an error.

These changes are breaking and only ship in a new dated version:

  • Removing or renaming an endpoint, parameter, field, or enum value.
  • Changing the type of a field.
  • Changing default values that affect behavior.
  • Changing the type or code of an existing error.
  • Changing the structure of webhook payloads.

Deprecation policy

When we deprecate a field or endpoint:

  1. We announce the deprecation in the changelog and via a Sunset header on affected responses.
  2. The old behavior continues for at least 6 months.
  3. The new behavior becomes the default for new accounts on the cutover date.
  4. Existing accounts must opt in by updating their default version in the dashboard.

We never silently change behavior on a pinned version.

  • Pin a version in your default account setting and reproduce it in Api-Version headers for clarity.
  • Read the changelog before upgrading.
  • Test new versions in test mode before flipping live.