Upload an Asset Using Air's Public API

This guide will show you how to use our public API to upload a new asset into your Air worksapce. At the end of this guide, you'll have a working script that will upload assets into Air by feeding in the required metadata.

For the purpose of this guide, we'll work with a hosted image URL that is under 5 GB.

Authentication

The first step to working with Air's API is to retrieve the necessary API key and Workspace ID. Both of these can be found in our web app, make sure to check out our getting started guide if its your first time working with Air's API.

x-api-key: your_api_key_here
x-air-workspace-id: your_workspace_id

Steps

1. Get required metadata
2. Generate an upload URL
3. Download File
4. Upload file to Air

Step 1: Get Required Asset Metadata

Air's API expects several pieces of metadata for uploads, all of qhich should be easily retrievable from the file itself (you can also see whats required by looking at the /uploads endpoint in our API Reference):

1. File Name - The name you'd like to assign your new asset.
2. Mime Type - A two part type and subtype identifier, seperated by a slash (e.g. image/jpeg, video/mp4, text/csv).
3. File Size - The file size, in bytes.
4. File Extension - The last part of the hosted url, without the period (jpeg, png, pdf, etc.).
5. File - The file you want to upload.

Step 2: Generate an Upload URL

The first request you send will be to /uploads - this endpoint takes in the metadata described above and returns a signed URL you can use to upload an asset to Air.

import axios from 'axios';

// headers for the API request
const airApiKey = '<YOUR_AIR_API_KEY>'
const airWorkspaceId = '<YOUR_AIR_WORKSPACE_ID>'

// generate an upload URL for a file - including the mime, size,and ext. 
const generateUploadUrl = async (fileName, mime, size, ext) => {
    const response = await axios.post('https://api.air.inc/v1/uploads', {
            fileName: fileName,
            mime: mime,
            size: size,
            ext: ext,
        }, {
            headers: {
            'x-api-key': airApiKey,
            'x-air-workspace-id': airWorkspaceId
        }});
    return response.data;
};

For this example, we're going to use Axios to send requests, but you can feel free to use Fetch, Ajax, or any of your preferred request libraries.

If your request is successful, you should recieve an object back that looks something like this:

{
    "assetId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "versionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "uploadUrl": "https://air-pipeline.s3-accelerate.amazonaws.com/.../"
}

Step 3: Download File

In order to upload a file into Air, we have to send load the actual bytes from the file to Air. We can fetch the source URL as binary with axios and convert it to a Node Buffer:

// if the file is hosted, download it from wherever it is doested today. 
const downloadFile = async (fileUrl) => {
    const fileRes = await axios.get(fileUrl, { responseType: 'arraybuffer' });
    return Buffer.from(fileRes.data);
};

Step 4: Upload file to Air

Now that we have the file contents, we can pass that data to the Signed URL output in Step 2. Make sure to pass the mime type, and (optionally) the content length, which tells our server exactly how many bytes to expect.

// upload the file using the upload URL from the generateUploadUrl function
const uploadFile = async (uploadUrl, mime, body) => {
    console.log('uploading file to ', uploadUrl);
    const response = await axios.put(uploadUrl, body,{
        headers: {
            'Content-Type': mime,
            'Content-Length': body.length,
        },
    });
    return response.data;
};

*Make sure to use a PUT request and not a POST request when sending data to the signed URL.

Step 5: Invoke Functions & Run

Paste in the code below to tie everything together, and upload your first file to Air via API! Make sure to replace the asset details in the final line with the details of your asset.

// execution - generate the upload URL and upload the file
const main = async (fileName, mime, size, ext, file) => {
    const uploadData = await generateUploadUrl(fileName, mime, size, ext, file)
    console.log('uploadData: ', uploadData);

    const body = await downloadFile(file);
    // upload the file to the upload URL
    const uploadResponse = await uploadFile(uploadData.uploadUrl, mime, body);
    console.log('uploadResponse: ', uploadResponse);
};

// replace the file URL, title, mime, size, etc. with the actual file info you want to upload
main('My Brand New Creative Asset', 'image/jpeg', 229730, 'jpeg', 'https://yourfileurl.com/');

How to Run this script

node <PATH_TO_YOUR_FILE>/yourFile.js

Expected output

• Logs the upload URL payload and the PUT response.
• On success, the file is uploaded and ready to be processed by Air.

Common issues

• 401/403: Check x-api-key and x-air-workspace-id.
• Network/timeout: Ensure the source file URL is reachable.