## List the handoffs and conversions of a ticket (desk:read; who sees the ticket)

`GET /api/desk/v1/items/{ref}/handoffs`

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

Both directions (`role` origin: this ticket was handed over or converted; receiver: it was received), newest first, with the cached state of the counterpart (`counterpartRef`, `counterpartStage`, `counterpartStatusName`), the delivery state (`syncState` pending/confirmed/failed, `lastError`) and the hand-back note. The counterpart's title is read from its own module (404 there: only the cached ref and state).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Responses

- **200** Handoffs (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Handoff, required)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row

Example 200 answer:

```json
{
  "items": [
    {
      "attempts": 1,
      "counterpartCheckedAt": "2026-11-16T10:02:00Z",
      "counterpartContainerId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "counterpartContainerKey": "APP",
      "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
      "counterpartModule": "forge",
      "counterpartRef": "APP-24",
      "counterpartStage": "active",
      "counterpartStatusKey": "in_arbeit",
      "counterpartStatusName": "In Arbeit",
      "createdAt": "2026-11-13T09:10:00Z",
      "createdByName": "Sophie Huber",
      "createdByRef": "sophie.huber@muster-it.example",
      "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b01",
      "itemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
      "kind": "handoff",
      "role": "origin",
      "state": "open",
      "syncState": "confirmed",
      "updatedAt": "2026-11-16T10:02:00Z",
      "version": 3
    }
  ]
}
```

### Example request

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