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
queryJSONA JSON string to perform media search and filtering. See Queries section for more detail.

Methods

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://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": 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

Methods

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://imgix.cosmicjs.com/d319ff30-13b7-11e9-acee-bd778576f320-default_profile.png"
}
}

Imgix

Imgix is included with every account. You can use the Imgix suite of image processing tools on the URL provided by the imgix_url property value. Check out the Imgix documentation for more info.

Add Media

The only required post value is the media object. You can also add optional folder and metadata params.

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

Quick Tip
The base endpoint is different than other REST API requests with a higher upload size limit of 900MB.

Upload URL

https://upload.cosmicjs.com/v2
ParameterRequiredTypeDescription
mediarequiredMedia Object (see below)Media object with specific properties
folderStringMedia folder slug
metadataObjectKey / value data store
trigger_webhookBooleanTriggers corresponding Media action Webhook (See Webhooks).

Media Object

The Media Object must be an object with certain properties indicated below. If using the multer NPM module the file objects have these by default. Otherwise you should create an object with these properties:

ParameterRequiredTypeDescription
originalnamerequiredStringThe name of your file (something.jpg)
bufferFile BufferThe File Buffer

Methods

See upload URL above.

POST $UPLOAD_URL/buckets/:bucket_slug/media

Curl

curl --form "folder=folder-name" --form "media=@test.png" -H "Authorization: Bearer <write-key>" 'https://upload.cosmicjs.com/v2/buckets/:bucket_slug/media'

Header

{
"Authorization": "Bearer n5MbD59UPBoVpyqi6B6DnOzAvZ..."
}

Example Response

{
"media": {
"id": "602fd622853cca45f4c9fd96",
"name": "c20391e0-b8a4-11e6-8836-fbdfd6956b31-test.png",
"original_name": "test.png",
"size": 457307,
"folder": "folder-name",
"type": "image/png",
"bucket": "5839c67f0d3201c114000004",
"created": "2016-12-02T15:34:05.054Z",
"location": "https://cdn.cosmicjs.com",
"url": "https://cdn.cosmicjs.com/c20391e0-b8a4-11e6-8836-fbdfd6956b31-test.png",
"imgix_url": "https://imgix.cosmicjs.com/c20391e0-b8a4-11e6-8836-fbdfd6956b31-test.png"
}
}

Examples

Multer: Server-Side

This application uses Express and Multer to create a route POST http://localhost:5000/upload that will upload a file to your Bucket Media area. This is an example from the article Upload Media to Your Cosmic Bucket Using Multer.

// index.js
const fs = require('fs')
const Cosmic = require('cosmicjs')
const api = Cosmic()
const multer = require('multer')
const express = require('express')
var app = express()
const bucket = api.bucket({
slug: 'your-bucket-slug',
write_key: 'your-write-key-found-in-bucket-settings'
})
var storage = multer.diskStorage({
destination: function (req, file, cb) {
cb(null, __dirname + '/uploads')
},
filename: function (req, file, cb) {
cb(null, file.fieldname + '-' + Date.now())
}
})
var upload = multer({ storage: storage })
app.post('/upload', upload.single('file'), async function (req, res) {
try {
const media_object = {
originalname: req.file.originalname,
buffer: fs.createReadStream(req.file.path)
}
const response = await bucket.addMedia({ media: media_object })
return res.json(response)
} catch (e) {
console.log(e)
}
})
app.listen(5000)

React Dropzone: Client-side

React Dropzone is a popular file uploader on the client-side. For implementation, read the React Dropzone docs on GitHub.

View full screen / fork on StackBlitz

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
metadataObjectJSON object
trigger_webhookBooleanTriggers corresponding Media action Webhook (See Webhooks).

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

Definition

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

Header

{
"Authorization": "Bearer n5MbD59UPBoVpyqi6B6DnOzAvZ..."
}

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.

Query ParameterTypeDescription
trigger_webhookBooleanTriggers corresponding Media action Webhook (See Webhooks).

Methods

DELETE $BASE_URL/buckets/${bucket_slug}/media/${media_id}?trigger_webhook=true

Header

{
"Authorization": "Bearer n5MbD59UPBoVpyqi6B6DnOzAvZ..."
}

Example Response

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