Skip to main content
POST
Upload File
Uploads a file directly to storage without processing. Suitable for PDFs, videos, Office documents, and other non-image assets. The file type is inferred automatically from the MIME type. This endpoint accepts multipart/form-data. Requires an authenticated user. Rate limit: 10 requests per 5 minutes.

Body Parameters

file
file
required
The file to upload. Maximum 50 MB.
pathParts
array
required
JSON-encoded array of path segments. The file is stored under the joined path with a UUID sub-folder appended. Example: ["documents", "user-123"]documents/user-123/<uuid>/<filename>.
entityId
string
Associates the file with an entity for cascade deletion.
commentId
string
Associates the file with a comment for cascade deletion.
spaceId
string
Associates the file with a space.
position
number
Display order when a record has multiple attachments. Defaults to 0.
metadata
object
Custom key-value data stored alongside the file record.
userId
string
Attribute the upload to a specific user. With a user token the upload is already attributed to the caller; only service/master keys may name a different user. Omit for a backend/project-owned file (no owning user).

Response

The type field is one of: image, video, document, other. It is inferred from the MIME type.

Error Responses