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."
}