Skip to main content

​
List Files

Retrieve a paginated list of files from your storage. You can filter by folder, file type, and other criteria.

​
Endpoint

GET /files

​
Query Parameters

ParameterTypeRequiredDescription
pagenumberNoPage number (default: 1)
limitnumberNoNumber of files per page (default: 20, max: 100)
folderIdstringNoFilter files by folder ID
typestringNoFilter by file type (e.g., “image”, “document”, “video”)
searchstringNoSearch files by name
sortBystringNoSort field (“name”, “size”, “uploadedAt”, “updatedAt”)
sortOrderstringNoSort order (“asc” or “desc”, default: “desc”)

​
Example Request

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

​
Response

{
  "success": true,
  "data": {
    "files": [
      {
        "id": "file_1234567890abcdef",
        "name": "example.jpg",
        "size": 1024000,
        "type": "image/jpeg",
        "url": "https://storage.astracollab.app/files/file_1234567890abcdef",
        "folderId": "folder_123",
        "uploadedAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "metadata": {
          "width": 1920,
          "height": 1080
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

​
File Object Properties

PropertyTypeDescription
idstringUnique file identifier
namestringOriginal filename
sizenumberFile size in bytes
typestringMIME type
urlstringDirect download URL
folderIdstringParent folder ID (null if in root)
uploadedAtstringISO 8601 timestamp of upload
updatedAtstringISO 8601 timestamp of last update
metadataobjectAdditional file metadata

​
Error Responses

​
Invalid Parameters

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

​
Folder Not Found

{
  "success": false,
  "error": {
    "code": "FOLDER_NOT_FOUND",
    "message": "Folder with ID 'folder_123' not found"
  }
}

​
Rate Limiting

This endpoint is subject to rate limiting based on your plan.

​
SDK Examples

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