Migrating from legacy /public - Chatarmin CX Docs

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:

Deprecation: true
Sunset: Fri, 31 Oct 2026 23:59:59 GMT
Link: <https://docs.armin.cx/api/v1/migration>; rel="successor-version"

Why migrate

Legacy `/public/*`	Public API v1 `/public/v1/*`
Inconsistent envelopes	Unified `{ success, data }` + structured errors
Offset pagination (`page`, `page_size`)	Cursor pagination (`cursor`, `has_more`, `next_cursor`)
Ad-hoc list filters (dates, status)	Saved views via `view_id`
Full-access API keys	Scoped keys (`tickets:read` default)
No message thread endpoint	`GET /tickets/:ticketNumber/messages`
No saved views listing	`GET /views`

Base URL change

	URL
Legacy	`https://api.armin.cx/public`
v1	`https://api.armin.cx/public/v1`

Authentication is unchanged: cx-api-key header.

Response envelope

Legacy list (example):

{
  "success": true,
  "tickets": [ ... ],
  "page": 1,
  "total_pages": 10
}

v1 list:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_cursor": "..."
  }
}

Legacy error:

{
  "success": false,
  "message": "Something went wrong",
  "error": "..."
}

v1 error:

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "request_id": "req_..."
}

Branch on code, not message. See Errors.

Pagination migration

Legacy	v1
`page=2&page_size=50`	`cursor=<next_cursor>&limit=50`
`total_pages` / total count in body	`pagination.has_more` + `next_cursor` (no total on ticket lists)
Re-fetch page 1 to poll	Cursor walk + backoff; use view `count` for totals

See Pagination.

Endpoint mapping

Legacy endpoint	v1 equivalent	Notes
`GET /public/tickets` (list)	`GET /public/v1/views` + `GET /public/v1/tickets?view_id=...`	Encode list filters in a saved view
`GET /public/tickets` (by filters/date)	Saved view + `view_id`	No `date_from` / `date_to` on v1 list
`GET /public/tickets/:id` (if used)	`GET /public/v1/tickets/:ticketNumber`	v1 uses numeric ticket number in the path
—	`GET /public/v1/tickets/:ticketNumber/messages`	New — conversation thread for agents
—	`GET /public/v1/views`	New — discover saved views
`POST /public/tickets`	No v1 equivalent	Stay on legacy until v2; requires `tickets:write`
`POST /public/tickets/export`	No v1 equivalent	Stay on legacy; requires `tickets:export`
`GET /public/tickets/statistics`	No v1 equivalent	Stay on legacy; requires `analytics:read`
`GET /public/agents/metrics`	No v1 equivalent	Stay on legacy; requires `analytics:read`

Scopes during migration

Create new keys with explicit scopes:

Integration type	Recommended scopes
Read-only agent / sync	`tickets:read` only
Legacy create ticket	`tickets:read` + `tickets:write`
Legacy export	`tickets:read` + `tickets:export`
Legacy analytics	`tickets:read` + `analytics:read`

Keys with empty scopes (pre-migration) still have full access until rotated.

Migration checklist

Audit legacy usage

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

Create scoped v1 key

Settings → API — tickets:read for read paths.

Map filters to views

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

Update client code

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

Add message/thread fetch

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

Test in staging

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

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

Date	Event
v1 GA	`/public/v1/*` recommended for all new integrations
2026-10-31	Legacy `/public/*` sunset — endpoints may be removed

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

​Why migrate

​Base URL change

​Response envelope

​Pagination migration

​Endpoint mapping

​Scopes during migration

​Migration checklist

​Documentation and tools

OpenAPI v1 reference

Legacy OpenAPI

Getting started

Agent tool examples

​Timeline

Why migrate

Base URL change

Response envelope

Pagination migration

Endpoint mapping

Scopes during migration

Migration checklist

Documentation and tools

Timeline