> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armin.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering & saved views

> Filter tickets with view_id and saved inbox views — no ad-hoc query params in v1.

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](/inbox/views-and-filters) in the product, then executed via the API.

## Standard workflow

<Steps>
  <Step title="List views">
    `GET /public/v1/views` — returns each view's `id`, `name`, `count`, and `filters` metadata.
  </Step>

  <Step title="Pick a view">
    Find the view that matches your use case (for example "Open — last 7 days" or "Returns").
  </Step>

  <Step title="List tickets">
    `GET /public/v1/tickets?view_id=<uuid>` — returns tickets matching that view's filters.
  </Step>
</Steps>

Example:

```bash theme={null}
# 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.

## Related

* [Agent tool examples](/api/agent-tool-examples) — "open tickets last 7 days" and view count patterns
* [Inbox views and filters](/inbox/views-and-filters) — create and manage views in the product