With Builder's Upload API, developers can 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:
- 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
POSTrequest to the endpointhttps://builder.io/api/v1/upload?name=MyFileName.pdfwith the file as the request body and whereMyFileName.pdfis the name of the file you're uploading. - Provide your Private API Key in the
Authorizationheader. - Specify the file type in the
Content-Typeheader. - When you make a successful
POSTrequest, 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, 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'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/..."
}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
fsmodule. - A
POSTrequest 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');
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
Headersobject to store some headers, such asAuthorizationandContent-Type. TheAuthorizationheader includes the Private API Key needed to authenticate the request, and theContent-Typeheader specifies the type of file being uploaded. - Uses a
filevariable that holds the binary data of the file to be uploaded. - Uses a
requestOptionsvariable that holds an object that specifies the options for thefetch()function call. It specifies the file name, HTTPPOSTmethod, the headers, thebody—which contains the binary data of the file—and a redirect option set tofollow. - Calls a
fetch()function to make an HTTPPOSTrequest to the Builder API's upload endpoint with therequestOptions. - 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));
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=a0c7e097c0c34c16aadc5a204affe346The following image shows the Edit Asset Folder dialogue, with the folder ID highlighted:
