## Change several items at once (tenant:forge:write and, as a member, at least developer, decided per item)

`POST /api/forge/v1/items/bulk`

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

Requires `tenant:forge:write` (or admin) and, per item, the right to edit it. Each item is changed on its own; a missing, hidden or refused item or a conflict is reported in its result (`ok` false with `code`) and does not stop the others. Writes the item events of each change.

### Request body

`application/json` (required)

- `refs` (array of string, required): Item references (APP-12) of any visible project; each item is changed on its own
- `addLabels` (array of string): Label names to put on the items
- `assignee` (string, nullable): The only assignee; null removes all
- `iterationId` (string (uuid), nullable): A planned or active iteration of each item's project; null takes the items out
- `milestoneId` (string (uuid), nullable): An open milestone of each item's project; null takes the items out
- `removeLabels` (array of string): Label names to take off the items
- `resolution` (string): Resolution when the status closes the items (one of `done`, `not_planned`, `duplicate`)
- `statusKey` (string): Status key to move every item to (must exist in the item's workflow)

Example:

```json
{
  "addLabels": [
    "sprint-ziel"
  ],
  "iterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
  "refs": [
    "APP-6",
    "APP-7",
    "APP-23"
  ]
}
```

### Responses

- **200** One result per item (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `results` (array of object, required): One result per distinct ref, in request order
  - `ok` (boolean, required): The change of this item succeeded
  - `ref` (string, required): The item reference
  - `code` (string): Error code when it failed
  - `error` (string): Error text when it failed
  - `item` (Item)
    - `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

Example 200 answer:

```json
{
  "results": [
    {
      "item": {
        "assignees": [
          "marie.wagner@muster-it.example"
        ],
        "createdAt": "2026-10-28T10:30:00Z",
        "customFields": {
          "story_points": 3
        },
        "description": "Wiederverwendbare Filterleiste mit Status-Auswahl und Zeitraum, auf dem Smartphone als Bottom-Sheet.",
        "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",
          "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c07"
        ],
        "labels": [
          "bereich::frontend",
          "priority::mittel",
          "sprint-ziel"
        ],
        "number": 6,
        "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
        "projectKey": "APP",
        "rank": "0000a8",
        "ref": "APP-6",
        "reporterRef": "emma.maier@muster-it.example",
        "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-18T10:30:00Z",
        "version": 4,
        "watchers": [
          "emma.maier@muster-it.example",
          "marie.wagner@muster-it.example"
        ]
      },
      "ok": true,
      "ref": "APP-6"
    },
    {
      "item": {
        "assignees": [
          "paul.schmid@muster-it.example"
        ],
        "createdAt": "2026-10-28T10:35:00Z",
        "customFields": {
          "story_points": 3
        },
        "description": "Die Liste lädt zunächst 25 Tickets und holt beim Scrollen die nächste Seite über den Cursor der API.",
        "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c07",
        "iterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
        "iterationName": "Iteration 2 – Ticketübersicht",
        "labelIds": [
          "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c01",
          "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c02",
          "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c07"
        ],
        "labels": [
          "bereich::frontend",
          "priority::mittel",
          "sprint-ziel"
        ],
        "number": 7,
        "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
        "projectKey": "APP",
        "rank": "0000a9",
        "ref": "APP-7",
        "reporterRef": "emma.maier@muster-it.example",
        "statusCategory": "todo",
        "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
        "statusKey": "offen",
        "statusName": "Offen",
        "title": "Cursor-basierte Seitenwechsel in der Ticketliste",
        "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
        "typeKey": "aufgabe",
        "updatedAt": "2026-11-18T10:30:00Z",
        "version": 4,
        "watchers": [
          "emma.maier@muster-it.example",
          "paul.schmid@muster-it.example"
        ]
      },
      "ok": true,
      "ref": "APP-7"
    },
    {
      "code": "converted",
      "error": "the item was converted; it is read-only",
      "ok": false,
      "ref": "APP-23"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/items/bulk' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addLabels":["sprint-ziel"],"iterationId":"f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02","refs":["APP-6","APP-7","APP-23"]}'
```
