/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):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 legacyPOST /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.Backfill
Before, a backfill had to stay under 500 tickets per request and returned413 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:
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.