# Media

# Add Media

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


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

Parameter Required Type Description
media required Media Object (see below) Media object with specific properties
folder String Media folder slug
metadata Object Key / value data store
write_key String Your Bucket write key

    # Server-side Multer Example

    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 (opens new window).

    // index.js
    const fs = require('fs')
    const Cosmic = require('cosmicjs')()
    const multer = require('multer')
    const express = require('express')
    var app = express()
    const bucket = Cosmic.bucket({
      slug: 'your-bucket-slug',
      write_key: 'your-bucket-write-key'
    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) {

    # Media Object

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

    Parameter Required Type Description
    originalname required String The name of your file (something.jpg)
    buffer File Buffer The File Buffer

    # Client-side React Dropzone Example

    React Dropzone is a popular file uploader on the client-side. For implementation, read the React Dropzone docs on GitHub (opens new window).

    Quick Tip

    To use the following example, get your Bucket slug and keys located in Bucket > Settings in your Bucket Dashboard (opens new window).

    View full screen / fork on StackBlitz (opens new window)

    # Get Media

    Get Media from your Bucket. You can add the folder parameter to get Media from a certain folder.

    Quick Tip

    For a quick reference to this endpoint click the "Developer Tools" button on your Media table view in your Bucket Dashboard (opens new window).

    Parameter Required Type Description
    pretty File Media object
    folder String Media folder slug
    read_key String Your Bucket read key

      # Imgix

      Imgix (opens new window) 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 (opens new window) for more info.

      # Delete Media

      If a write key is enabled on the requested bucket, the parameter write_key will need to be present.

      Parameter Required Type Description
      write_key String Your Bucket write key
      trigger_webhook Bool Triggers corresponding Object action Webhook (See Webhooks)