> ## 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.
# Upload a large file using multipart upload
> Initiate a multipart upload for large files (typically >100MB). This will return presigned URLs for each part.
Each presigned URL is valid for 900 seconds (15 minutes) and can be used multiple times.
The workflow is:
1. Call this endpoint to get presigned URLs for each part
2. Upload each part to its respective presigned URL using PUT requests
3. 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)
- `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)
Initiate a multipart upload for large files (typically >100MB). This endpoint returns presigned URLs for each part that you can use to upload file chunks directly to storage.
Each presigned URL is valid for 900 seconds (15 minutes) and can be used
multiple times.
## How It Works
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
This endpoint accepts an optional `Idempotency-Key` request header so a retry
cannot apply the change twice. See
[Idempotent requests](/docs-api/api-idempotency).
## OpenAPI
````yaml post /prod/v1/files/upload/multipart
openapi: 3.0.0
info:
title: Public API
description: >-
### Welcome to fileAI’s Public API Documentation.
This API allows users to check the health of the system, upload and manage
files, and manage AI Schemas.
Should you have any questions, please reach out to fileAI via the “Contact a
Developer” link below.
[Contact a Developer](mailto:support@file.ai)
### Prerequisites
Before using our API, please ensure you complete the following prerequisites
- You must have a fileAI account. Sign up or login
[here](https://orion.file.ai/en/sign-up)
- You must have an API Key. After creating your fileAI account, you can
generate your API Key. Refer to the Authentication section below for more
details.
### Authentication
All API requests require an API key for authentication.
- To obtain your API key, please log in to your fileAI account and navigate
to Project Settings in your dashboard
- Keep your API key secure and do not share it publicly.
### How to Use Your API Key
Once you have your API key:
- Click the Authorize button on the top-right of this page
- Enter your API Key under Value
- Click Authorize to start making authenticated requests directly from the
documentation
version: '1.0'
contact: {}
servers:
- url: https://api.orion.file.ai
description: Default. Use this unless your workspace is on an instance.
- url: https://api.orion.{instance}.file.ai
description: Instance-specific host.
variables:
instance:
default: au
enum:
- au
- sg
- jp
description: >-
Instance hosting your workspace: au (Australia), sg (Singapore), jp
(Japan).
security: []
tags:
- name: Public API V1
paths:
/prod/v1/files/upload/multipart:
post:
tags:
- Public API V1
summary: Upload a large file using multipart upload
description: >-
Initiate a multipart upload for large files (typically >100MB). This
will return presigned URLs for each part.
Each presigned URL is valid for 900 seconds (15 minutes) and can be used
multiple times.
The workflow is:
1. Call this endpoint to get presigned URLs for each part
2. Upload each part to its respective presigned URL using PUT requests
3. 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)
- `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)
operationId: PublicAPIController_uploadMultipartFileRequest
parameters:
- name: Idempotency-Key
in: header
description: >-
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.
required: false
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UploadMultipartFileForPAInput'
responses:
'201':
description: >-
Multipart upload initiated successfully. Use the presigned URLs to
upload each part.
content:
application/json:
example:
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
isEphemeral: false
'401':
description: Missing or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'403':
description: Read-only or inactive API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'404':
description: Resource not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'422':
description: Invalid input parameters
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
examples:
Invalid fileName:
summary: Invalid fileName
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid fileName.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid fileName.
error: Unprocessable Entity
statusCode: 422
Invalid fileType:
summary: Invalid fileType
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid fileType.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid fileType.
error: Unprocessable Entity
statusCode: 422
Invalid fileSize:
summary: Invalid fileSize
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid fileSize. Must be greater than 0.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid fileSize. Must be greater than 0.
error: Unprocessable Entity
statusCode: 422
Invalid isSplit:
summary: Invalid isSplit
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid isSplit. It must be one of true or false.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid isSplit. It must be one of true or false.
error: Unprocessable Entity
statusCode: 422
Invalid isSplitExcel:
summary: Invalid isSplitExcel
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid isSplitExcel. It must be one of true or false.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid isSplitExcel. It must be one of true or false.
error: Unprocessable Entity
statusCode: 422
Invalid schemaLocking:
summary: Invalid schemaLocking
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid schemaLocking. It must be one of true or false.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid schemaLocking. It must be one of true or false.
error: Unprocessable Entity
statusCode: 422
Invalid directoryId:
summary: Invalid directoryId
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid directoryId.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid directoryId.
error: Unprocessable Entity
statusCode: 422
Invalid OCR model:
summary: Invalid OCR model
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid ocr model
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid ocr model
error: Unprocessable Entity
statusCode: 422
Invalid isEphemeral:
summary: Invalid isEphemeral
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid isEphemeral. It must be one of true or false.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid isEphemeral. It must be one of true or false.
error: Unprocessable Entity
statusCode: 422
'429':
description: Rate limit exceeded.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'500':
description: Unexpected internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
security:
- x-api-key: []
components:
schemas:
UploadMultipartFileForPAInput:
type: object
properties:
fileName:
type: string
description: File name
example: large-file.pdf
fileType:
type: string
description: File type
example: application/pdf
fileSize:
type: number
description: File size in MB
example: 150.5
partSizeLimit:
type: number
description: Part size limit in MB (optional, default will be calculated)
example: 10
isSplit:
type: boolean
description: Is split
default: false
example: false
isSplitExcel:
type: boolean
description: Is split excel - whether to split Excel files by worksheets
example: false
callbackURL:
type: string
description: Callback URL
example: https://example.com/callback
ocrModel:
type: string
description: OCR model
enum:
- 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:
type: boolean
description: Schema locking
example: false
directoryId:
type: string
description: Directory Id
example: 649e2d2d2d2d2d2d2d2d2d2d
destinationPath:
type: string
description: >-
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:
type: boolean
description: Is ephemeral
example: false
pageCount:
type: number
description: >-
Page count of the PDF file. Used for early validation against page
limits.
example: 50
apiRequestId:
type: string
description: >-
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:
type: boolean
description: >-
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.
default: false
example: false
required:
- fileName
- fileType
- fileSize
ProblemDetailsDto:
type: object
properties:
type:
type: string
description: A URI identifying the problem type.
example: https://errors.file.ai/validation-failed
title:
type: string
description: Stable, human-readable summary of the problem type.
example: Validation failed
status:
type: number
description: HTTP status code.
example: 422
detail:
type: string
description: Human-readable explanation specific to this occurrence.
example: One or more fields are invalid.
instance:
type: string
description: URI reference for this occurrence (the request path).
example: /v1/files/upload
code:
type: string
description: Stable machine-readable error code.
example: VALIDATION_FAILED
requestId:
type: string
description: Correlation id for this request.
example: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors:
description: Field-level violations (validation only).
type: array
items:
$ref: '#/components/schemas/ProblemErrorItemDto'
retryAfter:
type: number
description: Seconds until the client may retry (present on 429 only).
example: 42
message:
type: string
description: Legacy key (deprecated — use `detail`/`title`).
example: Validation failed
error:
type: string
description: Legacy key (deprecated — use `title`).
example: Unprocessable Entity
statusCode:
type: number
description: Legacy key (deprecated — use `status`).
example: 422
required:
- type
- title
- status
- detail
- instance
- code
- requestId
- errors
- message
- error
- statusCode
ProblemErrorItemDto:
type: object
properties:
code:
type: string
example: REQUIRED
detail:
type: string
example: must not be empty
pointer:
type: string
description: JSON Pointer to the offending body field.
example: '#/fileName'
parameter:
type: string
description: Name of the offending query/header parameter.
example: limit
required:
- code
- detail
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````