Manage files

List files in folder

This example demonstrates how to create a folder. A folder can be created either as a top-level one, or within an already existing folder.

HTTP Method

Request URL
GET

https://{base_url}/rest/folders/{folder_id}/files

The value of folder_id indicates the UUID of the folder, where your files are located.

A successful request returns a 200 OK status code. The response body contains an array of JSON representations of the files.

Example request and response

Copy

Example request

curl -X GET "$KW_INSTANCE_URL/rest/folders/uuid0001-0000-0000-0000-000000000001/files" \
  -H "Authorization: Bearer $KW_ACCESS_TOKEN" \
  -H "X-Accellion-Version: 28" \
  -H "Content-Type: application/json"
Copy

Example response

[
    {
        "mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "fingerprint": "hash0001",
        "sharedTime": None,
        "clientCreated": None,
        "adminQuarantineStatus": "allowed",
        "tags": [],
        "safeEdit": {
            "safeEditLocked": False,
            "user": None
        },
        "parentId": "uuid0001-0000-0000-0000-000000000001",
        "userId": "uuid0002-0000-0000-0000-000000000002",
        "lockUser": None,
        "permDeleted": False,
        "fingerprints": [
            {
                "algo": "sha3-256",
                "hash": "hash0002"
            },
            {
                "algo": "md5",
                "hash": "hash0001"
            }
        ],
        "id": "uuid0003-0000-0000-0000-000000000003",
        "originalFileId": None,
        "path": "GenericFolder/Example_Subfolder/Example_Document.docx",
        "isShared": False,
        "permalink": "https://content.kiteworks.com/w/f-uuid0003-0000-0000-0000-000000000003",
        "modified": "2025-01-01T00:00:00+0000",
        "clientModified": "2025-01-01T00:00:00+0000",
        "creator": {
            "id": "uuid0002-0000-0000-0000-000000000002",
            "name": "Generic User",
            "profileIcon": "uuid0002-0000-0000-0000-000000000002",
            "email": "user@example.com"
        },
        "type": "f",
        "name": "Example_Document.docx",
        "pushed": False,
        "overriddenExpire": False,
        "locked": False,
        "size": 75395,
        "deleted": True,
        "source": None,
        "sharedBy": None,
        "modifier": {
            "id": "uuid0002-0000-0000-0000-000000000002",
            "name": "Generic User",
            "profileIcon": "uuid0002-0000-0000-0000-000000000002",
            "email": "user@example.com"
        },
        "dlpStatus": "allowed",
        "created": "2025-01-01T00:00:00+0000",
        "expire": 0,
        "wopiapp": None,
        "secure": False,
        "avStatus": "allowed"
    }
]

Python code sample

Upload a file

This example demonstrates how to upload a new file to a previously created folder. You must initiate a multi-chunks Upload before you can upload any part. In the response of your initiate request, the API returns an upload ID that you must include in the upload as part of the request. In this example, a file 'MyNewFile.txt' will be uploaded in 2 chunks with 1KB in each chunk (the user can choose their own chunk size).

Initiate multi-chunks upload

HTTP Method

Request URL
POST

https://{base_url}/rest/folders/{folder_id}/actions/initiateUpload

Request Body

filename - The new file name

totalSize - the total size of the file

totalChunks - the total number of chunks

Copy
Example request body
{
  "filename": "MyNewFile.txt",
  "totalSize": 2048,
  "totalChunks": 2
}

Response

If the upload is initiated successfully, the response is a 201 Created status code. The response body contains a JSON representation of the chunk upload info, including a id property (7890 in this sample request) that you can use as the value of upload_id for subsequent requests.

Example request and response

Copy

Example request

   -X POST 'https://{hostname}/rest/folders/1234/actions/initiateUpload' \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' \
   -H 'X-Kiteworks-Version: 15' \
   -H 'Authorization: Bearer {access_token}' \
   -d '{"filename": "MyNewFile.txt", "totalSize": 2048, totalChunks': 2}'
Copy

Example response

{
    "error": "OK",
    "totalSize": 2048,
    "timestamp": "2020-05-15T08:11:07Z",
    "uri": "dacfs_upload1/rest/uploads/7890",
    "userId": 1,
    "lastTimestamp": "2020-05-15T08:11:07Z",
    "uploadedSize": 0,
    "clientName": "API Playground",
    "fileUrl": "",
    "location": "{hostname}",
    "totalChunks": 2,
    "uploadedChunks": 0,
    "completeOk": 0,
    "svrUploadTime": 0,
    "id": 7890,
    "replaceId": null,
    "backend": "acfs"
}

 

Chunk upload

HTTP Method

Request URL
POST

https://{base_url}/rest/uploads/{upload_id}

Request Body

HTTP Method

Request URL
compressMode

The compression mode of the chunk (only NORMAL is supported).

compressionSize

The compressed size (it’s always the same as originalSize).

originalSize

The original size of the chunk.

index

The chunk index for this file. Starts from 1.

lastChunk

When set to '1', indicates that this is the last chunk, after which the upload is completed.
Copy
Example request body
{
  "compressionMode": "NORMAL",
  "compressionSize": 1024,
  "originalSize": 1024,
  "index": 1
}

Response

If the individual chunk is completed, the response is a 200 OK status code. Once the whole multi-chunks upload is completed successfully, the response is a 201 Created status code. The response body contains a JSON representation of the chunk upload info, including a id property (7890 in this sample request) that you can use for subsequent requests.

Example request and response

Copy

Example request

   -X POST 'https://{hostname}/rest/uploads/7890?returnEntity=true' \
   -H 'Accept: application/json' \
   -H 'X-Kiteworks-Version: 15' \
   -H 'Authorization: Bearer {access_token}' \
   -F 'compressionMode=NORMAL' \
   -F 'compressionSize=1024' \
   -F 'originalSize=1024' \
   -F 'index=1' \
   -F 'content=@/tmp/MyNewFile.txt_chunk_1'
Copy

Example response (chunk)

{
    "error": "OK",
    "totalSize": 2048,
    "timestamp": "2020-05-15T08:11:07Z",
    "uri": "dacfs_upload1/rest/uploads/7890",
    "userId": 1,
    "lastTimestamp": "2020-05-15T08:11:07Z",
    "uploadedSize": 1024,
    "clientName": "OAuth Playground",
    "fileUrl": "",
    "location": "{hostname}",
    "totalChunks": 2,
    "uploadedChunks": 1,
    "completeOk": 0,
    "svrUploadTime": 0,
    "id": 7890,
    "replaceId": null,
    "backend": "acfs"
}
Copy

Example response (final chunk)

{
    "locked": false,
    "description": "",
    "created": "2020-05-15T06:25:16Z",
    "deleted": false,
    "clientModified": null,
    "fingerprint": "Generating...",
    "userId": 1,
    "modified": "2020-05-15T09:30:14Z",
    "clientCreated": null,
    "name": "MyNewFile.txt",
    "overriddenExpire": false,
    "expire": null,
    "mime": "text/plain",
    "permDeleted": false,
    "parentId": 1234,
    "type": "f",
    "id": 1240,
    "size": 2048
}

Python code sample

In this code sample, the following operations are included:

  • Retrieving ID of the folder, where the file is to be uploaded. This is done by providing the path to this folder.

  • Initiating multi-chunk upload

  • Proceeding with the upload of chunks

 

Download a file

This example demonstrates how to download a file from Kiteworks based on the provided path to the file.

HTTP Method

Request URL
GET

https://{base_url}/rest/files/{file_id}/content

The value of file_id indicates the UUID of the file you want downloaded. A successful request returns a 200 OK status code.

Note: If the file ID is not known, it can be retrieved by making a GET request to /rest/search?path={kw_path_to_file}, where kw_path_to_file is the path to the file to be downloaded.

Python code sample

The steps that this sample includes are:

  • Retrieve the file ID based on the file path provided. This is done via a GET {base_url}/rest/search?path={path_to_file} request

  • Download the file via a GET {base_url}/rest/files/{file_id}/content request