Cosmic JS Blog Stay tuned for community news, company announcements and updates from the Cosmic JS team.

How to Upload Media to Your Bucket Using the Cosmic JS API

by Tony Spiro on December 3, 2016

In this short tutorial I’m going to show you how to:

1. Upload an image to your Cosmic JS Bucket via the Cosmic JS API.
2. Alter your image using the powerful Imgix processing service (free with every Cosmic JS Bucket)
3. Add the uploaded image as a Metafield to an Object in your Bucket

Getting Started

Sign up for Cosmic JS to create your own Bucket or just follow along with the examples.  

To start, let's create a simple HTML form to upload our media.

    <form action="" method="post" enctype="multipart/form-data">
      <input type="file" name="media" />
      <input type="submit" value="Upload!" />
Next let's add a file and let it rip.  Notice we now have data to use for data fetching / storing:
  "media": {
    "name": "57319310-b914-11e6-acef-b1b7e94fa195-earth.png",
    "original_name": "earth.png",
    "size": 1024912,
    "type": "image/png",
    "bucket": "5839c67f0d3201c114000004",
    "created": "2016-12-03T04:52:49.516Z",
    "location": "",
    "url": "",
    "imgix_url": "",

The Power of Imgix

After we POST our media to our Cosmic JS Bucket, one of the pieces of data returned is an Imgix URL.  Imgix gives us powerful image processing capability on the fly.  By simply adding query parameters to the end of the Imgix url, we have the power to resize, crop, add filters and more to our uploaded images.  For example, to resize this image to 2X mobile size just add "?w=640" at the end of the url:

This makes creating light-weight responsive websites much easier because now we don't have to upload multiple images for different devices.  All we do now is program the url to serve the size we want.  Browse the Imgix docs to see all the capabilities at your fingertips.  Imgix is included free with every Cosmic JS account.

Adding the Uploaded Image to an Object

After adding our image to our Cosmic JS Bucket we may want to add it to an Object.  To do this we'll simply take the "name" value returned after we POST our media and add it as a file Metafield value and POST this to our Add Object API endpoint:

POST /v1/:your-bucket-slug/add-object
  "title": "New Object",
  "slug": "new-object",
  "type_slug": "tests",
  "content": "",
  "metafields": [{
    "type": "file",
    "title": "Image",
    "key": "image",
    "value": "57319310-b914-11e6-acef-b1b7e94fa195-earth.png"

Now when we go into our Cosmic JS Bucket we'll notice that the "Tests" Object Type has a new Object titled "New Object" with our newly uploaded file as a file Metafield.


Cosmic JS makes it really easy to add dynamic content to any website or application.  In this tutorial I showed you how you can use the Cosmic JS API to add media, process images using the available Imgix processing URL then save that image to an Object in our Bucket for easy editing later.  To learn more about how Cosmic JS makes it easy to store media and power content for your websites and apps, check out the Documentation page.

I hope you enjoyed this tutorial.  If you have any questions or would like to learn more about how Cosmic JS can help you build content-powered apps faster and easier join Cosmic JS on Slack and reach out to us on Twitter.

You may also like

We are excited to announce our Developer Program (in private beta) and we invite developers to join us in our mission to help our community learn more about how to build apps faster using Cosmic JS.

The process of building your messenger bot is fairly simple the hardest part is setting up your machine to talk to talk to Facebook. That's why today I'm going to walk you through that real quick. Once it is all done you can get right on the way to creating your own bot.

You now have the ability to grant additional user permissions to team members working in your Bucket.  More granular control is useful if your editors need the ability to add other editors, if your developer needs access to Bucket billing, and other admin features.

This Appointment Scheduler lets users select a day and a one-hour time slot between 9AM and 5PM to meet with us. It integrates with Twilio to send a confirmation text that their appointment has been scheduled. This also comes with a Cosmic JS Extension so we can manage the appointments right from within the Cosmic JS dashboard.

In last week's article, Tony told us about the ingredients in The Cosmic Stack, why it is so powerful and what its benefits are. Now that we've seen what The Cosmic Stack looks like, let's look at how we can customize our use of it. 

From a high level, you have three basic ways to use The Cosmic Stack. You have flexibility to use just the CMS API, the CMS API and your own app hosted on the Cosmic app server, or the CMS API with a pre-built content-ready app hosted on the Cosmic App Server.

We're excited to announce a new feature that allows you to easily monitor API usage and activity for your Cosmic JS-powered applications.