API Versioning

Cornect versions the API in the URL path. Knowing what we can change without warning — and what we can't — lets you build clients that won't break unexpectedly.

Current version#

The current and only version is v1, served under https://api.cornect.io/api/v1. There is no separate date-based or header-based versioning — the path segment is the version.

Breaking vs additive#

We distinguish two kinds of change:

Additive changes can land in v1 at any time, without notice. These include: new endpoints, new optional request parameters, and new fields in responses. Your client must tolerate unknown response fields and must not assume the set of fields is fixed.
Breaking changes ship as a new version (v2). These include: removing or renaming a field, changing a field's type, removing an endpoint, changing default behavior, or tightening validation in a way that rejects previously-valid requests.

Write tolerant clients

Parse only the fields you use and ignore the rest. Don't rely on field ordering, and don't fail when a new field appears. This keeps your integration working across all additive changes.

How v2 ships#

When a breaking change is necessary, it lands under a new path prefix (/api/v2). We'll announce v2 ahead of time via the changelog and to active API token owners by email, with a migration guide describing what changed. Your v1 integration keeps working unchanged when v2 launches.

Support policy#

When v2 launches, v1 remains supported for at least 12 months. During that window v1 continues to receive security fixes and stays available, giving you time to migrate on your own schedule. We'll communicate the v1 end-of-life date when v2 ships, and again as it approaches.