CoverPort API and SDK are in beta. Endpoints and the embed may change without notice, and sales should be reconciled in the developer portal. Report problems to support@coverport.io.
CargoLabs Docs

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-20

A 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.

VersionStatusChanges
2026-11-20Current, betaFirst 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-Key header on POST /quotes and POST /buyers, with the error codes idempotency_in_progress, idempotency_outcome_unknown, idempotency_key_reused and idempotency_unavailable.
  • GET /purchases?quoteId=: find a purchase by the id from POST /quotes.
  • GET /purchases?testMode=true lists test purchases, and every purchase has a testMode field. Without it, GET /purchases lists 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_refused and internal_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-Version header.
  • 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 400 and error.code: "unsupported_version". The error's details lists 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.code values: 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.

On this page