Python SDK

pip install apulodi

import os
from apulodi import Apulodi

apulodi = Apulodi(api_key=os.environ["APULODI_API_KEY"])

apulodi = Apulodi(
    api_key=os.environ["APULODI_API_KEY"],
    base_url="http://localhost:3000",
)

from apulodi import Apulodi

apulodi = Apulodi(api_key=os.environ["APULODI_API_KEY"])

# One call performs the full flow: initiate → direct-to-storage PUT → complete.
file = apulodi.files.upload(
    open("avatar.jpg", "rb"),          # bytes / bytearray / binary file object
    file_name="avatar.jpg",
    content_type="image/jpeg",
    path="users/avatars",              # logical folder, created automatically
    metadata={"userId": "u_123"},
)
print(file["id"], file["status"])      # file_… uploaded

apulodi.files.upload(data, "report.pdf", idempotency_key="order-1234")

# Metadata
file = apulodi.files.get("file_…")
file["filename"]; file["contentType"]; file["status"]; file["metadata"]

# Listing with filters (they mirror the REST query params) + cursor pagination
page = apulodi.files.list({"path": "users/avatars", "limit": 50, "search": "avatar"})
page["pagination"]["nextCursor"]      # pass as {"cursor": …} for the next page

# …or iterate over everything matching a filter — cursors handled for you
for f in apulodi.files.iterate({"contentType": "image/png"}):
    print(f["filename"], f["size"])

# Rename / move / metadata (logical-only — no bytes are copied)
apulodi.files.update("file_…", {"filename": "profile.jpg", "path": "users/profiles"})

# Server-side copy (returns a new file id)
apulodi.files.copy("file_…", path="backups", filename="profile-backup.jpg")

# Short-lived presigned download URL — bytes go straight from storage
signed = apulodi.files.download_url("file_…", expires_in_seconds=300)
signed["url"]; signed["expiresAt"]

v2 = apulodi.files.replace("file_…", new_bytes, content_type="image/jpeg")
v2["version"]  # 2

apulodi.files.delete("file_…")    # {"id": …, "deleted": True} — soft-delete
back = apulodi.files.restore("file_…")  # re-activates within the grace window

# Fire-and-forget: returns immediately with a pending variant. Idempotent.
variant = apulodi.files.transform(
    "file_…", width=256, height=256, fit="cover", format="webp", quality=80
)

# Poll until ready (or subscribe to the file.processed webhook event).
done = apulodi.files.wait_for_variant("file_…", variant["id"], timeout=30)

# List every variant of a file / download the derivative from storage.
all_variants = apulodi.files.variants("file_…")
signed = apulodi.files.variant_download_url("file_…", done["id"], expires_in_seconds=3600)

result = apulodi.uploads.create_multipart("big.mp4", "video/mp4", size=250_000_000)
session, pending = result["session"], result["file"]

parts = []
with open("big.mp4", "rb") as f:
    for part_meta in session["parts"]:
        chunk = f.read(session["partSize"])
        parts.append(apulodi.uploads.upload_part(session, part_meta["partNumber"], chunk))

file = apulodi.uploads.complete(session["id"], parts)

apulodi.folders.list("users")             # subfolders of a logical path
usage = apulodi.usage.get("2026-09")      # omit the period for this month
usage["storage"]["usedBytes"]

result = apulodi.webhooks.create("https://example.com/hooks/apulodi")
secret = result["secret"]         # shown EXACTLY ONCE — store it server-side

apulodi.webhooks.list()
apulodi.webhooks.deliveries("wh_…", limit=25)   # status / attempts / lastError
apulodi.webhooks.redeliver("wh_…", "dl_…")

import json
import os

from apulodi import verify_webhook_signature

# Flask example — verify over the RAW body, before any parsing:
@app.post("/webhooks/apulodi")
def apulodi_webhook():
    raw = request.get_data()
    signature = request.headers.get("APULODI-Signature", "")

    if not verify_webhook_signature(
        os.environ["APULODI_WEBHOOK_SECRET"], raw.decode("utf-8"), signature
    ):
        return {"error": "invalid signature"}, 401

    event = json.loads(raw)
    # event["type"] == "file.uploaded", event["data"]["file"]["id"], …
    return {"ok": True}

from apulodi import ApulodiError

try:
    apulodi.files.get("file_missing")
except ApulodiError as e:
    e.status            # 404
    e.code              # "FILE_NOT_FOUND"
    e.message           # human-readable
    e.details           # structured extras, if the API sent any
    e.is_client_error   # True — the request was wrong, retrying won't help
    e.is_server_error   # True — retrying later may help