Skip to content

Media Folders

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

🔑

Get your keys
Your Bucket slug,read_key, and write_key will be required to perform the following requests. These can be found in Bucket Settings > API Access in your Bucket Dashboard .

Endpoints

GET /v2/buckets/${YOUR_BUCKET_SLUG}/media-folders
GET /v2/buckets/${YOUR_BUCKET_SLUG}/media-folders/:slug
PATCH /v2/buckets/${YOUR_BUCKET_SLUG}/media-folders/:slug
POST /v2/buckets/${YOUR_BUCKET_SLUG}/media-folders

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 /v2/buckets/${YOUR_BUCKET_SLUG}/media-folders

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/media-folders \
-d read_key=${YOUR_BUCKET_READ_KEY} \
-G

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 /v2/buckets/${YOUR_BUCKET_SLUG}/media-folders/:slug

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/media-folders/:slug \
-d read_key=${YOUR_BUCKET_READ_KEY} \
-G

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
Your Bucket write_key must be passed as Authorization Bearer in the header of the request. This can be found in Bucket Settings > API Access in your Admin Dashboard.

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

Definition

POST /v2/buckets/${YOUR_BUCKET_SLUG}/media-folders

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/media-folders \
-d '{"title":"Products"}' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer <YOUR_BUCKET_WRITE_KEY>"

Example Response

{
"media_folder": {
"title": "Products",
"slug": "products"
}
}

Edit Media Folder

Edit an existing Media Folder by slug in your Bucket.

Required
Your Bucket write_key must be passed as Authorization Bearer in the header of the request. This can be found in Bucket Settings > API Access in your Admin Dashboard.

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 /v2/buckets/${YOUR_BUCKET_SLUG}/media-folders/:slug

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/media-folders/:slug \
-d '{"title":"New Product Images"}' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer <YOUR_BUCKET_WRITE_KEY>" \
-X PATCH

Example Response

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

Delete Media Folder

Delete an existing Media Folder by slug from your Bucket.

Required
Your Bucket write_key must be passed as Authorization Bearer in the header of the request. This can be found in Bucket Settings > API Access in your Admin Dashboard.

Definition

DELETE /v2/buckets/${YOUR_BUCKET_SLUG}/media-folders/:slug

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/media-folders/:slug \
-H "Authorization: Bearer <YOUR_BUCKET_WRITE_KEY>" \
-X DELETE

Example Response

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