Upload a file for an import/upload task

The URL comes from result.form.url of the task and already holds the signed parameters. Send the file as multipart/form-data in the field file. No API key needed. Other form fields are ignored. At most 100 MB per request; send larger files with a PUT to result.upload.url.

POSThttps://api.switchfile.io/upload/{taskId}

No API key needed.

Example

Request

curl "https://api.switchfile.io/upload/c1f3a9d2-7e44-4b0a-a1b5-2f0e8c9d6a31?expires=1762538401&max_file_size=1073741824&signature=8d2e4f6a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d1e" \
  -F [email protected]

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("report.docx")]), "report.docx");

const res = await fetch("https://api.switchfile.io/upload/c1f3a9d2-7e44-4b0a-a1b5-2f0e8c9d6a31?expires=1762538401&max_file_size=1073741824&signature=8d2e4f6a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d1e", {
  method: "POST",
  body: form,
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

<?php
$ch = curl_init('https://api.switchfile.io/upload/c1f3a9d2-7e44-4b0a-a1b5-2f0e8c9d6a31?expires=1762538401&max_file_size=1073741824&signature=8d2e4f6a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d1e');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('report.docx'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("HTTP $status: $response");
}
print_r(json_decode($response, true));

import requests

res = requests.post(
    "https://api.switchfile.io/upload/c1f3a9d2-7e44-4b0a-a1b5-2f0e8c9d6a31?expires=1762538401&max_file_size=1073741824&signature=8d2e4f6a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d1e",
    files={"file": open("report.docx", "rb")},
)
res.raise_for_status()
print(res.json())

Parameters

Path parameters

taskIdstring (uuid)required
ID of the import/upload task

Query parameters

expiresnumberrequired
Part of the signed URL
example: 1762538401
max_file_sizenumberrequired
Part of the signed URL
example: 1073741824
signaturestringrequired
Part of the signed URL
at least 1 characters · example: 8d2e4f6a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d1e
max_file_countnumber
Part of the signed URL

Request body

expiresinteger
filefilerequired
max_file_countinteger
max_file_sizeinteger
signaturestring

Responses

201Stored. The task is finished
dataTaskDetailrequired
data.codestring | nullrequired
data.copy_of_task_idstring (uuid) | nullrequired
data.created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.creditsstring (integer) | integerrequired
data.depends_on_task_idsstring (uuid)[]required
data.depends_on_tasksmap of string (uuid)
Name and ID of each input task
keys match ^(.*)$
data.ended_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.enginestring | nullrequired
Internal identifier, may change. Do not rely on its value
data.engine_versionstring | nullrequired
Internal identifier, may change. Do not rely on its value
data.host_namestring | nullrequired
data.idstring (uuid)required
data.jobJob
data.job.created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.job.ended_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.job.idstring (uuid)required
data.job.linksobjectrequired
data.job.links.selfstringrequired
data.job.started_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.job.statusstringrequired
one of "waiting", "processing", "finished", "error"
data.job.tagstring | nullrequired
data.job.tasksTask[]
data.job.tasks[].codestring | nullrequired
data.job.tasks[].copy_of_task_idstring (uuid) | nullrequired
data.job.tasks[].created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.job.tasks[].creditsstring (integer) | integerrequired
data.job.tasks[].depends_on_task_idsstring (uuid)[]required
data.job.tasks[].ended_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.job.tasks[].enginestring | nullrequired
Internal identifier, may change. Do not rely on its value
data.job.tasks[].engine_versionstring | nullrequired
Internal identifier, may change. Do not rely on its value
data.job.tasks[].host_namestring | nullrequired
data.job.tasks[].idstring (uuid)required
data.job.tasks[].job_idstring (uuid)required
data.job.tasks[].linksobjectrequired
data.job.tasks[].messagestring | nullrequired
data.job.tasks[].namestringrequired
data.job.tasks[].operationstringrequired
data.job.tasks[].percentstring (integer) | integerrequired
Progress as in CloudConvert: 100 when finished, otherwise 0
0 to 100
data.job.tasks[].prioritystring (integer) | integerrequired
data.job.tasks[].regionstringrequired
Region the task runs in (eu-central)
data.job.tasks[].resultTaskResultrequired
data.job.tasks[].retry_of_task_idstring (uuid) | nullrequired
data.job.tasks[].started_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.job.tasks[].statusstringrequired
one of "waiting", "processing", "finished", "error"
data.job.tasks[].storagestring | nullrequired
data.job.tasks[].user_idstring | nullrequired
Account of the job (opaque ID, the same as data.id in /v2/users/me)
data.job.tasks[].waiting_forstring
What a waiting task waits for, one of "upload", "inputs", "queued". Only set while status is waiting
data.job_idstring (uuid)required
data.linksobjectrequired
data.links.selfstringrequired
data.messagestring | nullrequired
data.namestringrequired
data.operationstringrequired
data.payloadmap of any
keys match ^(.*)$
data.percentstring (integer) | integerrequired
Progress as in CloudConvert: 100 when finished, otherwise 0
0 to 100
data.prioritystring (integer) | integerrequired
data.regionstringrequired
Region the task runs in (eu-central)
data.resultTaskResultrequired
data.result.filesResultFile[]
data.result.files[].detected_input_formatstring
convert only: the format the input actually had, when it differs from the given format or the file extension (for example a PNG file named .jpg)
data.result.files[].filenamestringrequired
data.result.files[].notesstring[]
convert only: notes when the output differs from the request, for example a frame rate the target format does not support that was set to the nearest allowed value
data.result.files[].sizestring (integer) | integer
data.result.files[].urlstring
data.result.formUploadForm
data.result.form.parametersobjectrequired
data.result.form.urlstringrequired
data.result.uploadDirectUpload
import/upload only: a signed URL for large files, without the 100 MB limit of result.form. The task finishes on its own a few seconds after the PUT. Call POST /v2/tasks/{id}/upload-complete to finish it right away.
data.result.upload.expires_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.result.upload.headersmap of stringrequired
Headers the PUT request must send (usually none)
keys match ^(.*)$
data.result.upload.max_file_sizestring (integer) | integerrequired
Largest allowed file in bytes. A larger upload makes the task fail
data.result.upload.methodstringrequired
one of "PUT"
data.result.upload.urlstringrequired
Signed URL. Send the file as the raw body of a PUT request, not as a form
data.retriesTask[]
data.retries[].codestring | nullrequired
data.retries[].copy_of_task_idstring (uuid) | nullrequired
data.retries[].created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.retries[].creditsstring (integer) | integerrequired
data.retries[].depends_on_task_idsstring (uuid)[]required
data.retries[].ended_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.retries[].enginestring | nullrequired
Internal identifier, may change. Do not rely on its value
data.retries[].engine_versionstring | nullrequired
Internal identifier, may change. Do not rely on its value
data.retries[].host_namestring | nullrequired
data.retries[].idstring (uuid)required
data.retries[].job_idstring (uuid)required
data.retries[].linksobjectrequired
data.retries[].links.selfstringrequired
data.retries[].messagestring | nullrequired
data.retries[].namestringrequired
data.retries[].operationstringrequired
data.retries[].percentstring (integer) | integerrequired
Progress as in CloudConvert: 100 when finished, otherwise 0
0 to 100
data.retries[].prioritystring (integer) | integerrequired
data.retries[].regionstringrequired
Region the task runs in (eu-central)
data.retries[].resultTaskResultrequired
data.retries[].result.filesResultFile[]
data.retries[].result.formUploadForm
data.retries[].result.uploadDirectUpload
import/upload only: a signed URL for large files, without the 100 MB limit of result.form. The task finishes on its own a few seconds after the PUT. Call POST /v2/tasks/{id}/upload-complete to finish it right away.
data.retries[].retry_of_task_idstring (uuid) | nullrequired
data.retries[].started_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.retries[].statusstringrequired
one of "waiting", "processing", "finished", "error"
data.retries[].storagestring | nullrequired
data.retries[].user_idstring | nullrequired
Account of the job (opaque ID, the same as data.id in /v2/users/me)
data.retries[].waiting_forstring
What a waiting task waits for, one of "upload", "inputs", "queued". Only set while status is waiting
data.retry_of_task_idstring (uuid) | nullrequired
data.started_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data.statusstringrequired
one of "waiting", "processing", "finished", "error"
data.storagestring | nullrequired
data.user_idstring | nullrequired
Account of the job (opaque ID, the same as data.id in /v2/users/me)
data.waiting_forstring
What a waiting task waits for, one of "upload", "inputs", "queued". Only set while status is waiting
201 application/json
```
{
  "data": {
    "id": "c1f3a9d2-7e44-4b0a-a1b5-2f0e8c9d6a31",
    "job_id": "6e2c1b1f-3c1a-4d4e-9a57-0d7b2f6a8e10",
    "name": "upload-1",
    "operation": "import/upload",
    "status": "finished",
    "message": null,
    "code": null,
    "credits": 0,
    "created_at": "2026-11-06T18:00:00+00:00",
    "started_at": "2026-11-06T18:00:00+00:00",
    "ended_at": "2026-11-06T18:00:01+00:00",
    "depends_on_task_ids": [],
    "retry_of_task_id": null,
    "copy_of_task_id": null,
    "priority": 0,
    "host_name": null,
    "storage": null,
    "engine": null,
    "engine_version": null,
    "percent": 100,
    "region": "eu-central",
    "user_id": "4f8a2c6e-1b3d-4e5f-8a7c-9d0b2e4f6a18",
    "result": {
      "files": [
        {
          "filename": "report.docx",
          "size": 48213
        }
      ]
    },
    "links": {
      "self": "https://api.switchfile.io/v2/tasks/c1f3a9d2-7e44-4b0a-a1b5-2f0e8c9d6a31"
    }
  }
}
```
403The signature is wrong or the form has expiredEXPIRED
403 application/json
```
{
  "message": "The upload form has expired.",
  "code": "EXPIRED"
}
```
404Does not exist for this accountNOT_FOUND
404 application/json
```
{
  "message": "Task not found.",
  "code": "NOT_FOUND"
}
```

413The request or the file is too largeFILE_TOO_LARGE

413 application/json

{
  "message": "The file is larger than the allowed maximum.",
  "code": "FILE_TOO_LARGE"
}

422A file was already uploaded for this taskINVALID_DATA

422 application/json

{
  "message": "file: A file was already uploaded for this task.",
  "code": "INVALID_DATA",
  "errors": {
    "file": [
      "A file was already uploaded for this task."
    ]
  }
}

429Too many requests or a daily quota is used up. See Retry-AfterRATE_LIMIT_EXCEEDED
429 application/json
```
{
  "message": "Too many requests. Try again in 12 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

Error bodies and codes are explained in Errors.