File Manager

The File Manager module provides presigned URL operations against object storage (S3 / Digital Ocean Spaces) and listing/search utilities. The FileManagerController is mounted at /file-manager. For file uploads, use POST /v1/documents/upload in the document module — that endpoint does the upload server-side, validates MIME + size, and atomically creates a row in the Documents table. File Manager only exposes presigned read/delete operations + storage administration utilities.

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or cookie access_token
Content-Type	application/json
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown field → 400
Related modules	document, users, organizations
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

For file upload use POST /v1/documents/upload (see the document module). File Manager provides operations after the file is in storage: a presigned view URL via GET /file-manager, a presigned delete URL via DELETE /file-manager/:file_key, or a public URL via GET /file-manager/public-url/:file_key. The list, list-all, folders, search, and storage-size endpoints are administrative (require the manage-storage permission).

Method	Path	Auth	Summary
GET	/v1/file-manager	bearer	Get a presigned view URL for a file
DELETE	/v1/file-manager/:file_key	bearer	Get a presigned delete URL
GET	/v1/file-manager/public-url/:file_key	bearer	Get a public URL for a file
GET	/v1/file-manager/list	bearer	List files + folders at one level (admin)
GET	/v1/file-manager/list-all	bearer	List every file recursively (admin)
GET	/v1/file-manager/folders	bearer	List every folder (admin)
GET	/v1/file-manager/search	bearer	Search files by name pattern (admin)
GET	/v1/file-manager/storage-size	bearer	Total storage size (admin)

Auth + scope notes

• All endpoints require Bearer JWT. There is no @Roles on the controller — gating is done via @Permissions.
• Permissions used: read-document (view / public-url), delete-document (delete), manage-storage (list / search / size).
• file_key is the S3 object key (e.g. uploads/2026/05/profile-abc.jpg). Pass it back as-is when calling view/delete/public endpoints.
• For new uploads, use POST /v1/documents/upload — the document module documents that upload flow in full.

---

GET /v1/file-manager bearer

Returns a presigned view URL for a file in object storage. Used when the file is stored privately; the URL has a limited lifetime (service TTL).

bearer read-document RESOURCE_FETCHED

Query params

Param	Type	Required	Notes
file_key	string	✓	Object key returned on upload (e.g. uploads/profile-images/abc-1729-profile.jpg)

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "url to view file fetched successfully",
  "data": {
    "url": "https://moria-bucket.s3.ap-southeast-1.amazonaws.com/uploads/profile-images/abc-1729-profile.jpg?X-Amz-Algorithm=...",
    "file_key": "uploads/profile-images/abc-1729-profile.jpg"
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing read-document permission

---

DELETE /v1/file-manager/:file_key bearer

Returns a presigned delete URL for a file. FE must then call that URL with the DELETE method to actually remove the object from the bucket.

bearer delete-document RESOURCE_DELETED

Path params

Param	Type	Notes
file_key	string	Object key to delete. Since / cannot appear in a single path param, encode subfolders as %2F

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "url to delete file fetched successfully",
  "data": {
    "url": "https://moria-bucket.s3.ap-southeast-1.amazonaws.com/...?X-Amz-Algorithm=...",
    "file_key": "uploads/profile-images/abc-1729-profile.jpg"
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing delete-document permission

---

GET /v1/file-manager/public-url/:file_key bearer

Returns the public URL of a file (no signature). Used for files that are genuinely public (e.g. organization logos, profile pictures). No TTL — the URL is valid as long as the object exists.

bearer read-document RESOURCE_FETCHED

Path params

Param	Type	Notes
file_key	string	File object key (encode / as %2F)

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "public file url file fetched successfully",
  "data": {
    "public_url": "https://moria-bucket.s3.ap-southeast-1.amazonaws.com/uploads/profile-images/abc-1729-profile.jpg",
    "file_key": "uploads/profile-images/abc-1729-profile.jpg"
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing read-document permission

---

GET /v1/file-manager/list bearer

List files and subfolders at a single level inside the bucket. Administrative endpoint — requires the manage-storage permission. Supports limited pagination via maxKeys.

bearer manage-storage RESOURCE_FETCHED

Query params

Param	Type	Default	Notes
prefix	string	—	Folder being opened (e.g. uploads/). Empty → bucket root
maxKeys	number	1000	Maximum number of items returned

Response — 200 OK

{
  "status": "success",
  "data": {
    "files": [
      {
        "key": "uploads/profile-images/abc-1729-profile.jpg",
        "size": 245678,
        "lastModified": "2026-05-20T08:30:00.000Z",
        "etag": "\"abcdef0123456789\"",
        "isFolder": false,
        "publicUrl": "https://moria-bucket.s3.ap-southeast-1.amazonaws.com/uploads/profile-images/abc-1729-profile.jpg"
      }
    ],
    "folders": [
      "uploads/profile-images/",
      "uploads/documents/"
    ],
    "totalCount": 12,
    "isTruncated": false,
    "nextContinuationToken": null
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing manage-storage permission

---

GET /v1/file-manager/list-all bearer

List every file recursively under a given prefix. Administrative endpoint. Use with caution on a large bucket — the service paginates through S3 until exhausted.

bearer manage-storage RESOURCE_FETCHED

Query params

Param	Type	Default	Notes
prefix	string	—	Root folder of the traversal. Empty → every file in the bucket

Response — 200 OK

{
  "status": "success",
  "data": {
    "files": [
      {
        "key": "uploads/profile-images/abc-1729-profile.jpg",
        "size": 245678,
        "lastModified": "2026-05-20T08:30:00.000Z",
        "etag": "\"abcdef0123456789\"",
        "isFolder": false,
        "publicUrl": "https://moria-bucket.s3.ap-southeast-1.amazonaws.com/uploads/profile-images/abc-1729-profile.jpg"
      }
    ],
    "totalCount": 1240
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing manage-storage permission

---

GET /v1/file-manager/folders bearer

List folders at the bucket root. Parameterless administrative endpoint — returns an array of folder name strings and the count.

bearer manage-storage RESOURCE_FETCHED

Response — 200 OK

{
  "status": "success",
  "data": {
    "folders": [
      "uploads/",
      "logos/",
      "documents/"
    ],
    "count": 3
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing manage-storage permission

---

GET /v1/file-manager/search bearer

Search files by name pattern (substring match, case-insensitive). Administrative endpoint. The server runs listAllFiles(prefix) and filters in memory — use prefix to narrow the scope.

bearer manage-storage RESOURCE_FETCHED

Query params

Param	Type	Required	Notes
term	string	✓	Name pattern to search for (e.g. profile). Required — if empty the server returns { status: "error", message: "Search term is required" }
prefix	string	optional	Folder used to scope the search

Response — 200 OK

{
  "status": "success",
  "data": {
    "files": [
      {
        "key": "uploads/profile-images/abc-1729-profile.jpg",
        "size": 245678,
        "lastModified": "2026-05-20T08:30:00.000Z",
        "etag": "\"abcdef0123456789\"",
        "isFolder": false,
        "publicUrl": "https://moria-bucket.s3.ap-southeast-1.amazonaws.com/uploads/profile-images/abc-1729-profile.jpg"
      }
    ],
    "count": 1,
    "searchTerm": "profile"
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing manage-storage permission

---

GET /v1/file-manager/storage-size bearer

Returns total storage size (bytes / MB / GB) and file count under prefix. Administrative endpoint for the capacity dashboard.

bearer manage-storage RESOURCE_FETCHED

Query params

Param	Type	Default	Notes
prefix	string	—	Folder being measured. Empty → the entire bucket (label root)

Response — 200 OK

{
  "status": "success",
  "data": {
    "totalSize": 5368709120,
    "totalSizeMB": "5120.00",
    "totalSizeGB": "5.00",
    "fileCount": 1240,
    "prefix": "uploads/"
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing manage-storage permission

---

Reference

Permission strings used by this module

• read-document — GET view URL, GET public URL
• delete-document — DELETE :file_key
• manage-storage — list / list-all / folders / search / storage-size

FileItem shape

• key — object key in the bucket
• size — size in bytes
• lastModified — ISO 8601 timestamp
• etag — S3 etag (already includes the double-quotes)
• isFolder — boolean
• publicUrl — public URL (if the bucket is public-read)

Standard error envelope

{
  "message": "Forbidden resource",
  "statusCode": 403,
  "error": "Forbidden"
}

message can be a string or an array of strings (multi-field validation errors).

Common HTTP codes

• 400 empty file / missing required parameter
• 401 token expired / missing
• 403 insufficient permission
• 500 S3 / network error — show a generic toast

See also

• The document module — new upload flow (auth-required, MIME validation, atomic Documents row).