Folders

Organize uploaded files into folders.

client.folders  # FoldersResource

Methods overview

Method	HTTP	Scope
list	GET /folders	folders.lists
create	POST /folders	folders.create
rename	PATCH /folders/{id}	folders.update
delete	DELETE /folders/{id}	folders.delete

---

list

def list(
    *,
    q: str | None = None,
    as_json: bool | None = None,
) -> Paginated[Folder] | dict

Returns a Paginated envelope of Folder. q filters by folder name.

page = client.folders.list()
for folder in page.records:
    print(folder.id, folder.name)

---

create

def create(
    body: FolderCreateRequest | BaseModel | dict,
    *,
    as_json: bool | None = None,
) -> Folder | dict

Returns Folder — the newly created folder.

folder = client.folders.create({"name": "Q3 Assets"})
print(folder.id)

---

rename

def rename(
    folder_id: str,
    body: FolderRenameRequest | BaseModel | dict,
    *,
    as_json: bool | None = None,
) -> Folder | dict

Returns Folder — the renamed folder.

client.folders.rename("fld_1", {"name": "Q3 Assets (Archived)"})

---

delete

def delete(
    folder_id: str,
    *,
    as_json: bool | None = None,
) -> DeleteFolderResponse | dict

Returns DeleteFolderResponse — has a boolean success field.

Files inside the folder are not deleted. They lose their folder association and become uncategorized.

client.folders.delete("fld_1")

Recipes

Create a folder and upload directly into it

folder = client.folders.create({"name": "Brand Assets 2026"})

client.files.upload(
    ["logo.png", "brand-guide.pdf"],
    folder_id=folder.id,
)

Find or create

page = client.folders.list(q="Brand Assets 2026")
if page.records:
    folder = page.records[0]
else:
    folder = client.folders.create({"name": "Brand Assets 2026"})