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 addedid(string (uuid), required): Attachment iditemId(string (uuid), required): The item the file belongs tomime(string, required): MIME typename(string, required): File namesize(integer, required): Size in bytessource(string, required):upload: uploaded to the item;conversion: taken over by a conversion (one ofupload,conversion)uploadedByRef(string, required): E-mail of who uploaded itcommentId(string (uuid), nullable): The comment the file came with (conversions)
Example 201 answer:
{
"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
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'