## Move an item to another project (tenant:forge:write and, as a member, at least developer in the source; create rights in the target)

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

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

Requires the permission to change the item in this project (forge write) and a target project the caller sees; both projects are of the tenant and active. The item keeps its row and id and gets the next number of the target (a new reference); the old reference answers 404 `moved` with a redirect that follows the item to its current reference. Type by key (`typeKey`, else the same key, else the target's default type), status by key (`statusKey`, else the same key in the type's workflow, else the first status of the same category, else the initial one). Parent, milestone and iteration are cleared; labels (by name), custom fields and sections (by key) the target lacks are dropped and listed in `dropped`; section revisions are not kept (the current text becomes revision 1). History, comments, links, assignees and watchers follow. A confidential item stays confidential; the caller must still see it in the target (403 `confidential_target`). 409 `has_children` (an item with children), `converted` (tombstone), `conversion_pending`, `version_conflict`, `project_archived`. Writes `forge.item.moved` (with `fromProjectId`) and, when scm is connected, queues the relabel of the item's GitHub links.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `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)

- `project` (string, required): Key of the target project
- `version` (integer, required): Version of the item the caller saw
- `statusKey` (string): Status of the type's workflow in the target project (optional)
- `typeKey` (string): Item type of the target project (optional)

Example:

```json
{
  "project": "OPS",
  "typeKey": "fehler",
  "version": 5
}
```

### Responses

- **200** Moved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `dropped` (array of string, required): What the target has no place for: `label:<name>`, `section:<key>`, `customFields.<key>`
- `item` (Item, required)
  - `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 200 answer:

```json
{
  "dropped": [
    "label:owner::android",
    "label:plattform::android",
    "label:priority::hoch",
    "customFields.story_points"
  ],
  "item": {
    "assignees": [
      "paul.schmid@muster-it.example"
    ],
    "closedAt": null,
    "confidential": false,
    "createdAt": "2026-11-09T11:20:00Z",
    "customFields": {},
    "description": "Bei einer Antwort des Service Desks erscheint die Benachrichtigung auf Android zweimal.",
    "estimate": 3,
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c09",
    "iterationId": null,
    "iterationName": null,
    "labelIds": [
      "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8d24"
    ],
    "labels": [
      "bug"
    ],
    "milestoneId": null,
    "milestoneTitle": null,
    "number": 14,
    "parentId": null,
    "parentNumber": null,
    "projectId": "3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b",
    "projectKey": "OPS",
    "rank": "0000c0",
    "ref": "OPS-14",
    "reporterRef": "ben.koch@muster-it.example",
    "resolution": null,
    "statusCategory": "active",
    "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f23",
    "statusKey": "in_arbeit",
    "statusName": "In Arbeit",
    "title": "Push-Benachrichtigung erscheint doppelt",
    "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7c24",
    "typeKey": "fehler",
    "updatedAt": "2026-11-18T10:05:00Z",
    "version": 6,
    "watchers": [
      "ben.koch@muster-it.example",
      "emma.maier@muster-it.example",
      "paul.schmid@muster-it.example"
    ]
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/move' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"project":"OPS","typeKey":"fehler","version":5}'
```
