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; pass `permanent=true` to purge an already-trashed file from a stepped-up browser session.
`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 Content-Type: application/octet-stream to complete the upload. The validated mimeType remains on the file metadata; use multipart upload when the server should sniff the bytes before storage.

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`	After `assertFileAccessible`, redirects (302) to a short-lived signed object-storage URL.
`download=true&inline=true`	Streams the bytes inline (or redirects for eligible media types) with a hardened CSP and `Content-Disposition: inline`.

Private files are never exposed without org access checks. Signed URLs expire quickly; repeat the API call to refresh. See Troubleshooting for MIME mismatch and presigned finalize failures.

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 keeps the object available for trash restore. Protected folders return 403 FORBIDDEN. DELETE /api/v1/files/:id?permanent=true only works for files already in trash, requires a fresh stepped-up browser session, rejects API keys, and removes the storage object only when no other file references the same canonical storageKey.

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