Uploading Files with the Upload API

Builder's Upload API allows developers to 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 with the file as the request body.
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.

curl https://builder.io/api/v1/upload \
  -X POST \
  --data "@/path/to/binaryfilename"
  -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 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("https://builder.io/api/v1/upload", {
    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 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("https://builder.io/api/v1/upload", 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?