Files API

Upload, download, and manage files through the platform's storage layer.

Provider Types: local, s3, minio, google-drive


POST /api/storage/upload-url

Generates a pre-signed upload URL and registers the file in the database. Returns the upload endpoint URL and the file ID.

Auth: None (public endpoint)

Request Body:

{
  "projectId": "uuid",
  "fileName": "screenshot.png",
  "mimeType": "image/png",
  "provider": "local",
  "bucket": "default-bucket",
  "category": "screenshots",
  "uploadedById": "uuid"
}

Response 201:

{
  "url": "/api/storage/upload-raw/{fileId}",
  "fileId": "uuid"
}

PUT /api/storage/upload-raw/:fileId

Uploads the raw file content to the local filesystem. The request body should be the raw binary data. Updates the file size on completion.

Auth: None (public endpoint — uses pre-signed fileId)

Headers:

Content-Type: application/octet-stream

Response 200:

{
  "success": true,
  "size": 1048576
}

POST /api/storage/confirm

Confirms a file upload by updating its size and CDN URL.

Auth: None (public endpoint)

Request Body:

{
  "fileId": "uuid",
  "size": 1048576,
  "cdnUrl": "/api/storage/file/{fileId}"
}

Response 200:

{
  "id": "uuid",
  "size": 1048576,
  "cdnUrl": "/api/storage/file/uuid"
}

POST /api/storage/delete

Soft-deletes a file and removes the physical file from disk. Requires authentication.

Auth: Bearer token

Request Body:

{
  "fileId": "uuid"
}

Response 200:

{ "success": true }

GET /api/storage/file/:id

Downloads a file by its ID. Returns the file with the correct MIME type. No authentication required.

Auth: None

Response 200: Binary file content

Error 404:

{ "error": "File not found" }

GET /api/storage/project/:projectId

Lists all non-deleted files for a project.

Auth: Bearer token

Response 200:

[
  {
    "id": "uuid",
    "projectId": "uuid",
    "provider": "local",
    "bucket": "default-bucket",
    "storageKey": "{projectId}/{fileId}/screenshot.png",
    "originalName": "screenshot.png",
    "mimeType": "image/png",
    "size": 1048576,
    "category": "screenshots",
    "cdnUrl": "/api/storage/file/uuid",
    "createdAt": "2026-07-01T12:00:00.000Z"
  }
]

GET /api/storage/analytics/:projectId

Returns storage analytics for a project.

Auth: Bearer token

Response 200:

{
  "totalBytes": 52428800,
  "count": 12,
  "providerBreakdown": {
    "local": 12
  }
}

Error Codes

Status Error Description
404 File registration not found Pre-registered file ID does not exist
404 File not found File ID not found or was deleted
404 Physical file not found Database record exists but file is missing from disk