ConnectCloud Developers

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:

{
  "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'

View as Markdown · Interactive reference · OpenAPI