Upload through the API

No AWS account is needed. The API signs an upload into the project’s input/ folder and your client sends the bytes straight to S3, one of two ways:

	One `PUT`	Parts
Calls	2: start, `PUT` the file	3 + one per part: start, sign and `PUT` each part, complete
Largest file	5 GB	5 TB
Interrupted	Start again	Resumable: list the parts S3 holds and send the rest
Replacing a file	Delete it first	`overwrite: true`
For	Scripts, a first integration	Browsers, large files, pipelines that resume

A project that reads a feed takes no uploads.

One PUT

Start the upload, then PUT the whole file to the url it answers:

START=$(curl -s -X POST $API/projects/$PROJECT/uploads -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name": "episode 01.mp4", "size": 734003200}')
curl -T "episode 01.mp4" "$(jq -r .data.url <<< "$START")"

S3 answers 200 with an empty body, and the file is in input/, listed by GET /projects/{id}/files and processed by a running project. Nothing to complete. Until the PUT finishes, S3 shows nothing, so the project never sees half a file. The URL works until urlExpiresAt, an hour at most and sometimes less, and needs no header: a Content-Type you do send is stored with the file. url is absent from the answer in two cases, and then the file goes in parts:

The file is over 5 GB, the most S3 takes in one request.
A file of that name is already in input/. Replacing it in one PUT is not offered: it is the complete call of a parts upload that lets the project process the new content. Delete the file first (DELETE /projects/{id}/files/{name}), then upload it.

A project that stopped itself after its last file starts again within a minute of the PUT. Any other stopped project is not started by it (completing a parts upload does that): POST /projects/{id}/start afterwards, which is harmless on a running project. A project whose startOnNewFiles is off is started by neither.

Parts

The API starts an S3 multipart upload, signs a URL for each part, and completes it; any size, and resumable.

The calls

Start

curl -s -X POST $API/projects/$PROJECT/uploads -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name": "season 2/episode 01.mp4", "size": 734003200, "type": "video/mp4"}'

201

{
  "data": {
    "uploadId": "kuoFY0gBzJF3QDKXnQxnv0epFyjyDyUuF20w4yjsjCE4Sq9hkf7Fn.QWqeFXYSSx03HDx…",
    "key": "season 2/episode 01.mp4",
    "partSize": 16777216,
    "partCount": 44,
    "url": "https://sw-vod-express.s3.us-east-1.amazonaws.com/projects/141/…?X-Amz-Signature=…",
    "urlExpiresAt": "2026-09-28T07:10:46.000Z"
  }
}

Field
`name`	required	The file’s name under `input/`. A `/` puts it in a subfolder.
`size`	required	Its size in bytes; it decides `partSize` and `partCount`.
`type`	optional	Its media type, stored with the file.
`overwrite`	`false`	Replace a file of the same name, which is then processed again.

key is the name to send back in every later call. Cut the file into partCount parts of partSize bytes; the last one is shorter. url and urlExpiresAt are the one-PUT alternative, present when it is open to the file; a parts upload ignores them.

Send each part

Sign a part, then PUT its bytes to the URL with no other headers:

curl -s -H "$AUTH" "$API/projects/$PROJECT/uploads/$UPLOAD_ID/parts/1?key=season%202%2Fepisode%2001.mp4"

{ "data": { "url": "https://sw-vod-express.s3.us-east-1.amazonaws.com/projects/141/…?partNumber=1&uploadId=…&X-Amz-Signature=…", "expiresAt": "2026-09-28T06:43:02.000Z" } }

S3 answers 200 with an ETag header: keep it. Sign each part just before you send it; a URL works until expiresAt, an hour at most and sometimes less. Part signing has a budget of its own, 10,000 parts a minute per account, so it never uses up the API’s; parts may be sent in parallel, in any order.

Complete

curl -s -X POST $API/projects/$PROJECT/uploads/$UPLOAD_ID/complete -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"key": "season 2/episode 01.mp4", "parts": [{"partNumber": 1, "etag": "\"08b46181d7094b5ece88bb389c7499af\""}, …]}'

200

{ "data": { "key": "season 2/episode 01.mp4", "projectStatus": "running" } }

The file is now in input/ and listed by GET /projects/{id}/files. Until this call, S3 shows nothing, so the project never sees half a file. A project that ran before and is stopped now (auto-stopped after its last file, say) is started again, unless its startOnNewFiles is off. projectStatus is the project’s state afterwards: stopped for a project created with autoStart: false that has never run (start it once every file is in), error if its last start failed. Repeating the call with the same body is safe.

uploadId and key go into URLs, so URL-encode them (encodeURIComponent, jq @uri, urllib.parse.quote(…, safe="")).

Scripts

Complete uploaders in parts, with no dependency beyond the language’s standard library (and requests for Python). Each uploads one file of any size into a project and prints its entry from the files listing. For a one-PUT upload, the quick start has the three lines.

// node upload.mjs <projectId> <file> [name under input/]
import { open, stat } from 'node:fs/promises';
import { basename } from 'node:path';

const API = process.env.SW_VOD_API ?? 'https://api-vod-express.syncwords.com/v1';
const TOKEN = process.env.SW_TOKEN;
const [projectId, file, name = basename(file)] = process.argv.slice(2);

async function api(method, path, body) {
  const response = await fetch(`${API}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      Accept: 'application/json',
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await response.json();
  if (!response.ok) throw new Error(`${method} ${path}: ${response.status} ${JSON.stringify(json)}`);
  return json.data;
}

const { size } = await stat(file);
const upload = await api('POST', `/projects/${projectId}/uploads`, { name, size });
const base = `/projects/${projectId}/uploads/${encodeURIComponent(upload.uploadId)}`;
const key = encodeURIComponent(upload.key);

const handle = await open(file);
const parts = [];
try {
  for (let partNumber = 1; partNumber <= upload.partCount; partNumber++) {
    const buffer = Buffer.alloc(Math.min(upload.partSize, size - (partNumber - 1) * upload.partSize));
    await handle.read(buffer, 0, buffer.length, (partNumber - 1) * upload.partSize);

    const { url } = await api('GET', `${base}/parts/${partNumber}?key=${key}`);
    const put = await fetch(url, { method: 'PUT', body: buffer });
    if (!put.ok) throw new Error(`part ${partNumber}: S3 answered ${put.status}`);

    parts.push({ partNumber, etag: put.headers.get('etag') });
    console.log(`part ${partNumber}/${upload.partCount}`);
  }
} catch (error) {
  await api('DELETE', `${base}?key=${key}`); // discard what was sent
  throw error;
} finally {
  await handle.close();
}

await api('POST', `${base}/complete`, { key: upload.key, parts });
const files = await api('GET', `/projects/${projectId}/files`);
console.log(files.find((f) => f.name === upload.key));

# python upload.py <projectId> <file> [name under input/]
import os
import sys
from urllib.parse import quote

import requests

API = os.environ.get("SW_VOD_API", "https://api-vod-express.syncwords.com/v1")
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {os.environ['SW_TOKEN']}", "Accept": "application/json"})


def api(method, path, body=None):
    response = session.request(method, API + path, json=body)
    if not response.ok:
        raise RuntimeError(f"{method} {path}: {response.status_code} {response.text}")
    return response.json().get("data") if response.content else None


project_id, file = sys.argv[1], sys.argv[2]
name = sys.argv[3] if len(sys.argv) > 3 else os.path.basename(file)
size = os.path.getsize(file)

upload = api("POST", f"/projects/{project_id}/uploads", {"name": name, "size": size})
base = f"/projects/{project_id}/uploads/{quote(upload['uploadId'], safe='')}"
key = quote(upload["key"], safe="")

parts = []
try:
    with open(file, "rb") as handle:
        for part_number in range(1, upload["partCount"] + 1):
            chunk = handle.read(upload["partSize"])
            url = api("GET", f"{base}/parts/{part_number}?key={key}")["url"]
            put = requests.put(url, data=chunk)
            put.raise_for_status()
            parts.append({"partNumber": part_number, "etag": put.headers["ETag"]})
            print(f"part {part_number}/{upload['partCount']}")
except Exception:
    api("DELETE", f"{base}?key={key}")  # discard what was sent
    raise

api("POST", f"{base}/complete", {"key": upload["key"], "parts": parts})
files = api("GET", f"/projects/{project_id}/files")
print(next(f for f in files if f["name"] == upload["key"]))

For speed, send 4 to 8 parts at a time: each part is independent.

Resume an interrupted upload

An upload stays open for three days. To resume it, ask S3 which parts it already holds, and send only the others:

curl -s -H "$AUTH" "$API/projects/$PROJECT/uploads/$UPLOAD_ID/parts?key=$KEY"

{ "data": [{ "partNumber": 1, "size": 16777216, "etag": "08b46181d7094b5ece88bb389c7499af" }] }

Complete with every part, the listed ones included. To give up instead, abort, which discards the parts:

curl -s -X DELETE -H "$AUTH" "$API/projects/$PROJECT/uploads/$UPLOAD_ID?key=$KEY"   # 204

From a browser

The calls map one to one onto the callbacks of Uppy’s @uppy/aws-s3 plugin (version 5), so a web app gets chunking, parallel parts, retries and resume without a server of its own:

import Uppy from '@uppy/core';
import AwsS3 from '@uppy/aws-s3';

const api = (path, init = {}) =>
  fetch(`${API}/projects/${projectId}${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Accept: 'application/json' },
  }).then(async (r) => (r.status === 204 ? null : (await r.json()).data));
const q = encodeURIComponent;

new Uppy().use(AwsS3, {
  shouldUseMultipart: true,
  getChunkSize: (file) => Math.max(16 * 1024 * 1024, Math.ceil(file.size / 10000)),
  createMultipartUpload: (file) =>
    api('/uploads', { method: 'POST', body: JSON.stringify({ name: file.name, size: file.size, type: file.type }) })
      .then(({ uploadId, key }) => ({ uploadId, key })),
  signPart: (file, { uploadId, key, partNumber }) =>
    api(`/uploads/${q(uploadId)}/parts/${partNumber}?key=${q(key)}`).then(({ url }) => ({ url })),
  listParts: (file, { uploadId, key }) =>
    api(`/uploads/${q(uploadId)}/parts?key=${q(key)}`).then((parts) =>
      parts.map((p) => ({ PartNumber: p.partNumber, Size: p.size, ETag: p.etag }))),
  completeMultipartUpload: (file, { uploadId, key, parts }) =>
    api(`/uploads/${q(uploadId)}/complete`, {
      method: 'POST',
      body: JSON.stringify({ key, parts: parts.map((p) => ({ partNumber: p.PartNumber, etag: p.ETag })) }),
    }).then(() => ({})),
  abortMultipartUpload: (file, { uploadId, key }) =>
    api(`/uploads/${q(uploadId)}?key=${q(key)}`, { method: 'DELETE' }),
});

The browser sends the parts to S3 itself, so S3 must allow your web app’s origin. Send support the origins you upload from (for example https://media.example.com) to have them added, for each environment. Until then, part uploads fail in the browser with a CORS error while the API calls succeed. Scripts and servers are not affected.

Errors

Call	Status	Meaning
start	`409`	A file of that name is already in `input/` (`file_exists`). Send `overwrite: true` to replace it.
start	`409`	`overwrite: true`, but the running project may be processing that file (`file_processing`). Wait until it is `done` or `failed`, or stop the project.
start	`409`	The project reads its media from a feed (`project_reads_feed`), and takes no uploads.
start	`422`	A bad name (`errors.name`): not a media extension, `..` or empty segments, a `${`, over 255 bytes a segment; or its outputs would be written by another input already (`trailer.mov` beside `trailer.mkv`).
part `PUT`	`403` from S3	The URL expired. Sign the part again and resend it.
complete	`422`	S3 refused the parts (`errors.parts`): a wrong or missing ETag, a missing part, or a part under 5 MiB other than the last.
list, complete, abort	`404`	`{"message": "Upload not found."}`: the upload was completed, aborted, collected after three days, or never started. Start again.

Get started

Concepts

Configure a project

Upload media

Examples

Going to production

Help

One PUT

Parts

The calls

Scripts

Resume an interrupted upload

From a browser

Errors

​One PUT

​Parts

​The calls

​Scripts

​Resume an interrupted upload

​From a browser

​Errors

One PUT

Parts

The calls

Scripts

Resume an interrupted upload

From a browser

Errors