Every request to the ekko Climate API names the version it was built against and the API answers the way that version behaves. A change we make later reaches you only when you move to a new version.

❗️
The header is required
For now, a request without Ekko-Version is still served at the latest version. When this grace period ends, a request without the header is refused with API_VERSION_REQUIRED. Send the header now and the change will not affect you.

Send a version

Pass the version in the Ekko-Version header.

curl https://api.ekko.earth/v3/impact-partners \
  -H "Authorization: Bearer $EKKO_API_KEY" \
  -H "Ekko-Version: 2026-10-06.pangolin"

Send the same value on every request, from every part of your integration. Keep it in one place in your code, so moving to a new version is a single change. A browser page that calls the checkout endpoints sends it too.

The response carries an Ekko-Version header with the version it was served at. Log it alongside your request IDs.

Read a version name

A version is a release date and an animal, separated by a dot: 2026-10-06.pangolin.

The animal changes only when a release contains a breaking change. An animal is never reused, so the name alone tells you which generation you built against.
The date is the day a release went out. Releases that share an animal are backwards compatible with each other: moving from one date to a later one under the same animal never breaks a working integration.

The current version is 2026-10-06.pangolin.

Changes we make without a new version

These changes can reach you on any version, at any time. Build your integration so they don't break it:

New endpoints.
New optional request fields and new optional query parameters.
New fields in a response, including in nested objects.
New values in a field documented as an open set, such as the error code. Treat a value you don't recognise as the generic code for the response status.
New response headers.
A change to the order of fields in a response.
A change to the wording of a human-readable error message. Branch on code, never on error.
New error codes on an existing failure, where the response status is unchanged.

Anything else is a breaking change and ships under a new animal. That includes removing or renaming a field, changing a field's type, making an optional request field required and changing what a status code or error code means.

Move to a new version

When a new animal is released, we publish what changed and how to adapt. To move:

Read the changes between your version and the one you are moving to.
Update your code to handle them.
Change the Ekko-Version value and test against it before you deploy.

You can send the new version from one part of your integration while the rest stays on the old one. Each request is served at the version it names.

Handle version errors

A version error returns a 400 with one of these codes. details.latest_version names the current version. See Errors and error handling for the full error format.

Code	Cause
`API_VERSION_INVALID`	`Ekko-Version` is not a released version, either because it is not shaped like `YYYY-MM-DD.animal` or because no such version exists. A date in the future and a real date under the wrong animal are both refused.
`API_VERSION_REQUIRED`	The request carried no `Ekko-Version` header. Returned once the grace period ends.

{
  "error": "Ekko-Version is not a released version",
  "code": "API_VERSION_INVALID",
  "details": { "latest_version": "2026-10-06.pangolin" }
}