Versioning and deprecation
API versions are named by their release date. A version keeps working for at least 18 months after the next one ships, and you hear about every deprecation long before anything stops.
How versions work
| Names | Each version is named after its release date, for example 2026-09-01. |
|---|---|
| Pinned per key | A new key starts on the latest version and stays there until you change it in Settings, under Integrations, then API keys. |
| Per request | Send the Gripz-Version header to try another version for one call before you move the key. |
curl "$BASE/conversations/cnv_7Hq2Lm" \
-H "Authorization: Bearer $GRIPZ_API_KEY" \
-H "Gripz-Version: 2026-09-01"What can change without a new version
Any version
Additive changes
- New endpoints
- New fields in responses
- New optional parameters
- New values in fields marked as extensible
New version only
Breaking changes
- Removing or renaming a field
- Changing a field's type or format
- Adding a required parameter
- Changing an error code or status
Write your client to ignore fields and enum values it does not know. That is all it takes to stay safe between versions.
Supported versions
| Version | Status | Released | Works until |
|---|---|---|---|
| 2026-09-01 | Current | 1 Sep 2026 | At least 18 months after the next version ships |
| 2026-03-01 | Deprecated | 1 Mar 2026 | 1 Mar 2028 |
How we tell you
Every deprecation follows the same path. This is the one in progress now.
- 2026-09-01 ships and 2026-03-01 is deprecated (done)1 Sep 2026
Changelog entry. Every response on 2026-03-01 now carries Deprecation and Sunset headers.
- Monthly email to key owners (done)Monthly
Owners of keys still on 2026-03-01 get the list of those keys and what changed.
- Final notice, six months ahead (to come)1 Sep 2027
Email to key owners and a banner in the developer console.
- 2026-03-01 is switched off (to come)1 Mar 2028
Requests that still ask for it get an error that names the current version.
HTTP/1.1 200 OK
Gripz-Version: 2026-03-01
Deprecation: @1788220800
Sunset: Wed, 01 Mar 2028 00:00:00 GMT
Link: <https://developers.gripz.example/changelog#2026-09-01>; rel="deprecation"