Versions and changes

Sarah's booking app went live eighteen months ago and nobody has touched it since. It still works.

That's because her app is pinned to the version of the API that was current when she created it. We've shipped plenty since; none of it changed the answers her code already knew how to read.

The current version is 2026-08-01. Versions are dates.

Your side of the deal

One thing: ignore anything in a response you don't recognise.

We add fields to responses without changing the version, because adding is not breaking. If your code rejects unfamiliar fields — a strict schema, a parser configured to fail on unknown keys — then a routine addition on our side becomes an outage on yours.

// Fine. New fields arrive and nothing notices.
const { id, first_name, email } = customer;

// Fragile. Breaks the first time we add a field.
assertExactShape(customer, ['id', 'first_name', 'email']);

Same for field order, and for new values in an open-ended list like a booking status or a webhook event type.

What we'll change without warning

• New endpoints
• New optional fields on requests
• New fields in responses
• New values in open-ended lists
• New webhook event types

What gets a new version

• Removing or renaming a field or endpoint
• Changing a field's type
• Making an optional request field required
• Changing what an existing value means
• Changing a success status code

Checking which version you're on

Every response tells you:

HyphaBase-Version: 2026-08-01

Log it. When a response doesn't match what these guides say, that header is the first thing to look at — it's usually the answer.

Trying a new version before committing

Send the header on a single request to pin just that call:

curl https://api.hyphabase.com/api/modules/clients \
  -u sk_test_xxx: \
  -H "X-Location-Id: $HYPHABASE_LOCATION_ID" \
  -H "HyphaBase-Version: 2026-08-01"

An unsupported date is rejected rather than ignored, so a typo fails loudly instead of silently giving you something else.

The usual sequence: read what changed, try it against a few calls in your dev environment with the header, handle both shapes if you need a gradual rollout, then move the app across. The pin lives on the app — every environment shares it on purpose, so the code you promote from dev to prod always speaks the same shapes. The per-request header is how you rehearse a new version without moving anything.

Next