General
The Capacities API is versioned via a request header. This lets you pin your integration to the exact version it was built against and upgrade on your own schedule.
The current API version is — — you can also find it at the top of the Reference page.
Include X-Capacities-Api-Version in every request:
GET /space/structures HTTP/1.1
Host: api.capacities.io
Authorization: Bearer cap-api-AbCdEfGh...
X-Capacities-Api-Version: <version>
| Situation | Behavior |
|---|---|
| Header absent | Defaults to the current latest version |
| Header present, valid semver | Request is routed to that version |
| Header present, not valid semver | 400 with cap_invalid_input |
| Header present, below minimum supported version | 400 with cap_invalid_input and a message indicating the minimum |
Version format: MAJOR.MINOR.PATCH — standard semver. Examples: 1.0.0, 1.2.3.
Always send the version your integration was built against — not the latest. This protects you from breaking changes when you are not ready to upgrade.
When we release a new version we will communicate it via our newsletter and in What's new. You can then review the changelog and opt in by bumping the header value in your integration.
Create a ticket on our feedback board. - Let us know if you have an idea for a feature, improvement or think there is something missing.
Request additions to the documentation. - If your questions are not getting answered, let us know and we will extend the documentation.