Skip to Content
Python SDKDrives and folders

Organize drives and folders

A workspace contains drives, and a drive contains files and folders. Your API key selects the workspace. A read/write key can create or change resources within its permitted scope, subject to the workspace’s limits.

Create and select a drive

This creates a drive in the key’s workspace and prints its ID:

from uuid import uuid4
from flashdrive import Flashdrive
 
with Flashdrive() as client:
    drive = client.drives.create("Team handbook", idempotency_key=str(uuid4()))
    print("Drive ID:", drive.id)
    print("Status:", drive.status)

Set FLASHDRIVE_DRIVE_ID to that ID for the other examples. Creating a drive does not change the workspace’s default drive. It can initially report provisioning; use client.drives.get(drive.id) to check its status.

Use client.drives.list() to find existing drives. Pass drive_id= to the client constructor or an individual file, folder, upload, or search method to select one explicitly.

Create a folder

This makes a top-level folder and a child folder:

import os
from flashdrive import Flashdrive
 
with Flashdrive(drive_id=os.environ["FLASHDRIVE_DRIVE_ID"]) as client:
    handbook = client.folders.create("Handbook")
    policies = client.folders.create("Policies", parent_folder_id=handbook.id)
    print("Policies folder:", policies.id)
    for folder in client.folders.list(parent_folder_id=handbook.id):
        print(folder.id, folder.name)

folders.list() without a parent returns the drive’s top-level folders. It does not recursively list the whole tree. To upload directly into a folder, pass its ID as folder_id= to client.upload().

For a repeatable setup task, folders.ensure() creates missing paths and returns their IDs:

import os
from flashdrive import Flashdrive
 
with Flashdrive(drive_id=os.environ["FLASHDRIVE_DRIVE_ID"]) as client:
    paths = client.folders.ensure(["Handbook/Policies", "Handbook/Onboarding"])
    for folder in paths:
        print(folder.path, folder.id)

Folders organize content; they do not create separate permissions inside a drive. See workspace access before storing shared or individual information.

Rename or move a folder

This renames a selected folder and moves it to the drive’s top level:

import os
from flashdrive import Flashdrive
 
folder_id = input("Folder ID: ").strip()
with Flashdrive(drive_id=os.environ["FLASHDRIVE_DRIVE_ID"]) as client:
    renamed = client.folders.rename(folder_id, "Reference")
    moved = client.folders.move(renamed.id, None)
    print(moved.id, moved.name, moved.parent_folder_id)

To move it inside another folder, replace None with that folder’s ID. The SDK reads the folder’s current version before changing it. If a concurrent change causes a conflict, inspect the current folder before retrying.

Move a file into a folder

Moving a file requires the revision you observed, just like replacing its content:

import os
from uuid import uuid4
from flashdrive import Flashdrive
 
document_id = input("Document ID: ").strip()
folder_id = input("Destination folder ID: ").strip()
with Flashdrive(drive_id=os.environ["FLASHDRIVE_DRIVE_ID"]) as client:
    observed = client.documents.get(document_id)
    receipt = client.documents.move(
        document_id,
        folder_id,
        expected_revision=observed.latest_revision,
        idempotency_key=str(uuid4()),
    )
    print("Processing operation:", receipt.operation_id)

Use None as the destination to move a file to the drive’s top level. The document keeps its identity. See revision-safe updates for handling a file that changed after your read.

QuickstartUpload files