CabinetsResource: Manage Files, Zips, and Uploads

The cabinets resource on the Figranium Python SDK is the typed client for the Cabinets API. Cabinets are durable, installation-wide download queues. Tasks can route intercepted downloads into a selected Cabinet, and later actions can upload the newest unuploaded item from that queue.

from figranium import Figranium
import os

client = Figranium(api_key=os.environ["FIGRANIUM_API_KEY"])

Supported operations

cabinets covers the Cabinet lifecycle and item-management API.

Cabinet lifecycle

List, create, rename, migrate, clear, and delete Cabinets.

Item management

List Cabinet items, update upload status, and remove one or many items.

Downloads

Build item download URLs for files stored in a Cabinet.

Methods

list

List all Cabinets.

HTTP endpoint: GET /api/cabinets
Signature: cabinets.list(*, options=None)

list_cabinets.py

result = client.cabinets.list()
for cabinet in result["cabinets"]:
    print(cabinet["id"], cabinet["name"])

create

Create a new Cabinet.

HTTP endpoint: POST /api/cabinets
Signature: cabinets.create(name, *, options=None)

create_cabinet.py

result = client.cabinets.create("downloads-q3")
print(result["cabinet"]["id"])

rename

Rename an existing Cabinet.

HTTP endpoint: POST /api/cabinets/{cabinetId}/rename
Signature: cabinets.rename(cabinet_id, name, *, options=None)

rename_cabinet.py

result = client.cabinets.rename("cab_01", "downloads-q4")
print(result["cabinet"]["name"])

delete

Delete a Cabinet. You can optionally migrate its items to another Cabinet first.

HTTP endpoint: DELETE /api/cabinets/{cabinetId}
Signature: cabinets.delete(cabinet_id, *, target_cabinet_id=None, migrate=False, options=None)

delete_cabinet.py

# Delete a cabinet outright
result = client.cabinets.delete("cab_01")

# Migrate items to another cabinet before deleting
result = client.cabinets.delete(
    "cab_01",
    target_cabinet_id="cab_02",
    migrate=True,
)

When migrate=True, items are moved to target_cabinet_id before the Cabinet is removed.

list_items

List the items inside a Cabinet.

HTTP endpoint: GET /api/cabinets/{cabinetId}/items
Signature: cabinets.list_items(cabinet_id, *, options=None)

list_items.py

result = client.cabinets.list_items("cab_01")
for item in result["items"]:
    print(item["id"], item["name"], item["status"])

clear

Remove every item from a Cabinet.

HTTP endpoint: POST /api/cabinets/{cabinetId}/clear
Signature: cabinets.clear(cabinet_id, *, options=None)

clear_cabinet.py

result = client.cabinets.clear("cab_01")
print(result["success"])

set_item_status

Update the status of one or more Cabinet items.

HTTP endpoint: POST /api/cabinets/{cabinetId}/items/status
Signature: cabinets.set_item_status(cabinet_id, item_ids, status, *, options=None)

set_status.py

result = client.cabinets.set_item_status(
    "cab_01",
    ["item_1", "item_2"],
    "uploaded",
)
print(result["success"])

Valid statuses are "pending" and "uploaded".

remove_items

Remove specific items from a Cabinet.

HTTP endpoint: POST /api/cabinets/{cabinetId}/items/remove
Signature: cabinets.remove_items(cabinet_id, item_ids, *, options=None)

remove_items.py

result = client.cabinets.remove_items("cab_01", ["item_1", "item_2"])
print(result["success"])

zip_items

Create a ZIP archive from selected Cabinet items.

HTTP endpoint: POST /api/cabinets/{cabinetId}/zip
Signature: cabinets.zip_items(cabinet_id, item_ids, *, name=None, options=None)

zip_items.py

result = client.cabinets.zip_items(
    "cab_01",
    ["item_1", "item_2"],
    name="archive.zip",
)
print(result)

unzip_item

Extract a ZIP archive that is stored as a Cabinet item.

HTTP endpoint: POST /api/cabinets/{cabinetId}/unzip/{itemId}
Signature: cabinets.unzip_item(cabinet_id, item_id, *, options=None)

unzip_item.py

result = client.cabinets.unzip_item("cab_01", "zip_item_1")
print(result["success"])

get_item_download_url

Build a download URL for a Cabinet item. This method does not make an HTTP request. It returns a URL string synchronously.

Signature: cabinets.get_item_download_url(cabinet_id, item_id)

download_url.py

url = client.cabinets.get_item_download_url("cab_01", "item_1")
print(url)

Use a Cabinet from a task

Tasks can set cabinetId to select where intercepted browser downloads are stored:

task_with_cabinet.py

from figranium import Figranium, Task, actions
import os

client = Figranium(api_key=os.environ["FIGRANIUM_API_KEY"])

task: Task = {
    "name": "Download and reuse file",
    "url": "https://example.com/export",
    "mode": "agent",
    "cabinetId": "cab_basic",
    "actions": [
        actions.click("#download"),
        actions.upload(selector="input[type=file]"),
        actions.finalize_uploads(),
    ],
}

client.tasks.save(task)

If a task omits cabinetId, Figranium uses the instance’s default Cabinet. An individual Upload action can override the task-level selection with its own cabinetId.

Upload status

Cabinet items track whether they have been uploaded. The upload action normally selects the newest unuploaded item. You can mark an item uploaded immediately with markAsUploaded, or keep finalization separate and call finalize_uploads later in the workflow.

Keep finalization separate when attaching a file and successfully submitting it are two different steps. That lets the workflow consume the Cabinet item only after the later step succeeds.

Async usage

All cabinets methods are also available on AsyncFigranium. Use await for each call.

async_cabinets.py

import asyncio
from figranium import AsyncFigranium
import os

async def main():
    async with AsyncFigranium(api_key=os.environ["FIGRANIUM_API_KEY"]) as client:
        result = await client.cabinets.list()
        print(len(result["cabinets"]), "cabinets")

asyncio.run(main())

Action helpers

Build Upload and Finalize Uploads actions.

Tasks resource

Save and run tasks that select a Cabinet with cabinetId.

File downloads

Understand Cabinets, intercepted downloads, and the upload lifecycle.

JavaScript SDK

Python SDK

Swift SDK

CabinetsResource: Manage Files, Zips, and Uploads

Supported operations

Cabinet lifecycle

Item management

Archives

Downloads

Methods

Use a Cabinet from a task

Upload status

Async usage

Action helpers

Tasks resource

File downloads

​Supported operations

Cabinet lifecycle

Item management

Archives

Downloads

​Methods

​Use a Cabinet from a task

​Upload status

​Async usage

​Related resources

Action helpers

Tasks resource

File downloads

Supported operations

Methods

Use a Cabinet from a task

Upload status

Async usage

Related resources