Ingest

Introduction

Ingest means to pull media from a remote source and store it in Ittybit.

You can ingest files from any public or signed URL.

For example, you may have an archive full of video files in an existing S3 bucket, and you want to ingest them into ittybit so you can process them and make them available for delivery.

How to ingest media

There are two options for ingesting media:

1. Create a new file from a URL (synchronous)
2. Create an ingest task (asynchronous)

1. Create a new file from a URL

If you need immediate access to the file for delivery, or to access the file's metadata, you can create a new file from a URL synchronously.

Request

const ittybit = require('ittybit')({
  apiKey: 'ITTYBIT_API_KEY'
})

const file = await ittybit.files.create({ url: 'https://example.com/video.mp4' })

Ittybit's server will download the file from the URL, analyse it, and store it in your project.

Response

A successful response will include a File object.

// 201 Created
// Content-Type: application/json
{
  "meta": { 
    "id": "req_abcdefgh12345678",
    "type": "object",
  },
  "data": {
    "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"
  },
  "links": {
    "self": "https://api.ittybit.com/files/file_abcdefgh1234"
  }
}

2. Create an ingest task

You can also create an ingest task to ingest a file asynchronously. This will start the ingestion process and return a task_id immediately, without waiting for the file to be ingested.

This is the better option if you need to ingest a large number of files without waiting for each file to complete before moving on, or if you are ingesting files in a cron job, scheduled batch, etc.

Request

const ittybit = require('ittybit')({
  apiKey: 'ITTYBIT_API_KEY'
})

const task = await ittybit.tasks.create({
  kind: 'ingest',
  url: 'https://example.com/video.mp4'
})

Response

A successful response will include a Task object.

// 201 Created
// Content-Type: application/json  
{
  "meta": { 
    "id": "req_abcdefgh12345678",
    "type": "object",
  },
  "data": {
    "id": "task_abcdefgh1234",
    "kind": "ingest",
    // ... other props
    "status": "pending",
    "created": "2025-01-01T01:23:45Z",
    "updated": "2025-01-01T01:23:45Z"
  },  
  "links": {  
    "self": "https://api.ittybit.com/tasks/task_abcdefgh1234"
  }
}

The file will be ingested in the background and you can either poll the task occasionally for updates, or set up a webhook to notify you when the file is ready.

Poll for updates

const ittybit = require('ittybit')({
  apiKey: 'ITTYBIT_API_KEY'
})

const task = await ittybit.tasks.get('task_abcdefgh1234')

When the task is complete, the task object will contain an output object with the file data.

// 200 OK
// Content-Type: application/json
{
  "meta": { 
    "id": "req_abcdefgh56789012",
    "type": "object",
  },
  "data": {
    "id": "task_abcdefgh1234",
    "kind": "ingest",
    // ... other props
    "output": {
      "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",
      "status": "complete",
    }
  }
}

Additional props

Both File and Task approaches support additional properties, which can be included in the request's JSON body.

For example, you might set a specific folder or filename for the ingested file.

{
  "url": "https://example.com/video.mp4",
  "folder": "user_1234/uploads",
  "filename": "custom-filename.mp4"
}

Signed URLs

The examples above show a URL that is publicly accessible. If you need to ingest a file from a URL that is not publicly accessible, you can provide a signed URL to the API.

url: "https://example.com/video.mp4?signature=s0Mes3cR3tS1gN4tUr3"