Skip to main content
Skip table of contents

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:

  1. Create upload session

  2. Upload content of file using chunk mechanism

  3. 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:

JSON 
{
    "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:

JSON 
{
    "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:

JSON 
{
    "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

  1. Use Simple Upload for files < 100MB

  2. Use Chunked Upload for:

    • Large files

    • Unstable network connections

    • Need to resume interrupted uploads

  3. Always perform a preflight check before uploading

  4. 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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close