Upload a large file using multipart upload

POST

files

upload

multipart

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/files/upload/multipart \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileName": "large-file.pdf",
  "fileType": "application/pdf",
  "fileSize": 150.5,
  "partSizeLimit": 10,
  "isSplit": false,
  "isSplitExcel": false,
  "callbackURL": "https://example.com/callback",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "isEphemeral": false,
  "pageCount": 50,
  "apiRequestId": "my-batch-request-123",
  "retainOriginalZipFileName": false
}
'

import requests

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

payload = {
    "fileName": "large-file.pdf",
    "fileType": "application/pdf",
    "fileSize": 150.5,
    "partSizeLimit": 10,
    "isSplit": False,
    "isSplitExcel": False,
    "callbackURL": "https://example.com/callback",
    "ocrModel": "Beethoven_ENG_O5.6",
    "schemaLocking": False,
    "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
    "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
    "destinationPath": "mammals/walrus",
    "isEphemeral": False,
    "pageCount": 50,
    "apiRequestId": "my-batch-request-123",
    "retainOriginalZipFileName": False
}
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({
    fileName: 'large-file.pdf',
    fileType: 'application/pdf',
    fileSize: 150.5,
    partSizeLimit: 10,
    isSplit: false,
    isSplitExcel: false,
    callbackURL: 'https://example.com/callback',
    ocrModel: 'Beethoven_ENG_O5.6',
    schemaLocking: false,
    directoryId: '649e2d2d2d2d2d2d2d2d2d2d',
    blueprintId: '649e2d2d2d2d2d2d2d2d2d2d',
    destinationPath: 'mammals/walrus',
    isEphemeral: false,
    pageCount: 50,
    apiRequestId: 'my-batch-request-123',
    retainOriginalZipFileName: false
  })
};

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

{
  "id": "upload_aws_xyz789",
  "key": "org_123/workspace_456/device/file_abc/document.pdf",
  "s3Path": "s3://bucket/org_123/workspace_456/device/file_abc/document.pdf",
  "partSize": 6291456,
  "totalParts": 2,
  "totalSize": 9123430,
  "presignedUrls": [
    {
      "partNumber": 1,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 0,
      "endByte": 6291455,
      "size": 6291456
    },
    {
      "partNumber": 2,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 6291456,
      "endByte": 9123429,
      "size": 2831974
    }
  ],
  "uploadId": "file_abc123xyz",
  "callbackURL": "https://example.com/callback",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": true,
  "isSplit": false,
  "isSplitExcel": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "blueprintId": "649e2d2d2d2d2d2d2d2d2d2e",
  "isEphemeral": false
}

Request · Guide: Upload files

More details

Each presigned URL is valid for 900 seconds (15 minutes) and can be used multiple times.The workflow is:

Call this endpoint to get presigned URLs for each part
Upload each part to its respective presigned URL using PUT requests
Call the complete multipart upload endpoint with all part ETags

The input should contain:

fileName: the name of the file to be uploaded
fileType: the MIME type of the file
fileSize: the size of the file in MB
partSizeLimit: (optional) the size limit for each part in MB
isSplit: whether the file should be split after upload (optional, default: false)
isSplitExcel: whether to split Excel files by worksheets (optional, default: false)
callbackURL: the url that will be called after processing (optional)
ocrModel: the OCR model to use (optional)
schemaLocking: whether the schema should be locked (optional)
directoryId: the directory id where the file should be uploaded (optional)
destinationPath: slash-delimited folder path where the file should be placed (e.g. “mammals/walrus”). Folders are auto-created if they do not exist. Can be used together with directoryId (optional)
blueprintId: the file type id (from GET /file-type) to use for every document in the file, skipping auto-classification. Must be an approved file type in your organization or a built-in one (optional)
isEphemeral: whether the file and all related data should be deleted after the file is processed, must be one of true or false (optional, default: false)
pageCount: page count of the file, used for early validation against page limits (optional)

Authorizations

x-api-key

string

header

required

API key for authentication

Headers

Idempotency-Key

string

Optional opaque key (max 255 chars, UUIDv4 recommended) making this request idempotent for 24h: a retry with the same key and body replays the original response with Idempotent-Replayed: true.

Body

application/json

fileName

string

required

File name

Example:

"large-file.pdf"

fileType

string

required

File type

Example:

"application/pdf"

fileSize

number

required

File size in MB

Example:

150.5

partSizeLimit

number

Part size limit in MB (optional, default will be calculated)

Example:

10

isSplit

boolean

default:false

Is split

Example:

false

isSplitExcel

boolean

Is split excel - whether to split Excel files by worksheets

Example:

false

callbackURL

string

Callback URL

Example:

"https://example.com/callback"

ocrModel

enum<string>

OCR model

Available options:

Beethoven_ENG_O5.6,

Beethoven_ENG_G5.5,

Beethoven_ENG_GP25,

Beethoven_ENG_GP25.1,

Beethoven_ENG_GP25.2,

Beethoven_CUS_O5.1,

Beethoven_CUS_O5.2,

Unified (google-document-ai-ocr-gemini-v10),

Aegis (google-document-ai-ocr-gemini-aegis-v1),

Beethoven_ZH_O5.9,

Beethoven_JP_O5.3,

Beethoven_JP_G5.4,

Beethoven_TH_O5.1,

Beethoven_TH_G5.1,

Beethoven_CUS_GP25.1,

Beethoven_Direct_Form_Filling (GP2.5),

Capybara (Experimental)

Example:

"Beethoven_ENG_O5.6"

schemaLocking

boolean

Schema locking

Example:

false

directoryId

string

Directory Id

Example:

"649e2d2d2d2d2d2d2d2d2d2d"

blueprintId

string

File type id (the blueprintId from GET /file-type). Pre-selects that file type and its schema for every document in the file, skipping auto-classification. Must be an approved file type in your organization or a built-in one.

Example:

"649e2d2d2d2d2d2d2d2d2d2d"

destinationPath

string

Slash-delimited folder path for the uploaded document (e.g. "mammals/walrus"). Folders are auto-created if they do not exist. Can be used together with directoryId.

Example:

"mammals/walrus"

isEphemeral

boolean

Is ephemeral

Example:

false

pageCount

number

Page count of the PDF file. Used for early validation against page limits.

Example:

50

apiRequestId

string

Optional request ID to group files uploaded in the same API session. If not provided, one is auto-generated.

Example:

"my-batch-request-123"

retainOriginalZipFileName

boolean

default:false

Retain the original file name of a ZIP upload. Only applies to zip uploads (fileType "application/zip" or a .zip file name) and is ignored for all other files. When true, the original zip name is preserved (control characters, path separators and ".." are stripped, leading/trailing dots and whitespace trimmed, capped at 255 characters) and surfaced on the extracted files as zipArchiveName. When false (default), the name is sanitized as before.

Example:

false

Response

Multipart upload initiated successfully. Use the presigned URLs to upload each part.

Upload a large file using multipart upload

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/files/upload/multipart \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileName": "large-file.pdf",
  "fileType": "application/pdf",
  "fileSize": 150.5,
  "partSizeLimit": 10,
  "isSplit": false,
  "isSplitExcel": false,
  "callbackURL": "https://example.com/callback",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "isEphemeral": false,
  "pageCount": 50,
  "apiRequestId": "my-batch-request-123",
  "retainOriginalZipFileName": false
}
'

import requests

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

payload = {
    "fileName": "large-file.pdf",
    "fileType": "application/pdf",
    "fileSize": 150.5,
    "partSizeLimit": 10,
    "isSplit": False,
    "isSplitExcel": False,
    "callbackURL": "https://example.com/callback",
    "ocrModel": "Beethoven_ENG_O5.6",
    "schemaLocking": False,
    "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
    "blueprintId": "649e2d2d2d2d2d2d2d2d2d2d",
    "destinationPath": "mammals/walrus",
    "isEphemeral": False,
    "pageCount": 50,
    "apiRequestId": "my-batch-request-123",
    "retainOriginalZipFileName": False
}
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({
    fileName: 'large-file.pdf',
    fileType: 'application/pdf',
    fileSize: 150.5,
    partSizeLimit: 10,
    isSplit: false,
    isSplitExcel: false,
    callbackURL: 'https://example.com/callback',
    ocrModel: 'Beethoven_ENG_O5.6',
    schemaLocking: false,
    directoryId: '649e2d2d2d2d2d2d2d2d2d2d',
    blueprintId: '649e2d2d2d2d2d2d2d2d2d2d',
    destinationPath: 'mammals/walrus',
    isEphemeral: false,
    pageCount: 50,
    apiRequestId: 'my-batch-request-123',
    retainOriginalZipFileName: false
  })
};

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

{
  "id": "upload_aws_xyz789",
  "key": "org_123/workspace_456/device/file_abc/document.pdf",
  "s3Path": "s3://bucket/org_123/workspace_456/device/file_abc/document.pdf",
  "partSize": 6291456,
  "totalParts": 2,
  "totalSize": 9123430,
  "presignedUrls": [
    {
      "partNumber": 1,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 0,
      "endByte": 6291455,
      "size": 6291456
    },
    {
      "partNumber": 2,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 6291456,
      "endByte": 9123429,
      "size": 2831974
    }
  ],
  "uploadId": "file_abc123xyz",
  "callbackURL": "https://example.com/callback",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": true,
  "isSplit": false,
  "isSplitExcel": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "blueprintId": "649e2d2d2d2d2d2d2d2d2d2e",
  "isEphemeral": false
}