List files and folders

List your files. When you list a folder, you can also get its subfolders.

Same flow in MCP: beecargo_list_files

Endpoint

GEThttps://api.beecargo.net/files/list

Authentication

Required. Send Authorization: Bearer YOUR_API_KEY.

Authorization: Bearer YOUR_API_KEY

Request examples

List your uploaded files with pagination.

# 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 (ignored when `runId` is set)
`limit`	Integer	50	Files per page (max 200). With `runId`, max 500 (default 100)
`folderId`	String	-	Filter by folder. Use `"null"` for root only. Ignored when `runId` is set.
`includeFolders`	Boolean	true	When true, the response includes a `folders` array for that folder (or root). Set to `"false"` for files only. Ignored when `runId` is set.
`runId`	String	-	When set, list files uploaded with this pipeline id (`GET /files/run/{runId}` is an alias)

Response

data holds files. folders is included when you list a folder and includeFolders is true. With runId, the response is a run artifact list (data.runId + data.artifacts) instead of the paginated library shape.

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

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

GEThttps://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, and total_size when not searching.

Error response

{
  "success": false,
  "error": "Unauthorized. Provide an API key via Authorization header or sign in."
}

Try it