Skip to content

Media Folders

The following endpoints allow you to manage media folders in your Bucket.

Quick Tip
Your read and write keys will be required to perform the following requests. These can be found in Your Bucket > Settings > API Access in your Bucket Dashboard .

Get Media Folders

Get Media Folders in your Bucket.

ParameterRequiredTypeDefaultDescription
read_keyrequiredStringRestrict read access to your Bucket
prettyEnumfalsetrue, Makes the response more reader-friendly

Definition

GET $BASE_URL/buckets/${bucket_slug}/media-folders

Example Response

{
"media_folders": [
{
"title": "Product Images",
"slug": "product-images"
},
{
"title": "Jungle Animals",
"slug": "jungle-animals"
}
],
"total": 2
}

Get Media List In Folder

Returns list of media in Folder by slug from your Bucket.

ParameterRequiredTypeDefaultDescription
read_keyrequiredStringRestrict read access to your Bucket
propsStringDeclare which properties to return in comma-separated string. Reference full Media for all available properties. Example: ?props=name,url,imgix_url,metadata
sortEnum-createdcreated, -created, size, -size, random
limitNumber1000The number of Media to return
skipNumber0The number of Media to skip
prettyEnumfalsetrue, Makes the response more reader-friendly

Definition

GET $BASE_URL/buckets/${bucket_slug}/media-folders/${media_folder_slug}/media

Example Response

{
"media": [
{
"id": "5feb42f3601e2b3a6151289a",
"name": "9c4d6b70-49e5-11eb-98a2-810fade44566-logo-layout-1.jpg",
"original_name": "logo-layout-1.jpg",
"size": 256652,
"type": "image/jpeg",
"bucket": "5e6818d8e11cffafef7a6230",
"created": "2020-12-29T14:53:39.847Z",
"location": "https://cdn.cosmicjs.com",
"folder": "product-images",
"metadata": {
"ok": true
},
"url": "https://cdn.cosmicjs.com/9c4d6b70-49e5-11eb-98a2-810fade44566-logo-layout-1.jpg",
"imgix_url": "https://imgix.cosmicjs.com/9c4d6b70-49e5-11eb-98a2-810fade44566-logo-layout-1.jpg"
},
{
"id": "5feb42f2601e2b3a61512899",
"name": "9c5a3cb0-49e5-11eb-98a2-810fade44566-logo-layout-2.jpg",
"original_name": "logo-layout-2.jpg",
"size": 170482,
"type": "image/jpeg",
"bucket": "5e6818d8e11cffafef7a6230",
"created": "2020-12-29T14:53:38.494Z",
"location": "https://cdn.cosmicjs.com",
"folder": "product-images",
"url": "https://cdn.cosmicjs.com/9c5a3cb0-49e5-11eb-98a2-810fade44566-logo-layout-2.jpg",
"imgix_url": "https://imgix.cosmicjs.com/9c5a3cb0-49e5-11eb-98a2-810fade44566-logo-layout-2.jpg"
}
],
"total": 3,
"limit": 2
}

Add Media Folder

Add a new Media Folder to your Bucket.

Required
write_key must be passed as Authorization Bearer in the header of the request.

ParameterRequiredTypeDescription
titlerequiredStringTitle of the media folder. Note: slug will be auto-generated

Definition

POST $BASE_URL/buckets/${bucket_slug}/media-folders/

Header

{
"Authorization": "Bearer n5MbD59UPBoVpyqi6B6DnOzAvZ..."
}

Example Body (JSON)

{
"title": "Slideshow"
}

Example Response

{
"media_folder": {
"title": "Slideshow",
"slug": "slideshow"
}
}

Edit Media Folder

Edit an existing Media Folder by slug in your Bucket.

Required
write_key must be passed as Authorization Bearer in the header of the request.

ParameterTypeDescription
titleStringTitle of the media folder. Note: slug will be auto-generated

Note: At least one of the Parameters is required to process the request.

Definition

PATCH $BASE_URL/buckets/${bucket_slug}/media-folders/${media_folder_slug}

Header

{
"Authorization": "Bearer n5MbD59UPBoVpyqi6B6DnOzAvZ..."
}

Example Body (JSON)

{
"title": "Product Images"
}

Example Response

{
"media_folder": {
"title": "Product Images",
"slug": "product-images"
}
}

Delete Media Folder

Delete an existing Media Folder by slug from your Bucket.

Required
write_key must be passed as Authorization Bearer in the header of the request.

Definition

DELETE $BASE_URL/buckets/${bucket_slug}/media-folders/${media_folder_slug}

Header

{
"Authorization": "Bearer n5MbD59UPBoVpyqi6B6DnOzAvZ..."
}

Example Response

{
"message": "Media folder with slug '${media_folder_slug}' deleted successfully from bucket."
}