## Convert an item into another project or a desk ticket (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/convert`

Module: Forge · operationId: `convertForgeItem` · Tag: Handoffs · Auth: access token (`Authorization: Bearer <accessToken>`)

Requires the permission to change the item (forge write; CanEditItem), header `Idempotency-Key` and the item's `version`. `target.module` forge: the move to another project (`POST …/move`, 200 with the moved item and `dropped`). `target.module` desk: an internal desk ticket in the space `target.container` with title, description, type and status (by key, else the stage), custom fields by key, labels, dates, assignees, watchers, the reporter, the comments (author, kind, time), the attachments (the same DMS documents), the links and sections listed in desk's note and `confidential` (A2). While desk has not confirmed, the item is read-only (409 `conversion_pending`, 202 with the pending row); once confirmed (201) the item stays as a read-only tombstone: first cancelled status, resolution `converted`, `convertedTo {module, id, ref, path, at}`, left out of lists, boards and metrics, every write 409 `converted`; history `converted`, event `forge.handoff.sent`. Refusals and failures as for handoffs (422 `handoff_refused`, 24 h). 409 `has_children`, `version_conflict`, `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes | (max length 200) |
| `key` | path | string | yes | Project key (e.g. APP) |
| `number` | path | integer | yes | Item number in the project (12 of APP-12) |

### Request body

`application/json` (required)

- `target` (HandoffTargetRef, required)
  - `container` (string, required): Desk space key or forge project key
  - `module` (string, required): Target module (one of `desk`, `forge`)
  - `statusKey` (string): Status of the new item; default the first status of the stage
  - `typeKey` (string): Item type (forge) or ticket type (desk) of the new item; default the target's default
- `version` (integer, required): Version of the item the caller saw (409 `version_conflict` when it changed)

Example:

```json
{
  "target": {
    "container": "SUP",
    "module": "desk",
    "typeKey": "serviceanfrage"
  },
  "version": 3
}
```

### Responses

- **200** Moved within forge (`application/json`)
- **201** Converted (the item is the tombstone) (`application/json`)
- **202** Pending (desk 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:

- `dropped` (array of string): What the target did not take over (a move: `label:<name>`, …; a forge handoff: the priority)
- `handoff` (Handoff)
  - `counterpartModule` (string, required): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string, required): Reference of the item on the other side (#123 or APP-12)
  - `counterpartStage` (string, required): Last known stage of the other item; `gone` when it no longer exists (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `createdAt` (string (date-time), required): When the handoff was started
  - `id` (string (uuid), required): Handoff id, shared with the other side
  - `itemId` (string (uuid), required): The forge item of this side
  - `kind` (string, required): `handoff`: a new linked item; `conversion`: the item moved and left a tombstone (one of `handoff`, `conversion`)
  - `role` (string, required): Which side this row is: the origin (handed over) or the receiver (one of `origin`, `receiver`)
  - `state` (string, required): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string, required): Delivery to the other side: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last checked
  - `counterpartContainerId` (string): Desk space or forge project id of the other side (once known)
  - `counterpartContainerKey` (string): Desk space key or forge project key of the other side
  - `counterpartItemId` (string): Id of the item on the other side (once known)
  - `counterpartStatusKey` (string): Last known status key of the other item
  - `counterpartStatusName` (string): Last known status name of the other item
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): E-mail of who started the handoff
  - `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)): Next delivery attempt while pending
  - `projectId` (string (uuid)): Project of the forge item
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When it was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): E-mail of who handed it back
  - `updatedAt` (string (date-time)): Last change of this side
  - `version` (integer): Version of this row
- `item` (Item)
  - `assignees` (array of string, required): E-mail addresses of the assignees
  - `createdAt` (string (date-time), required): When the item was created
  - `customFields` (object, required): Values of custom fields by field key
  - `description` (string, required): Markdown
  - `id` (string (uuid), required): Item id
  - `labelIds` (array of string (uuid), required): Label ids
  - `labels` (array of string, required): Label names
  - `number` (integer, required): Number in the project (the 12 of APP-12)
  - `projectId` (string (uuid), required): Project id
  - `projectKey` (string, required): Project key
  - `rank` (string, required): Order key, compared byte-wise
  - `ref` (string, required): APP-12
  - `reporterRef` (string, required): E-mail (or actor ref) of who created the item
  - `statusCategory` (string, required): Category of the status (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
  - `statusId` (string (uuid), required): Status id
  - `statusKey` (string, required): Status key
  - `statusName` (string, required): Status name
  - `title` (string, required): Title
  - `typeId` (string (uuid), required): Item type id
  - `typeKey` (string, required): Item type key
  - `updatedAt` (string (date-time), required): Last change
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
  - `watchers` (array of string, required): E-mail addresses of the watchers
  - `closedAt` (string (date-time), nullable): When the item reached a done or cancelled status; null while open
  - `confidential` (boolean): Visible only to tenant forge admins, members with role maintainer or higher, the reporter and the assignees
  - `convertedTo` (object): Set on the tombstone of an item converted to another module (read-only)
    - `at` (string (date-time), required): When it was converted
    - `id` (string (uuid), required): Id of the new item
    - `module` (string, required): Module of the new item (one of `desk`, `forge`)
    - `path` (string, required): Portal path of the new item
    - `ref` (string, required): #123 or APP-12
  - `convertingSince` (string (date-time)): Set while a conversion of the item is pending
  - `dueOn` (string (date), nullable): Due date
  - `estimate` (number, nullable): Estimate; null when none
  - `iterationId` (string (uuid), nullable): Iteration the item is in; null when none
  - `iterationName` (string, nullable): Name of the iteration
  - `milestoneId` (string (uuid), nullable): Milestone the item is in; null when none
  - `milestoneTitle` (string, nullable): Title of the milestone
  - `parentId` (string (uuid), nullable): Parent item id; null without a parent
  - `parentNumber` (integer, nullable): Number of the parent item; null without a parent
  - `resolution` (string, nullable): `returned`: handed back to its origin; `converted`: the tombstone of a converted item (one of `done`, `not_planned`, `duplicate`, `returned`, `converted`, `<nil>`)
  - `spentMinutes` (integer, nullable, read-only): Work HR booked on the item (subject `forge:item:<id>`, worked minus breaks, ADR 0040); filled by the item read and the item lists, null when HR does not answer (never an error) and in answers of writes
  - `startOn` (string (date), nullable): Planned start date

Example 201 answer:

```json
{
  "handoff": {
    "attempts": 1,
    "counterpartContainerId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
    "counterpartContainerKey": "SUP",
    "counterpartItemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c4a",
    "counterpartModule": "desk",
    "counterpartRef": "#74",
    "counterpartStage": "new",
    "counterpartStatusKey": "neu",
    "counterpartStatusName": "Neu",
    "createdAt": "2026-11-16T09:45:00Z",
    "createdByName": "Emma Maier",
    "createdByRef": "emma.maier@muster-it.example",
    "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b04",
    "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c17",
    "kind": "conversion",
    "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "role": "origin",
    "state": "converted",
    "syncState": "confirmed",
    "updatedAt": "2026-11-16T09:45:02Z",
    "version": 2
  },
  "item": {
    "assignees": [],
    "closedAt": "2026-11-16T09:45:02Z",
    "convertedTo": {
      "at": "2026-11-16T09:45:02Z",
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c4a",
      "module": "desk",
      "path": "/desk/tickets/74",
      "ref": "#74"
    },
    "createdAt": "2026-11-13T08:30:00Z",
    "customFields": {},
    "description": "Zugang zur Kundenportal-App für eine neue Mitarbeiterin einrichten.",
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c17",
    "labelIds": [],
    "labels": [],
    "number": 23,
    "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "projectKey": "APP",
    "rank": "0000e0",
    "ref": "APP-23",
    "reporterRef": "emma.maier@muster-it.example",
    "resolution": "converted",
    "statusCategory": "cancelled",
    "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06",
    "statusKey": "verworfen",
    "statusName": "Verworfen",
    "title": "App-Zugang für neue Mitarbeiterin im Sekretariat",
    "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
    "typeKey": "aufgabe",
    "updatedAt": "2026-11-16T09:45:02Z",
    "version": 4,
    "watchers": [
      "emma.maier@muster-it.example"
    ]
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/convert' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"target":{"container":"SUP","module":"desk","typeKey":"serviceanfrage"},"version":3}'
```
