Egnyte Python client

An unofficial typed Python client and command-line interface for the Egnyte Public API. No affiliation with Egnyte is implied or intended.

The package wraps Egnyte's REST APIs in a fully type-hinted client built on Pydantic, plus an egnyte-client CLI for quick access from the terminal. Responses are validated into predictable Python objects, so you can work with files, folders, search, links, users, and groups without hand-rolling requests.

Features

• Typed models. Every response is parsed into Pydantic models with descriptive fields, and Egnyte's timestamps become datetimes.
• Python client and CLI. Use it as a library or from the shell via egnyte-client.
• Sync and async. EgnyteClient and AsyncEgnyteClient expose the same methods over httpx.
• Sensible defaults. Paths are encoded for you, calls refused by the rate limit are retried after Retry-After, and an expired token is refreshed when refresh credentials are configured.
• The core platform. Files and folders (including chunked upload, locks, and trash), search, links, permissions, comments, bookmarks, metadata, events, webhooks, users, groups, and audit reporting.
• Egnyte AI. Document questions and summaries, the AI Assistant, agents, and hybrid keyword and semantic search.
• Typed errors. Egnyte's error bodies come in several shapes. Each is raised as an EgnyteError with a status, message, and code. EgnyteNotFoundError, EgnyteAuthError, and EgnyteRateLimitError are its subclasses.

Installation

The package is published on PyPI as egnyte-client and imported as egnyte_client:

pip install egnyte-client
# or, with uv:
uv add egnyte-client

Requires Python 3.12+.

Configuration

Settings are read from environment variables, or can be passed directly to EgnyteClient:

export EGNYTE_DOMAIN="acme"
export EGNYTE_ACCESS_TOKEN="your-access-token"

Getting a token

Register an application at developers.egnyte.com to get an API key and secret. Then complete one of the OAuth 2.0 flows in Egnyte's authentication docs against https://<domain>.egnyte.com/puboauth/token. Use the authorization code flow for public apps, or the resource-owner password flow for internal apps. Access tokens last 30 days.

The client can run the flow for you:

from egnyte_client import EgnyteClient, build_authorization_url

url = build_authorization_url(
    "acme",
    client_id,
    "https://app.example.com/callback",
    scope=["Egnyte.filesystem"],
    state=state,
)
# ... send the user to `url`, then take `code` from the redirect:
client = EgnyteClient("acme", client_id=client_id, client_secret=client_secret)
token = client.exchange_authorization_code(code, "https://app.example.com/callback")

# Internal API keys can use the password grant instead:
token = client.login_with_password(username, password)

get_token_info() reports a token's user, domain, and scopes, and revoke_token() revokes it.

When refresh_token, client_id, and client_secret are all set, a call that fails with 401 refreshes the token once and is retried. Egnyte rotates the refresh token on every refresh, so the old refresh token stops working: pass on_token_refresh to save each new pair where the next run will find it. For example, with the pair kept in a JSON file:

from pathlib import Path

from egnyte_client import EgnyteClient, OAuthToken

TOKEN_FILE = Path("egnyte-token.json")  # keep it out of version control


def save_token(token: OAuthToken) -> None:
    TOKEN_FILE.write_text(token.model_dump_json())


# The first pair comes from exchange_authorization_code() or
# login_with_password() above; save it with save_token(token).
token = OAuthToken.model_validate_json(TOKEN_FILE.read_text())

client = EgnyteClient(
    "acme",
    access_token=token.access_token,
    refresh_token=token.refresh_token,
    client_id="...",
    client_secret="...",
    on_token_refresh=save_token,  # called with each new OAuthToken
)

Rate limits, timeouts and retries

Egnyte allows 2 calls per second per token, and between 1,000 and 4,000 calls per day depending on the plan. A call refused by the per-second limit (HTTP 429, a spike-arrest violation) is retried after its Retry-After (1 second if absent), up to rate_limit_retries times (default 5). The gateway refuses such a call before it reaches Egnyte, so retrying a write is safe. The daily quota is never retried: it raises EgnyteQuotaExceededError at once, since waiting seconds will not help and the quota resets at 00:00 UTC. Any other 429 is retried only when it asks for a wait of 5 seconds or less, so a long Retry-After never blocks the caller.

Every request carries a timeout (default (5, 30) seconds for connect and read). Pass timeout= to override it (a single float, a (connect, read) tuple, or None to disable). Pass retries= to retry connection-establishment failures:

client = EgnyteClient(timeout=60, retries=3, rate_limit_retries=10)

The CLI reads EGNYTE_API_TIMEOUT (seconds), EGNYTE_API_RETRIES (count), and EGNYTE_API_HEADERS (a JSON object of extra headers) for the same behaviour.

The AI endpoints have tighter limits of their own, on top of these: 100 calls a day, 10 a minute, and 2 a second per token.

Quick start

Python

from egnyte_client import EgnyteClient, EgnyteNotFoundError

with EgnyteClient() as client:
    me = client.get_user_info()

    # Folders and files
    client.create_folder("/Shared/Reports/2026")
    uploaded = client.upload_file("/Shared/Reports/2026/summary.pdf", pdf_bytes)
    folder = client.get_folder("/Shared/Reports/2026")
    for file in folder.files:
        print(file.name, file.size, file.last_modified)
    data = client.download_file("/Shared/Reports/2026/summary.pdf")
    client.move_item(
        "/Shared/Reports/2026/summary.pdf", "/Shared/Reports/2026/final.pdf"
    )

    # Search names, content, comments, and metadata
    page = client.search("quarterly revenue", folder="/Shared/Reports", type="FILE")
    for hit in page.results:
        print(hit.path, hit.score, hit.snippet)

    # Links
    link = client.create_link(
        "/Shared/Reports/2026/final.pdf", "file", accessibility="domain"
    )
    print(link.url)
    client.delete_link(link.id)

    # Groups
    group = client.create_group("Reporting", [me.id])
    client.update_group(group.id, add_member_ids=[42])
    client.delete_group(group.id)

    try:
        client.get_file("/Shared/missing.txt")
    except EgnyteNotFoundError:
        ...

Python (async)

AsyncEgnyteClient mirrors EgnyteClient method for method, with the same arguments and return types, awaited. Share one instance across tasks so they reuse its connection pool and tokens. Keep fan-out modest, because Egnyte allows two calls per second:

import asyncio

from egnyte_client import AsyncEgnyteClient


async def main() -> None:
    async with AsyncEgnyteClient() as client:
        folder = await client.get_folder("/Shared/Reports")
        contents = await asyncio.gather(
            *(client.download_file(file.path) for file in folder.files[:4])
        )


asyncio.run(main())

CLI

$ egnyte-client auth whoami
$ egnyte-client fs ls /Shared/Reports --count 20
$ egnyte-client fs upload ./summary.pdf /Shared/Reports/
$ egnyte-client fs download /Shared/Reports/summary.pdf -o -
$ egnyte-client search "quarterly revenue" --folder /Shared/Reports --type file --in content
$ egnyte-client links create /Shared/Reports/summary.pdf --type file --accessibility domain
$ egnyte-client groups create Reporting --member 8
$ egnyte-client trash list --count 20
$ egnyte-client perms set /Shared/Reports --group Finance=Viewer
$ egnyte-client metadata set project --folder-id FOLDER_ID --value status=active
$ egnyte-client audit create files 2026-11-01 2026-11-05 --folder /Shared
$ egnyte-client ai assistant-ask "Summarize the Q3 results" --folder-id FOLDER_ID --wait
$ egnyte-client --log users list --email jdoe@acme.com

Every client method has a command except the token grants (the CLI reads its token from the environment); the API reference below lists each one. egnyte-client <group> --help lists every option.

• Output. Results print as indented JSON, so they pipe into jq; downloads write raw bytes (-o - for stdout); a bare value, such as a lock token or a permission level, prints alone so a script can capture it.
• Confirmation. Commands that delete, purge, replace, or change permissions ask first, naming what will change; -y/--yes skips the prompt. Prompts go to stderr.
• Structured input. Options that take a structure, such as a namespace's keys or metadata values, take JSON (--keys '[...]'), checked before anything is sent.
• Secrets. The webhook --auth-header can come from EGNYTE_WEBHOOK_AUTH_HEADER instead, keeping it out of shell history, and is never printed back.
• Disabling commands. Set EGNYTE_CLI_DISABLE to a comma-separated list of dotted command paths (for example users.delete,groups,metadata.namespaces.delete) to hide and refuse those commands.

Usage

Pagination

List methods return one page, and the page size is capped by Egnyte. Each API family pages in its own style:

Every page is an API call, and Egnyte's daily quota is between 1,000 and 4,000 calls, so page deliberately.

Errors

Every error this package raises is an EgnyteError:

Egnyte words its errors in several body shapes depending on the API; each is read into the same message and code:

from egnyte_client import EgnyteForbiddenError, EgnyteNotFoundError

try:
    client.create_folder("/Shared/Reports")
except EgnyteForbiddenError:
    pass  # already exists
try:
    client.get_file("/Shared/missing.txt")
except EgnyteNotFoundError as error:
    print(error.message)

Arguments the client can check before sending (for example, two mutually exclusive filters) raise a plain ValueError without a request.

Logging

The package logs to the egnyte_client logger and configures nothing itself: it attaches only a NullHandler, so records appear only where your application's logging sends them. Each request is logged at DEBUG (GET /pubapi/v1/userinfo -> 200); rate-limit retries and token refreshes at INFO.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("egnyte_client").setLevel(logging.DEBUG)  # include each request

The CLI's --log flag prints the same records to stderr.

Uploads and downloads

upload_file() sends content in one request and suits files up to about 100 MB. For larger files, upload_file_chunked() takes bytes or an open binary file and streams it in chunks; the CLI's fs upload switches to it on its own. download_file() returns the content as bytes.

Background jobs

Audit reports are generated asynchronously:

job = client.create_file_audit_report(start, end, folders=["/Shared"])
status = client.get_audit_job(job.id)  # poll at most every 2 minutes
if status.is_complete:
    report = client.get_audit_report(status.report_type, status.report_id)
    client.delete_audit_report(status.report_type, status.report_id)

AI Assistant and agent questions are answered in the background too. wait_for_assistant() and wait_for_agent() poll until the answer is ready, every 10 seconds for up to 3 minutes by default. Each check counts against the AI limit of 100 calls a day, so the defaults use at most 19:

execution = client.ask_assistant("Summarize the Q3 results", folder_ids=[folder_id])
status = client.wait_for_assistant(execution.execution_id)
if status.status == "COMPLETED":
    print(status.response_text)

Design

Operations, transport, and two clients

Each API call is described once, in egnyte_client.operations, as an Operation: method, path, query, body, and the parser that turns the response into a model. Nothing there performs I/O. EgnyteClient and AsyncEgnyteClient only put operations on the wire, through a shared transport that holds configuration, token refresh, the rate-limit retry, and error mapping. The two clients therefore have the same methods, arguments, docstrings, and return types, which a test checks.

Live behaviour over the documentation

Where Egnyte's live API differs from its documentation, the models and methods follow the live API. For example, date values come back as epoch milliseconds, the by-ID chunked upload endpoint is unusable, and some status codes differ. Response models ignore fields they do not declare, so a new field from Egnyte never breaks parsing. Audit report rows and events also keep undeclared fields in model_extra, since their columns vary by report type.

Reference Documentation

This client follows (to the extent possible) the API documentation Egnyte provides at developers.egnyte.com.

API reference

Each section maps client methods to the Egnyte endpoints they call, and to the CLI command where there is one. AsyncEgnyteClient exposes every method as a coroutine of the same name.

Auth

Docs: Authentication

build_authorization_url() is a module function, as it makes no request. The token grants are library-only: the CLI reads its token from EGNYTE_ACCESS_TOKEN. Each grant adopts the new token pair and passes it to on_token_refresh.

File system

Docs: File System Management · Folder Options

upload_file() sends one request and suits files up to about 100 MB. upload_file_chunked() streams bytes or a binary file object in chunks of 10 MiB to 1 GiB (default 100 MiB), with the composite checksum Egnyte verifies. Egnyte refuses content under 10 MiB on the chunked endpoint, so use upload_file() for small files. Egnyte's documented by-ID chunked endpoint rejects every upload, so upload_file_chunked_by_id() looks up the file's path (one extra call) and uploads to it. For chunked uploads, Egnyte stores the composite checksum, not a plain SHA-512. Downloads are read into memory.

Search

Docs: Search

search matches file and folder names, file content, comments, and folder descriptions. It also takes:

• Filters: folder, type, and modified and uploaded date ranges.
• metadata_filters, a list of MetadataFilters, for custom metadata.
• similar_to_entry_ids and similar_to_text, for similarity search.

The query must be 3 to 250 characters. Results arrive 20 at a time at most, best match first. Page with offset while has_more is true:

from egnyte_client import MetadataFilter

offset = 0
while True:
    page = client.search(
        "invoice",
        metadata_filters=[
            MetadataFilter(namespace="finance", key="status", value="paid")
        ],
        offset=offset,
        count=20,
    )
    handle(page.results)
    if not page.has_more:
        break
    offset += page.count

Each page is one API call, so mind the daily quota when paging deep.

AI

Docs: AI · Agents

These calls need the Egnyte.ai scope on the API key and token, and agents must be enabled for the domain (otherwise a 403 with code AGENTS_FEATURE_NOT_ENABLED). Each call, including each status check, counts against the AI limits of 100 a day, 10 a minute, and 2 a second per token.

• Document questions (ask_document, summarize_document) answer in the response. They take a file version's entry_id.
• AI Assistant and agent questions are answered in the background. Ask, then poll the returned ID, or call a wait_for_* helper (see Background jobs). Pass the returned conversation_id with a follow-up question to continue the conversation, and earlier turns as chat_history, a list of ChatMessages.
• Hybrid search blends keyword and meaning (semantic_weight from 0.0, keywords only, to 1.0, meaning only) and returns each matching file with its scored passages.

Where the live API differs from Egnyte's AI documentation, the client follows the live API:

• A newly uploaded file answers document questions with a 400 (SMART_APP_SERVICE_ERROR, "Error getting the extracted content") until Egnyte has extracted its text, which took a few minutes in testing.
• Agent questions report IN_PROGRESS while running, not the documented PENDING or RUNNING; wait_for_agent() treats all three as running. A FAILED status carries no reason. Egnyte's built-in Deep Research agent answered FAILED to every question asked through the API in testing.
• Hybrid search returns each file's full path in filename, adds group_id and uploaded, and scores passages on an open scale rather than 0 to 1.

Copilot (/ai/copilot/ask, retired on 30 September 2026) and Knowledge Bases (/ai/kb/..., replaced by agents) are not wrapped.

Trash and insights

Docs: Trash · User Insights

Restore and purge take up to 10 item IDs and return one result per item, so a partial failure does not raise. Purging cannot be undone.

Permissions

Docs: Permissions

In set_folder_permissions(), mapping a user or group to None removes its permission. Egnyte rejects top-level paths such as /Shared (the path needs at least two segments).

Comments and bookmarks

Docs: Comments · Bookmarks

Metadata

Docs: Metadata

Date values go over the wire as epoch milliseconds; pass a date or datetime. Setting a value to None removes it. Pass force=True to the deletes to remove definitions that are in use. To search by metadata, use search(metadata_filters=...).

Events and webhooks

Docs: Events · Webhooks

list_events() returns a page whose latest_id is the cursor for the next call. Egnyte sends back the auth_header registered with a webhook as each delivery's Authorization header; check it with verify_webhook_authorization() from egnyte_client.operations.webhook, and parse delivery bodies with the WebhookDelivery model. Webhook calls need the Egnyte.webhooks scope.

Audit reporting

Docs: Audit Reporting v1 · Audit Reporting v2

Reports are generated asynchronously: create one, poll get_audit_job() (Egnyte asks for no more than once every 2 minutes) until is_complete, then read it with get_audit_report() (JSON) or download_audit_report() (CSV bytes). stream_audit_events() pages through the last 7 days of events with a cursor.

Links

Docs: Links

Users

Docs: User Management

Creating a user emails an invitation unless send_invite=False. For egnyte authentication, Egnyte always sends one.

Groups

Docs: Group Management

Egnyte requires at least one member to create a group, although its documentation marks members optional.

License

MIT