Hand an item over to a forge project or a desk space (tenant:forge:write and, as a member, at least developer)
POST /api/forge/v1/projects/{key}/items/{number}/handoffs
Module: Forge · operationId: createForgeItemHandoff · Tag: Handoffs · Auth: access token (Authorization: Bearer <accessToken>)
Requires the permission to change the item (forge write; CanEditItem). Creates a NEW linked item in the target (target.module forge: a project key the caller may create items in, the normal create path – type by key else the default, status by key else the first new status; desk: a space key, desk decides with the caller's permissions). Title, description and priority default to the item's (priority from a priority::/prioritaet:: label); a confidential item gives a confidential one. Header Idempotency-Key is required (400 without): the handoff id is derived from the item and the key, so a retry answers the same handoff. forge → forge: one transaction, 201 with both rows confirmed, history handoff_received / handed_off, events forge.handoff.received / forge.handoff.sent, automations on forge.item.handoff_received in the target. forge → desk: 201 once desk confirmed, 202 with the pending row while desk cannot be reached (retried every 30 s with backoff up to an hour; after 24 h the handoff fails with a system comment); a refusal by desk is 422 handoff_refused (row failed, system comment „Übergabe an … fehlgeschlagen: …“, forge.handoff.failed). 409 converted, conversion_pending, project_archived; 503 desk_unavailable when desk is not connected.
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
description(string): Description of the new item; empty = the item'spriority(string): Priority of the new item; default from the item's priority label (a forge target does not take it over)title(string): Title of the new item; empty = the item's
Example:
{
"description": "Nach dem Fix in der App (APP-9) bleiben alte Geräte-Tokens im Push-Dienst stehen; bitte einmalig bereinigen.",
"target": {
"container": "OPS",
"module": "forge",
"typeKey": "aufgabe"
},
"title": "Doppelte Push-Registrierungen im Push-Dienst bereinigen"
}
Responses
- 201 Handed off (
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:
{
"dropped": [
"priority"
],
"handoff": {
"attempts": 0,
"counterpartContainerId": "3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b",
"counterpartContainerKey": "OPS",
"counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5d0f",
"counterpartModule": "forge",
"counterpartRef": "OPS-15",
"counterpartStage": "new",
"counterpartStatusKey": "offen",
"counterpartStatusName": "Offen",
"createdAt": "2026-11-18T10:20:00Z",
"createdByName": "Paul Schmid",
"createdByRef": "paul.schmid@muster-it.example",
"id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b03",
"itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c09",
"kind": "handoff",
"projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
"role": "origin",
"state": "open",
"syncState": "confirmed",
"updatedAt": "2026-11-18T10:20:00Z",
"version": 1
},
"item": {
"assignees": [],
"confidential": false,
"createdAt": "2026-11-18T10:20:00Z",
"customFields": {},
"description": "Nach dem Fix in der App (APP-9) bleiben alte Geräte-Tokens im Push-Dienst stehen; bitte einmalig bereinigen.",
"id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5d0f",
"labelIds": [],
"labels": [],
"number": 15,
"projectId": "3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b",
"projectKey": "OPS",
"rank": "0000d0",
"ref": "OPS-15",
"reporterRef": "paul.schmid@muster-it.example",
"statusCategory": "todo",
"statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f22",
"statusKey": "offen",
"statusName": "Offen",
"title": "Doppelte Push-Registrierungen im Push-Dienst bereinigen",
"typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7c23",
"typeKey": "aufgabe",
"updatedAt": "2026-11-18T10:20:00Z",
"version": 1,
"watchers": [
"paul.schmid@muster-it.example"
]
}
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/handoffs' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Idempotency-Key: string' \
-H 'Content-Type: application/json' \
--data '{"description":"Nach dem Fix in der App (APP-9) bleiben alte Geräte-Tokens im Push-Dienst stehen; bitte einmalig bereinigen.","target":{"container":"OPS","module":"forge","typeKey":"aufgabe"},"title":"Doppelte Push-Registrierungen im Push-Dienst bereinigen"}'