ConnectCloud Developers

Change an item (tenant:forge:write and, as a member, at least developer; the reporter may change only confidential)

PATCH /api/forge/v1/projects/{key}/items/{number}

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

Requires tenant:forge:write and project role developer or higher (non-members of a tenant-visible project may); the item's reporter (any forge reader who sees it) or who configures the project may send a PATCH that changes only confidential. version is required (409 version_conflict). Status changes follow the workflow (409 transition_not_allowed); entering done/cancelled sets closedAt and resolution. A type change maps the status by category. milestoneId must name an open milestone of the project (400 milestoneId); the change is recorded as milestone. iterationId must name a planned or active iteration of the project (400 iterationId); the change is recorded as iteration. confidential may be changed by who configures the project or the item's reporter (403 otherwise). A tombstone (convertedTo) is 409 converted, an item being converted 409 conversion_pending – this holds for every item write. Writes forge.item.updated, status_changed, closed or reopened (a close and a reopen write status_changed as well).

Parameters

Name In Type Required Description
key path string yes Project key (e.g. APP)
number path integer yes Item number in the project (12 of APP-12)

Request body

application/json (required)

  • version (integer, required): The version the change is based on (409 version_conflict when it changed)
  • confidential (boolean): Who configures the project or the reporter only
  • customFields (object): Custom field values to merge by key; null unsets a field
  • description (string): Description (Markdown) (max length 100000)
  • dueOn (string (date), nullable): Due date; null clears it
  • estimate (number, nullable): Estimate; null clears it
  • iterationId (string (uuid), nullable): A planned or active iteration of the project; null takes the item out
  • milestoneId (string (uuid), nullable): An open milestone of the project; null takes the item out
  • parentNumber (integer, nullable): Number of the parent item; null removes the parent
  • resolution (string): Resolution when the status is done or cancelled (one of done, not_planned, duplicate, returned)
  • startOn (string (date), nullable): Planned start date; null clears it
  • statusId (string (uuid)): Status (the workflow must allow the move)
  • title (string): Title (max length 300)
  • typeId (string (uuid)): Item type; the status is mapped to the new workflow

Example:

{
  "customFields": {
    "story_points": 5
  },
  "dueOn": "2026-11-21",
  "estimate": 5,
  "version": 4
}

Responses

  • 200 Changed (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)
  • 409 Error (application/json)

Fields of the 200 answer:

  • 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:

{
  "assignees": [
    "marie.wagner@muster-it.example"
  ],
  "closedAt": null,
  "confidential": false,
  "createdAt": "2026-10-28T10:30:00Z",
  "customFields": {
    "story_points": 3
  },
  "description": "Wiederverwendbare Filterleiste mit Status-Auswahl und Zeitraum, auf dem Smartphone als Bottom-Sheet.",
  "dueOn": null,
  "estimate": 3,
  "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"
  ],
  "labels": [
    "bereich::frontend",
    "priority::mittel"
  ],
  "milestoneId": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
  "milestoneTitle": "Version 1.1 – Ticketübersicht",
  "number": 6,
  "parentId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c05",
  "parentNumber": 5,
  "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "projectKey": "APP",
  "rank": "0000a8",
  "ref": "APP-6",
  "reporterRef": "emma.maier@muster-it.example",
  "resolution": null,
  "startOn": null,
  "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-16T16:40:00Z",
  "version": 4,
  "watchers": [
    "emma.maier@muster-it.example",
    "marie.wagner@muster-it.example"
  ]
}

Example request

curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"customFields":{"story_points":5},"dueOn":"2026-11-21","estimate":5,"version":4}'

View as Markdown · Interactive reference · OpenAPI