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 keymodule(string, required): Target module (one ofdesk,forge)statusKey(string): Status of the new item; default the first status of the stagetypeKey(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 (409version_conflictwhen it changed)
Example:
{
"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 ofdesk,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;gonewhen it no longer exists (one ofnew,active,waiting,done,cancelled,gone)createdAt(string (date-time), required): When the handoff was startedid(string (uuid), required): Handoff id, shared with the other sideitemId(string (uuid), required): The forge item of this sidekind(string, required):handoff: a new linked item;conversion: the item moved and left a tombstone (one ofhandoff,conversion)role(string, required): Which side this row is: the origin (handed over) or the receiver (one oforigin,receiver)state(string, required): State of the handoff (one ofopen,handed_back,closed,converted)syncState(string, required): Delivery to the other side: pending, confirmed or failed (one ofpending,confirmed,failed)attempts(integer): Delivery attempts so farcounterpartCheckedAt(string (date-time)): When the other side was last checkedcounterpartContainerId(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 sidecounterpartItemId(string): Id of the item on the other side (once known)counterpartStatusKey(string): Last known status key of the other itemcounterpartStatusName(string): Last known status name of the other itemcreatedByName(string): Name of who started the handoffcreatedByRef(string): E-mail of who started the handofflastError(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 loggednextAttemptAt(string (date-time)): Next delivery attempt while pendingprojectId(string (uuid)): Project of the forge itemreturnNote(string): Note given when the item was handed backreturnedAt(string (date-time)): When it was handed backreturnedByName(string): Name of who handed it backreturnedByRef(string): E-mail of who handed it backupdatedAt(string (date-time)): Last change of this sideversion(integer): Version of this row
item(Item)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 201 answer:
{
"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
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}'