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 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 dateaccess(Capabilities, required)canConfigure(boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)canCreateItem(boolean, required): Create items and commentcanDeleteItem(boolean, required): Delete items and anyone's commentscanEditItem(boolean, required): Edit items (status, fields, labels, assignees, sections, links)canManage(boolean, required): Members, project settings, archive, deletecanPlan(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 projectmember(boolean, required): The caller is a member of the projectrole(string, required): Effective role; empty when none
handoffs(array of Handoff, required): The item's handoffs and conversions in both roles, newest firstcounterpartModule(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
sections(array of Section, required): The sections of the item type with their contentbody(string, required): Markdown (checklist: a task list)key(string, required): Section keykind(string, required): markdown or checklist (one ofmarkdown,checklist)label(string, required): Display labelplacement(string, required): Where the portal shows it: a tab or the side column (one oftab,aside)version(integer, required): 0 = never writtenupdatedAt(string (date-time), nullable): When the current version was written; null when never writtenupdatedByKind(string): Kind of actor who wrote itupdatedByName(string): Name of who wrote itupdatedByRef(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"