Files

Upload, list, download, preview, and delete files in org and project storage.

Files are stored in object storage and indexed in PostgreSQL. Each file lives in a folder (parentId) and may be attached to a project. Two upload modes are supported: a JSON pre-signed URL flow and a direct multipart upload. Soft-deleted files are removed from listings; their object-storage blobs are deleted only when no other file references the same storageKey.

Endpoints

Method	Path	Description
`GET`	`/api/v1/files`	List files in a folder or project.
`POST`	`/api/v1/files`	Upload a file, create a folder, or create a link to an existing file.
`GET`	`/api/v1/files/:id`	File metadata, signed download URL, or inline stream.
`PATCH`	`/api/v1/files/:id`	Rename, move, or retag a file.
`DELETE`	`/api/v1/files/:id`	Soft-delete a file or folder.
`GET`	`/api/v1/files/:id/preview`	Server-rendered preview for supported types.

Maximum upload size is 100 MB. Allowed MIME types are gated by the platform's stored-file allowlist.

List files

GET /api/v1/files

Query	Type	Description
`limit`	number	1–100, default 50.
`page`	number	1-based, default 1.
`search`	string	Case-insensitive name match.
`parentId`	string	Folder ID. Defaults to the org root.
`projectId`	string	When set, scopes listing under the project's protected folder.

Response:

{
  "success": true,
  "data": {
    "items": [ { "id": "uuid", "name": "...", "mimeType": "...", "size": 123, "..." } ],
    "page": 1,
    "limit": 50
  }
}

Upload (JSON, pre-signed URL)

POST /api/v1/files with Content-Type: application/json.

Field	Type	Required	Description
`name`	string	yes (except for `link` source)	1–255 chars, no NUL/CR/LF.
`mimeType`	string	yes (file uploads)	Must be in the allowed MIME list.
`size`	integer	yes (file uploads)	0 to 100 MB.
`parentId`	string \| null	no	Target folder. Validated to be inside the org root.
`projectId`	string	no	Routes the upload into the project folder.
`source`	`"upload"` \| `"folder"` \| `"link"`	no	Defaults to `upload`.
`targetFileId`	string	only when `source: "link"`	The file this link points to.

Response (201, upload):

{
  "success": true,
  "data": {
    "file": { "id": "uuid", "name": "...", "mimeType": "...", "size": 123, "storageUrl": "..." },
    "uploadUrl": "https://..."
  }
}

PUT the bytes to uploadUrl with the same Content-Type to complete the upload.

When source: "folder", the call only creates a folder record (no uploadUrl). When source: "link", a virtual link is created pointing at targetFileId; folders cannot be linked.

Upload (multipart)

POST /api/v1/files with Content-Type: multipart/form-data. Form fields: file (required), parentId, projectId. The server reads the bytes, validates size and MIME, and stores the object in one step. Returns the file record.

bash

curl -X POST https://alumia.com/api/v1/files \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-F "file=@./report.pdf"

Get / download / preview

GET /api/v1/files/:id — Returns file metadata.

Query	Effect
`download=true`	Redirects (302) to a signed download URL.
`download=true&inline=true`	Streams the bytes inline with a hardened CSP and `Content-Disposition: inline`.

GET /api/v1/files/:id/preview returns a server-rendered preview payload for spreadsheets, documents, and text files (up to 25 MB / 512 KB text cap).

Update

PATCH /api/v1/files/:id

Field	Type	Description
`name`	string	Rename.
`parentId`	string \| null	Move to a different folder (still within org root).
`tags`	string[]	Replace the tag list.

Protected folders cannot be renamed or moved.

Delete

DELETE /api/v1/files/:id soft-deletes the record and, if no other live file references the canonical storageKey, removes the object from storage. Protected folders return 403 FORBIDDEN.

Errors

Code	When
`UNAUTHORIZED`	No valid key.
`BAD_REQUEST`	Missing/oversized `name`, missing `mimeType`, disallowed MIME, oversized file, invalid `parentId`, invalid `targetFileId`, no fields to update.
`FORBIDDEN`	Attempt to rename, move, or delete a protected folder.
`NOT_FOUND`	File or target file missing, soft-deleted, or in another org.

Search docs