Uploads
Register a batch of files
Register up to 100 files in one call and receive a presigned upload URL for each.
POST
/
v1
/
files
/
upload
/
batch
Register a batch of files
curl --request POST \
--url https://api.orion.file.ai/prod/v1/files/upload/batch \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"files": [
{
"fileName": "inv-001.pdf",
"fileType": "application/pdf",
"pageCount": 3,
"isSplit": true,
"isSplitExcel": true,
"callbackURL": "<string>",
"schemaLocking": true,
"directoryId": "<string>",
"blueprintId": "<string>",
"destinationPath": "<string>",
"retainOriginalZipFileName": true
}
],
"defaults": {
"isSplit": true,
"isSplitExcel": true,
"callbackURL": "<string>",
"schemaLocking": true,
"directoryId": "<string>",
"blueprintId": "<string>",
"destinationPath": "<string>",
"isEphemeral": true,
"apiRequestId": "<string>",
"retainOriginalZipFileName": true
}
}
'import requests
url = "https://api.orion.file.ai/prod/v1/files/upload/batch"
payload = {
"files": [
{
"fileName": "inv-001.pdf",
"fileType": "application/pdf",
"pageCount": 3,
"isSplit": True,
"isSplitExcel": True,
"callbackURL": "<string>",
"schemaLocking": True,
"directoryId": "<string>",
"blueprintId": "<string>",
"destinationPath": "<string>",
"retainOriginalZipFileName": True
}
],
"defaults": {
"isSplit": True,
"isSplitExcel": True,
"callbackURL": "<string>",
"schemaLocking": True,
"directoryId": "<string>",
"blueprintId": "<string>",
"destinationPath": "<string>",
"isEphemeral": True,
"apiRequestId": "<string>",
"retainOriginalZipFileName": True
}
}
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({
files: [
{
fileName: 'inv-001.pdf',
fileType: 'application/pdf',
pageCount: 3,
isSplit: true,
isSplitExcel: true,
callbackURL: '<string>',
schemaLocking: true,
directoryId: '<string>',
blueprintId: '<string>',
destinationPath: '<string>',
retainOriginalZipFileName: true
}
],
defaults: {
isSplit: true,
isSplitExcel: true,
callbackURL: '<string>',
schemaLocking: true,
directoryId: '<string>',
blueprintId: '<string>',
destinationPath: '<string>',
isEphemeral: true,
apiRequestId: '<string>',
retainOriginalZipFileName: true
}
})
};
fetch('https://api.orion.file.ai/prod/v1/files/upload/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"batchId": "batch_01J9Z",
"apiRequestId": "batch_01J9Z",
"accepted": 2,
"rejected": 1,
"results": [
{
"index": 0,
"status": "accepted",
"fileName": "inv-001.pdf",
"uploadId": "up_a1",
"s3Path": "<string>",
"presignedUploadURL": "<string>",
"expiresAt": "2026-08-19T10:15:00Z",
"error": {
"code": "VALIDATION_FAILED",
"detail": "isSplitExcel requires an Excel fileType",
"status": 422
}
}
]
}{
"batchId": "batch_01J9Z",
"apiRequestId": "batch_01J9Z",
"accepted": 2,
"rejected": 1,
"results": [
{
"index": 0,
"status": "accepted",
"fileName": "inv-001.pdf",
"uploadId": "up_a1",
"s3Path": "<string>",
"presignedUploadURL": "<string>",
"expiresAt": "2026-08-19T10:15:00Z",
"error": {
"code": "VALIDATION_FAILED",
"detail": "isSplitExcel requires an Excel fileType",
"status": 422
}
}
]
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}Request · Response · Guide: Upload files
More details
More details
Batch-level
defaults apply to every file; a per-file field overrides the matching default.
Partial success is normal: valid files are registered and returned as accepted with a
presignedUploadURL; files that fail per-file validation are returned as rejected with a
per-item error and are not registered. One bad file never rejects the others.Status: 201 when all files are accepted, 207 when the result is mixed. The batch envelope
is rejected wholesale with 422 (and nothing is registered) when files is empty or absent
(INVALID_BATCH) or exceeds the cap (BATCH_TOO_LARGE). A file over the page limit is a
per-item rejected, not a whole-batch rejection.The presignedUploadURL for each accepted file is valid for 300 seconds (5 minutes). An
idempotent replay returns the same batchId, uploadIds and verdicts but freshly signed URLs.Authorizations
API key for authentication
Headers
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
Response
All files accepted.
Server-generated batch identifier.
Example:
"batch_01J9Z"
Grouping id stamped on every file. Equals the supplied defaults.apiRequestId, else batchId.
Example:
"batch_01J9Z"
Number of accepted files.
Example:
2
Number of rejected files.
Example:
1
One entry per requested file, in request order (results[i] maps to files[i]).
Show child attributes
Show child attributes
⌘I
Register a batch of files
curl --request POST \
--url https://api.orion.file.ai/prod/v1/files/upload/batch \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"files": [
{
"fileName": "inv-001.pdf",
"fileType": "application/pdf",
"pageCount": 3,
"isSplit": true,
"isSplitExcel": true,
"callbackURL": "<string>",
"schemaLocking": true,
"directoryId": "<string>",
"blueprintId": "<string>",
"destinationPath": "<string>",
"retainOriginalZipFileName": true
}
],
"defaults": {
"isSplit": true,
"isSplitExcel": true,
"callbackURL": "<string>",
"schemaLocking": true,
"directoryId": "<string>",
"blueprintId": "<string>",
"destinationPath": "<string>",
"isEphemeral": true,
"apiRequestId": "<string>",
"retainOriginalZipFileName": true
}
}
'import requests
url = "https://api.orion.file.ai/prod/v1/files/upload/batch"
payload = {
"files": [
{
"fileName": "inv-001.pdf",
"fileType": "application/pdf",
"pageCount": 3,
"isSplit": True,
"isSplitExcel": True,
"callbackURL": "<string>",
"schemaLocking": True,
"directoryId": "<string>",
"blueprintId": "<string>",
"destinationPath": "<string>",
"retainOriginalZipFileName": True
}
],
"defaults": {
"isSplit": True,
"isSplitExcel": True,
"callbackURL": "<string>",
"schemaLocking": True,
"directoryId": "<string>",
"blueprintId": "<string>",
"destinationPath": "<string>",
"isEphemeral": True,
"apiRequestId": "<string>",
"retainOriginalZipFileName": True
}
}
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({
files: [
{
fileName: 'inv-001.pdf',
fileType: 'application/pdf',
pageCount: 3,
isSplit: true,
isSplitExcel: true,
callbackURL: '<string>',
schemaLocking: true,
directoryId: '<string>',
blueprintId: '<string>',
destinationPath: '<string>',
retainOriginalZipFileName: true
}
],
defaults: {
isSplit: true,
isSplitExcel: true,
callbackURL: '<string>',
schemaLocking: true,
directoryId: '<string>',
blueprintId: '<string>',
destinationPath: '<string>',
isEphemeral: true,
apiRequestId: '<string>',
retainOriginalZipFileName: true
}
})
};
fetch('https://api.orion.file.ai/prod/v1/files/upload/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"batchId": "batch_01J9Z",
"apiRequestId": "batch_01J9Z",
"accepted": 2,
"rejected": 1,
"results": [
{
"index": 0,
"status": "accepted",
"fileName": "inv-001.pdf",
"uploadId": "up_a1",
"s3Path": "<string>",
"presignedUploadURL": "<string>",
"expiresAt": "2026-08-19T10:15:00Z",
"error": {
"code": "VALIDATION_FAILED",
"detail": "isSplitExcel requires an Excel fileType",
"status": 422
}
}
]
}{
"batchId": "batch_01J9Z",
"apiRequestId": "batch_01J9Z",
"accepted": 2,
"rejected": 1,
"results": [
{
"index": 0,
"status": "accepted",
"fileName": "inv-001.pdf",
"uploadId": "up_a1",
"s3Path": "<string>",
"presignedUploadURL": "<string>",
"expiresAt": "2026-08-19T10:15:00Z",
"error": {
"code": "VALIDATION_FAILED",
"detail": "isSplitExcel requires an Excel fileType",
"status": 422
}
}
]
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}