Uploads
Complete a set of multipart uploads
Finalize several multipart uploads in one request, after all of their parts have been uploaded to S3.
POST
/
v1
/
files
/
upload
/
multipart
/
complete
/
batch
Complete a set of multipart uploads
curl --request POST \
--url https://api.orion.file.ai/prod/v1/files/upload/multipart/complete/batch \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"uploads": [
{
"id": "upload_abc123xyz",
"key": "org_123/workspace_456/device/file_abc/document.pdf",
"parts": [
{
"partNumber": 1,
"eTag": "\"etag1\""
},
{
"partNumber": 2,
"eTag": "\"etag2\""
}
]
}
],
"batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T"
}
'import requests
url = "https://api.orion.file.ai/prod/v1/files/upload/multipart/complete/batch"
payload = {
"uploads": [
{
"id": "upload_abc123xyz",
"key": "org_123/workspace_456/device/file_abc/document.pdf",
"parts": [
{
"partNumber": 1,
"eTag": "\"etag1\""
},
{
"partNumber": 2,
"eTag": "\"etag2\""
}
]
}
],
"batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T"
}
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({
uploads: [
{
id: 'upload_abc123xyz',
key: 'org_123/workspace_456/device/file_abc/document.pdf',
parts: [{partNumber: 1, eTag: '"etag1"'}, {partNumber: 2, eTag: '"etag2"'}]
}
],
batchId: 'batch_01JA1ZC7S9V0F4C6H2M8QK3R7T'
})
};
fetch('https://api.orion.file.ai/prod/v1/files/upload/multipart/complete/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T",
"completed": 2,
"failed": 0,
"results": [
{
"index": 0,
"status": "completed",
"success": true,
"id": "upload_aws_xyz789",
"key": "uploads/devices/workspaces/456/organizations/123/files/file_abc/file_abc#stmt-a.pdf",
"location": "https://s3.amazonaws.com/bucket/uploads/devices/.../stmt-a.pdf",
"etag": "\"abc123def456-13\""
},
{
"index": 1,
"status": "completed",
"success": true,
"id": "upload_aws_xyz790",
"key": "uploads/devices/workspaces/456/organizations/123/files/file_abd/file_abd#stmt-b.pdf",
"location": "https://s3.amazonaws.com/bucket/uploads/devices/.../stmt-b.pdf",
"etag": "\"def456abc123-25\""
}
]
}{
"batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T",
"completed": 1,
"failed": 1,
"results": [
{
"index": 0,
"status": "completed",
"success": true,
"id": "upload_aws_xyz789",
"key": "uploads/devices/workspaces/456/organizations/123/files/file_abc/file_abc#stmt-a.pdf",
"location": "https://s3.amazonaws.com/bucket/uploads/devices/.../stmt-a.pdf",
"etag": "\"abc123def456-13\""
},
{
"index": 1,
"status": "failed",
"success": false,
"id": "upload_aws_xyz790",
"key": "uploads/devices/workspaces/456/organizations/123/files/file_abd/file_abd#stmt-b.pdf",
"error": {
"status": 422,
"code": "INVALID_PARTS",
"detail": "The part list for this upload was rejected by S3. Check that every part is listed with the ETag S3 returned for it."
}
}
]
}{
"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 · Guide: Upload files
More details
More details
Each upload is finalized on its own. One upload with a broken part list fails by itself and
is returned with its own error — it never rolls back the uploads beside it, which for a bulk
transfer means hundreds of megabytes of finished work are never discarded because of one bad
part list. Retry just the upload that failed.Returns 201 when every upload was finalized, and 207 when some were and some were not.
Inspect
completed, failed and each result’s success either way.Sending the same Idempotency-Key again within 24h replays the original per-upload results
and queues nothing for processing a second time.The input should contain:batchId: (optional) the batch id from the initiate, echoed back for correlationuploads: each with theidandkeyfrom the initiate and the fullpartslist
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
Uploads to finalize, at most 25 per request. Each upload is finalized independently — one broken part list never rolls back its siblings.
Required array length:
1 - 25 elementsShow child attributes
Show child attributes
The batchId returned by the batch initiate. Optional, and echoed back on the response for correlation; uploads are finalized by their own id and key.
Example:
"batch_01JA1ZC7S9V0F4C6H2M8QK3R7T"
Response
Every upload in the batch was finalized
⌘I
Complete a set of multipart uploads
curl --request POST \
--url https://api.orion.file.ai/prod/v1/files/upload/multipart/complete/batch \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"uploads": [
{
"id": "upload_abc123xyz",
"key": "org_123/workspace_456/device/file_abc/document.pdf",
"parts": [
{
"partNumber": 1,
"eTag": "\"etag1\""
},
{
"partNumber": 2,
"eTag": "\"etag2\""
}
]
}
],
"batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T"
}
'import requests
url = "https://api.orion.file.ai/prod/v1/files/upload/multipart/complete/batch"
payload = {
"uploads": [
{
"id": "upload_abc123xyz",
"key": "org_123/workspace_456/device/file_abc/document.pdf",
"parts": [
{
"partNumber": 1,
"eTag": "\"etag1\""
},
{
"partNumber": 2,
"eTag": "\"etag2\""
}
]
}
],
"batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T"
}
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({
uploads: [
{
id: 'upload_abc123xyz',
key: 'org_123/workspace_456/device/file_abc/document.pdf',
parts: [{partNumber: 1, eTag: '"etag1"'}, {partNumber: 2, eTag: '"etag2"'}]
}
],
batchId: 'batch_01JA1ZC7S9V0F4C6H2M8QK3R7T'
})
};
fetch('https://api.orion.file.ai/prod/v1/files/upload/multipart/complete/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T",
"completed": 2,
"failed": 0,
"results": [
{
"index": 0,
"status": "completed",
"success": true,
"id": "upload_aws_xyz789",
"key": "uploads/devices/workspaces/456/organizations/123/files/file_abc/file_abc#stmt-a.pdf",
"location": "https://s3.amazonaws.com/bucket/uploads/devices/.../stmt-a.pdf",
"etag": "\"abc123def456-13\""
},
{
"index": 1,
"status": "completed",
"success": true,
"id": "upload_aws_xyz790",
"key": "uploads/devices/workspaces/456/organizations/123/files/file_abd/file_abd#stmt-b.pdf",
"location": "https://s3.amazonaws.com/bucket/uploads/devices/.../stmt-b.pdf",
"etag": "\"def456abc123-25\""
}
]
}{
"batchId": "batch_01JA1ZC7S9V0F4C6H2M8QK3R7T",
"completed": 1,
"failed": 1,
"results": [
{
"index": 0,
"status": "completed",
"success": true,
"id": "upload_aws_xyz789",
"key": "uploads/devices/workspaces/456/organizations/123/files/file_abc/file_abc#stmt-a.pdf",
"location": "https://s3.amazonaws.com/bucket/uploads/devices/.../stmt-a.pdf",
"etag": "\"abc123def456-13\""
},
{
"index": 1,
"status": "failed",
"success": false,
"id": "upload_aws_xyz790",
"key": "uploads/devices/workspaces/456/organizations/123/files/file_abd/file_abd#stmt-b.pdf",
"error": {
"status": 422,
"code": "INVALID_PARTS",
"detail": "The part list for this upload was rejected by S3. Check that every part is listed with the ETag S3 returned for it."
}
}
]
}{
"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
}