Versioning

The Lynkist Public API and Lynkist webhooks have one version, written MAJOR.MINOR — for example 1.0, 1.1, 2.0. This page is the contract: what we can change without a new major version, how you see the version, and how long an old version works.

The rules

A client written for 1.0 works unchanged on every 1.x.

What a minor version can do

• Add an endpoint or a webhook event type.
• Add an optional request parameter or body field.
• Add a field to a response or to a webhook payload.
• Add a value to an enum in a response or a payload (for example a new status).
• Add an error code for a new feature.
• Add a response header.
• Make validation less strict.

What needs a major version

• Removing or renaming an endpoint, a field, a parameter or an event.
• Changing the type, the format or the meaning of a field.
• Adding a required parameter, or making an optional one required.
• Changing a default value, or making validation stricter.
• Changing the HTTP status or the error code of an existing case.
• Removing an enum value.

Every change, minor or major, is in the Changelog under its version.

Write a tolerant client

Minor versions add things. For your integration to keep working, your code must:

• Ignore fields it does not know, in responses and in webhook payloads.
• Accept enum values it does not know (handle an unknown status as "other").
• Ignore webhook event types it does not know. Return 2xx for them.
• Ignore response headers it does not know.
• Branch on error.code, never on the text of error.message.

How you see the version

Public API. The major version is in the URL:

https://lynkist.io/api/v1/public/contacts

Every response carries the exact version in a header, also on errors:

Lynkist-Version: 1.0

Webhooks. Each webhook endpoint has an api_version. Every delivery to it carries the exact version, in the Lynkist-Version header and in the body:

{ "id": "evt_…", "type": "contact.created", "api_version": "1.0", "…": "…" }

You do not send a version header on a request. Minor versions are compatible, so there is no reason to stay on an older minor.

Choosing the version of a webhook endpoint

A new endpoint gets the latest major version. To choose one, send api_version when you create or update the endpoint:

curl -X POST https://lynkist.io/api/v1/public/webhooks \
  -H "Authorization: Bearer $LYNKIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/lynkist", "events": ["message.received"], "api_version": "1" }'

Only the major is stored ("1" and "1.3" mean the same). An endpoint stays on its major version until you change it. A new major version never changes the payloads of an endpoint that exists.

Support window and deprecation

• When a new major version is released, the old one is deprecated.
• A deprecated major version works for at least 12 months after the next major is released.
• The date it stops working (the sunset date) is in the changelog.

Every response and every webhook delivery of a deprecated version says so in standard headers:

Lynkist-Version: 1.7
Deprecation: @1798761600
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://lynkist.io/developers/versioning>; rel="deprecation"

Deprecation (RFC 9745) is the time the version was deprecated, as Unix seconds after @. Sunset (RFC 8594) is the time it stops working. Log a warning when you see either header.

The current version