# Files

[View original](https://ittybit.com/docs/files)

## File Props

### ID

The `id` property is a unique identifier for the file.

It is set by the API and is immutable.

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

***

### Object

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

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

The following objects are supported:

| Object         | Description                                                                              |
| -------------- | ---------------------------------------------------------------------------------------- |
| `source`       | A source file, like a video or image which can be displayed in a website, player, or app |
| `track`        | A supplementary file that players can use to display subtitles, chapters, or thumbnails  |
| `intelligence` | A file containing AI-generated data about a source, like transcripts or tags             |

***

### 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.

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

The following kinds are supported:

| Object         | Kinds                                             |
| -------------- | ------------------------------------------------- |
| `source`       | `video`, `image`, `audio`                         |
| `track`        | `subtitles`, `chapters`, `thumbnails`             |
| `intelligence` | `speech`, `tags`, `description`, `nsfw`, `prompt` |

***

### Type

The `type` property is the [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types) of the file.

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

```json
{
  "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](/docs/sources) for a list of supported types.

***

### Filesize

The `filesize` is the size in bytes.

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

This will be the value used to calculate how much [Storage](/docs/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. [^1]

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "url": "https://you.ittybit.net/file_abcdefgh1234",
}
```

By default the url is formed from your project's [domain](/docs/domains) [^2] and the file's `id`.

***

### Filename

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

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "filename": "video.mp4",
  "url": "https://you.ittybit.net/video.mp4",
}
```

<Callout>
  <Icon icon="warning" />

  You can give the same filename to multiple files.

  When URLs collide, the most recently updated file will be served.
</Callout>

***

### Folder

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

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "filename": "video.mp4",
  "folder": "example",
  "url": "https://you.ittybit.net/example/video.mp4",
}
```

You can also use forward slashes to create nested folders.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "filename": "video.mp4",
  "folder": "example/videos",
  "url": "https://you.ittybit.net/example/videos/video.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[^2]) avoid breaking existing any links.

***

### Original

The `original` property is a boolean that indicates if the file is the originally [uploaded](/docs/uploads) / [ingested](/docs/ingest) file.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  // ... other props
  "url": "https://you.ittybit.net/example/videos/video.mp4",
  "original": true,
}
```

***

### Ref

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

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "image",
  // ... other props
  "url": "https://you.ittybit.net/example/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](/docs/media) `urls` object.

```json
{
  "id": "med_abcdefgh1234",
  // ... other props
  "urls": { 
    "poster": "https://you.ittybit.net/example/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](/docs/media) objects.

<Tabs items={["JS", "Python", "Ruby", "PHP", "Go"]}>
  <Tab value="JS">
    ```js
    const poster = media.sources.find(source => source.ref === 'poster') || null;
    ```
  </Tab>

  <Tab value="Python">
    ```python
    poster = next((source for source in media.sources if source.ref == 'poster'), None)
    ```
  </Tab>

  <Tab value="Ruby">
    ```ruby
    poster = media.sources.find { |source| source.ref == 'poster' } || nil
    ```
  </Tab>

  <Tab value="PHP">
    ```php
    $poster = array_filter($media->sources, function($source) {
        return $source->ref === 'poster';
    })[0] ?? null;
    ```
  </Tab>

  <Tab value="Go">
    ```go
    poster := media.Sources.Find(func(source *Source) bool {
        return source.Ref == "poster"
    })
    ```
  </Tab>
</Tabs>

***

### Status

The `status` property is the current status of the file.

```json
{
  "id": "file_abcdefgh1234",
  // ... other props
  "status": "ready",
}
```

The `status` property is one of `waiting`, `processing`, `ready`, or `failed`.

<Callout>
  <Icon icon="info" />

  Only `ready` files are publicly accessible.

  Files in other states are not accessible by the public but might be visible in API results and as part of [Tasks](/docs/tasks) that are still processing.
</Callout>

***

### Created

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

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

Ittybit uses [ISO 8601](https://en.wikipedia.org/wiki/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.

```json
{
  "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](/docs/metadata) section for more details.

<Card href="/docs/metadata" icon={<Icon icon="metadata" className="text-brand-purple" />} title="Metadata" />

***

## Other Props

Different file objects have different properties.

Take a look at the sections below for more details.

<Cards>
  ### Sources \[toc]

  <Card href="/docs/sources" icon={<Icon icon="sources" className="text-brand-green" />} title="Sources" />

  ### Tracks \[toc]

  <Card href="/docs/tracks" icon={<Icon icon="track" className="text-brand-orange" />} title="Tracks" />

  ### Intelligence \[toc]

  <Card href="/docs/intelligence" icon={<Icon icon="intelligence" className="text-brand-magenta" />} title="Intelligence" />
</Cards>

***

## API Reference

See the [API Reference](/api/files) section for a full rundown of the file object, its properties, the available endpoints, and how to use them.

<Card href="/api" icon={<Icon icon="terminal" className="text-brand-green" />} title="API Reference" />

***

[^1]: New projects default to public delivery, but depending on your [Access Rules](/docs/delivery/rules) you may require a [Signed URL](/docs/delivery/signed) to view the file.

[^2]: New projects default to a free `*.ittybit.net` domain, but you can [add your own custom domain](/docs/domains) if you'd prefer to keep your URLs on-brand.