Dropbox API

Dropbox API Integration

Integrates with the Dropbox API v2 to manage files and folders, sharing settings and links, Paper documents, Dropbox Sign signature requests, file requests, backups, and team administration using the official dropbox Python SDK.

TL;DR for Code Generation

• Use dropbox.Dropbox(oauth2_access_token) with a short-lived access token + refresh flow; or dropbox.Dropbox(app_key, app_secret, oauth2_refresh_token) for long-running server apps
• The SDK uses a functional API pattern: dbx.files_upload(), dbx.files_list_folder(), dbx.sharing_create_shared_link_with_settings()
• All list operations use cursors for pagination: dbx.files_list_folder_continue(cursor)
• Use files_upload_session_* for files larger than 150 MB
• Paths are case-sensitive and must start with / (root) — Dropbox uses lowercase paths by convention
• Handle dropbox.exceptions.ApiError with .error and .user_message_text for structured errors

When to Use

Use this skill when:

• Uploading, downloading, moving, copying, or restoring files and folders
• Creating and managing shared links with permissions and expiration
• Managing folder and file sharing with specific users and groups
• Reading and creating Dropbox Paper documents
• Sending signature requests via Dropbox Sign (formerly HelloSign)
• Creating file requests for receiving files from external users
• Monitoring file changes via webhooks and listing file revisions
• Backing up application data to Dropbox

When NOT to Use

• Real-time collaborative editing (use Dropbox Paper or Office Online integration)
• High-resolution image/video streaming (use Dropbox's native media players or a CDN)
• Anonymous public access (shared links require authentication-free toggle, but API always authenticates)
• Replacing a full CMS for web content delivery (Dropbox is a file sync platform, not a web server)

Core Workflow

1. Create a Dropbox App — Go to https://www.dropbox.com/developers/apps and create an app with "Full Dropbox" or "App Folder" access type. Choose "Scoped Access" for granular permissions. Checkpoint: Copy the App key and App secret from the app console.

2. Generate an Access Token — For testing, generate a short-lived token from the app console. For production, implement OAuth 2.0 PKCE flow or use a refresh token. Checkpoint: Verify the token with dbx.users_get_current_account().

3. Initialize the Client — dbx = dropbox.Dropbox(oauth2_refresh_token=refresh_token, app_key=key, app_secret=secret) for server apps, or dbx = dropbox.Dropbox(access_token) for short-lived tokens. Checkpoint: Call dbx.users_get_current_account() and print the name.display_name.

4. Choose an Operation — File operations: dbx.files_upload(), dbx.files_download(), dbx.files_list_folder(), dbx.files_move_v2(). Sharing: dbx.sharing_create_shared_link_with_settings(). Checkpoint: Verify the operation returns the expected result type (e.g., FileMetadata).

5. Paginate Folder Listings — Use dbx.files_list_folder(path, recursive=False) to get the first page and a cursor. Call dbx.files_list_folder_continue(cursor) in a loop until cursor is None. Checkpoint: Verify result.has_more before continuing.

6. Handle Errors — Wrap in try/except dropbox.exceptions.ApiError. Access e.error for the structured error object and e.user_message_text for human-readable details. Checkpoint: Log e.error.get_path().tag for path-related errors to identify the root cause.

Implementation Patterns

Pattern 1: Upload a File

import os
import dropbox
from dropbox import files, exceptions

dbx = dropbox.Dropbox(
    app_key=os.environ["DROPBOX_APP_KEY"],
    app_secret=os.environ["DROPBOX_APP_SECRET"],
    oauth2_refresh_token=os.environ["DROPBOX_REFRESH_TOKEN"],
)

def upload_file(local_path: str, dropbox_path: str) -> files.FileMetadata:
    """Upload a file to Dropbox with autorename on conflict."""
    try:
        with open(local_path, "rb") as f:
            content = f.read()
        metadata = dbx.files_upload(
            content,
            dropbox_path,
            mode=files.WriteMode("add"),
            autorename=True,
            mute=True,  # don't notify users
        )
        return metadata
    except exceptions.ApiError as e:
        if e.error.is_path():
            print(f"Path error: {e.error.get_path().tag}")
        raise

result = upload_file("/tmp/backup.sql", "/backups/daily/2026-05-23.sql")
print(f"Uploaded rev {result.rev} at {result.size} bytes")

Pattern 2: List and Download Files

def download_latest_backup(backup_folder: str, local_dir: str) -> str | None:
    """Download the most recent file from a Dropbox folder."""
    try:
        result = dbx.files_list_folder(backup_folder)
        entries = sorted(result.entries, key=lambda e: e.server_modified, reverse=True)
        if not entries:
            print("No files found.")
            return None

        latest = entries[0]
        metadata, response = dbx.files_download(latest.path_lower)
        local_path = os.path.join(local_dir, latest.name)
        with open(local_path, "wb") as f:
            f.write(response.content)
        print(f"Downloaded {latest.name} ({latest.size} bytes)")
        return local_path
    except exceptions.ApiError as e:
        print(f"Download error: {e.user_message_text}")
        return None

download_latest_backup("/backups/daily", "/tmp/restore")

Pattern 3: Create a Shared Link

from dropbox import sharing

def create_shared_link(path: str, expires: str | None = None) -> str:
    """Create a shared link for a Dropbox file or folder."""
    try:
        settings = sharing.LinkSettings(
            require_password=False,
            expires=expires,
            link_access_level=sharing.RequestedLinkAccessLevel("viewer"),
        )
        result = dbx.sharing_create_shared_link_with_settings(
            path=path,
            settings=settings,
        )
        return result.url
    except exceptions.ApiError as e:
        if e.error.is_shared_link_already_exists():
            # Link already exists — list existing links
            links = dbx.sharing_list_shared_links(path=path)
            if links.links:
                return links.links[0].url
        raise

url = create_shared_link("/reports/q1-2026.pdf", expires="2026-12-31T23:59:59Z")
print(f"Shared link: {url}")

Pattern 4: Search Files

def search_files(query: str, max_results: int = 20) -> list[dict]:
    """Search for files in Dropbox by name."""
    try:
        result = dbx.files_search_v2(
            query=query,
            options=files.SearchOptions(max_results=max_results, order_by="relevance"),
        )
        matches = []
        for match in result.matches:
            metadata = match.metadata.get_metadata()
            matches.append({
                "name": metadata.name,
                "path": metadata.path_lower,
                "type": "folder" if isinstance(metadata, files.FolderMetadata) else "file",
            })
        return matches
    except exceptions.ApiError as e:
        print(f"Search error: {e.user_message_text}")
        return []

results = search_files("quarterly report")
for r in results:
    print(f"[{r['type']}] {r['path']}")

Pattern 5: BAD vs GOOD — Error Handling

# ❌ BAD — catches generic Exception, loses structured error info
try:
    dbx.files_upload(data, "/target/file.txt")
except Exception as e:
    print(f"Upload failed: {e}")

# ✅ GOOD — typed ApiError with path-level diagnostics
def safe_upload(dbx_client, content: bytes, path: str) -> files.FileMetadata | None:
    """Upload with typed error recovery."""
    try:
        return dbx_client.files_upload(
            content, path,
            mode=files.WriteMode("add"),
        )
    except exceptions.ApiError as e:
        if e.error.is_path():
            path_err = e.error.get_path()
            print(f"Path error: {path_err.tag} ({path_err.get_value()})")
        elif e.error.is_rate_limit():
            retry_after = e.error.get_rate_limit().retry_after
            print(f"Rate limited — retry after {retry_after} seconds")
        else:
            print(f"Dropbox error: {e.user_message_text}")
        return None

Constraints

MUST DO

• Use refresh tokens for server-side apps — short-lived tokens expire after 4 hours
• Always handle WriteMode explicitly — use "add" with autorename=True to avoid overwrites
• Paginate folder listings with files_list_folder_continue() — never assume single page
• Use upload sessions for files larger than 150 MB
• Check has_more flag before continuing pagination loops
• Use path_lower consistently — Dropbox paths are case-insensitive but API returns lowercase

MUST NOT DO

• Hardcode access tokens in source code — use env vars or a secrets manager
• Assume all entries in files_list_folder are files — check .is_file() or .is_folder()
• Poll for file changes — use webhooks with files_list_folder_longpoll() instead
• Upload without checking available quota (dbx.users_get_space_usage())
• Use root / path for app-folder-scoped apps (they only have access to the app folder)

Output Template

Every integration function should expose:

1. Client Initialization — Dropbox(app_key, app_secret, oauth2_refresh_token) from env
2. Resource Path — Dropbox path starting with / (or /Apps/AppName for App Folder apps)
3. Operation — Upload, download, share, search, or list with typed params
4. Pagination — files_list_folder → files_list_folder_continue loop
5. Error Handling — try/except ApiError with .error structure parsing

Related Skills

| Skill | Purpose | |