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