12 — API Mapping (Files Module)

• 1. Endpoint table
• 2. Detail
  • 2.1 POST /api/v1/files/upload — 201
  • 2.2 GET /api/v1/files — 200
  • 2.3 GET /api/v1/files/:id — 200 / 404
  • 2.4 GET /api/v1/files/:id/download — 200
  • 2.5 DELETE /api/v1/files/:id — 200
• 3. Permission coverage
• 4. Planned / forward-looking endpoints
• 5. Client mapping
• 6. Envelope & errors

Exact backend contract. Conventions (envelope, errors, versioning): 00-shared/07_API_Conventions. Source: files.controller.ts:29-71, files.service.ts, file.schema.ts, src/modules/rbac/permissions.constants.ts:86-88.

1. Endpoint table

2. Detail

2.1 POST /api/v1/files/upload — 201

• Request: multipart/form-data, part file (binary) (files.controller.ts:31-37). Client-supplied: originalname, mimetype, size (used verbatim, files.service.ts:32-33).
• Flow: tenant from TenantContextService.requireTenantId() (files.service.ts:28) → storage.upload({buffer, filename: <uuid>--<originalName>, mimeType, tenantId}) (files.service.ts:29-34) → record create (files.service.ts:36-45).
• Response body: FileRecord — {id, originalName, mimeType, size, storageProvider, storageFileId, storagePath, createdAt, updatedAt}. storageFileId/storagePath are internal; do not expose in UI.
• Errors: 400 (malformed multipart), 401/403 (guards (planned)), 500 (provider).

2.2 GET /api/v1/files — 200

• Query: no params (no pagination/filter; gap). Sorted createdAt: -1 (files.service.ts:48-50). Tenant-scoped + soft-delete filtered via BaseRepository (file.repository.ts:9-15).

2.3 GET /api/v1/files/:id — 200 / 404

• 404 File not found (files.service.ts:54) for unknown or soft-deleted ids.

2.4 GET /api/v1/files/:id/download — 200

• Headers: Content-Type: <mimeType> (files.controller.ts:60); Content-Disposition: attachment; filename="<originalName>" (files.controller.ts:61).
• Body: full bytes (res.send, files.controller.ts:63) — proxied buffer, no redirect, no signed URL, no Range/streaming today.
• Flow: findById → storage.download(storageFileId) (files.service.ts:58-64).

2.5 DELETE /api/v1/files/:id — 200

• Response: { message: 'File deleted' } (files.controller.ts:70).
• Flow: findById (404 if gone) → storage.delete(storageFileId) → repo.softDelete(id) (files.service.ts:66-70). Object hard-deleted; metadata retained (soft).

3. Permission coverage

No file.update/file.share — matching UI (no replace, no share UI).

4. Planned / forward-looking endpoints

5. Client mapping

6. Envelope & errors

• Success/failure envelopes per 00-shared/07_API_Conventions and common/interceptors/response-envelope.interceptor.ts / common/filters/http-exception.filter.ts.
• HTTP statuses above are what the client must handle; 401/403 require guards which are (planned) (AGENTS.md: auth not yet implemented).