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

> How to update your Kiteworks API integration to use UUID strings instead of integer IDs for Files and Folders endpoints — required when upgrading to API v28 from v18 or earlier.

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](upgrade-check-version.html).

## 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 Copy

```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 Copy

```bash
# 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 Copy

```python
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 Copy

```python
# 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+)](upgrade-uuid-users.html) 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+)](upgrade-uuid-users.html). |
| `destinationFolderId` | `POST /rest/files/actions/copy`, `move` | Single UUID string |

request-body.json Copy

```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 Copy

```python
# 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) ↗](changelog.html?from=18&to=19&tags=files,folders,dli)

## Code Samples

### List files in a folder — before and after

list_files_v18.py Copy

```python
# 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 Copy

```python
# 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 Copy

```bash
# 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-uuid-mail.html) Upgrade mail and email IDs if you built your integration against v20 or earlier.
- [Update Users to UUID (v21 to v22+) →](upgrade-uuid-users.html) Upgrade user IDs, including `userId` and `userIds` on member endpoints, if you built against v21 or earlier.
- [Upgrade to API v28 →](upgrade-api-v28.html) Apply all remaining breaking changes to reach the current API version.