> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sublay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload File

> Upload a generic file without server-side processing

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 keys** may name a
different user. Omit for a backend/project-owned file (no owning user).

## Response

```json theme={null}
{
  "fileId": "uuid",
  "type": "document",
  "relativePath": "documents/user-123/uuid/report.pdf",
  "publicPath": "/internal/files/documents/user-123/uuid/report.pdf",
  "size": 102400,
  "mimeType": "application/pdf",
  "createdAt": "2025-01-01T00:00:00.000Z"
}
```

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

## Error Responses

> [accordion] No File — 400 Bad Request
>
> ```json theme={null}
> { "error": "No file provided", "code": "storage/no-file" }
> ```

> [accordion] File Too Large — 413
>
> ```json theme={null}
> { "error": "File size exceeds the allowed limit of 50MB", "code": "storage/file-too-large" }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.