Uploads

What it does

Uploading is how files enter fileAI for processing. You ask for a presigned storage URL, PUT the file to it, and processing starts as soon as the file lands.

When to use it

You receive invoices, statements or forms and want fileAI to classify them and extract values into your project.
You need to send many files at once (up to 100 per request), or files too large for one request (multipart, typically over 100 MB).
You have a folder of documents and want to send it as one .zip that fileAI unpacks and processes file by file.

Need values from one document without storing it? POST /v1/extract takes the file directly as multipart/form-data (up to 50 MB) and returns a job. See Extract, split and classify.

How it works

You never send file bytes to the API itself. You track the upload with GET /v1/uploads/{uploadId} or a callback; Async jobs compares the two.

Try it

Request an upload URL, then PUT the file to it. The URL is valid for 300 seconds (5 minutes) and can be used more than once within that time. Send the same Content-Type you gave as fileType (the file’s MIME type). The cURL examples assume FILEAI_BASE_URL is set as in Authentication.

# 1. Request an upload URL
curl -X POST "$FILEAI_BASE_URL/files/upload" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "invoice.pdf",
    "fileType": "application/pdf",
    "callbackURL": "https://example.com/fileai/callback"
  }'

# 2. PUT the file to the presignedUploadURL from the response
curl -X PUT "<presignedUploadURL>" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf

import os, requests

BASE = "https://api.orion.file.ai/prod/v1"
HEADERS = {"x-api-key": os.environ["FILEAI_API_KEY"]}

upload = requests.post(
    f"{BASE}/files/upload",
    headers=HEADERS,
    json={
        "fileName": "invoice.pdf",
        "fileType": "application/pdf",
        "callbackURL": "https://example.com/fileai/callback",
    },
).json()

with open("invoice.pdf", "rb") as f:
    requests.put(
        upload["presignedUploadURL"],
        headers={"Content-Type": "application/pdf"},
        data=f,
    ).raise_for_status()

import { readFile } from "node:fs/promises";

const BASE = "https://api.orion.file.ai/prod/v1";
const headers = { "x-api-key": process.env.FILEAI_API_KEY };

const upload = await fetch(`${BASE}/files/upload`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    fileName: "invoice.pdf",
    fileType: "application/pdf",
    callbackURL: "https://example.com/fileai/callback",
  }),
}).then((r) => r.json());

await fetch(upload.presignedUploadURL, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf" },
  body: await readFile("invoice.pdf"),
});

Understand the result

The upload request returns 201:

Response (201)

{
  "uploadId": "f2538513-f0b9-4aa8-9c57-bc0a85c77de6",
  "presignedUploadURL": "https://…",
  "s3Path": "s3://…",
  "callbackURL": "https://example.com/fileai/callback",
  "callbackURLSource": "user",
  "isSplit": false,
  "isSplitExcel": false
}

Field	Meaning
`uploadId`	The id you track with `GET /v1/uploads/{uploadId}`.
`presignedUploadURL`	Where you `PUT` the file bytes. Valid for 300 seconds.
`callbackURLSource`	Which callback URL applies: `user` (the one you sent) or `api_key` (the key’s default).

Once the file lands, poll the upload, or wait for the request to your callbackURL:

curl "$FILEAI_BASE_URL/uploads/<uploadId>" -H "x-api-key: $FILEAI_API_KEY"

Response (200)

{
  "fileType": "application/pdf",
  "statuses": [
    { "step": "processing_started", "status": "completed", "timestamp": "2025-06-11T10:30:30Z" },
    { "step": "fraud_detection", "status": "completed", "timestamp": "2025-06-11T10:31:00Z" }
  ],
  "files": [
    { "fileId": "53d6a0b1-…", "fileName": "invoice.pdf", "status": "processed", "fileClass": "Invoice", "schemaId": "6835aca6…" }
  ]
}

Field	Meaning
`statuses[]`	Processing steps in order, each with `step`, `status`, `timestamp`, and `errorReason` when a step fails. Step and status values are listed in Async jobs.
`files[]`	The documents created from the upload. One file can become several documents when it is split. Use each `fileId` with `GET /v1/files/{fileId}/values`.

The fraud_detection step is an internal processing step, not fileForensics. To check a file with fileForensics, see Choose products.

Next steps

Processing callbacks

Get notified instead of polling.

Supported file types

Every type fileAI accepts.

Files and folders

Organize uploads into folders.

Idempotency

Retry uploads safely.

Reference

Upload routes

You have	Use	Limit per request
One file	`POST /v1/files/upload`	1 file
Many files	`POST /v1/files/upload/batch`	100 files
One large file	`POST /v1/files/upload/multipart`, then `/multipart/complete`	1 file
Many large files	`POST /v1/files/upload/multipart/batch`, then `/multipart/complete/batch`	25 files, 2,500 part URLs in total
A folder of files in one archive	Any route above with a `.zip` file	See ZIP uploads

Batch registration

POST /v1/files/upload/batch registers up to 100 files in one call and returns a presigned URL for each. Put shared options in defaults; any field on a file overrides the default.

curl -X POST "$FILEAI_BASE_URL/files/upload/batch" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c3e-1b7a-4b8e-9a51-2f0c4d1e9b77" \
  -d '{
    "defaults": { "directoryId": "649e2d2d2d2d2d2d2d2d2d2d", "callbackURL": "https://example.com/fileai/callback" },
    "files": [
      { "fileName": "inv-001.pdf", "fileType": "application/pdf" },
      { "fileName": "inv-002.pdf", "fileType": "application/pdf", "pageCount": 3 },
      { "fileName": "scan.png", "fileType": "image/png", "ocrModel": "Not_A_Model" }
    ]
  }'

Response (207)

{
  "batchId": "k3x9q2m7v1c8z4n6b0w5t",
  "apiRequestId": "k3x9q2m7v1c8z4n6b0w5t",
  "accepted": 2,
  "rejected": 1,
  "results": [
    { "index": 0, "status": "accepted", "fileName": "inv-001.pdf", "uploadId": "…", "presignedUploadURL": "https://…", "expiresAt": "…" },
    { "index": 1, "status": "accepted", "fileName": "inv-002.pdf", "uploadId": "…", "presignedUploadURL": "https://…", "expiresAt": "…" },
    { "index": 2, "status": "rejected", "fileName": "scan.png", "error": { "status": 422, "code": "VALIDATION_FAILED", "detail": "Invalid ocr model" } }
  ]
}

results[i] always maps to files[i]. One bad file never rejects the others.
batchId is a 21-character lowercase id with no prefix. It is also the apiRequestId unless you set one in defaults.
The status is 201 when every file is accepted and 207 when the result is mixed.
An empty or missing files array returns 422 INVALID_BATCH; more than 100 files returns 422 BATCH_TOO_LARGE. Nothing is registered in either case.
A file over the page limit (when you send pageCount) is rejected on its own.
Send an Idempotency-Key (1–255 characters) to make the call safe to retry. A replay returns the same batchId, uploadIds and verdicts, with freshly signed URLs. See Idempotency.
isEphemeral and apiRequestId apply to the whole batch on this route, so they are only accepted in defaults.

Each URL is valid for 300 seconds. PUT each file to its own URL as in the single upload.

Multipart uploads for large files

Multipart uploads split one file into parts that you upload in parallel and then stitch together. Use them for large files (typically over 100 MB).

Initiate

Send the file size in MB. partSizeLimit (MB) is optional; parts are at least 5 MB, and the file is cut into at most 10,000 parts.

curl -X POST "$FILEAI_BASE_URL/files/upload/multipart" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "ledger.pdf", "fileType": "application/pdf", "fileSize": 150.5, "partSizeLimit": 10 }'

Response (201)

{
  "id": "upload_aws_xyz789",
  "key": "…/ledger.pdf",
  "uploadId": "file_abc123xyz",
  "partSize": 10485760,
  "totalParts": 16,
  "presignedUrls": [
    { "partNumber": 1, "presignedUrl": "https://…", "startByte": 0, "endByte": 10485759, "size": 10485760 }
  ]
}

Keep id and key to complete the upload. uploadId is the id you track with GET /v1/uploads/{uploadId}.

Upload each part

PUT bytes startByte–endByte to each part’s presignedUrl, and save the ETag header from every response. Part URLs are valid for 900 seconds (15 minutes).

Complete

curl -X POST "$FILEAI_BASE_URL/files/upload/multipart/complete" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "upload_aws_xyz789",
    "key": "…/ledger.pdf",
    "parts": [ { "partNumber": 1, "eTag": "\"abc123\"" }, { "partNumber": 2, "eTag": "\"def456\"" } ]
  }'

The response includes success: true, and processing starts.

Many large files

Initiate: POST /v1/files/upload/multipart/batch takes up to 25 files, with at most 2,500 part URLs across the batch. Over that, the request returns 422 BATCH_PARTS_TOO_LARGE and nothing is created; split the batch or raise partSizeLimit. Each file is accepted or rejected on its own, and the response is 201 even if every file is rejected, so check accepted, rejected and each result’s status.
Field names differ here: in batch results, uploadId is the storage multipart id (send it as id to complete or refresh) and fileId is the fileAI id you track with GET /v1/uploads/{uploadId}. Accepted results also include key and s3Path.
Per-file options: unlike /files/upload/batch, this route accepts isEphemeral on each file as well as in defaults.
Complete: POST /v1/files/upload/multipart/complete/batch with uploads (each id, key and full parts list) and an optional batchId. Each upload completes on its own: 201 when all succeed, 207 when some fail. Retry only the failed ones. A bad part list fails with INVALID_PARTS.
Refresh URLs: a long transfer can outlive its part URLs. POST /v1/files/upload/multipart/urls/refresh with id, key and the partNumbers still outstanding returns new URLs valid for another 900 seconds. Parts already uploaded stay uploaded. An unknown id/key returns 404.

Idempotency-Key is ignored on /multipart/batch and /multipart/urls/refresh: a retry starts a fresh set of uploads or signs fresh URLs. /multipart/complete/batch is idempotent for 24 hours. Abandoned multipart uploads expire on their own.

ZIP uploads

Upload a .zip through any route above. fileAI validates the archive, extracts it, and processes each supported file inside as its own upload. Set retainOriginalZipFileName: true to keep the archive’s name on the extracted files as zipArchiveName. Files from one ZIP share an apiRequestId (the ZIP’s id unless you supply one). GET /v1/uploads/{uploadId} for a ZIP returns one entry per extracted file in files, each with its own uploadId, statuses and files (documents). Files that could not be processed carry a processing_failed step with status error and an errorReason such as Unsupported file type. When some files succeed and some fail, the response is 207 instead of 200. If the archive itself fails validation, you get a zip_validation step with status error and an empty files array.

Upload options

These body fields are accepted on POST /v1/files/upload, and on the batch and multipart routes unless noted.

Field	Type	What it does
`fileName`	string, required	File name, including extension.
`fileType`	string, required	The file’s MIME type, such as `application/pdf`. This is not the fileAI file type (see Concepts). Accepted values: Supported file types.
`callbackURL`	string	URL fileAI calls once with processing updates (no retries). Use HTTPS. Overrides the key’s default callback URL; `callbackURLSource` in the response says which one applies (`user` or `api_key`). On `/files/upload/batch` the order is the file’s own URL, then `defaults`, then the key’s default. Multipart routes do not fall back to the key’s default: send `callbackURL` on each multipart upload that needs one. Payload: Processing callbacks.
`directoryId`	string	Folder to place the file in. See Files and folders.
`destinationPath`	string	Slash-delimited folder path such as `clients/acme`. Missing folders are created. Works with `directoryId`.
`blueprintId`	string	File type id from `GET /v1/file-type` (the API calls a file type a blueprint). Applies that file type and its schema to every document in the file and skips auto-classification. Must be approved (Verify in the app) or built in.
`ocrModel`	string	OCR model for this file, overriding the project default. See Read and parse.
`schemaLocking`	boolean	Only classify into your saved schemas. See Schema locking.
`isSplit`	boolean	Split a file that holds several documents into separate documents. Default `false`.
`isSplitExcel`	boolean	Process each worksheet of an Excel file as its own document. Default `false`.
`isEphemeral`	boolean	Delete the file and all related data after it is processed. Default `false`. On `/files/upload/batch`, only in `defaults`; `/multipart/batch` also accepts it per file.
`pageCount`	number	Page count, checked early against your page limit.
`apiRequestId`	string	Your own id to group related uploads. In a batch, only in `defaults`.
`retainOriginalZipFileName`	boolean	Keep a ZIP’s original name on its extracted files. Default `false`.
`storageOnly`	boolean	Store the file without OCR, classification or extraction, for example to run fileForensics later. Single upload only. See Choose products.
`enabledProducts`	array	`FILE_SCOUT`, `FILE_FORENSICS` or both. Single upload only. See Choose products.
`platformIngest`	boolean	Convert JPEG and PNG uploads to PDF before processing, as the app does. Single upload only.
`fileSize`, `partSizeLimit`	number (MB)	Multipart routes only.

Validation errors return 422, for example Invalid fileName., Invalid directoryId. or an ocrModel that is retired or unknown.

Choose products

enabledProducts on POST /v1/files/upload picks which products run on the file and are metered. It is accepted on single uploads only, and only in workspaces enabled for these products; otherwise the request returns 422.

`enabledProducts`	`storageOnly`	What happens
Left out	Either	The upload follows your workspace’s existing processing and billing.
`["FILE_SCOUT"]`	Must be `false` or left out	Full processing: OCR, classification and extraction. See fileScout.
`["FILE_FORENSICS"]`	Must be `true`	The file is stored and checked with fileForensics only.
`["FILE_SCOUT", "FILE_FORENSICS"]`	Must be `false` or left out	Full processing plus fileForensics.

A storage-only upload without enabledProducts can later be sent to POST /v1/forensics.

Size limits

The maximum size for presigned and multipart uploads is set per instance. A file over it is marked as exceeding the maximum file size and is not processed. POST /v1/extract, /split and /classify accept files up to 50 MB.

Get started

Products

Build

Go live

What it does

When to use it

How it works

Try it

Understand the result

Next steps

Processing callbacks

Supported file types

Files and folders

Idempotency

Reference

Upload routes

Batch registration

Multipart uploads for large files

Many large files

ZIP uploads

Upload options

Choose products

Size limits

​What it does

​When to use it

​How it works

​Try it

​Understand the result

​Next steps

Processing callbacks

Supported file types

Files and folders

Idempotency

​Reference

​Upload routes

​Batch registration

​Multipart uploads for large files

​Many large files

​ZIP uploads

​Upload options

​Choose products

​Size limits

What it does

When to use it

How it works

Try it

Understand the result

Next steps

Reference

Upload routes

Batch registration

Multipart uploads for large files

Many large files

ZIP uploads

Upload options

Choose products

Size limits