Upgrade Guides

Update Files & Folders to UUID (v18 to v19+)

When Kiteworks API moved from v18 to v19, all file and folder IDs changed from sequential integers to Universally Unique Identifier (UUID) strings. If you built your integration against v18 or earlier, update every place your code stores, constructs, or compares these IDs.

Who Is Affected

This guide applies only if you built your integration against API v18 or earlier. The ID format switch is controlled by the X-Accellion-Version header value — it is not tied to when your Kiteworks server was upgraded. Once you send X-Accellion-Version: 19 or higher (including v28), the API returns UUID strings for all file and folder IDs.

Not sure what version you're on? See Check Your API Version.

What Changed

In API v19, all ID fields for files, folders, Data Leak Investigator (DLI) files, DLI folders, and sources changed from sequential integers (e.g., 12345) to UUID strings (e.g., 550e8400-e29b-41d4-a716-446655440000). This affects:

Path parameters

IDs embedded in URL paths
Query parameters

IDs passed as filter values
Request body fields

IDs sent in JSON request bodies
Response body parsing

ID fields returned in JSON responses

id-format-comparison.json

// Old (v18 and earlier) — integer IDs
{ "id": 12345, "parentId": 6789, "creator": { "id": 42 } }

// New (v19 and later, including v28) — UUID strings
{ "id": "550e8400-e29b-41d4-a716-446655440000", "parentId": "6a2b3c4d-...", "creator": { "id": "7e8f9a0b-..." } }

Step 1 — Audit Your Code

Before making changes, find every place in your code that handles file or folder IDs:

audit.sh

# Find integer ID usage in URL construction
grep -rn "rest/files/[0-9]" ./src
grep -rn "rest/folders/[0-9]" ./src

# Find places where IDs might be stored as integers
grep -rn "file_id\s*=\s*[0-9]" ./src
grep -rn "folder_id\s*=\s*[0-9]" ./src
grep -rn "int(.*id\b" ./src

Python pattern to catch at runtime — add temporarily for detection:

assert_uuid.py

def assert_uuid(value, field_name):
    import re
    if not re.match(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', str(value), re.I):
        raise ValueError(f"Expected UUID for {field_name}, got: {value!r}")

Step 2 — Update Path Parameters

The following path parameters must now be UUID strings:

Parameter	Example Endpoint	Old Value	New Value
`{id}`	`GET /rest/files/{id}`	`12345`	`550e8400-e29b-41d4-a716-446655440000`
`{file_id}`	`GET /rest/files/{file_id}/members`	`12345`	`550e8400-...`
`{version_id}`	`GET /rest/files/{id}/versions/{version_id}`	`7`	`a1b2c3d4-...`
`{folder_id}`	`GET /rest/folders/{folder_id}/files`	`6789`	`6a2b3c4d-...`
`{parent}`	`POST /rest/folders/{parent}/files`	`6789`	`6a2b3c4d-...`
`{parent_id}`	`GET /rest/sources/{parent_id}/files`	`100`	`7e8f9a0b-...`

path-params.py

# Old — integer ID
url = f"{base_url}/rest/files/{file_id}/content"   # file_id = 12345

# New — UUID string
url = f"{base_url}/rest/files/{file_id}/content"   # file_id = "550e8400-e29b-41d4-a716-446655440000"

If you stored file or folder IDs in a database or cache, you must re-fetch them from the API using v28 to get the UUID values.

Step 3 — Update Query Parameters

The following query parameters must now accept UUID strings:

Parameter	How to Update
`id:in`	Re-fetch file/folder UUIDs via `GET /rest/files` or `GET /rest/folders`, then replace stored integers with the returned UUID strings before passing to this parameter.
`fileId`	Re-fetch the file UUID via `GET /rest/files/{id}`. Replace the stored integer with the returned UUID string.
`fileId:in`	Re-fetch file UUIDs via `GET /rest/files`, then replace stored integers with the returned UUID strings.
`folderId`	Re-fetch the folder UUID via `GET /rest/folders/{id}`. Replace the stored integer with the returned UUID string.
`folderId:in`	Re-fetch folder UUIDs via `GET /rest/folders`, then replace stored integers with the returned UUID strings.
`userId`	User ID query parameters on file and folder member endpoints became UUID strings in v22, not v19. See Update Users to UUID (v21 to v22+) when you proceed to v22.

Step 4 — Update Request Body Fields

The following request body fields must now contain UUID strings:

Field	Endpoint	Notes
`ids`	`DELETE /rest/files`, bulk operations	Array of UUID strings
`userIds`	`POST /rest/folders/{id}/members` and similar	User IDs in this field became UUID strings in v22, not v19. See Update Users to UUID (v21 to v22+).
`destinationFolderId`	`POST /rest/files/actions/copy`, `move`	Single UUID string

request-body.json

// Old — integer IDs in request body
{
  "ids": [12345, 67890],
  "destinationFolderId": 6789
}

// New v28 — UUID strings
{
  "ids": ["550e8400-e29b-41d4-a716-446655440000", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "destinationFolderId": "6a2b3c4d-e5f6-7890-abcd-ef1234567890"
}

Step 5 — Update Response Parsing

The following response body fields now return UUID strings instead of integers. Update any code that reads these values and stores or compares them as integers:

Field	Appears In
`id`	All file and folder objects
`creator.id`	File and folder metadata
`lastModifiedBy.id`	File and folder metadata
`lockUser.id`	Lock state metadata
`userId`	Member and permission objects
`objectId`	Activity and notification objects
`sharedBy.id`	Shared file/folder metadata
`parentId`	Folder hierarchy
`rootId`	Source folder reference
`originId`	Source integration reference
`members[].objectId`	Member list entries
`members[].userId`	Member list entries

response-parsing.py

# Old — storing ID as integer
folder_id = int(folder["id"])

# New v28 — keep as string
folder_id = folder["id"]   # "550e8400-e29b-41d4-a716-446655440000"

See All Affected Endpoints

This update affects 23 endpoints across Files, Folders, and DLI resources, with 41 individual field-level changes. Use the interactive API Changelog to see the full list — View Files & Folders changes (v18→v19) ↗

Code Samples

List files in a folder — before and after

list_files_v18.py

# Before — v18, integer IDs
import requests

folder_id = 6789   # integer
response = requests.get(
    f"{base_url}/rest/folders/{folder_id}/files",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Accellion-Version": "18",
    },
)
files = response.json()
for f in files["data"]:
    print(f["id"], f["name"])   # id is an integer

list_files_v28.py

# After — v28, UUID strings
import requests

folder_id = "6a2b3c4d-e5f6-7890-abcd-ef1234567890"   # UUID string
response = requests.get(
    f"{base_url}/rest/folders/{folder_id}/files",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Accellion-Version": "28",
    },
)
files = response.json()
for f in files["data"]:
    print(f["id"], f["name"])   # id is now a UUID string

Download a file — before and after

download-file.sh

# Before — integer file ID
curl -s -H "Authorization: Bearer $TOKEN" \
     -H "X-Accellion-Version: 18" \
     "https://your-instance.kiteworks.com/rest/files/12345/content" -o file.bin

# After — UUID file ID
curl -s -H "Authorization: Bearer $TOKEN" \
     -H "X-Accellion-Version: 28" \
     "https://your-instance.kiteworks.com/rest/files/550e8400-e29b-41d4-a716-446655440000/content" -o file.bin

Next Steps

After completing all five steps, test your integration against a v19+ (or v28) instance and verify that file and folder operations return UUID strings in all ID fields.

Update Mail & Email to UUID (v20 to v21+) → Upgrade mail and email IDs if you built your integration against v20 or earlier.
Update Users to UUID (v21 to v22+) → Upgrade user IDs, including userId and userIds on member endpoints, if you built against v21 or earlier.
Upgrade to API v28 → Apply all remaining breaking changes to reach the current API version.