Versioning
Pin the behaviour you built against with one header. New versions never change an old one.
The API is versioned by a request header, not by its URL:
CoverPort-Version: 2026-11-20A version is the date a breaking change shipped. Send the version you built and tested against on every request, and your integration keeps behaving the same way when newer versions come out.
| Version | Status | Changes |
|---|---|---|
2026-11-20 | Current, beta | First version. |
Changes within 2026-11-20
These were added without a new version, because they only add to what the API accepts or returns:
Idempotency-Keyheader onPOST /quotesandPOST /buyers, with the error codesidempotency_in_progress,idempotency_outcome_unknown,idempotency_key_reusedandidempotency_unavailable.GET /purchases?quoteId=: find a purchase by theidfromPOST /quotes.GET /purchases?testMode=truelists test purchases, and every purchase has atestModefield. Without it,GET /purchaseslists live purchases, as before.- Requests the gateway refuses (a bad key, too many requests, an unknown route, a gateway failure) now have the usual error shape, with the codes
invalid_api_key,route_not_found,rate_limited,quota_exceeded,request_refusedandinternal_error, instead of{ "message": … }. This changed bodies that were never part of a working integration, while the API was not yet enabled for any partner.
How it works
- Every response says which version answered, in its own
CoverPort-Versionheader. - No header gets you the oldest version still supported. Code written without the header therefore keeps working, but send it anyway: when the oldest version is retired, requests without a header move to the next one.
- An unknown version is refused with
400anderror.code: "unsupported_version". The error'sdetailslists the versions that exist.
What changes without a new version
These are added to the current version at any time, so write your code to tolerate them:
- new endpoints
- new optional request fields and query parameters
- new fields in responses: ignore the ones you do not know
- new
error.codevalues: for one you do not know, act on the HTTP status
What needs a new version
Anything that could break code that works today: removing or renaming a field or endpoint, changing what a field means or its unit, making an optional field required, accepting less than before, or changing a status code. Each one ships as a new dated version, listed on this page with what changed and how to move to it. Your current version is not affected.
Retiring a version
A version is retired at least 90 days after its replacement ships. Before that, its responses carry Deprecation: true and Sunset: <date> headers, and we email the owners of every key that still uses it.
The SDKs
@cargolabs/coverport-js (the browser button) and @cargolabs/coverport-api (the typed server client) follow semantic versioning. While they are 0.x, a breaking change bumps the minor version. Pin them in your package.json.