File Manager

Overview

The Filemanager module provides a file storage and serving layer for the Oblax platform. It accepts multipart file uploads, stores binary data in S3-compatible object storage, and persists metadata (filename, type, size, directory) in a relational database. Each file record belongs to a project and an owning user, and can be flagged as public or private.

Large files are automatically split into 5 MB chunks for multipart upload. Access to stored files is granted through time-limited presigned URLs. The module exposes a single top-level resource, File, which represents an uploaded blob with its associated metadata.

Before You Start

CLI: Filemanager operations are not yet available through the CLI. Use the SDK or REST API below.
SDK: Import the oblax package in your TypeScript project. Instantiate the filemanager client with new oblax.Filemanager() using your project credentials.
API: All REST endpoints are prefixed with /api/v1/filemanager. Requests require the X-App-Id header and a Bearer Authorization token. –> See: Authentication and Project Setup reference docs.

When to Use

Upload user-generated content such as avatars, documents, or images.
Store and serve PDF reports, CSVs, or other business documents.
Generate temporary download links for private files shared with collaborators.
Organise files into virtual directories like documents, images, videos, avatars, or pdfs.
Toggle file visibility between public (unauthenticated access) and private (presigned URL required).

How It Fits

    flowchart LR
  A[Auth] --> F[Filemanager]
  P[Projects] --> F
  F --> R[Forms]

The Filemanager module authenticates all operations through the Auth module, scopes file directories to the active Project, and provides file ID references used by the Forms module for attachments.

Works Well With

Auth – File operations are scoped to authenticated users and projects. Owner IDs are extracted from the request context.
Forms – File attachments in form submissions can reference uploaded file IDs for retrieval or download.
Projects – Files are organised under a project-scoped directory path, making cleanup and access control straightforward.

Quick Example

The following example uploads a document, retrieves a download link, and then deletes the file.

Uploading a file

Upload a document to a directory. Files can be public or private.

File upload is available through the SDK and REST API.

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { filemanager } from "@oblax/filemanager";

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [filemanager()],
});

const file = await oblax.filemanager.file.create("./report.pdf", {
  directory: "documents",
  public: false,
});

POST /api/v1/filemanager

file: @report.pdf
public: false
directory: documents

Successful response

{
  "id": "fl_abc123def456",
  "original_filename": "report.pdf",
  "filename": "aB3xK9mN2p_report.pdf",
  "path": "documents/project_d8lcac3epc83jq9i2d60/aB3xK9mN2p_report.pdf",
  "dir_path": "documents/project_d8lcac3epc83jq9i2d60",
  "type": "application/pdf",
  "size": 204800,
  "owner_id": "usr_abc123def456"
}

Retrieving a download link

Generate a time-limited presigned URL for secure access to the uploaded file.

File retrieval is available through the SDK and REST API.

GET /api/v1/filemanager/fl_abc123def456/link

Successful response

{
  "url": "https://storage.oblax.io/oblax/documents/project_d8lcac3epc83jq9i2d60/aB3xK9mN2p_report.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=abc123",
  "expiration_time": 1781277681
}

Deleting a file

Remove the file and its metadata.

File deletion is available through the SDK and REST API.

Errors

HTTP Status	Error Code	Description
400	`upload_file_missing`	No file was included in the multipart request.
400	`file_upload_failed`	The upload could not be completed due to a storage error.
400	`validation_failed`	One or more required fields are missing or invalid.
404	`not_found`	No file exists for the given ID.
500	`unable_to_create_object`	The file could not be created on the server.
500	`unable_to_fetch_multiple`	The file list could not be retrieved.
500	`unable_to_delete`	The file could not be deleted.

Best Practices

Use the public flag intentionally. Only mark files public when they need unauthenticated access (e.g. avatars, shared images).
Choose a directory that matches the content type. The allowed directories are documents, images, videos, avatars, and pdfs.
Presigned URLs expire after one hour. Generate them on demand rather than storing them long-term.
Delete files you no longer need to keep storage costs predictable.
For files larger than 5 MB the platform automatically uses multipart upload, so no client-side splitting is required.

Related Modules

Auth, Forms, Projects