## Hand an item over to a forge project or a desk space (tenant:forge:write and, as a member, at least developer)

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

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

Requires the permission to change the item (forge write; CanEditItem). Creates a NEW linked item in the target (`target.module` forge: a project key the caller may create items in, the normal create path – type by key else the default, status by key else the first new status; desk: a space key, desk decides with the caller's permissions). Title, description and priority default to the item's (priority from a `priority::`/`prioritaet::` label); a confidential item gives a confidential one. Header `Idempotency-Key` is required (400 without): the handoff id is derived from the item and the key, so a retry answers the same handoff. forge → forge: one transaction, 201 with both rows confirmed, history `handoff_received` / `handed_off`, events `forge.handoff.received` / `forge.handoff.sent`, automations on `forge.item.handoff_received` in the target. forge → desk: 201 once desk confirmed, 202 with the pending row while desk cannot be reached (retried every 30 s with backoff up to an hour; after 24 h the handoff fails with a system comment); a refusal by desk is 422 `handoff_refused` (row failed, system comment „Übergabe an … fehlgeschlagen: …“, `forge.handoff.failed`). 409 `converted`, `conversion_pending`, `project_archived`; 503 `desk_unavailable` when desk is not connected.

### 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
- `description` (string): Description of the new item; empty = the item's
- `priority` (string): Priority of the new item; default from the item's priority label (a forge target does not take it over)
- `title` (string): Title of the new item; empty = the item's

Example:

```json
{
  "description": "Nach dem Fix in der App (APP-9) bleiben alte Geräte-Tokens im Push-Dienst stehen; bitte einmalig bereinigen.",
  "target": {
    "container": "OPS",
    "module": "forge",
    "typeKey": "aufgabe"
  },
  "title": "Doppelte Push-Registrierungen im Push-Dienst bereinigen"
}
```

### Responses

- **201** Handed off (`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
{
  "dropped": [
    "priority"
  ],
  "handoff": {
    "attempts": 0,
    "counterpartContainerId": "3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b",
    "counterpartContainerKey": "OPS",
    "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5d0f",
    "counterpartModule": "forge",
    "counterpartRef": "OPS-15",
    "counterpartStage": "new",
    "counterpartStatusKey": "offen",
    "counterpartStatusName": "Offen",
    "createdAt": "2026-11-18T10:20:00Z",
    "createdByName": "Paul Schmid",
    "createdByRef": "paul.schmid@muster-it.example",
    "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b03",
    "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c09",
    "kind": "handoff",
    "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "role": "origin",
    "state": "open",
    "syncState": "confirmed",
    "updatedAt": "2026-11-18T10:20:00Z",
    "version": 1
  },
  "item": {
    "assignees": [],
    "confidential": false,
    "createdAt": "2026-11-18T10:20:00Z",
    "customFields": {},
    "description": "Nach dem Fix in der App (APP-9) bleiben alte Geräte-Tokens im Push-Dienst stehen; bitte einmalig bereinigen.",
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5d0f",
    "labelIds": [],
    "labels": [],
    "number": 15,
    "projectId": "3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b",
    "projectKey": "OPS",
    "rank": "0000d0",
    "ref": "OPS-15",
    "reporterRef": "paul.schmid@muster-it.example",
    "statusCategory": "todo",
    "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f22",
    "statusKey": "offen",
    "statusName": "Offen",
    "title": "Doppelte Push-Registrierungen im Push-Dienst bereinigen",
    "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7c23",
    "typeKey": "aufgabe",
    "updatedAt": "2026-11-18T10:20:00Z",
    "version": 1,
    "watchers": [
      "paul.schmid@muster-it.example"
    ]
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/handoffs' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"description":"Nach dem Fix in der App (APP-9) bleiben alte Geräte-Tokens im Push-Dienst stehen; bitte einmalig bereinigen.","target":{"container":"OPS","module":"forge","typeKey":"aufgabe"},"title":"Doppelte Push-Registrierungen im Push-Dienst bereinigen"}'
```
