ConnectCloud Developers

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:

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

View as Markdown · Interactive reference · OpenAPI