## Upload a file to the ticket, within the tenant's mail limits (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/attachments`

Module: Desk · operationId: `createItemAttachment` · Tag: Mail · Auth: access token (`Authorization: Bearer <accessToken>`)

The file is stored in DMS and scanned for malware afterwards: until the scan cleared it, its content answers `409 scan_pending`, a file the scan found something in `403 infected`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`multipart/form-data` (required)

- `file` (string (binary), required)

### Responses

- **201** The stored file (`application/json`)
- **400** No multipart `file` part, no usable file name, or the file breaks the tenant's mail limits (size, blocked type) – code invalid, field file (`application/json`)
- **403** No desk:write, or not at least the agent role in the ticket's space (code forbidden) (`application/json`)
- **404** No such ticket, or one the caller does not see (`application/json`)
- **503** The file store is not configured (code unavailable) (`application/json`)

Fields of the 201 answer:

- `contentId` (string): Content-ID of an inline image
- `createdAt` (string (date-time)): When the file was added
- `documentId` (string): DMS document holding the file
- `entryId` (string): Entry (mail or comment) the file came with
- `id` (string): Id of the file record
- `inline` (boolean): An inline image of a mail body
- `itemId` (string): Item the file belongs to
- `mime` (string): MIME type
- `name` (string): File name
- `portalVisible` (boolean): Requesters see the file in the customer portal
- `size` (integer): Size in bytes
- `source` (string): mail: attachment of a mail; upload: staff upload; portal: requester upload; conversion: brought along by a conversion; eml: the original (.eml) of a received or sent mail (entryId set, never visible to requesters, never handed to forge); generated: made by desk (meeting transcripts) (one of `mail`, `upload`, `portal`, `conversion`, `eml`, `generated`)
- `uploadedBy` (string): Login (e-mail) of who uploaded it

Example 201 answer:

```json
{
  "contentId": "",
  "createdAt": "2026-11-17T08:41:00Z",
  "documentId": "3d0e1f2a-4b5c-4d6e-9f8a-0b1c2d3e4f01",
  "entryId": "",
  "id": "2c9d0e1f-3a4b-4c5d-8e7f-9a0b1c2d3e01",
  "inline": false,
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "mime": "text/plain",
  "name": "Controller-Log_AP-207.txt",
  "portalVisible": false,
  "size": 18233,
  "source": "upload",
  "uploadedBy": "lukas.wimmer@muster-it.example"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/attachments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```
