List files and folders

Get a list of your files and, when listing a folder, its subfolders. Use the same endpoint to list root contents or the contents of any folder.

Endpoint

Authentication

Required. Include your API key in the Authorization header using the Bearer token format. Create an API key in your dashboard settings.

Request examples

List all your uploaded files with pagination support.

# List all files (first page, 50 per page)

curl https://api.beecargo.net/files/list \
  -H "Authorization: Bearer YOUR_API_KEY"

# With pagination

curl "https://api.beecargo.net/files/list?page=2&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by folder

curl "https://api.beecargo.net/files/list?folderId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List files in root folder only (no folder)

curl "https://api.beecargo.net/files/list?folderId=null" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List folder contents (files + subfolders)

curl "https://api.beecargo.net/files/list?folderId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Parameter	Type	Default	Description
page	Integer	1	Page number for pagination
limit	Integer	50	Number of files per page (max 200)
folderId	String	-	Filter by folder ID. Use "null" for root folder only.
includeFolders	Boolean	true	When true, response includes a "folders" array with subfolders of the requested folder (or root). Set to "false" to get only files.

Response

data contains files; folders is present when listing a folder and includeFolders is true.

List folders (dedicated endpoint)

To list only folders (e.g. all your folders or subfolders of a parent), use the folders endpoint. Same API key as above.

Query params: parentId (folder UUID or "null" for root), page, limit, search. Response: { success, data: [ folders ], pagination }. Each folder includes id, name, parent_id, file_count, total_size when not searching.

Error response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "document.pdf",
      "size": 1048576,
      "mime_type": "application/pdf",
      "path": "user-id/document.pdf",
      "short_id": "abc123",
      "folder_id": null,
      "owner_id": "user-uuid",
      "is_anonymous": false,
      "expires_at": null,
      "created_at": "2025-11-16T12:00:00.000Z",
      "updated_at": "2025-11-16T12:00:00.000Z",
      "download_count": 42
    }
  ],
  "folders": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "My folder",
      "parent_id": null,
      "owner_id": "user-uuid",
      "created_at": "2025-11-16T12:00:00.000Z",
      "updated_at": "2025-11-16T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 156,
    "totalPages": 4
  }
}