Create a ZIP archive

Example

curl "https://api.switchfile.io/v1/archives" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversions": [
      "0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10",
      "3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35"
    ]
  }'

const res = await fetch("https://api.switchfile.io/v1/archives", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SWITCHFILE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    conversions: [
      "0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10",
      "3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35"
    ]
  }),
});
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/v1/archives');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'conversions' => [
            '0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10',
            '3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35',
        ],
    ]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SWITCHFILE_API_KEY'),
        'Content-Type: application/json',
    ],
    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 os
import requests

res = requests.post(
    "https://api.switchfile.io/v1/archives",
    headers={"Authorization": f"Bearer {os.environ['SWITCHFILE_API_KEY']}"},
    json={
        "conversions": [
            "0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10",
            "3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35",
        ],
    },
)
res.raise_for_status()
print(res.json())

Parameters

Request body

Responses

• 201Created

  • expires_atstringrequired

    url works until this time, at most until the first included conversion is deleted

  • filesstring (integer) | integerrequired

    Number of files in the ZIP when it was created

    at least 0

  • idstring (uuid)required
  • objectstringrequired

    one of "archive"

  • urlstringrequired

    Signed URL of the ZIP file, works without an API key

  201 application/jsonCopy

  {
    "object": "archive",
    "id": "9f0c4e2a-1b7d-4c3e-a5f6-2d8e7b6a1c90",
    "url": "https://api.switchfile.io/v1/archives/9f0c4e2a-1b7d-4c3e-a5f6-2d8e7b6a1c90?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8",
    "expires_at": "2026-11-07T18:00:02+00:00",
    "files": 2
  }

• 401The API key is missing or not validUNAUTHENTICATED

  401 application/problem+jsonCopy

  {
    "type": "https://switchfile.io/docs/api/v1#errors-unauthenticated",
    "title": "Unauthenticated",
    "status": 401,
    "code": "UNAUTHENTICATED",
    "detail": "Missing or invalid API key."
  }

• 403Not allowed: a signed URL is wrong or expired, or X-End-User was sent without a service keyEND_USER_NOT_ALLOWED

  403 application/problem+jsonCopy

  {
    "type": "https://switchfile.io/docs/api/v1#errors-end-user-not-allowed",
    "title": "End user not allowed",
    "status": 403,
    "code": "END_USER_NOT_ALLOWED",
    "detail": "The X-End-User header is only allowed with a service key."
  }

• 404An ID is unknown. index names itNOT_FOUND

  404 application/problem+jsonCopy

  {
    "type": "https://switchfile.io/docs/api/v1#errors-not-found",
    "title": "Not found",
    "status": 404,
    "code": "NOT_FOUND",
    "detail": "Conversion not found.",
    "index": 1
  }

• 409A conversion is still running or has failed. index names itCONVERSION_NOT_FINISHED

  409 application/problem+jsonCopy

  {
    "type": "https://switchfile.io/docs/api/v1#errors-conversion-not-finished",
    "title": "Conversion not finished",
    "status": 409,
    "code": "CONVERSION_NOT_FINISHED",
    "detail": "The conversion is not finished.",
    "index": 0
  }

• 411The request has a body but no Content-Length headerLENGTH_REQUIRED

  411 application/problem+jsonCopy

  {
    "type": "https://switchfile.io/docs/api/v1#errors-length-required",
    "title": "Length required",
    "status": 411,
    "code": "LENGTH_REQUIRED",
    "detail": "A Content-Length header is required for this request."
  }

• 413The request or the file is too largeFILE_TOO_LARGE

  413 application/problem+jsonCopy

  {
    "type": "https://switchfile.io/docs/api/v1#errors-file-too-large",
    "title": "File too large",
    "status": 413,
    "code": "FILE_TOO_LARGE",
    "detail": "The file is larger than the allowed maximum."
  }

• 422Invalid data. errors names the fieldsINVALID_DATA

  422 application/problem+jsonCopy

  {
    "type": "https://switchfile.io/docs/api/v1#errors-invalid-data",
    "title": "Invalid data",
    "status": 422,
    "code": "INVALID_DATA",
    "detail": "The request contains invalid data.",
    "errors": {
      "to": [
        "Expected string"
      ]
    }
  }

• 429Too many requests or a daily quota is used up. See Retry-AfterRATE_LIMIT_EXCEEDED

  429 application/problem+jsonCopy

  {
    "type": "https://switchfile.io/docs/api/v1#errors-rate-limit-exceeded",
    "title": "Rate limit exceeded",
    "status": 429,
    "code": "RATE_LIMIT_EXCEEDED",
    "detail": "Too many requests. Try again in 12 seconds."
  }

Error bodies and codes are explained in Errors.