ConnectCloud Developers

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 of desk, 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; gone when it no longer exists (one of new, active, waiting, done, cancelled, gone)
    • createdAt (string (date-time), required): When the handoff was started
    • id (string (uuid), required): Handoff id, shared with the other side
    • itemId (string (uuid), required): The forge item of this side
    • kind (string, required): handoff: a new linked item; conversion: the item moved and left a tombstone (one of handoff, conversion)
    • role (string, required): Which side this row is: the origin (handed over) or the receiver (one of origin, receiver)
    • state (string, required): State of the handoff (one of open, handed_back, closed, converted)
    • syncState (string, required): Delivery to the other side: pending, confirmed or failed (one of pending, confirmed, failed)
    • attempts (integer): Delivery attempts so far
    • counterpartCheckedAt (string (date-time)): When the other side was last checked
    • counterpartContainerId (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 side
    • counterpartItemId (string): Id of the item on the other side (once known)
    • counterpartStatusKey (string): Last known status key of the other item
    • counterpartStatusName (string): Last known status name of the other item
    • createdByName (string): Name of who started the handoff
    • createdByRef (string): E-mail of who started the handoff
    • 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 logged
    • nextAttemptAt (string (date-time)): Next delivery attempt while pending
    • projectId (string (uuid)): Project of the forge item
    • returnNote (string): Note given when the item was handed back
    • returnedAt (string (date-time)): When it was handed back
    • returnedByName (string): Name of who handed it back
    • returnedByRef (string): E-mail of who handed it back
    • updatedAt (string (date-time)): Last change of this side
    • version (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"

View as Markdown · Interactive reference · OpenAPI