Uploading Files

Learn how to upload your media to Ittybit

Introduction

There are two main ways to upload or ingest files into Ittybit with varying use-cases:

Simple Uploads - suitable for most files or scenarios.
Resumable Uploads - best for large files or if you suspect you have an unstable connection.

Via the `/files` endpoint

The simplest way to ingest with a publicly accessible URL.

Copy the following code snippet. Make a POST request and replace the placeholders in the first two lines with your API key and a publicly accessible URL of the media file to be ingested.

This method takes a file from a publicly accessible URL (plus your API key) and ingests the file into Ittybit.

const API_KEY = "YOUR API KEY HERE"
const URL = "YOUR FILE URL HERE"
const response = await fetch("https://api.ittybit.com/files", {
  headers: {
    Method: "POST",
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    body: JSON.stringify({
      url: URL
    }),
  },
});

Upload Sessions

Uploads are short-lived sessions that allow you or your users to create new Media Items with a direct file upload from your client to our servers.

1. Create an Upload Session

First, make a POST request to create a new upload session.

This will return an upload URL, that you can then use to upload your file directly from the client to our servers.

You should do this initial request from your server to keep your API keys secret.

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

The returned upload url will look something like this: https://yourdomain.com/store/single?key=aWQ9QU...

{
"meta":{
  "id": "req_abcdefgh1234",
  "org_id": "org_abcdefgh1234",
  "project_id": "prj_abcdefgh1234",
  "method": "POST",
  "host": "https://api.ittybit.com",
  "path": "/uploads",
  "version": "2024-08-21",
  "status": 200,
  "type": "object"
},
"data": {
  "url": "https://yourdomain.com/store/single?key=aWQ9QU...aWQ9QU==",
},
"links": {}
}

We automatically analyse each upload and will include some file properties for the new Source:

kind string

The type of media. Possible values are image, video, or audio.
type string

The MIME type of the media. For example, image/jpeg, video/mp4, audio/mpeg.
width integer

The width of the media in pixels. For audio files this will be null.
height integer

The height of the media in pixels. For audio files this will be null.
duration number

The duration of the media in seconds. Only available for videos and audio files.
fps number

The frames per second of the media. Only available for videos and animated images.
filesize integer

The size of the media in bytes.
bitrate integer

The bitrate of the media in kbps. For images this will be null.

Body Parameters

operator string

The operator to use to combine the rules. Possible values are && (AND) / || (OR).
rules array

An array of rules to apply to the media. Each rule is an object with the following properties:
key string

The key of the media property to check. Possible values are kind, mimetype, filesize, width, height, duration.
operator string

The operator to use to compare the value. Possible values are ==, !=, >, <, >=, <=.
value varies

The value to compare the media property to. The type of this value depends on the key and operator.

Note You will still be charged for an upload (1x the filesize against your monthly usage limit) even if the media is rejected on the server-side. So it's best to also validate the media on the client-side before starting the upload. Server-side conditions give you an extra layer of security and additional options that aren't possible on the client-side.