## Convert a ticket to another desk space or to a forge project (desk:write; agent in the ticket's space)

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

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

Header `Idempotency-Key` and the ticket's `version` are required. `target.module` desk: a move (`POST /items/{ref}/move`
semantics: same ticket and number, 200). `target.module` forge: the conversion contract (version 1) carries title,
description, type, status, custom fields by key, priority, dates, estimate, labels, assignees, watchers, the
reporter, the agents' comments with author, time, kind and visibility, uploaded files (same DMS documents), links and
the checklist (both listed in forge's note) and notes on what stays here (customer, contacts, mails, the requester's
messages, time, project, parent). Free text is scrubbed of customer data like a handoff; a confidential ticket goes
with full content and `confidential`. While forge has not confirmed, edits are 409 `conversion_pending`; once it has,
the ticket is the read-only tombstone (`convertedTo`, closed; a forwarding stub when it has requesters or people in
copy) with history `converted`. 201 confirmed, 202 pending (retried like a handoff), 422 `handoff_refused`,
409 `has_children` (sub-tickets), `converted`, `version_conflict`; 503 `forge_unavailable`.

### 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
- `version` (integer, required)

Example:

```json
{
  "target": {
    "container": "SUP",
    "module": "desk",
    "typeKey": "problem"
  },
  "version": 6
}
```

### Responses

- **200** Moved within desk (`application/json`)
- **201** Converted (`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/convert' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"target":{"container":"SUP","module":"desk","typeKey":"problem"},"version":6}'
```
