API versioning
We version our API so that we can keep improving it without breaking your integration unexpectedly. This guide explains how versioning works, what does and doesn't count as a breaking change, and how to keep track of the version you're using.
Specifying a version
Pass the version you want in the Griffin-Version header on every request:
curl "https://api.griffin.com/organizations/og.o1rsp7efTN6CpMRybuu4OA" \
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H "Griffin-Version: 2026-07-09"
Versions are named using a date, in yyyy-MM-dd format.
Your organisation's default version
Every organisation has a default API version. The default version defines which version the events will be created at.
If you don't supply a Griffin-Version header, your request uses this default. You can view and change your default version in the Griffin app under Settings > API version.
If something goes wrong after an upgrade, you can roll back to your previous version within 72 hours.
What's in a new version
Each new version bundles together the changes we've made since the last version, along with any new functionality we've built in the meantime: new optional fields, new endpoints, new payment rails, or entirely new products. New functionality is only ever added to the latest version, not backported to versions you're already using.
| Change type | Breaking? | Available on |
|---|---|---|
| Bug fixes, performance improvements with no schema change | No | All supported versions |
| New endpoints | No | Introduced in a new version |
| New optional fields added to requests or responses | No | Introduced in a new version |
| New payment rails or new products | No | Introduced in a new version |
| Removal or renaming of existing fields | Yes | Introduced in a new version |
| Changes to field types or formats | Yes | Introduced in a new version |
| Changes to authentication or authorisation behaviour | Yes | Introduced in a new version |
Where we can, we'll batch multiple breaking changes into a single version so you don't need to migrate more often than necessary.
Version lifecycle
| Stage | What it means |
|---|---|
| Current | The latest version, actively developed |
| Supported | An older version, still fully functional |
| Deprecated | Outside standard support window, still functional, plan your migration |
| Sunset | No longer served, requests return an error |
Keeping track of changes
Every release comes with:
- A changelog entry describing what changed, which endpoints are affected, and what you need to do
- An email to your organisation's technical contacts
You can see the full history of released versions, and browse the API reference for each one, from the version selector in our API reference.
Moving from v0/
If you integrated with Griffin before versioning was introduced (October 2026), your requests use the v0/ prefix. The versioned API is served from the root path, with no prefix. Your existing v0/ endpoints will keep working.
The Griffin-Version header applies to the versioned API only. Requests to v0/ ignore the header.
Events and webhooks
We only create and send events supported by your current API version. Historic events are stored using the API version format that was in use when they were created.
After a default version roll back, events introduced in the newer version stop being generated. Events are stored based on the default version at the time they were created, so upgrades and rollbacks don’t affect past events. Event types that only exist in newer versions will not be returned in older versions. Events whose payload has changed in newer versions will be returned with an "unsupported payload" message in older versions.
Testing a new version
As soon as a new version is released, you can start sending requests with the new Griffin-Version header against your sandbox environment. There's no obligation to move your production traffic until you're ready.