# Ingesting and Uploading Source Files

The Ingest API allows you to fetch and upload source files (videos, images, audio and fonts) to use in your edits. The
examples below show you how to fetch files from URLs and upload files directly.

### Fetch a file from a URL

If you have your own storage or hosting solution and want to transfer assets to Shotstack before editing, use the
`sources` endpoint and include the file URL in the payload body:

```bash
curl -X POST https://api.shotstack.io/ingest/stage/sources \
     -H 'Content-Type: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf' \
     -d '
{
    "url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4"
}'
```

The example above requests the url `https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4` be
ingested to the `stage` environment.

You should receive a response similar to below:

```json
{
  "data": {
    "type": "source",
    "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2"
  }
}
```

The file will be fetched asynchronously from the URL which may take a some time depending on the file size, bandwidth
and geographic location. You can check the status of the transfer by polling the individual
[sources resource](#get-an-individual-source-files-details).

### Upload files directly

If the file you want to ingest is not already stored online you can upload it directly from your application using a
signed URL. By using direct uploads you do not need to worry about setting up or managing your own storage and can use
Shotstacks infrastructure instead.

To upload a file you first need to request a signed URL:

```bash
curl -X POST https://api.shotstack.io/ingest/stage/upload \
     -H 'Accept: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'
```

The request above calls the `stage` environment and returns a signed URL in the response like below:

```json
{
  "data": {
    "type": "upload",
    "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
    "attributes": {
      "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
      "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
      "expires": "2023-01-02T02:47:37.260Z"
    }
  }
}
```

The url at `data.attributes.url` is the signed URL that you use in the next step to upload the file.

#### Uploading the file

To upload a file from your desktop or server you can use the following cURL command:

```bash
curl -X PUT -T video.mp4 https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D
```

In this example a file called `video.mp4` is uploaded to Shotstack. The signed URL is appended to the end of the
command.

The upload process will be performed in the foreground and should not be interrupted until it completes. If the file
upload is interrupted the command will need to be run again.

Once complete you can poll the [sources resource](#get-an-individual-source-files-details) to get the file details.

#### Setting the Content-Type header

When uploading files you can include a `Content-Type` header to help identify the file type. For common media files
like videos, images and audio this is optional as the file type is detected automatically from the file contents.

For text-based files such as `.srt` subtitles, `.vtt` captions, `.csv` or `.txt` files, the content type cannot be
detected automatically. For these files you should either include the `Content-Type` header when uploading or provide a
`filename` with the correct extension in the initial upload request.

For example, to upload an SRT subtitle file with the Content-Type header:

```bash
curl -X PUT -H 'Content-Type: application/x-subrip' -T subtitles.srt "SIGNED_URL"
```

Or provide a filename when requesting the signed URL:

```bash
curl -X POST https://api.shotstack.io/ingest/stage/upload \
     -H 'Content-Type: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf' \
     -d '{"filename": "subtitles.srt"}'
```

:::tip

Most HTTP clients and browsers automatically set the `Content-Type` header based on the file being uploaded, so this
is usually handled for you without any extra configuration.

:::

### Get an individual source files details

Look up the details and ingestion status of a file by its id. Use the id returned when you fetch a URL or perform a
direct upload:

```bash
curl -X GET https://api.shotstack.io/ingest/stage/sources/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2 \
     -H 'Accept: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'
```

The example above calls the `sources` endpoint in the `stage` (sandbox) environment with the id
`zzytey4v-32km-kq1z-aftr-3kcuqi0brad2` which was returned by the fetch URL request.

The response will look similar to:

```json
{
  "data": {
    "type": "source",
    "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
    "attributes": {
      "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
      "owner": "5ca6hu7s9k",
      "input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
      "source": "https://shotstack-ingest-api-stage-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
      "status": "ready",
      "width": 1920,
      "height": 1080,
      "duration": 25.86,
      "fps": 23.967,
      "created": "2023-01-02T01:47:18.973Z",
      "updated": "2023-01-02T01:47:37.260Z"
    }
  }
}
```

The URL at `data.attributes.source` is the file saved with Shotstack that you can use when editing videos. If the file
is still being transferred or uploaded the `status` will show as `queued` or `importing`. If there is an error the
status will be `failed`.

### List all ingested files

You can retrieve a list of all your ingested source files. Files are returned in date order with the most recent first.

```bash
curl -X GET https://api.shotstack.io/ingest/stage/sources \
     -H 'Accept: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'
```

The response returns an array of source files like below:

```json
{
  "data": [
    {
      "type": "source",
      "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
      "attributes": {
        "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
        "owner": "5ca6hu7s9k",
        "input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
        "source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
        "status": "ready",
        "width": 1920,
        "height": 1080,
        "duration": 25.86,
        "fps": 23.967,
        "created": "2023-01-02T01:47:18.973Z",
        "updated": "2023-01-02T01:47:37.260Z"
      }
    },
    {
      "type": "source",
      "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
      "attributes": {
        "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
        "owner": "5ca6hu7s9k",
        "source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl/video.mp4",
        "status": "ready",
        "width": 1920,
        "height": 1080,
        "duration": 18.24,
        "fps": 30,
        "created": "2023-01-02T01:53:28.973Z",
        "updated": "2023-01-02T01:53:57.460Z"
      }
    }
  ]
}
```

:::info Note

In the example above the second file does not have an `input` file. The second file was uploaded using a direct upload
so there is no input URL.

:::

### Delete a file from storage

To delete a file by id send a DELETE request to the sources resource with the id of the file to delete:

```bash
curl -X DELETE https://api.shotstack.io/ingest/stage/sources/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'
```

A 204 response code is returned, the file will be deleted from storage and the status updated to `deleted`, like this:

```json
{
  "data": {
    "type": "source",
    "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
    "attributes": {
      "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
      "owner": "5ca6hu7s9k",
      "source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl/video.mp4",
      "status": "deleted",
      "width": 1920,
      "height": 1080,
      "duration": 18.24,
      "fps": 30,
      "created": "2023-01-02T01:53:28.973Z",
      "updated": "2023-01-02T01:53:57.460Z"
    }
  }
}
```

:::note Note

All Ingest API responses follow the [JSON:API](https://jsonapi.org/) specification making it easy to consume using an
existing [library](https://jsonapi.org/implementations/).

:::