## Hand a ticket over to a desk space or a forge project as a new linked item (desk:write; agent in the ticket's space)

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

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

Header `Idempotency-Key` is required (400 without): the handoff id is derived from the ticket and the key, so a
retry answers the same handoff. The ticket stays as it is; the new item is linked through the handoff (both
histories: `handed_off` here, `handoff_received` there; `desk.handoff.sent` / `.received`). Empty title,
description and priority are the ticket's; a confidential ticket gives a confidential item with its full content.
`target.module` desk: a ticket in the space `target.container` (key; the actor needs `desk:write` and the agent role
there, 403; type by key else the space's default, status by key) in one transaction, the automations of `desk.item.handoff_received` (a conversion: `desk.item.converted_from`) run;
201. `target.module` forge: project key `target.container`; forge checks the person's forge permissions. Title and
description are scrubbed of customer data first (customer name and number, contact, requester and participant
names → „[Kunde]“ / „[Kontakt]“, e-mail addresses → „[E-Mail]“). 201 once forge created the item; 202 with the
pending handoff while forge cannot be reached (retried every 30 s, backing off to an hour, failed after 24 hours with
a system entry „Übergabe an … fehlgeschlagen: …“); a refusal by forge is 422 `handoff_refused` (same entry). Without
forge configured 503 `forge_unavailable` (`forgeEnabled` in the bootstrap). A converted ticket is 409 `converted`,
a pending conversion 409 `conversion_pending`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes | (max length 200) |
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `target` (HandoffTarget, required)
  - `container` (string, required): Desk space key or forge project key
  - `module` (string, required): Module of the target (one of `desk`, `forge`)
  - `statusKey` (string): Status key of the new item
  - `typeKey` (string): Type key of the new item
- `description` (string): Markdown
- `priority` (string): Priority key (desk target) or label (forge target)
- `title` (string)

Example:

```json
{
  "description": "Im Kundenportal im Browser sind die Tickets richtig als gelöst markiert, in der App stehen sie tagelang unter „Offen“.",
  "priority": "priority::mittel",
  "target": {
    "container": "APP",
    "module": "forge",
    "typeKey": "fehler"
  },
  "title": "App zeigt gelöste Tickets weiterhin als offen"
}
```

### Responses

- **201** Handed over (`application/json`)
- **202** Pending (forge not reached yet) (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `handoff` (Handoff): Desk's side of a handoff or conversion (table `handoffs`).
  - `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
- `item` (Item)
- `notes` (array of string): What the receiver did not take over

Example 201 answer:

```json
{
  "handoff": {
    "attempts": 1,
    "counterpartContainerId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "counterpartContainerKey": "APP",
    "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
    "counterpartModule": "forge",
    "counterpartRef": "APP-24",
    "counterpartStage": "new",
    "counterpartStatusKey": "offen",
    "counterpartStatusName": "Offen",
    "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-13T09:10:02Z",
    "version": 2
  },
  "item": {
    "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",
    "number": 37,
    "phase": "waiting",
    "priority": "normal",
    "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
    "status": "wartet_dritte",
    "title": "App zeigt gelöste Tickets weiterhin als offen",
    "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
    "updatedAt": "2026-11-13T09:10:02Z",
    "version": 4
  },
  "notes": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/handoffs' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"description":"Im Kundenportal im Browser sind die Tickets richtig als gelöst markiert, in der App stehen sie tagelang unter „Offen“.","priority":"priority::mittel","target":{"container":"APP","module":"forge","typeKey":"fehler"},"title":"App zeigt gelöste Tickets weiterhin als offen"}'
```
