Read the backlog of a project (tenant:forge:read)
GET /api/forge/v1/projects/{key}/backlog
Module: Forge · operationId: getForgeBacklog · Tag: Iterations · Auth: access token (Authorization: Bearer <accessToken>)
Requires tenant:forge:read and a project the caller sees. iterations are the planned iterations with their items (rank order); backlog is the page of open items without an iteration in rank order, continued with cursor. The item filters (q, status, category, type, label, assignee, milestone) narrow the backlog page; iteration, open and sort are fixed.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q |
query | string | Words in title or description, or a reference (APP-12) (max length 200) | |
status |
query | string | Status keys, comma separated | |
category |
query | string | Status categories, comma separated | |
type |
query | string | Item type keys, comma separated | |
label |
query | string | Label names, comma separated; an item must carry all | |
assignee |
query | string | me or an e-mail address |
|
milestone |
query | string | A milestone id, or none for items without one |
|
cursor |
query | string | nextCursor of the previous page |
|
limit |
query | integer | (default 50; max 200) |
|
key |
path | string | yes | Project key (e.g. APP) |
Responses
- 200 The backlog (
application/json) - 400 Error (
application/json) - 404 Error (
application/json)
Fields of the 200 answer:
backlog(object, required): Open items without an iteration in rank order (paged)items(array of Item, required): One page of backlog itemsassignees(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
nextCursor(string, nullable, required): Cursor of the next page; null at the end
iterations(array of object, required): The planned iterations with their items, in position orderitems(array of Item, required): Items of the iteration in rank orderassignees(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
iteration(IterationView, required)
Example 200 answer:
{
"backlog": {
"items": [
{
"assignees": [],
"createdAt": "2026-10-28T16:00:00Z",
"customFields": {},
"description": "Zuletzt geladene Tickets sollen ohne Netz lesbar bleiben.",
"id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c0b",
"labelIds": [
"8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c01",
"8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c0e"
],
"labels": [
"bereich::frontend",
"priority::niedrig"
],
"milestoneId": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c03",
"milestoneTitle": "Version 2.0 – Rückfragen",
"number": 11,
"parentId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
"parentNumber": 1,
"projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
"projectKey": "APP",
"rank": "0000b4",
"ref": "APP-11",
"reporterRef": "emma.maier@muster-it.example",
"statusCategory": "triage",
"statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
"statusKey": "triage",
"statusName": "Triage",
"title": "Offline-Modus für Ticketlisten",
"typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b02",
"typeKey": "story",
"updatedAt": "2026-11-11T11:00:00Z",
"version": 3,
"watchers": [
"emma.maier@muster-it.example"
]
}
],
"nextCursor": null
},
"iterations": [
{
"items": [
{
"assignees": [],
"createdAt": "2026-11-16T15:40:00Z",
"customFields": {},
"description": "Im Dunkelmodus sind die Labels „Wartet auf Kunde“ und „Gelöst“ kaum lesbar (Kontrast unter 3:1).",
"estimate": 1,
"id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c0a",
"iterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d03",
"iterationName": "Iteration 3 – Rückfragen",
"labelIds": [
"8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
"8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c0d",
"8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c0e",
"8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c0b"
],
"labels": [
"bug",
"owner::ios",
"plattform::ios",
"priority::niedrig"
],
"number": 10,
"projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
"projectKey": "APP",
"rank": "0000a0",
"ref": "APP-10",
"reporterRef": "ben.koch@muster-it.example",
"statusCategory": "todo",
"statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
"statusKey": "offen",
"statusName": "Offen",
"title": "Dunkelmodus: Kontrast der Statuslabels zu gering",
"typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
"typeKey": "fehler",
"updatedAt": "2026-11-17T09:00:00Z",
"version": 2,
"watchers": [
"ben.koch@muster-it.example"
]
}
],
"iteration": {
"closedAt": null,
"createdAt": "2026-11-15T14:00:00Z",
"endsOn": "2026-12-15",
"goal": "Rückfragen beantworten und Anhänge ansehen.",
"id": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d03",
"name": "Iteration 3 – Rückfragen",
"position": 2,
"progress": {
"byCategory": {
"active": 0,
"cancelled": 0,
"done": 0,
"on_hold": 0,
"todo": 1,
"triage": 0
},
"committed": null,
"estimate": {
"done": 0,
"total": 1
},
"total": 1
},
"startedAt": null,
"startsOn": "2026-11-25",
"state": "planned",
"updatedAt": "2026-11-15T14:00:00Z",
"version": 1
}
}
]
}
Example request
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/backlog' \
-H "Authorization: Bearer $ACCESS_TOKEN"