Media
Media Overview
Uploading photos and videos for listings via API
Media files are a required part of listings. You need at least 3 photos for publishing. The API supports two upload methods and automatically optimizes all files.
You don't need to optimize photos before uploading — upload originals.
Upload Methods
| Method | When to Use | Description |
|---|---|---|
| URL in listing | Whenever possible | Simplest — pass URLs directly when creating a listing |
| Import by URL | Pre-upload | Upload photos separately, then link to listing |
| Signed URL | Upload from local disk | For files without a public URL |
Recommendation: Pass photo URLs directly when creating a listing — the system will download them automatically. This is the simplest approach.
Supported Formats
Images
JPEG, PNG, WebP, HEIC, and other popular formats.
Video
MP4, AVI, MOV — up to 3 minutes.
Limits
| Parameter | Value |
|---|---|
| Minimum photos for publishing | 3 |
| Maximum photos per listing | 20 |
| Files in a single request | up to 100 |
| Signed URL validity | 30 minutes |
Typical Scenario
Recommended approach — in one request:
PUT /listings
→ pass files: [{ url: "https://..." }] and announcementStatus: "active"
→ system automatically downloads and optimizes photos
Alternative approach — separate upload:
1. Upload photos → POST /media/bulk
→ with upload-from-url operation
2. Link to listing → PUT /listings
→ pass files: [{ id: 123 }] or [{ externalFileId: "..." }]
Media File Structure
After upload and optimization, a file contains:
{
"id": 123,
"externalId": "photo-001",
"size": 245000,
"contentType": "image/jpeg",
"optimization": "success",
"blurhash": "L7HuX^zY1z-6ADx?0z2@1Io#{yV_",
"originalUrl": "https://storage.../original.jpg",
"variants": [
{ "url": "https://storage.../128.webp", "variantSize": "128", "size": 4074 },
{ "url": "https://storage.../512.webp", "variantSize": "512", "size": 32850 },
{ "url": "https://storage.../1024.webp", "variantSize": "1024", "size": 98500 }
]
}
| Field | Description |
|---|---|
id | Internal file ID |
externalId | Your CRM ID |
optimization | Optimization status |
blurhash | String for generating placeholder |
originalUrl | Link to original |
variants | Optimized versions of different sizes |
API Endpoints
| Method | Path | Description |
|---|---|---|
POST | /media/upload-from-url | Import by URL |
POST | /media/bulk | Bulk operations (upload-from-url, confirm-upload, etc.) |
POST | /media/request-upload-url | Signed URL |
GET | /media/:id | Get file |
GET | /media/external/:externalId | Get by external ID |
DELETE | /media/:id | Delete file |
DELETE | /media/external/:externalId | Delete by external ID |
POST | /media/:id/link | Link external ID |
DELETE | /media/:id/link | Unlink external ID |
Next Steps
- Upload photos — step-by-step instructions
- Manage files — retrieval, deletion, linking