Skip to main content
Legacy public endpoints under /public/* are deprecated and sunset on 31 October 2026. New integrations should use /public/v1/*. Every legacy response includes deprecation headers:

Why migrate

Base URL change

Authentication is unchanged: cx-api-key header.

Response envelope

Legacy list (example):
v1 list:
Legacy error:
v1 error:
Branch on code, not message. See Errors.

Pagination migration

See Pagination.

Endpoint mapping

Migrating the ticket export

The v1 export replaces the legacy export for nightly syncs and backfills. It runs in the background, handles up to 50,000 tickets in one export, and has no per-ticket message rate limit. The legacy POST /public/tickets/export stays available.

Nightly sync

Before, the sync listed tickets with legacy calls and loaded the messages of each ticket. Now it is one export and a few status checks.
1

Use a saved view

Keep the tickets you sync in a saved view and read its id from GET /public/v1/views.
2

Create the export

POST /public/v1/ticket-exports with { "view_id": "<view id>", "include_messages": true }. The response is 202 with the export in status queued.
3

Poll until it is ready

GET /public/v1/ticket-exports/<export id> every few seconds until status is completed.
4

Download and parse

Download download_url, unzip it, and read tickets.csv and messages.csv. Adjust your parser for the value changes in the table above.
Before (legacy export, at most 500 tickets, the file is the response):
After (v1 export, up to 50,000 tickets, in the background):

Backfill

Before, a backfill had to stay under 500 tickets per request and returned 413 TOO_MANY_TICKETS above that, so it ran as many small date ranges. Now you export by creation date and one export holds up to 50,000 tickets. Dates are UTC and inclusive. You can have 2 exports running at once. Before:
After:
Poll the export, download the file, then create the next range. If a range matches more than 50,000 tickets, the request fails with EXPORT_TOO_LARGE; use smaller ranges. See Ticket exports for every field, status, and limit.

Scopes during migration

Create new keys with explicit scopes: Keys with empty scopes (pre-migration) still have full access until rotated.

Migration checklist

1

Audit legacy usage

List which /public/* endpoints your integration calls today.
2

Create scoped v1 key

Settings → API — tickets:read for read paths.
3

Map filters to views

For each legacy list filter, create or identify a matching saved inbox view.
4

Update client code

Switch base URL, envelope parsing, and pagination to cursor model.
5

Add message/thread fetch

Replace custom workarounds with GET /tickets/:ticketNumber/messages.
6

Test in staging

Verify view access for agent-linked keys vs service keys.
7

Deploy and rotate

Deploy v1 client, then delete legacy-only API keys.

Documentation and tools

OpenAPI v1 reference

Interactive Scalar docs for all v1 endpoints.

Legacy OpenAPI

Deprecated /public/* reference (sunset Oct 2026).

Getting started

First v1 request walkthrough.

Agent tool examples

AI agent patterns on v1.

Timeline

Plan migration before the sunset date. Legacy analytics endpoints have no v1 replacement yet — keep scoped legacy keys only for those calls until v2.