Thru Content API - File Upload
Overview
The ThruContent API provides two primary methods for uploading files:
Simple Upload
Use it when you need to upload files in one chunk and you have a stable connection. Usually can be used for small files, but limited to 2G file size.
Chunked Upload
Use it when you need to upload large file or when you have unstable network connection. This upload method provides mechanism to resume upload in case of network issue or interruption. It also works for small files (less than chunk size) but less-performance in this case than Simple Upload
Endpoint path
As part of initiation upload process client should provide endpoint path where file should be uploaded, it is represented by string in following format:
"flow:{FlowCode}/endpoint:{EndpointCode}/flowendpoint:{Id}"
Simple Upload
Use POST /api/Files/1.0/Content with multipart/form-data payload where first form-data section represents file-metadata and flow endpoint resource path and second form-data section file content.
Chunked Upload
This upload is useful in case of upload large files. It allows to resume file upload and also make parallel upload of different parts of the file.
Chunked upload is consists from three steps:
Create upload session
Upload content of file using chunk mechanism
Complete upload session
Create upload session
Use POST /api/Files/1.0/Upload_Sessions to create an upload session and get UID.
Client may include file metadata section as part of this request, however client can set metadata lately using PATH /api/Files/1.0/Upload_Sessions but it should do that before the upload session will be committed.
Upload Content
This documentation is not published yet, this is only a preview. Changes to the publishing settings will reload this page.
Use PUT /api/File/1.0/Upload_Sessions/{sessionUID} to send chunk to the server. Each chunk should be send as multipart/form-data where first form-data section is represents chunk metadata and second section is content
Complete Upload
Use POST /api/Files/1.0/Upload_Sessions/{sessionUID}/Commit when all file chunks are uploaded to server If you need to cancel or abort upload: POST /api/Files/1.0/Upload_Sessions/{sessionUID}/Abort
Get information about Upload Session
Use GET /api/Files/1.0/Upload_Sessions/:upload_session to get information about upload session. This method is useful when you need to restore upload and want to get upload state on the server. This method will return error response if upload session doesn't exist.
Upload preflight
Use OPTION /api/Files/1.0/Content request with file metadata to check if server will be able to accept the file according to the pre-defined server rules for the source flow endpoint.
Upload API provides the way to upload files to some of source flow endpoints types
Authentication
All requests require a Bearer token or API Key in the Authorization header
Ensure you have a valid JWT token for authentication
Upload Methods
1. Preflight Check (OPTIONS)
Endpoint: /api/Files/1.0/Content
Purpose: Validate file upload and get upload configuration
Method: OPTIONS
Request Body Example:
{
"endpointPath": "flow:FLCKGR/endpoint:END9GSR/flowendpoint:6",
"attributes": {
"fileTime": "06/22/2022",
"fileName": "test2.test",
"path": "\\6to6\\S6"
}
}
Expected Response:
Provides upload configuration details
Maximum chunk size
Upload URLs for single and chunked file uploads
This endpoint is used to check if the server will accept the file to be uploaded, based on the pre-defined rules for the source flow endpoint. The client sends the file metadata in the request body, and the server responds with the maximum chunk size and the URLs for uploading single files and chunked files.
2. Simple Upload (Single Chunk)
Use it when you need to upload files in one chunk and you have a stable connection. Usually can be used for small files, but limited to 2G file size.
Endpoint: /api/Files/1.0/Content
Purpose: Upload small files (up to 2GB) in a single request
Method: POST
Content-Type: multipart/form-data
Request Components:
First part: File metadata (JSON)
Second part: Actual file content
Recommended For:
Small files
Stable network connections
Quick uploads
This endpoint is used for simple file uploads. The client sends the file metadata and content in a single multipart/form-data request.
3. Chunked Upload Process
Use it when you need to upload large file or when you have unstable network connection. This upload method provides mechanism to resume upload in case of network issue or interruption. It also works for small files (less than chunk size) but less-performance in this case than Simple Upload
3.1 Create Upload Session
Endpoint: /api/Files/1.0/Upload_Sessions
Purpose: Initiate a chunked file upload and get a session ID
Method: POST
Request Body Example:
{
"endpointPath": "flow:FLCKGR/endpoint:END9GSR/flowendpoint:6",
"attributes": {
"fileTime": "06/22/2022",
"fileName": "test4.test",
"path": "\\6to6\\S6"
}
}
Response:
Receives
x-thru-transferid
(Upload Session ID) in response headers
This endpoint is used to create an upload session for a chunked upload. The client can include the file metadata in the request body, but can also set it later using the PATCH endpoint.
3.2 Update Session Metadata (Optional)
Endpoint: /api/Files/1.0/Upload_Sessions/:uploadSession
Purpose: Update file metadata for an existing upload session
Method: PATCH
Use Case: If metadata wasn't specified during session creation
This endpoint is used to set the file metadata for an existing upload session, before any file content is uploaded.
3.3 Upload File Chunks
Endpoint: /api/Files/1.0/Upload_Sessions/:uploadSession
Purpose: Upload individual file chunks
Method: PUT
Content-Type: multipart/form-data
Request Components:
First part: Chunk metadata (sequence number)
Second part: File chunk content
This endpoint is used to upload a chunk of the file content. The client sends the chunk metadata and content in a multipart/form-data request.
3.4 Commit Upload
Endpoint: /api/Files/1.0/Upload_Sessions/:uploadSession/Commit
Purpose: Complete and close the upload session
Method: POST
When to Use: After all file chunks have been uploaded
This endpoint is used to complete and close the upload session, and queue the file assembly on the server side.
3.5 Abort Upload
Endpoint: /api/Files/1.0/Upload_Sessions/:uploadSession/Abort
Purpose: Cancel an ongoing upload
Method: POST
Request Body Example:
{
"status": 0, // 0: Error, 1: Cancelled
"message": "Upload aborted"
}
This endpoint is used to abort the upload due to an error or cancellation on the client side. The client provides details about the abort operation in the request body.
3.6 Get Upload Session Status
Endpoint: /api/Files/1.0/Upload_Sessions/:upload_session
Purpose: Retrieve information about an ongoing upload
Method: GET
Use Cases:
Check upload progress
Resume interrupted uploads
Verify committed chunks
This endpoint is used to get information about the uploaded chunks during an active upload session, which can be useful for resuming the upload after an interruption.
Endpoint Path Format
The endpoint path follows this structure:flow:{FlowCode}/endpoint:{EndpointCode}/flowendpoint:{Id}
Best Practices
Use Simple Upload for files < 100MB
Use Chunked Upload for:
Large files
Unstable network connections
Need to resume interrupted uploads
Always perform a preflight check before uploading
Handle potential errors and implement retry mechanisms
Common Error Scenarios
409 Conflict: Invalid file path
Authentication failures
Network interruptions during upload
Contact the support team for an example json provided as a postman collection.