Recipe: check a folder, then create a sub-folder and upload missing files

💡
Prompt example
Query the content/test folder and see if files a, b, c exist. If they don't, create a new sub-folder and upload them into that folder.

This composes catalog components. It demonstrates the pattern; adapt names/ids to the task.

Pattern

list_children(folder_id) → names already present.
Compute which of the wanted files are missing.
If any are missing: create_folder(folder_id, sub_name) → new sub-folder id.
upload(sub_folder_id, path) for each missing file.
(Optional) get(asset_id) to confirm each upload resolves and sits under the sub-folder.

Confinement: folder_id must be your run-root anchor (or a folder beneath it). Every create/upload targets a folder you control — never the tree root.

Python

# components: list_children, create_folder, upload, get
def ensure_uploaded(sdk, folder_id, sub_name, files):
    """files: {display_name: local_path}. Creates sub_name under folder_id and uploads
    any files not already present. Returns {display_name: asset_id} for uploads done."""
    present = {(c.get("displayName") or c.get("name")) for c in list_children(sdk, folder_id)}
    missing = {n: p for n, p in files.items() if n not in present}
    if not missing:
        return {}
    sub_id = create_folder(sdk, folder_id, sub_name)
    uploaded = {}
    for name, path in missing.items():
        asset_id = upload(sdk, sub_id, path, name=name)  # returns a string id
        uploaded[name] = asset_id
        assert get(sdk, asset_id)["parentId"] == sub_id   # confirm placement
    return uploaded

JavaScript

// components: listChildren, createFolder, upload, get
export async function ensureUploaded(sdk, folderId, subName, files) {
    // files: { displayName: localPath }
    const children = await listChildren(sdk, folderId);
    const present = new Set(children.map((c) => c.displayName ?? c.name));
    const missing = Object.entries(files).filter(([name]) => !present.has(name));
    if (missing.length === 0) return {};
    const subId = await createFolder(sdk, folderId, subName);
    const uploaded = {};
    for (const [name, path] of missing) {
        const assetId = await upload(sdk, subId, path, name); // string id
        uploaded[name] = assetId;
        const asset = await get(sdk, assetId);
        if (asset.parentId !== subId) throw new Error(`misplaced upload: ${name}`);
    }
    return uploaded;
}

Notes

Existence check uses list_children (cheap, scoped). To search the whole tree instead, use search with a parentId Equals <folder-id> filter — see components/*/search.md.
upload returns a string id, not an object (see reference/return-shapes.md).