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",
  "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"

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",
    "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: 'file.pdf',
    fileType: 'application/pdf',
    isSplit: false,
    isSplitExcel: false,
    callbackURL: 'https://example.com/callback',
    ocrModel: 'Beethoven_ENG_O5.6',
    schemaLocking: false,
    directoryId: '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', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orion.file.ai/prod/v1/files/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fileName' => 'file.pdf',
    'fileType' => 'application/pdf',
    'isSplit' => false,
    'isSplitExcel' => false,
    'callbackURL' => 'https://example.com/callback',
    'ocrModel' => 'Beethoven_ENG_O5.6',
    'schemaLocking' => false,
    'directoryId' => '649e2d2d2d2d2d2d2d2d2d2d',
    'destinationPath' => 'mammals/walrus',
    'isEphemeral' => false,
    'pageCount' => 50,
    'apiRequestId' => 'my-batch-request-123',
    'retainOriginalZipFileName' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"fileName\": \"file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orion.file.ai/prod/v1/files/upload")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileName\": \"file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}")
  .asString();

require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileName\": \"file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

Endpoints

Upload a file

Upload a file to the server, this will return a presigned upload url to be used for the upload.

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). Available models:
- 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)
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)

POST

prod

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",
  "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"

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",
    "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: 'file.pdf',
    fileType: 'application/pdf',
    isSplit: false,
    isSplitExcel: false,
    callbackURL: 'https://example.com/callback',
    ocrModel: 'Beethoven_ENG_O5.6',
    schemaLocking: false,
    directoryId: '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', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orion.file.ai/prod/v1/files/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fileName' => 'file.pdf',
    'fileType' => 'application/pdf',
    'isSplit' => false,
    'isSplitExcel' => false,
    'callbackURL' => 'https://example.com/callback',
    'ocrModel' => 'Beethoven_ENG_O5.6',
    'schemaLocking' => false,
    'directoryId' => '649e2d2d2d2d2d2d2d2d2d2d',
    'destinationPath' => 'mammals/walrus',
    'isEphemeral' => false,
    'pageCount' => 50,
    'apiRequestId' => 'my-batch-request-123',
    'retainOriginalZipFileName' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"fileName\": \"file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orion.file.ai/prod/v1/files/upload")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileName\": \"file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}")
  .asString();

require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileName\": \"file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

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

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

Request Parameters

Request Body

The request body must contain a JSON object with the following properties:

Property	Type	Required	Description
fileName	string	Yes	Original name of the file including extension (e.g., “document.pdf”)
fileType	string	Yes	MIME type of the file (e.g., “application/pdf”, “image/jpeg”)
isSplit	boolean	Yes	Whether the file should be processed as separate pages/sections
callbackURL	string	No	HTTP endpoint to receive processing completion notifications
ocrModel	string	No	OCR engine to use for text extraction. Available models vary by plan
schemaLocking	boolean	Yes	Whether to lock the schema after processing. Must be true or false
isEphemeral	boolean	No	Whether 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
}

This endpoint accepts an optional Idempotency-Key request header so a retry cannot apply the change twice. See Idempotent requests.

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)

Example:

"Beethoven_ENG_O5.6"

schemaLocking

boolean

Schema locking

Example:

false

directoryId

string

Directory Id

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

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.

⌘I

fileAI API

Key Functions

Endpoints

Upload a file

How It Works

Request Parameters

Request Body

Responses

Authorizations

Headers

Body

Response

​How It Works

​Request Parameters

​Request Body

​Responses

Authorizations

Headers

Body

Response

How It Works

Request Parameters

Request Body

Responses