Initiate multipart uploads for a set of files

POST

files

upload

multipart

batch

Initiate multipart uploads for a set of files

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/files/upload/multipart/batch \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "files": [
    {
      "fileName": "stmt-a.pdf",
      "fileType": "application/pdf",
      "fileSize": 412,
      "partSizeLimit": 16,
      "isSplit": false,
      "isSplitExcel": false,
      "callbackURL": "https://example.com/callback",
      "ocrModel": "Beethoven_ENG_O5.6",
      "schemaLocking": false,
      "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
      "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
      "destinationPath": "statements/q3",
      "isEphemeral": false,
      "pageCount": 1100,
      "retainOriginalZipFileName": false
    }
  ],
  "defaults": {
    "partSizeLimit": 32,
    "isSplit": false,
    "isSplitExcel": false,
    "callbackURL": "https://example.com/callback",
    "ocrModel": "Beethoven_ENG_O5.6",
    "schemaLocking": false,
    "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
    "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
    "destinationPath": "statements/q3",
    "isEphemeral": false,
    "retainOriginalZipFileName": false,
    "apiRequestId": "my-batch-request-123"
  }
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/files/upload/multipart/batch"

payload = {
    "files": [
        {
            "fileName": "stmt-a.pdf",
            "fileType": "application/pdf",
            "fileSize": 412,
            "partSizeLimit": 16,
            "isSplit": False,
            "isSplitExcel": False,
            "callbackURL": "https://example.com/callback",
            "ocrModel": "Beethoven_ENG_O5.6",
            "schemaLocking": False,
            "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
            "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
            "destinationPath": "statements/q3",
            "isEphemeral": False,
            "pageCount": 1100,
            "retainOriginalZipFileName": False
        }
    ],
    "defaults": {
        "partSizeLimit": 32,
        "isSplit": False,
        "isSplitExcel": False,
        "callbackURL": "https://example.com/callback",
        "ocrModel": "Beethoven_ENG_O5.6",
        "schemaLocking": False,
        "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
        "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
        "destinationPath": "statements/q3",
        "isEphemeral": False,
        "retainOriginalZipFileName": False,
        "apiRequestId": "my-batch-request-123"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    files: [
      {
        fileName: 'stmt-a.pdf',
        fileType: 'application/pdf',
        fileSize: 412,
        partSizeLimit: 16,
        isSplit: false,
        isSplitExcel: false,
        callbackURL: 'https://example.com/callback',
        ocrModel: 'Beethoven_ENG_O5.6',
        schemaLocking: false,
        directoryId: '649e2d2d2d2d2d2d2d2d2d2d',
        blueprintId: '649e2d2d2d2d2d2d2d2d2d2d',
        destinationPath: 'statements/q3',
        isEphemeral: false,
        pageCount: 1100,
        retainOriginalZipFileName: false
      }
    ],
    defaults: {
      partSizeLimit: 32,
      isSplit: false,
      isSplitExcel: false,
      callbackURL: 'https://example.com/callback',
      ocrModel: 'Beethoven_ENG_O5.6',
      schemaLocking: false,
      directoryId: '649e2d2d2d2d2d2d2d2d2d2d',
      blueprintId: '649e2d2d2d2d2d2d2d2d2d2d',
      destinationPath: 'statements/q3',
      isEphemeral: false,
      retainOriginalZipFileName: false,
      apiRequestId: 'my-batch-request-123'
    }
  })
};

fetch('https://api.orion.file.ai/prod/v1/files/upload/multipart/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T",
  "apiRequestId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T",
  "accepted": 2,
  "rejected": 1,
  "results": [
    {
      "index": 0,
      "status": "accepted",
      "fileName": "stmt-a.pdf",
      "uploadId": "upload_aws_xyz789",
      "fileId": "file_abc123xyz",
      "key": "uploads/devices/workspaces/456/organizations/123/files/file_abc/file_abc#stmt-a.pdf",
      "s3Path": "s3://bucket/uploads/devices/workspaces/456/organizations/123/files/file_abc/file_abc#stmt-a.pdf",
      "partSize": 33554432,
      "totalParts": 13,
      "totalSize": 432013312,
      "urlsExpireAt": "2026-08-19T10:15:00.000Z",
      "presignedUrls": [
        {
          "partNumber": 1,
          "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
          "startByte": 0,
          "endByte": 33554432,
          "size": 33554432
        }
      ]
    },
    {
      "index": 1,
      "status": "accepted",
      "fileName": "stmt-b.pdf",
      "uploadId": "upload_aws_xyz790",
      "fileId": "file_abc123xy0",
      "key": "uploads/devices/workspaces/456/organizations/123/files/file_abd/file_abd#stmt-b.pdf",
      "partSize": 16777216,
      "totalParts": 25,
      "totalSize": 406847488,
      "urlsExpireAt": "2026-08-19T10:15:00.000Z",
      "presignedUrls": [
        {
          "partNumber": 1,
          "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
          "startByte": 0,
          "endByte": 16777216,
          "size": 16777216
        }
      ]
    },
    {
      "index": 2,
      "status": "rejected",
      "fileName": "empty.pdf",
      "error": {
        "status": 422,
        "code": "VALIDATION_FAILED",
        "detail": "Invalid fileSize. Must be greater than 0."
      }
    }
  ]
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

Request · Guide: Upload files

More details

Accepts up to 25 files in files, and at most 2500 presigned part URLs across the whole batch — a batch over that combined cap is rejected with BATCH_PARTS_TOO_LARGE, and nothing is created. Split the batch, or raise partSizeLimit so the same bytes need fewer parts.Part sizing is unchanged: for a given fileSize and partSizeLimit, a file in a batch gets exactly the partSize and totalParts the single-file endpoint would return for it.defaults supplies values for files that omit them; a per-file value always wins, including an explicit false. Every field a file may carry is the one the single-file endpoint accepts.Files are accepted or rejected independently: a descriptor that fails validation is returned as rejected with its own error, and its siblings are still initiated. Check accepted / rejected and the per-file status — a response where every file is rejected is still a 201.Each part URL is valid for 900 seconds. For a transfer that runs past that, re-sign just the parts still outstanding with POST /v1/files/upload/multipart/urls/refresh; parts already uploaded stay uploaded.Then finalize with POST /v1/files/upload/multipart/complete/batch.This response is the only copy of the upload handles it creates, and it is too large to cache, so Idempotency-Key is accepted but ignored here — a retry initiates a fresh set of uploads rather than replaying the first. Abandoned uploads expire under the bucket lifecycle policy. The complete endpoint IS idempotent.Note the field names, which differ from the single-file response: here uploadId is the S3 multipart upload id — the value to send as id when completing or refreshing — and fileId is the internal file id. The single-file endpoint calls them id and uploadId.

Authorizations

x-api-key

string

header

required

API key for authentication

Headers

Idempotency-Key

string

Accepted for client uniformity but IGNORED on this endpoint. Its response is the only copy of the upload handles it creates and is far larger than the idempotency cache can hold, so a replay would return a placeholder carrying none of them. The key is accepted and ignored rather than trading a duplicate set of uploads — which the lifecycle policy sweeps — for handles that cannot be recovered. Every request executes fresh: no 24h window, no replay, no Idempotent-Replayed header, and no key-reuse 422.

Body

application/json

files

object[]

required

Files to initiate, at most 25 per request. Each item is validated on its own: a bad descriptor is rejected without affecting its siblings.

Required array length: 1 - 25 elements

Show child attributes

defaults

object

Values applied to every file that does not set them itself. A per-file value always wins.

Show child attributes

Response

The batch was processed. Inspect results for each file's outcome — a batch where every file was rejected is still a 201.

Initiate multipart uploads for a set of files

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/files/upload/multipart/batch \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "files": [
    {
      "fileName": "stmt-a.pdf",
      "fileType": "application/pdf",
      "fileSize": 412,
      "partSizeLimit": 16,
      "isSplit": false,
      "isSplitExcel": false,
      "callbackURL": "https://example.com/callback",
      "ocrModel": "Beethoven_ENG_O5.6",
      "schemaLocking": false,
      "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
      "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
      "destinationPath": "statements/q3",
      "isEphemeral": false,
      "pageCount": 1100,
      "retainOriginalZipFileName": false
    }
  ],
  "defaults": {
    "partSizeLimit": 32,
    "isSplit": false,
    "isSplitExcel": false,
    "callbackURL": "https://example.com/callback",
    "ocrModel": "Beethoven_ENG_O5.6",
    "schemaLocking": false,
    "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
    "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
    "destinationPath": "statements/q3",
    "isEphemeral": false,
    "retainOriginalZipFileName": false,
    "apiRequestId": "my-batch-request-123"
  }
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/files/upload/multipart/batch"

payload = {
    "files": [
        {
            "fileName": "stmt-a.pdf",
            "fileType": "application/pdf",
            "fileSize": 412,
            "partSizeLimit": 16,
            "isSplit": False,
            "isSplitExcel": False,
            "callbackURL": "https://example.com/callback",
            "ocrModel": "Beethoven_ENG_O5.6",
            "schemaLocking": False,
            "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
            "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
            "destinationPath": "statements/q3",
            "isEphemeral": False,
            "pageCount": 1100,
            "retainOriginalZipFileName": False
        }
    ],
    "defaults": {
        "partSizeLimit": 32,
        "isSplit": False,
        "isSplitExcel": False,
        "callbackURL": "https://example.com/callback",
        "ocrModel": "Beethoven_ENG_O5.6",
        "schemaLocking": False,
        "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
        "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
        "destinationPath": "statements/q3",
        "isEphemeral": False,
        "retainOriginalZipFileName": False,
        "apiRequestId": "my-batch-request-123"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    files: [
      {
        fileName: 'stmt-a.pdf',
        fileType: 'application/pdf',
        fileSize: 412,
        partSizeLimit: 16,
        isSplit: false,
        isSplitExcel: false,
        callbackURL: 'https://example.com/callback',
        ocrModel: 'Beethoven_ENG_O5.6',
        schemaLocking: false,
        directoryId: '649e2d2d2d2d2d2d2d2d2d2d',
        blueprintId: '649e2d2d2d2d2d2d2d2d2d2d',
        destinationPath: 'statements/q3',
        isEphemeral: false,
        pageCount: 1100,
        retainOriginalZipFileName: false
      }
    ],
    defaults: {
      partSizeLimit: 32,
      isSplit: false,
      isSplitExcel: false,
      callbackURL: 'https://example.com/callback',
      ocrModel: 'Beethoven_ENG_O5.6',
      schemaLocking: false,
      directoryId: '649e2d2d2d2d2d2d2d2d2d2d',
      blueprintId: '649e2d2d2d2d2d2d2d2d2d2d',
      destinationPath: 'statements/q3',
      isEphemeral: false,
      retainOriginalZipFileName: false,
      apiRequestId: 'my-batch-request-123'
    }
  })
};

fetch('https://api.orion.file.ai/prod/v1/files/upload/multipart/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T",
  "apiRequestId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T",
  "accepted": 2,
  "rejected": 1,
  "results": [
    {
      "index": 0,
      "status": "accepted",
      "fileName": "stmt-a.pdf",
      "uploadId": "upload_aws_xyz789",
      "fileId": "file_abc123xyz",
      "key": "uploads/devices/workspaces/456/organizations/123/files/file_abc/file_abc#stmt-a.pdf",
      "s3Path": "s3://bucket/uploads/devices/workspaces/456/organizations/123/files/file_abc/file_abc#stmt-a.pdf",
      "partSize": 33554432,
      "totalParts": 13,
      "totalSize": 432013312,
      "urlsExpireAt": "2026-08-19T10:15:00.000Z",
      "presignedUrls": [
        {
          "partNumber": 1,
          "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
          "startByte": 0,
          "endByte": 33554432,
          "size": 33554432
        }
      ]
    },
    {
      "index": 1,
      "status": "accepted",
      "fileName": "stmt-b.pdf",
      "uploadId": "upload_aws_xyz790",
      "fileId": "file_abc123xy0",
      "key": "uploads/devices/workspaces/456/organizations/123/files/file_abd/file_abd#stmt-b.pdf",
      "partSize": 16777216,
      "totalParts": 25,
      "totalSize": 406847488,
      "urlsExpireAt": "2026-08-19T10:15:00.000Z",
      "presignedUrls": [
        {
          "partNumber": 1,
          "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
          "startByte": 0,
          "endByte": 16777216,
          "size": 16777216
        }
      ]
    },
    {
      "index": 2,
      "status": "rejected",
      "fileName": "empty.pdf",
      "error": {
        "status": 422,
        "code": "VALIDATION_FAILED",
        "detail": "Invalid fileSize. Must be greater than 0."
      }
    }
  ]
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}