Kiteworks API Concepts

Core behaviors that apply uniformly across every Kiteworks API endpoint — how to page through large result sets, sort responses, stay within rate limits, and interpret HTTP status codes and error bodies.

Pagination

All list endpoints — folders, files, users, and other top-level resources — share a consistent pagination interface. Two query parameters control which slice of results is returned:

Example — paging through files

The pattern below retrieves records in pages of 50, advancing the offset by limit on each request until fewer results than the limit are returned.

# Page 1 — first 50 records
curl -s "https://demo.kiteworks.com/rest/files?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Page 2 — next 50 records
curl -s "https://demo.kiteworks.com/rest/files?limit=50&offset=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

def get_all_files(base_url: str, headers: dict, page_size: int = 50) -> list:
    """Fetch all files by paging through the API."""
    results = []
    offset = 0

    while True:
        resp = requests.get(
            f"{base_url}/rest/files",
            headers=headers,
            params={"limit": page_size, "offset": offset},
        )
        resp.raise_for_status()
        page = resp.json().get("data", [])
        results.extend(page)

        # Stop when the page is smaller than the requested limit
        if len(page) < page_size:
            break

        offset += page_size

    return results

Sorting

List endpoints accept an orderBy query parameter that controls the order in which results are returned. Sorting is performed server-side, so you receive results in the requested order without any additional client-side processing.

Syntax

The value of orderBy is a field name and direction joined by a colon:

orderBy={fieldName}:{direction}

# direction must be one of:
#   asc   — ascending order  (A → Z, oldest → newest)
#   desc  — descending order (Z → A, newest → oldest)

# The colon must be URL-encoded as %3A in query strings:
?orderBy=name%3Aasc

Example

The following request retrieves top-level folders sorted alphabetically by name:

curl -s "https://demo.kiteworks.com/rest/folders/top?orderBy=name%3Aasc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rate Limiting

Rate limits apply to every Kiteworks API endpoint and are enforced per IP address within a rolling time window. When a limit is exceeded the API returns 429 Too Many Requests.

The elevated MFT limit accommodates the high-volume, automated transfer patterns typical of managed file transfer operations.

Staying within limits

Two practices will keep most integrations well inside the thresholds:

• Cache access tokens. Fetch a token once and reuse it until it expires — don't request a new token on every API call. See Authorization Code — Python sample for an example caching implementation.
• Apply exponential backoff on 429 responses. Wait before retrying — start at 1 second, doubling on each subsequent attempt, to avoid hammering the endpoint while limits are in effect.

HTTP Status Codes

The Kiteworks API uses standard HTTP response codes. Codes fall into three categories:

Status code reference

Error Response Body

All error responses include a JSON body with a consistent structure. Use the code field for programmatic error handling and message for logging or user-facing messaging.

Example error responses

{
  "code": "INVALID_PARAMETER",
  "field": "email",
  "message": "The value provided for 'email' is not a valid email address."
}

{
  "code": "invalid_token",
  "message": "The access token has expired. Request a new token and retry."
}

{
  "code": "insufficient_scope",
  "message": "The token does not have the required scope to perform this action."
}

Frequently Asked Questions

What is the default page size for Kiteworks API responses?

When no limit parameter is specified, the Kiteworks API returns up to 25 items per page. You can increase this up to the maximum allowed by passing a limit query parameter. To retrieve all results, increment the offset parameter by your page size until the returned count is less than your requested limit.

Which fields can I sort on in the Kiteworks API?

Sortable fields vary by resource type. Common sort fields include name, created, modified, and size. Use the orderBy=field:direction format, where direction is asc or desc — for example, orderBy=name%3Adesc.

What happens when I exceed the Kiteworks API rate limit?

The API returns HTTP 429 Too Many Requests when your application exceeds the configured rate limit. The response includes a Retry-After header indicating how many seconds to wait before retrying. Implement exponential backoff in your client to handle this gracefully. See Staying within limits for a recommended retry strategy.

What is the difference between a 401 and 403 response from the Kiteworks API?

HTTP 401 Unauthorized means your access token is missing, malformed, or expired — you need to re-authenticate. HTTP 403 Forbidden means your token is valid but the authenticated user or application does not have permission to perform the requested operation on the specified resource.

Next Steps

With pagination, sorting, and error handling understood, you're ready to start building:

• Quick Start → Make your first authenticated API call
• API Reference → Browse all available endpoints
• API Playground → Try pagination and sorting live in your browser