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