Filtering & saved views - Chatarmin CX Docs

In Public API v1, view_id is the only way to filter ticket lists. Status, channel, priority, assignee, tags, and date ranges must be encoded in a saved inbox view in the product, then executed via the API.

Standard workflow

List views

GET /public/v1/views — returns each view’s id, name, count, and filters metadata.

Pick a view

Find the view that matches your use case (for example “Open — last 7 days” or “Returns”).

List tickets

GET /public/v1/tickets?view_id=<uuid> — returns tickets matching that view’s filters.

Example:

# 1. Discover views
curl -sS -H "cx-api-key: $KEY" \
  "https://api.armin.cx/public/v1/views"

# 2. List tickets in a view
curl -sS -H "cx-api-key: $KEY" \
  "https://api.armin.cx/public/v1/tickets?view_id=019b0e3d-e88a-715c-b540-ea11ac058052&limit=40"

View response fields

Each view in GET /views includes:

Field	Use
`id`	Pass as `view_id` on `GET /tickets`
`name`	Human-readable label for agent tool selection
`count`	Current ticket count for that view — use for “how many?” without listing all tickets
`filters`	Filter definitions (condition + options) so agents can pick the right view
`shared`	Whether the view is shared with the team

Unfiltered list

Omit view_id to list all organization tickets (subject to pagination):

GET /public/v1/tickets?limit=40

Use this sparingly for large workspaces — prefer saved views to keep result sets bounded.

Sort order

Ticket list results are sorted by created_at descending, then ticket id descending. This differs from the inbox UI default (latest activity). If your view depends on “most recently updated” ordering, account for that when comparing API results to the UI.

What is NOT supported in v1

Unsupported	Alternative
`status=open` query param	Create a view filtered to open tickets
`channel=email` query param	Create a channel-filtered view
`date_from` / `date_to` query params	Create a view with date filters
Full-text / subject search	Create a view with search filters in the inbox
`message_body` filter	Not available via public API in v1
Combining `view_id` with extra filter params	Only `view_id`, `limit`, `cursor`, and `include` are accepted

Passing unknown query parameters returns 400 VALIDATION_ERROR.

View access rules

Agent-linked API keys — only views visible to that agent in the inbox.
Service keys (no linked agent) — all organization views.

Inaccessible view_id values return 404 VIEW_NOT_FOUND (not 403), including cross-org IDs and views hidden from the linked agent.

Optional expansion

Pass include=ticket_fields on GET /tickets or GET /tickets/:ticketNumber to include custom ticket field values in the response.

Agent tool examples — “open tickets last 7 days” and view count patterns
Inbox views and filters — create and manage views in the product

​Standard workflow

​View response fields

​Unfiltered list

​Sort order

​What is NOT supported in v1

​View access rules

​Optional expansion

​Related