Upload a file - fileAI Docs

POST

files

upload

Upload a file

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/files/upload \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileName": "file.pdf",
  "fileType": "application/pdf",
  "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,
  "storageOnly": false,
  "enabledProducts": [],
  "platformIngest": false
}
'

import requests

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

payload = {
    "fileName": "file.pdf",
    "fileType": "application/pdf",
    "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,
    "storageOnly": False,
    "enabledProducts": [],
    "platformIngest": 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: 'file.pdf',
    fileType: 'application/pdf',
    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,
    storageOnly: false,
    enabledProducts: [],
    platformIngest: false
  })
};

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

{
  "s3Path": "s3://bucket/upload/file.txt",
  "presignedUploadURL": "https://s3.amazonaws.com/bucket/upload/file.txt?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=1%2F6%2BN7Z6h%2F7oV7Z6i%2F9oV7Z4%3D&Expires=3600",
  "uploadId": "f2538513-f0b9-4aa8-9c57-bc0a85c77de6",
  "callbackURL": "https://example.com/callback",
  "callbackURLSource": "user",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": true,
  "isSplit": false,
  "isSplitExcel": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "blueprintId": "649e2d2d2d2d2d2d2d2d2d2e"
}

Request · Response · Guide: Upload files

More details

The presignedUploadURL is valid for 300 seconds (5 minutes) and can be used multiple times.The input should contain the following information:

fileName: the name of the file to be uploaded
fileType: the type of the file to be uploaded
isSplit: whether the file is a split file or not (optional, default: false)
isSplitExcel: whether to split Excel files by worksheets (optional, default: false)
callbackURL: (optional) the URL that will be called after file processing. Must be a valid HTTPS URL.
- If provided, this URL takes precedence over the API key’s default callback URL
- If not provided, the API key’s default callback URL will be used (if configured)
- The response includes callbackURLSource indicating whether the URL came from the request (“user”) or API key (“api_key”)
ocrModel: the OCR model to be used for file processing (optional). Accepts either the model name below or its stable processor id (e.g. capybara). The model must use the same engine as the project: a Beethoven project rejects capybara, and a Capybara project accepts only capybara (422 otherwise). Omit ocrModel to use the project setting. Available models:
- Capybara:
  - capybara - Capybara pipeline (stable id; also accepted as Capybara (Experimental)). Only for projects set to Capybara, with Capybara enabled for the organisation. See aiProcessingProvider on GET /v1/files/upload/{uploadId} for the engine that actually ran.
- English Models:
  - Beethoven_ENG_O5.6 - OpenAI v6
  - Beethoven_ENG_G5.5 - Gemini v5
  - Beethoven_ENG_GP25 - Gemini Pro 2.5
  - Beethoven_ENG_GP25.1 - Gemini Pro 2.5 v1
  - Beethoven_ENG_GP25.2 - Gemini Pro 2.5 PDF
  - Beethoven_CUS_O5.1 - Custom OpenAI v8
  - Beethoven_CUS_O5.2 - Custom Gemini v13
  - Unified (google-document-ai-ocr-gemini-v10) - Unified model
  - Aegis (google-document-ai-ocr-gemini-aegis-v1) - Aegis model
- Chinese Models:
  - Beethoven_ZH_O5.9 - Chinese OpenAI v9
- Japanese Models:
  - Beethoven_JP_O5.3 - Japanese OpenAI v3
  - Beethoven_JP_G5.4 - Japanese Gemini fine-tuned
- Thai Models:
  - Beethoven_TH_O5.1 - Thai OpenAI v1
  - Beethoven_TH_G5.1 - Thai Gemini v1
schemaLocking: whether the schema should be locked after the file is uploaded, must be one of true or false (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:

"file.pdf"

fileType

string

required

File type

Example:

"application/pdf"

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 together (e.g. from a zip). If not provided and the uploaded file is a zip, the zip file ID will be used.

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

storageOnly

boolean

Store the original file without OCR, classification, extraction, or image conversion. Required when enabledProducts contains only FILE_FORENSICS; cannot be true when FILE_SCOUT is selected. A storage-only file with no enabledProducts can later be sent to POST /v1/forensics.

Example:

false

enabledProducts

enum<string>[]

Developer Portal products to run and charge after successful work. FILE_SCOUT requires normal processing. FILE_FORENSICS by itself requires storageOnly=true. Selecting both requires normal processing. Omitted leaves the existing upload and billing flow unchanged.

Available options:

FILE_SCOUT,

FILE_FORENSICS

platformIngest

boolean

Convert JPEG and PNG uploads to PDF before processing, matching a dashboard upload. Omitted leaves public API images unchanged.

Example:

false

Response

Get a presigned upload url for upload file, after getting the result use the presignedUploadURL with a PUT method to send the request with the binary file, the presignedUploadURL is valid for 300 seconds (5 minutes) and can be used multiple times

s3Path

string

presignedUploadURL

string

uploadId

string

callbackURL

string

The callback URL that will be used for notifications

callbackURLSource

string

Source of the callback URL: "user" if provided in request, "api_key" if from API key default

ocrModel

string

schemaLocking

boolean

isSplit

boolean

isSplitExcel

boolean

directoryId

string

destinationPath

string

Slash-delimited folder path (e.g. "mammals/walrus"). Folders are auto-created if they do not exist.

blueprintId

string

The pre-selected file type id, echoed back when one was sent

Upload a file

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/files/upload \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileName": "file.pdf",
  "fileType": "application/pdf",
  "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,
  "storageOnly": false,
  "enabledProducts": [],
  "platformIngest": false
}
'

import requests

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

payload = {
    "fileName": "file.pdf",
    "fileType": "application/pdf",
    "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,
    "storageOnly": False,
    "enabledProducts": [],
    "platformIngest": 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: 'file.pdf',
    fileType: 'application/pdf',
    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,
    storageOnly: false,
    enabledProducts: [],
    platformIngest: false
  })
};

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

{
  "s3Path": "s3://bucket/upload/file.txt",
  "presignedUploadURL": "https://s3.amazonaws.com/bucket/upload/file.txt?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=1%2F6%2BN7Z6h%2F7oV7Z6i%2F9oV7Z4%3D&Expires=3600",
  "uploadId": "f2538513-f0b9-4aa8-9c57-bc0a85c77de6",
  "callbackURL": "https://example.com/callback",
  "callbackURLSource": "user",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": true,
  "isSplit": false,
  "isSplitExcel": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "blueprintId": "649e2d2d2d2d2d2d2d2d2d2e"
}