Media Library
List media files, generate upload links, and request secure download links.
Media Library API
Strategy
For large files, use presigned direct upload:
- Request upload link from API.
- Upload file directly to storage with
PUT. - Use media list or download-link APIs for retrieval flow.
List Files
GET
Required permission
media_library:readApiAccessPermission::MEDIA_LIBRARY_READQuery Parameters
pageintegerPage number starting from 1.
Responses
Media file list returned.
{
"entities": "MediaLibraryFile",
"count": 1,
"per_page": 60,
"pages": {
"current": 1,
"max": 1
},
"elements": [
{
"filename": "invoice-apr-2026.pdf",
"size": 58211,
"etag": "15d6a30e7a6f0d...",
"last_modified": "2026-04-20T08:55:10+00:00"
}
]
}Create Upload Link
POST
Required permission
media_library:writeApiAccessPermission::MEDIA_LIBRARY_WRITEQuery Parameters
No query parameters required.
Request Body
{
"file": {
"filename": "invoice-apr-2026.pdf",
"content_type": "application/pdf",
"size_bytes": 58211
}
}fileobjectRequiredUpload target metadata (filename/content type/optional size).
Responses
Presigned direct upload link generated.
{
"strategy": "direct_presigned_put",
"file": {
"filename": "invoice-apr-2026.pdf",
"content_type": "application/pdf",
"max_size_bytes": 524288000
},
"upload": {
"method": "PUT",
"url": "https://storage.example.com/prod-.../invoice-apr-2026.pdf?...",
"expires_in": 1200,
"headers": {
"Content-Type": "application/pdf"
}
}
}Upload File (Fallback)
POST
Required permission
media_library:writeApiAccessPermission::MEDIA_LIBRARY_WRITEQuery Parameters
No query parameters required.
Request Body
{
"file": {
"filename": "small-note.txt",
"content_type": "text/plain",
"content_base64": "U2NoZWR1bGVkIG5vdGUgZnJvbSBBUEk="
}
}fileobjectRequiredFallback upload payload using base64 content.
Responses
File uploaded.
{
"filename": "small-note.txt",
"size": 24,
"uploaded": true
}Create Download Link
POST
Required permission
media_library:writeApiAccessPermission::MEDIA_LIBRARY_WRITEQuery Parameters
No query parameters required.
Request Body
{
"file": {
"filename": "invoice-apr-2026.pdf"
}
}fileobjectRequiredTarget file descriptor for secure download URL generation.
Responses
Download link generated.
{
"filename": "invoice-apr-2026.pdf",
"url": "https://app.example.com/file-download/download?file=..."
}