> ## 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 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) 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: | 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 ```json theme={null} { "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](/docs-api/api-idempotency). ## OpenAPI ````yaml post /prod/v1/files/upload 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. ![Authentication](https://static.orion.file.ai/authentication.png) ### 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 ![How to Use Your API Key](https://static.orion.file.ai/how-to-use-api-keys.png) 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: post: tags: - Public API V1 summary: Upload a file description: >- 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) operationId: PublicAPIController_uploadFileRequest 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/UploadFileForPAInput' responses: '201': description: >- 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 content: application/json: example: 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 schema: type: object properties: s3Path: type: string presignedUploadURL: type: string uploadId: type: string callbackURL: type: string description: The callback URL that will be used for notifications callbackURLSource: type: string description: >- Source of the callback URL: "user" if provided in request, "api_key" if from API key default ocrModel: type: string schemaLocking: type: boolean isSplit: type: boolean isSplitExcel: type: boolean directoryId: type: string destinationPath: type: string description: >- Slash-delimited folder path (e.g. "mammals/walrus"). Folders are auto-created if they do not exist. '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 content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Invalid isSplit. It must be one of true or false: summary: Invalid isSplit. It must be one of true or false 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. It must be one of true or false: summary: Invalid isSplitExcel. It must be one of true or false 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 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 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 ocrModel: summary: Invalid ocrModel value: type: https://errors.file.ai/validation-failed title: Validation failed status: 422 detail: Invalid ocrModel. instance: /v1/{route} code: VALIDATION_FAILED requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324 errors: [] message: Invalid ocrModel. 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. instance: /v1/{route} code: VALIDATION_FAILED requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324 errors: [] message: Invalid schemaLocking. 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: UploadFileForPAInput: type: object properties: fileName: type: string description: File name example: file.pdf fileType: type: string description: File type example: application/pdf 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 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: 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 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 ````