## 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 items
    - `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
  - `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 order
  - `items` (array of Item, required): Items of the iteration in rank order
    - `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
  - `iteration` (IterationView, required)

Example 200 answer:

```json
{
  "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

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