File and Folder Endpoints

File and Folder Endpoints

Files

All file endpoints are under /api/v1/clients/:client_id/files.

GET /api/v1/clients/:client_id/files

List files for a client in a given folder.

Query parameters:

• folder_id (optional): Parent folder ID (root if omitted)
• page (optional): Page number (default: 1)
• per_page (optional): Items per page (default: 50)

Response:

{
  "files": [
    {
      "id": "uuid",
      "name": "document.pdf",
      "size": 1048576,
      "mime_type": "application/pdf",
      "folder_id": "uuid",
      "encryption_type": "client",
      "uses_custom_key": true,
      "created_at": "2026-02-14T00:00:00Z",
      "updated_at": "2026-02-14T00:00:00Z"
    }
  ],
  "total": 10,
  "page": 1,
  "per_page": 50
}

POST /api/v1/clients/:client_id/files

Upload a file (multipart/form-data).

Body (form-data):

• file: The binary file
• folder_id: Destination folder ID
• encrypted_key (optional): RSA-encrypted DEK (for E2E)
• key_version (optional): RSA key version used
• metadata (optional): Encryption metadata (JSON)
• original_checksum (optional): SHA-256 of original file

Limit: 25 MB (configurable via MAX_BODY_SIZE override on the upload route)

GET /api/v1/clients/:client_id/files/:file_id

Retrieve file metadata.

GET /api/v1/clients/:client_id/files/:file_id/download

Download a file. If server-side encrypted, the file is decrypted before sending. If client-side encrypted (uses_custom_key=true), the encrypted file is returned as-is with encryption metadata in response headers.

GET /api/v1/clients/:client_id/files/:file_id/preview

Preview a file (for supported types).

POST /api/v1/clients/:client_id/files/:file_id/copy

Copy a file to another location.

PATCH /api/v1/clients/:client_id/files/:file_id/rename

Rename a file.

{
  "name": "new-filename.pdf"
}

PATCH /api/v1/clients/:client_id/files/:file_id/move

Move a file to another folder.

{
  "target_folder_id": "uuid"
}

DELETE /api/v1/clients/:client_id/files/:file_id

Delete a file (S3 + PostgreSQL metadata).

GET /api/v1/clients/:client_id/files/search

Search files by name.

Query parameters:

• q: Search query

Folders

All folder endpoints are under /api/v1/clients/:client_id/folders.

GET /api/v1/clients/:client_id/folders

List folders for a client.

Query parameters:

• parent_id (optional): Parent folder ID (root if omitted)

Response:

{
  "folders": [
    {
      "id": "uuid",
      "name": "Documents",
      "parent_id": null,
      "is_system": false,
      "created_at": "2026-02-14T00:00:00Z"
    }
  ]
}

POST /api/v1/clients/:client_id/folders

Create a new folder.

{
  "name": "New Folder",
  "parent_id": "uuid"
}

GET /api/v1/clients/:client_id/folders/tree

Get the complete folder tree structure.

GET /api/v1/clients/:client_id/folders/:folder_id

Get folder details.

GET /api/v1/clients/:client_id/folders/:folder_id/contents

Get folder contents (files and subfolders).

PATCH /api/v1/clients/:client_id/folders/:folder_id/rename

Rename a folder.

{
  "name": "Renamed Folder"
}

PATCH /api/v1/clients/:client_id/folders/:folder_id/move

Move a folder.

{
  "target_parent_id": "uuid"
}

DELETE /api/v1/clients/:client_id/folders/:folder_id

Delete a folder and all its contents (recursive).