Skip to main content

​
List Folders

Retrieve a paginated list of folders from your storage. You can filter by parent folder and other criteria.

​
Endpoint

GET /folders

​
Query Parameters

ParameterTypeRequiredDescription
pagenumberNoPage number (default: 1)
limitnumberNoNumber of folders per page (default: 20, max: 100)
parentFolderIdstringNoFilter folders by parent folder ID (null for root)
searchstringNoSearch folders by name
sortBystringNoSort field (“name”, “createdAt”, “updatedAt”, “fileCount”)
sortOrderstringNoSort order (“asc” or “desc”, default: “asc”)

​
Example Request

curl -X GET "https://api.astracollab.app/v1/folders?page=1&limit=20&parentFolderId=folder_123" \
  -H "Authorization: Bearer your-api-key-here"

​
Response

{
  "success": true,
  "data": {
    "folders": [
      {
        "id": "folder_4567890abcdef123",
        "name": "My Documents",
        "description": "Personal documents and files",
        "parentFolderId": "folder_123",
        "path": "/Work/My Documents",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "fileCount": 15,
        "totalSize": 52428800
      },
      {
        "id": "folder_7890abcdef123456",
        "name": "Photos",
        "description": "Photo collection",
        "parentFolderId": "folder_123",
        "path": "/Work/Photos",
        "createdAt": "2024-01-14T15:20:00Z",
        "updatedAt": "2024-01-15T09:45:00Z",
        "fileCount": 42,
        "totalSize": 1073741824
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

​
Folder Object Properties

PropertyTypeDescription
idstringUnique folder identifier
namestringFolder name
descriptionstringOptional folder description
parentFolderIdstringParent folder ID (null if root)
pathstringFull path to the folder
createdAtstringISO 8601 timestamp of creation
updatedAtstringISO 8601 timestamp of last update
fileCountnumberNumber of files in the folder
totalSizenumberTotal size of files in bytes

​
Error Responses

​
Invalid Parameters

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid query parameters",
    "details": {
      "limit": "Must be between 1 and 100"
    }
  }
}

​
Parent Folder Not Found

{
  "success": false,
  "error": {
    "code": "PARENT_FOLDER_NOT_FOUND",
    "message": "Parent folder with ID 'folder_123' not found"
  }
}

​
Get Root Folders

To get folders at the root level (no parent): 
curl -X GET "https://api.astracollab.app/v1/folders?parentFolderId=null" \
  -H "Authorization: Bearer your-api-key-here"

​
Search Folders

Search for folders by name: 
curl -X GET "https://api.astracollab.app/v1/folders?search=documents" \
  -H "Authorization: Bearer your-api-key-here"

​
Sort Options

Sort folders by different criteria: 
# Sort by name (alphabetical)
curl -X GET "https://api.astracollab.app/v1/folders?sortBy=name&sortOrder=asc"

# Sort by creation date (newest first)
curl -X GET "https://api.astracollab.app/v1/folders?sortBy=createdAt&sortOrder=desc"

# Sort by file count (most files first)
curl -X GET "https://api.astracollab.app/v1/folders?sortBy=fileCount&sortOrder=desc"

​
SDK Examples

curl -X GET "https://api.astracollab.app/v1/folders" \
  -H "Authorization: Bearer your-api-key-here"

​
Folder Tree Structure

To build a complete folder tree, you can recursively fetch subfolders: 
const buildFolderTree = async (parentFolderId = null) => {
  const folders = await client.folders.list({ parentFolderId });
  
  const tree = await Promise.all(
    folders.map(async (folder) => ({
      ...folder,
      children: await buildFolderTree(folder.id)
    }))
  );
  
  return tree;
};
You can build breadcrumb navigation using the folder path: 
const getBreadcrumbs = (folderPath) => {
  const pathParts = folderPath.split('/').filter(Boolean);
  return pathParts.map((part, index) => ({
    name: part,
    path: '/' + pathParts.slice(0, index + 1).join('/')
  }));
};