ConnectCloud Developers

Get an item with its sections (tenant:forge:read)

GET /api/forge/v1/items/{ref}

Module: Forge · operationId: getForgeItem · Tag: Items · Auth: access token (Authorization: Bearer <accessToken>)

Requires tenant:forge:read and a project the caller sees (else 404); a confidential item only for tenant forge admins, members with role maintainer or higher, its reporter and its assignees (else 404). Includes the sections of the item's type and the caller's capabilities in the project. The tombstone of an item converted to another module is answered with convertedTo (writes on it are 409 converted). A number that moved to another project (or module) is 404 moved with redirect {module, ref, path} when the caller may see the target.

Parameters

Name In Type Required Description
ref path string yes Item reference, e.g. APP-12

Responses

  • 200 Item (application/json)
  • 404 Error (application/json)

Fields of the 200 answer:

  • assignees (array of string, required): E-mail addresses of the assignees
  • createdAt (string (date-time), required): When the item was created
  • customFields (object, required): Values of custom fields by field key
  • description (string, required): Markdown
  • id (string (uuid), required): Item id
  • labelIds (array of string (uuid), required): Label ids
  • labels (array of string, required): Label names
  • number (integer, required): Number in the project (the 12 of APP-12)
  • projectId (string (uuid), required): Project id
  • projectKey (string, required): Project key
  • rank (string, required): Order key, compared byte-wise
  • ref (string, required): APP-12
  • reporterRef (string, required): E-mail (or actor ref) of who created the item
  • statusCategory (string, required): Category of the status (one of triage, todo, active, on_hold, done, cancelled)
  • statusId (string (uuid), required): Status id
  • statusKey (string, required): Status key
  • statusName (string, required): Status name
  • title (string, required): Title
  • typeId (string (uuid), required): Item type id
  • typeKey (string, required): Item type key
  • updatedAt (string (date-time), required): Last change
  • version (integer, required): Optimistic-locking version; send it with PATCH
  • watchers (array of string, required): E-mail addresses of the watchers
  • closedAt (string (date-time), nullable): When the item reached a done or cancelled status; null while open
  • confidential (boolean): Visible only to tenant forge admins, members with role maintainer or higher, the reporter and the assignees
  • convertedTo (object): Set on the tombstone of an item converted to another module (read-only)
    • at (string (date-time), required): When it was converted
    • id (string (uuid), required): Id of the new item
    • module (string, required): Module of the new item (one of desk, forge)
    • path (string, required): Portal path of the new item
    • ref (string, required): #123 or APP-12
  • convertingSince (string (date-time)): Set while a conversion of the item is pending
  • dueOn (string (date), nullable): Due date
  • estimate (number, nullable): Estimate; null when none
  • iterationId (string (uuid), nullable): Iteration the item is in; null when none
  • iterationName (string, nullable): Name of the iteration
  • milestoneId (string (uuid), nullable): Milestone the item is in; null when none
  • milestoneTitle (string, nullable): Title of the milestone
  • parentId (string (uuid), nullable): Parent item id; null without a parent
  • parentNumber (integer, nullable): Number of the parent item; null without a parent
  • resolution (string, nullable): returned: handed back to its origin; converted: the tombstone of a converted item (one of done, not_planned, duplicate, returned, converted, <nil>)
  • spentMinutes (integer, nullable, read-only): Work HR booked on the item (subject forge: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 writes
  • startOn (string (date), nullable): Planned start date
  • access (Capabilities, required)
    • canConfigure (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
    • canCreateItem (boolean, required): Create items and comment
    • canDeleteItem (boolean, required): Delete items and anyone's comments
    • canEditItem (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
    • canManage (boolean, required): Members, project settings, archive, delete
    • canPlan (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
    • canUseAgent (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
    • member (boolean, required): The caller is a member of the project
    • role (string, required): Effective role; empty when none
  • handoffs (array of Handoff, required): The item's handoffs and conversions in both roles, newest first
    • 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
  • sections (array of Section, required): The sections of the item type with their content
    • body (string, required): Markdown (checklist: a task list)
    • key (string, required): Section key
    • kind (string, required): markdown or checklist (one of markdown, checklist)
    • label (string, required): Display label
    • placement (string, required): Where the portal shows it: a tab or the side column (one of tab, aside)
    • version (integer, required): 0 = never written
    • updatedAt (string (date-time), nullable): When the current version was written; null when never written
    • updatedByKind (string): Kind of actor who wrote it
    • updatedByName (string): Name of who wrote it
    • updatedByRef (string): E-mail (or actor ref) of who wrote the current version

Example 200 answer:

{
  "access": {
    "canConfigure": false,
    "canCreateItem": true,
    "canDeleteItem": false,
    "canEditItem": true,
    "canManage": false,
    "canPlan": true,
    "canUseAgent": true,
    "member": true,
    "role": "developer"
  },
  "assignees": [
    "marie.wagner@muster-it.example"
  ],
  "closedAt": null,
  "confidential": false,
  "createdAt": "2026-10-28T10:30:00Z",
  "customFields": {
    "story_points": 3
  },
  "description": "Wiederverwendbare Filterleiste mit Status-Auswahl und Zeitraum, auf dem Smartphone als Bottom-Sheet.",
  "dueOn": null,
  "estimate": 3,
  "handoffs": [],
  "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06",
  "iterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
  "iterationName": "Iteration 2 – Ticketübersicht",
  "labelIds": [
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c01",
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c02"
  ],
  "labels": [
    "bereich::frontend",
    "priority::mittel"
  ],
  "milestoneId": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
  "milestoneTitle": "Version 1.1 – Ticketübersicht",
  "number": 6,
  "parentId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c05",
  "parentNumber": 5,
  "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "projectKey": "APP",
  "rank": "0000a8",
  "ref": "APP-6",
  "reporterRef": "emma.maier@muster-it.example",
  "resolution": null,
  "sections": [
    {
      "body": "Die Komponente bekommt ihre Optionen über Props und meldet Änderungen als Ereignis. Der Zeitraum nutzt den Datumsdialog des Betriebssystems.",
      "key": "plan",
      "kind": "markdown",
      "label": "Plan",
      "placement": "tab",
      "updatedAt": "2026-11-04T09:15:00Z",
      "updatedByKind": "person",
      "updatedByName": "Marie Wagner",
      "updatedByRef": "marie.wagner@muster-it.example",
      "version": 1
    },
    {
      "body": "",
      "key": "agent_notes",
      "kind": "markdown",
      "label": "Notizen für Agenten",
      "placement": "tab",
      "updatedAt": null,
      "version": 0
    },
    {
      "body": "",
      "key": "acceptance",
      "kind": "checklist",
      "label": "Akzeptanzkriterien",
      "placement": "tab",
      "updatedAt": null,
      "version": 0
    }
  ],
  "spentMinutes": 960,
  "startOn": null,
  "statusCategory": "active",
  "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
  "statusKey": "review",
  "statusName": "Review",
  "title": "Filterleiste als Komponente",
  "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
  "typeKey": "aufgabe",
  "updatedAt": "2026-11-16T16:40:00Z",
  "version": 4,
  "watchers": [
    "emma.maier@muster-it.example",
    "marie.wagner@muster-it.example"
  ]
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/forge/v1/items/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI