Skip to main content
POST
/
prod
/
v1
/
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",
  "isEphemeral": false,
  "pageCount": 50,
  "apiRequestId": "my-batch-request-123"
}
'
{
  "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",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": true,
  "isSplit": false,
  "isSplitExcel": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d"
}

Documentation Index

Fetch the complete documentation index at: https://docs.file.ai/llms.txt

Use this file to discover all available pages before exploring further.

The presignedUploadURL is valid for 3600 seconds (1 hour) 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
  • callbackURL: the url that will be called after the file is uploaded
  • ocrModel: the ocr model to be used for the file processing
  • schemaLocking: whether the schema should be locked after the file is uploaded, must be one of true or false
  • isEphemeral: whether to automatically delete a file. If this is set to “true”, then the file will be automatically deleted 24 hours after upload. (optional, default: false)

​
How It Works

  1. Request Upload URL: Submit file metadata to this endpoint
  2. Receive Presigned URL: Get a secure upload URL valid for 1 hour
  3. Upload File: Use the presigned URL to upload your file directly to storage
  4. Processing: File is automatically processed with specified OCR model and schema
  5. Callback (optional): Receive notification when processing is complete

​
Request Parameters

​
Request Body

The request body must contain a JSON object with the following properties:
PropertyTypeRequiredDescription
fileNamestringYesOriginal name of the file including extension (e.g., “document.pdf”)
fileTypestringYesMIME type of the file (e.g., “application/pdf”, “image/jpeg”)
isSplitbooleanYesWhether the file should be processed as separate pages/sections
callbackURLstringNoHTTP endpoint to receive processing completion notifications
ocrModelstringNoOCR engine to use for text extraction. Available models vary by plan
schemaLockingbooleanYesWhether to lock the schema after processing. Must be true or false
isEphemeralbooleanNoWhether to automatically delete a file 24 hours after upload.

​
Responses

{
  "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",
  "ocrModel": "Beethoven_ENG_G5.0",
  "schemaLocking": true,
  "isEphemeral": false
}

Authorizations

​
x-api-key
string
header
required

API key for authentication

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,
Beethoven_CUS_GP25.1,
Unified (google-document-ai-ocr-gemini-v10),
Beethoven_ZH_O5.9,
Beethoven_JP_O5.3,
Beethoven_JP_G5.4,
Beethoven_TH_O5.1,
Beethoven_TH_G5.1
Example:

"Beethoven_ENG_O5.6"

​
schemaLocking
boolean

Schema locking

Example:

false

​
directoryId
string

Directory Id

Example:

"649e2d2d2d2d2d2d2d2d2d2d"

​
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 client-supplied correlation ID that ties files uploaded in the same logical batch together.

Behaviour:

  • Persisted on every resulting document and forwarded as api_request_id on all subsequent webhook callbacks for this upload, so you can correlate processing events back to the originating request on your side.
  • When the uploaded file is a ZIP archive, every file extracted from it inherits this same value, letting you link all per-file callbacks back to the one ZIP upload.
  • If omitted, the server auto-generates an opaque ID. For ZIP uploads specifically, the generated ID is shared across all extracted files.

Supply your own value when you already have an idempotency key or job ID on the client side (e.g. from your own queue) that you want to reconcile against inbound webhook events.

Example:

"my-batch-request-123"

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

​
ocrModel
string
​
schemaLocking
boolean
​
isSplit
boolean
​
isSplitExcel
boolean
​
directoryId
string