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 ownaddLabels(array of string): Label names to put on the itemsassignee(string, nullable): The only assignee; null removes alliterationId(string (uuid), nullable): A planned or active iteration of each item's project; null takes the items outmilestoneId(string (uuid), nullable): An open milestone of each item's project; null takes the items outremoveLabels(array of string): Label names to take off the itemsresolution(string): Resolution when the status closes the items (one ofdone,not_planned,duplicate)statusKey(string): Status key to move every item to (must exist in the item's workflow)
Example:
{
"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 orderok(boolean, required): The change of this item succeededref(string, required): The item referencecode(string): Error code when it failederror(string): Error text when it faileditem(Item)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 date
Example 200 answer:
{
"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
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"]}'