List the handoffs of an item (tenant:forge:read)
GET /api/forge/v1/projects/{key}/items/{number}/handoffs
Module: Forge · operationId: listForgeItemHandoffs · Tag: Handoffs · Auth: access token (Authorization: Bearer <accessToken>)
Requires tenant:forge:read and an item the caller sees. Both directions (role origin = handed off from this item, receiver = received), newest first, with the cached state of the counterpart.
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) |
Responses
- 200 Handoffs (
application/json) - 404 Error (
application/json)
Fields of the 200 answer:
items(array of Handoff, required)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
Example 200 answer:
{
"items": [
{
"attempts": 0,
"counterpartCheckedAt": "2026-11-13T10:12:00Z",
"counterpartContainerId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
"counterpartContainerKey": "SUP",
"counterpartItemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
"counterpartModule": "desk",
"counterpartRef": "#37",
"counterpartStage": "waiting",
"counterpartStatusKey": "wartet_dritte",
"counterpartStatusName": "Wartet auf Dritte",
"createdAt": "2026-11-13T10:10:00Z",
"createdByName": "Sophie Huber",
"createdByRef": "sophie.huber@muster-it.example",
"id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b01",
"itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
"kind": "handoff",
"projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
"role": "receiver",
"state": "open",
"syncState": "confirmed",
"updatedAt": "2026-11-13T10:12:00Z",
"version": 2
}
]
}
Example request
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/handoffs' \
-H "Authorization: Bearer $ACCESS_TOKEN"