Skip to main content

​
Upload File

Upload a single file to your storage. Supports files up to 5GB for most plans.

​
Endpoint

POST /files/upload

​
Request Body

This endpoint accepts multipart/form-data with the following fields:
FieldTypeRequiredDescription
filefileYesThe file to upload
folderIdstringNoID of the folder to upload to
metadatastringNoJSON string of additional metadata

​
Example Request

curl -X POST "https://api.astracollab.app/v1/files/upload" \
  -H "Authorization: Bearer your-api-key-here" \
  -F "[email protected]" \
  -F "folderId=folder_123" \
  -F 'metadata={"description": "My photo", "tags": ["photo", "personal"]}'

​
Response

{
  "success": true,
  "data": {
    "file": {
      "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": {
        "description": "My photo",
        "tags": ["photo", "personal"],
        "width": 1920,
        "height": 1080
      }
    }
  }
}

​
File Size Limits

PlanMaximum File Size
Free100 MB
Creator1 GB
Studio5 GB
Production10 GB

​
Supported File Types

AstraCollab supports all file types. Common categories include:
  • Images: JPG, PNG, GIF, WebP, SVG, etc.
  • Documents: PDF, DOC, DOCX, TXT, etc.
  • Videos: MP4, MOV, AVI, WebM, etc.
  • Audio: MP3, WAV, FLAC, etc.
  • Archives: ZIP, RAR, 7Z, etc.

​
Error Responses

​
File Too Large

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds plan limit",
    "details": {
      "fileSize": 1073741824,
      "maxSize": 104857600
    }
  }
}

​
Invalid File

{
  "success": false,
  "error": {
    "code": "INVALID_FILE",
    "message": "Invalid or corrupted file"
  }
}

​
Storage Quota Exceeded

{
  "success": false,
  "error": {
    "code": "STORAGE_QUOTA_EXCEEDED",
    "message": "Storage quota exceeded",
    "details": {
      "used": "9.5 GB",
      "limit": "10 GB"
    }
  }
}

​
Progress Tracking

For large files, you can track upload progress: 
const formData = new FormData();
formData.append('file', file);

const response = await fetch('https://api.astracollab.app/v1/files/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-api-key-here'
  },
  body: formData,
  onUploadProgress: (progressEvent) => {
    const percentCompleted = Math.round(
      (progressEvent.loaded * 100) / progressEvent.total
    );
    console.log(`Upload progress: ${percentCompleted}%`);
  }
});

​
SDK Examples

curl -X POST "https://api.astracollab.app/v1/files/upload" \
  -H "Authorization: Bearer your-api-key-here" \
  -F "[email protected]"

​
Large File Uploads

For files larger than 100MB, consider using multipart uploads for better reliability and resumability.