Quick Start — Your First Kiteworks API Call in Python

In this guide you'll authenticate against your Kiteworks instance and make your first API call — listing your top-level folders — using a single Python script. The whole thing takes about 10 minutes.

Before you start

Confirm the following before running any code:

What you'll build

A single Python script that authenticates against your Kiteworks instance using the Authorization Code flow and prints a list of your top-level folders — their names, IDs, and paths. Those folder IDs are the starting point for everything else in the API: listing files, uploading, creating subfolders, and more.

Step 1 — Authenticate

KWOAuthClient handles the full Authorization Code flow for you: it opens a browser window for the Kiteworks login page, captures the authorization code after you sign in, exchanges it for an access token, and caches the token locally so subsequent calls don't require re-authentication until the token expires.

Create a new file called quick_start.py and start with these three lines:

from get_access_token import KWOAuthClient

base_url = "https://your.kiteworks.domain"  # replace with your instance URL
client = KWOAuthClient(base_url)

When you run the script, KWOAuthClient will prompt you for your client_id and client_secret in the terminal, then open a browser window for you to sign in. After you authenticate, it captures the token automatically — you won't need to handle the redirect manually.

Step 2 — List your top-level folders

Now add the API call. GET /rest/folders/top returns all root folders accessible to the authenticated user. Add this to quick_start.py:

import requests

access_token = client.get_access_token()

response = requests.get(
    f"{base_url}/rest/folders/top",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Accellion-Version": "28",
        "Content-Type": "application/json",
    }
)
response.raise_for_status()
folders = response.json()

print(f"Found {len(folders)} top-level folder(s):\n")
for folder in folders:
    print(f"  {folder['name']}")
    print(f"    ID:   {folder['id']}")
    print(f"    Path: {folder['path']}")
    print()

The complete script

Here's everything together. Save this as quick_start.py in the same directory as get_access_token.py, then run it with python quick_start.py.

import requests
from get_access_token import KWOAuthClient

# ── Configuration ────────────────────────────────────────────────
# Replace with your Kiteworks instance URL.
# client_id and client_secret will be prompted at runtime.
BASE_URL = "https://your.kiteworks.domain"

# ── Step 1: Authenticate ─────────────────────────────────────────
# KWOAuthClient opens a browser for sign-in, captures the token,
# and caches it so subsequent calls skip re-authentication.
client = KWOAuthClient(BASE_URL)
access_token = client.get_access_token()

# ── Step 2: List top-level folders ───────────────────────────────
response = requests.get(
    f"{BASE_URL}/rest/folders/top",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Accellion-Version": "28",
        "Content-Type": "application/json",
    }
)
response.raise_for_status()
folders = response.json()

# ── Step 3: Print the results ────────────────────────────────────
print(f"Found {len(folders)} top-level folder(s):\n")
for folder in folders:
    print(f"  {folder['name']}")
    print(f"    ID:   {folder['id']}")
    print(f"    Path: {folder['path']}")
    print()

Step 3 — Read the result

A successful run prints output like this:

Found 3 top-level folder(s):

  My Folder
    ID:   b111c222-d333-e444-f555-a666777888bbb
    Path: My Folder

  Shared Projects
    ID:   c222d333-e444-f555-a666-b777888999ccc
    Path: Shared Projects

  Archive
    ID:   d333e444-f555-a666-b777-c888999000ddd
    Path: Archive

Each folder has three key fields:

Something went wrong?

For a full reference on API status codes and error responses, see API Concepts → HTTP Status Codes.

Frequently Asked Questions

How long does it take to make a first Kiteworks API call?

Most developers make their first successful API call within 10 minutes, assuming they have a licensed Kiteworks instance and a registered custom application. The main steps are: obtain an access token, then send a GET request to /rest/folders/top.

Does the Kiteworks API support languages other than Python?

Yes. The Kiteworks REST API is language-agnostic — any HTTP client can call it. This guide uses Python for its readability, but the same patterns apply to JavaScript, Java, Go, Ruby, and any other language with an HTTP library.

What does GET /rest/folders/top return?

GET /rest/folders/top returns a JSON array of the top-level folders your access token has permission to see. Each folder object includes an id, name, type, and permission metadata. Use the id from this response to navigate into child folders or list files.

How do I attach a Kiteworks access token to API requests?

Include the access token in the HTTP Authorization header as a Bearer token: Authorization: Bearer <access_token>. This header must be present on every API request except the token endpoint itself.

What's next

Now that you have folder IDs and a working authentication setup, here's where to go: