### List Top Level Folders

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

This example demonstrates how to retrieve a list of top level folders.

```APIDOC
## GET /rest/folders/top

### Description
Retrieves a list of all top-level folders.

### Method
GET

### Endpoint
https://{base_url}/rest/folders/top

### Response
#### Success Response (200 OK)
- An array of JSON representations of the folders.
```

--------------------------------

### Example Response Structure

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

This is an example of the JSON response structure when listing files in a folder. It details file properties such as ID, name, path, creation date, and modification information.

```json
[
  {
    "avStatus": "allowed",
    "tags": [],
    "deleted": false,
    "sharedBy": null,
    "id": "f333a444-b555-c666-d777-e888999000fff  
",
    "dlpStatus": "allowed",
    "overriddenExpire": false,
    "path": "My Folder/My Sub-folder/my-file.csv"
    "originalFileId": null,
    "creator": {
      "profileIcon": "a111b222-c333-d444-e555-f666777888aaa",
      "name": "John Doe",
      "id": "a111b222-c333-d444-e555-f666777888aaa",
      "email": "user@example.com"
    },
    "fingerprint": "c8e1128f94a57129f59aa39f230c7844",
    "pushed": false,
    "secure": false,
    "sharedTime": null,
    "wopiapp": null,
    "modified": "2026-01-21T20:43:42+0000",
    "modifier": {
      "profileIcon": "a111b222-c333-d444-e555-f666777888aaa",
      "name": "John Doe",
      "id": "a111b222-c333-d444-e555-f666777888aaa",
      "email": "user@example.com"
    },
    "locked": false,
    "parentId": "c222d333-e444-f555-a666-b777888999ccc",
    "created": "2026-01-21T20:43:42+0000",
    "isShared": false,
    "mime": "text/plain",
    "type": "f",
    "size": 30,
    "fingerprints": [
      {
        "algo": "sha3-256",
        "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      {
        "algo": "md5",
        "hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      }
    ],
    "source": null,
    "clientModified": null,
    "adminQuarantineStatus": "allowed",
    "name": "my-file.csv",
    "userId": "a111b222-c333-d444-e555-f666777888aaa",
    "permDeleted": false,
    "permalink": "https://content.example.com/w/f-f333a444-b555-c666-d777-e888999000fff  
",
    "lockUser": null,
    "clientCreated": null,
    "safeEdit": {
      "safeEditLocked": false,
      "user": null
    },
    "expire": 0
  }
]
```

--------------------------------

### Create Folder

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

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.

```APIDOC
## POST /rest/folders/{parent_folder_id}/folders

### Description
Creates a new folder. The `parent_folder_id` specifies the parent folder, with `0` indicating a top-level folder.

### Method
POST

### Endpoint
https://{base_url}/rest/folders/{parent_folder_id}/folders

### Parameters
#### Query Parameters
- **returnEntity** (boolean) - Optional - If true, the newly created folder object is returned in the response body.

#### Request Body
- **name** (string) - Required - The name of the folder.
- **description** (string) - Optional - A description for the folder.
- **secure** (boolean) - Optional - Indicates if the folder is secure.
- **syncable** (boolean) - Optional - Indicates if the folder is syncable.

### Request Example
```curl
curl -X POST "https://{base_url}/rest/folders/0/folders?returnEntity=true" \
  -H "X-Accellion-Version: 28" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{  
    "name": "The new Top Level Folder",  
    "description": "This is a top-level folder.",  
    "secure": false,  
    "syncable": false  
  }'
```

### Response
#### Success Response (201 Created)
- **secure** (boolean) - Description
- **maxFileLifetime** (integer) - Description
- **permDeleted** (boolean) - Description
- **useFolderQuota** (boolean) - Description
- **source** (string) - Description
- **type** (string) - Description
- **parentId** (string) - Description
- **path** (string) - Description
- **expire** (integer) - Description
- **maxFolderExpiration** (integer) - Description
- **permalink** (string) - Description
- **id** (string) - Description
- **created** (string) - Description
- **description** (string) - Description
- **syncable** (boolean) - Description
- **fileLifetime** (integer) - Description
- **modified** (string) - Description
- **deleted** (boolean) - Description
- **name** (string) - Description
- **userId** (string) - Description

#### Response Example
```json
{
  "secure": false,
  "maxFileLifetime": 0,
  "permDeleted": false,
  "useFolderQuota": false,
  "source": null,
  "type": "d",
  "parentId": "0",
  "path": "The new Top Level Folder",
  "expire": 0,
  "maxFolderExpiration": 0,
  "permalink": "https://content.kiteworks.com/w/f-b333c444-d555-e666-f777-a888999000bbb",
  "id": "b333c444-d555-e666-f777-a888999000bbb",
  "created": "2026-02-04T11:14:18+0000",
  "description": "This is a top-level folder.",
  "syncable": false,
  "fileLifetime": 0,
  "modified": "2026-02-04T11:14:18+0000",
  "deleted": false,
  "name": "The new Top Level Folder",
  "userId": "a111b222-c333-d444-e555-f666777888aaa"
}
```
```

--------------------------------

### Send Email Request Example (cURL)

Source: https://developer.kiteworks.com/api-guides/manage-mail.htm

Example of sending an email using cURL. Ensure to replace YOUR_ACCESS_TOKEN with your actual token and adjust the base URL.

```bash
curl -X POST "{base_url}/rest/mail/actions/sendFile?returnEntity=True" \
  -H "X-Accellion-Version: 28" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "subject": "Test mail subject",
        "body": "Test mail body",
        "to": [
            "recipient1@example.com",
            "recipient2@example.com"
        ],
        "cc": [],
        "bcc": [],
        "draft": "true",
        "secureBody": "false"
    }'
```

--------------------------------

### Create a Folder using Python

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

This Python script demonstrates how to create a folder using the requests library. It includes a function to handle the API call and a main section to get user input for the base URL and folder details.

```python
import requests
import json
from get_access_token import KWOAuthClient

"""
Create a top-level folder in Kiteworks
"""

def create_folder(base_url, access_token, folder_data):

 url = f"{base_url}/rest/folders/0/folders"

 headers = {
 'X-Accellion-Version': '28',
 'Authorization': f'Bearer {access_token}',
 'Content-Type': 'application/json'
 }

 params = {
 "returnEntity": "true"
 }

 res = requests.post(url, headers=headers, params=params, data=json.dumps(folder_data))

 return res

def main():
 base_url = input("Enter Base URL for Kiteworks Instance: ")
 client = KWOAuthClient(base_url)
 access_token = client.get_access_token()

 folder_data = {
 "name": "The Top Level Folder",
 "description": "This is a top-level folder.",
 "secure": False,
 "syncable": False,
 # "clientId": "", # Optional, provide if applicable
 # "vendorDocId": "", # Optional, provide if applicable
 # "isFolderUpload": False, # Optional, for internal use only
 # "expire": "", # Optional, provide if applicable (format not defined)
 # "rename": False, # Optional
 # "fileLifetime": 0 # Optional, provide if applicable
 }


 response = create_folder(base_url, access_token, folder_data)

 print(response.json())


if __name__ == "__main__":
 main()
```

--------------------------------

### List Top-Level Folders

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

This example demonstrates how to retrieve a list of top-level folders. A successful request returns a 200 OK status code with an array of folder objects in the response body.

```http
GET https://{base_url}/rest/folders/top
```

--------------------------------

### Send Email with Attachment using Python

Source: https://developer.kiteworks.com/api-guides/manage-mail.htm

Use this Python script to send an email with a file attachment. It handles creating the email draft, uploading the file in chunks, and sending the final email. Ensure you have the `requests` library and `get_access_token` module installed.

```python
import os
import requests
from get_access_token import KWOAuthClient

"""
Compose an email, attach a file to the email, and send the message.  

User Inputs:
 1. file_path: Local file path of the file you want to upload  
 2. file_name: Name of the attachment you want that file to be called.  
 3. subject: Subject of email  
 4. body: Message body of email  
"""

def send_mail(base_url, access_token, file_name, file_path, subject, body, recipient):
 headers = {
 "X-Accellion-Version": '28',
 "Authorization": f"Bearer {access_token}"
 }

 # Step 1: Create the email
 url_create_email = f"{base_url}/rest/mail/actions/sendFile?returnEntity=True"

 # Request body
 data_create_email = {
 "subject": subject,
 "body": body, #Change email body
 "to": [recipient], #Change recipients here
 "draft": "true",
 "secureBody": "false"
 }

 # Make the POST request to create the email and get the email ID
 create_email_response = requests.post(url_create_email, headers=headers, json=data_create_email)
 # Check the response
 if create_email_response.status_code != 201:
 print("Failed to send email:", create_email_response.text)
 return

 create_mail_json = create_email_response.json()
 mail_id = create_mail_json["id"]

 # Step 2: Initiate the file upload

 initiate_upload_url = f"{base_url}/rest/mail/{mail_id}/actions/initiateUpload?returnEntity=true"
 file_size = os.path.getsize(file_path)
 initiate_upload_payload = {
 "totalChunks": 1,
 "totalSize": file_size,
 "filename": file_name
 }

 initiate_upload_response = requests.post(initiate_upload_url, headers=headers, json=initiate_upload_payload)
 initiate_upload_data = initiate_upload_response.json()
 upload_url = initiate_upload_data["uri"]

 # Step 2: Upload the file chunk
 upload_url = f"{base_url}/{upload_url}?returnEntity=True"

 compression_mode = "NORMAL" # Available options: "NORMAL", "GZIP", "ZLIB"
 compression_size = file_size # Assuming no compression, set to original file size
 original_size = file_size

 payload = {
 "compressionMode": (None, compression_mode),
 "compressionSize": (None, str(compression_size)),
 "originalSize": (None, str(original_size)),
 "content": (file_name, open(file_path, "rb"))
 # "index": (None, "1"), # Optional: Chunk index, starts from 1
 # "lastChunk": (None, "1") # Optional: Indicate if this is the last chunk
 }

 upload_response = requests.post(upload_url, headers=headers, files=payload)

 if upload_response.status_code == 201:
 uploaded_file_data = upload_response.json()
 print("File uploaded successfully.")
 file_id = uploaded_file_data["id"]

 # Step 3: Send the email
 url_send_email = f"{base_url}/rest/mail/{mail_id}/actions/sendFile?returnEntity=True"
 data_send_email = {
 "files": [file_id],
 "draft": "false",
 "uploading": 0
 }

 # Make the PUT request to send the email
 send_email_response = requests.put(url_send_email, headers=headers, json=data_send_email)
 # Check the response
 if send_email_response.status_code == 200:
 print("Email sent successfully")
 else:
 print("Failed to send email:", send_email_response.text)

def main():
 base_url = input("Enter Base URL for Kiteworks Instance: ")
 client = KWOAuthClient(base_url)
 access_token = client.get_access_token()

 file_path = input("Enter local file path of file to upload: ")
 file_name = input("Enter name of attachment: ")
 subject = input("Enter Email Subject: ")
 body = input("Enter Email Message Body: ")
 recipient = input("Enter email address of recipient: ")

 send_mail(base_url, access_token, file_name, file_path, subject, body, recipient)

if __name__ == "__main__":
 main()
```

--------------------------------

### Authorization Request

Source: https://developer.kiteworks.com/api-overview/authorization-code.htm

Initiates the authorization process by requesting an authorization code from the server. This is an HTTP GET request.

```APIDOC
## GET /oauth/authorize

### Description
Requests an authorization code from the server. The user may be prompted to authenticate and authorize the client application.

### Method
GET

### Endpoint
https://{kiteworks_server}/oauth/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The identifier of the client application as registered in the server.
- **redirect_uri** (string) - Required - The URI to which the result of the authorization will be passed. Must be a registered redirect URI for the client application and properly URL-encoded.
- **response_type** (string) - Required - Value must be set to 'code'.
- **scope** (string) - Optional - A space-separated string of API services the client wants to access. If blank, the registered scope is assumed.
- **m** (integer) - Optional - Set to 1 to display a mobile-friendly authorization page.
- **state** (string) - Optional - An opaque value used to maintain state between the request and callback.

### Request Example
```http
GET https://{kiteworks_server}/oauth/authorize?client_id=abc&response_type=code&scope=&redirect_uri= https%3A%2F%2F{kiteworks_server}%2Foauth_callback.php HTTP/1.1
```

### Response
#### Success Response (302 Found)
Redirects to the `redirect_uri` with `code` and `state` parameters.

#### Response Example
```http
HTTP/1.1 302 Found
Location: https://{kiteworks_server}/oauth_callback.php?code=60cc146c8dced75e26e
```

#### Error Response (302 Found)
Redirects to the `redirect_uri` with an `error` parameter.

#### Response Example
```http
HTTP/1.1 302 Found
Location: https://{kiteworks_server}/oauth_callback.php?error=access_denied
```

### Error Codes
- **access_denied**: The user denied the permission request.
- **invalid_scope**: The requested scope is invalid.
- **invalid_request**: The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed.
- **unauthorized_client**: The client-application is not authorized to use this flow.
```

--------------------------------

### List Top-Level Folders

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

Retrieves a list of all top-level folders in your Kiteworks instance. This is useful for getting an overview of your folder structure.

```APIDOC
## GET /rest/folders/top

### Description
Retrieves a list of all top-level folders.

### Method
GET

### Endpoint
/rest/folders/top

### Headers
- X-Accellion-Version (string) - Required
- Authorization (string) - Required
- Content-Type (string) - Required

### Query Parameters
- orderBy (string) - Optional - Sorting options: name, modified, created, size
- offset (integer) - Optional - Pagination offset
- limit (integer) - Optional - Pagination limit
- deleted (string) - Optional - Include deleted: true, false, none
- with (string) - Optional - Additional data to include
- returnEntity (string) - Optional - Whether to return the entity in the response

### Response
#### Success Response (200)
- Array of folder objects, each containing details like id, name, path, created, modified, etc.

### Response Example
```json
[
  {
    "useFolderQuota": false,
    "parentId": "0",
    "userId": "a111b222-c333-d444-e555-f666777888aaa",
    "description": "My folder for testing purposes",
    "permDeleted": false,
    "id": "b111c222-d333-e444-f555-a666777888bbb",
    "path": "My Folder",
    "isShared": true,
    "permalink": "https://content.example.com/w/f-b111c222-d333-e444-f555-a666777888bbb",
    "modified": "2025-11-07T15:06:25+0000",
    "creator": {
      "id": "a111b222-c333-d444-e555-f666777888aaa",
      "name": "jane.doe@example.com",
      "profileIcon": "a111b222-c333-d444-e555-f666777888aaa",
      "email": "jane.doe@example.com"
    },
    "type": "d",
    "name": "My Folder",
    "deleted": false,
    "maxFolderExpiration": 0,
    "source": null,
    "fileLifetime": 0,
    "syncable": true,
    "created": "2014-01-20T23:01:39+0000",
    "expire": 0,
    "maxFileLifetime": 0,
    "secure": false
  }
  ...
]
```
```

--------------------------------

### Kiteworks OAuth Client Initialization and Token Retrieval (Python)

Source: https://developer.kiteworks.com/api-overview/authorization-code.htm

This script demonstrates how to initialize the Kiteworks OAuth client and retrieve an access token. It requires the base URL of the Kiteworks instance.

```python
if __name__ == "__main__":
 base_url = input("Enter Base URL for Kiteworks Instance: ")
 client = KWOAuthClient(base_url)
 token = client.get_access_token()
 print("Got access token:", token)
```

--------------------------------

### Timezones API

Source: https://developer.kiteworks.com/api-guides/api-endpoints.htm

List all supported time zones and get details about them, including name and time offset.

```APIDOC
## Timezones API

### Description
Lists all supported time zones and provides details such as name and time offset.

### Method
GET

### Endpoint
/timezones
```

--------------------------------

### Initiate Multi-Chunk Upload Request (cURL)

Source: https://developer.kiteworks.com/api-guides/manage-files.htm

This cURL command demonstrates how to send a POST request to initiate a multi-chunk upload. Ensure you replace placeholders like {hostname} and {access_token}.

```bash
  -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}'
```

--------------------------------

### Initiate File Upload

Source: https://developer.kiteworks.com/api-guides/manage-mail.htm

Initiates a file upload process, specifying the filename and total size. This is the first step before uploading file chunks.

```shell
   -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}'
```

--------------------------------

### Initiate File Upload

Source: https://developer.kiteworks.com/api-guides/manage-mail.htm

Initiates a file upload process for a given folder, returning upload details and a URI for subsequent chunk uploads.

```APIDOC
## POST /rest/folders/{folder_id}/actions/initiateUpload

### Description
Initiates the upload process for a file within a specified folder. This endpoint prepares the system for receiving file data and provides a URI to be used for uploading file chunks.

### Method
POST

### Endpoint
`https://{hostname}/rest/folders/{folder_id}/actions/initiateUpload`

### Parameters
#### Request Body
- **filename** (string) - Required - The name of the file to be uploaded.
- **totalSize** (integer) - Required - The total size of the file in bytes.
- **totalChunks** (integer) - Required - The total number of chunks the file will be divided into for uploading.

### Request Example
```json
{
  "filename": "MyNewFile.txt",
  "totalSize": 2048,
  "totalChunks": 2
}
```

### Response
#### Success Response (200)
- **error** (string) - Indicates the status of the operation, typically 'OK' on success.
- **totalSize** (integer) - The total size of the file.
- **timestamp** (string) - The timestamp when the upload was initiated.
- **uri** (string) - The URI to be used for uploading file chunks.
- **userId** (integer) - The ID of the user initiating the upload.
- **lastTimestamp** (string) - The timestamp of the last activity related to the upload.
- **uploadedSize** (integer) - The size of the file uploaded so far.
- **clientName** (string) - The name of the client initiating the upload.
- **fileUrl** (string) - The URL of the uploaded file (if applicable).
- **location** (string) - The hostname where the file is stored.
- **totalChunks** (integer) - The total number of chunks for the file.
- **uploadedChunks** (integer) - The number of chunks uploaded so far.
- **completeOk** (integer) - Status indicating if the upload is complete.
- **svrUploadTime** (integer) - Server upload time.
- **id** (integer) - The unique identifier for the upload session.
- **replaceId** (any) - Identifier for replacement, if applicable.
- **backend** (string) - The backend storage system used.

#### Response Example
```json
{
  "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"
}
```
```

--------------------------------

### Create a Top-Level Folder using cURL

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

Use this cURL command to create a new top-level folder. Ensure you replace YOUR_ACCESS_TOKEN with a valid token and adjust the base URL. The request body defines the folder's properties.

```bash
curl -X POST "https://{base_url}/rest/folders/0/folders?returnEntity=true" \
  -H "X-Accellion-Version: 28" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "The new Top Level Folder",
    "description": "This is a top-level folder.",
    "secure": false,
    "syncable": false
}'
```

--------------------------------

### Create Email Draft or Send Immediately

Source: https://developer.kiteworks.com/api-guides/manage-mail.htm

Use this endpoint to create a new email. Set 'draft' to 'true' to save as a draft or 'false' to send immediately. The response provides the email ID for further actions.

```json
{
    "subject": "Test mail subject",
    "body": "Test mail body",
    "to": [
        "recipient1@example.com",
        "recipient2@example.com"
    ],
    "cc": [],
    "bcc": [],
    "draft": "true",
    "secureBody": "false"
}
```

--------------------------------

### Users API

Source: https://developer.kiteworks.com/api-guides/api-endpoints.htm

Obtain basic user information, root folders, and navigate user-accessible files and folders.

```APIDOC
## GET /users/me

### Description
Retrieves the ID, root folder IDs, email, name, and status of the authenticated user.

### Method
GET

### Endpoint
/users/me
```

--------------------------------

### List Top-Level Folders (Python)

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

This Python script lists all top-level folders in Kiteworks. It requires the 'requests' library and a 'KWOAuthClient' for authentication. Optional parameters for sorting, pagination, and filtering can be uncommented and configured.

```python
import requests
from get_access_token import KWOAuthClient

"""
Lists all the top-level folders in Kiteworks
"""

def list_top_level_folders(base_url, access_token):
  url = f"{base_url}/rest/folders/top"
  headers = {
  'X-Accellion-Version': '28',
  'Authorization': f'Bearer {access_token}',
  'Content-Type': 'application/json'
  }
  # Optional parameters can be included in the query string if needed
  params = {
  # 'orderBy': 'name:asc', # Sorting options: name, modified, created, size
  # 'offset': 0, # Pagination offset
  # 'limit': 10, # Pagination limit
  # 'deleted': 'false', # Include deleted: true, false, none
  # 'with': '', # Additional data to include
  # 'returnEntity': 'false' # Whether to return the entity in the response
  }
  
  response = requests.get(url, headers=headers, params=params)
  if response.status_code == 200:
  return response.json()
  else:
  return f"Failed to retrieve folders: {response.status_code} - {response.text}"

def main():
  base_url = input("Enter Base URL for Kiteworks Instance: ")
  client = KWOAuthClient(base_url)
  access_token = client.get_access_token()

  folders_data = list_top_level_folders(base_url, access_token)
  print(folders_data)

if __name__ == "__main__":
  main()
```

--------------------------------

### Request Access Token with Authorization Code

Source: https://developer.kiteworks.com/api-overview/authorization-code.htm

Send this POST request to the token endpoint to exchange an authorization code for an access token. Ensure client credentials and the authorization code are valid. Optional parameters like install_tag_id and install_name can be included for device identification.

```http
POST /oauth/token HTTP/1.1
Host: {kiteworks_server}
Content-type: application/x-www-form-urlencoded

client_id=abc&client_secret=TheSecret&grant_type=authorization_code&code=c88bc36f751549adf60658c2c607a03b52e417bc& redirect_uri= https%3A%2F%2F{kiteworks_server}%2Foauth_callback.php &install_tag_id=device_123&install_name=user_ipad
```

--------------------------------

### List Files in a Folder using Python

Source: https://developer.kiteworks.com/api-guides/manage-files.htm

This Python script utilizes the requests library to list files in a specified folder. It requires an access token and the folder ID. Optional query parameters can be uncommented to filter or modify the results.

```python
import requests
from get_access_token import KWOAuthClient

"""
Generate list of files in a specific folder.

User Inputs:
 1. folder_id: ID of the folder.
"""

def list_files_in_folder(base_url, access_token, folder_id):
  
 url = f"{base_url}/rest/folders/{folder_id}/files"
 headers = {
 'Authorization': f'Bearer {access_token}',
 'X-Accellion-Version': '28',
 'Content-Type': 'application/json'
 }
 # Optional query parameters
 params = {
 # 'name': 'exampleFileName', # Uncomment and set the file name to filter by name
 # 'userId': 'exampleUserId', # Uncomment and set the user ID to filter by creator
 # 'limit': 10, # Uncomment and set the limit of files to retrieve
 # 'offset': 0, # Uncomment and set the offset for pagination
 # 'orderBy': 'name:asc', # Uncomment and set the order by criteria
 # 'returnEntity': 'false' # Uncomment and set to 'true' if you want to return the entity
 }
 
 response = requests.get(url, headers=headers, params=params)
 if response.status_code == 200:
 return response.json().get('data', [])
 else:
 return response.status_code, response.text

def main():
 base_url = input("Enter Base URL for Kiteworks Instance: ")
 client = KWOAuthClient(base_url)
 access_token = client.get_access_token()

 parent_folder_id = input("Enter parent folder ID: ")
 files = list_files_in_folder(base_url, access_token, parent_folder_id)
 print(files)

if __name__ == "__main__":
 main()
```

--------------------------------

### Kiteworks OAuth Client and Token Management (Python)

Source: https://developer.kiteworks.com/api-overview/authorization-code.htm

This class handles client authentication and token storage. It prompts for client ID and secret, and provides methods to save and retrieve tokens.

```python
self.token_data = None # format: {'access_token':..., 'refresh_token':..., 'expiry':...}
self.client_id = input("Enter your Client ID: ")
self.client_secret = input("Enter your Client Secret: ")

def get_client_id(self):
 return self.client_id

def get_client_secret(self):
 return self.client_secret

def save_tokens(self, access_token, refresh_token, expiry):
 self.token_data = {
 'access_token': access_token,
 'refresh_token': refresh_token,
 'expiry': expiry
 }

def retrieve_saved_access_token(self):
 return self.token_data

def retrieve_saved_refresh_token(self):
 if self.token_data and 'refresh_token' in self.token_data:
 return self.token_data['refresh_token']
 return None
```

--------------------------------

### List Files in a Folder (Python)

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

This Python script lists files in a specified folder using the Kiteworks API. It requires the `requests` library and a function to obtain an access token. You can uncomment and set query parameters to filter or modify the results.

```python
import requests
from get_access_token import KWOAuthClient

"""
Generate list of files in a specific folder.

User Inputs:
 1. folder_id: ID of the folder.
"""

def list_files_in_folder(base_url, access_token, folder_id):
  
 url = f"{base_url}/rest/folders/{folder_id}/files"
 headers = {
 'Authorization': f'Bearer {access_token}',
 'X-Accellion-Version': '28',
 'Content-Type': 'application/json'
 }
 # Optional query parameters
 params = {
 # 'name': 'exampleFileName', # Uncomment and set the file name to filter by name
 # 'userId': 'exampleUserId', # Uncomment and set the user ID to filter by creator
 # 'limit': 10, # Uncomment and set the limit of files to retrieve
 # 'offset': 0, # Uncomment and set the offset for pagination
 # 'orderBy': 'name:asc', # Uncomment and set the order by criteria
 # 'returnEntity': 'false' # Uncomment and set to 'true' if you want to return the entity
 }
 
 response = requests.get(url, headers=headers, params=params)
 if response.status_code == 200:
 return response.json().get('data', [])
 else:
 return response.status_code, response.text

def main():
 base_url = input("Enter Base URL for Kiteworks Instance: ")
 client = KWOAuthClient(base_url)
 access_token = client.get_access_token()
 
 parent_folder_id = input("Enter parent folder ID: ")
 files = list_files_in_folder(base_url, access_token, parent_folder_id)
 print(files)

if __name__ == "__main__":
 main()
```

--------------------------------

### Initiate File Upload for Email

Source: https://developer.kiteworks.com/api-guides/manage-mail.htm

This endpoint initiates the process of uploading a file to be attached to an email. You need to provide the filename, total size, and total number of chunks for the file. The response includes an upload ID which is crucial for subsequent chunk uploads.

```APIDOC
## POST /rest/mail/{mail_id}/actions/initiateUpload

### Description
Initiates the upload process for a file to be attached to an email.

### Method
POST

### Endpoint
https://{base_url}/rest/mail/{mail_id}/actions/initiateUpload

### Parameters
#### Path Parameters
- **mail_id** (string) - Required - The ID of the email to which the file will be attached.

#### Request Body
- **filename** (string) - Required - The name of the file to be uploaded.
- **totalSize** (integer) - Required - The total size of the file in bytes.
- **totalChunks** (integer) - Required - The total number of chunks the file will be divided into for uploading.

### Request Example
```json
{
  "filename": "MyNewFile.txt",
  "totalSize": 2048,
  "totalChunks": 2
}
```

### Response
#### Success Response (201 Created)
- **uri** (string) - The upload URI, which includes the upload ID to be used in subsequent chunk upload requests.
```

--------------------------------

### Upload a File to Kiteworks using Python

Source: https://developer.kiteworks.com/api-guides/manage-files.htm

Use this script to upload a file to a specified location in Kiteworks. It handles retrieving the folder ID, initiating the multi-chunk upload, and uploading the file chunks. Ensure you have the KWOAuthClient for authentication.

```python
import os
import requests
import json
from urllib.parse import quote
from get_access_token import KWOAuthClient

"""
Upload a file to a specified location in Kiteworks.  

User Inputs:
 1. path_to_file: Local file path of the file you want to upload  
 2. path_to_upload_folder: Path to the folder on Kiteworks that the file is uploaded to  
 3. new_file_name: Name of the attachment you want that file to be called.  
"""

def upload_file(base_url, access_token, path_to_file, path_to_upload_folder, new_file_name):

 headers = {
 "x-accellion-version": "28",
 "Authorization": f"Bearer {access_token}",
 "Content-Type": 'application/json'
 }

 # Step 1: Get folder id
 path_to_upload_folder = quote(path_to_upload_folder)
 search_folder_url = f"{base_url}/rest/search?path={path_to_upload_folder}"

 search_response = requests.get(search_folder_url, headers=headers)
 search_response_data = search_response.json()

 folder_id = ""
 if search_response_data and search_response_data["folders"]:
 folder_id = search_response_data["folders"][0]["id"]
 else:
 print("Incorrect path specified. Folder does not exist.")

 # Step 2: Initiate the file upload
 file_size = os.path.getsize(path_to_file)

 initiate_upload_url = f"{base_url}/rest/folders/{folder_id}/actions/initiateUpload"
 initiate_upload_payload = {
 "totalChunks": 1,
 "totalSize": file_size,
 "filename": new_file_name
 }

 del headers["Content-Type"]
 initiate_upload_response = requests.post(initiate_upload_url, headers=headers, json=initiate_upload_payload)
 initiate_upload_data = initiate_upload_response.json()
 upload_id = initiate_upload_data["id"]

 # Step 3: Upload the file chunk
 upload_url = f"{base_url}/rest/uploads/{upload_id}?returnEntity=True"

 compression_mode = "NORMAL" # Available options: "NORMAL", "GZIP", "ZLIB"
 compression_size = file_size # Assuming no compression, set to original file size
 original_size = file_size

 payload = {
 "compressionMode": (None, compression_mode),
 "compressionSize": (None, str(compression_size)),
 "originalSize": (None, str(original_size)),
 "content": (new_file_name, open(path_to_file, "rb"))
 # "index": (None, "1"), # Optional: Chunk index, starts from 1
 # "lastChunk": (None, "1") # Optional: Indicate if this is the last chunk
 }

 upload_response = requests.post(upload_url, headers=headers, files=payload)

 if upload_response.status_code == 201:
 uploaded_file_data = upload_response.json()
 print("File uploaded successfully.")
 print("Uploaded file details:")
 print(json.dumps(uploaded_file_data, indent=2))
 else:
 print(f"File upload failed with status code: {upload_response.status_code}")
 print(upload_response.text)

def main():
 base_url = input("Enter Base URL for Kiteworks Instance: ")
 client = KWOAuthClient(base_url)
 access_token = client.get_access_token()

 path_to_file = input("Enter path to local file: ")
 path_to_upload_folder = input("Enter path to KW folder for file to be uploaded to: ")
 new_file_name = input("Enter the file's new name on KW: ")

 upload_file(base_url, access_token, path_to_file, path_to_upload_folder, new_file_name)

if __name__ == "__main__":
 main()

```

--------------------------------

### List Child Folders (cURL)

Source: https://developer.kiteworks.com/api-guides/manage-folders.htm

This cURL command retrieves a list of child folders for a specified parent folder. Replace the placeholder with the parent folder's UUID and your Kiteworks instance URL and access token.

```bash
curl -X GET "$KW_INSTANCE_URL/rest/folders/b111c222-d333-e444-f555-a666777888bbb/folders" \
  -H "X-Accellion-Version: 28" \
  -H "Authorization: Bearer $KW_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

--------------------------------

### Initiate Multi-Chunk Upload Response

Source: https://developer.kiteworks.com/api-guides/manage-files.htm

A successful initiation of a multi-chunk upload returns a 201 Created status and this JSON payload, which includes the upload ID required for subsequent chunk uploads.

```json
{
    "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"
}
```

--------------------------------

### Create Email

Source: https://developer.kiteworks.com/api-guides/manage-mail.htm

This endpoint allows you to create an email. You can specify recipients, subject, body, and whether to save it as a draft or send it immediately. A successful request returns a 201 Created status code, and optionally the newly created email object if `returnEntity` is set to true.

```APIDOC
## POST /rest/mail/actions/sendFile

### Description
Creates an email, with options to save as draft or send immediately.

### Method
POST

### Endpoint
https://{base_url}/rest/mail/actions/sendFile

### Parameters
#### Query Parameters
- **returnEntity** (boolean) - Optional - If set to true, the newly created email object is returned in the response body.

#### Request Body
- **subject** (string) - Required - The subject of the email.
- **body** (string) - Required - The main content of the email.
- **to** (array of strings) - Required - A list of recipient email addresses.
- **cc** (array of strings) - Optional - A list of CC recipient email addresses.
- **bcc** (array of strings) - Optional - A list of BCC recipient email addresses.
- **draft** (boolean) - Required - If true, the email is saved as a draft; otherwise, it is sent immediately.
- **secureBody** (boolean) - Optional - Indicates if the email body is secured. Defaults to false.

### Request Example
```json
{
    "subject": "Test mail subject",
    "body": "Test mail body",
    "to": [
        "recipient1@example.com",
        "recipient2@example.com"
    ],
    "cc": [],
    "bcc": [],
    "draft": "true",
    "secureBody": "false"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The UUID of the created email.
- Other fields related to the email object if `returnEntity` is true.

#### Response Example
```json
{
    "hasTrackingAccess": true,
    "policyDirective": 0,
    "dlpStatus": null,
    "status": "draft",
    "date": "2026-02-04T14:15:04+0000",
    "modifiedDate": "2026-02-04T14:15:04+0000",
    "withdrawnDate": null,
    "type": "original",
    "senderId": "a111b222-c333-d444-e555-f666777888aaa",
    "emailReturnReceipt": [
        {
            "user": {
                "profileIcon": "a111b222-c333-d444-e555-f666777888aaa",
                "name": "John Doe",
                "id": "a111b222-c333-d444-e555-f666777888aaa",
                "email": "user@example.com"
            }
        }
    ],
    "emailPackageId": "a1b2c3d4-e5f6-1a2b-3c4d-5e6f7a8b9c0d",
    "avStatus": null,
    "isUserSent": true,
    "error": null,
    "bucket": "draft",
    "attachmentCount": 0,
    "webFormId": null,
    "rawBody": "Test email body",
    "secureBody": true,
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "trackingAccess": [],
    "emailFrom": "user@example.com",
    "isRead": false,
    "isPreview": false,
    "watermark": null,
    "expirationDate": "2026-03-06T23:59:59+0000",
    "recipients": [
        {
            "type": 0,
            "email": "recipient1@example.com",
            "userId": "f9e8d7c6-b5a4-3f2e-1d0c-9b8a7f6e5d4c",
            "isDistributionList": false
        },
        {
            "type": 0,
            "email": "recipient2@example.com",
            "userId": "e8d7c6b5-a4f3-2e1d-0c9b-8a7f6e5d4c3b",
            "isDistributionList": false
        }
    ],
    "deleted": false,
    "templateId": 73,
    "body": "<p style=\"margin: 0px;\">Test email body</p>",
    "sharedMailboxId": null,
    "subject": "Test email subject",
    "parentEmailId": null
}
```
```