Start an upload

POST

/v1/uploads

curl --request POST \
  --url https://api.iomza.com/v1/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "file_name": "video.mov", "content_type": "application/octet-stream", "size": 1, "progressive": true }'

• Production

Reserves a place for a file and signs where to send it. Up to 100 MB: mode: "single", one PUT to url with headers, then complete. Larger: mode: "multipart", each part (part_size bytes) PUT to its URL in parallel, keeping each response’s ETag, then complete with them. With progressive: true, each part is its own object and there is no complete: create the job right away and it is transcoded while the file arrives (send the first and last parts first). Sources are kept 7 days.

Authorizations

• apiKey

Request Body^required

Media typeapplication/json

object

file_name

required

The file’s name, shown in the app.

string

>= 1 characters <= 255 characters

content_type

The file’s type, sent again as Content-Type in each PUT.

string

default: application/octet-stream <= 255 characters

size

required

Bytes. Up to the plan’s maximum file size.

integer

> 0 <= 9007199254740991

progressive

Each part becomes its own object, readable as it lands, and there is no complete: create the job as soon as the upload starts and it is transcoded while the file arrives.

boolean

Responses

201

The upload, with how to send the file.

Media typeapplication/json

Any of:

object

object

mode

required

How it arrives: single (one PUT), multipart (parts in parallel, then complete), progressive (parts readable as they land, no complete) or url (copied by the job that was given the URL; completed once the copy is done).

string

Allowed value: single

url

required

string

method

required

string

Allowed value: PUT

headers

required

object

key

additional properties

string

expires_in

required

number

id

required

string

object

required

string

Allowed value: upload

status

required

completed once the whole file is stored.

string

Allowed values: pending completed

file_name

required

string

size

required

number | null

source_url

required

Where an imported source came from.

string | null

created_at

required

string format: date-time

completed_at

required

string | null format: date-time

object

object

mode

required

How it arrives: single (one PUT), multipart (parts in parallel, then complete), progressive (parts readable as they land, no complete) or url (copied by the job that was given the URL; completed once the copy is done).

string

Allowed value: multipart

part_size

required

number

parts

required

Array<object>

object

part_number

required

number

url

required

string

expires_in

required

number

id

required

string

object

required

string

Allowed value: upload

status

required

completed once the whole file is stored.

string

Allowed values: pending completed

file_name

required

string

size

required

number | null

source_url

required

Where an imported source came from.

string | null

created_at

required

string format: date-time

completed_at

required

string | null format: date-time

object

object

mode

required

How it arrives: single (one PUT), multipart (parts in parallel, then complete), progressive (parts readable as they land, no complete) or url (copied by the job that was given the URL; completed once the copy is done).

string

Allowed value: progressive

part_size

required

number

parts

required

Array<object>

object

part_number

required

number

url

required

string

headers

required

object

key

additional properties

string

expires_in

required

number

id

required

string

object

required

string

Allowed value: upload

status

required

completed once the whole file is stored.

string

Allowed values: pending completed

file_name

required

string

size

required

number | null

source_url

required

Where an imported source came from.

string | null

created_at

required

string format: date-time

completed_at

required

string | null format: date-time

Example

{
  "mode": "single",
  "method": "PUT",
  "object": "upload",
  "status": "pending"
}

400

Invalid fields: details lists each problem with its path.

Media typeapplication/json

object

error

required

object

code

required

Stable: branch on it.

string

Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable

message

required

English, for people; may change.

string

details

required

Each problem, as path: message (validation errors).

Array<string>

Example

{
  "error": {
    "code": "validation_error"
  }
}

401

The API key is missing, invalid or revoked.

Media typeapplication/json

object

error

required

object

code

required

Stable: branch on it.

string

Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable

message

required

English, for people; may change.

string

details

required

Each problem, as path: message (validation errors).

Array<string>

Example

{
  "error": {
    "code": "validation_error"
  }
}

402

The plan doesn’t allow it (minutes this month, file size: quota_exceeded), or the balance is used up and has to be topped up (insufficient_balance).

Media typeapplication/json

object

error

required

object

code

required

Stable: branch on it.

string

Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable

message

required

English, for people; may change.

string

details

required

Each problem, as path: message (validation errors).

Array<string>

Example

{
  "error": {
    "code": "validation_error"
  }
}

403

Valid credentials that may not do this (forbidden), your plan doesn’t include the module the route belongs to (module_not_in_plan), or your organization is suspended (organization_suspended).

Media typeapplication/json

object

error

required

object

code

required

Stable: branch on it.

string

Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable

message

required

English, for people; may change.

string

details

required

Each problem, as path: message (validation errors).

Array<string>

Example

{
  "error": {
    "code": "validation_error"
  }
}

429

Too many requests: wait and retry. Answered by the gateway, so the body may differ.

Media typeapplication/json

object

error

required

object

code

required

Stable: branch on it.

string

Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable

message

required

English, for people; may change.

string

details

required

Each problem, as path: message (validation errors).

Array<string>

Example

{
  "error": {
    "code": "validation_error"
  }
}

500

Ours: retry, and tell us if it persists.

Media typeapplication/json

object

error

required

object

code

required

Stable: branch on it.

string

Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable

message

required

English, for people; may change.

string

details

required

Each problem, as path: message (validation errors).

Array<string>

Example

{
  "error": {
    "code": "validation_error"
  }
}

503

Momentarily unavailable: retry in a few seconds.

Media typeapplication/json

object

error

required

object

code

required

Stable: branch on it.

string

Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable

message

required

English, for people; may change.

string

details

required

Each problem, as path: message (validation errors).

Array<string>

Example

{
  "error": {
    "code": "validation_error"
  }
}