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 projectversion(integer, required): Version of the item the caller sawstatusKey(string): Status of the type's workflow in the target project (optional)typeKey(string): Item type of the target project (optional)
Example:
{
"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 assigneescreatedAt(string (date-time), required): When the item was createdcustomFields(object, required): Values of custom fields by field keydescription(string, required): Markdownid(string (uuid), required): Item idlabelIds(array of string (uuid), required): Label idslabels(array of string, required): Label namesnumber(integer, required): Number in the project (the 12 of APP-12)projectId(string (uuid), required): Project idprojectKey(string, required): Project keyrank(string, required): Order key, compared byte-wiseref(string, required): APP-12reporterRef(string, required): E-mail (or actor ref) of who created the itemstatusCategory(string, required): Category of the status (one oftriage,todo,active,on_hold,done,cancelled)statusId(string (uuid), required): Status idstatusKey(string, required): Status keystatusName(string, required): Status nametitle(string, required): TitletypeId(string (uuid), required): Item type idtypeKey(string, required): Item type keyupdatedAt(string (date-time), required): Last changeversion(integer, required): Optimistic-locking version; send it with PATCHwatchers(array of string, required): E-mail addresses of the watchersclosedAt(string (date-time), nullable): When the item reached a done or cancelled status; null while openconfidential(boolean): Visible only to tenant forge admins, members with role maintainer or higher, the reporter and the assigneesconvertedTo(object): Set on the tombstone of an item converted to another module (read-only)at(string (date-time), required): When it was convertedid(string (uuid), required): Id of the new itemmodule(string, required): Module of the new item (one ofdesk,forge)path(string, required): Portal path of the new itemref(string, required): #123 or APP-12
convertingSince(string (date-time)): Set while a conversion of the item is pendingdueOn(string (date), nullable): Due dateestimate(number, nullable): Estimate; null when noneiterationId(string (uuid), nullable): Iteration the item is in; null when noneiterationName(string, nullable): Name of the iterationmilestoneId(string (uuid), nullable): Milestone the item is in; null when nonemilestoneTitle(string, nullable): Title of the milestoneparentId(string (uuid), nullable): Parent item id; null without a parentparentNumber(integer, nullable): Number of the parent item; null without a parentresolution(string, nullable):returned: handed back to its origin;converted: the tombstone of a converted item (one ofdone,not_planned,duplicate,returned,converted,<nil>)spentMinutes(integer, nullable, read-only): Work HR booked on the item (subjectforge: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 writesstartOn(string (date), nullable): Planned start date
Example 200 answer:
{
"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
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}'