Skip to content

Media

The following endpoints allow you to manage media 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 List

Get Media List in 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
queryJSONCOMING SOON! A JSON string to perform media search and filtering. See Queries section for more detail.

Definition

GET $BASE_URL/buckets/${bucket_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",
"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": 10,
"limit": 2
}

Get Media

Returns a single Media by id 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
prettyEnumfalsetrue, Makes the response more reader-friendly

Definition

GET $BASE_URL/buckets/${bucket_slug}/media/${media_id}

Example Response

{
"media": {
"id": "5f331eac9d52b17aee21d1b4",
"name": "d319ff30-13b7-11e9-acee-bd778576f320-default_profile.png",
"original_name": "default_profile.png",
"size": 4889,
"type": "image/png",
"bucket": "5e6818d8e11cffafef7a6230",
"created": "2020-08-11T22:41:48.651Z",
"location": "https://cdn.cosmicjs.com",
"folder": null,
"metadata": {
"ok": true
},
"url": "https://cdn.cosmicjs.com/d319ff30-13b7-11e9-acee-bd778576f320-default_profile.png",
"imgix_url": "https://cosmic-s3.imgix.net/d319ff30-13b7-11e9-acee-bd778576f320-default_profile.png"
}
}

Edit Media

Edit an existing Media by id in your Bucket.

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

ParameterTypeDescription
folderStringSlug of the folder where you want to move the media
MetadataObjectMetadata object

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

Definition

PATCH $BASE_URL/buckets/${bucket_slug}/media/${media_id}

Example Body (JSON)

{
"metadata": {
"avatar": true
}
}

Example Response

{
"message": "Media with id '${media_id}' edited successfully in bucket."
}

Delete Media

Delete an existing Media by id 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/${media_id}

Example Response

{
"message": "Media with id '${media_id}' deleted successfully from bucket."
}