Files

Introduction

Files are the most fundamental objects in ittybit.

Each file object in the API represents a single binary file in your storage system.

For example, a single video uploaded to your project might be represented by a file object that looks like this:

{
  "id": "file_abcdefgh1234",
  "kind": "video",
  "type": "video/mp4",
  "width": 1024,
  "height": 768,
  "duration": 120.5,
  "filesize": 123456,
  "url": "https://your-project.ittybit.net/file_abcdefgh1234",
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}

(Simplified example. We'll cover additional props in later sections.)

File Props

ID

The id property is a unique identifier for the file.

It is set by the API and is immutable.

{
  "id": "file_abcdefgh1234",
  // ... other props
}

Object

The object property of a file object describes the type of object it is.

{
  "id": "file_abcdefgh1234",
  "object": "source",
  // ... other props
}

The following objects are supported:

Kind

The kind property describes how to categorise the file.

For source files you can think of it as the value you'd use to decide which element to display in a UI e.g. "kind": "image" would use an <img> tag, "kind": "video" would use a <video> tag, etc.

{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
}

The following kinds are supported:

Type

The type property is the MIME type of the file.

Browsers and media players use the type to determine how to handle the file.

{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "type": "video/mp4",
  // ... other props
}

A file's type is set automatically by the API when you upload, ingest, or create a new file.

See Sources for a list of supported types.

Filesize

The filesize is the size in bytes.

{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "type": "video/mp4",
  "filesize": 123456,
  // ... other props
}

This will be the value used to calculate how much Storage you are using.

URL

The url property of a file object is (unsurprisingly) the URL you can use to access the file in a browser or your application's code. ¹

{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "url": "https://your-project.ittybit.net/file_abcdefgh1234",
}

By default the url is formed from your project's domain ² and the file's id.

Filename

You can customise your file's url using the filename property.

{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "filename": "bunny.mp4",
  "url": "https://your-project.ittybit.net/bunny.mp4",
}

Folder

If you want to further customise the url you can use the folder property.

{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "filename": "bunny.mp4",
  "folder": "samples",
  "url": "https://your-project.ittybit.net/samples/bunny.mp4",
}

You can also use forward slashes to create nested folders.

{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "filename": "bunny.mp4",
  "folder": "samples/videos",
  "url": "https://your-project.ittybit.net/samples/videos/bunny.mp4",
}

This can be useful if you are transferring files from a legacy system and want to keep the same url structure, or (with custom domain²) avoid breaking existing any links.

Original

The original property is a boolean that indicates if the file is the originally uploaded / ingested file.

{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "url": "https://your-project.ittybit.net/samples/videos/bunny.mp4",
  "original": true,
}

Ref

The ref is a convenience prop that can be used to organise your files.

{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "image",
  // ... other props
  "url": "https://your-project.ittybit.net/bunny/poster.png",
  "original": false,
  "ref": "poster",
}

Refs are not required, but if you provide one then the file's url will be included in parent Media object's urls object.

{
  "id": "med_abcdefgh1234",
  // ... other props
  "urls": { 
    "poster": "https://your-project.ittybit.net/bunny/poster.png" 
  },
}

They can also be a useful hook to use inside your code. Ittybit customers often use the ref to get specific files from the sources array inside Media objects.

const poster = media.sources.find(source => source.ref === 'poster') || null;

Created

The created property is the date and time the file was created.

{
  "id": "file_abcdefgh1234",
  // ... other props
  "created": "2025-01-01T01:23:45Z",
}

Ittybit uses ISO 8601 format for all date and time properties, and sets them to UTC (Coordinated Universal Time).

The created property is set automatically by the API when you upload, ingest, or create a new file.

Updated

The updated property is the date and time the file was last updated.

{
  "id": "file_abcdefgh1234",
  // ... other props  
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z",
}

The updated property is set automatically by the API. Initially it will be the same as the created property, then it will be updated whenever the file is modified.

Metadata

See the Metadata section for more details.

Other Props

Different file objects have different properties.

Take a look at the sections below for more details.

API Reference

See the API Reference section for a full rundown of the file object, its properties, the available endpoints, and how to use them.