Versions and deprecations

This policy applies to the whole integration API: REST API v1, widget, outbound and inbound webhooks, SCIM 2.0. The internal calls used by the Core, Workspace and Desk portals are not covered and can change at any time: do not use them in integrations.

Major versions

• The major version is in the path: /api/v1/…. Every /api/v1 response contains X-Exo-API-Version: 1.
• v1 is stable. Within v1 we make only compatible changes:
  • new endpoints, new optional fields in requests, new query parameters;
  • new fields in responses: your client must ignore the ones it does not know;
  • new webhook event types: your system must ignore the ones it does not know;
  • new error codes: handle unknown ones based on the HTTP status;
  • new optional headers.
• An incompatible change requires a new major version (/api/v2). Removing or renaming a field, an endpoint or an event, changing a type, making an optional field required or changing authentication are incompatible changes.
• When a new major version comes out, the previous one stays available for at least 12 months.

Deprecations

• A deprecated feature keeps working for at least 6 months after the announcement.
• Responses that use a deprecated feature contain:
  • Deprecation: @<unix-seconds>: when the deprecation was announced (RFC 9745);
  • Sunset: <HTTP-date>: when the feature will stop working (RFC 8594);
  • Link: <url>; rel="deprecation": the migration guide.
• Every deprecation is in the changelog and is marked as deprecated in the OpenAPI specification.

Current deprecations

Feature	Announced	Stops working	What to use
nh_… API keys	1 November 2026	30 June 2027	nhk.<keyid>.<secret> keys
X-NH-Signature signature on outbound webhooks	1 November 2026	30 June 2027	X-Exo-Signature with X-Exo-Timestamp
X-NH-Connector-Signature signature on inbound webhooks	1 November 2026	30 June 2027	X-Exo-Signature with X-Exo-Timestamp
event, timestamp, source fields in the webhook body	1 November 2026	30 June 2027	type, created_at, data

Specification and changelog

• The OpenAPI specification is the contract. Its version follows semantic versioning 1.MINOR.PATCH: MINOR increases for compatible additions, PATCH for documentation-only fixes.
• Every API change updates the specification version and adds an entry to the changelog.