Hand a ticket over to a desk space or a forge project as a new linked item (desk:write; agent in the ticket's space)
POST /api/desk/v1/items/{ref}/handoffs
Module: Desk · operationId: createItemHandoff · Tag: Items · Auth: access token (Authorization: Bearer <accessToken>)
Header Idempotency-Key is required (400 without): the handoff id is derived from the ticket and the key, so a
retry answers the same handoff. The ticket stays as it is; the new item is linked through the handoff (both
histories: handed_off here, handoff_received there; desk.handoff.sent / .received). Empty title,
description and priority are the ticket's; a confidential ticket gives a confidential item with its full content.
target.module desk: a ticket in the space target.container (key; the actor needs desk:write and the agent role
there, 403; type by key else the space's default, status by key) in one transaction, the automations of desk.item.handoff_received (a conversion: desk.item.converted_from) run;
201. target.module forge: project key target.container; forge checks the person's forge permissions. Title and
description are scrubbed of customer data first (customer name and number, contact, requester and participant
names → „[Kunde]“ / „[Kontakt]“, e-mail addresses → „[E-Mail]“). 201 once forge created the item; 202 with the
pending handoff while forge cannot be reached (retried every 30 s, backing off to an hour, failed after 24 hours with
a system entry „Übergabe an … fehlgeschlagen: …“); a refusal by forge is 422 handoff_refused (same entry). Without
forge configured 503 forge_unavailable (forgeEnabled in the bootstrap). A converted ticket is 409 converted,
a pending conversion 409 conversion_pending.
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
description(string): Markdownpriority(string): Priority key (desk target) or label (forge target)title(string)
Example:
{
"description": "Im Kundenportal im Browser sind die Tickets richtig als gelöst markiert, in der App stehen sie tagelang unter „Offen“.",
"priority": "priority::mittel",
"target": {
"container": "APP",
"module": "forge",
"typeKey": "fehler"
},
"title": "App zeigt gelöste Tickets weiterhin als offen"
}
Responses
- 201 Handed over (
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/handoffs' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Idempotency-Key: string' \
-H 'Content-Type: application/json' \
--data '{"description":"Im Kundenportal im Browser sind die Tickets richtig als gelöst markiert, in der App stehen sie tagelang unter „Offen“.","priority":"priority::mittel","target":{"container":"APP","module":"forge","typeKey":"fehler"},"title":"App zeigt gelöste Tickets weiterhin als offen"}'