Versioning

How the OpenCourt API changes without breaking your integration — dated versions, the OpenCourt-Version header, and webhook versions.

The OpenCourt API changes often. New fields, endpoints and signal types arrive all the time, and none of them breaks an integration. When a change would break one — a field removed, renamed or retyped — it ships as a new dated version, and your integration keeps the version it was built against until you choose to upgrade.

The current version is 2026-11-01. Every version is listed in the changelog.

Your key is pinned to a version

Each API key is pinned to the version that was current when it was created. Every request made with that key gets that version's shapes, whatever has been released since.

Every response states the version it was served at:

OpenCourt-Version: 2026-11-01

Choose a version for one request

Send the OpenCourt-Version header to use another version for one request — for example, to test your code against a newer version before you upgrade:

curl https://api.getopencourt.com/v1/customers \
  -H "Authorization: Bearer oc_live_xxxxxxxxxxxxxxxx" \
  -H "OpenCourt-Version: 2026-11-01"

A version that does not exist is a 400 with the code invalid_api_version, and the message lists the versions you can use.

Upgrade

When you are ready for a newer version:

Read what changed in the changelog.
Test your code with the OpenCourt-Version header set to the new version.
Ask the club admin to upgrade the key in Settings → OpenCourt API (Upgrade to … in the API version column). From the next request, the key gets the new version.

An upgrade never happens on its own.

Webhooks have their own version

Each webhook endpoint has an api_version. Every delivery to it is shaped by that version, and the envelope's api_version field says so.

An endpoint created through the API gets the version of the request that created it (your key's version, or the OpenCourt-Version header). Pass api_version to choose another.
Change it with PATCH /v1/webhook_endpoints/{id} and api_version, or let the club admin press Upgrade for the endpoint. The next delivery uses the new version.

A signal keeps the shape of the version it was created at or older. If you read an old signal at a newer version, it is returned as it was created, and its api_version tells you which version that was.

Deduplicate deliveries on the signal's id, not on the svix-id header. If an endpoint's version changes while a delivery is being retried, the same signal can arrive once for each version.

What is not a breaking change

These ship in any version, without notice. Build your integration to accept them:

a new field in a response, or a new optional parameter in a request;
a new endpoint, or a new signal type;
a new value in a field that has a fixed set of values (a status, a type);
a change to the wording of an error message (match on type and code, never on message).

When a version is retired

A version is retired only with notice. While a version is deprecated, every response at it carries:

Deprecation: @1830297600
Sunset: Mon, 01 Jan 2029 00:00:00 GMT
Link: <https://www.getopencourt.com/developers/changelog>; rel="deprecation"; type="text/html"

After the sunset, a key still pinned to the retired version gets a 400 with the code api_version_retired (the OpenCourt-Version header still works), and a webhook endpoint still on it is disabled with the reason. A key or endpoint is never moved to another version silently.