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://cosmic-s3.imgix.net/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://cosmic-s3.imgix.net/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/

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}

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}

Example Response

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