Uploading Files with the Upload API

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

Prerequisites

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.

Creating a request

To upload a file to Builder using the Upload API:

Create a Private API Key if you don't already have one.
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.
Make a POST request to the endpoint https://builder.io/api/v1/upload?name=MyFileName.pdf with the file as the request body and where MyFileName.pdf is the name of the file you're uploading.
Provide your Private API Key in the Authorization header.
Specify the file type in the Content-Type header.
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.

POST Request Example

To upload a file into your assets library, send a POST with the file as the request body as in the following example, making sure to specify the name of file in the URL with name.

curl https://builder.io/api/v1/upload?name=MyFileName.pdf \
  -X POST \
  --data "@/path/to/your-file.ext"
  -H 'Authorization: Bearer YOUR_PRIVATE_KEY' \
  -H 'Content-Type: image/png'

Example Response

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": "https://cdn.builder.io/api/v1/image/..."
}

Node.js example

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, the file name, 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 
  // which includes the name of the file.
  // Include the binary data as the request body and needed headers
  fetch("https://builder.io/api/v1/upload?name=MyFileName.pdf", {
    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
upload_image('./path-to-media');

Javascript example

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 file name, 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
// including the name of the file
fetch("https://builder.io/api/v1/upload?name=MyFileName.pdf", 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));

Specifying a destination asset folder

Tip: If you are using environments, you can only manage folders in the main environment. Builder then syncs the updates you make to folders in the main environment with child environments.

To make changes to folders, be sure to use your main environment API Key.

For more information, visit Understanding Environments.

If you're using folders to organize assets in Builder, you can optionally upload to a specific folder by adding the folder ID to the URL.

For example, if you wanted to upload an asset to a folder with the ID of abc123, you'd add &folder=abc123 to the URL and replace the placeholder ID of abc123 with your actual folder ID.

To find an asset folder ID:

Go to the Asset Library.
Hover over the folder and click the Pencil icon.
In the dialogue that opens, copy the ID.

For example, if the ID were a0c7e097c0c34c16aadc5a204affe346, the syntax would be:

https://builder.io/api/v1/upload?name=MyFileName.pdf&folder=a0c7e097c0c34c16aadc5a204affe346

The following image shows the Edit Asset Folder dialogue, with the folder ID highlighted:

Screenshot of Edit Asset Folder dialogue. The Name is My Photos and the Folder ID is an approximately 30-character alphanumeric string.

Was this article helpful?