Concepts

Versioning

The DMHero-Version header, the webhook schema version, and what is and is not a breaking change.

The API is versioned by date. The current version is 2026-10-08; supported: 2026-10-08.

Pinning a version

Send the version your code was written against on every request:

bash

curl https://api.dmhero.ai/v1/me \
  -H "Authorization: Bearer $DMHERO_API_KEY" \
  -H "DMHero-Version: 2026-10-08"

Without the header you get the default version, 2026-10-08 today.
An unknown version answers 400 API_VERSION_UNSUPPORTED_400.
Every response carries DMHero-Version with the version that answered it.

One version for the API and the webhooks

The API version and the webhook payload's schema_version (today 2026-10-08) move together. A breaking change to either ships a new date for both, and the old date keeps answering and rendering exactly as before, so an endpoint pinned to a schema version keeps receiving the payload it was built for.

What never changes the version

Additive changes ship without a new date. Write your code to tolerate them:

New operations and new paths.
New optional request fields and new query parameters.
New fields in responses and in webhook payloads. Ignore fields you do not know.
New webhook event types. An endpoint receives only the types it subscribed to.
New error codes for new situations. Branch on error, fall back on the HTTP status.
New values of an enumeration in a response, for example a new lead status. Treat an unknown value as "other".

What does

Removing or renaming a field, changing its type or meaning, making an optional input required, or changing a default. Each comes with a new version date and an entry in the changelog, and an old version is retired only after an announcement there, never silently.