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/${YOUR_BUCKET_SLUG}/media-folders?read_key=${YOUR_BUCKET_READ_KEY}

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/${YOUR_BUCKET_SLUG}/media-folders/${media_folder_slug}/media?read_key=${YOUR_BUCKET_READ_KEY}

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

Header

{
  "Authorization": "Bearer YOUR_BUCKET_WRITE_KEY"
}

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

Header

{
  "Authorization": "Bearer YOUR_BUCKET_WRITE_KEY"
}

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

Header

{
  "Authorization": "Bearer YOUR_BUCKET_WRITE_KEY"
}

Example Response

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