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

GET https://api.beecargo.net/files/list

Authentication

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

Authorization: Bearer YOUR_API_KEY

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.

{
  "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
  }
}

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.

GET https://api.beecargo.net/folders/list

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": false,
  "error": "Unauthorized. Provide an API key via Authorization header or sign in."
}