Made in

Ship Your First Personalized Web Experience webinar on June 15 @ 10AM PT. Register Now

Talk to Us
Talk to Us










Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required



Get StartedLogin

Builder's Upload API allows developers to upload files programmatically, such as images and videos, to Builder.

Before using the Upload API, create a Private API Key in Organization Account Settings.

Tip: Only those with Developer or Admin permissions can create Private API Keys.

Be sure to read Managing Private API Keys so that you know how to keep your key secure.

To upload a file to Builder using the Upload API:

  1. Create a Private API Key if you don't already have one.
  2. Copy the Private API Key. Keep this key secret and only use it in API calls from your server, not any calls from public client applications.
  3. Make a POST request to the endpoint with the file as the request body.
  4. Provide your Private API Key in the Authorization header.
  5. Specify the file type in the Content-Type header.
  6. When you make a successful POST request, you receive a JSON response with a URL for the uploaded file.

To better understand this process, the following is an example request and response.

To upload a file into your assets library, send a POST with the file as the request body as in the following example.

curl \
  -X POST \
  --data "@/path/to/binaryfilename"
  -H 'Authorization: Bearer YOUR_PRIVATE_KEY' \
  -H 'Content-Type: image/png'

The response to a successful POST request includes a JSON object with information about the uploaded file, such as its URL. Here is an example response from the Builder Upload API:

    "status": 200,
    "message": "Success",
    "url": ""

The following Node.js example demonstrates how to use the Builder Upload API in a Node.js environment.

Notable features of this example include:

  • A function called upload_image() that uploads an image file to the Builder Upload API.
  • The image file is read as binary data using the fs module.
  • A POST request is made to the API endpoint with the binary data and appropriate headers.
  • If the request is successful, the response is logged to the console as JSON.
  • The function is then called with the path to the image file as an argument to upload the image.

See the comments for details.

// Import modules
const fetch = require("node-fetch");
const fs = require('fs');

// Define a function that will upload the image to Builder
function upload_image(file) {
  // Read the binary data from the image file
  var bitmap = fs.readFileSync(file);
  // Send a POST request to Builder Upload API 
  // with the binary data as the request body and needed headers
  fetch("", {
    method: "POST",
    body: bitmap, // binary data of the image
    headers: {
      // header with private key
     "Authorization": "Bearer builder-private-key",
     // header with the type of the image
     "Content-Type": "image/jpeg" 
 }).then(res => {
      return res.json(); // Parse the response JSON
 }).then(resp => {
     console.log(resp); // Log the response JSON
 }).catch((e) => console.log(e)); // log errors

// Call the `upload_image()` function with the 
// path to the image file as the argument

This next example is similar to the Node.js example, but written with the browser's fetch() API instead.

This example has the following features:

  • Creates a new Headers object to store some headers, such as Authorization and Content-Type. The Authorization header includes the Private API Key needed to authenticate the request, and the Content-Type header specifies the type of file being uploaded.
  • Uses a file variable that holds the binary data of the file to be uploaded.
  • Uses a requestOptions variable that holds an object that specifies the options for the fetch() function call. It specifies the HTTP POST method, the headers, the body—which contains the binary data of the file—and a redirect option set to follow.
  • Calls a fetch() function to make an HTTP POST request to the Builder API's upload endpoint with the requestOptions.
  • The response from the server is then converted to text and logged to the console.

For more context, see the comments in the code below:

// create a new Headers object
var myHeaders = new Headers();
// append the authorization token to the headers object
myHeaders.append("Authorization", "Bearer builder-private-key");
// append the content type to the headers object
myHeaders.append("Content-Type", "image/jpeg");

// specify the binary data to be uploaded
var file = "<file contents here>"; // Binary data

// create the `requestOptions` object
var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: file,
  redirect: 'follow'

// send the fetch request to the Builder Upload API
fetch("", requestOptions)
  // when the response is received, parse it as text
  .then(response => response.text())
  // once the response has been parsed, log the resulting text to the console
  .then(result => console.log(result))
  // if an error occurs during the fetch request, log it to the console
  .catch(error => console.log('error', error));

Looking to hire a third party to help with your project?

Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.

Connect with us

Was this article helpful?


Visual CMS

Theme Studio for Shopify

Sign up


Featured Integrations





Get In Touch

Chat With Us




© 2020, Inc.


Privacy Policy

Terms of Service

Get the latest from

Developer Newsletter

Latest tips, tricks, and news for frontend developers from our blog

Product Newsletter

Latest features and updates on the platform

By submitting, you agree to our Privacy Policy




What's New




Community Forum



Submit an Idea

Use Cases

Landing Pages

Headless CMS

Headless Storefront

Customer Showcase

Customer Success Stories logo

Visually build and optimize digital experiences on any tech stack. No coding required, and developer approved.

Get Started

Log In





Use Cases

© 2023, Inc.


Privacy Policy

SaaS Terms