API changelog

The Cairn API is versioned under /api/v1. Breaking changes are announced here and on the wire: a deprecated operation emits Deprecation: and Sunset: HTTP-date headers plus a Link: rel="deprecation" pointing at this page, months before removal (RFC 8594). If your integration logs response headers, you will see a retirement long before you need to read this page.

Current

• v1 — the current, supported version.

Deprecated

• POST /hooks/email/inbound/{token} (emailInboundWebhook) — deprecated 2026-10-09, sunset 2027-04-12 (PA-389). The inbound-email provider webhook with the workspace token in the path. Replaced by POST /hooks/email/inbound (emailInboundRoutedWebhook): one URL for the whole deployment, routing each message by its recipient address ({workspace inbound token}@{inbound domain}, or the reply+… Reply-To outbound mail carries). Same payload, same shared secret. Not a client API — only an inbound-mail provider calls it; it answers with the Deprecation / Sunset headers until removed.

Additions

Additive changes within v1. Nothing here changes or removes an existing field, and nothing here needs a code change from an existing integration.

2026-10-09

• Contact events: POST /events (PA-394). Record events about your contacts from your back end (first_order_placed, plan_upgraded) in batches of up to 100, naming each contact by contact_id, external_id or email; segments and in-app experience rules match on them. New ability events:write (granted with manage contacts). Well-formed events for a contact the workspace does not have come back by index in rejected; a malformed batch is 422 and writes nothing. Behind the workspace's public API and event-tracking flags.

• Widget: Cairn.track(name, properties?) (PA-394), backed by POST /widget/events, records the same events for the identified visitor — see widget-api.md.

• GET /workspaces/{workspace}/contact-event-names (PA-394) lists the event names recorded in the last 90 days, for rule pickers.

• Data exports: /workspaces/{workspace}/data-exports (PA-411) — createDataExport, listDataExports, getDataExport. Export every contact (with custom attributes), conversation (with messages) and ticket, or everything held about one contact, as JSON or CSV. Built in the background; a ready export carries a signed download link that works for 15 minutes and needs a manage workspace settings session; files are deleted after 7 days. Behind the workspace's data-export flag.

• Webhooks: contact.created and conversation.resolved (PA-405). Two new event types in the subscribable catalog (GET /webhook-event-types and the portal picker). contact.created carries contact_id, external_id, verified and created_at; conversation.resolved carries conversation_id, channel, kind, contact_id and resolved_at. Neither carries personal details or message text. Same envelope, signing, retries and redelivery as every other event — see webhooks.md §7.

• OAuth apps: registration and consent now honour the rollout flag (PA-405). Below the workspace's OAuth app platform flag, POST /workspaces/{workspace}/oauth-apps answers 404 (before validating the body), and the consent screen neither offers nor accepts that workspace. Listing and withdrawing apps, and listing and revoking installs, are unaffected, so access granted earlier can always be ended.