## List items (desk:read)

`GET /api/desk/v1/items`

Module: Desk · operationId: `listItems` · Tag: Items · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `space` | query | string |  | Space ids or keys (comma separated) |
| `type` | query | string |  | Type ids or keys |
| `status` | query | string |  |  |
| `phase` | query | string |  | new, active, waiting, done |
| `assignee` | query | string |  | User ref, `me` or `none` |
| `team` | query | string |  | Team ids or keys (comma separated); `mine` stands for the teams the caller is a member of. Items of any of these teams; an unknown team, or `mine` for a caller in no team, gives an empty list |
| `label` | query | string |  | All of these labels |
| `priority` | query | string |  |  |
| `project` | query | string |  | Project id or `none` |
| `projects` | query | string |  | Project ids (comma separated) |
| `projectTickets` | query | string |  | How tickets of projects show: `view` (ticket lists: tickets without project, of projects displaying tickets, and those assigned to the caller), `none` (without project), `only` (with project); omitted filters nothing (one of `view`, `none`, `only`) |
| `customer` | query | string |  | Customer ids (comma separated); items of any of these customers |
| `parent` | query | string |  | Parent id or `none` |
| `category` | query | string |  | Category ids (comma separated); items of these categories or of any category below them |
| `notSpace` | query | string |  | Space ids or keys (comma separated); items of none of these spaces. An unknown space excludes nothing |
| `notType` | query | string |  | Type ids or keys (comma separated); items of none of these types. An unknown type excludes nothing |
| `notStatus` | query | string |  | Status keys (comma separated); items in none of these statuses |
| `notTeam` | query | string |  | Team ids or keys (comma separated), `mine` for the teams the caller is a member of; items of none of these teams (an item in several teams is left out when any of them is listed). An unknown team, or `mine` for a caller in no team, excludes nothing |
| `notPriority` | query | string |  | Priority keys (comma separated); items with none of these priorities, items without priority stay |
| `notLabel` | query | string |  | Label ids (comma separated); items that have none of these labels. An unknown label excludes nothing |
| `notCustomer` | query | string |  | Customer ids (comma separated); items of none of these customers, items without customer stay |
| `notCategory` | query | string |  | Category ids (comma separated); items of none of these categories nor of any category below them, items without category stay. An unknown category excludes nothing |
| `notAssignee` | query | string |  | User ref or `me`; items this person does not work on (watchers do not count as working on it) |
| `q` | query | string |  | Full-text search |
| `number` | query | integer |  |  |
| `dueBefore` | query | string (date-time) |  |  |
| `slaState` | query | string |  | Comma-separated: none, running, warning, breached, paused, met |
| `slaDueBefore` | query | string (date-time) |  | Earliest running SLA deadline before |
| `createdAfter` | query | string (date-time) |  |  |
| `createdBefore` | query | string (date-time) |  | Created before (RFC 3339 or a date) |
| `closedAfter` | query | string (date-time) |  | Closed at or after (RFC 3339 or a date); items that are not closed are left out |
| `closedBefore` | query | string (date-time) |  | Closed before (RFC 3339 or a date); items that are not closed are left out |
| `updatedSince` | query | string (date-time) |  |  |
| `includeMerged` | query | boolean |  |  |
| `cf.{key}` | query | string |  | Custom field value (JSON or plain string) |
| `sort` | query | string |  | (one of `updated`, `created`, `number`, `due`, `priority`, `rank`, `title`, `sla`) |
| `order` | query | string |  | (one of `asc`, `desc`) |
| `limit` | query | integer |  | 1–500; another value is a 400 invalid. (default `100`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page (keyset: sort value and id of its last item). Valid only with the same `sort` and `order`, else 400 invalid with `field: cursor`. |

### Responses

- **200** A page of items (`application/json`)

Fields of the 200 answer:

- `items` (array of Item, required): Items of the page
- `total` (integer, required): Number of items matching the filter
- `nextCursor` (string): Cursor of the next page (keyset, bound to `sort` and `order`); missing on the last page.

Example 200 answer:

```json
{
  "items": [
    {
      "assignees": [
        {
          "role": "owner",
          "userRef": "lukas.wimmer@muster-it.example"
        },
        {
          "role": "assignee",
          "userRef": "sophie.huber@muster-it.example"
        }
      ],
      "createdAt": "2026-11-17T07:12:00Z",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
        "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
      },
      "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
      "labelIds": [
        "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
        "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
      ],
      "number": 1,
      "phase": "active",
      "priority": "hoch",
      "slaDueAt": "2026-11-17T15:12:00Z",
      "slaState": "running",
      "source": "phone",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "spentMinutes": 45,
      "status": "in_bearbeitung",
      "title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "updatedAt": "2026-11-17T08:55:00Z",
      "version": 6
    },
    {
      "assignees": [
        {
          "role": "owner",
          "userRef": "sophie.huber@muster-it.example"
        }
      ],
      "createdAt": "2026-11-13T08:20:00Z",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
        "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
      },
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
      "labelIds": [],
      "number": 37,
      "phase": "waiting",
      "priority": "normal",
      "slaDueAt": null,
      "slaState": "paused",
      "source": "portal",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "spentMinutes": 20,
      "status": "wartet_dritte",
      "title": "App zeigt gelöste Tickets weiterhin als offen",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "updatedAt": "2026-11-13T09:10:00Z",
      "version": 4
    }
  ],
  "nextCursor": "eyJ1cGRhdGVkQXQiOiIyMDI2LTExLTEzVDA5OjEwOjAwWiJ9",
  "total": 14
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
