Convert a ticket to another desk space or to a forge project (desk:write; agent in the ticket's space)
POST /api/desk/v1/items/{ref}/convert
Module: Desk · operationId: convertItem · Tag: Items · Auth: access token (Authorization: Bearer <accessToken>)
Header Idempotency-Key and the ticket's version are required. target.module desk: a move (POST /items/{ref}/move
semantics: same ticket and number, 200). target.module forge: the conversion contract (version 1) carries title,
description, type, status, custom fields by key, priority, dates, estimate, labels, assignees, watchers, the
reporter, the agents' comments with author, time, kind and visibility, uploaded files (same DMS documents), links and
the checklist (both listed in forge's note) and notes on what stays here (customer, contacts, mails, the requester's
messages, time, project, parent). Free text is scrubbed of customer data like a handoff; a confidential ticket goes
with full content and confidential. While forge has not confirmed, edits are 409 conversion_pending; once it has,
the ticket is the read-only tombstone (convertedTo, closed; a forwarding stub when it has requesters or people in
copy) with history converted. 201 confirmed, 202 pending (retried like a handoff), 422 handoff_refused,
409 has_children (sub-tickets), converted, version_conflict; 503 forge_unavailable.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key |
header | string | yes | (max length 200) |
ref |
path | string | yes | Item id or number |
Request body
application/json (required)
target(HandoffTarget, required)container(string, required): Desk space key or forge project keymodule(string, required): Module of the target (one ofdesk,forge)statusKey(string): Status key of the new itemtypeKey(string): Type key of the new item
version(integer, required)
Example:
{
"target": {
"container": "SUP",
"module": "desk",
"typeKey": "problem"
},
"version": 6
}
Responses
- 200 Moved within desk (
application/json) - 201 Converted (
application/json) - 202 Pending (forge 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:
handoff(Handoff): Desk's side of a handoff or conversion (tablehandoffs).attempts(integer): Delivery attempts so farcounterpartCheckedAt(string (date-time)): When the other side was last synchronisedcounterpartContainerId(string (uuid)): Space or project id of the other sidecounterpartContainerKey(string): Space or project key of the other sidecounterpartItemId(string (uuid)): Item id of the other sidecounterpartModule(string): Module of the other side (one ofdesk,forge)counterpartRef(string): Reference of the other side's item (e.g. #42 or APP-12)counterpartStage(string): Last known stage of the other side's item (gone: deleted) (one ofnew,active,waiting,done,cancelled,gone)counterpartStatusKey(string): Last known status key of the other side's itemcounterpartStatusName(string): Last known status name of the other side's itemcreatedAt(string (date-time)): When the handoff was startedcreatedByName(string): Name of who started the handoffcreatedByRef(string): Login (e-mail) of who started the handoffid(string (uuid)): Id of the handoffitemId(string (uuid)): Desk item of this sidekind(string): handoff (a new linked item) or conversion (the item moved) (one ofhandoff,conversion)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 loggednextAttemptAt(string (date-time)): When delivery is tried next (pending)returnNote(string): Note given when the item was handed backreturnedAt(string (date-time)): When the item was handed backreturnedByName(string): Name of who handed it backreturnedByRef(string): Login (e-mail) of who handed it backrole(string): origin: this ticket handed over; receiver: this ticket was received (one oforigin,receiver)state(string): State of the handoff (one ofopen,handed_back,closed,converted)syncState(string): Delivery to the other module: pending, confirmed or failed (one ofpending,confirmed,failed)updatedAt(string (date-time)): When the handoff row last changedversion(integer): Version of the handoff row
item(Item)notes(array of string): What the receiver did not take over
Example 201 answer:
{
"handoff": {
"attempts": 1,
"counterpartContainerId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
"counterpartContainerKey": "APP",
"counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
"counterpartModule": "forge",
"counterpartRef": "APP-24",
"counterpartStage": "new",
"counterpartStatusKey": "offen",
"counterpartStatusName": "Offen",
"createdAt": "2026-11-13T09:10:00Z",
"createdByName": "Sophie Huber",
"createdByRef": "sophie.huber@muster-it.example",
"id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b01",
"itemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
"kind": "handoff",
"role": "origin",
"state": "open",
"syncState": "confirmed",
"updatedAt": "2026-11-13T09:10:02Z",
"version": 2
},
"item": {
"createdAt": "2026-11-13T08:20:00Z",
"customer": {
"id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
"name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
},
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
"number": 37,
"phase": "waiting",
"priority": "normal",
"spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
"status": "wartet_dritte",
"title": "App zeigt gelöste Tickets weiterhin als offen",
"typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
"updatedAt": "2026-11-13T09:10:02Z",
"version": 4
},
"notes": []
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/convert' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Idempotency-Key: string' \
-H 'Content-Type: application/json' \
--data '{"target":{"container":"SUP","module":"desk","typeKey":"problem"},"version":6}'