Uploading Files (Simple Uploads)

First, make sure you have an Ittybit account and an API key. You can sign up for an account and get your API key in the Ittybit webapp.

1. Create an Upload URL

You can create a short-lived upload URL to use in your frontend from your backend. This URL will allow you to upload files directly from your frontend without exposing your Ittybit API key to the client.

Example

The following example uses Node.js but you can use any language or framework you like to make the request. The only requirement is that you can make a POST request to the Ittybit API endpoint from a secure environment.

If using Node.js version 18+ you don't need to install any other packages. For lower versions, install node-fetch by running the following command in your terminal:

npm install node-fetch

Make a POST request to the Ittybit API /uploads endpoint. You'll need to include your API key in the request Authorization header:

// Uncomment the following line if you're using Node.js version 17 or lower
// const fetch = require('node-fetch');

const api_key = 'YOUR_API_KEY';

const response = await fetch('https://api.ittybit.com/uploads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_key}`,
  },
});

const { data, error } = await response.json();
if (error) {
  // Handle error
  return
}
const { url } = data;
return url;

2. Upload a file

Once you have the upload URL, you can use XHR (or axios/fetch/your requests library of choice) to upload your file from the frontend.

Note, the request doesn't require any authentication headers because the upload URL is unique to your account, short-lived, and can only be used once.

Example

function uploadFile(file, upload_url) {
  const xhr = new XMLHttpRequest();
  xhr.open('POST', upload_url);
  xhr.setRequestHeader('Content-Type', 'multipart/form-data');
  xhr.onreadystatechange = function() {
    if (xhr.readyState === 4) {
      if (xhr.status === 200) {
        const { data: media } = JSON.parse(xhr.responseText);
        console.log('File uploaded successfully');
        console.log({ media });
      } else {
        console.error('File upload failed.');
      }
    }
  };
  const formData = new FormData();
  formData.append('file', file);
  xhr.send(formData);
});

This code creates a new XMLHttpRequest object, sets the necessary request headers, and sends the file data in a FormData object.

The onreadystatechange method is called whenever the server responds, and the code checks the response status to determine whether the file was uploaded successfully.

If the upload succeeds, the response body will contain the media object that was created. In the example we only log our new media to the console, but you can use it however you like.

Note 1: Simple uploads have a filesize limit of 64MB (67,108,864 bytes) minus a few bytes for request headers. If you need to upload larger files, – up to 5TB depending on your billing plan – you can use multipart uploads.

Note 2: There is also a soft filesize limit for each organisation. Please contact us if you run in to any Request Entity Too Large errors.

3. Additional props

Any additional props should be provided when creating the upload URL.

For example, if you want to attach metadata to the media object or run a specific workflow_id after upload, you can include those props in the request body:

const response = await fetch('https://api.ittybit.com/uploads', {
  method: 'POST',
  headers: {
    'Authorization': api_key,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workflow_id: 'wf_12345678',
    metadata: {
      user_id: '12345678',
      purpose: 'avatar'
    }
  })
});

For a full list of available props, view the API docs.

4. Upload from your server

You can also use an upload URL to upload files from your server directly. Just ensure your POST request includes the Content-Type: multipart/form-data header.