# ConnectCloud Forge API (v1.0.0)

Software development: projects with linked repositories, items (APP-12) with sections, links, milestones, iterations and the backlog, views, automations, and the handoff and conversion of items to and from desk.

Base URLs:

- Production: `https://api.mbcom.cloud/api/forge/v1`
- Staging: `https://api.mbcom.cloud/api/forge/v1`
- Sandbox: `https://developers.mbcom.cloud/sandbox/forge`

Software development (ADR 0027): projects with a key and linked repositories, their items (`APP-12`) and the
configuration each project owns – statuses, item types, labels, fields, templates and item sections that
people and integrations write.

## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

## Permissions
| Permission | Grants |
|---|---|
| `tenant:forge:read` | the projects the caller may see and their items |
| `tenant:forge:write` | create and change items in projects the caller is a developer of (or every project the tenant shares) |
| `tenant:forge:admin` | create projects and keep members, repositories and configuration of every project |
| `tenant:forge:intake` | create items from desk tickets in projects that accept them |

A project or item the caller may not see answers `404`.

## Errors
Errors have the shared shape `{error, code, field?, details?}` (guide „Errors“). Codes: `invalid` (400, `field`),
`not_found`, `forbidden`, `tenant_required`, `version_conflict` (409: the `version` sent is not the current one),
`key_taken`, `in_use` (with `details.counts`), `is_default`, `project_archived`, `repository_linked`,
`has_items` (with `details.counts`), `has_children`, `transition_not_allowed`, `link_exists`, `link_cycle`,
`session_required` / `person_required` (403: a planning agent route that needs a person's own sign-in), `iteration_active`, `iteration_closed`, `iteration_not_active`,
`iteration_not_planned`, `infected` / `not_scanned` (403) and `scan_pending` (409) for attachment downloads,
`rate_limited` (429), `internal`. Automations (ADR 0044): `invalid_definition` (422: the definition of an automation
cannot be read, or has errors and was to be enabled; `details.diagnostics`), `automation_blocked` (422: a blocking
automation of the project failed and refused the change – every item write can answer it; `details.automation`,
`details.reason`, `details.message`). Handoff and conversion (ADR 0027): `converted` (409: the item is a read-only
tombstone of a conversion), `conversion_pending` (409: a conversion is being delivered), `moved` (404 with
`details.redirect`: the item moved to another project), `handoff_state` (409: the handoff cannot be handed back in its
state), `handoff_pending` (409: the item has a handoff still being delivered), `confidential_target` (403: a
confidential item would be hidden from the caller in the target project), `handoff_refused` (422: desk refused the
handoff), `desk_unavailable` (503). Ownerships (code ownership): `ownership_label` (409: the label of an ownership keeps its
name – change the ownership), `in_use` with `details.counts.ownerships` / `details.counts.teams` (a member who owns or
deputises ownerships or belongs to a team, a team that owns an ownership, an ownership with children, an item type or
label an ownership matches, the label of an ownership).

## Project access
Projects are `private` (members only) or `tenant` (every forge reader). Member roles: `reporter` < `developer` <
`maintainer` < `admin`. Configuration needs `tenant:forge:admin` or a maintainer membership with
`tenant:forge:write`; members, settings, archive and delete need `tenant:forge:admin` or an admin membership with
`tenant:forge:write`.

# Status

## What the caller may do in forge (tenant:forge:read)

`GET /api/forge/v1/status`

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

Requires `tenant:forge:read`.

### Responses

- **200** The caller's capabilities. (`application/json`)
- **401** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `canIntake` (boolean, required)
- `canWrite` (boolean, required)
- `isAdmin` (boolean, required)

Example 200 answer:

```json
{
  "canIntake": false,
  "canWrite": true,
  "isAdmin": false
}
```

### Example request

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

## Change notices for open forge pages (tenant:forge:read)

`GET /api/forge/v1/live`

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

Requires `tenant:forge:read`. Answers `text/event-stream` (`X-Accel-Buffering: no`, a `: ping` comment every
15 seconds). First a `ready` event (`{}`), then one `change` event per item, project or configuration change
of a project the caller sees (the rule of `GET /projects/{key}`: visibility and membership), about one to two
seconds after the commit; a new stream starts with the changes of the last 10 seconds. A notice only names
what changed – never title or content; the client reloads it through the API. `kind` is `item` (`action` =
the history action, `projectId`, `projectKey`, `itemId`, `number`, `ref`), `project` (`action` `saved` with
`projectId` and `projectKey` – also members and repositories –, or `deleted` with `projectId` only, sent to
whoever could see the project before), `config` (`projectId`: reload the project's configuration; no actor) or `resync`
(notices were dropped: reload everything shown). When the token expires, and after 15 minutes at the latest,
the stream ends with a `reconnect` event (`{}`): reconnecting within 10 seconds loses nothing. Any other end
means notices may be missing; the client reloads what it shows. At most 10 open streams per person and 500
per tenant and server instance (429 `rate_limited`).

### Responses

- **200** Event stream (`text/event-stream`)
- **401** Error (`application/json`)
- **403** Error (`application/json`)
- **429** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `kind` (string, required): What changed (resync: notices were dropped, reload everything) (one of `item`, `project`, `config`, `milestone`, `iteration`, `resync`)
- `action` (string): item: the history action (created, updated, status_changed, commented, …); project: saved or deleted; milestone: saved, closed, reopened or deleted; iteration: saved, started, closed or deleted
- `itemId` (string (uuid)): Item of an item notice
- `iterationId` (string (uuid)): Iteration of an iteration notice
- `milestoneId` (string (uuid)): Milestone of a milestone notice
- `number` (integer): Number of the item
- `projectId` (string (uuid)): Project of the change
- `projectKey` (string): Key of the project
- `ref` (string): Item reference, e.g. APP-12

### Example request

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

# Projects

## List the projects the caller sees (tenant:forge:read)

`GET /api/forge/v1/projects`

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

Requires `tenant:forge:read`. Private projects only for members and forge admins.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `state` | query | string |  | (one of `active`, `archived`) |

### Responses

- **200** Projects (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ProjectView, required)
  - `acceptsIntake` (boolean, required): Callers with only `tenant:forge:intake` may hand desk tickets to the project
  - `access` (Capabilities, required)
    - `canConfigure` (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
    - `canCreateItem` (boolean, required): Create items and comment
    - `canDeleteItem` (boolean, required): Delete items and anyone's comments
    - `canEditItem` (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
    - `canManage` (boolean, required): Members, project settings, archive, delete
    - `canPlan` (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
    - `canUseAgent` (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
    - `member` (boolean, required): The caller is a member of the project
    - `role` (string, required): Effective role; empty when none
  - `createdAt` (string (date-time), required): When the project was created
  - `createdBy` (string, required): E-mail of who created the project
  - `description` (string, required): Markdown
  - `id` (string (uuid), required): Project id
  - `key` (string, required): Project key, prefix of item references (APP-12); never changes
  - `name` (string, required): Project name
  - `settings` (object, required): Project settings (handoff, code intake, planning agent), each changed through its own PUT route
  - `state` (string, required): active or archived (archived: read-only) (one of `active`, `archived`)
  - `updatedAt` (string (date-time), required): Last change
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
  - `visibility` (string, required): `private`: members and tenant forge admins; `tenant`: every forge reader (one of `private`, `tenant`)
  - `defaultTypeId` (string (uuid), nullable): Default item type of new items; null when none
  - `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`forge:project:<id>`, worked minus breaks, ADR 0040); filled by the project read and list, null when HR does not answer (never an error)
  - `workCustomer` (WorkCustomer | null): How work on the project and its items is booked in HR (ADR 0040); null = no setting (the person picks the customer)

Example 200 answer:

```json
{
  "items": [
    {
      "acceptsIntake": true,
      "access": {
        "canConfigure": true,
        "canCreateItem": true,
        "canDeleteItem": true,
        "canEditItem": true,
        "canManage": false,
        "canPlan": true,
        "canUseAgent": false,
        "member": true,
        "role": "maintainer"
      },
      "createdAt": "2026-09-23T09:00:00Z",
      "createdBy": "emma.maier@muster-it.example",
      "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
      "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
      "id": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "key": "APP",
      "name": "Kundenportal-App",
      "settings": {
        "planningAgent": {
          "enabled": true,
          "language": "de"
        }
      },
      "spentMinutes": 14520,
      "state": "active",
      "updatedAt": "2026-11-11T14:20:00Z",
      "version": 7,
      "visibility": "tenant",
      "workCustomer": null
    },
    {
      "acceptsIntake": false,
      "access": {
        "canConfigure": true,
        "canCreateItem": true,
        "canDeleteItem": true,
        "canEditItem": true,
        "canManage": false,
        "canPlan": true,
        "canUseAgent": false,
        "member": true,
        "role": "maintainer"
      },
      "createdAt": "2026-10-05T08:30:00Z",
      "createdBy": "emma.maier@muster-it.example",
      "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b33",
      "description": "Mobile App für das Lager von Donau Maschinenbau in Neutraubling: Wareneingang, Umlagerung und Inventur mit Anbindung an das ERP.",
      "id": "7c2d4e6f-8a1b-4c3d-9e5f-6a7b8c9d0e1f",
      "key": "LAG",
      "name": "Lager-App Donau",
      "settings": {},
      "spentMinutes": 23880,
      "state": "active",
      "updatedAt": "2026-11-04T08:10:00Z",
      "version": 4,
      "visibility": "tenant",
      "workCustomer": {
        "customer": {
          "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
          "name": "Donau Maschinenbau AG"
        },
        "internal": false
      }
    }
  ]
}
```

### Example request

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

## Create a project from a template (tenant:forge:admin)

`POST /api/forge/v1/projects`

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

Requires `tenant:forge:admin`. Applies `templateKey` (built-in key or saved template id/key; default `kanban`) in the same transaction; the creator becomes member `admin`. Writes `forge.project.saved`.

### Request body

`application/json` (required)

- `key` (string, required): Project key, prefix of item references (APP-12); never changes
- `name` (string, required): Project name (max length 120)
- `acceptsIntake` (boolean): Callers with only `tenant:forge:intake` may hand desk tickets to the project
- `description` (string): Description (Markdown) (max length 20000)
- `templateKey` (string): Built-in key or saved template id or key; default kanban
- `visibility` (string): `private`: members and tenant forge admins; `tenant`: every forge reader (one of `private`, `tenant`; default `"private"`)
- `workCustomer` (WorkCustomer): How work on a project and its items is booked in HR's Leistungserfassung (ADR 0040): either `internal: true` (internal work, HR's internal kind) or a `customer` – a masterdata address (`id`, at most 100 characters) with its name as a snapshot (at most 200 characters) – never both (400 `workCustomer`). `internal` may be left out and then is `false`, so `{customer: {...}}` alone is a customer project.
  - `customer` (object): The masterdata address the work is booked for
    - `id` (string, required): Masterdata address id (max length 100)
    - `name` (string, required): Name of the address (snapshot) (max length 200)
  - `internal` (boolean): Internal work (not billed to a customer) (default `false`)

Example:

```json
{
  "acceptsIntake": true,
  "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
  "key": "APP",
  "name": "Kundenportal-App",
  "templateKey": "scrum",
  "visibility": "tenant"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `acceptsIntake` (boolean, required): Callers with only `tenant:forge:intake` may hand desk tickets to the project
- `access` (Capabilities, required)
  - `canConfigure` (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
  - `canCreateItem` (boolean, required): Create items and comment
  - `canDeleteItem` (boolean, required): Delete items and anyone's comments
  - `canEditItem` (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
  - `canManage` (boolean, required): Members, project settings, archive, delete
  - `canPlan` (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
  - `canUseAgent` (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
  - `member` (boolean, required): The caller is a member of the project
  - `role` (string, required): Effective role; empty when none
- `createdAt` (string (date-time), required): When the project was created
- `createdBy` (string, required): E-mail of who created the project
- `description` (string, required): Markdown
- `id` (string (uuid), required): Project id
- `key` (string, required): Project key, prefix of item references (APP-12); never changes
- `name` (string, required): Project name
- `settings` (object, required): Project settings (handoff, code intake, planning agent), each changed through its own PUT route
- `state` (string, required): active or archived (archived: read-only) (one of `active`, `archived`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `visibility` (string, required): `private`: members and tenant forge admins; `tenant`: every forge reader (one of `private`, `tenant`)
- `defaultTypeId` (string (uuid), nullable): Default item type of new items; null when none
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`forge:project:<id>`, worked minus breaks, ADR 0040); filled by the project read and list, null when HR does not answer (never an error)
- `workCustomer` (WorkCustomer | null): How work on the project and its items is booked in HR (ADR 0040); null = no setting (the person picks the customer)

Example 201 answer:

```json
{
  "acceptsIntake": true,
  "access": {
    "canConfigure": true,
    "canCreateItem": true,
    "canDeleteItem": true,
    "canEditItem": true,
    "canManage": false,
    "canPlan": true,
    "canUseAgent": false,
    "member": true,
    "role": "maintainer"
  },
  "createdAt": "2026-09-23T09:00:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
  "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
  "id": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "key": "APP",
  "name": "Kundenportal-App",
  "settings": {
    "handoff": {
      "originOnReturn": {
        "action": "none"
      },
      "receiverOnReturn": {
        "action": "close",
        "status": "erledigt"
      }
    },
    "planningAgent": {
      "enabled": true,
      "language": "de"
    }
  },
  "spentMinutes": 14520,
  "state": "active",
  "updatedAt": "2026-11-11T14:20:00Z",
  "version": 7,
  "visibility": "tenant",
  "workCustomer": null
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"acceptsIntake":true,"description":"Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.","key":"APP","name":"Kundenportal-App","templateKey":"scrum","visibility":"tenant"}'
```

## Get a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}`

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

Requires `tenant:forge:read` and a project the caller sees (else 404).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** Project (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `acceptsIntake` (boolean, required): Callers with only `tenant:forge:intake` may hand desk tickets to the project
- `access` (Capabilities, required)
  - `canConfigure` (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
  - `canCreateItem` (boolean, required): Create items and comment
  - `canDeleteItem` (boolean, required): Delete items and anyone's comments
  - `canEditItem` (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
  - `canManage` (boolean, required): Members, project settings, archive, delete
  - `canPlan` (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
  - `canUseAgent` (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
  - `member` (boolean, required): The caller is a member of the project
  - `role` (string, required): Effective role; empty when none
- `createdAt` (string (date-time), required): When the project was created
- `createdBy` (string, required): E-mail of who created the project
- `description` (string, required): Markdown
- `id` (string (uuid), required): Project id
- `key` (string, required): Project key, prefix of item references (APP-12); never changes
- `name` (string, required): Project name
- `settings` (object, required): Project settings (handoff, code intake, planning agent), each changed through its own PUT route
- `state` (string, required): active or archived (archived: read-only) (one of `active`, `archived`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `visibility` (string, required): `private`: members and tenant forge admins; `tenant`: every forge reader (one of `private`, `tenant`)
- `defaultTypeId` (string (uuid), nullable): Default item type of new items; null when none
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`forge:project:<id>`, worked minus breaks, ADR 0040); filled by the project read and list, null when HR does not answer (never an error)
- `workCustomer` (WorkCustomer | null): How work on the project and its items is booked in HR (ADR 0040); null = no setting (the person picks the customer)

Example 200 answer:

```json
{
  "acceptsIntake": true,
  "access": {
    "canConfigure": true,
    "canCreateItem": true,
    "canDeleteItem": true,
    "canEditItem": true,
    "canManage": false,
    "canPlan": true,
    "canUseAgent": false,
    "member": true,
    "role": "maintainer"
  },
  "createdAt": "2026-09-23T09:00:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
  "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
  "id": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "key": "APP",
  "name": "Kundenportal-App",
  "settings": {
    "handoff": {
      "originOnReturn": {
        "action": "none"
      },
      "receiverOnReturn": {
        "action": "close",
        "status": "erledigt"
      }
    },
    "planningAgent": {
      "enabled": true,
      "language": "de"
    }
  },
  "spentMinutes": 14520,
  "state": "active",
  "updatedAt": "2026-11-11T14:20:00Z",
  "version": 7,
  "visibility": "tenant",
  "workCustomer": null
}
```

### Example request

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

## Delete a project with everything it owns (tenant:forge:write and project admin, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role admin. A project with items is refused (409 `has_items` with `details.counts`; archive it instead). Writes `forge.project.deleted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

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

## Change a project (tenant:forge:write and project admin, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role admin. `version` is required; the key never changes. `workCustomer` (null clears it, absent keeps it) sets how work on the project and its items is booked in HR; a change affects only new work entries. Writes `forge.project.saved`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `version` (integer, required): The version the change is based on
- `acceptsIntake` (boolean): Accept desk tickets from intake-only callers
- `defaultTypeId` (string (uuid), nullable): Default item type of new items; null clears it
- `description` (string): Description (Markdown) (max length 20000)
- `name` (string): Project name (max length 120)
- `visibility` (string): `private` or `tenant` (one of `private`, `tenant`)
- `workCustomer` (WorkCustomer | null): null clears it

Example:

```json
{
  "acceptsIntake": true,
  "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen und Rückfragen beantworten.",
  "version": 7
}
```

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

- `acceptsIntake` (boolean, required): Callers with only `tenant:forge:intake` may hand desk tickets to the project
- `access` (Capabilities, required)
  - `canConfigure` (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
  - `canCreateItem` (boolean, required): Create items and comment
  - `canDeleteItem` (boolean, required): Delete items and anyone's comments
  - `canEditItem` (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
  - `canManage` (boolean, required): Members, project settings, archive, delete
  - `canPlan` (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
  - `canUseAgent` (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
  - `member` (boolean, required): The caller is a member of the project
  - `role` (string, required): Effective role; empty when none
- `createdAt` (string (date-time), required): When the project was created
- `createdBy` (string, required): E-mail of who created the project
- `description` (string, required): Markdown
- `id` (string (uuid), required): Project id
- `key` (string, required): Project key, prefix of item references (APP-12); never changes
- `name` (string, required): Project name
- `settings` (object, required): Project settings (handoff, code intake, planning agent), each changed through its own PUT route
- `state` (string, required): active or archived (archived: read-only) (one of `active`, `archived`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `visibility` (string, required): `private`: members and tenant forge admins; `tenant`: every forge reader (one of `private`, `tenant`)
- `defaultTypeId` (string (uuid), nullable): Default item type of new items; null when none
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`forge:project:<id>`, worked minus breaks, ADR 0040); filled by the project read and list, null when HR does not answer (never an error)
- `workCustomer` (WorkCustomer | null): How work on the project and its items is booked in HR (ADR 0040); null = no setting (the person picks the customer)

Example 200 answer:

```json
{
  "acceptsIntake": true,
  "access": {
    "canConfigure": true,
    "canCreateItem": true,
    "canDeleteItem": true,
    "canEditItem": true,
    "canManage": false,
    "canPlan": true,
    "canUseAgent": false,
    "member": true,
    "role": "maintainer"
  },
  "createdAt": "2026-09-23T09:00:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
  "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
  "id": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "key": "APP",
  "name": "Kundenportal-App",
  "settings": {
    "handoff": {
      "originOnReturn": {
        "action": "none"
      },
      "receiverOnReturn": {
        "action": "close",
        "status": "erledigt"
      }
    },
    "planningAgent": {
      "enabled": true,
      "language": "de"
    }
  },
  "spentMinutes": 14520,
  "state": "active",
  "updatedAt": "2026-11-11T14:20:00Z",
  "version": 7,
  "visibility": "tenant",
  "workCustomer": null
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"acceptsIntake":true,"description":"Die mobile App für Kunden von Muster IT: Tickets ansehen und Rückfragen beantworten.","version":7}'
```

## Archive a project (tenant:forge:write and project admin, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/archive`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role admin. An archived project's configuration and items are read-only (409 `project_archived`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** Archived (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `acceptsIntake` (boolean, required): Callers with only `tenant:forge:intake` may hand desk tickets to the project
- `access` (Capabilities, required)
  - `canConfigure` (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
  - `canCreateItem` (boolean, required): Create items and comment
  - `canDeleteItem` (boolean, required): Delete items and anyone's comments
  - `canEditItem` (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
  - `canManage` (boolean, required): Members, project settings, archive, delete
  - `canPlan` (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
  - `canUseAgent` (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
  - `member` (boolean, required): The caller is a member of the project
  - `role` (string, required): Effective role; empty when none
- `createdAt` (string (date-time), required): When the project was created
- `createdBy` (string, required): E-mail of who created the project
- `description` (string, required): Markdown
- `id` (string (uuid), required): Project id
- `key` (string, required): Project key, prefix of item references (APP-12); never changes
- `name` (string, required): Project name
- `settings` (object, required): Project settings (handoff, code intake, planning agent), each changed through its own PUT route
- `state` (string, required): active or archived (archived: read-only) (one of `active`, `archived`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `visibility` (string, required): `private`: members and tenant forge admins; `tenant`: every forge reader (one of `private`, `tenant`)
- `defaultTypeId` (string (uuid), nullable): Default item type of new items; null when none
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`forge:project:<id>`, worked minus breaks, ADR 0040); filled by the project read and list, null when HR does not answer (never an error)
- `workCustomer` (WorkCustomer | null): How work on the project and its items is booked in HR (ADR 0040); null = no setting (the person picks the customer)

Example 200 answer:

```json
{
  "acceptsIntake": true,
  "access": {
    "canConfigure": false,
    "canCreateItem": false,
    "canDeleteItem": false,
    "canEditItem": false,
    "canManage": true,
    "canPlan": false,
    "canUseAgent": false,
    "member": true,
    "role": "admin"
  },
  "createdAt": "2026-09-23T09:00:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
  "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
  "id": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "key": "APP",
  "name": "Kundenportal-App",
  "settings": {},
  "state": "archived",
  "updatedAt": "2026-11-18T08:00:00Z",
  "version": 8,
  "visibility": "tenant",
  "workCustomer": null
}
```

### Example request

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

## Make an archived project active again (tenant:forge:write and project admin, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/unarchive`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role admin.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** Active (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `acceptsIntake` (boolean, required): Callers with only `tenant:forge:intake` may hand desk tickets to the project
- `access` (Capabilities, required)
  - `canConfigure` (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
  - `canCreateItem` (boolean, required): Create items and comment
  - `canDeleteItem` (boolean, required): Delete items and anyone's comments
  - `canEditItem` (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
  - `canManage` (boolean, required): Members, project settings, archive, delete
  - `canPlan` (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
  - `canUseAgent` (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
  - `member` (boolean, required): The caller is a member of the project
  - `role` (string, required): Effective role; empty when none
- `createdAt` (string (date-time), required): When the project was created
- `createdBy` (string, required): E-mail of who created the project
- `description` (string, required): Markdown
- `id` (string (uuid), required): Project id
- `key` (string, required): Project key, prefix of item references (APP-12); never changes
- `name` (string, required): Project name
- `settings` (object, required): Project settings (handoff, code intake, planning agent), each changed through its own PUT route
- `state` (string, required): active or archived (archived: read-only) (one of `active`, `archived`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `visibility` (string, required): `private`: members and tenant forge admins; `tenant`: every forge reader (one of `private`, `tenant`)
- `defaultTypeId` (string (uuid), nullable): Default item type of new items; null when none
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`forge:project:<id>`, worked minus breaks, ADR 0040); filled by the project read and list, null when HR does not answer (never an error)
- `workCustomer` (WorkCustomer | null): How work on the project and its items is booked in HR (ADR 0040); null = no setting (the person picks the customer)

Example 200 answer:

```json
{
  "acceptsIntake": true,
  "access": {
    "canConfigure": true,
    "canCreateItem": true,
    "canDeleteItem": true,
    "canEditItem": true,
    "canManage": false,
    "canPlan": true,
    "canUseAgent": false,
    "member": true,
    "role": "maintainer"
  },
  "createdAt": "2026-09-23T09:00:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
  "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
  "id": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "key": "APP",
  "name": "Kundenportal-App",
  "settings": {
    "handoff": {
      "originOnReturn": {
        "action": "none"
      },
      "receiverOnReturn": {
        "action": "close",
        "status": "erledigt"
      }
    },
    "planningAgent": {
      "enabled": true,
      "language": "de"
    }
  },
  "spentMinutes": 14520,
  "state": "active",
  "updatedAt": "2026-11-11T14:20:00Z",
  "version": 7,
  "visibility": "tenant",
  "workCustomer": null
}
```

### Example request

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

## Set the code intake of a project (tenant:forge:write and maintainer, or tenant:forge:admin)

`PUT /api/forge/v1/projects/{key}/scm-intake-settings`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Stores `settings.scmIntake` of the project (the project's `settings` answer it): with `enabled`, a failed GitHub workflow run (`workflowTypeKey`) or an opened security alert (`alertTypeKey`) of one of the project's repositories becomes an item of that type (actor kind `scm`; the first active project, oldest first, whose repositories include the repository and whose intake takes the kind). While that item is open, repeats, the recovery and the resolution are system comments on it; once it is closed the next failure opens a new one. Type keys must exist (400); `enabled` needs at least one. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `alertKinds` (array of string): Only alerts of these kinds; empty = all
- `alertLabels` (array of string): Label names put on the items of security alerts
- `alertTypeKey` (string): Item type of security alerts; empty = none
- `assigneeRef` (string): E-mail of a member with at least the developer role; assigned to every intake item
- `branches` (array of string): Only failed runs on these branches: exact names or patterns (release/*); empty = every branch
- `enabled` (boolean): Failed workflow runs and security alerts of the linked repositories become items
- `minSeverity` (string): Only alerts of this severity and above (an alert without a known severity is taken); empty = all (one of `low`, `medium`, `high`, `critical`)
- `workflowLabels` (array of string): Label names put on the items of failed workflow runs (a label deleted or renamed since is skipped)
- `workflowTypeKey` (string): Item type of failed workflow runs; empty = none

Example:

```json
{
  "alertKinds": [
    "dependabot",
    "code_scanning"
  ],
  "alertLabels": [
    "bereich::sicherheit"
  ],
  "alertTypeKey": "fehler",
  "assigneeRef": "paul.schmid@muster-it.example",
  "branches": [
    "main",
    "release/*"
  ],
  "enabled": true,
  "minSeverity": "high",
  "workflowLabels": [
    "bug"
  ],
  "workflowTypeKey": "fehler"
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `alertKinds` (array of string): Only alerts of these kinds; empty = all
- `alertLabels` (array of string): Label names put on the items of security alerts
- `alertTypeKey` (string): Item type of security alerts; empty = none
- `assigneeRef` (string): E-mail of a member with at least the developer role; assigned to every intake item
- `branches` (array of string): Only failed runs on these branches: exact names or patterns (release/*); empty = every branch
- `enabled` (boolean): Failed workflow runs and security alerts of the linked repositories become items
- `minSeverity` (string): Only alerts of this severity and above (an alert without a known severity is taken); empty = all (one of `low`, `medium`, `high`, `critical`)
- `workflowLabels` (array of string): Label names put on the items of failed workflow runs (a label deleted or renamed since is skipped)
- `workflowTypeKey` (string): Item type of failed workflow runs; empty = none

Example 200 answer:

```json
{
  "alertKinds": [
    "dependabot",
    "code_scanning"
  ],
  "alertLabels": [
    "bereich::sicherheit"
  ],
  "alertTypeKey": "fehler",
  "assigneeRef": "paul.schmid@muster-it.example",
  "branches": [
    "main",
    "release/*"
  ],
  "enabled": true,
  "minSeverity": "high",
  "workflowLabels": [
    "bug"
  ],
  "workflowTypeKey": "fehler"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/forge/v1/projects/string/scm-intake-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"alertKinds":["dependabot","code_scanning"],"alertLabels":["bereich::sicherheit"],"alertTypeKey":"fehler","assigneeRef":"paul.schmid@muster-it.example","branches":["main","release/*"],"enabled":true,"minSeverity":"high","workflowLabels":["bug"],"workflowTypeKey":"fehler"}'
```

# Members

## List the members of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/members`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** Members (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Member, required)
  - `addedAt` (string (date-time), required): When the member was added
  - `addedBy` (string, required): E-mail of who added the member
  - `ref` (string, required): Lower-cased e-mail address
  - `role` (Role, required): (one of `reporter`, `developer`, `maintainer`, `admin`)

Example 200 answer:

```json
{
  "items": [
    {
      "addedAt": "2026-09-23T09:00:00Z",
      "addedBy": "emma.maier@muster-it.example",
      "ref": "emma.maier@muster-it.example",
      "role": "maintainer"
    },
    {
      "addedAt": "2026-09-23T09:05:00Z",
      "addedBy": "emma.maier@muster-it.example",
      "ref": "paul.schmid@muster-it.example",
      "role": "developer"
    },
    {
      "addedAt": "2026-09-23T09:05:00Z",
      "addedBy": "emma.maier@muster-it.example",
      "ref": "marie.wagner@muster-it.example",
      "role": "developer"
    },
    {
      "addedAt": "2026-09-23T09:06:00Z",
      "addedBy": "emma.maier@muster-it.example",
      "ref": "ben.koch@muster-it.example",
      "role": "reporter"
    }
  ]
}
```

### Example request

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

## Add a member or change the role (tenant:forge:write and project admin, or tenant:forge:admin)

`PUT /api/forge/v1/projects/{key}/members/{ref}`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role admin. An owner, deputy or team member of an ownership keeps at least the developer role (409 `in_use` with `details.counts.ownerships` / `details.counts.teams`). Writes `forge.project.saved`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `ref` | path | string | yes | E-mail address of the person |

### Request body

`application/json` (required)

- `role` (Role, required): (one of `reporter`, `developer`, `maintainer`, `admin`)

Example:

```json
{
  "role": "developer"
}
```

### Responses

- **200** Member (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `addedAt` (string (date-time), required): When the member was added
- `addedBy` (string, required): E-mail of who added the member
- `ref` (string, required): Lower-cased e-mail address
- `role` (Role, required): (one of `reporter`, `developer`, `maintainer`, `admin`)

Example 200 answer:

```json
{
  "addedAt": "2026-09-23T09:05:00Z",
  "addedBy": "emma.maier@muster-it.example",
  "ref": "marie.wagner@muster-it.example",
  "role": "developer"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/forge/v1/projects/string/members/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"role":"developer"}'
```

## Remove a member (oneself with tenant:forge:read; anyone else tenant:forge:write and project admin, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/members/{ref}`

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

Requires `tenant:forge:read`; removing someone else needs `tenant:forge:admin`, or `tenant:forge:write` and project role admin. Members may leave on their own. An owner, deputy or team member of an ownership cannot be removed until someone else is named (409 `in_use` with `details.counts.ownerships` / `details.counts.teams`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `ref` | path | string | yes | E-mail address of the person |

### Responses

- **204** Removed
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

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

# Repositories

## List the repositories of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/repositories`

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

Requires `tenant:forge:read` and a project the caller sees. The default repository comes first.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** Repositories (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Repository, required)
  - `createdAt` (string (date-time), required): When it was linked
  - `fullName` (string, required): owner/name
  - `id` (string (uuid), required): Repository link id
  - `isDefault` (boolean, required): The default repository of the project
  - `provider` (string, required): Repository provider key: github, gitlab or gitlab@<host> (self-managed GitLab)
  - `baseBranch` (string, nullable): Base branch for new branches; null = the repository's default branch

Example 200 answer:

```json
{
  "items": [
    {
      "baseBranch": null,
      "createdAt": "2026-09-23T09:10:00Z",
      "fullName": "mbcomdev/demo-app",
      "id": "4b5c6d7e-8f9a-4b1c-8d2e-3f4a5b6c7d01",
      "isDefault": true,
      "provider": "github"
    }
  ]
}
```

### Example request

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

## Link a repository (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/repositories`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. The first repository becomes the default. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `fullName` (string, required): owner/name of the repository
- `baseBranch` (string, nullable): Base branch for new branches; null = the repository's default branch
- `isDefault` (boolean): Make it the default repository (the first one always is)
- `provider` (string): Repository provider key: github, gitlab or gitlab@<host>. forge checks only the syntax; scm decides whether the provider is known and configured (400 `fullName` when its installations do not reach the repository, 503 when scm cannot be asked or the provider is not configured) (default `"github"`)

Example:

```json
{
  "fullName": "mbcomdev/demo-app",
  "isDefault": true
}
```

### Responses

- **201** Linked (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time), required): When it was linked
- `fullName` (string, required): owner/name
- `id` (string (uuid), required): Repository link id
- `isDefault` (boolean, required): The default repository of the project
- `provider` (string, required): Repository provider key: github, gitlab or gitlab@<host> (self-managed GitLab)
- `baseBranch` (string, nullable): Base branch for new branches; null = the repository's default branch

Example 201 answer:

```json
{
  "baseBranch": null,
  "createdAt": "2026-09-23T09:10:00Z",
  "fullName": "mbcomdev/demo-app",
  "id": "4b5c6d7e-8f9a-4b1c-8d2e-3f4a5b6c7d01",
  "isDefault": true,
  "provider": "github"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/repositories' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"fullName":"mbcomdev/demo-app","isDefault":true}'
```

## Unlink a repository (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/repositories/{id}`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. When the default goes, the oldest remaining repository becomes the default.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Unlinked
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/repositories/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Configuration

## Project page bootstrap (project, configuration, members, repositories) (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/config`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** Bootstrap (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `customFields` (array of CustomField, required): Custom fields in position order
  - `id` (string (uuid), required): Field id
  - `key` (string, required): Field key: the key in `customFields` of an item; never changes
  - `kind` (string, required): Value type; never changes (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
  - `label` (string, required): Display label
  - `options` (array of FieldOption, required): Choices of select and multiselect fields
  - `position` (integer, required): Order in the configuration
  - `required` (boolean, required): Items of the types the field applies to need a value
  - `typeKeys` (array of string, required): Item type keys; empty = every type
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `itemTemplates` (array of ItemTemplate, required): Item templates in position order
  - `body` (string, required): Markdown
  - `id` (string (uuid), required): Template id
  - `key` (string, required): Template key (`templateKey` of a new item)
  - `labelIds` (array of string (uuid), required): Labels it sets
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `title` (string, required): Title it prefills
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
  - `typeId` (string (uuid), nullable): Item type it sets; null = none
- `itemTypes` (array of ItemType, required): Item types in position order
  - `archived` (boolean, required): Archived: no new items of the type
  - `icon` (string, required): Icon name shown in the portal
  - `id` (string (uuid), required): Item type id
  - `key` (string, required): Type key; never changes
  - `level` (integer, required): 0 = leaf; a parent type has a higher level (max 5)
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
  - `workflowId` (string (uuid), required): Workflow the items of the type follow
- `labels` (array of Label, required): Labels sorted by name
  - `color` (string, required): Color token (neutral, primary, …) or #rrggbb
  - `description` (string, required): Description
  - `id` (string (uuid), required): Label id
  - `name` (string, required): scope::value makes it exclusive within the scope
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `ownerships` (array of Ownership, required): Ownerships (code ownership) in position order
  - `deputyRefs` (array of string, required): E-mails of the deputies (members, at least developer); need an owner of their own
  - `description` (string, required): Description (max length 2000)
  - `id` (string (uuid), required): Ownership id
  - `itemTypes` (array of string, required): Item type keys: items of these types belong here (without an owner:: label)
  - `key` (string, required): Key; never changes (its label is `owner::<key>`)
  - `labelId` (string (uuid), required): The ownership's label `owner::<key>`; items carry it and it wins over the matchers
  - `matchLabelIds` (array of string (uuid), required): Plain labels (never `owner::…`): items carrying one belong here (without an owner:: label); the later position wins
  - `name` (string, required): Display name (max length 80)
  - `ownerRef` (string, nullable, required): E-mail of the owner person (a member, at least developer); exclusive with ownerTeamId
  - `ownerTeamId` (string (uuid), nullable, required): The owning team; exclusive with ownerRef. Neither is allowed only with a parent (inherited)
  - `parentId` (string (uuid), nullable, required): The parent ownership (same project, no cycle, at most 4 levels); without an owner of its own the nearest ancestor's applies
  - `paths` (array of string, required): Repository path patterns, the CODEOWNERS subset: segments separated by `/`, `*` and `?` within a segment, `**` as a whole segment for any number of directories. A pattern without `/` (other than a trailing one) matches at any depth, one with `/` is relative to the root (a leading `/` anchors explicitly); a trailing `/` matches directories. A pattern whose last segment has no wildcard also matches everything below the directory it names (`hr`, `/apps/github`); one ending in a wildcard matches only what it names (`docs/*`). No character classes, `\`, `!`, `#` or spaces. Paths decide only for code (CODEOWNERS, scm).
  - `position` (integer, required): Precedence: a later ownership wins a path or an item both match
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `sectionDefs` (array of SectionDef, required): Section definitions in position order
  - `id` (string (uuid), required): Section definition id
  - `key` (string, required): Section key; never changes
  - `kind` (string, required): markdown or checklist (one of `markdown`, `checklist`)
  - `label` (string, required): Display label
  - `placement` (string, required): Where the portal shows it: a tab or the side column (one of `tab`, `aside`)
  - `position` (integer, required): Order in the configuration
  - `typeKeys` (array of string, required): Item type keys the section applies to; empty = every type
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `statuses` (array of Status, required): Statuses in position order
  - `category` (string, required): Status category (the group the status belongs to) (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
  - `color` (string, required): Color token (neutral, primary, …) or #rrggbb
  - `id` (string (uuid), required): Status id
  - `isDefault` (boolean, required): Where new items start; exactly one, in triage or todo
  - `key` (string, required): Status key; never changes
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `teams` (array of Team, required): Teams in position order
  - `description` (string, required): Description (max length 2000)
  - `id` (string (uuid), required): Team id
  - `key` (string, required): Team key; never changes
  - `memberRefs` (array of string, required): E-mails, the first is the lead
  - `name` (string, required): Display name (max length 80)
  - `position` (integer, required): Order in the configuration
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `workflows` (array of Workflow, required): Workflows in position order
  - `id` (string (uuid), required): Workflow id
  - `key` (string, required): Workflow key; never changes
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `statusIds` (array of string (uuid), required): Statuses of the workflow
  - `transitions` (array of Transition, required): Empty = free movement among the statuses
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `members` (array of Member, required): Members of the project
  - `addedAt` (string (date-time), required): When the member was added
  - `addedBy` (string, required): E-mail of who added the member
  - `ref` (string, required): Lower-cased e-mail address
  - `role` (Role, required): (one of `reporter`, `developer`, `maintainer`, `admin`)
- `project` (ProjectView, required)
  - `acceptsIntake` (boolean, required): Callers with only `tenant:forge:intake` may hand desk tickets to the project
  - `access` (Capabilities, required)
    - `canConfigure` (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
    - `canCreateItem` (boolean, required): Create items and comment
    - `canDeleteItem` (boolean, required): Delete items and anyone's comments
    - `canEditItem` (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
    - `canManage` (boolean, required): Members, project settings, archive, delete
    - `canPlan` (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
    - `canUseAgent` (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
    - `member` (boolean, required): The caller is a member of the project
    - `role` (string, required): Effective role; empty when none
  - `createdAt` (string (date-time), required): When the project was created
  - `createdBy` (string, required): E-mail of who created the project
  - `description` (string, required): Markdown
  - `id` (string (uuid), required): Project id
  - `key` (string, required): Project key, prefix of item references (APP-12); never changes
  - `name` (string, required): Project name
  - `settings` (object, required): Project settings (handoff, code intake, planning agent), each changed through its own PUT route
  - `state` (string, required): active or archived (archived: read-only) (one of `active`, `archived`)
  - `updatedAt` (string (date-time), required): Last change
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
  - `visibility` (string, required): `private`: members and tenant forge admins; `tenant`: every forge reader (one of `private`, `tenant`)
  - `defaultTypeId` (string (uuid), nullable): Default item type of new items; null when none
  - `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`forge:project:<id>`, worked minus breaks, ADR 0040); filled by the project read and list, null when HR does not answer (never an error)
  - `workCustomer` (WorkCustomer | null): How work on the project and its items is booked in HR (ADR 0040); null = no setting (the person picks the customer)
- `repositories` (array of Repository, required): Linked repositories
  - `createdAt` (string (date-time), required): When it was linked
  - `fullName` (string, required): owner/name
  - `id` (string (uuid), required): Repository link id
  - `isDefault` (boolean, required): The default repository of the project
  - `provider` (string, required): Repository provider key: github, gitlab or gitlab@<host> (self-managed GitLab)
  - `baseBranch` (string, nullable): Base branch for new branches; null = the repository's default branch

Example 200 answer:

```json
{
  "customFields": [
    {
      "id": "9b5c6d7e-8f9a-4b0c-9dbe-5f6a7b8c9d01",
      "key": "story_points",
      "kind": "number",
      "label": "Story Points",
      "options": [],
      "position": 0,
      "required": false,
      "typeKeys": [
        "story",
        "aufgabe",
        "fehler"
      ],
      "version": 1
    }
  ],
  "itemTemplates": [
    {
      "body": "## Beobachtet\n\n## Erwartet\n\n## Schritte zum Nachstellen\n\n1. \n",
      "id": "ac6d7e8f-9a0b-4c1d-8ecf-6a7b8c9d0e01",
      "key": "fehlerbericht",
      "labelIds": [
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04"
      ],
      "name": "Fehlerbericht",
      "position": 0,
      "title": "",
      "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
      "version": 1
    }
  ],
  "itemTypes": [
    {
      "archived": false,
      "icon": "i-lucide-mountain",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b01",
      "key": "epic",
      "level": 3,
      "name": "Epic",
      "position": 0,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    },
    {
      "archived": false,
      "icon": "i-lucide-book-open",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b02",
      "key": "story",
      "level": 2,
      "name": "Story",
      "position": 1,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    },
    {
      "archived": false,
      "icon": "i-lucide-square-check",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
      "key": "aufgabe",
      "level": 1,
      "name": "Aufgabe",
      "position": 2,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    },
    {
      "archived": false,
      "icon": "i-lucide-bug",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
      "key": "fehler",
      "level": 1,
      "name": "Fehler",
      "position": 3,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    },
    {
      "archived": false,
      "icon": "i-lucide-list-checks",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b05",
      "key": "subtask",
      "level": 0,
      "name": "Sub-Task",
      "position": 4,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    }
  ],
  "labels": [
    {
      "color": "info",
      "description": "Oberfläche der App",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c01",
      "name": "bereich::frontend",
      "version": 1
    },
    {
      "color": "error",
      "description": "",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
      "name": "bug",
      "version": 1
    },
    {
      "color": "neutral",
      "description": "Android-App",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c06",
      "name": "owner::android",
      "version": 1
    },
    {
      "color": "success",
      "description": "",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05",
      "name": "plattform::android",
      "version": 1
    },
    {
      "color": "error",
      "description": "Hohe Priorität",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03",
      "name": "priority::hoch",
      "version": 1
    },
    {
      "color": "warning",
      "description": "Mittlere Priorität",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c02",
      "name": "priority::mittel",
      "version": 1
    },
    {
      "color": "primary",
      "description": "Trägt zum Sprint-Ziel bei",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c07",
      "name": "sprint-ziel",
      "version": 1
    }
  ],
  "members": [
    {
      "addedAt": "2026-09-23T09:00:00Z",
      "addedBy": "emma.maier@muster-it.example",
      "ref": "emma.maier@muster-it.example",
      "role": "maintainer"
    },
    {
      "addedAt": "2026-09-23T09:05:00Z",
      "addedBy": "emma.maier@muster-it.example",
      "ref": "paul.schmid@muster-it.example",
      "role": "developer"
    },
    {
      "addedAt": "2026-09-23T09:05:00Z",
      "addedBy": "emma.maier@muster-it.example",
      "ref": "marie.wagner@muster-it.example",
      "role": "developer"
    },
    {
      "addedAt": "2026-09-23T09:06:00Z",
      "addedBy": "emma.maier@muster-it.example",
      "ref": "ben.koch@muster-it.example",
      "role": "reporter"
    }
  ],
  "ownerships": [
    {
      "deputyRefs": [],
      "description": "Gesamter Code der mobilen Apps.",
      "id": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01",
      "itemTypes": [],
      "key": "apps",
      "labelId": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c0a",
      "matchLabelIds": [],
      "name": "Apps",
      "ownerRef": null,
      "ownerTeamId": "ce8f9a0b-1c2d-4e3f-8a01-8c9d0e1f2a01",
      "parentId": null,
      "paths": [
        "app/**"
      ],
      "position": 0,
      "version": 1
    },
    {
      "deputyRefs": [
        "paul.schmid@muster-it.example"
      ],
      "description": "Kotlin-Code der Android-App.",
      "id": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b02",
      "itemTypes": [],
      "key": "android",
      "labelId": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c06",
      "matchLabelIds": [],
      "name": "Android-App",
      "ownerRef": "marie.wagner@muster-it.example",
      "ownerTeamId": null,
      "parentId": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01",
      "paths": [
        "app/android/**"
      ],
      "position": 1,
      "version": 1
    }
  ],
  "project": {
    "acceptsIntake": true,
    "access": {
      "canConfigure": true,
      "canCreateItem": true,
      "canDeleteItem": true,
      "canEditItem": true,
      "canManage": false,
      "canPlan": true,
      "canUseAgent": false,
      "member": true,
      "role": "maintainer"
    },
    "createdAt": "2026-09-23T09:00:00Z",
    "createdBy": "emma.maier@muster-it.example",
    "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
    "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
    "id": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "key": "APP",
    "name": "Kundenportal-App",
    "settings": {
      "planningAgent": {
        "enabled": true,
        "language": "de"
      }
    },
    "state": "active",
    "updatedAt": "2026-11-11T14:20:00Z",
    "version": 7,
    "visibility": "tenant",
    "workCustomer": null
  },
  "repositories": [
    {
      "baseBranch": null,
      "createdAt": "2026-09-23T09:10:00Z",
      "fullName": "mbcomdev/demo-app",
      "id": "4b5c6d7e-8f9a-4b1c-8d2e-3f4a5b6c7d01",
      "isDefault": true,
      "provider": "github"
    }
  ],
  "sectionDefs": [
    {
      "id": "bd7e8f9a-0b1c-4d2e-9fd0-7b8c9d0e1f01",
      "key": "plan",
      "kind": "markdown",
      "label": "Plan",
      "placement": "tab",
      "position": 0,
      "typeKeys": [],
      "version": 1
    },
    {
      "id": "bd7e8f9a-0b1c-4d2e-9fd0-7b8c9d0e1f02",
      "key": "agent_notes",
      "kind": "markdown",
      "label": "Notizen für Agenten",
      "placement": "tab",
      "position": 1,
      "typeKeys": [],
      "version": 1
    },
    {
      "id": "bd7e8f9a-0b1c-4d2e-9fd0-7b8c9d0e1f03",
      "key": "acceptance",
      "kind": "checklist",
      "label": "Akzeptanzkriterien",
      "placement": "tab",
      "position": 2,
      "typeKeys": [],
      "version": 1
    }
  ],
  "statuses": [
    {
      "category": "triage",
      "color": "neutral",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
      "isDefault": false,
      "key": "triage",
      "name": "Triage",
      "position": 0,
      "version": 1
    },
    {
      "category": "todo",
      "color": "info",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
      "isDefault": true,
      "key": "offen",
      "name": "Offen",
      "position": 1,
      "version": 1
    },
    {
      "category": "active",
      "color": "primary",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
      "isDefault": false,
      "key": "in_arbeit",
      "name": "In Arbeit",
      "position": 2,
      "version": 1
    },
    {
      "category": "active",
      "color": "warning",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
      "isDefault": false,
      "key": "review",
      "name": "Review",
      "position": 3,
      "version": 1
    },
    {
      "category": "done",
      "color": "success",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05",
      "isDefault": false,
      "key": "erledigt",
      "name": "Erledigt",
      "position": 4,
      "version": 1
    },
    {
      "category": "cancelled",
      "color": "neutral",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06",
      "isDefault": false,
      "key": "verworfen",
      "name": "Verworfen",
      "position": 5,
      "version": 1
    }
  ],
  "teams": [
    {
      "description": "Entwickler der iOS- und Android-App; Paul leitet das Team.",
      "id": "ce8f9a0b-1c2d-4e3f-8a01-8c9d0e1f2a01",
      "key": "mobile",
      "memberRefs": [
        "paul.schmid@muster-it.example",
        "marie.wagner@muster-it.example"
      ],
      "name": "Mobile-Team",
      "position": 0,
      "version": 1
    }
  ],
  "workflows": [
    {
      "id": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01",
      "key": "standard",
      "name": "Standard",
      "position": 0,
      "statusIds": [
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"
      ],
      "transitions": [],
      "version": 1
    }
  ]
}
```

### Example request

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

## Set the order of a configuration collection (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/config/reorder`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. `ids` lists every row of the collection once; labels sort by name and cannot be reordered. The order of `ownerships` is their precedence, a later ownership wins a path both match (as in CODEOWNERS) or an item both match.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `collection` (string, required): (one of `statuses`, `workflows`, `item-types`, `custom-fields`, `item-templates`, `section-defs`, `ownerships`, `teams`)
- `ids` (array of string (uuid), required)

Example:

```json
{
  "collection": "statuses",
  "ids": [
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"
  ]
}
```

### Responses

- **204** Reordered
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/config/reorder' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"collection":"statuses","ids":["5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01","5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02","5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03","5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04","5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05","5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"]}'
```

## List the statuses of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/statuses`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The statuss (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Status, required)
  - `category` (string, required): Status category (the group the status belongs to) (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
  - `color` (string, required): Color token (neutral, primary, …) or #rrggbb
  - `id` (string (uuid), required): Status id
  - `isDefault` (boolean, required): Where new items start; exactly one, in triage or todo
  - `key` (string, required): Status key; never changes
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "items": [
    {
      "category": "triage",
      "color": "neutral",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
      "isDefault": false,
      "key": "triage",
      "name": "Triage",
      "position": 0,
      "version": 1
    },
    {
      "category": "todo",
      "color": "info",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
      "isDefault": true,
      "key": "offen",
      "name": "Offen",
      "position": 1,
      "version": 1
    },
    {
      "category": "active",
      "color": "primary",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
      "isDefault": false,
      "key": "in_arbeit",
      "name": "In Arbeit",
      "position": 2,
      "version": 1
    },
    {
      "category": "active",
      "color": "warning",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
      "isDefault": false,
      "key": "review",
      "name": "Review",
      "position": 3,
      "version": 1
    },
    {
      "category": "done",
      "color": "success",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05",
      "isDefault": false,
      "key": "erledigt",
      "name": "Erledigt",
      "position": 4,
      "version": 1
    },
    {
      "category": "cancelled",
      "color": "neutral",
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06",
      "isDefault": false,
      "key": "verworfen",
      "name": "Verworfen",
      "position": 5,
      "version": 1
    }
  ]
}
```

### Example request

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

## Create a status (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/statuses`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `category` (string): Status category (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
- `color` (string): Color token (neutral, primary, …) or #rrggbb
- `isDefault` (boolean): true makes it the default status (moves the default); cannot be unset
- `key` (string): Create: status key; fixed afterwards
- `name` (string): Display name (max length 60)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "category": "on_hold",
  "color": "neutral",
  "key": "wartet",
  "name": "Wartet auf Rückmeldung"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `category` (string, required): Status category (the group the status belongs to) (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
- `color` (string, required): Color token (neutral, primary, …) or #rrggbb
- `id` (string (uuid), required): Status id
- `isDefault` (boolean, required): Where new items start; exactly one, in triage or todo
- `key` (string, required): Status key; never changes
- `name` (string, required): Display name
- `position` (integer, required): Order in the configuration
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

```json
{
  "category": "active",
  "color": "warning",
  "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
  "isDefault": false,
  "key": "review",
  "name": "Review",
  "position": 3,
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/statuses' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"category":"on_hold","color":"neutral","key":"wartet","name":"Wartet auf Rückmeldung"}'
```

## Delete a status (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/statuses/{id}`

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

Same permission as creating. A row other configuration or items still reference answers 409 `in_use` with `details.counts` (for a section definition the items with content in it); deleting a label or an empty section takes it off the items. Automations are not counted – one that names the status fails its run (`transition_not_allowed` or `invalid` in its log).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/statuses/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a status (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/statuses/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); keys never change.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `category` (string): Status category (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
- `color` (string): Color token (neutral, primary, …) or #rrggbb
- `isDefault` (boolean): true makes it the default status (moves the default); cannot be unset
- `key` (string): Create: status key; fixed afterwards
- `name` (string): Display name (max length 60)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "color": "warning",
  "name": "Im Review",
  "version": 1
}
```

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

- `category` (string, required): Status category (the group the status belongs to) (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
- `color` (string, required): Color token (neutral, primary, …) or #rrggbb
- `id` (string (uuid), required): Status id
- `isDefault` (boolean, required): Where new items start; exactly one, in triage or todo
- `key` (string, required): Status key; never changes
- `name` (string, required): Display name
- `position` (integer, required): Order in the configuration
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "category": "active",
  "color": "warning",
  "id": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
  "isDefault": false,
  "key": "review",
  "name": "Review",
  "position": 3,
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/statuses/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"color":"warning","name":"Im Review","version":1}'
```

## List the workflows of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/workflows`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The workflows (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Workflow, required)
  - `id` (string (uuid), required): Workflow id
  - `key` (string, required): Workflow key; never changes
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `statusIds` (array of string (uuid), required): Statuses of the workflow
  - `transitions` (array of Transition, required): Empty = free movement among the statuses
    - `fromStatusId` (string (uuid), required): Status the move starts from
    - `toStatusId` (string (uuid), required): Status the move leads to
  - `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "items": [
    {
      "id": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01",
      "key": "standard",
      "name": "Standard",
      "position": 0,
      "statusIds": [
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05",
        "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"
      ],
      "transitions": [],
      "version": 1
    }
  ]
}
```

### Example request

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

## Create a workflow (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/workflows`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `key` (string): Create: workflow key; fixed afterwards
- `name` (string): Display name (max length 60)
- `statusIds` (array of string (uuid)): Statuses of the workflow (at least one); replaces the list on PATCH
- `transitions` (array of Transition): Allowed moves; empty = free movement; replaces the list on PATCH
  - `fromStatusId` (string (uuid), required): Status the move starts from
  - `toStatusId` (string (uuid), required): Status the move leads to
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "key": "fehler",
  "name": "Fehlerablauf",
  "statusIds": [
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"
  ],
  "transitions": [
    {
      "fromStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
      "toStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02"
    },
    {
      "fromStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
      "toStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"
    },
    {
      "fromStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
      "toStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03"
    },
    {
      "fromStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
      "toStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05"
    }
  ]
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `id` (string (uuid), required): Workflow id
- `key` (string, required): Workflow key; never changes
- `name` (string, required): Display name
- `position` (integer, required): Order in the configuration
- `statusIds` (array of string (uuid), required): Statuses of the workflow
- `transitions` (array of Transition, required): Empty = free movement among the statuses
  - `fromStatusId` (string (uuid), required): Status the move starts from
  - `toStatusId` (string (uuid), required): Status the move leads to
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

```json
{
  "id": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01",
  "key": "standard",
  "name": "Standard",
  "position": 0,
  "statusIds": [
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"
  ],
  "transitions": [],
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/workflows' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"key":"fehler","name":"Fehlerablauf","statusIds":["5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01","5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02","5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03","5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05","5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"],"transitions":[{"fromStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01","toStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02"},{"fromStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01","toStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"},{"fromStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02","toStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03"},{"fromStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03","toStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05"}]}'
```

## Delete a workflow (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/workflows/{id}`

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

Same permission as creating. A row other configuration or items still reference answers 409 `in_use` with `details.counts` (for a section definition the items with content in it); deleting a label or an empty section takes it off the items.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/workflows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a workflow (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/workflows/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); keys never change. Dropping a status that items of the workflow's types sit on is 409 `in_use` with `details.counts`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string): Create: workflow key; fixed afterwards
- `name` (string): Display name (max length 60)
- `statusIds` (array of string (uuid)): Statuses of the workflow (at least one); replaces the list on PATCH
- `transitions` (array of Transition): Allowed moves; empty = free movement; replaces the list on PATCH
  - `fromStatusId` (string (uuid), required): Status the move starts from
  - `toStatusId` (string (uuid), required): Status the move leads to
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "transitions": [
    {
      "fromStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
      "toStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04"
    },
    {
      "fromStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
      "toStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05"
    },
    {
      "fromStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
      "toStatusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03"
    }
  ],
  "version": 1
}
```

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

- `id` (string (uuid), required): Workflow id
- `key` (string, required): Workflow key; never changes
- `name` (string, required): Display name
- `position` (integer, required): Order in the configuration
- `statusIds` (array of string (uuid), required): Statuses of the workflow
- `transitions` (array of Transition, required): Empty = free movement among the statuses
  - `fromStatusId` (string (uuid), required): Status the move starts from
  - `toStatusId` (string (uuid), required): Status the move leads to
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "id": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01",
  "key": "standard",
  "name": "Standard",
  "position": 0,
  "statusIds": [
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f01",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05",
    "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06"
  ],
  "transitions": [],
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/workflows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"transitions":[{"fromStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03","toStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04"},{"fromStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04","toStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f05"},{"fromStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f04","toStatusId":"5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03"}],"version":1}'
```

## List the item types of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/item-types`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The item types (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ItemType, required)
  - `archived` (boolean, required): Archived: no new items of the type
  - `icon` (string, required): Icon name shown in the portal
  - `id` (string (uuid), required): Item type id
  - `key` (string, required): Type key; never changes
  - `level` (integer, required): 0 = leaf; a parent type has a higher level (max 5)
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
  - `workflowId` (string (uuid), required): Workflow the items of the type follow

Example 200 answer:

```json
{
  "items": [
    {
      "archived": false,
      "icon": "i-lucide-mountain",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b01",
      "key": "epic",
      "level": 3,
      "name": "Epic",
      "position": 0,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    },
    {
      "archived": false,
      "icon": "i-lucide-book-open",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b02",
      "key": "story",
      "level": 2,
      "name": "Story",
      "position": 1,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    },
    {
      "archived": false,
      "icon": "i-lucide-square-check",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
      "key": "aufgabe",
      "level": 1,
      "name": "Aufgabe",
      "position": 2,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    },
    {
      "archived": false,
      "icon": "i-lucide-bug",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
      "key": "fehler",
      "level": 1,
      "name": "Fehler",
      "position": 3,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    },
    {
      "archived": false,
      "icon": "i-lucide-list-checks",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b05",
      "key": "subtask",
      "level": 0,
      "name": "Sub-Task",
      "position": 4,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
    }
  ]
}
```

### Example request

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

## Create an item type (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/item-types`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `archived` (boolean): Archive or restore the type
- `icon` (string): Icon name (at most 60 characters)
- `key` (string): Create: type key; fixed afterwards
- `level` (integer): 0 = leaf; a parent type has a higher level (max 5)
- `name` (string): Display name (max length 60)
- `version` (integer): PATCH: the version the change is based on
- `workflowId` (string (uuid)): Workflow of the type

Example:

```json
{
  "icon": "i-lucide-flask-conical",
  "key": "spike",
  "level": 1,
  "name": "Spike",
  "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `archived` (boolean, required): Archived: no new items of the type
- `icon` (string, required): Icon name shown in the portal
- `id` (string (uuid), required): Item type id
- `key` (string, required): Type key; never changes
- `level` (integer, required): 0 = leaf; a parent type has a higher level (max 5)
- `name` (string, required): Display name
- `position` (integer, required): Order in the configuration
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `workflowId` (string (uuid), required): Workflow the items of the type follow

Example 201 answer:

```json
{
  "archived": false,
  "icon": "i-lucide-bug",
  "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
  "key": "fehler",
  "level": 1,
  "name": "Fehler",
  "position": 3,
  "version": 1,
  "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/item-types' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"icon":"i-lucide-flask-conical","key":"spike","level":1,"name":"Spike","workflowId":"6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"}'
```

## Delete an item type (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/item-types/{id}`

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

Same permission as creating. A row other configuration or items still reference answers 409 `in_use` with `details.counts` (for a section definition the items with content in it); deleting a label or an empty section takes it off the items.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/item-types/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change an item type (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/item-types/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); keys never change. Moving to a workflow that lacks a status the type's items sit on is 409 `in_use` with `details.counts`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `archived` (boolean): Archive or restore the type
- `icon` (string): Icon name (at most 60 characters)
- `key` (string): Create: type key; fixed afterwards
- `level` (integer): 0 = leaf; a parent type has a higher level (max 5)
- `name` (string): Display name (max length 60)
- `version` (integer): PATCH: the version the change is based on
- `workflowId` (string (uuid)): Workflow of the type

Example:

```json
{
  "icon": "i-lucide-bug-play",
  "name": "Fehlerbericht",
  "version": 1
}
```

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

- `archived` (boolean, required): Archived: no new items of the type
- `icon` (string, required): Icon name shown in the portal
- `id` (string (uuid), required): Item type id
- `key` (string, required): Type key; never changes
- `level` (integer, required): 0 = leaf; a parent type has a higher level (max 5)
- `name` (string, required): Display name
- `position` (integer, required): Order in the configuration
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `workflowId` (string (uuid), required): Workflow the items of the type follow

Example 200 answer:

```json
{
  "archived": false,
  "icon": "i-lucide-bug",
  "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
  "key": "fehler",
  "level": 1,
  "name": "Fehler",
  "position": 3,
  "version": 1,
  "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a01"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/item-types/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"icon":"i-lucide-bug-play","name":"Fehlerbericht","version":1}'
```

## List the labels of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/labels`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The labels (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Label, required)
  - `color` (string, required): Color token (neutral, primary, …) or #rrggbb
  - `description` (string, required): Description
  - `id` (string (uuid), required): Label id
  - `name` (string, required): scope::value makes it exclusive within the scope
  - `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "items": [
    {
      "color": "info",
      "description": "Oberfläche der App",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c01",
      "name": "bereich::frontend",
      "version": 1
    },
    {
      "color": "error",
      "description": "",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
      "name": "bug",
      "version": 1
    },
    {
      "color": "success",
      "description": "",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05",
      "name": "plattform::android",
      "version": 1
    },
    {
      "color": "error",
      "description": "Hohe Priorität",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03",
      "name": "priority::hoch",
      "version": 1
    },
    {
      "color": "warning",
      "description": "Mittlere Priorität",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c02",
      "name": "priority::mittel",
      "version": 1
    }
  ]
}
```

### Example request

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

## Create a label (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/labels`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `color` (string): Color token (neutral, primary, …) or #rrggbb
- `description` (string): Description (max length 500)
- `name` (string): Name, unique per project ignoring case; `scope::value` makes it exclusive within the scope (max length 60)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "color": "info",
  "description": "Kundenportal im Browser",
  "name": "plattform::web"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `color` (string, required): Color token (neutral, primary, …) or #rrggbb
- `description` (string, required): Description
- `id` (string (uuid), required): Label id
- `name` (string, required): scope::value makes it exclusive within the scope
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

```json
{
  "color": "success",
  "description": "",
  "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05",
  "name": "plattform::android",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/labels' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"color":"info","description":"Kundenportal im Browser","name":"plattform::web"}'
```

## Delete a label (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/labels/{id}`

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

Same permission as creating. A row other configuration or items still reference answers 409 `in_use` with `details.counts` (for a section definition the items with content in it); deleting a label or an empty section takes it off the items. Automations are not counted and not rewritten – one that names a deleted or renamed label fails its run (`invalid`, field `label`, in its log). The label of an ownership (scope `owner`) goes only with its ownership (409 `in_use`, `details.counts.ownerships`, which also counts ownerships matching a label); no other label may be created in or renamed into that scope (400 `name`), and an ownership's label keeps its name (409 `ownership_label`). An item type an ownership matches is 409 `in_use` (`details.counts.ownerships`); a team owning an ownership too, and an ownership with children.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/labels/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a label (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/labels/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); keys never change.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `color` (string): Color token (neutral, primary, …) or #rrggbb
- `description` (string): Description (max length 500)
- `name` (string): Name, unique per project ignoring case; `scope::value` makes it exclusive within the scope (max length 60)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "description": "Android-App (Kotlin)",
  "version": 1
}
```

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

- `color` (string, required): Color token (neutral, primary, …) or #rrggbb
- `description` (string, required): Description
- `id` (string (uuid), required): Label id
- `name` (string, required): scope::value makes it exclusive within the scope
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "color": "success",
  "description": "",
  "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05",
  "name": "plattform::android",
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/labels/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Android-App (Kotlin)","version":1}'
```

## List the ownerships (code ownership) of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/ownerships`

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

Requires `tenant:forge:read` and a project the caller sees. In precedence order (a later ownership wins a path or an item both match).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The ownerships (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Ownership, required)
  - `deputyRefs` (array of string, required): E-mails of the deputies (members, at least developer); need an owner of their own
  - `description` (string, required): Description (max length 2000)
  - `id` (string (uuid), required): Ownership id
  - `itemTypes` (array of string, required): Item type keys: items of these types belong here (without an owner:: label)
  - `key` (string, required): Key; never changes (its label is `owner::<key>`)
  - `labelId` (string (uuid), required): The ownership's label `owner::<key>`; items carry it and it wins over the matchers
  - `matchLabelIds` (array of string (uuid), required): Plain labels (never `owner::…`): items carrying one belong here (without an owner:: label); the later position wins
  - `name` (string, required): Display name (max length 80)
  - `ownerRef` (string, nullable, required): E-mail of the owner person (a member, at least developer); exclusive with ownerTeamId
  - `ownerTeamId` (string (uuid), nullable, required): The owning team; exclusive with ownerRef. Neither is allowed only with a parent (inherited)
  - `parentId` (string (uuid), nullable, required): The parent ownership (same project, no cycle, at most 4 levels); without an owner of its own the nearest ancestor's applies
  - `paths` (array of string, required): Repository path patterns, the CODEOWNERS subset: segments separated by `/`, `*` and `?` within a segment, `**` as a whole segment for any number of directories. A pattern without `/` (other than a trailing one) matches at any depth, one with `/` is relative to the root (a leading `/` anchors explicitly); a trailing `/` matches directories. A pattern whose last segment has no wildcard also matches everything below the directory it names (`hr`, `/apps/github`); one ending in a wildcard matches only what it names (`docs/*`). No character classes, `\`, `!`, `#` or spaces. Paths decide only for code (CODEOWNERS, scm).
  - `position` (integer, required): Precedence: a later ownership wins a path or an item both match
  - `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "items": [
    {
      "deputyRefs": [],
      "description": "Gesamter Code der mobilen Apps.",
      "id": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01",
      "itemTypes": [],
      "key": "apps",
      "labelId": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c0a",
      "matchLabelIds": [],
      "name": "Apps",
      "ownerRef": null,
      "ownerTeamId": "ce8f9a0b-1c2d-4e3f-8a01-8c9d0e1f2a01",
      "parentId": null,
      "paths": [
        "app/**"
      ],
      "position": 0,
      "version": 1
    },
    {
      "deputyRefs": [
        "paul.schmid@muster-it.example"
      ],
      "description": "Alle Fehler gehen an die Qualitätssicherung.",
      "id": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b04",
      "itemTypes": [
        "fehler"
      ],
      "key": "qualitaet",
      "labelId": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c0f",
      "matchLabelIds": [],
      "name": "Qualitätssicherung",
      "ownerRef": "emma.maier@muster-it.example",
      "ownerTeamId": null,
      "parentId": null,
      "paths": [],
      "position": 1,
      "version": 1
    },
    {
      "deputyRefs": [
        "paul.schmid@muster-it.example"
      ],
      "description": "Kotlin-Code der Android-App.",
      "id": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b02",
      "itemTypes": [],
      "key": "android",
      "labelId": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c06",
      "matchLabelIds": [],
      "name": "Android-App",
      "ownerRef": "marie.wagner@muster-it.example",
      "ownerTeamId": null,
      "parentId": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01",
      "paths": [
        "app/android/**"
      ],
      "position": 2,
      "version": 1
    }
  ]
}
```

### Example request

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

## Create an ownership (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/ownerships`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Exactly one of `ownerRef` (a project member, at least developer) and `ownerTeamId` – or neither when `parentId` is set (the owner is inherited); the deputies are members with at least the developer role (400 `ownerRef` / `ownerTeamId` / `deputyRefs`). `parentId` nests the ownership (same project, no cycle, at most 4 levels, 400 `parentId`). `itemTypes` are item type keys and `matchLabelIds` plain labels (never `owner::…`). Creates the ownership's label `owner::<key>` in the same transaction (409 `key_taken` when the key or the label name exists). Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `deputyRefs` (array of string): E-mails of the deputies
- `description` (string): Description (max length 2000)
- `itemTypes` (array of string): Item type keys
- `key` (string): Create: key; fixed afterwards
- `matchLabelIds` (array of string (uuid)): Plain labels (never `owner::…`)
- `name` (string): Display name (max length 80)
- `ownerRef` (string): E-mail of the owner person; empty clears it on PATCH
- `ownerTeamId` (string): Owning team; empty clears it on PATCH
- `parentId` (string): Parent ownership; empty clears it on PATCH
- `paths` (array of string): Repository path patterns (see Ownership.paths)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "deputyRefs": [
    "paul.schmid@muster-it.example"
  ],
  "description": "Kotlin-Code der Android-App.",
  "key": "android",
  "name": "Android-App",
  "ownerRef": "marie.wagner@muster-it.example",
  "parentId": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01",
  "paths": [
    "app/android/**"
  ]
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `deputyRefs` (array of string, required): E-mails of the deputies (members, at least developer); need an owner of their own
- `description` (string, required): Description (max length 2000)
- `id` (string (uuid), required): Ownership id
- `itemTypes` (array of string, required): Item type keys: items of these types belong here (without an owner:: label)
- `key` (string, required): Key; never changes (its label is `owner::<key>`)
- `labelId` (string (uuid), required): The ownership's label `owner::<key>`; items carry it and it wins over the matchers
- `matchLabelIds` (array of string (uuid), required): Plain labels (never `owner::…`): items carrying one belong here (without an owner:: label); the later position wins
- `name` (string, required): Display name (max length 80)
- `ownerRef` (string, nullable, required): E-mail of the owner person (a member, at least developer); exclusive with ownerTeamId
- `ownerTeamId` (string (uuid), nullable, required): The owning team; exclusive with ownerRef. Neither is allowed only with a parent (inherited)
- `parentId` (string (uuid), nullable, required): The parent ownership (same project, no cycle, at most 4 levels); without an owner of its own the nearest ancestor's applies
- `paths` (array of string, required): Repository path patterns, the CODEOWNERS subset: segments separated by `/`, `*` and `?` within a segment, `**` as a whole segment for any number of directories. A pattern without `/` (other than a trailing one) matches at any depth, one with `/` is relative to the root (a leading `/` anchors explicitly); a trailing `/` matches directories. A pattern whose last segment has no wildcard also matches everything below the directory it names (`hr`, `/apps/github`); one ending in a wildcard matches only what it names (`docs/*`). No character classes, `\`, `!`, `#` or spaces. Paths decide only for code (CODEOWNERS, scm).
- `position` (integer, required): Precedence: a later ownership wins a path or an item both match
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

```json
{
  "deputyRefs": [
    "paul.schmid@muster-it.example"
  ],
  "description": "Kotlin-Code der Android-App.",
  "id": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b02",
  "itemTypes": [],
  "key": "android",
  "labelId": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c06",
  "matchLabelIds": [],
  "name": "Android-App",
  "ownerRef": "marie.wagner@muster-it.example",
  "ownerTeamId": null,
  "parentId": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01",
  "paths": [
    "app/android/**"
  ],
  "position": 3,
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/ownerships' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"deputyRefs":["paul.schmid@muster-it.example"],"description":"Kotlin-Code der Android-App.","key":"android","name":"Android-App","ownerRef":"marie.wagner@muster-it.example","parentId":"df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01","paths":["app/android/**"]}'
```

## Delete an ownership (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/ownerships/{id}`

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

Same permission as creating. Deletes the ownership's label too, which takes it off the items; while ownerships nest below it, 409 `in_use` (`details.counts.ownerships`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/ownerships/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change an ownership (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/ownerships/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); the key never changes. A new name becomes the description of the ownership's label. An empty `ownerRef`, `ownerTeamId` or `parentId` clears it; setting the person clears the team and the other way round.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `deputyRefs` (array of string): E-mails of the deputies
- `description` (string): Description (max length 2000)
- `itemTypes` (array of string): Item type keys
- `key` (string): Create: key; fixed afterwards
- `matchLabelIds` (array of string (uuid)): Plain labels (never `owner::…`)
- `name` (string): Display name (max length 80)
- `ownerRef` (string): E-mail of the owner person; empty clears it on PATCH
- `ownerTeamId` (string): Owning team; empty clears it on PATCH
- `parentId` (string): Parent ownership; empty clears it on PATCH
- `paths` (array of string): Repository path patterns (see Ownership.paths)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "paths": [
    "app/android/**",
    "app/shared/push/**"
  ],
  "version": 1
}
```

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

- `deputyRefs` (array of string, required): E-mails of the deputies (members, at least developer); need an owner of their own
- `description` (string, required): Description (max length 2000)
- `id` (string (uuid), required): Ownership id
- `itemTypes` (array of string, required): Item type keys: items of these types belong here (without an owner:: label)
- `key` (string, required): Key; never changes (its label is `owner::<key>`)
- `labelId` (string (uuid), required): The ownership's label `owner::<key>`; items carry it and it wins over the matchers
- `matchLabelIds` (array of string (uuid), required): Plain labels (never `owner::…`): items carrying one belong here (without an owner:: label); the later position wins
- `name` (string, required): Display name (max length 80)
- `ownerRef` (string, nullable, required): E-mail of the owner person (a member, at least developer); exclusive with ownerTeamId
- `ownerTeamId` (string (uuid), nullable, required): The owning team; exclusive with ownerRef. Neither is allowed only with a parent (inherited)
- `parentId` (string (uuid), nullable, required): The parent ownership (same project, no cycle, at most 4 levels); without an owner of its own the nearest ancestor's applies
- `paths` (array of string, required): Repository path patterns, the CODEOWNERS subset: segments separated by `/`, `*` and `?` within a segment, `**` as a whole segment for any number of directories. A pattern without `/` (other than a trailing one) matches at any depth, one with `/` is relative to the root (a leading `/` anchors explicitly); a trailing `/` matches directories. A pattern whose last segment has no wildcard also matches everything below the directory it names (`hr`, `/apps/github`); one ending in a wildcard matches only what it names (`docs/*`). No character classes, `\`, `!`, `#` or spaces. Paths decide only for code (CODEOWNERS, scm).
- `position` (integer, required): Precedence: a later ownership wins a path or an item both match
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "deputyRefs": [
    "paul.schmid@muster-it.example"
  ],
  "description": "Kotlin-Code der Android-App.",
  "id": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b02",
  "itemTypes": [],
  "key": "android",
  "labelId": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c06",
  "matchLabelIds": [],
  "name": "Android-App",
  "ownerRef": "marie.wagner@muster-it.example",
  "ownerTeamId": null,
  "parentId": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01",
  "paths": [
    "app/android/**"
  ],
  "position": 3,
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/ownerships/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"paths":["app/android/**","app/shared/push/**"],"version":1}'
```

## List the teams of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/teams`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The teams (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Team, required)
  - `description` (string, required): Description (max length 2000)
  - `id` (string (uuid), required): Team id
  - `key` (string, required): Team key; never changes
  - `memberRefs` (array of string, required): E-mails, the first is the lead
  - `name` (string, required): Display name (max length 80)
  - `position` (integer, required): Order in the configuration
  - `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "items": [
    {
      "description": "Entwickler der iOS- und Android-App; Paul leitet das Team.",
      "id": "ce8f9a0b-1c2d-4e3f-8a01-8c9d0e1f2a01",
      "key": "mobile",
      "memberRefs": [
        "paul.schmid@muster-it.example",
        "marie.wagner@muster-it.example"
      ],
      "name": "Mobile-Team",
      "position": 0,
      "version": 1
    }
  ]
}
```

### Example request

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

## Create a team (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/teams`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. 1 to 50 members, project members with at least the developer role (400 `memberRefs`); the first is the lead. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `description` (string): Description (max length 2000)
- `key` (string): Create: team key; fixed afterwards
- `memberRefs` (array of string): E-mails, the first is the lead
- `name` (string): Display name (max length 80)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "description": "Entwickler der iOS- und Android-App; Paul leitet das Team.",
  "key": "mobile",
  "memberRefs": [
    "paul.schmid@muster-it.example",
    "marie.wagner@muster-it.example"
  ],
  "name": "Mobile-Team"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `description` (string, required): Description (max length 2000)
- `id` (string (uuid), required): Team id
- `key` (string, required): Team key; never changes
- `memberRefs` (array of string, required): E-mails, the first is the lead
- `name` (string, required): Display name (max length 80)
- `position` (integer, required): Order in the configuration
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

```json
{
  "description": "Entwickler der iOS- und Android-App; Paul leitet das Team.",
  "id": "ce8f9a0b-1c2d-4e3f-8a01-8c9d0e1f2a01",
  "key": "mobile",
  "memberRefs": [
    "paul.schmid@muster-it.example",
    "marie.wagner@muster-it.example"
  ],
  "name": "Mobile-Team",
  "position": 0,
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/teams' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Entwickler der iOS- und Android-App; Paul leitet das Team.","key":"mobile","memberRefs":["paul.schmid@muster-it.example","marie.wagner@muster-it.example"],"name":"Mobile-Team"}'
```

## Delete a team (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/teams/{id}`

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

Same permission as creating. While ownerships have the team as owner, 409 `in_use` (`details.counts.ownerships`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/teams/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a team (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/teams/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); the key never changes; `memberRefs` replaces the members.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `description` (string): Description (max length 2000)
- `key` (string): Create: team key; fixed afterwards
- `memberRefs` (array of string): E-mails, the first is the lead
- `name` (string): Display name (max length 80)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "description": "Entwickler der iOS- und Android-App; Marie leitet das Team.",
  "memberRefs": [
    "marie.wagner@muster-it.example",
    "paul.schmid@muster-it.example"
  ],
  "version": 1
}
```

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

- `description` (string, required): Description (max length 2000)
- `id` (string (uuid), required): Team id
- `key` (string, required): Team key; never changes
- `memberRefs` (array of string, required): E-mails, the first is the lead
- `name` (string, required): Display name (max length 80)
- `position` (integer, required): Order in the configuration
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "description": "Entwickler der iOS- und Android-App; Paul leitet das Team.",
  "id": "ce8f9a0b-1c2d-4e3f-8a01-8c9d0e1f2a01",
  "key": "mobile",
  "memberRefs": [
    "paul.schmid@muster-it.example",
    "marie.wagner@muster-it.example"
  ],
  "name": "Mobile-Team",
  "position": 0,
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/teams/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Entwickler der iOS- und Android-App; Marie leitet das Team.","memberRefs":["marie.wagner@muster-it.example","paul.schmid@muster-it.example"],"version":1}'
```

## Render the ownerships as a CODEOWNERS file (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/codeowners`

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

Requires `tenant:forge:read` and a project the caller sees. The ownerships in precedence order, one line per path pattern with the logins of the effective owner (a team: its members) and deputies who linked an account at the provider of the project's default repository (scm; `.github/CODEOWNERS` for GitHub, `.gitlab/CODEOWNERS` for GitLab, GitHub without a repository); the others are named in a comment and in `unlinked`. An ownership without any linked owner keeps its lines without owners, so it still overrides earlier ones as in forge. Item types and labels have no CODEOWNERS form and are not written. `ownerships` summarises them like scm's answer (`paths` = number of path patterns). Nothing is written to the provider. 503 `unavailable` when scm cannot be asked.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The file (`application/json`)
- **404** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `content` (string, required): The CODEOWNERS file as text (nothing is written to GitHub)
- `ownerships` (array of OwnershipSummary, required): Every ownership with its effective owner and path pattern count
  - `deputies` (array of string, required): E-mails of the deputies
  - `key` (string, required): Ownership key
  - `name` (string, required): Ownership name
  - `paths` (integer, required): How many of the asked paths the ownership owns (in the CODEOWNERS answer: its path patterns)
  - `primary` (string, required): E-mail of the effective owner, or the lead of the owning team
  - `team` (object): Set when the effective owner is a team
    - `key` (string, required): Team key
    - `members` (array of string, required): E-mails, the lead first
    - `name` (string, required): Team name
- `ownershipsConfigured` (boolean, required): The project has at least one ownership
- `path` (string, required): Where GitHub reads it: .github/CODEOWNERS
- `unlinked` (array of string, required): Owners and deputies without a linked GitHub account

Example 200 answer:

```json
{
  "content": "# Generated by ConnectCloud forge (project APP). Edit the ownerships in forge, not this file.\n\n# Apps (apps)\napp/** @paul-schmid-mi @marie-wagner-mi\n\n# Android-App (android)\napp/android/** @marie-wagner-mi @paul-schmid-mi\n\n# API-Client (api-client)\n# no GitHub login linked: emma.maier@muster-it.example\napp/shared/api/** @marie-wagner-mi\napp/shared/auth/** @marie-wagner-mi\n",
  "ownerships": [
    {
      "deputies": [],
      "key": "apps",
      "name": "Apps",
      "paths": 1,
      "primary": "paul.schmid@muster-it.example",
      "team": {
        "key": "mobile",
        "members": [
          "paul.schmid@muster-it.example",
          "marie.wagner@muster-it.example"
        ],
        "name": "Mobile-Team"
      }
    },
    {
      "deputies": [
        "paul.schmid@muster-it.example"
      ],
      "key": "qualitaet",
      "name": "Qualitätssicherung",
      "paths": 0,
      "primary": "emma.maier@muster-it.example"
    },
    {
      "deputies": [
        "paul.schmid@muster-it.example"
      ],
      "key": "android",
      "name": "Android-App",
      "paths": 1,
      "primary": "marie.wagner@muster-it.example"
    },
    {
      "deputies": [
        "marie.wagner@muster-it.example"
      ],
      "key": "api-client",
      "name": "API-Client",
      "paths": 2,
      "primary": "emma.maier@muster-it.example"
    }
  ],
  "ownershipsConfigured": true,
  "path": ".github/CODEOWNERS",
  "unlinked": [
    "emma.maier@muster-it.example"
  ]
}
```

### Example request

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

## List the custom fields of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/custom-fields`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The custom fields (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of CustomField, required)
  - `id` (string (uuid), required): Field id
  - `key` (string, required): Field key: the key in `customFields` of an item; never changes
  - `kind` (string, required): Value type; never changes (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
  - `label` (string, required): Display label
  - `options` (array of FieldOption, required): Choices of select and multiselect fields
    - `label` (string, required): Display label
    - `value` (string, required): Stored value
    - `color` (string): Color token or #rrggbb (optional)
  - `position` (integer, required): Order in the configuration
  - `required` (boolean, required): Items of the types the field applies to need a value
  - `typeKeys` (array of string, required): Item type keys; empty = every type
  - `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "items": [
    {
      "id": "9b5c6d7e-8f9a-4b0c-9dbe-5f6a7b8c9d01",
      "key": "story_points",
      "kind": "number",
      "label": "Story Points",
      "options": [],
      "position": 0,
      "required": false,
      "typeKeys": [
        "story",
        "aufgabe",
        "fehler"
      ],
      "version": 1
    }
  ]
}
```

### Example request

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

## Create a custom field (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/custom-fields`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `key` (string): Create: field key; fixed afterwards
- `kind` (string): Create: value type; fixed afterwards (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
- `label` (string): Display label (max length 80)
- `options` (array of FieldOption): Choices of select and multiselect fields
  - `label` (string, required): Display label
  - `value` (string, required): Stored value
  - `color` (string): Color token or #rrggbb (optional)
- `required` (boolean): Items need a value
- `typeKeys` (array of string): Item type keys the field applies to; empty = every type
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "key": "plattform",
  "kind": "select",
  "label": "Plattform",
  "options": [
    {
      "label": "iOS",
      "value": "ios"
    },
    {
      "color": "success",
      "label": "Android",
      "value": "android"
    }
  ],
  "typeKeys": [
    "fehler"
  ]
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `id` (string (uuid), required): Field id
- `key` (string, required): Field key: the key in `customFields` of an item; never changes
- `kind` (string, required): Value type; never changes (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
- `label` (string, required): Display label
- `options` (array of FieldOption, required): Choices of select and multiselect fields
  - `label` (string, required): Display label
  - `value` (string, required): Stored value
  - `color` (string): Color token or #rrggbb (optional)
- `position` (integer, required): Order in the configuration
- `required` (boolean, required): Items of the types the field applies to need a value
- `typeKeys` (array of string, required): Item type keys; empty = every type
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

```json
{
  "id": "9b5c6d7e-8f9a-4b0c-9dbe-5f6a7b8c9d01",
  "key": "story_points",
  "kind": "number",
  "label": "Story Points",
  "options": [],
  "position": 0,
  "required": false,
  "typeKeys": [
    "story",
    "aufgabe",
    "fehler"
  ],
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/custom-fields' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"key":"plattform","kind":"select","label":"Plattform","options":[{"label":"iOS","value":"ios"},{"color":"success","label":"Android","value":"android"}],"typeKeys":["fehler"]}'
```

## Delete a custom field (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/custom-fields/{id}`

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

Same permission as creating. A row other configuration or items still reference answers 409 `in_use` with `details.counts` (for a section definition the items with content in it); deleting a label or an empty section takes it off the items.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/custom-fields/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a custom field (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/custom-fields/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); keys never change.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string): Create: field key; fixed afterwards
- `kind` (string): Create: value type; fixed afterwards (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
- `label` (string): Display label (max length 80)
- `options` (array of FieldOption): Choices of select and multiselect fields
  - `label` (string, required): Display label
  - `value` (string, required): Stored value
  - `color` (string): Color token or #rrggbb (optional)
- `required` (boolean): Items need a value
- `typeKeys` (array of string): Item type keys the field applies to; empty = every type
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "required": true,
  "typeKeys": [
    "story"
  ],
  "version": 1
}
```

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

- `id` (string (uuid), required): Field id
- `key` (string, required): Field key: the key in `customFields` of an item; never changes
- `kind` (string, required): Value type; never changes (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
- `label` (string, required): Display label
- `options` (array of FieldOption, required): Choices of select and multiselect fields
  - `label` (string, required): Display label
  - `value` (string, required): Stored value
  - `color` (string): Color token or #rrggbb (optional)
- `position` (integer, required): Order in the configuration
- `required` (boolean, required): Items of the types the field applies to need a value
- `typeKeys` (array of string, required): Item type keys; empty = every type
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "id": "9b5c6d7e-8f9a-4b0c-9dbe-5f6a7b8c9d01",
  "key": "story_points",
  "kind": "number",
  "label": "Story Points",
  "options": [],
  "position": 0,
  "required": false,
  "typeKeys": [
    "story",
    "aufgabe",
    "fehler"
  ],
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/custom-fields/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"required":true,"typeKeys":["story"],"version":1}'
```

## List the item templates of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/item-templates`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The item templates (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ItemTemplate, required)
  - `body` (string, required): Markdown
  - `id` (string (uuid), required): Template id
  - `key` (string, required): Template key (`templateKey` of a new item)
  - `labelIds` (array of string (uuid), required): Labels it sets
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `title` (string, required): Title it prefills
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
  - `typeId` (string (uuid), nullable): Item type it sets; null = none

Example 200 answer:

```json
{
  "items": [
    {
      "body": "## Beobachtet\n\n## Erwartet\n\n## Schritte zum Nachstellen\n\n1. \n",
      "id": "ac6d7e8f-9a0b-4c1d-8ecf-6a7b8c9d0e01",
      "key": "fehlerbericht",
      "labelIds": [
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04"
      ],
      "name": "Fehlerbericht",
      "position": 0,
      "title": "",
      "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
      "version": 1
    }
  ]
}
```

### Example request

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

## Create an item template (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/item-templates`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `body` (string): Description it prefills (Markdown) (max length 100000)
- `key` (string): Create: template key; fixed afterwards
- `labelIds` (array of string (uuid)): Labels it sets
- `name` (string): Display name (max length 80)
- `title` (string): Title it prefills (max length 300)
- `typeId` (string (uuid), nullable): Item type it sets; null clears it
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "body": "## Gerät und Version\n\n## Was wurde zuletzt getan?\n\n## Absturzbericht (Anhang)\n",
  "key": "absturz",
  "labelIds": [
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"
  ],
  "name": "Absturzbericht",
  "title": "Absturz: ",
  "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `body` (string, required): Markdown
- `id` (string (uuid), required): Template id
- `key` (string, required): Template key (`templateKey` of a new item)
- `labelIds` (array of string (uuid), required): Labels it sets
- `name` (string, required): Display name
- `position` (integer, required): Order in the configuration
- `title` (string, required): Title it prefills
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `typeId` (string (uuid), nullable): Item type it sets; null = none

Example 201 answer:

```json
{
  "body": "## Beobachtet\n\n## Erwartet\n\n## Schritte zum Nachstellen\n\n1. \n",
  "id": "ac6d7e8f-9a0b-4c1d-8ecf-6a7b8c9d0e01",
  "key": "fehlerbericht",
  "labelIds": [
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04"
  ],
  "name": "Fehlerbericht",
  "position": 0,
  "title": "",
  "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/item-templates' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"## Gerät und Version\n\n## Was wurde zuletzt getan?\n\n## Absturzbericht (Anhang)\n","key":"absturz","labelIds":["8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04","8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"],"name":"Absturzbericht","title":"Absturz: ","typeId":"7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04"}'
```

## Delete an item template (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/item-templates/{id}`

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

Same permission as creating. A row other configuration or items still reference answers 409 `in_use` with `details.counts` (for a section definition the items with content in it); deleting a label or an empty section takes it off the items.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/item-templates/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change an item template (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/item-templates/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); keys never change.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `body` (string): Description it prefills (Markdown) (max length 100000)
- `key` (string): Create: template key; fixed afterwards
- `labelIds` (array of string (uuid)): Labels it sets
- `name` (string): Display name (max length 80)
- `title` (string): Title it prefills (max length 300)
- `typeId` (string (uuid), nullable): Item type it sets; null clears it
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "labelIds": [
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c02"
  ],
  "version": 1
}
```

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

- `body` (string, required): Markdown
- `id` (string (uuid), required): Template id
- `key` (string, required): Template key (`templateKey` of a new item)
- `labelIds` (array of string (uuid), required): Labels it sets
- `name` (string, required): Display name
- `position` (integer, required): Order in the configuration
- `title` (string, required): Title it prefills
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `typeId` (string (uuid), nullable): Item type it sets; null = none

Example 200 answer:

```json
{
  "body": "## Beobachtet\n\n## Erwartet\n\n## Schritte zum Nachstellen\n\n1. \n",
  "id": "ac6d7e8f-9a0b-4c1d-8ecf-6a7b8c9d0e01",
  "key": "fehlerbericht",
  "labelIds": [
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04"
  ],
  "name": "Fehlerbericht",
  "position": 0,
  "title": "",
  "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/item-templates/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"labelIds":["8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04","8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c02"],"version":1}'
```

## List the section definitions of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/section-defs`

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

Requires `tenant:forge:read` and a project the caller sees.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The section definitions (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of SectionDef, required)
  - `id` (string (uuid), required): Section definition id
  - `key` (string, required): Section key; never changes
  - `kind` (string, required): markdown or checklist (one of `markdown`, `checklist`)
  - `label` (string, required): Display label
  - `placement` (string, required): Where the portal shows it: a tab or the side column (one of `tab`, `aside`)
  - `position` (integer, required): Order in the configuration
  - `typeKeys` (array of string, required): Item type keys the section applies to; empty = every type
  - `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "items": [
    {
      "id": "bd7e8f9a-0b1c-4d2e-9fd0-7b8c9d0e1f01",
      "key": "plan",
      "kind": "markdown",
      "label": "Plan",
      "placement": "tab",
      "position": 0,
      "typeKeys": [],
      "version": 1
    },
    {
      "id": "bd7e8f9a-0b1c-4d2e-9fd0-7b8c9d0e1f02",
      "key": "agent_notes",
      "kind": "markdown",
      "label": "Notizen für Agenten",
      "placement": "tab",
      "position": 1,
      "typeKeys": [],
      "version": 1
    },
    {
      "id": "bd7e8f9a-0b1c-4d2e-9fd0-7b8c9d0e1f03",
      "key": "acceptance",
      "kind": "checklist",
      "label": "Akzeptanzkriterien",
      "placement": "tab",
      "position": 2,
      "typeKeys": [],
      "version": 1
    }
  ]
}
```

### Example request

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

## Create a section definition (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/section-defs`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `key` (string): Create: section key; fixed afterwards
- `kind` (string): markdown (default) or checklist (one of `markdown`, `checklist`)
- `label` (string): Display label (max length 80)
- `placement` (string): tab (default) or aside (one of `tab`, `aside`)
- `typeKeys` (array of string): Item type keys; empty = every type
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "key": "testplan",
  "kind": "checklist",
  "label": "Testplan",
  "placement": "aside",
  "typeKeys": [
    "story",
    "fehler"
  ]
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `id` (string (uuid), required): Section definition id
- `key` (string, required): Section key; never changes
- `kind` (string, required): markdown or checklist (one of `markdown`, `checklist`)
- `label` (string, required): Display label
- `placement` (string, required): Where the portal shows it: a tab or the side column (one of `tab`, `aside`)
- `position` (integer, required): Order in the configuration
- `typeKeys` (array of string, required): Item type keys the section applies to; empty = every type
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

```json
{
  "id": "bd7e8f9a-0b1c-4d2e-9fd0-7b8c9d0e1f03",
  "key": "acceptance",
  "kind": "checklist",
  "label": "Akzeptanzkriterien",
  "placement": "tab",
  "position": 2,
  "typeKeys": [],
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/section-defs' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"key":"testplan","kind":"checklist","label":"Testplan","placement":"aside","typeKeys":["story","fehler"]}'
```

## Delete a section definition (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/section-defs/{id}`

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

Same permission as creating. A row other configuration or items still reference answers 409 `in_use` with `details.counts` (for a section definition the items with content in it); deleting a label or an empty section takes it off the items.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/section-defs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a section definition (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/section-defs/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); keys never change.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `key` (string): Create: section key; fixed afterwards
- `kind` (string): markdown (default) or checklist (one of `markdown`, `checklist`)
- `label` (string): Display label (max length 80)
- `placement` (string): tab (default) or aside (one of `tab`, `aside`)
- `typeKeys` (array of string): Item type keys; empty = every type
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "placement": "aside",
  "version": 1
}
```

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

- `id` (string (uuid), required): Section definition id
- `key` (string, required): Section key; never changes
- `kind` (string, required): markdown or checklist (one of `markdown`, `checklist`)
- `label` (string, required): Display label
- `placement` (string, required): Where the portal shows it: a tab or the side column (one of `tab`, `aside`)
- `position` (integer, required): Order in the configuration
- `typeKeys` (array of string, required): Item type keys the section applies to; empty = every type
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "id": "bd7e8f9a-0b1c-4d2e-9fd0-7b8c9d0e1f03",
  "key": "acceptance",
  "kind": "checklist",
  "label": "Akzeptanzkriterien",
  "placement": "tab",
  "position": 2,
  "typeKeys": [],
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/section-defs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"placement":"aside","version":1}'
```

# Automations

## List the automations of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/automations`

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

Requires `tenant:forge:read` and a project the caller sees. In position order, each with its newest execution (`lastRun`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The automations (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Automation, required)
  - `blocking` (boolean, required): true: a failure of the automation refuses the change that triggered it (422 `automation_blocked`); false (default): the failure is logged and the change is kept
  - `createdAt` (string (date-time), required): When it was created
  - `createdBy` (string, required): E-mail of who created it
  - `description` (string, required): The description of the definition
  - `enabled` (boolean, required): Only an enabled automation with a valid definition runs
  - `events` (array of string, required): The event types its triggers listen to
  - `id` (string (uuid), required): Automation id
  - `key` (string, required): The key of the definition, unique per project
  - `manual` (boolean, required): Whether the definition has a manual trigger
  - `name` (string, required): The name of the definition (the actor name of the automation's changes)
  - `position` (integer, required): Automations that listen to the same event run in position order
  - `scope` (string, required): What the automation belongs to: `project:<project id>`
  - `updatedAt` (string (date-time), required): When it was changed last
  - `updatedBy` (string, required): E-mail of who changed it last
  - `valid` (boolean, required): The definition had no error when it was saved; a draft with errors (`false`) cannot be enabled
  - `version` (integer, required): Name it when changing or deleting the automation
  - `yaml` (string, required): The definition (YAML of the flow language)
  - `lastRun` (AutomationRun): One execution of an automation in its log.
    - `automationId` (string (uuid), required): The automation that ran
    - `createdAt` (string (date-time), required): When the run happened
    - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
    - `durationMs` (integer, required): Duration in milliseconds
    - `id` (string (uuid), required): Run id
    - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
    - `steps` (integer, required): The number of nodes that ran
    - `triggerKind` (string, required): What started it: an event or a manual start (one of `event`, `manual`)
    - `version` (integer, required): The version of the automation that ran
    - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
    - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
    - `errorMessage` (string): Failed runs: the error text
    - `event` (string): The event type that started it
    - `node` (string): The id of the node that failed
    - `startedBy` (string): The person or actor behind the triggering change
    - `subject` (string): What the event was about: the item's id
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "blocking": false,
      "createdAt": "2026-09-23T09:00:00Z",
      "createdBy": "emma.maier@muster-it.example",
      "description": "Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.",
      "enabled": true,
      "events": [
        "forge.item.children_done"
      ],
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
      "key": "unteraufgaben-erledigt",
      "lastRun": {
        "actorKind": "person",
        "automationId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
        "createdAt": "2026-10-28T15:00:02Z",
        "depth": 1,
        "durationMs": 14,
        "event": "forge.item.children_done",
        "id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f01",
        "outcome": "succeeded",
        "startedBy": "marie.wagner@muster-it.example",
        "steps": 1,
        "subject": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
        "triggerKind": "event",
        "version": 2
      },
      "manual": false,
      "name": "Unteraufgaben erledigt → Eltern erledigt",
      "position": 0,
      "scope": "project:0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "updatedAt": "2026-09-23T09:30:00Z",
      "updatedBy": "emma.maier@muster-it.example",
      "valid": true,
      "version": 2,
      "yaml": "schemaVersion: 1\nkey: unteraufgaben-erledigt\nname: \"Unteraufgaben erledigt → Eltern erledigt\"\ndescription: Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.\ntriggers:\n  - { id: kinder_erledigt, kind: event, event: forge.item.children_done, includeAutomated: true }\nnodes:\n  erledigen:\n    kind: action\n    name: Auf Erledigt setzen\n    action: forge.item.transition\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", category: done }\nedges:\n  - kinder_erledigt -\u003e erledigen\n"
    }
  ],
  "total": 1
}
```

### Example request

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

## Create an automation of a project (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/automations`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin; an archived project is 409 `project_archived`. An automation is a definition in the flow language (ADR 0044, the YAML of flows): triggers that listen to forge's item events (`GET …/automations/catalog` lists them with their payload, which is `trigger.data`), an optional filter, and nodes – `if`, `switch`, `set`, `end`, `mail` and the actions `forge.item.transition`, `forge.item.add_label`, `forge.item.remove_label`, `forge.item.assign` and `forge.comment.add`. It runs immediately, in the transaction of the item change that triggered it, as actor kind `automation` (ref `automation:<id>`, name = the automation's name) and through the normal item rules (workflow transitions, scoped labels, auto-watch); member roles are not checked, and it changes only items of its own project (another project's key fails the action with `out_of_scope`). Without `yaml` the automation starts from a skeleton named `name`; key and name come from the definition, the key is unique per project (409 `key_taken`). A definition that cannot be read is 422 `invalid_definition` (`details.diagnostics`); one with errors is stored as a draft (`valid: false`) and cannot be enabled (422 `invalid_definition`). Everything only a flow in the background can run (wait, human tasks, schedules, other modules' actions, …) is the finding `needs_durable`. An action the item rules refuse (e.g. a transition the workflow does not allow) fails the run: its changes are rolled back and the failure is in the log (`GET …/{id}/runs`), the triggering change is kept – unless the automation is `blocking`, then the change is refused with 422 `automation_blocked` (changes made by scm or the system are never refused). A trigger ignores changes made by automations unless it says `includeAutomated: true`; then automations start each other at most 4 levels deep, each at most once per item per change, at most 20 per event.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `blocking` (boolean): A failure refuses the triggering change (422 `automation_blocked`) (default `false`)
- `enabled` (boolean): Needs a definition without errors (default `false`)
- `name` (string): Without `yaml`: the name of the new automation (its key is derived from it) (max length 200)
- `yaml` (string): The definition (YAML of the flow language, at most 256 KiB); key and name are read from it

Example:

```json
{
  "blocking": false,
  "enabled": true,
  "yaml": "schemaVersion: 1\nkey: neue-fehler-label-bug\nname: Neue Fehler bekommen das Label bug\ndescription: Setzt auf jedem neuen Element vom Typ Fehler das Label bug.\ntriggers:\n  - { id: neu, kind: event, event: forge.item.created, filter: 'trigger.data.typeKey == \"fehler\"' }\nnodes:\n  etikettieren:\n    kind: action\n    name: Label setzen\n    action: forge.item.add_label\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", label: bug }\nedges:\n  - neu -\u003e etikettieren\n"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 201 answer:

- `blocking` (boolean, required): true: a failure of the automation refuses the change that triggered it (422 `automation_blocked`); false (default): the failure is logged and the change is kept
- `createdAt` (string (date-time), required): When it was created
- `createdBy` (string, required): E-mail of who created it
- `description` (string, required): The description of the definition
- `enabled` (boolean, required): Only an enabled automation with a valid definition runs
- `events` (array of string, required): The event types its triggers listen to
- `id` (string (uuid), required): Automation id
- `key` (string, required): The key of the definition, unique per project
- `manual` (boolean, required): Whether the definition has a manual trigger
- `name` (string, required): The name of the definition (the actor name of the automation's changes)
- `position` (integer, required): Automations that listen to the same event run in position order
- `scope` (string, required): What the automation belongs to: `project:<project id>`
- `updatedAt` (string (date-time), required): When it was changed last
- `updatedBy` (string, required): E-mail of who changed it last
- `valid` (boolean, required): The definition had no error when it was saved; a draft with errors (`false`) cannot be enabled
- `version` (integer, required): Name it when changing or deleting the automation
- `yaml` (string, required): The definition (YAML of the flow language)
- `lastRun` (AutomationRun): One execution of an automation in its log.
  - `automationId` (string (uuid), required): The automation that ran
  - `createdAt` (string (date-time), required): When the run happened
  - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
  - `durationMs` (integer, required): Duration in milliseconds
  - `id` (string (uuid), required): Run id
  - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
  - `steps` (integer, required): The number of nodes that ran
  - `triggerKind` (string, required): What started it: an event or a manual start (one of `event`, `manual`)
  - `version` (integer, required): The version of the automation that ran
  - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
  - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
  - `errorMessage` (string): Failed runs: the error text
  - `event` (string): The event type that started it
  - `node` (string): The id of the node that failed
  - `startedBy` (string): The person or actor behind the triggering change
  - `subject` (string): What the event was about: the item's id

Example 201 answer:

```json
{
  "blocking": false,
  "createdAt": "2026-09-23T09:00:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "description": "Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.",
  "enabled": true,
  "events": [
    "forge.item.children_done"
  ],
  "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
  "key": "unteraufgaben-erledigt",
  "lastRun": {
    "actorKind": "person",
    "automationId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
    "createdAt": "2026-10-28T15:00:02Z",
    "depth": 1,
    "durationMs": 14,
    "event": "forge.item.children_done",
    "id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f01",
    "outcome": "succeeded",
    "startedBy": "marie.wagner@muster-it.example",
    "steps": 1,
    "subject": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
    "triggerKind": "event",
    "version": 2
  },
  "manual": false,
  "name": "Unteraufgaben erledigt → Eltern erledigt",
  "position": 0,
  "scope": "project:0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "updatedAt": "2026-09-23T09:30:00Z",
  "updatedBy": "emma.maier@muster-it.example",
  "valid": true,
  "version": 2,
  "yaml": "schemaVersion: 1\nkey: unteraufgaben-erledigt\nname: \"Unteraufgaben erledigt → Eltern erledigt\"\ndescription: Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.\ntriggers:\n  - { id: kinder_erledigt, kind: event, event: forge.item.children_done, includeAutomated: true }\nnodes:\n  erledigen:\n    kind: action\n    name: Auf Erledigt setzen\n    action: forge.item.transition\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", category: done }\nedges:\n  - kinder_erledigt -\u003e erledigen\n"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"blocking":false,"enabled":true,"yaml":"schemaVersion: 1\nkey: neue-fehler-label-bug\nname: Neue Fehler bekommen das Label bug\ndescription: Setzt auf jedem neuen Element vom Typ Fehler das Label bug.\ntriggers:\n  - { id: neu, kind: event, event: forge.item.created, filter: '\''trigger.data.typeKey == \"fehler\"'\'' }\nnodes:\n  etikettieren:\n    kind: action\n    name: Label setzen\n    action: forge.item.add_label\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", label: bug }\nedges:\n  - neu -\u003e etikettieren\n"}'
```

## What a project's automations can use (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/automations/catalog`

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

Requires `tenant:forge:read` and a project the caller sees. The catalogue of the builder – the shape of flows' catalogue, cut down to what runs immediately – forge's item events with their payload schemas, the actions with an immediate implementation, the node and trigger kinds of the inline profile, the expression namespaces and functions, the limits, and per action the parameters the builder prefills (`defaults`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The catalogue (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `defaults` (object, required): Per action key, the parameters the builder prefills when the action is added: the ones that address the item the event is about
- `functions` (array of string, required): The functions of the expression language
- `kinds` (array of object, required): The node kinds that run immediately, with their default ports and fields
  - `fields` (array of AutomationField, required): Fields the inspector edits
    - `path` (string, required): Dotted below the node or trigger
    - `type` (string, required): Editor type of the field
    - `options` (array of string): Allowed values of a choice field
    - `when` (object): The field applies only while the sibling field has one of the values
      - `equals` (array of string): Values of the sibling field for which this field applies
      - `field` (string): The sibling field
  - `name` (string, required): Node kind
  - `ports` (array of string, required): Default output ports of the kind
  - `retry` (boolean, required): Always false – an immediate automation is not retried
- `limits` (object, required): Limits of immediate automations
  - `maxDepth` (integer, required): How deep automations start each other
  - `maxNodes` (integer, required): The most nodes of an immediate automation
  - `maxPerEvent` (integer, required): The most automations one event starts
- `modules` (array of object, required): forge's flows manifest, cut down to the actions with an immediate implementation: `nodes` (key, labels, parameter and output schemas) and `events` (type, labels, payload schema)
  - `events` (array of object): The events a trigger can listen to
  - `module` (string): Module of the manifest
  - `nodes` (array of object): The actions with an immediate implementation
  - `revision` (string): Revision of the manifest
  - `version` (integer): Manifest format version
- `namespaces` (array of string, required): The names expressions read
- `profile` (string, required): The validation profile: always `inline` (runs immediately) (one of `inline`)
- `retryFields` (array of AutomationField, required): Always empty
  - `path` (string, required): Dotted below the node or trigger
  - `type` (string, required): Editor type of the field
  - `options` (array of string): Allowed values of a choice field
  - `when` (object): The field applies only while the sibling field has one of the values
    - `equals` (array of string): Values of the sibling field for which this field applies
    - `field` (string): The sibling field
- `triggers` (array of object, required): The trigger kinds a definition may use here (forge - event only; nothing starts an automation by hand) with their fields
  - `fields` (array of AutomationField, required): Fields the inspector edits
    - `path` (string, required): Dotted below the node or trigger
    - `type` (string, required): Editor type of the field
    - `options` (array of string): Allowed values of a choice field
    - `when` (object): The field applies only while the sibling field has one of the values
      - `equals` (array of string): Values of the sibling field for which this field applies
      - `field` (string): The sibling field
  - `name` (string, required): Trigger kind

Example 200 answer:

```json
{
  "defaults": {
    "forge.item.add_label": {
      "key": "{{ trigger.data.projectKey }}",
      "number": "{{ trigger.data.number }}"
    },
    "forge.item.transition": {
      "key": "{{ trigger.data.projectKey }}",
      "number": "{{ trigger.data.number }}"
    }
  },
  "functions": [
    "len",
    "any",
    "all",
    "hasPrefix",
    "hasSuffix",
    "lower",
    "upper",
    "now"
  ],
  "kinds": [
    {
      "fields": [
        {
          "path": "condition",
          "type": "condition"
        }
      ],
      "name": "if",
      "ports": [
        "true",
        "false",
        "error"
      ],
      "retry": false
    },
    {
      "fields": [
        {
          "path": "action",
          "type": "action"
        },
        {
          "path": "params",
          "type": "params"
        }
      ],
      "name": "action",
      "ports": [
        "main",
        "error"
      ],
      "retry": false
    }
  ],
  "limits": {
    "maxDepth": 4,
    "maxNodes": 25,
    "maxPerEvent": 20
  },
  "modules": [
    {
      "events": [
        {
          "label": {
            "de": "Element angelegt",
            "en": "Item created"
          },
          "type": "forge.item.created"
        },
        {
          "label": {
            "de": "Alle Unteraufgaben erledigt",
            "en": "All children done"
          },
          "type": "forge.item.children_done"
        }
      ],
      "module": "forge",
      "nodes": [
        {
          "access": "write",
          "key": "forge.item.transition",
          "label": {
            "de": "Status wechseln",
            "en": "Change status"
          }
        },
        {
          "access": "write",
          "key": "forge.item.add_label",
          "label": {
            "de": "Label hinzufügen",
            "en": "Add label"
          }
        },
        {
          "access": "write",
          "key": "forge.item.assign",
          "label": {
            "de": "Zuständige Person hinzufügen",
            "en": "Add assignee"
          }
        },
        {
          "access": "write",
          "key": "forge.comment.add",
          "label": {
            "de": "Kommentar hinzufügen",
            "en": "Add comment"
          }
        }
      ],
      "revision": "3f9c2a17",
      "version": 1
    }
  ],
  "namespaces": [
    "trigger",
    "nodes",
    "vars",
    "error",
    "run"
  ],
  "profile": "inline",
  "retryFields": [],
  "triggers": [
    {
      "fields": [
        {
          "path": "event",
          "type": "event"
        },
        {
          "path": "filter",
          "type": "condition"
        },
        {
          "path": "includeAutomated",
          "type": "boolean"
        }
      ],
      "name": "event"
    }
  ]
}
```

### Example request

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

## Check an automation's definition without storing it (tenant:forge:read)

`POST /api/forge/v1/projects/{key}/automations/validate`

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

Requires `tenant:forge:read` and a project the caller sees. Validates the YAML with the inline profile against forge's catalogue and answers the findings (the same codes, paths and positions as flows) and the ports of every node. `needsDurable` says that the definition is fine but for parts only a flow in the background can run.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `yaml` (string, required): The definition (YAML of the flow language)

Example:

```json
{
  "yaml": "schemaVersion: 1\nkey: review-erinnerung\nname: Review-Erinnerung\ntriggers:\n  - { id: review, kind: event, event: forge.item.status_changed, filter: 'trigger.data.statusKey == \"review\"' }\nnodes:\n  warten:\n    kind: wait\n    duration: 48h\n  erinnern:\n    kind: action\n    action: forge.comment.add\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", body: Das Review wartet seit zwei Tagen. }\nedges:\n  - review -\u003e warten\n  - warten -\u003e erinnern\n"
}
```

### Responses

- **200** The findings (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `diagnostics` (array of AutomationDiagnostic, required): The findings, errors and warnings
  - `code` (string, required): Stable code, e.g. `unknown_action`, `missing_param`, `expression`, `needs_durable`, `inline_ignored`
  - `message` (string, required): Human-readable text of the finding
  - `severity` (string, required): Errors keep the automation from being enabled (one of `error`, `warning`)
  - `col` (integer): Column in the YAML definition (when known)
  - `line` (integer): Line in the YAML definition (when known)
  - `nodeId` (string): The node the finding is about
  - `params` (object): `needs_durable`: `reason` (trigger, kind, action, foreign_action, foreign_event, recipient, mail_option – a mail node sets `mandatory` or `mailChannel`, which only a tenant flow without scope may –, too_many_nodes)
  - `path` (string): Dotted path in the definition
- `needsDurable` (boolean, required): A finding is `needs_durable`: the definition runs only as a flow in the background
- `permissions` (array of array of string, required): The any-of permission groups a flow with this definition would need
- `ports` (object, required): The output ports of every node that parsed, by node id (the builder's handles)
- `profile` (string, required): The profile the definition was checked with (one of `inline`)
- `valid` (boolean, required): No finding is an error

Example 200 answer:

```json
{
  "diagnostics": [
    {
      "code": "needs_durable",
      "col": 3,
      "line": 8,
      "message": "Der Knoten „warten“ kann nicht sofort laufen; als Flow im Hintergrund ist er möglich.",
      "nodeId": "warten",
      "params": {
        "reason": "kind"
      },
      "path": "nodes.warten",
      "severity": "error"
    }
  ],
  "needsDurable": true,
  "permissions": [
    [
      "tenant:forge:write",
      "tenant:forge:admin"
    ]
  ],
  "ports": {
    "erinnern": [
      "main",
      "error"
    ],
    "warten": [
      "main",
      "error"
    ]
  },
  "profile": "inline",
  "valid": false
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/validate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"yaml":"schemaVersion: 1\nkey: review-erinnerung\nname: Review-Erinnerung\ntriggers:\n  - { id: review, kind: event, event: forge.item.status_changed, filter: '\''trigger.data.statusKey == \"review\"'\'' }\nnodes:\n  warten:\n    kind: wait\n    duration: 48h\n  erinnern:\n    kind: action\n    action: forge.comment.add\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", body: Das Review wartet seit zwei Tagen. }\nedges:\n  - review -\u003e warten\n  - warten -\u003e erinnern\n"}'
```

## Set the order of a project's automations (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/automations/reorder`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin; an archived project is 409 `project_archived`. `ids` names every automation of the project exactly once (else 400 `ids`). Automations that listen to the same event run in this order.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `ids` (array of string (uuid), required): Every automation of the project, in the new order

Example:

```json
{
  "ids": [
    "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e02",
    "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01"
  ]
}
```

### Responses

- **204** Reordered
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/reorder' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"ids":["1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e02","1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01"]}'
```

## Read an automation of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/automations/{id}`

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

Requires `tenant:forge:read` and a project the caller sees. An automation of another project or tenant is 404.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The automation (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `blocking` (boolean, required): true: a failure of the automation refuses the change that triggered it (422 `automation_blocked`); false (default): the failure is logged and the change is kept
- `createdAt` (string (date-time), required): When it was created
- `createdBy` (string, required): E-mail of who created it
- `description` (string, required): The description of the definition
- `enabled` (boolean, required): Only an enabled automation with a valid definition runs
- `events` (array of string, required): The event types its triggers listen to
- `id` (string (uuid), required): Automation id
- `key` (string, required): The key of the definition, unique per project
- `manual` (boolean, required): Whether the definition has a manual trigger
- `name` (string, required): The name of the definition (the actor name of the automation's changes)
- `position` (integer, required): Automations that listen to the same event run in position order
- `scope` (string, required): What the automation belongs to: `project:<project id>`
- `updatedAt` (string (date-time), required): When it was changed last
- `updatedBy` (string, required): E-mail of who changed it last
- `valid` (boolean, required): The definition had no error when it was saved; a draft with errors (`false`) cannot be enabled
- `version` (integer, required): Name it when changing or deleting the automation
- `yaml` (string, required): The definition (YAML of the flow language)
- `lastRun` (AutomationRun): One execution of an automation in its log.
  - `automationId` (string (uuid), required): The automation that ran
  - `createdAt` (string (date-time), required): When the run happened
  - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
  - `durationMs` (integer, required): Duration in milliseconds
  - `id` (string (uuid), required): Run id
  - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
  - `steps` (integer, required): The number of nodes that ran
  - `triggerKind` (string, required): What started it: an event or a manual start (one of `event`, `manual`)
  - `version` (integer, required): The version of the automation that ran
  - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
  - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
  - `errorMessage` (string): Failed runs: the error text
  - `event` (string): The event type that started it
  - `node` (string): The id of the node that failed
  - `startedBy` (string): The person or actor behind the triggering change
  - `subject` (string): What the event was about: the item's id

Example 200 answer:

```json
{
  "blocking": false,
  "createdAt": "2026-09-23T09:00:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "description": "Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.",
  "enabled": true,
  "events": [
    "forge.item.children_done"
  ],
  "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
  "key": "unteraufgaben-erledigt",
  "lastRun": {
    "actorKind": "person",
    "automationId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
    "createdAt": "2026-10-28T15:00:02Z",
    "depth": 1,
    "durationMs": 14,
    "event": "forge.item.children_done",
    "id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f01",
    "outcome": "succeeded",
    "startedBy": "marie.wagner@muster-it.example",
    "steps": 1,
    "subject": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
    "triggerKind": "event",
    "version": 2
  },
  "manual": false,
  "name": "Unteraufgaben erledigt → Eltern erledigt",
  "position": 0,
  "scope": "project:0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "updatedAt": "2026-09-23T09:30:00Z",
  "updatedBy": "emma.maier@muster-it.example",
  "valid": true,
  "version": 2,
  "yaml": "schemaVersion: 1\nkey: unteraufgaben-erledigt\nname: \"Unteraufgaben erledigt → Eltern erledigt\"\ndescription: Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.\ntriggers:\n  - { id: kinder_erledigt, kind: event, event: forge.item.children_done, includeAutomated: true }\nnodes:\n  erledigen:\n    kind: action\n    name: Auf Erledigt setzen\n    action: forge.item.transition\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", category: done }\nedges:\n  - kinder_erledigt -\u003e erledigen\n"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete an automation and its log (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/automations/{id}`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin; an archived project is 409 `project_archived`. `version` is the version the caller read (400 without, 409 `version_conflict`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `version` | query | integer | yes | The automation's current version |
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12?version=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change an automation (tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}/automations/{id}`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin; an archived project is 409 `project_archived`. Changes what is set: the definition (`yaml`; key and name follow it), `enabled`, `blocking`. `version` is required (409 `version_conflict`). Enabling needs a definition without errors (422 `invalid_definition` with `details.diagnostics`); a definition saved with errors switches the automation off. A key another automation of the project has is 409 `key_taken`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `version` (integer, required): The version the caller read
- `blocking` (boolean): A failure refuses the triggering change (422 `automation_blocked`)
- `enabled` (boolean): Switch the automation on or off (on needs a definition without errors)
- `yaml` (string): The new definition

Example:

```json
{
  "enabled": false,
  "version": 2
}
```

### Responses

- **200** Changed (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `blocking` (boolean, required): true: a failure of the automation refuses the change that triggered it (422 `automation_blocked`); false (default): the failure is logged and the change is kept
- `createdAt` (string (date-time), required): When it was created
- `createdBy` (string, required): E-mail of who created it
- `description` (string, required): The description of the definition
- `enabled` (boolean, required): Only an enabled automation with a valid definition runs
- `events` (array of string, required): The event types its triggers listen to
- `id` (string (uuid), required): Automation id
- `key` (string, required): The key of the definition, unique per project
- `manual` (boolean, required): Whether the definition has a manual trigger
- `name` (string, required): The name of the definition (the actor name of the automation's changes)
- `position` (integer, required): Automations that listen to the same event run in position order
- `scope` (string, required): What the automation belongs to: `project:<project id>`
- `updatedAt` (string (date-time), required): When it was changed last
- `updatedBy` (string, required): E-mail of who changed it last
- `valid` (boolean, required): The definition had no error when it was saved; a draft with errors (`false`) cannot be enabled
- `version` (integer, required): Name it when changing or deleting the automation
- `yaml` (string, required): The definition (YAML of the flow language)
- `lastRun` (AutomationRun): One execution of an automation in its log.
  - `automationId` (string (uuid), required): The automation that ran
  - `createdAt` (string (date-time), required): When the run happened
  - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
  - `durationMs` (integer, required): Duration in milliseconds
  - `id` (string (uuid), required): Run id
  - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
  - `steps` (integer, required): The number of nodes that ran
  - `triggerKind` (string, required): What started it: an event or a manual start (one of `event`, `manual`)
  - `version` (integer, required): The version of the automation that ran
  - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
  - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
  - `errorMessage` (string): Failed runs: the error text
  - `event` (string): The event type that started it
  - `node` (string): The id of the node that failed
  - `startedBy` (string): The person or actor behind the triggering change
  - `subject` (string): What the event was about: the item's id

Example 200 answer:

```json
{
  "blocking": false,
  "createdAt": "2026-09-23T09:00:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "description": "Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.",
  "enabled": true,
  "events": [
    "forge.item.children_done"
  ],
  "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
  "key": "unteraufgaben-erledigt",
  "lastRun": {
    "actorKind": "person",
    "automationId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
    "createdAt": "2026-10-28T15:00:02Z",
    "depth": 1,
    "durationMs": 14,
    "event": "forge.item.children_done",
    "id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f01",
    "outcome": "succeeded",
    "startedBy": "marie.wagner@muster-it.example",
    "steps": 1,
    "subject": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
    "triggerKind": "event",
    "version": 2
  },
  "manual": false,
  "name": "Unteraufgaben erledigt → Eltern erledigt",
  "position": 0,
  "scope": "project:0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "updatedAt": "2026-09-23T09:30:00Z",
  "updatedBy": "emma.maier@muster-it.example",
  "valid": true,
  "version": 2,
  "yaml": "schemaVersion: 1\nkey: unteraufgaben-erledigt\nname: \"Unteraufgaben erledigt → Eltern erledigt\"\ndescription: Setzt ein Element auf Erledigt, sobald seine letzte offene Unteraufgabe erledigt oder verworfen ist.\ntriggers:\n  - { id: kinder_erledigt, kind: event, event: forge.item.children_done, includeAutomated: true }\nnodes:\n  erledigen:\n    kind: action\n    name: Auf Erledigt setzen\n    action: forge.item.transition\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", category: done }\nedges:\n  - kinder_erledigt -\u003e erledigen\n"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"enabled":false,"version":2}'
```

## List the last executions of an automation (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/automations/{id}/runs`

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

Requires `tenant:forge:read` and a project the caller sees. Newest first; the log keeps the last 50 executions of an automation – what triggered it, the outcome, the failing node with its error, the duration.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | (default `50`; max 50) |
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The executions (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of AutomationRun, required)
  - `automationId` (string (uuid), required): The automation that ran
  - `createdAt` (string (date-time), required): When the run happened
  - `depth` (integer, required): 1 when a person's (or another service's) change started it, n when automations started each other
  - `durationMs` (integer, required): Duration in milliseconds
  - `id` (string (uuid), required): Run id
  - `outcome` (string, required): skipped: a limit stopped it (too many automations for one event) (one of `succeeded`, `failed`, `skipped`)
  - `steps` (integer, required): The number of nodes that ran
  - `triggerKind` (string, required): What started it: an event or a manual start (one of `event`, `manual`)
  - `version` (integer, required): The version of the automation that ran
  - `actorKind` (string): Who made the triggering change (person, integration, assistant, automation, system, scm)
  - `errorCode` (string): Failed runs: the stable code, e.g. `transition_not_allowed`, `invalid`, `out_of_scope`, `expression`, `invalid_definition`, `action_failed`
  - `errorMessage` (string): Failed runs: the error text
  - `event` (string): The event type that started it
  - `node` (string): The id of the node that failed
  - `startedBy` (string): The person or actor behind the triggering change
  - `subject` (string): What the event was about: the item's id
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "actorKind": "person",
      "automationId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
      "createdAt": "2026-10-28T15:00:02Z",
      "depth": 1,
      "durationMs": 14,
      "event": "forge.item.children_done",
      "id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f01",
      "outcome": "succeeded",
      "startedBy": "marie.wagner@muster-it.example",
      "steps": 1,
      "subject": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
      "triggerKind": "event",
      "version": 2
    },
    {
      "actorKind": "person",
      "automationId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e01",
      "createdAt": "2026-11-12T12:00:01Z",
      "depth": 1,
      "durationMs": 9,
      "errorCode": "transition_not_allowed",
      "errorMessage": "the workflow does not allow the move to erledigt",
      "event": "forge.item.children_done",
      "id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f02",
      "node": "erledigen",
      "outcome": "failed",
      "startedBy": "marie.wagner@muster-it.example",
      "steps": 1,
      "subject": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c05",
      "triggerKind": "event",
      "version": 2
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/runs' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Milestones

## List the milestones of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/milestones`

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

Requires `tenant:forge:read` and a project the caller sees. Each milestone carries its `progress`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `state` | query | string |  | (one of `open`, `closed`) |
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The milestones (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of MilestoneView, required)

Example 200 answer:

```json
{
  "items": [
    {
      "closedAt": "2026-11-04T10:00:00Z",
      "createdAt": "2026-09-23T10:00:00Z",
      "description": "Erste Version im App Store und bei Google Play mit Anmeldung per Passkey.",
      "dueOn": "2026-11-04",
      "id": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c01",
      "position": 0,
      "progress": {
        "byCategory": {
          "active": 0,
          "cancelled": 1,
          "done": 8,
          "on_hold": 0,
          "todo": 0,
          "triage": 0
        },
        "estimate": {
          "done": 28,
          "total": 28
        },
        "total": 9
      },
      "releaseProvider": "github",
      "releaseRepo": "mbcomdev/demo-app",
      "releaseTag": "v1.0.0",
      "state": "closed",
      "title": "Version 1.0 – Anmeldung",
      "updatedAt": "2026-11-04T10:00:00Z",
      "version": 3
    },
    {
      "closedAt": null,
      "createdAt": "2026-09-30T13:00:00Z",
      "description": "Kunden sehen ihre Tickets mit Filtern, Seitenwechseln und einem verständlichen leeren Zustand.",
      "dueOn": "2026-11-25",
      "id": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
      "position": 1,
      "progress": {
        "byCategory": {
          "active": 2,
          "cancelled": 0,
          "done": 5,
          "on_hold": 0,
          "todo": 2,
          "triage": 0
        },
        "estimate": {
          "done": 12,
          "total": 25
        },
        "total": 9
      },
      "releaseProvider": "github",
      "releaseRepo": null,
      "releaseTag": null,
      "state": "open",
      "title": "Version 1.1 – Ticketübersicht",
      "updatedAt": "2026-10-21T10:15:00Z",
      "version": 2
    }
  ]
}
```

### Example request

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

## Create a milestone (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/milestones`

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

Requires `tenant:forge:write`, and project role developer or higher (non-members of a tenant-visible project may), or `tenant:forge:admin`. `title` is required and unique in the project ignoring case (409 `key_taken`). `releaseRepo` must be one of the project's repositories (compared ignoring case, stored as linked) and is set together with `releaseTag`. Archived project 409 `project_archived`. Writes `forge.milestone.saved`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `description` (string): Description (Markdown) (max length 20000)
- `dueOn` (string (date), nullable): Due date; null clears it
- `releaseProvider` (string): Provider of releaseRepo; needed only when the project links the same name at several providers (400 `releaseProvider` otherwise)
- `releaseRepo` (string, nullable): Full name of a repository of the project (owner/name, GitLab: group/subgroup/project)
- `releaseTag` (string, nullable): Git tag of the release (set together with releaseRepo); null clears it (max length 128)
- `title` (string): Title (max length 120)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "description": "Rückfragen des Service Desks direkt in der App beantworten, Anhänge ansehen.",
  "dueOn": "2027-01-27",
  "title": "Version 2.0 – Rückfragen"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `closedAt` (string (date-time), nullable, required): When it was closed; null while open
- `createdAt` (string (date-time), required): When it was created
- `description` (string, required): Markdown
- `dueOn` (string (date), nullable, required): Due date; null when none
- `id` (string (uuid), required): Milestone id
- `position` (integer, required): Order of the milestones
- `releaseProvider` (string, required): Provider of releaseRepo (github without a release)
- `releaseRepo` (string, nullable, required): Full name of a repository of the project
- `releaseTag` (string, nullable, required): Git tag of the release in releaseRepo
- `state` (string, required): open or closed (one of `open`, `closed`)
- `title` (string, required): Title
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (MilestoneProgress, required)
  - `byCategory` (object, required): Items per status category
    - `active` (integer, required): Items in progress
    - `cancelled` (integer, required): Items cancelled
    - `done` (integer, required): Items done
    - `on_hold` (integer, required): Items on hold
    - `todo` (integer, required): Items in todo
    - `triage` (integer, required): Items in triage
  - `estimate` (object, required): Sums of the estimates
    - `done` (number, required): Sum of the estimates of items in a done status
    - `total` (number, required): Sum of the estimates without cancelled items
  - `total` (integer, required): Items in the milestone

Example 201 answer:

```json
{
  "closedAt": null,
  "createdAt": "2026-09-30T13:00:00Z",
  "description": "Kunden sehen ihre Tickets mit Filtern, Seitenwechseln und einem verständlichen leeren Zustand.",
  "dueOn": "2026-11-25",
  "id": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 2,
      "cancelled": 0,
      "done": 5,
      "on_hold": 0,
      "todo": 2,
      "triage": 0
    },
    "estimate": {
      "done": 12,
      "total": 25
    },
    "total": 9
  },
  "releaseProvider": "github",
  "releaseRepo": null,
  "releaseTag": null,
  "state": "open",
  "title": "Version 1.1 – Ticketübersicht",
  "updatedAt": "2026-10-21T10:15:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/milestones' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Rückfragen des Service Desks direkt in der App beantworten, Anhänge ansehen.","dueOn":"2027-01-27","title":"Version 2.0 – Rückfragen"}'
```

## Read a milestone with its progress (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/milestones/{id}`

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

Requires `tenant:forge:read` and a project the caller sees. `progress` counts the milestone's items (`total`, `byCategory` with every status category) and sums their estimates (`estimate.total` without cancelled items, `estimate.done` for items in a done status).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The milestone (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `closedAt` (string (date-time), nullable, required): When it was closed; null while open
- `createdAt` (string (date-time), required): When it was created
- `description` (string, required): Markdown
- `dueOn` (string (date), nullable, required): Due date; null when none
- `id` (string (uuid), required): Milestone id
- `position` (integer, required): Order of the milestones
- `releaseProvider` (string, required): Provider of releaseRepo (github without a release)
- `releaseRepo` (string, nullable, required): Full name of a repository of the project
- `releaseTag` (string, nullable, required): Git tag of the release in releaseRepo
- `state` (string, required): open or closed (one of `open`, `closed`)
- `title` (string, required): Title
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (MilestoneProgress, required)
  - `byCategory` (object, required): Items per status category
    - `active` (integer, required): Items in progress
    - `cancelled` (integer, required): Items cancelled
    - `done` (integer, required): Items done
    - `on_hold` (integer, required): Items on hold
    - `todo` (integer, required): Items in todo
    - `triage` (integer, required): Items in triage
  - `estimate` (object, required): Sums of the estimates
    - `done` (number, required): Sum of the estimates of items in a done status
    - `total` (number, required): Sum of the estimates without cancelled items
  - `total` (integer, required): Items in the milestone

Example 200 answer:

```json
{
  "closedAt": null,
  "createdAt": "2026-09-30T13:00:00Z",
  "description": "Kunden sehen ihre Tickets mit Filtern, Seitenwechseln und einem verständlichen leeren Zustand.",
  "dueOn": "2026-11-25",
  "id": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 2,
      "cancelled": 0,
      "done": 5,
      "on_hold": 0,
      "todo": 2,
      "triage": 0
    },
    "estimate": {
      "done": 12,
      "total": 25
    },
    "total": 9
  },
  "releaseProvider": "github",
  "releaseRepo": null,
  "releaseTag": null,
  "state": "open",
  "title": "Version 1.1 – Ticketübersicht",
  "updatedAt": "2026-10-21T10:15:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/milestones/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete a milestone (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/milestones/{id}`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Open items in the milestone refuse it (409 `in_use`, `counts.items`); closed items are taken off the milestone without an item history entry (configuration-side cleanup, like deleting a label). Writes `forge.milestone.deleted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/milestones/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a milestone (tenant:forge:write and, as a member, at least developer)

`PATCH /api/forge/v1/projects/{key}/milestones/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`); `null` clears `dueOn` and, for both fields together, the release. Nothing changed writes no event. Writes `forge.milestone.saved`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `description` (string): Description (Markdown) (max length 20000)
- `dueOn` (string (date), nullable): Due date; null clears it
- `releaseProvider` (string): Provider of releaseRepo; needed only when the project links the same name at several providers (400 `releaseProvider` otherwise)
- `releaseRepo` (string, nullable): Full name of a repository of the project (owner/name, GitLab: group/subgroup/project)
- `releaseTag` (string, nullable): Git tag of the release (set together with releaseRepo); null clears it (max length 128)
- `title` (string): Title (max length 120)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "dueOn": "2026-12-02",
  "releaseRepo": "mbcomdev/demo-app",
  "releaseTag": "v1.1.0",
  "version": 2
}
```

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

- `closedAt` (string (date-time), nullable, required): When it was closed; null while open
- `createdAt` (string (date-time), required): When it was created
- `description` (string, required): Markdown
- `dueOn` (string (date), nullable, required): Due date; null when none
- `id` (string (uuid), required): Milestone id
- `position` (integer, required): Order of the milestones
- `releaseProvider` (string, required): Provider of releaseRepo (github without a release)
- `releaseRepo` (string, nullable, required): Full name of a repository of the project
- `releaseTag` (string, nullable, required): Git tag of the release in releaseRepo
- `state` (string, required): open or closed (one of `open`, `closed`)
- `title` (string, required): Title
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (MilestoneProgress, required)
  - `byCategory` (object, required): Items per status category
    - `active` (integer, required): Items in progress
    - `cancelled` (integer, required): Items cancelled
    - `done` (integer, required): Items done
    - `on_hold` (integer, required): Items on hold
    - `todo` (integer, required): Items in todo
    - `triage` (integer, required): Items in triage
  - `estimate` (object, required): Sums of the estimates
    - `done` (number, required): Sum of the estimates of items in a done status
    - `total` (number, required): Sum of the estimates without cancelled items
  - `total` (integer, required): Items in the milestone

Example 200 answer:

```json
{
  "closedAt": null,
  "createdAt": "2026-09-30T13:00:00Z",
  "description": "Kunden sehen ihre Tickets mit Filtern, Seitenwechseln und einem verständlichen leeren Zustand.",
  "dueOn": "2026-11-25",
  "id": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 2,
      "cancelled": 0,
      "done": 5,
      "on_hold": 0,
      "todo": 2,
      "triage": 0
    },
    "estimate": {
      "done": 12,
      "total": 25
    },
    "total": 9
  },
  "releaseProvider": "github",
  "releaseRepo": null,
  "releaseTag": null,
  "state": "open",
  "title": "Version 1.1 – Ticketübersicht",
  "updatedAt": "2026-10-21T10:15:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/milestones/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"dueOn":"2026-12-02","releaseRepo":"mbcomdev/demo-app","releaseTag":"v1.1.0","version":2}'
```

## Close a milestone (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/milestones/{id}/close`

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

Same permission as creating. Closing is allowed with open items (they stay in the milestone, no automatic move) and the answer's `progress` counts them; a closed milestone takes no new items. Already closed changes nothing. Writes `forge.milestone.closed`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Closed (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `closedAt` (string (date-time), nullable, required): When it was closed; null while open
- `createdAt` (string (date-time), required): When it was created
- `description` (string, required): Markdown
- `dueOn` (string (date), nullable, required): Due date; null when none
- `id` (string (uuid), required): Milestone id
- `position` (integer, required): Order of the milestones
- `releaseProvider` (string, required): Provider of releaseRepo (github without a release)
- `releaseRepo` (string, nullable, required): Full name of a repository of the project
- `releaseTag` (string, nullable, required): Git tag of the release in releaseRepo
- `state` (string, required): open or closed (one of `open`, `closed`)
- `title` (string, required): Title
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (MilestoneProgress, required)
  - `byCategory` (object, required): Items per status category
    - `active` (integer, required): Items in progress
    - `cancelled` (integer, required): Items cancelled
    - `done` (integer, required): Items done
    - `on_hold` (integer, required): Items on hold
    - `todo` (integer, required): Items in todo
    - `triage` (integer, required): Items in triage
  - `estimate` (object, required): Sums of the estimates
    - `done` (number, required): Sum of the estimates of items in a done status
    - `total` (number, required): Sum of the estimates without cancelled items
  - `total` (integer, required): Items in the milestone

Example 200 answer:

```json
{
  "closedAt": "2026-11-04T10:00:00Z",
  "createdAt": "2026-09-23T10:00:00Z",
  "description": "Erste Version im App Store und bei Google Play mit Anmeldung per Passkey.",
  "dueOn": "2026-11-04",
  "id": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c01",
  "position": 0,
  "progress": {
    "byCategory": {
      "active": 0,
      "cancelled": 1,
      "done": 8,
      "on_hold": 0,
      "todo": 0,
      "triage": 0
    },
    "estimate": {
      "done": 28,
      "total": 28
    },
    "total": 9
  },
  "releaseProvider": "github",
  "releaseRepo": "mbcomdev/demo-app",
  "releaseTag": "v1.0.0",
  "state": "closed",
  "title": "Version 1.0 – Anmeldung",
  "updatedAt": "2026-11-04T10:00:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/milestones/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/close' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Reopen a milestone (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/milestones/{id}/reopen`

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

Same permission as creating. Already open changes nothing. Writes `forge.milestone.reopened`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Reopened (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `closedAt` (string (date-time), nullable, required): When it was closed; null while open
- `createdAt` (string (date-time), required): When it was created
- `description` (string, required): Markdown
- `dueOn` (string (date), nullable, required): Due date; null when none
- `id` (string (uuid), required): Milestone id
- `position` (integer, required): Order of the milestones
- `releaseProvider` (string, required): Provider of releaseRepo (github without a release)
- `releaseRepo` (string, nullable, required): Full name of a repository of the project
- `releaseTag` (string, nullable, required): Git tag of the release in releaseRepo
- `state` (string, required): open or closed (one of `open`, `closed`)
- `title` (string, required): Title
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (MilestoneProgress, required)
  - `byCategory` (object, required): Items per status category
    - `active` (integer, required): Items in progress
    - `cancelled` (integer, required): Items cancelled
    - `done` (integer, required): Items done
    - `on_hold` (integer, required): Items on hold
    - `todo` (integer, required): Items in todo
    - `triage` (integer, required): Items in triage
  - `estimate` (object, required): Sums of the estimates
    - `done` (number, required): Sum of the estimates of items in a done status
    - `total` (number, required): Sum of the estimates without cancelled items
  - `total` (integer, required): Items in the milestone

Example 200 answer:

```json
{
  "closedAt": null,
  "createdAt": "2026-09-30T13:00:00Z",
  "description": "Kunden sehen ihre Tickets mit Filtern, Seitenwechseln und einem verständlichen leeren Zustand.",
  "dueOn": "2026-11-25",
  "id": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 2,
      "cancelled": 0,
      "done": 5,
      "on_hold": 0,
      "todo": 2,
      "triage": 0
    },
    "estimate": {
      "done": 12,
      "total": 25
    },
    "total": 9
  },
  "releaseProvider": "github",
  "releaseRepo": null,
  "releaseTag": null,
  "state": "open",
  "title": "Version 1.1 – Ticketübersicht",
  "updatedAt": "2026-10-21T10:15:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/milestones/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reopen' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Iterations

## List the iterations of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/iterations`

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

Requires `tenant:forge:read` and a project the caller sees. Each iteration carries its `progress`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `state` | query | string |  | (one of `planned`, `active`, `closed`) |
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The iterations (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of IterationView, required)

Example 200 answer:

```json
{
  "items": [
    {
      "closedAt": "2026-11-04T08:30:00Z",
      "createdAt": "2026-10-07T10:00:00Z",
      "endsOn": "2026-11-03",
      "goal": "Anmeldung mit Passkey auf iOS und Android, Fehlermeldungen verständlich.",
      "id": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d01",
      "name": "Iteration 1 – Anmeldung",
      "position": 0,
      "progress": {
        "byCategory": {
          "active": 0,
          "cancelled": 1,
          "done": 5,
          "on_hold": 0,
          "todo": 1,
          "triage": 0
        },
        "committed": 21,
        "estimate": {
          "done": 18,
          "total": 22
        },
        "total": 7
      },
      "startedAt": "2026-10-14T09:30:00Z",
      "startsOn": "2026-10-14",
      "state": "closed",
      "updatedAt": "2026-11-04T08:30:00Z",
      "version": 4
    },
    {
      "closedAt": null,
      "createdAt": "2026-10-28T11:00:00Z",
      "endsOn": "2026-11-24",
      "goal": "Kunden sehen ihre Tickets mit Filtern und laden lange Listen nach.",
      "id": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
      "name": "Iteration 2 – Ticketübersicht",
      "position": 1,
      "progress": {
        "byCategory": {
          "active": 2,
          "cancelled": 0,
          "done": 4,
          "on_hold": 0,
          "todo": 1,
          "triage": 0
        },
        "committed": 16,
        "estimate": {
          "done": 9,
          "total": 19
        },
        "total": 7
      },
      "startedAt": "2026-11-04T09:30:00Z",
      "startsOn": "2026-11-04",
      "state": "active",
      "updatedAt": "2026-11-04T09:30:00Z",
      "version": 3
    }
  ]
}
```

### Example request

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

## Create an iteration (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/iterations`

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

Requires `tenant:forge:write`, and project role developer or higher (non-members of a tenant-visible project may), or `tenant:forge:admin`. `name`, `startsOn` and `endsOn` are required (`endsOn` not before `startsOn`). The iteration starts planned. Archived project 409 `project_archived`. Writes `forge.iteration.saved`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `endsOn` (string (date)): Last day (not before startsOn)
- `goal` (string): Goal of the iteration (max length 2000)
- `name` (string): Name (max length 80)
- `startsOn` (string (date)): First day
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "endsOn": "2027-01-12",
  "goal": "Anhänge im Ticketverlauf ansehen und herunterladen.",
  "name": "Iteration 4 – Anhänge",
  "startsOn": "2026-12-16"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `closedAt` (string (date-time), nullable, required): When it was closed; null until then
- `createdAt` (string (date-time), required): When it was created
- `endsOn` (string (date), required): Last day
- `goal` (string, required): Goal of the iteration
- `id` (string (uuid), required): Iteration id
- `name` (string, required): Name
- `position` (integer, required): Order of the iterations
- `startedAt` (string (date-time), nullable, required): When it was started; null while planned
- `startsOn` (string (date), required): First day
- `state` (string, required): planned, active (at most one per project) or closed (one of `planned`, `active`, `closed`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (IterationProgress, required): Planned and active iterations count the items in them now; a closed iteration counts its snapshot (every item as it stood at the close, carried-over ones included).

Example 201 answer:

```json
{
  "closedAt": null,
  "createdAt": "2026-10-28T11:00:00Z",
  "endsOn": "2026-11-24",
  "goal": "Kunden sehen ihre Tickets mit Filtern und laden lange Listen nach.",
  "id": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
  "name": "Iteration 2 – Ticketübersicht",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 2,
      "cancelled": 0,
      "done": 4,
      "on_hold": 0,
      "todo": 1,
      "triage": 0
    },
    "committed": 16,
    "estimate": {
      "done": 9,
      "total": 19
    },
    "total": 7
  },
  "startedAt": "2026-11-04T09:30:00Z",
  "startsOn": "2026-11-04",
  "state": "active",
  "updatedAt": "2026-11-04T09:30:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/iterations' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"endsOn":"2027-01-12","goal":"Anhänge im Ticketverlauf ansehen und herunterladen.","name":"Iteration 4 – Anhänge","startsOn":"2026-12-16"}'
```

## Read an iteration with its progress (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/iterations/{id}`

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

Requires `tenant:forge:read` and a project the caller sees. `progress` counts the iteration's items (`total`, `byCategory` with every status category) and sums their estimates (`estimate.total` without cancelled items, `estimate.done` for items in a done status); `committed` is the estimate of the non-cancelled items when the iteration was started (null while planned). A closed iteration's progress comes from its snapshot – every item as it stood at the close, also those carried over – so it shows what the iteration delivered.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The iteration (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `closedAt` (string (date-time), nullable, required): When it was closed; null until then
- `createdAt` (string (date-time), required): When it was created
- `endsOn` (string (date), required): Last day
- `goal` (string, required): Goal of the iteration
- `id` (string (uuid), required): Iteration id
- `name` (string, required): Name
- `position` (integer, required): Order of the iterations
- `startedAt` (string (date-time), nullable, required): When it was started; null while planned
- `startsOn` (string (date), required): First day
- `state` (string, required): planned, active (at most one per project) or closed (one of `planned`, `active`, `closed`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (IterationProgress, required): Planned and active iterations count the items in them now; a closed iteration counts its snapshot (every item as it stood at the close, carried-over ones included).

Example 200 answer:

```json
{
  "closedAt": null,
  "createdAt": "2026-10-28T11:00:00Z",
  "endsOn": "2026-11-24",
  "goal": "Kunden sehen ihre Tickets mit Filtern und laden lange Listen nach.",
  "id": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
  "name": "Iteration 2 – Ticketübersicht",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 2,
      "cancelled": 0,
      "done": 4,
      "on_hold": 0,
      "todo": 1,
      "triage": 0
    },
    "committed": 16,
    "estimate": {
      "done": 9,
      "total": 19
    },
    "total": 7
  },
  "startedAt": "2026-11-04T09:30:00Z",
  "startsOn": "2026-11-04",
  "state": "active",
  "updatedAt": "2026-11-04T09:30:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/iterations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete an iteration (tenant:forge:write and, as a member, at least developer)

`DELETE /api/forge/v1/projects/{key}/iterations/{id}`

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

Same permission as creating. Only a planned iteration without items can be deleted (409 `iteration_not_planned`; 409 `in_use` with `counts.items` while items are in it). Writes `forge.iteration.deleted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/iterations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change an iteration (tenant:forge:write and, as a member, at least developer)

`PATCH /api/forge/v1/projects/{key}/iterations/{id}`

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

Same permission as creating. `version` is required (409 `version_conflict`). A closed iteration cannot be changed (409 `iteration_closed`). Nothing changed writes no event. Writes `forge.iteration.saved`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `endsOn` (string (date)): Last day (not before startsOn)
- `goal` (string): Goal of the iteration (max length 2000)
- `name` (string): Name (max length 80)
- `startsOn` (string (date)): First day
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "goal": "Rückfragen beantworten, Anhänge ansehen und herunterladen.",
  "version": 1
}
```

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

- `closedAt` (string (date-time), nullable, required): When it was closed; null until then
- `createdAt` (string (date-time), required): When it was created
- `endsOn` (string (date), required): Last day
- `goal` (string, required): Goal of the iteration
- `id` (string (uuid), required): Iteration id
- `name` (string, required): Name
- `position` (integer, required): Order of the iterations
- `startedAt` (string (date-time), nullable, required): When it was started; null while planned
- `startsOn` (string (date), required): First day
- `state` (string, required): planned, active (at most one per project) or closed (one of `planned`, `active`, `closed`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (IterationProgress, required): Planned and active iterations count the items in them now; a closed iteration counts its snapshot (every item as it stood at the close, carried-over ones included).

Example 200 answer:

```json
{
  "closedAt": null,
  "createdAt": "2026-10-28T11:00:00Z",
  "endsOn": "2026-11-24",
  "goal": "Kunden sehen ihre Tickets mit Filtern und laden lange Listen nach.",
  "id": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
  "name": "Iteration 2 – Ticketübersicht",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 2,
      "cancelled": 0,
      "done": 4,
      "on_hold": 0,
      "todo": 1,
      "triage": 0
    },
    "committed": 16,
    "estimate": {
      "done": 9,
      "total": 19
    },
    "total": 7
  },
  "startedAt": "2026-11-04T09:30:00Z",
  "startsOn": "2026-11-04",
  "state": "active",
  "updatedAt": "2026-11-04T09:30:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/iterations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"goal":"Rückfragen beantworten, Anhänge ansehen und herunterladen.","version":1}'
```

## Start an iteration (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/iterations/{id}/start`

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

Same permission as creating. Only a planned iteration starts (409 `iteration_not_planned`) and only while no other iteration of the project is active (409 `iteration_active`). The summed estimates of its non-cancelled items are stored as `progress.committed`. Writes `forge.iteration.started`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Started (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `closedAt` (string (date-time), nullable, required): When it was closed; null until then
- `createdAt` (string (date-time), required): When it was created
- `endsOn` (string (date), required): Last day
- `goal` (string, required): Goal of the iteration
- `id` (string (uuid), required): Iteration id
- `name` (string, required): Name
- `position` (integer, required): Order of the iterations
- `startedAt` (string (date-time), nullable, required): When it was started; null while planned
- `startsOn` (string (date), required): First day
- `state` (string, required): planned, active (at most one per project) or closed (one of `planned`, `active`, `closed`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (IterationProgress, required): Planned and active iterations count the items in them now; a closed iteration counts its snapshot (every item as it stood at the close, carried-over ones included).

Example 200 answer:

```json
{
  "closedAt": null,
  "createdAt": "2026-10-28T11:00:00Z",
  "endsOn": "2026-11-24",
  "goal": "Kunden sehen ihre Tickets mit Filtern und laden lange Listen nach.",
  "id": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
  "name": "Iteration 2 – Ticketübersicht",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 2,
      "cancelled": 0,
      "done": 4,
      "on_hold": 0,
      "todo": 1,
      "triage": 0
    },
    "committed": 16,
    "estimate": {
      "done": 9,
      "total": 19
    },
    "total": 7
  },
  "startedAt": "2026-11-04T09:30:00Z",
  "startsOn": "2026-11-04",
  "state": "active",
  "updatedAt": "2026-11-04T09:30:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/iterations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/start' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Close an iteration (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/iterations/{id}/close`

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

Same permission as creating. Only the active iteration closes (409 `iteration_not_active`). The state of every item in it is snapshotted first; then the open items (status category not done or cancelled) move to the planned iteration `nextIterationId` (`carryOver` `next`; 400 `nextIterationId` when it is missing or not a planned iteration of the project) or to the backlog (`carryOver` `backlog`). Each move is an item change recorded as `updated` with the change `iteration`; everything happens in one transaction. Done and cancelled items stay in the closed iteration. Writes `forge.iteration.closed` and `forge.item.updated` per moved item.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `carryOver` (string, required): Where the open items go (one of `next`, `backlog`)
- `nextIterationId` (string (uuid)): Required with `next`: a planned iteration of the project; not allowed with `backlog`

Example:

```json
{
  "carryOver": "next",
  "nextIterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d03"
}
```

### Responses

- **200** Closed (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `closedAt` (string (date-time), nullable, required): When it was closed; null until then
- `createdAt` (string (date-time), required): When it was created
- `endsOn` (string (date), required): Last day
- `goal` (string, required): Goal of the iteration
- `id` (string (uuid), required): Iteration id
- `name` (string, required): Name
- `position` (integer, required): Order of the iterations
- `startedAt` (string (date-time), nullable, required): When it was started; null while planned
- `startsOn` (string (date), required): First day
- `state` (string, required): planned, active (at most one per project) or closed (one of `planned`, `active`, `closed`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `progress` (IterationProgress, required): Planned and active iterations count the items in them now; a closed iteration counts its snapshot (every item as it stood at the close, carried-over ones included).

Example 200 answer:

```json
{
  "closedAt": "2026-11-25T08:30:00Z",
  "createdAt": "2026-10-28T11:00:00Z",
  "endsOn": "2026-11-24",
  "goal": "Kunden sehen ihre Tickets mit Filtern und laden lange Listen nach.",
  "id": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
  "name": "Iteration 2 – Ticketübersicht",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 1,
      "cancelled": 0,
      "done": 5,
      "on_hold": 0,
      "todo": 1,
      "triage": 0
    },
    "committed": 16,
    "estimate": {
      "done": 12,
      "total": 19
    },
    "total": 7
  },
  "startedAt": "2026-11-04T09:30:00Z",
  "startsOn": "2026-11-04",
  "state": "closed",
  "updatedAt": "2026-11-25T08:30:00Z",
  "version": 4
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/iterations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/close' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"carryOver":"next","nextIterationId":"f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d03"}'
```

## 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"
```

# Metrics

## Read the flow metrics of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/metrics`

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

Requires `tenant:forge:read` and a project the caller sees. `from` and `to` are dates (UTC, both inclusive); without them the range is the last 12 weeks, a range over 52 weeks is 400 `invalid` on `to`, `from` after `to` 400 on `from`. Weeks start on Monday (UTC). Only items done now count; they count in the week they last entered a done status. Cycle time runs from first entering an `active` status to that moment (items that never were active are left out), lead time from creation. Categories of past statuses are the statuses' current categories. `openByCategory` counts the items now in triage, todo, active and on_hold; `velocity` lists the iterations closed in the range from their snapshots.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string (date) |  | First day, YYYY-MM-DD |
| `to` | query | string (date) |  | Last day, YYYY-MM-DD |
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The metrics (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `cycleTime` (DurationStats, required)
  - `count` (integer, required): Number of items measured
  - `medianHours` (number, nullable, required): Nearest-rank median; null without values
  - `p85Hours` (number, nullable, required): Nearest-rank 85th percentile; null without values
- `from` (string (date), required): First day of the range (inclusive, UTC)
- `leadTime` (DurationStats, required)
  - `count` (integer, required): Number of items measured
  - `medianHours` (number, nullable, required): Nearest-rank median; null without values
  - `p85Hours` (number, nullable, required): Nearest-rank 85th percentile; null without values
- `openByCategory` (object, required): Open items per status category now
  - `active` (integer, required): Items in progress
  - `on_hold` (integer, required): Items on hold
  - `todo` (integer, required): Items in todo
  - `triage` (integer, required): Items in triage
- `throughput` (array of object, required): Items finished per week (UTC, Monday first); every week of the range is present
  - `count` (integer, required): Items finished in the week
  - `weekStart` (string (date), required): Monday of the week
- `to` (string (date), required): Last day of the range (inclusive, UTC)
- `velocity` (array of object, required): Closed iterations with their figures
  - `closedAt` (string (date-time), nullable, required): When it was closed
  - `committed` (number, nullable, required): Estimate committed at the start
  - `doneEstimate` (number, required): Estimate of the items done at the close
  - `doneItems` (integer, required): Items done at the close
  - `endsOn` (string (date), required): Last day of the iteration
  - `iterationId` (string (uuid), required): Iteration id
  - `name` (string, required): Iteration name
  - `startsOn` (string (date), required): First day of the iteration
  - `totalItems` (integer, required): Items in the iteration at the close

Example 200 answer:

```json
{
  "cycleTime": {
    "count": 14,
    "medianHours": 54.5,
    "p85Hours": 166
  },
  "from": "2026-08-31",
  "leadTime": {
    "count": 15,
    "medianHours": 141.2,
    "p85Hours": 402.5
  },
  "openByCategory": {
    "active": 3,
    "on_hold": 0,
    "todo": 4,
    "triage": 1
  },
  "throughput": [
    {
      "count": 0,
      "weekStart": "2026-08-31"
    },
    {
      "count": 0,
      "weekStart": "2026-09-07"
    },
    {
      "count": 0,
      "weekStart": "2026-09-14"
    },
    {
      "count": 0,
      "weekStart": "2026-09-21"
    },
    {
      "count": 1,
      "weekStart": "2026-09-28"
    },
    {
      "count": 1,
      "weekStart": "2026-10-05"
    },
    {
      "count": 2,
      "weekStart": "2026-10-12"
    },
    {
      "count": 3,
      "weekStart": "2026-10-19"
    },
    {
      "count": 2,
      "weekStart": "2026-10-26"
    },
    {
      "count": 3,
      "weekStart": "2026-11-02"
    },
    {
      "count": 3,
      "weekStart": "2026-11-09"
    },
    {
      "count": 0,
      "weekStart": "2026-11-16"
    }
  ],
  "to": "2026-11-18",
  "velocity": [
    {
      "closedAt": "2026-11-04T08:30:00Z",
      "committed": 21,
      "doneEstimate": 18,
      "doneItems": 6,
      "endsOn": "2026-11-03",
      "iterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d01",
      "name": "Iteration 1 – Anmeldung",
      "startsOn": "2026-10-14",
      "totalItems": 7
    }
  ]
}
```

### Example request

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

## Read the roadmap of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/roadmap`

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

Requires `tenant:forge:read` and a project the caller sees. The milestones with their progress and the items of a type with level 1 or higher that have a start date, a due date or a milestone, ordered by start (else due date), then rank; at most 500 (`truncated` tells there are more).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Responses

- **200** The roadmap (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of RoadmapItem, required): Planned items: types of level 1 or higher with dates or a milestone (at most 500)
  - `dueOn` (string (date), nullable, required): Due date
  - `id` (string (uuid), required): Item id
  - `milestoneId` (string (uuid), nullable, required): Milestone of the item
  - `parentNumber` (integer, nullable, required): Number of the parent item
  - `ref` (string, required): Item reference
  - `startOn` (string (date), nullable, required): Planned start date
  - `statusCategory` (string, required): Status category (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
  - `statusKey` (string, required): Status key
  - `title` (string, required): Title
  - `typeKey` (string, required): Item type key
  - `typeLevel` (integer, required): Level of the item type
- `milestones` (array of MilestoneView, required): Milestones of the project with their progress
- `truncated` (boolean, required): There were more than 500 items

Example 200 answer:

```json
{
  "items": [
    {
      "dueOn": "2026-12-30",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
      "milestoneId": null,
      "parentNumber": null,
      "ref": "APP-1",
      "startOn": "2026-09-23",
      "statusCategory": "active",
      "statusKey": "in_arbeit",
      "title": "Self-Service-Bereich für Kunden",
      "typeKey": "epic",
      "typeLevel": 3
    },
    {
      "dueOn": "2026-11-24",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c05",
      "milestoneId": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
      "parentNumber": 1,
      "ref": "APP-5",
      "startOn": "2026-10-14",
      "statusCategory": "active",
      "statusKey": "in_arbeit",
      "title": "Ticketübersicht mit Filtern",
      "typeKey": "story",
      "typeLevel": 2
    }
  ],
  "milestones": [
    {
      "closedAt": null,
      "createdAt": "2026-09-30T13:00:00Z",
      "description": "Kunden sehen ihre Tickets mit Filtern, Seitenwechseln und einem verständlichen leeren Zustand.",
      "dueOn": "2026-11-25",
      "id": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
      "position": 1,
      "progress": {
        "byCategory": {
          "active": 2,
          "cancelled": 0,
          "done": 5,
          "on_hold": 0,
          "todo": 2,
          "triage": 0
        },
        "estimate": {
          "done": 12,
          "total": 25
        },
        "total": 9
      },
      "releaseProvider": "github",
      "releaseRepo": null,
      "releaseTag": null,
      "state": "open",
      "title": "Version 1.1 – Ticketübersicht",
      "updatedAt": "2026-10-21T10:15:00Z",
      "version": 2
    }
  ],
  "truncated": false
}
```

### Example request

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

# Templates

## List the built-in and saved project templates (tenant:forge:read)

`GET /api/forge/v1/project-templates`

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

Requires `tenant:forge:read`. Built-ins (kanban, scrum, bugs) have no id and are chosen by key.

### Responses

- **200** Templates (`application/json`)

Fields of the 200 answer:

- `items` (array of TemplateInfo, required)
  - `builtIn` (boolean, required): A built-in template (chosen by key; no id)
  - `description` (string, required): Description
  - `key` (string, required): Template key (built-in) or the saved key
  - `name` (string, required): Display name
  - `summary` (object, required): Number of rows per configuration collection
  - `createdAt` (string (date-time)): Saved templates: when it was saved
  - `createdBy` (string): Saved templates: e-mail of who saved it
  - `id` (string (uuid)): Saved templates only

Example 200 answer:

```json
{
  "items": [
    {
      "builtIn": true,
      "description": "Freier Ablauf von Triage bis Erledigt mit Epics, Storys, Aufgaben und Fehlern",
      "key": "kanban",
      "name": "Kanban",
      "summary": {
        "automations": 2,
        "customFields": 0,
        "itemTemplates": 1,
        "itemTypes": 4,
        "labels": 5,
        "sectionDefs": 3,
        "statuses": 6,
        "workflows": 1
      }
    },
    {
      "builtIn": true,
      "description": "Wie Kanban, dazu Sub-Tasks, Story Points und das Label „sprint-ziel“",
      "key": "scrum",
      "name": "Scrum",
      "summary": {
        "automations": 2,
        "customFields": 1,
        "itemTemplates": 1,
        "itemTypes": 5,
        "labels": 6,
        "sectionDefs": 3,
        "statuses": 6,
        "workflows": 1
      }
    },
    {
      "builtIn": true,
      "description": "Fehler und Verbesserungen mit festem Ablauf von Neu über Bestätigt bis Behoben",
      "key": "bugs",
      "name": "Fehlerverfolgung",
      "summary": {
        "automations": 2,
        "customFields": 1,
        "itemTemplates": 1,
        "itemTypes": 2,
        "labels": 4,
        "sectionDefs": 3,
        "statuses": 5,
        "workflows": 1
      }
    },
    {
      "builtIn": false,
      "createdAt": "2026-11-12T15:30:00Z",
      "createdBy": "emma.maier@muster-it.example",
      "description": "Scrum mit den Bereichs- und Plattform-Labels der Kundenportal-App.",
      "id": "2e4f6a8b-0c1d-4e3f-9a5b-7c9d1e3f5a01",
      "key": "muster-app",
      "name": "Muster-App-Projekt",
      "summary": {
        "automations": 3,
        "customFields": 1,
        "itemTemplates": 1,
        "itemTypes": 5,
        "labels": 12,
        "sectionDefs": 3,
        "statuses": 6,
        "workflows": 1
      }
    }
  ]
}
```

### Example request

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

## Delete a saved project template (tenant:forge:admin)

`DELETE /api/forge/v1/project-templates/{id}`

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

Requires `tenant:forge:admin`. Built-ins cannot be deleted (404).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/project-templates/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Add a template's missing configuration to a project (tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/apply-template`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Adds what the project lacks (matched by key, labels by name); never changes or deletes existing rows. `dryRun=true` answers the plan without writing. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `dryRun` | query | boolean |  | (default `false`) |
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `templateKey` (string, required): Built-in key or saved template id or key

Example:

```json
{
  "templateKey": "scrum"
}
```

### Responses

- **200** What was (or would be) added and skipped (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `customFields` (array of CustomField, required): Custom fields in position order
  - `id` (string (uuid), required): Field id
  - `key` (string, required): Field key: the key in `customFields` of an item; never changes
  - `kind` (string, required): Value type; never changes (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `user`, `url`)
  - `label` (string, required): Display label
  - `options` (array of FieldOption, required): Choices of select and multiselect fields
  - `position` (integer, required): Order in the configuration
  - `required` (boolean, required): Items of the types the field applies to need a value
  - `typeKeys` (array of string, required): Item type keys; empty = every type
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `itemTemplates` (array of ItemTemplate, required): Item templates in position order
  - `body` (string, required): Markdown
  - `id` (string (uuid), required): Template id
  - `key` (string, required): Template key (`templateKey` of a new item)
  - `labelIds` (array of string (uuid), required): Labels it sets
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `title` (string, required): Title it prefills
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
  - `typeId` (string (uuid), nullable): Item type it sets; null = none
- `itemTypes` (array of ItemType, required): Item types in position order
  - `archived` (boolean, required): Archived: no new items of the type
  - `icon` (string, required): Icon name shown in the portal
  - `id` (string (uuid), required): Item type id
  - `key` (string, required): Type key; never changes
  - `level` (integer, required): 0 = leaf; a parent type has a higher level (max 5)
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
  - `workflowId` (string (uuid), required): Workflow the items of the type follow
- `labels` (array of Label, required): Labels sorted by name
  - `color` (string, required): Color token (neutral, primary, …) or #rrggbb
  - `description` (string, required): Description
  - `id` (string (uuid), required): Label id
  - `name` (string, required): scope::value makes it exclusive within the scope
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `ownerships` (array of Ownership, required): Ownerships (code ownership) in position order
  - `deputyRefs` (array of string, required): E-mails of the deputies (members, at least developer); need an owner of their own
  - `description` (string, required): Description (max length 2000)
  - `id` (string (uuid), required): Ownership id
  - `itemTypes` (array of string, required): Item type keys: items of these types belong here (without an owner:: label)
  - `key` (string, required): Key; never changes (its label is `owner::<key>`)
  - `labelId` (string (uuid), required): The ownership's label `owner::<key>`; items carry it and it wins over the matchers
  - `matchLabelIds` (array of string (uuid), required): Plain labels (never `owner::…`): items carrying one belong here (without an owner:: label); the later position wins
  - `name` (string, required): Display name (max length 80)
  - `ownerRef` (string, nullable, required): E-mail of the owner person (a member, at least developer); exclusive with ownerTeamId
  - `ownerTeamId` (string (uuid), nullable, required): The owning team; exclusive with ownerRef. Neither is allowed only with a parent (inherited)
  - `parentId` (string (uuid), nullable, required): The parent ownership (same project, no cycle, at most 4 levels); without an owner of its own the nearest ancestor's applies
  - `paths` (array of string, required): Repository path patterns, the CODEOWNERS subset: segments separated by `/`, `*` and `?` within a segment, `**` as a whole segment for any number of directories. A pattern without `/` (other than a trailing one) matches at any depth, one with `/` is relative to the root (a leading `/` anchors explicitly); a trailing `/` matches directories. A pattern whose last segment has no wildcard also matches everything below the directory it names (`hr`, `/apps/github`); one ending in a wildcard matches only what it names (`docs/*`). No character classes, `\`, `!`, `#` or spaces. Paths decide only for code (CODEOWNERS, scm).
  - `position` (integer, required): Precedence: a later ownership wins a path or an item both match
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `sectionDefs` (array of SectionDef, required): Section definitions in position order
  - `id` (string (uuid), required): Section definition id
  - `key` (string, required): Section key; never changes
  - `kind` (string, required): markdown or checklist (one of `markdown`, `checklist`)
  - `label` (string, required): Display label
  - `placement` (string, required): Where the portal shows it: a tab or the side column (one of `tab`, `aside`)
  - `position` (integer, required): Order in the configuration
  - `typeKeys` (array of string, required): Item type keys the section applies to; empty = every type
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `statuses` (array of Status, required): Statuses in position order
  - `category` (string, required): Status category (the group the status belongs to) (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
  - `color` (string, required): Color token (neutral, primary, …) or #rrggbb
  - `id` (string (uuid), required): Status id
  - `isDefault` (boolean, required): Where new items start; exactly one, in triage or todo
  - `key` (string, required): Status key; never changes
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `teams` (array of Team, required): Teams in position order
  - `description` (string, required): Description (max length 2000)
  - `id` (string (uuid), required): Team id
  - `key` (string, required): Team key; never changes
  - `memberRefs` (array of string, required): E-mails, the first is the lead
  - `name` (string, required): Display name (max length 80)
  - `position` (integer, required): Order in the configuration
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `workflows` (array of Workflow, required): Workflows in position order
  - `id` (string (uuid), required): Workflow id
  - `key` (string, required): Workflow key; never changes
  - `name` (string, required): Display name
  - `position` (integer, required): Order in the configuration
  - `statusIds` (array of string (uuid), required): Statuses of the workflow
  - `transitions` (array of Transition, required): Empty = free movement among the statuses
  - `version` (integer, required): Optimistic-locking version; send it with PATCH
- `added` (object, required): Keys added, per collection
- `skipped` (object, required): Keys skipped because the project has them already, per collection
- `defaultTypeId` (string (uuid)): The default item type the template set (only when the project had none)

Example 200 answer:

```json
{
  "added": {
    "customFields": [
      "story_points"
    ],
    "itemTypes": [
      "subtask"
    ],
    "labels": [
      "sprint-ziel"
    ]
  },
  "customFields": [
    {
      "id": "9b5c6d7e-8f9a-4b0c-9dbe-5f6a7b8c9d11",
      "key": "story_points",
      "kind": "number",
      "label": "Story Points",
      "options": [],
      "position": 0,
      "required": false,
      "typeKeys": [
        "story",
        "aufgabe",
        "fehler"
      ],
      "version": 1
    }
  ],
  "itemTemplates": [],
  "itemTypes": [
    {
      "archived": false,
      "icon": "i-lucide-list-checks",
      "id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7c15",
      "key": "subtask",
      "level": 0,
      "name": "Sub-Task",
      "position": 4,
      "version": 1,
      "workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a11"
    }
  ],
  "labels": [
    {
      "color": "primary",
      "description": "Trägt zum Sprint-Ziel bei",
      "id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8d17",
      "name": "sprint-ziel",
      "version": 1
    }
  ],
  "ownerships": [],
  "sectionDefs": [],
  "skipped": {
    "automations": [
      "unteraufgaben-erledigt",
      "pr-gemergt-erledigt"
    ],
    "itemTemplates": [
      "fehlerbericht"
    ],
    "itemTypes": [
      "epic",
      "story",
      "aufgabe",
      "fehler"
    ],
    "labels": [
      "priority::hoch",
      "priority::mittel",
      "priority::niedrig",
      "bug",
      "docs"
    ],
    "sectionDefs": [
      "plan",
      "agent_notes",
      "acceptance"
    ],
    "statuses": [
      "triage",
      "offen",
      "in_arbeit",
      "review",
      "erledigt",
      "verworfen"
    ],
    "workflows": [
      "standard"
    ]
  },
  "statuses": [],
  "teams": [],
  "workflows": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/apply-template' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"templateKey":"scrum"}'
```

## Save a project's configuration as a tenant template (tenant:forge:admin)

`POST /api/forge/v1/projects/{key}/save-as-template`

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

Requires `tenant:forge:admin`. 409 `key_taken` for a used or built-in key.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `key` (string, required)
- `name` (string, required): (max length 120)
- `description` (string): (max length 2000)

Example:

```json
{
  "description": "Scrum mit den Bereichs- und Plattform-Labels der Kundenportal-App.",
  "key": "muster-app",
  "name": "Muster-App-Projekt"
}
```

### Responses

- **201** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `builtIn` (boolean, required): A built-in template (chosen by key; no id)
- `description` (string, required): Description
- `key` (string, required): Template key (built-in) or the saved key
- `name` (string, required): Display name
- `summary` (object, required): Number of rows per configuration collection
- `createdAt` (string (date-time)): Saved templates: when it was saved
- `createdBy` (string): Saved templates: e-mail of who saved it
- `id` (string (uuid)): Saved templates only

Example 201 answer:

```json
{
  "builtIn": false,
  "createdAt": "2026-11-12T15:30:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "description": "Scrum mit den Bereichs- und Plattform-Labels der Kundenportal-App.",
  "id": "2e4f6a8b-0c1d-4e3f-9a5b-7c9d1e3f5a01",
  "key": "muster-app",
  "name": "Muster-App-Projekt",
  "summary": {
    "automations": 3,
    "customFields": 1,
    "itemTemplates": 1,
    "itemTypes": 5,
    "labels": 12,
    "sectionDefs": 3,
    "statuses": 6,
    "workflows": 1
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/save-as-template' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Scrum mit den Bereichs- und Plattform-Labels der Kundenportal-App.","key":"muster-app","name":"Muster-App-Projekt"}'
```

# Views

## List saved views (tenant:forge:read)

`GET /api/forge/v1/views`

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

Requires `tenant:forge:read`. With `project` (a key the caller sees, else 404) the views of that project, i.e. its project views and the caller's personal views in it; without, the caller's personal tenant-wide items views. Other people's personal views are never listed.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `project` | query | string |  | Project key |

### Responses

- **200** The views in their order (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of View, required)
  - `columns` (array of string, required): Columns of the list
  - `createdAt` (string (date-time), required): When the view was created
  - `groupBy` (string, nullable, required): status, assignee, milestone, iteration or label-scope:<scope>
  - `id` (string (uuid), required): View id
  - `kind` (string, required): list or board (one of `list`, `board`)
  - `name` (string, required): Name (max length 80)
  - `ownerRef` (string, required): E-mail address of the creator
  - `position` (integer, required): Order of the views
  - `projectId` (string (uuid), nullable, required): null: a tenant-wide items view (always personal)
  - `projectKey` (string, nullable, required): Key of the project; null for a tenant-wide view
  - `query` (object, required): Item search filters, as the query parameters of `GET /items` (strings)
    - `assignee` (string): Assignee e-mails, comma separated
    - `category` (string): Status categories, comma separated
    - `iteration` (string): Iteration ids, comma separated
    - `label` (string): Label names, comma separated
    - `milestone` (string): Milestone ids, comma separated
    - `open` (string): Only open (true) or only closed (false) items (one of `true`, `false`)
    - `q` (string): Full-text search or an item reference
    - `status` (string): Status keys, comma separated
    - `type` (string): Item type keys, comma separated
  - `scope` (string, required): `personal`: the owner's own; `project`: part of the project's configuration (one of `personal`, `project`)
  - `sort` (string, required): Empty: the default of the list the view runs in (one of ``, `updated`, `created`, `rank`, `number`)
  - `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "items": [
    {
      "columns": [],
      "createdAt": "2026-10-28T11:25:00Z",
      "groupBy": "status",
      "id": "2d3e4f5a-6b7c-4d8e-9fa0-1b2c3d4e5f02",
      "kind": "list",
      "name": "Nach Status",
      "ownerRef": "emma.maier@muster-it.example",
      "position": 0,
      "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "projectKey": "APP",
      "query": {
        "open": "true"
      },
      "scope": "project",
      "sort": "",
      "version": 1
    },
    {
      "columns": [],
      "createdAt": "2026-10-28T11:30:00Z",
      "groupBy": "status",
      "id": "2d3e4f5a-6b7c-4d8e-9fa0-1b2c3d4e5f01",
      "kind": "board",
      "name": "Aktuelle Iteration",
      "ownerRef": "emma.maier@muster-it.example",
      "position": 1,
      "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "projectKey": "APP",
      "query": {
        "iteration": "active"
      },
      "scope": "project",
      "sort": "rank",
      "version": 1
    }
  ]
}
```

### Example request

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

## Save a view (tenant:forge:read for a personal view; a project view tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/views`

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

Requires `tenant:forge:read` for a personal view (the default; needs the caller's e-mail address; optionally of a project the caller sees via `projectKey`). A project view (`scope` `project` with `projectKey`; without a project 400 `scope`) needs the right to configure the project (`tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or higher; else 403) and an active project (409 `project_archived`) and writes `forge.config.updated`. `query` may only hold the item search filters (`q`, `status`, `category`, `type`, `label`, `assignee`, `milestone`, `iteration`, `open`) with the values the search accepts; anything else is 400 naming `query.<key>`.

### Request body

`application/json` (required)

- `columns` (array of string): Columns of the list
- `groupBy` (string, nullable): status, assignee, milestone, iteration or label-scope:<scope>; null clears it
- `kind` (string): list or board (one of `list`, `board`)
- `name` (string): Name (max length 80)
- `position` (integer): Order of the views
- `projectKey` (string): Create only: the project (required with scope project)
- `query` (object): Item search filters (see View.query); `open` may be a boolean
- `scope` (string): Create only: personal (default) or project (one of `personal`, `project`)
- `sort` (string): Sort order; empty = the default of the list (one of ``, `updated`, `created`, `rank`, `number`)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "columns": [
    "ref",
    "title",
    "status",
    "assignees",
    "updatedAt"
  ],
  "kind": "list",
  "name": "Offene Android-Fehler",
  "projectKey": "APP",
  "query": {
    "label": "plattform::android",
    "open": true,
    "type": "fehler"
  },
  "scope": "personal",
  "sort": "updated"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `columns` (array of string, required): Columns of the list
- `createdAt` (string (date-time), required): When the view was created
- `groupBy` (string, nullable, required): status, assignee, milestone, iteration or label-scope:<scope>
- `id` (string (uuid), required): View id
- `kind` (string, required): list or board (one of `list`, `board`)
- `name` (string, required): Name (max length 80)
- `ownerRef` (string, required): E-mail address of the creator
- `position` (integer, required): Order of the views
- `projectId` (string (uuid), nullable, required): null: a tenant-wide items view (always personal)
- `projectKey` (string, nullable, required): Key of the project; null for a tenant-wide view
- `query` (object, required): Item search filters, as the query parameters of `GET /items` (strings)
  - `assignee` (string): Assignee e-mails, comma separated
  - `category` (string): Status categories, comma separated
  - `iteration` (string): Iteration ids, comma separated
  - `label` (string): Label names, comma separated
  - `milestone` (string): Milestone ids, comma separated
  - `open` (string): Only open (true) or only closed (false) items (one of `true`, `false`)
  - `q` (string): Full-text search or an item reference
  - `status` (string): Status keys, comma separated
  - `type` (string): Item type keys, comma separated
- `scope` (string, required): `personal`: the owner's own; `project`: part of the project's configuration (one of `personal`, `project`)
- `sort` (string, required): Empty: the default of the list the view runs in (one of ``, `updated`, `created`, `rank`, `number`)
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

```json
{
  "columns": [],
  "createdAt": "2026-10-28T11:30:00Z",
  "groupBy": "status",
  "id": "2d3e4f5a-6b7c-4d8e-9fa0-1b2c3d4e5f01",
  "kind": "board",
  "name": "Aktuelle Iteration",
  "ownerRef": "emma.maier@muster-it.example",
  "position": 1,
  "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "projectKey": "APP",
  "query": {
    "iteration": "active"
  },
  "scope": "project",
  "sort": "rank",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/views' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"columns":["ref","title","status","assignees","updatedAt"],"kind":"list","name":"Offene Android-Fehler","projectKey":"APP","query":{"label":"plattform::android","open":true,"type":"fehler"},"scope":"personal","sort":"updated"}'
```

## Delete a saved view (its owner for a personal view; a project view tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/views/{id}`

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

Same permission as changing it. A project view writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/views/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a saved view (its owner for a personal view; a project view tenant:forge:write and maintainer, or tenant:forge:admin)

`PATCH /api/forge/v1/views/{id}`

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

Personal views are changed by their owner (anyone else 404), project views by those who configure the project (403 for others who see it; a view of a project the caller cannot see is 404). `version` is required (409 `version_conflict`); scope and project never change. Same validation as creating. Nothing changed writes no event and keeps the version. A project view writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `columns` (array of string): Columns of the list
- `groupBy` (string, nullable): status, assignee, milestone, iteration or label-scope:<scope>; null clears it
- `kind` (string): list or board (one of `list`, `board`)
- `name` (string): Name (max length 80)
- `position` (integer): Order of the views
- `projectKey` (string): Create only: the project (required with scope project)
- `query` (object): Item search filters (see View.query); `open` may be a boolean
- `scope` (string): Create only: personal (default) or project (one of `personal`, `project`)
- `sort` (string): Sort order; empty = the default of the list (one of ``, `updated`, `created`, `rank`, `number`)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "groupBy": "assignee",
  "name": "Iteration nach Zuständigen",
  "version": 1
}
```

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

- `columns` (array of string, required): Columns of the list
- `createdAt` (string (date-time), required): When the view was created
- `groupBy` (string, nullable, required): status, assignee, milestone, iteration or label-scope:<scope>
- `id` (string (uuid), required): View id
- `kind` (string, required): list or board (one of `list`, `board`)
- `name` (string, required): Name (max length 80)
- `ownerRef` (string, required): E-mail address of the creator
- `position` (integer, required): Order of the views
- `projectId` (string (uuid), nullable, required): null: a tenant-wide items view (always personal)
- `projectKey` (string, nullable, required): Key of the project; null for a tenant-wide view
- `query` (object, required): Item search filters, as the query parameters of `GET /items` (strings)
  - `assignee` (string): Assignee e-mails, comma separated
  - `category` (string): Status categories, comma separated
  - `iteration` (string): Iteration ids, comma separated
  - `label` (string): Label names, comma separated
  - `milestone` (string): Milestone ids, comma separated
  - `open` (string): Only open (true) or only closed (false) items (one of `true`, `false`)
  - `q` (string): Full-text search or an item reference
  - `status` (string): Status keys, comma separated
  - `type` (string): Item type keys, comma separated
- `scope` (string, required): `personal`: the owner's own; `project`: part of the project's configuration (one of `personal`, `project`)
- `sort` (string, required): Empty: the default of the list the view runs in (one of ``, `updated`, `created`, `rank`, `number`)
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 200 answer:

```json
{
  "columns": [],
  "createdAt": "2026-10-28T11:30:00Z",
  "groupBy": "status",
  "id": "2d3e4f5a-6b7c-4d8e-9fa0-1b2c3d4e5f01",
  "kind": "board",
  "name": "Aktuelle Iteration",
  "ownerRef": "emma.maier@muster-it.example",
  "position": 1,
  "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "projectKey": "APP",
  "query": {
    "iteration": "active"
  },
  "scope": "project",
  "sort": "rank",
  "version": 1
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/views/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"groupBy":"assignee","name":"Iteration nach Zuständigen","version":1}'
```

## Run a saved view (tenant:forge:read)

`GET /api/forge/v1/views/{id}/items`

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

Requires `tenant:forge:read` and a view the caller may see (else 404). Runs the view's `query` and `sort` through the same search as `GET /items` (a project view or a personal view of a project through `GET /projects/{key}/items`, so its default sort is rank; a tenant-wide view through `GET /items`, default sort updated) and answers the same page; `cursor` and `limit` continue it. `assignee` `me` means the caller.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cursor` | query | string |  | `nextCursor` of the previous page |
| `limit` | query | integer |  | (default `50`; max 200) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Items (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Item, required): One page of 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

Example 200 answer:

```json
{
  "items": [
    {
      "assignees": [
        "paul.schmid@muster-it.example"
      ],
      "closedAt": null,
      "confidential": false,
      "createdAt": "2026-11-09T11:20:00Z",
      "customFields": {
        "story_points": 3
      },
      "description": "Bei einer Antwort des Service Desks erscheint die Benachrichtigung auf Android zweimal.",
      "estimate": 3,
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c09",
      "iterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
      "iterationName": "Iteration 2 – Ticketübersicht",
      "labelIds": [
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c06",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"
      ],
      "labels": [
        "bug",
        "owner::android",
        "plattform::android",
        "priority::hoch"
      ],
      "milestoneId": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
      "milestoneTitle": "Version 1.1 – Ticketübersicht",
      "number": 9,
      "parentId": null,
      "parentNumber": null,
      "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "projectKey": "APP",
      "rank": "0000a2",
      "ref": "APP-9",
      "reporterRef": "ben.koch@muster-it.example",
      "resolution": null,
      "spentMinutes": 420,
      "statusCategory": "active",
      "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
      "statusKey": "in_arbeit",
      "statusName": "In Arbeit",
      "title": "Push-Benachrichtigung erscheint doppelt",
      "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
      "typeKey": "fehler",
      "updatedAt": "2026-11-13T10:00:00Z",
      "version": 5,
      "watchers": [
        "ben.koch@muster-it.example",
        "emma.maier@muster-it.example",
        "paul.schmid@muster-it.example"
      ]
    },
    {
      "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.",
      "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,
      "spentMinutes": 960,
      "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"
      ]
    }
  ],
  "nextCursor": "eyJzb3J0IjoidXBkYXRlZCIsInZhbHVlIjoiMjAyNi0xMS0xNlQxNjo0MDowMFoifQ"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/views/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Items

## Search items of every visible project (tenant:forge:read)

`GET /api/forge/v1/items`

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

Requires `tenant:forge:read`. Covers the projects the caller sees (private ones only for members and forge admins); confidential items only for tenant forge admins, members with role maintainer or higher, their reporter and their assignees. Tombstones of converted items are left out unless `includeConverted=true`. Filters combine; lists are comma separated. `nextCursor` continues the list.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  | Words in title or description, or a reference (APP-12) (max length 200) |
| `project` | query | string |  | Project keys, comma separated |
| `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 |
| `iteration` | query | string |  | An iteration id, `active` for the items of the active iteration, or `none` for items without one |
| `open` | query | boolean |  | true: open items only, false: closed ones |
| `includeConverted` | query | boolean |  | true also lists the tombstones of items converted to another module (left out by default) (default `false`) |
| `sort` | query | string |  | (one of `updated`, `created`, `rank`, `number`; default `"updated"`) |
| `cursor` | query | string |  | `nextCursor` of the previous page |
| `limit` | query | integer |  | (default `50`; max 200) |

### Responses

- **200** Items (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Item, required): One page of 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

Example 200 answer:

```json
{
  "items": [
    {
      "assignees": [
        "paul.schmid@muster-it.example"
      ],
      "closedAt": null,
      "confidential": false,
      "createdAt": "2026-11-09T11:20:00Z",
      "customFields": {
        "story_points": 3
      },
      "description": "Bei einer Antwort des Service Desks erscheint die Benachrichtigung auf Android zweimal.",
      "estimate": 3,
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c09",
      "iterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
      "iterationName": "Iteration 2 – Ticketübersicht",
      "labelIds": [
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c06",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"
      ],
      "labels": [
        "bug",
        "owner::android",
        "plattform::android",
        "priority::hoch"
      ],
      "milestoneId": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
      "milestoneTitle": "Version 1.1 – Ticketübersicht",
      "number": 9,
      "parentId": null,
      "parentNumber": null,
      "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "projectKey": "APP",
      "rank": "0000a2",
      "ref": "APP-9",
      "reporterRef": "ben.koch@muster-it.example",
      "resolution": null,
      "spentMinutes": 420,
      "statusCategory": "active",
      "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
      "statusKey": "in_arbeit",
      "statusName": "In Arbeit",
      "title": "Push-Benachrichtigung erscheint doppelt",
      "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
      "typeKey": "fehler",
      "updatedAt": "2026-11-13T10:00:00Z",
      "version": 5,
      "watchers": [
        "ben.koch@muster-it.example",
        "emma.maier@muster-it.example",
        "paul.schmid@muster-it.example"
      ]
    },
    {
      "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.",
      "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,
      "spentMinutes": 960,
      "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"
      ]
    }
  ],
  "nextCursor": "eyJzb3J0IjoidXBkYXRlZCIsInZhbHVlIjoiMjAyNi0xMS0xNlQxNjo0MDowMFoifQ"
}
```

### Example request

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

## 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"]}'
```

## Get an item with its sections (tenant:forge:read)

`GET /api/forge/v1/items/{ref}`

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

Requires `tenant:forge:read` and a project the caller sees (else 404); a confidential item only for tenant forge admins, members with role maintainer or higher, its reporter and its assignees (else 404). Includes the sections of the item's type and the caller's capabilities in the project. The tombstone of an item converted to another module is answered with `convertedTo` (writes on it are 409 `converted`). A number that moved to another project (or module) is 404 `moved` with `redirect {module, ref, path}` when the caller may see the target.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item reference, e.g. APP-12 |

### Responses

- **200** Item (`application/json`)
- **404** 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
- `access` (Capabilities, required)
  - `canConfigure` (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
  - `canCreateItem` (boolean, required): Create items and comment
  - `canDeleteItem` (boolean, required): Delete items and anyone's comments
  - `canEditItem` (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
  - `canManage` (boolean, required): Members, project settings, archive, delete
  - `canPlan` (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
  - `canUseAgent` (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
  - `member` (boolean, required): The caller is a member of the project
  - `role` (string, required): Effective role; empty when none
- `handoffs` (array of Handoff, required): The item's handoffs and conversions in both roles, newest first
  - `counterpartModule` (string, required): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string, required): Reference of the item on the other side (#123 or APP-12)
  - `counterpartStage` (string, required): Last known stage of the other item; `gone` when it no longer exists (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `createdAt` (string (date-time), required): When the handoff was started
  - `id` (string (uuid), required): Handoff id, shared with the other side
  - `itemId` (string (uuid), required): The forge item of this side
  - `kind` (string, required): `handoff`: a new linked item; `conversion`: the item moved and left a tombstone (one of `handoff`, `conversion`)
  - `role` (string, required): Which side this row is: the origin (handed over) or the receiver (one of `origin`, `receiver`)
  - `state` (string, required): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string, required): Delivery to the other side: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last checked
  - `counterpartContainerId` (string): Desk space or forge project id of the other side (once known)
  - `counterpartContainerKey` (string): Desk space key or forge project key of the other side
  - `counterpartItemId` (string): Id of the item on the other side (once known)
  - `counterpartStatusKey` (string): Last known status key of the other item
  - `counterpartStatusName` (string): Last known status name of the other item
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): E-mail of who started the handoff
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): Next delivery attempt while pending
  - `projectId` (string (uuid)): Project of the forge item
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When it was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): E-mail of who handed it back
  - `updatedAt` (string (date-time)): Last change of this side
  - `version` (integer): Version of this row
- `sections` (array of Section, required): The sections of the item type with their content
  - `body` (string, required): Markdown (checklist: a task list)
  - `key` (string, required): Section key
  - `kind` (string, required): markdown or checklist (one of `markdown`, `checklist`)
  - `label` (string, required): Display label
  - `placement` (string, required): Where the portal shows it: a tab or the side column (one of `tab`, `aside`)
  - `version` (integer, required): 0 = never written
  - `updatedAt` (string (date-time), nullable): When the current version was written; null when never written
  - `updatedByKind` (string): Kind of actor who wrote it
  - `updatedByName` (string): Name of who wrote it
  - `updatedByRef` (string): E-mail (or actor ref) of who wrote the current version

Example 200 answer:

```json
{
  "access": {
    "canConfigure": false,
    "canCreateItem": true,
    "canDeleteItem": false,
    "canEditItem": true,
    "canManage": false,
    "canPlan": true,
    "canUseAgent": true,
    "member": true,
    "role": "developer"
  },
  "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,
  "handoffs": [],
  "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,
  "sections": [
    {
      "body": "Die Komponente bekommt ihre Optionen über Props und meldet Änderungen als Ereignis. Der Zeitraum nutzt den Datumsdialog des Betriebssystems.",
      "key": "plan",
      "kind": "markdown",
      "label": "Plan",
      "placement": "tab",
      "updatedAt": "2026-11-04T09:15:00Z",
      "updatedByKind": "person",
      "updatedByName": "Marie Wagner",
      "updatedByRef": "marie.wagner@muster-it.example",
      "version": 1
    },
    {
      "body": "",
      "key": "agent_notes",
      "kind": "markdown",
      "label": "Notizen für Agenten",
      "placement": "tab",
      "updatedAt": null,
      "version": 0
    },
    {
      "body": "",
      "key": "acceptance",
      "kind": "checklist",
      "label": "Akzeptanzkriterien",
      "placement": "tab",
      "updatedAt": null,
      "version": 0
    }
  ],
  "spentMinutes": 960,
  "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

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

## List the items of a project (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items`

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

Requires `tenant:forge:read` and a project the caller sees. Same filters and confidential rule as `GET /items`; rank order by default.

### 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 |
| `iteration` | query | string |  | An iteration id, `active` for the items of the active iteration, or `none` for items without one |
| `open` | query | boolean |  | true: open items only, false: closed ones |
| `includeConverted` | query | boolean |  | true also lists the tombstones of items converted to another module (left out by default) (default `false`) |
| `sort` | query | string |  | (one of `updated`, `created`, `rank`, `number`; default `"rank"`) |
| `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** Items (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Item, required): One page of 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

Example 200 answer:

```json
{
  "items": [
    {
      "assignees": [
        "paul.schmid@muster-it.example"
      ],
      "closedAt": null,
      "confidential": false,
      "createdAt": "2026-11-09T11:20:00Z",
      "customFields": {
        "story_points": 3
      },
      "description": "Bei einer Antwort des Service Desks erscheint die Benachrichtigung auf Android zweimal.",
      "estimate": 3,
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c09",
      "iterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
      "iterationName": "Iteration 2 – Ticketübersicht",
      "labelIds": [
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c06",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"
      ],
      "labels": [
        "bug",
        "owner::android",
        "plattform::android",
        "priority::hoch"
      ],
      "milestoneId": "e0a1b2c3-d4e5-4f6a-8b23-0e1f2a3b4c02",
      "milestoneTitle": "Version 1.1 – Ticketübersicht",
      "number": 9,
      "parentId": null,
      "parentNumber": null,
      "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "projectKey": "APP",
      "rank": "0000a2",
      "ref": "APP-9",
      "reporterRef": "ben.koch@muster-it.example",
      "resolution": null,
      "spentMinutes": 420,
      "statusCategory": "active",
      "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f03",
      "statusKey": "in_arbeit",
      "statusName": "In Arbeit",
      "title": "Push-Benachrichtigung erscheint doppelt",
      "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
      "typeKey": "fehler",
      "updatedAt": "2026-11-13T10:00:00Z",
      "version": 5,
      "watchers": [
        "ben.koch@muster-it.example",
        "emma.maier@muster-it.example",
        "paul.schmid@muster-it.example"
      ]
    },
    {
      "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.",
      "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,
      "spentMinutes": 960,
      "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"
      ]
    }
  ],
  "nextCursor": "eyJzb3J0IjoidXBkYXRlZCIsInZhbHVlIjoiMjAyNi0xMS0xNlQxNjo0MDowMFoifQ"
}
```

### Example request

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

## Create an item (tenant:forge:write, or any member role in the project; iterationId and milestoneId need tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items`

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

Requires `tenant:forge:write`, or any project membership (reporters may create). The number comes from the project (`APP-12`); type defaults to the project's default type, status to the default status of the type's workflow. Archived project 409 `project_archived`. Writes `forge.item.created`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `title` (string, required): Title (max length 300)
- `assignees` (array of string (email)): E-mail addresses of the assignees
- `confidential` (boolean): Only tenant forge admins, members ≥ maintainer, the reporter and the assignees see the item (default `false`)
- `customFields` (object): Values of custom fields by field key
- `description` (string): Description (Markdown) (max length 100000)
- `dueOn` (string (date)): Due date
- `estimate` (number): Estimate (story points or hours, as the team uses it)
- `iterationId` (string (uuid)): A planned or active iteration of the project; needs the right to plan (403 otherwise)
- `labelIds` (array of string (uuid)): Labels of the project
- `milestoneId` (string (uuid)): An open milestone of the project
- `parentNumber` (integer): Number of the parent item in the project (its type must have a higher level)
- `resolution` (string): Resolution when the status is done or cancelled (one of `done`, `not_planned`, `duplicate`, `returned`)
- `startOn` (string (date)): Planned start date
- `statusId` (string (uuid)): Initial status; default the initial status of the type's workflow
- `templateKey` (string): Item template key: fills type, title, description and labels not given
- `typeId` (string (uuid)): Item type; default the project's default type

Example:

```json
{
  "assignees": [
    "paul.schmid@muster-it.example"
  ],
  "customFields": {
    "story_points": 3
  },
  "description": "Bei einer Antwort des Service Desks erscheint die Benachrichtigung auf Android zweimal.\n\nSchritte: App im Hintergrund lassen, im Kundenportal eine Antwort auf ein Ticket schreiben.",
  "estimate": 3,
  "labelIds": [
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05",
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"
  ],
  "title": "Push-Benachrichtigung erscheint doppelt",
  "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 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 201 answer:

```json
{
  "assignees": [
    "paul.schmid@muster-it.example"
  ],
  "closedAt": null,
  "confidential": false,
  "createdAt": "2026-11-09T11:20:00Z",
  "customFields": {
    "story_points": 3
  },
  "description": "Bei einer Antwort des Service Desks erscheint die Benachrichtigung auf Android zweimal.\n\nSchritte: App im Hintergrund lassen, im Kundenportal eine Antwort auf ein Ticket schreiben.",
  "dueOn": null,
  "estimate": 3,
  "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c09",
  "iterationId": null,
  "iterationName": null,
  "labelIds": [
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04",
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05",
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"
  ],
  "labels": [
    "bug",
    "plattform::android",
    "priority::hoch"
  ],
  "milestoneId": null,
  "milestoneTitle": null,
  "number": 9,
  "parentId": null,
  "parentNumber": null,
  "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "projectKey": "APP",
  "rank": "0000a2",
  "ref": "APP-9",
  "reporterRef": "ben.koch@muster-it.example",
  "resolution": null,
  "spentMinutes": null,
  "startOn": null,
  "statusCategory": "todo",
  "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f02",
  "statusKey": "offen",
  "statusName": "Offen",
  "title": "Push-Benachrichtigung erscheint doppelt",
  "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04",
  "typeKey": "fehler",
  "updatedAt": "2026-11-09T11:20:00Z",
  "version": 1,
  "watchers": [
    "ben.koch@muster-it.example",
    "paul.schmid@muster-it.example"
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"assignees":["paul.schmid@muster-it.example"],"customFields":{"story_points":3},"description":"Bei einer Antwort des Service Desks erscheint die Benachrichtigung auf Android zweimal.\n\nSchritte: App im Hintergrund lassen, im Kundenportal eine Antwort auf ein Ticket schreiben.","estimate":3,"labelIds":["8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c04","8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c05","8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"],"title":"Push-Benachrichtigung erscheint doppelt","typeId":"7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b04"}'
```

## Delete an item for good (tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/items/{number}`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. An item with children is refused (409 `has_children`), so is one with a handoff still being delivered (409 `handoff_pending`) or a pending conversion (409 `conversion_pending`). Writes `forge.item.deleted` before the item goes; links, comments and sections go with it.

### 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) |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

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

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

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

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

```bash
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}'
```

## Move an item in the project's order (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/rank`

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

Same permission as changing an item. Places the item after `after` and/or before `before` (item numbers of the project). Writes `forge.item.moved`.

### 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)

- `after` (integer): Number of the item to come after
- `before` (integer): Number of the item to come before

Example:

```json
{
  "after": 9
}
```

### Responses

- **200** Moved (`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:

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

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/rank' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"after":9}'
```

## Move an item to another project (tenant:forge:write and, as a member, at least developer in the source; create rights in the target)

`POST /api/forge/v1/projects/{key}/items/{number}/move`

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

Requires the permission to change the item in this project (forge write) and a target project the caller sees; both projects are of the tenant and active. The item keeps its row and id and gets the next number of the target (a new reference); the old reference answers 404 `moved` with a redirect that follows the item to its current reference. Type by key (`typeKey`, else the same key, else the target's default type), status by key (`statusKey`, else the same key in the type's workflow, else the first status of the same category, else the initial one). Parent, milestone and iteration are cleared; labels (by name), custom fields and sections (by key) the target lacks are dropped and listed in `dropped`; section revisions are not kept (the current text becomes revision 1). History, comments, links, assignees and watchers follow. A confidential item stays confidential; the caller must still see it in the target (403 `confidential_target`). 409 `has_children` (an item with children), `converted` (tombstone), `conversion_pending`, `version_conflict`, `project_archived`. Writes `forge.item.moved` (with `fromProjectId`) and, when scm is connected, queues the relabel of the item's GitHub links.

### 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)

- `project` (string, required): Key of the target project
- `version` (integer, required): Version of the item the caller saw
- `statusKey` (string): Status of the type's workflow in the target project (optional)
- `typeKey` (string): Item type of the target project (optional)

Example:

```json
{
  "project": "OPS",
  "typeKey": "fehler",
  "version": 5
}
```

### Responses

- **200** Moved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `dropped` (array of string, required): What the target has no place for: `label:<name>`, `section:<key>`, `customFields.<key>`
- `item` (Item, required)
  - `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
{
  "dropped": [
    "label:owner::android",
    "label:plattform::android",
    "label:priority::hoch",
    "customFields.story_points"
  ],
  "item": {
    "assignees": [
      "paul.schmid@muster-it.example"
    ],
    "closedAt": null,
    "confidential": false,
    "createdAt": "2026-11-09T11:20:00Z",
    "customFields": {},
    "description": "Bei einer Antwort des Service Desks erscheint die Benachrichtigung auf Android zweimal.",
    "estimate": 3,
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c09",
    "iterationId": null,
    "iterationName": null,
    "labelIds": [
      "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8d24"
    ],
    "labels": [
      "bug"
    ],
    "milestoneId": null,
    "milestoneTitle": null,
    "number": 14,
    "parentId": null,
    "parentNumber": null,
    "projectId": "3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b",
    "projectKey": "OPS",
    "rank": "0000c0",
    "ref": "OPS-14",
    "reporterRef": "ben.koch@muster-it.example",
    "resolution": null,
    "statusCategory": "active",
    "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f23",
    "statusKey": "in_arbeit",
    "statusName": "In Arbeit",
    "title": "Push-Benachrichtigung erscheint doppelt",
    "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7c24",
    "typeKey": "fehler",
    "updatedAt": "2026-11-18T10:05:00Z",
    "version": 6,
    "watchers": [
      "ben.koch@muster-it.example",
      "emma.maier@muster-it.example",
      "paul.schmid@muster-it.example"
    ]
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/move' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"project":"OPS","typeKey":"fehler","version":5}'
```

## List the children of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/children`

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

Requires `tenant:forge:read` and a project the caller sees. Direct children in rank order (at most 200).

### 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) |

### Responses

- **200** Children (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Item, required)
  - `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
{
  "items": [
    {
      "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.",
      "estimate": 3,
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06",
      "labelIds": [
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c01",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c02"
      ],
      "labels": [
        "bereich::frontend",
        "priority::mittel"
      ],
      "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",
      "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"
      ]
    },
    {
      "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.",
      "estimate": 3,
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c07",
      "labelIds": [
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c01",
        "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c02"
      ],
      "labels": [
        "bereich::frontend",
        "priority::mittel"
      ],
      "number": 7,
      "parentId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c05",
      "parentNumber": 5,
      "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-17T10:00:00Z",
      "version": 3,
      "watchers": [
        "emma.maier@muster-it.example",
        "paul.schmid@muster-it.example"
      ]
    }
  ]
}
```

### Example request

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

## Replace the assignees of an item (tenant:forge:write and, as a member, at least developer)

`PUT /api/forge/v1/projects/{key}/items/{number}/assignees`

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

Same permission as changing an item. At most 20 e-mail addresses; new assignees start watching the item. Writes `forge.item.assigned` or `unassigned`.

### 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)

- `assignees` (array of string (email), required)

Example:

```json
{
  "assignees": [
    "marie.wagner@muster-it.example",
    "paul.schmid@muster-it.example"
  ]
}
```

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

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

```bash
curl -X PUT 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/assignees' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"assignees":["marie.wagner@muster-it.example","paul.schmid@muster-it.example"]}'
```

## Add one assignee to an item (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/assignees/add`

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

Same permission as changing an item (`tenant:forge:write` and project role developer or higher). `ref` is a lower-case e-mail address, `reporter` or `ownership_owner` – the effective owner of the item's ownership (its `owner::` label, else the later-positioned ownership matching its type or labels): the person, or the lead of the owning team. Nobody to add (no ownership, no owner) or a person who is assigned already changes nothing and answers 200 with the item. The new assignee starts watching the item; at most 20 assignees (400 `assignees`). Writes `forge.item.assigned`.

### 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)

- `ref` (string, required): A lower-case e-mail address, `reporter` (the item's reporter) or `ownership_owner` (the owner of the item's ownership: the person, or the lead of the owning team)

Example:

```json
{
  "ref": "ownership_owner"
}
```

### Responses

- **200** The item after the change and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** 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:

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

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/assignees/add' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"ref":"ownership_owner"}'
```

## Replace the labels of an item (tenant:forge:write and, as a member, at least developer)

`PUT /api/forge/v1/projects/{key}/items/{number}/labels`

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

Same permission as changing an item. A scoped label (`scope::value`) replaces the item's label of the same scope. Writes `forge.item.labeled` or `unlabeled`.

### 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)

- `labelIds` (array of string (uuid), required)

Example:

```json
{
  "labelIds": [
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c01",
    "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"
  ]
}
```

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

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

```bash
curl -X PUT 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/labels' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"labelIds":["8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c01","8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c03"]}'
```

## Add one label to an item (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/labels/add`

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

Same permission as changing an item. `label` names a label of the project (case-insensitive; an unknown one is 400 `label`). A scoped label (`scope::value`) replaces the item's label of the same scope; a label the item carries already changes nothing and answers 200 with the item. Writes `forge.item.labeled` (`addedLabels`, `removedLabels` in the event).

### 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)

- `label` (string, required): Name of a label of the project (case-insensitive)

Example:

```json
{
  "label": "sprint-ziel"
}
```

### Responses

- **200** The item after the change and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** 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:

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

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/labels/add' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"label":"sprint-ziel"}'
```

## Remove one label from an item (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/labels/remove`

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

Same permission as changing an item. `label` names a label of the project (case-insensitive; an unknown one is 400 `label`). A label the item does not carry changes nothing and answers 200 with the item. Writes `forge.item.unlabeled`.

### 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)

- `label` (string, required): Name of a label of the project (case-insensitive)

Example:

```json
{
  "label": "priority::mittel"
}
```

### Responses

- **200** The item after the change and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** 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:

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

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/labels/remove' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"label":"priority::mittel"}'
```

## Move an item to a status or a status category (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/transition`

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

Same permission as changing an item. Exactly one of `statusKey` and `category` (else 400 `statusKey`; an unknown status 400 `statusKey`). `statusKey`: that status, when the workflow of the item's type allows the move from the current status. `category`: the first status of the category, by position, that the workflow contains and allows from the current status; an item already in the category stays where it is (200, nothing recorded). A move the workflow does not allow is 409 `transition_not_allowed`. Unlike `PATCH` it needs neither a status id nor the item's version. Entering done or cancelled sets `closedAt` and `resolution`. Writes `forge.item.status_changed`, or `closed` / `reopened` together with `status_changed`.

### 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)

- `category` (string): Status category to reach: the first status of the category (by position) that the workflow contains and allows from the current status; an item already in the category stays where it is (one of `triage`, `todo`, `active`, `on_hold`, `done`, `cancelled`)
- `statusKey` (string): Key of the status to move to; the workflow of the item's type must allow the move from the current status

Example:

```json
{
  "statusKey": "review"
}
```

### Responses

- **200** The item after the change and the automations it started (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** 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:

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

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/transition' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"statusKey":"review"}'
```

## List the links of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/links`

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

Requires `tenant:forge:read` and a project the caller sees. Links to items of projects the caller does not see are left out.

### 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) |

### Responses

- **200** Links (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Link, required)
  - `createdAt` (string (date-time), required): When the link was created
  - `createdBy` (string, required): E-mail of who created the link
  - `direction` (string, required): `outgoing`: this item is the source; `incoming`: the other item is (one of `outgoing`, `incoming`)
  - `id` (string (uuid), required): Link id
  - `item` (object, required): The other item
    - `id` (string (uuid), required): Item id
    - `projectKey` (string, required): Project key
    - `ref` (string, required): Item reference, e.g. WEB-3
    - `statusCategory` (string, required): Status category
    - `statusKey` (string, required): Status key
    - `statusName` (string, required): Status name
    - `title` (string, required): Title
    - `typeKey` (string, required): Item type key
  - `kind` (string, required): Link kind (one of `blocks`, `relates`, `duplicates`)

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-10-28T10:40:00Z",
      "createdBy": "emma.maier@muster-it.example",
      "direction": "outgoing",
      "id": "6c7d8e9f-0a1b-4c2d-9e3f-5a6b7c8d9e01",
      "item": {
        "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c07",
        "projectKey": "APP",
        "ref": "APP-7",
        "statusCategory": "todo",
        "statusKey": "offen",
        "statusName": "Offen",
        "title": "Cursor-basierte Seitenwechsel in der Ticketliste",
        "typeKey": "aufgabe"
      },
      "kind": "blocks"
    }
  ]
}
```

### Example request

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

## Link an item to another item (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/links`

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

Same permission as changing an item; the target may be in any project of the tenant the caller sees. No self links; a `blocks` link that closes a cycle is 409 `link_cycle`; an existing link 409 `link_exists`. `duplicates` closes the item with resolution `duplicate`. Writes `forge.item.linked` (and `closed`).

### 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)

- `kind` (string, required): Seen from this item: it blocks / relates to / duplicates the target (one of `blocks`, `relates`, `duplicates`)
- `target` (string, required): Reference of the other item, e.g. WEB-3

Example:

```json
{
  "kind": "blocks",
  "target": "APP-7"
}
```

### Responses

- **201** Linked (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time), required): When the link was created
- `createdBy` (string, required): E-mail of who created the link
- `direction` (string, required): `outgoing`: this item is the source; `incoming`: the other item is (one of `outgoing`, `incoming`)
- `id` (string (uuid), required): Link id
- `item` (object, required): The other item
  - `id` (string (uuid), required): Item id
  - `projectKey` (string, required): Project key
  - `ref` (string, required): Item reference, e.g. WEB-3
  - `statusCategory` (string, required): Status category
  - `statusKey` (string, required): Status key
  - `statusName` (string, required): Status name
  - `title` (string, required): Title
  - `typeKey` (string, required): Item type key
- `kind` (string, required): Link kind (one of `blocks`, `relates`, `duplicates`)

Example 201 answer:

```json
{
  "createdAt": "2026-10-28T10:40:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "direction": "outgoing",
  "id": "6c7d8e9f-0a1b-4c2d-9e3f-5a6b7c8d9e01",
  "item": {
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c07",
    "projectKey": "APP",
    "ref": "APP-7",
    "statusCategory": "todo",
    "statusKey": "offen",
    "statusName": "Offen",
    "title": "Cursor-basierte Seitenwechsel in der Ticketliste",
    "typeKey": "aufgabe"
  },
  "kind": "blocks"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/links' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"kind":"blocks","target":"APP-7"}'
```

## Remove a link (tenant:forge:write and, as a member, at least developer)

`DELETE /api/forge/v1/projects/{key}/items/{number}/links/{id}`

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

Same permission as changing the item in the URL (either end of the link). Writes `forge.item.unlinked`.

### 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) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Removed
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/links/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## History of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/events`

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

Requires `tenant:forge:read` and a project the caller sees. Oldest first; `changes` names the fields with `from`/`to` (the description is named without its text).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | 1–500; another value is a 400 invalid. (default `200`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page. |
| `key` | path | string | yes | Project key (e.g. APP) |
| `number` | path | integer | yes | Item number in the project (12 of APP-12) |

### Responses

- **200** A page of the history (keyset, `nextCursor` while more follow) (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ItemEvent, required)
  - `action` (string, required): What happened (one of `created`, `updated`, `status_changed`, `assigned`, `unassigned`, `labeled`, `unlabeled`, `linked`, `unlinked`, `commented`, `comment_edited`, `comment_deleted`, `section_updated`, `moved`, `closed`, `reopened`, `deleted`)
  - `actorKind` (string, required): Kind of actor (person, integration, assistant, automation, system, scm)
  - `actorName` (string, required): Display name of the actor
  - `actorRef` (string, required): E-mail (or actor ref) of who made the change
  - `changes` (object, required): Changed fields with their old (`from`) and new (`to`) value
  - `createdAt` (string (date-time), required): When it happened
  - `id` (integer, required): Event id (ascending)
  - `itemId` (string (uuid), required): The item
- `nextCursor` (string)

Example 200 answer:

```json
{
  "items": [
    {
      "action": "status_changed",
      "actorKind": "person",
      "actorName": "Marie Wagner",
      "actorRef": "marie.wagner@muster-it.example",
      "changes": {
        "status": {
          "from": "offen",
          "to": "in_arbeit"
        }
      },
      "createdAt": "2026-11-04T09:00:00Z",
      "id": 4807,
      "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06"
    },
    {
      "action": "status_changed",
      "actorKind": "person",
      "actorName": "Marie Wagner",
      "actorRef": "marie.wagner@muster-it.example",
      "changes": {
        "status": {
          "from": "in_arbeit",
          "to": "review"
        }
      },
      "createdAt": "2026-11-16T16:40:00Z",
      "id": 4812,
      "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06"
    }
  ],
  "nextCursor": "eyJpZCI6NDgxMn0"
}
```

### Example request

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

## Watch an item (tenant:forge:read)

`PUT /api/forge/v1/projects/{key}/items/{number}/watch`

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

Requires `tenant:forge:read` and a project the caller sees. Idempotent; not part of the item's history.

### 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) |

### Responses

- **204** Watching
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

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

## Stop watching an item (tenant:forge:read)

`DELETE /api/forge/v1/projects/{key}/items/{number}/watch`

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

Requires `tenant:forge:read` and a project the caller sees. Idempotent.

### 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) |

### Responses

- **204** Not watching
- **403** Error (`application/json`)
- **404** Error (`application/json`)

### Example request

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

# Handoffs

## List the projects an item or ticket can be handed to (tenant:forge:read or tenant:forge:intake)

`GET /api/forge/v1/handoff-targets`

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

Requires `tenant:forge:read`, `write`, `admin` or `intake`. The active projects, each with its item types and default type, that a handoff from `origin` may go to: `desk` (default; desk's handoff to development, called with the person's token) – projects where the caller may create items (forge write or a membership in a visible project) or, with `tenant:forge:intake`, that accept intake (`acceptsIntake`); `forge` (forge's own handoff) – only projects where the caller may create items. Desk targets come from desk's bootstrap.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `origin` | query | string |  | (one of `desk`, `forge`; default `"desk"`) |

### Responses

- **200** Targets (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of HandoffTarget, required)
  - `acceptsIntake` (boolean, required): The project accepts desk tickets from intake-only callers
  - `id` (string (uuid), required): Project id
  - `key` (string, required): Project key
  - `name` (string, required): Project name
  - `types` (array of object, required): Item types of the project
    - `key` (string, required): Item type key
    - `name` (string, required): Item type name
  - `defaultTypeKey` (string): Key of the default item type

Example 200 answer:

```json
{
  "items": [
    {
      "acceptsIntake": true,
      "defaultTypeKey": "aufgabe",
      "id": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "key": "APP",
      "name": "Kundenportal-App",
      "types": [
        {
          "key": "epic",
          "name": "Epic"
        },
        {
          "key": "story",
          "name": "Story"
        },
        {
          "key": "aufgabe",
          "name": "Aufgabe"
        },
        {
          "key": "fehler",
          "name": "Fehler"
        },
        {
          "key": "subtask",
          "name": "Sub-Task"
        }
      ]
    },
    {
      "acceptsIntake": false,
      "defaultTypeKey": "aufgabe",
      "id": "3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b",
      "key": "OPS",
      "name": "Plattform-Betrieb",
      "types": [
        {
          "key": "epic",
          "name": "Epic"
        },
        {
          "key": "story",
          "name": "Story"
        },
        {
          "key": "aufgabe",
          "name": "Aufgabe"
        },
        {
          "key": "fehler",
          "name": "Fehler"
        }
      ]
    }
  ]
}
```

### Example request

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

## Set what handed-back items do in a project (tenant:forge:write and maintainer, or tenant:forge:admin)

`PUT /api/forge/v1/projects/{key}/handoff-settings`

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

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or admin. Stores `settings.handoff` of the project (the project's `settings` answer it): `receiverOnReturn` – what an item this project received does when it is handed back (`close`: `status` if given, a done or cancelled status, else the first done status of its workflow (a cancelled one without a done status; an item that is closed already stays), resolution `returned`; or `keep`); `originOnReturn` – what an item this project handed off does when it comes back (`none`, or `status`: `stage` new|active|waiting and optionally a `status` of that stage, else the first status of the stage; nothing when the item is in the stage already). Both reactions are system moves that ignore workflow transitions. Defaults: close / none. Writes `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `originOnReturn` (object): What the origin item does when its handoff comes back
  - `action` (string): `none`: nothing; `status`: move it to a status of `stage` (one of `none`, `status`)
  - `stage` (string): The stage to move the origin item to (one of `new`, `active`, `waiting`)
  - `status` (string): status: a status key of the stage
- `receiverOnReturn` (object): What a received item does when it is handed back
  - `action` (string): `close`: move it to `status`; `keep`: leave it as it is (one of `close`, `keep`)
  - `status` (string): close: a done or cancelled status key of the project

Example:

```json
{
  "originOnReturn": {
    "action": "status",
    "stage": "active",
    "status": "in_arbeit"
  },
  "receiverOnReturn": {
    "action": "close",
    "status": "erledigt"
  }
}
```

### Responses

- **200** Saved (with defaults filled) (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `originOnReturn` (object): What the origin item does when its handoff comes back
  - `action` (string): `none`: nothing; `status`: move it to a status of `stage` (one of `none`, `status`)
  - `stage` (string): The stage to move the origin item to (one of `new`, `active`, `waiting`)
  - `status` (string): status: a status key of the stage
- `receiverOnReturn` (object): What a received item does when it is handed back
  - `action` (string): `close`: move it to `status`; `keep`: leave it as it is (one of `close`, `keep`)
  - `status` (string): close: a done or cancelled status key of the project

Example 200 answer:

```json
{
  "originOnReturn": {
    "action": "status",
    "stage": "active",
    "status": "in_arbeit"
  },
  "receiverOnReturn": {
    "action": "close",
    "status": "erledigt"
  }
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/forge/v1/projects/string/handoff-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"originOnReturn":{"action":"status","stage":"active","status":"in_arbeit"},"receiverOnReturn":{"action":"close","status":"erledigt"}}'
```

## List the handoffs of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/handoffs`

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

Requires `tenant:forge:read` and an item the caller sees. Both directions (role `origin` = handed off from this item, `receiver` = received), newest first, with the cached state of the counterpart.

### 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) |

### Responses

- **200** Handoffs (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Handoff, required)
  - `counterpartModule` (string, required): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string, required): Reference of the item on the other side (#123 or APP-12)
  - `counterpartStage` (string, required): Last known stage of the other item; `gone` when it no longer exists (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `createdAt` (string (date-time), required): When the handoff was started
  - `id` (string (uuid), required): Handoff id, shared with the other side
  - `itemId` (string (uuid), required): The forge item of this side
  - `kind` (string, required): `handoff`: a new linked item; `conversion`: the item moved and left a tombstone (one of `handoff`, `conversion`)
  - `role` (string, required): Which side this row is: the origin (handed over) or the receiver (one of `origin`, `receiver`)
  - `state` (string, required): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string, required): Delivery to the other side: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last checked
  - `counterpartContainerId` (string): Desk space or forge project id of the other side (once known)
  - `counterpartContainerKey` (string): Desk space key or forge project key of the other side
  - `counterpartItemId` (string): Id of the item on the other side (once known)
  - `counterpartStatusKey` (string): Last known status key of the other item
  - `counterpartStatusName` (string): Last known status name of the other item
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): E-mail of who started the handoff
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): Next delivery attempt while pending
  - `projectId` (string (uuid)): Project of the forge item
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When it was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): E-mail of who handed it back
  - `updatedAt` (string (date-time)): Last change of this side
  - `version` (integer): Version of this row

Example 200 answer:

```json
{
  "items": [
    {
      "attempts": 0,
      "counterpartCheckedAt": "2026-11-13T10:12:00Z",
      "counterpartContainerId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
      "counterpartContainerKey": "SUP",
      "counterpartItemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
      "counterpartModule": "desk",
      "counterpartRef": "#37",
      "counterpartStage": "waiting",
      "counterpartStatusKey": "wartet_dritte",
      "counterpartStatusName": "Wartet auf Dritte",
      "createdAt": "2026-11-13T10:10:00Z",
      "createdByName": "Sophie Huber",
      "createdByRef": "sophie.huber@muster-it.example",
      "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b01",
      "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
      "kind": "handoff",
      "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "role": "receiver",
      "state": "open",
      "syncState": "confirmed",
      "updatedAt": "2026-11-13T10:12:00Z",
      "version": 2
    }
  ]
}
```

### Example request

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

## Hand an item over to a forge project or a desk space (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/handoffs`

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

Requires the permission to change the item (forge write; CanEditItem). Creates a NEW linked item in the target (`target.module` forge: a project key the caller may create items in, the normal create path – type by key else the default, status by key else the first new status; desk: a space key, desk decides with the caller's permissions). Title, description and priority default to the item's (priority from a `priority::`/`prioritaet::` label); a confidential item gives a confidential one. Header `Idempotency-Key` is required (400 without): the handoff id is derived from the item and the key, so a retry answers the same handoff. forge → forge: one transaction, 201 with both rows confirmed, history `handoff_received` / `handed_off`, events `forge.handoff.received` / `forge.handoff.sent`, automations on `forge.item.handoff_received` in the target. forge → desk: 201 once desk confirmed, 202 with the pending row while desk cannot be reached (retried every 30 s with backoff up to an hour; after 24 h the handoff fails with a system comment); a refusal by desk is 422 `handoff_refused` (row failed, system comment „Übergabe an … fehlgeschlagen: …“, `forge.handoff.failed`). 409 `converted`, `conversion_pending`, `project_archived`; 503 `desk_unavailable` when desk is not connected.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes | (max length 200) |
| `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)

- `target` (HandoffTargetRef, required)
  - `container` (string, required): Desk space key or forge project key
  - `module` (string, required): Target module (one of `desk`, `forge`)
  - `statusKey` (string): Status of the new item; default the first status of the stage
  - `typeKey` (string): Item type (forge) or ticket type (desk) of the new item; default the target's default
- `description` (string): Description of the new item; empty = the item's
- `priority` (string): Priority of the new item; default from the item's priority label (a forge target does not take it over)
- `title` (string): Title of the new item; empty = the item's

Example:

```json
{
  "description": "Nach dem Fix in der App (APP-9) bleiben alte Geräte-Tokens im Push-Dienst stehen; bitte einmalig bereinigen.",
  "target": {
    "container": "OPS",
    "module": "forge",
    "typeKey": "aufgabe"
  },
  "title": "Doppelte Push-Registrierungen im Push-Dienst bereinigen"
}
```

### Responses

- **201** Handed off (`application/json`)
- **202** Pending (desk not reached yet) (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `dropped` (array of string): What the target did not take over (a move: `label:<name>`, …; a forge handoff: the priority)
- `handoff` (Handoff)
  - `counterpartModule` (string, required): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string, required): Reference of the item on the other side (#123 or APP-12)
  - `counterpartStage` (string, required): Last known stage of the other item; `gone` when it no longer exists (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `createdAt` (string (date-time), required): When the handoff was started
  - `id` (string (uuid), required): Handoff id, shared with the other side
  - `itemId` (string (uuid), required): The forge item of this side
  - `kind` (string, required): `handoff`: a new linked item; `conversion`: the item moved and left a tombstone (one of `handoff`, `conversion`)
  - `role` (string, required): Which side this row is: the origin (handed over) or the receiver (one of `origin`, `receiver`)
  - `state` (string, required): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string, required): Delivery to the other side: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last checked
  - `counterpartContainerId` (string): Desk space or forge project id of the other side (once known)
  - `counterpartContainerKey` (string): Desk space key or forge project key of the other side
  - `counterpartItemId` (string): Id of the item on the other side (once known)
  - `counterpartStatusKey` (string): Last known status key of the other item
  - `counterpartStatusName` (string): Last known status name of the other item
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): E-mail of who started the handoff
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): Next delivery attempt while pending
  - `projectId` (string (uuid)): Project of the forge item
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When it was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): E-mail of who handed it back
  - `updatedAt` (string (date-time)): Last change of this side
  - `version` (integer): Version of this row
- `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 201 answer:

```json
{
  "dropped": [
    "priority"
  ],
  "handoff": {
    "attempts": 0,
    "counterpartContainerId": "3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b",
    "counterpartContainerKey": "OPS",
    "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5d0f",
    "counterpartModule": "forge",
    "counterpartRef": "OPS-15",
    "counterpartStage": "new",
    "counterpartStatusKey": "offen",
    "counterpartStatusName": "Offen",
    "createdAt": "2026-11-18T10:20:00Z",
    "createdByName": "Paul Schmid",
    "createdByRef": "paul.schmid@muster-it.example",
    "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b03",
    "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c09",
    "kind": "handoff",
    "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "role": "origin",
    "state": "open",
    "syncState": "confirmed",
    "updatedAt": "2026-11-18T10:20:00Z",
    "version": 1
  },
  "item": {
    "assignees": [],
    "confidential": false,
    "createdAt": "2026-11-18T10:20:00Z",
    "customFields": {},
    "description": "Nach dem Fix in der App (APP-9) bleiben alte Geräte-Tokens im Push-Dienst stehen; bitte einmalig bereinigen.",
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5d0f",
    "labelIds": [],
    "labels": [],
    "number": 15,
    "projectId": "3e5f7a9b-1c2d-4e3f-8a5b-7c9d1e3f5a7b",
    "projectKey": "OPS",
    "rank": "0000d0",
    "ref": "OPS-15",
    "reporterRef": "paul.schmid@muster-it.example",
    "statusCategory": "todo",
    "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f22",
    "statusKey": "offen",
    "statusName": "Offen",
    "title": "Doppelte Push-Registrierungen im Push-Dienst bereinigen",
    "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7c23",
    "typeKey": "aufgabe",
    "updatedAt": "2026-11-18T10:20:00Z",
    "version": 1,
    "watchers": [
      "paul.schmid@muster-it.example"
    ]
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/handoffs' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"description":"Nach dem Fix in der App (APP-9) bleiben alte Geräte-Tokens im Push-Dienst stehen; bitte einmalig bereinigen.","target":{"container":"OPS","module":"forge","typeKey":"aufgabe"},"title":"Doppelte Push-Registrierungen im Push-Dienst bereinigen"}'
```

## Hand a received item back (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/handoffs/{id}/return`

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

Requires the permission to change the item (forge write; CanEditItem). The item must be the receiver of the handoff (else 404), the handoff open or closed (409 `handoff_state`). Marks it handed back with the note (≤ 2 000 characters), applies the project's `receiverOnReturn` (default: close with resolution `returned`) as a system move, records `handed_back`, writes `forge.handoff.returned` and runs the automations on `forge.item.handed_back`. A forge origin is updated in the same transaction (system comment with the note, its project's `originOnReturn`, `handback_received`); desk learns it from forge's feed.

### 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) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `note` (string): (max length 2000)

Example:

```json
{
  "note": "Kein Fehler und vorerst keine Funktion der App: Den PDF-Export der Ticketliste gibt es im Kundenportal im Browser (Tickets → Exportieren)."
}
```

### Responses

- **200** Handed back (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `counterpartModule` (string, required): Module of the other side (one of `desk`, `forge`)
- `counterpartRef` (string, required): Reference of the item on the other side (#123 or APP-12)
- `counterpartStage` (string, required): Last known stage of the other item; `gone` when it no longer exists (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
- `createdAt` (string (date-time), required): When the handoff was started
- `id` (string (uuid), required): Handoff id, shared with the other side
- `itemId` (string (uuid), required): The forge item of this side
- `kind` (string, required): `handoff`: a new linked item; `conversion`: the item moved and left a tombstone (one of `handoff`, `conversion`)
- `role` (string, required): Which side this row is: the origin (handed over) or the receiver (one of `origin`, `receiver`)
- `state` (string, required): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
- `syncState` (string, required): Delivery to the other side: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
- `attempts` (integer): Delivery attempts so far
- `counterpartCheckedAt` (string (date-time)): When the other side was last checked
- `counterpartContainerId` (string): Desk space or forge project id of the other side (once known)
- `counterpartContainerKey` (string): Desk space key or forge project key of the other side
- `counterpartItemId` (string): Id of the item on the other side (once known)
- `counterpartStatusKey` (string): Last known status key of the other item
- `counterpartStatusName` (string): Last known status name of the other item
- `createdByName` (string): Name of who started the handoff
- `createdByRef` (string): E-mail of who started the handoff
- `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
- `nextAttemptAt` (string (date-time)): Next delivery attempt while pending
- `projectId` (string (uuid)): Project of the forge item
- `returnNote` (string): Note given when the item was handed back
- `returnedAt` (string (date-time)): When it was handed back
- `returnedByName` (string): Name of who handed it back
- `returnedByRef` (string): E-mail of who handed it back
- `updatedAt` (string (date-time)): Last change of this side
- `version` (integer): Version of this row

Example 200 answer:

```json
{
  "attempts": 0,
  "counterpartCheckedAt": "2026-11-12T11:00:05Z",
  "counterpartContainerId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "counterpartContainerKey": "SUP",
  "counterpartItemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c38",
  "counterpartModule": "desk",
  "counterpartRef": "#38",
  "counterpartStage": "active",
  "counterpartStatusKey": "in_bearbeitung",
  "counterpartStatusName": "In Bearbeitung",
  "createdAt": "2026-11-11T14:30:00Z",
  "createdByName": "Elias Gruber",
  "createdByRef": "elias.gruber@muster-it.example",
  "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b02",
  "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c19",
  "kind": "handoff",
  "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "returnNote": "Kein Fehler und vorerst keine Funktion der App: Den PDF-Export der Ticketliste gibt es im Kundenportal im Browser (Tickets → Exportieren).",
  "returnedAt": "2026-11-12T11:00:00Z",
  "returnedByName": "Emma Maier",
  "returnedByRef": "emma.maier@muster-it.example",
  "role": "receiver",
  "state": "handed_back",
  "syncState": "confirmed",
  "updatedAt": "2026-11-12T11:00:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/handoffs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/return' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Kein Fehler und vorerst keine Funktion der App: Den PDF-Export der Ticketliste gibt es im Kundenportal im Browser (Tickets → Exportieren)."}'
```

## Convert an item into another project or a desk ticket (tenant:forge:write and, as a member, at least developer)

`POST /api/forge/v1/projects/{key}/items/{number}/convert`

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

Requires the permission to change the item (forge write; CanEditItem), header `Idempotency-Key` and the item's `version`. `target.module` forge: the move to another project (`POST …/move`, 200 with the moved item and `dropped`). `target.module` desk: an internal desk ticket in the space `target.container` with title, description, type and status (by key, else the stage), custom fields by key, labels, dates, assignees, watchers, the reporter, the comments (author, kind, time), the attachments (the same DMS documents), the links and sections listed in desk's note and `confidential` (A2). While desk has not confirmed, the item is read-only (409 `conversion_pending`, 202 with the pending row); once confirmed (201) the item stays as a read-only tombstone: first cancelled status, resolution `converted`, `convertedTo {module, id, ref, path, at}`, left out of lists, boards and metrics, every write 409 `converted`; history `converted`, event `forge.handoff.sent`. Refusals and failures as for handoffs (422 `handoff_refused`, 24 h). 409 `has_children`, `version_conflict`, `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes | (max length 200) |
| `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)

- `target` (HandoffTargetRef, required)
  - `container` (string, required): Desk space key or forge project key
  - `module` (string, required): Target module (one of `desk`, `forge`)
  - `statusKey` (string): Status of the new item; default the first status of the stage
  - `typeKey` (string): Item type (forge) or ticket type (desk) of the new item; default the target's default
- `version` (integer, required): Version of the item the caller saw (409 `version_conflict` when it changed)

Example:

```json
{
  "target": {
    "container": "SUP",
    "module": "desk",
    "typeKey": "serviceanfrage"
  },
  "version": 3
}
```

### Responses

- **200** Moved within forge (`application/json`)
- **201** Converted (the item is the tombstone) (`application/json`)
- **202** Pending (desk not reached yet) (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `dropped` (array of string): What the target did not take over (a move: `label:<name>`, …; a forge handoff: the priority)
- `handoff` (Handoff)
  - `counterpartModule` (string, required): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string, required): Reference of the item on the other side (#123 or APP-12)
  - `counterpartStage` (string, required): Last known stage of the other item; `gone` when it no longer exists (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `createdAt` (string (date-time), required): When the handoff was started
  - `id` (string (uuid), required): Handoff id, shared with the other side
  - `itemId` (string (uuid), required): The forge item of this side
  - `kind` (string, required): `handoff`: a new linked item; `conversion`: the item moved and left a tombstone (one of `handoff`, `conversion`)
  - `role` (string, required): Which side this row is: the origin (handed over) or the receiver (one of `origin`, `receiver`)
  - `state` (string, required): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string, required): Delivery to the other side: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last checked
  - `counterpartContainerId` (string): Desk space or forge project id of the other side (once known)
  - `counterpartContainerKey` (string): Desk space key or forge project key of the other side
  - `counterpartItemId` (string): Id of the item on the other side (once known)
  - `counterpartStatusKey` (string): Last known status key of the other item
  - `counterpartStatusName` (string): Last known status name of the other item
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): E-mail of who started the handoff
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): Next delivery attempt while pending
  - `projectId` (string (uuid)): Project of the forge item
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When it was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): E-mail of who handed it back
  - `updatedAt` (string (date-time)): Last change of this side
  - `version` (integer): Version of this row
- `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 201 answer:

```json
{
  "handoff": {
    "attempts": 1,
    "counterpartContainerId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
    "counterpartContainerKey": "SUP",
    "counterpartItemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c4a",
    "counterpartModule": "desk",
    "counterpartRef": "#74",
    "counterpartStage": "new",
    "counterpartStatusKey": "neu",
    "counterpartStatusName": "Neu",
    "createdAt": "2026-11-16T09:45:00Z",
    "createdByName": "Emma Maier",
    "createdByRef": "emma.maier@muster-it.example",
    "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b04",
    "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c17",
    "kind": "conversion",
    "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "role": "origin",
    "state": "converted",
    "syncState": "confirmed",
    "updatedAt": "2026-11-16T09:45:02Z",
    "version": 2
  },
  "item": {
    "assignees": [],
    "closedAt": "2026-11-16T09:45:02Z",
    "convertedTo": {
      "at": "2026-11-16T09:45:02Z",
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c4a",
      "module": "desk",
      "path": "/desk/tickets/74",
      "ref": "#74"
    },
    "createdAt": "2026-11-13T08:30:00Z",
    "customFields": {},
    "description": "Zugang zur Kundenportal-App für eine neue Mitarbeiterin einrichten.",
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c17",
    "labelIds": [],
    "labels": [],
    "number": 23,
    "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "projectKey": "APP",
    "rank": "0000e0",
    "ref": "APP-23",
    "reporterRef": "emma.maier@muster-it.example",
    "resolution": "converted",
    "statusCategory": "cancelled",
    "statusId": "5d1e2f3a-4b5c-4d6e-8f7a-1b2c3d4e5f06",
    "statusKey": "verworfen",
    "statusName": "Verworfen",
    "title": "App-Zugang für neue Mitarbeiterin im Sekretariat",
    "typeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
    "typeKey": "aufgabe",
    "updatedAt": "2026-11-16T09:45:02Z",
    "version": 4,
    "watchers": [
      "emma.maier@muster-it.example"
    ]
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/convert' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"target":{"container":"SUP","module":"desk","typeKey":"serviceanfrage"},"version":3}'
```

# Attachments

## List the files of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/attachments`

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

Requires `tenant:forge:read` and an item the caller sees. Oldest first; `source` upload or conversion (a file of the source item, the same DMS document).

### 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) |

### Responses

- **200** Files (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Attachment, required)
  - `createdAt` (string (date-time), required): When the file was added
  - `id` (string (uuid), required): Attachment id
  - `itemId` (string (uuid), required): The item the file belongs to
  - `mime` (string, required): MIME type
  - `name` (string, required): File name
  - `size` (integer, required): Size in bytes
  - `source` (string, required): `upload`: uploaded to the item; `conversion`: taken over by a conversion (one of `upload`, `conversion`)
  - `uploadedByRef` (string, required): E-mail of who uploaded it
  - `commentId` (string (uuid), nullable): The comment the file came with (conversions)

Example 200 answer:

```json
{
  "items": [
    {
      "commentId": null,
      "createdAt": "2026-11-06T08:45:00Z",
      "id": "5b6c7d8e-9f0a-4b1c-8d2e-4f5a6b7c8d01",
      "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c11",
      "mime": "application/pdf",
      "name": "Absturzbericht_iOS_17.pdf",
      "size": 48213,
      "source": "upload",
      "uploadedByRef": "ben.koch@muster-it.example"
    },
    {
      "commentId": null,
      "createdAt": "2026-11-06T08:44:00Z",
      "id": "5b6c7d8e-9f0a-4b1c-8d2e-4f5a6b7c8d02",
      "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c11",
      "mime": "image/png",
      "name": "Absturz_PDF_Anhang_iOS.png",
      "size": 182334,
      "source": "upload",
      "uploadedByRef": "ben.koch@muster-it.example"
    }
  ]
}
```

### Example request

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

## Upload a file to an item (tenant:forge:write, or any member role in the project)

`POST /api/forge/v1/projects/{key}/items/{number}/attachments`

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

Requires the permission to comment (`tenant:forge:write`, or any project membership). Multipart field `file` (at most 25 MB). The file is stored in DMS as a forge document and scanned for malware there. 503 `unavailable` when DMS is not configured; 413 `too_large`; a tombstone 409 `converted`. Writes `forge.item.attachment_added`.

### 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

`multipart/form-data` (required)

- `file` (string (binary), required)

### Responses

- **201** Stored (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **413** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time), required): When the file was added
- `id` (string (uuid), required): Attachment id
- `itemId` (string (uuid), required): The item the file belongs to
- `mime` (string, required): MIME type
- `name` (string, required): File name
- `size` (integer, required): Size in bytes
- `source` (string, required): `upload`: uploaded to the item; `conversion`: taken over by a conversion (one of `upload`, `conversion`)
- `uploadedByRef` (string, required): E-mail of who uploaded it
- `commentId` (string (uuid), nullable): The comment the file came with (conversions)

Example 201 answer:

```json
{
  "commentId": null,
  "createdAt": "2026-11-06T08:45:00Z",
  "id": "5b6c7d8e-9f0a-4b1c-8d2e-4f5a6b7c8d01",
  "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c11",
  "mime": "application/pdf",
  "name": "Absturzbericht_iOS_17.pdf",
  "size": 48213,
  "source": "upload",
  "uploadedByRef": "ben.koch@muster-it.example"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/attachments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```

## Download a file of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/attachments/{id}`

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

Requires `tenant:forge:read` and an item the caller sees. Only files DMS' malware scan found clean are served; infected or unscanned files are 403 (`infected`, `not_scanned`), a running scan 409 `scan_pending`. 503 when DMS is not configured.

### 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) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The file (`application/octet-stream`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/attachments/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Remove a file from an item (its uploader with comment rights, or tenant:forge:write and, as a member, at least developer)

`DELETE /api/forge/v1/projects/{key}/items/{number}/attachments/{id}`

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

The uploader (with the permission to comment) or who may edit the item. Removes the file from the item; an uploaded file's DMS document that no other item links is deleted once DMS' retention (30 days after upload) ends. Writes `forge.item.attachment_removed`.

### 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) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Removed
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/attachments/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Comments

## List the comments of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/comments`

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

Requires `tenant:forge:read` and a project the caller sees. Thread order, paged by keyset (`limit` 1–500, default 200; follow `nextCursor`); deleted comments keep their place with an empty body and `deletedAt`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | 1–500; another value is a 400 invalid. (default `200`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page. |
| `key` | path | string | yes | Project key (e.g. APP) |
| `number` | path | integer | yes | Item number in the project (12 of APP-12) |

### Responses

- **200** A page of comments (keyset, `nextCursor` while more follow) (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Comment, required)
  - `authorKind` (string, required): Kind of actor that wrote it (one of `person`, `integration`, `assistant`, `system`, `automation`)
  - `authorName` (string, required): Display name of the author
  - `authorRef` (string, required): E-mail (or actor ref) of the author
  - `body` (string, required): Markdown
  - `createdAt` (string (date-time), required): When the comment was written
  - `id` (string (uuid), required): Comment id
  - `itemId` (string (uuid), required): The item commented on
  - `deletedAt` (string (date-time), nullable): When it was deleted (the body is then empty); null otherwise
  - `editedAt` (string (date-time), nullable): Last edit; null when never edited
  - `originRef` (string): Comments imported by a conversion: the source item, e.g. #123
  - `originVisibility` (string): Comments imported by a conversion: the visibility on the source side (one of `public`, `internal`)
- `nextCursor` (string)

Example 200 answer:

```json
{
  "items": [
    {
      "authorKind": "person",
      "authorName": "Emma Maier",
      "authorRef": "emma.maier@muster-it.example",
      "body": "Zwei Anmerkungen im Pull Request, vor allem der Fokus beim Schließen des Bottom-Sheets.",
      "createdAt": "2026-11-17T09:20:00Z",
      "deletedAt": null,
      "editedAt": null,
      "id": "4a5b6c7d-8e9f-4a0b-9c1d-3e4f5a6b7c01",
      "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06"
    }
  ]
}
```

### Example request

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

## Comment on an item (tenant:forge:write, or any member role in the project)

`POST /api/forge/v1/projects/{key}/items/{number}/comments`

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

Requires `tenant:forge:write`, or any project membership. A person who comments starts watching the item. Writes `forge.item.commented`.

### 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)

- `body` (string, required): Comment text (Markdown) (max length 20000)

Example:

```json
{
  "body": "Zwei Anmerkungen im Pull Request, vor allem der Fokus beim Schließen des Bottom-Sheets."
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `authorKind` (string, required): Kind of actor that wrote it (one of `person`, `integration`, `assistant`, `system`, `automation`)
- `authorName` (string, required): Display name of the author
- `authorRef` (string, required): E-mail (or actor ref) of the author
- `body` (string, required): Markdown
- `createdAt` (string (date-time), required): When the comment was written
- `id` (string (uuid), required): Comment id
- `itemId` (string (uuid), required): The item commented on
- `deletedAt` (string (date-time), nullable): When it was deleted (the body is then empty); null otherwise
- `editedAt` (string (date-time), nullable): Last edit; null when never edited
- `originRef` (string): Comments imported by a conversion: the source item, e.g. #123
- `originVisibility` (string): Comments imported by a conversion: the visibility on the source side (one of `public`, `internal`)

Example 201 answer:

```json
{
  "authorKind": "person",
  "authorName": "Emma Maier",
  "authorRef": "emma.maier@muster-it.example",
  "body": "Zwei Anmerkungen im Pull Request, vor allem der Fokus beim Schließen des Bottom-Sheets.",
  "createdAt": "2026-11-17T09:20:00Z",
  "deletedAt": null,
  "editedAt": null,
  "id": "4a5b6c7d-8e9f-4a0b-9c1d-3e4f5a6b7c01",
  "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/comments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Zwei Anmerkungen im Pull Request, vor allem der Fokus beim Schließen des Bottom-Sheets."}'
```

## Delete a comment (one's own with comment rights; anyone's tenant:forge:write and maintainer, or tenant:forge:admin)

`DELETE /api/forge/v1/projects/{key}/items/{number}/comments/{id}`

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

The author (with the permission to comment), or `tenant:forge:admin` / `tenant:forge:write` with project role maintainer or admin for any comment. Soft delete. Writes `forge.item.comment_deleted`.

### 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) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/comments/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Edit one's own comment (its author, with comment rights: tenant:forge:write, or any member role in the project)

`PATCH /api/forge/v1/projects/{key}/items/{number}/comments/{id}`

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

Requires the permission to comment; only the author edits. Writes `forge.item.comment_edited`.

### 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) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `body` (string, required): Comment text (Markdown) (max length 20000)

Example:

```json
{
  "body": "Zwei Anmerkungen im Pull Request, vor allem der Fokus beim Schließen des Bottom-Sheets. Sonst sieht es gut aus."
}
```

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

- `authorKind` (string, required): Kind of actor that wrote it (one of `person`, `integration`, `assistant`, `system`, `automation`)
- `authorName` (string, required): Display name of the author
- `authorRef` (string, required): E-mail (or actor ref) of the author
- `body` (string, required): Markdown
- `createdAt` (string (date-time), required): When the comment was written
- `id` (string (uuid), required): Comment id
- `itemId` (string (uuid), required): The item commented on
- `deletedAt` (string (date-time), nullable): When it was deleted (the body is then empty); null otherwise
- `editedAt` (string (date-time), nullable): Last edit; null when never edited
- `originRef` (string): Comments imported by a conversion: the source item, e.g. #123
- `originVisibility` (string): Comments imported by a conversion: the visibility on the source side (one of `public`, `internal`)

Example 200 answer:

```json
{
  "authorKind": "person",
  "authorName": "Emma Maier",
  "authorRef": "emma.maier@muster-it.example",
  "body": "Zwei Anmerkungen im Pull Request, vor allem der Fokus beim Schließen des Bottom-Sheets.",
  "createdAt": "2026-11-17T09:20:00Z",
  "deletedAt": null,
  "editedAt": null,
  "id": "4a5b6c7d-8e9f-4a0b-9c1d-3e4f5a6b7c01",
  "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/comments/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Zwei Anmerkungen im Pull Request, vor allem der Fokus beim Schließen des Bottom-Sheets. Sonst sieht es gut aus."}'
```

# Sections

## List the sections of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/sections`

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

Requires `tenant:forge:read` and a project the caller sees. The sections of the item's type in order; `version` 0 = never written.

### 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) |

### Responses

- **200** Sections (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Section, required)
  - `body` (string, required): Markdown (checklist: a task list)
  - `key` (string, required): Section key
  - `kind` (string, required): markdown or checklist (one of `markdown`, `checklist`)
  - `label` (string, required): Display label
  - `placement` (string, required): Where the portal shows it: a tab or the side column (one of `tab`, `aside`)
  - `version` (integer, required): 0 = never written
  - `updatedAt` (string (date-time), nullable): When the current version was written; null when never written
  - `updatedByKind` (string): Kind of actor who wrote it
  - `updatedByName` (string): Name of who wrote it
  - `updatedByRef` (string): E-mail (or actor ref) of who wrote the current version

Example 200 answer:

```json
{
  "items": [
    {
      "body": "Die Komponente bekommt ihre Optionen über Props und meldet Änderungen als Ereignis.",
      "key": "plan",
      "kind": "markdown",
      "label": "Plan",
      "placement": "tab",
      "updatedAt": "2026-11-04T09:15:00Z",
      "updatedByKind": "person",
      "updatedByName": "Marie Wagner",
      "updatedByRef": "marie.wagner@muster-it.example",
      "version": 1
    },
    {
      "body": "",
      "key": "agent_notes",
      "kind": "markdown",
      "label": "Notizen für Agenten",
      "placement": "tab",
      "updatedAt": null,
      "version": 0
    },
    {
      "body": "",
      "key": "acceptance",
      "kind": "checklist",
      "label": "Akzeptanzkriterien",
      "placement": "tab",
      "updatedAt": null,
      "version": 0
    }
  ]
}
```

### Example request

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

## Write a section of an item (tenant:forge:write and, as a member, at least developer)

`PUT /api/forge/v1/projects/{key}/items/{number}/sections/{section}`

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

Same permission as changing an item. Integrations (API keys) and the assistant may write every section; a section not defined for the item's type is 404. `version` is the version the text was based on (0 for a new section; else 409 `version_conflict`). Every write is a revision. Writes `forge.item.section_updated`.

### 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) |
| `section` | path | string | yes | Section definition key (e.g. plan) |

### Request body

`application/json` (required)

- `body` (string, required): New content (Markdown; checklist: a task list) (max length 100000)
- `version` (integer, required): The version the text was based on (0 for a section never written); 409 `version_conflict` otherwise

Example:

```json
{
  "body": "Die Komponente bekommt ihre Optionen über Props und meldet Änderungen als Ereignis. Der Zeitraum nutzt\nden Datumsdialog des Betriebssystems, damit wir keine eigene Kalender-Ansicht bauen müssen.",
  "version": 1
}
```

### Responses

- **200** Written (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `body` (string, required): Markdown (checklist: a task list)
- `key` (string, required): Section key
- `kind` (string, required): markdown or checklist (one of `markdown`, `checklist`)
- `label` (string, required): Display label
- `placement` (string, required): Where the portal shows it: a tab or the side column (one of `tab`, `aside`)
- `version` (integer, required): 0 = never written
- `updatedAt` (string (date-time), nullable): When the current version was written; null when never written
- `updatedByKind` (string): Kind of actor who wrote it
- `updatedByName` (string): Name of who wrote it
- `updatedByRef` (string): E-mail (or actor ref) of who wrote the current version

Example 200 answer:

```json
{
  "body": "Die Komponente bekommt ihre Optionen über Props und meldet Änderungen als Ereignis. Der Zeitraum nutzt\nden Datumsdialog des Betriebssystems, damit wir keine eigene Kalender-Ansicht bauen müssen.",
  "key": "plan",
  "kind": "markdown",
  "label": "Plan",
  "placement": "tab",
  "updatedAt": "2026-11-18T09:40:00Z",
  "updatedByKind": "person",
  "updatedByName": "Marie Wagner",
  "updatedByRef": "marie.wagner@muster-it.example",
  "version": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/sections/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Die Komponente bekommt ihre Optionen über Props und meldet Änderungen als Ereignis. Der Zeitraum nutzt\nden Datumsdialog des Betriebssystems, damit wir keine eigene Kalender-Ansicht bauen müssen.","version":1}'
```

## List the revisions of a section (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/sections/{section}/revisions`

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

Requires `tenant:forge:read` and a project the caller sees. Newest first, without content; paged by keyset (follow `nextCursor`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | Rows per page (default 200) (default `200`; max 500) |
| `cursor` | query | string |  | `nextCursor` of the previous page |
| `key` | path | string | yes | Project key (e.g. APP) |
| `number` | path | integer | yes | Item number in the project (12 of APP-12) |
| `section` | path | string | yes | Section definition key (e.g. plan) |

### Responses

- **200** Revisions (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of SectionRevision, required)
  - `authorKind` (string, required): Kind of actor who wrote it
  - `authorName` (string, required): Name of who wrote it
  - `authorRef` (string, required): E-mail (or actor ref) of who wrote it
  - `createdAt` (string (date-time), required): When it was written
  - `version` (integer, required): Version number of the section text
  - `body` (string): Only when one revision is read
- `nextCursor` (string): Cursor of the next page (pass it as `cursor`); missing on the last page.

Example 200 answer:

```json
{
  "items": [
    {
      "authorKind": "person",
      "authorName": "Marie Wagner",
      "authorRef": "marie.wagner@muster-it.example",
      "createdAt": "2026-11-18T09:40:00Z",
      "version": 2
    },
    {
      "authorKind": "person",
      "authorName": "Marie Wagner",
      "authorRef": "marie.wagner@muster-it.example",
      "createdAt": "2026-11-04T09:15:00Z",
      "version": 1
    }
  ]
}
```

### Example request

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

## Get one revision of a section (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/sections/{section}/revisions/{version}`

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

Requires `tenant:forge:read` and a project the caller sees.

### 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) |
| `section` | path | string | yes | Section definition key (e.g. plan) |
| `version` | path | integer | yes |  |

### Responses

- **200** Revision (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `authorKind` (string, required): Kind of actor who wrote it
- `authorName` (string, required): Name of who wrote it
- `authorRef` (string, required): E-mail (or actor ref) of who wrote it
- `createdAt` (string (date-time), required): When it was written
- `version` (integer, required): Version number of the section text
- `body` (string): Only when one revision is read

Example 200 answer:

```json
{
  "authorKind": "person",
  "authorName": "Marie Wagner",
  "authorRef": "marie.wagner@muster-it.example",
  "body": "Die Komponente bekommt ihre Optionen über Props und meldet Änderungen als Ereignis.",
  "createdAt": "2026-11-04T09:15:00Z",
  "version": 1
}
```

### Example request

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

# Agent

## Planning agent of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/agent`

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

Requires `tenant:forge:read` and edit rights on the item. Answers whether the caller can use the planning
agent (ADR 0028) on the item now (`status`) and the caller's own conversations about it, latest activity first.
A hidden item answers `404`, a visible one the caller may not edit `403`.

### 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) |

### Responses

- **200** Agent panel (`application/json`)
- **401** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `conversations` (array of AgentConversation, required): The caller's own conversations about the item, latest activity first
  - `createdAt` (string (date-time)): When the conversation was started
  - `credentialId` (string): The tenant model credential the conversation runs on
  - `id` (string (uuid)): Conversation id
  - `itemId` (string): The item the conversation is about
  - `lastActivity` (string (date-time)): Last message, run or decision in the conversation
  - `model` (string): The model the conversation runs on
  - `ownerRef` (string): E-mail of the person who started it (only they see it)
  - `projectId` (string): Project of the item
  - `title` (string): Short title taken from the first message
  - `updatedAt` (string (date-time)): Last change of the conversation row
- `status` (AgentStatus, required)
  - `canUse` (boolean, required): The caller can start the planning agent on the item now
  - `enabled` (boolean, required): The project switched the agent on
  - `models` (array of AgentModel, required): The tenant's usable models (bring your own key)
    - `credentialId` (string): Id of the tenant credential (bring your own key)
    - `credentialName` (string): Name of the credential as the tenant set it
    - `label` (string): Display name of the model
    - `model` (string): Model id
    - `provider` (string): Provider of the credential
  - `budget` (object): The tenant's agent token budget of the month (missing when it could not be read)
    - `capReached` (boolean): The cap is reached; no new run starts
    - `capTokens` (integer): The tenant's monthly token cap
    - `usedTokens` (integer): Tokens used this month
  - `reason` (string): Why `canUse` is false (one of `disabled`, `no_credentials`, `cap_reached`, `unavailable`)

Example 200 answer:

```json
{
  "conversations": [
    {
      "createdAt": "2026-11-17T14:02:00Z",
      "credentialId": "6f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b01",
      "id": "7d8e9f0a-1b2c-4d3e-8f4a-6b7c8d9e0f01",
      "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06",
      "lastActivity": "2026-11-17T14:06:00Z",
      "model": "claude-sonnet-4-5",
      "ownerRef": "marie.wagner@muster-it.example",
      "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "title": "Akzeptanzkriterien für die Filterleiste",
      "updatedAt": "2026-11-17T14:06:00Z"
    }
  ],
  "status": {
    "budget": {
      "capReached": false,
      "capTokens": 5000000,
      "usedTokens": 1284000
    },
    "canUse": true,
    "enabled": true,
    "models": [
      {
        "credentialId": "6f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b01",
        "credentialName": "Anthropic Muster IT",
        "label": "Claude Sonnet 4.5",
        "model": "claude-sonnet-4-5",
        "provider": "anthropic"
      }
    ]
  }
}
```

### Example request

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

## Switch the planning agent of a project on or off and set its language (tenant:forge:write and maintainer, or tenant:forge:admin)

`PUT /api/forge/v1/projects/{key}/agent-settings`

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

Requires `tenant:forge:write` or `admin` and the project role that may configure the project. `language` is the
language the agent writes in (answers, drafts, questions), whatever language the item or the prompt is in; without
it the stored language stays (`de` when none is stored). Emits `forge.config.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `enabled` (boolean, required): The planning agent is switched on for the project
- `language` (string): Language the agent writes in (one of `de`, `en`; default `"de"`)

Example:

```json
{
  "enabled": true,
  "language": "de"
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `enabled` (boolean, required): The planning agent is switched on for the project
- `language` (string): Language the agent writes in (one of `de`, `en`; default `"de"`)

Example 200 answer:

```json
{
  "enabled": true,
  "language": "de"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/forge/v1/projects/string/agent-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"enabled":true,"language":"de"}'
```

