Storage API

Use the CesiumCloud REST API to list account files, inspect storage quotas, upload files in resumable chunks, download files as streams, and delete files. The API uses the same account storage and quotas as the CesiumCloud website.

CesiumCloud CLI & SDK — current release 0.2.1

Replace or cancel uploads: cesiumcloud upload --replace "file.txt" creates a new file when absent or replaces the exact matching cloud path when present. cesiumcloud cancel-upload UPLOAD_ID cancels the incomplete upload session, leaving already completed files intact. On the website, replacing a file archives its previous version under ReplacedFiles with a five-day expiration; the storage coordinator must support replacement archives for this feature.

Both official packages are now published to npm and PyPI. Version 0.2.1 uses independent, individually deletable objects through the authenticated Altare coordinator; uploads no longer rebuild shared storage packs. Sign in with a device code through cesiumcloud authenticate.

npm install --global [email protected]
cesiumcloud authenticate
cesiumcloud upload "E:\Downloads\My file.mp4"
cesiumcloud list -a
cesiumcloud download "images/dog.png" --location "E:\Downloads"

Node.js 22+ is required. Optional client-side authenticated encryption is available with cesiumcloud e2ee help. Existing historical legacy storage packs remain separate and are not automatically converted or physically erased by the client upgrade. npm registry.

Python SDK & CLI — current release 0.2.1

Python 3.10+ is supported. Install into a virtual environment when your system Python is externally managed.

python3 -m pip install --upgrade cesiumcloud==0.2.1
python3 -m cesiumcloud authenticate
python3 -m cesiumcloud upload "/home/user/Documents"
python3 -m cesiumcloud download "/home/user/Restored"

Python SDK: from cesiumcloud import CesiumCloudClient. PyPI registry. Client files are independent in both languages; deleted Google Drive objects are verified against provider metadata for dashboard usage. Provider-side removal is not emulated by merely deleting a local catalog record.

Linux installation

For Ubuntu and Debian, use the official Python SDK in a virtual environment, as shown below. The Python CLI works without Node.js, and supports filenames with spaces and incremental upload progress. For npm users, Node.js 22+ is required. Legacy APT packages are no longer offered as the recommended installer.

Storage organization and download history

Each customer has an isolated storage namespace. All reads and writes are authorized against the authenticated account ID; visible names are not used as access permissions. Internal storage topology is not part of the public API contract.

The web dashboard shows download history and real-time received-byte progress for supported browsers, including large downloads tracked through a service worker. Completed means bytes reached the browser; the browser controls the final save location and disk write. History is stored in this browser only.

Security assessment

CesiumCloud passed 43/43 live two-account API security checks on October 27, 2026, including cross-account file access, download/delete denial, expired sessions and revoked keys. Read the detailed security report for method, evidence and limitations. Availability target: 99.9% (not a contractual SLA).

Ubuntu 22.04, 24.04, 26.04 and 26.10

The dependency-free Python CLI supports Python 3.10+ (including Python 3.10 on Ubuntu 22.04, Python 3.12 on Ubuntu 24.04 and Python 3.14 on Ubuntu 26.10). Use an isolated Python virtual environment; modern Ubuntu system Python may block global pip installations.

sudo apt-get update
sudo apt-get install -y python3 python3-venv
python3 -m venv "$HOME/.local/share/cesiumcloud/venv"
"$HOME/.local/share/cesiumcloud/venv/bin/python" -m pip install --upgrade cesiumcloud==0.2.1
"$HOME/.local/share/cesiumcloud/venv/bin/cesiumcloud" authenticate
"$HOME/.local/share/cesiumcloud/venv/bin/cesiumcloud" upload "$HOME/Videos/My video.mp4"

Quote complete filenames when they contain parentheses, particularly in PowerShell: cesiumcloud upload "E:\Downloads\Roblox 2026-10-18 13-37-47 (1).mp4". PowerShell removes unquoted parenthesized suffixes before they reach the client; the CLI cannot recover arguments that the shell discards. CesiumCloud 0.2.1 detects missing paths and suggests matching fully quoted filenames instead of selecting a potentially different file. Plain spaces without parentheses can still be accepted as unquoted fragments. Progress updates while data is transmitted. The Python client does not yet persist interrupted transfer sessions between separate runs. Node.js 22+ is necessary only for the npm CLI, not for the Python CLI.

Complete CLI command reference — version 0.2.1

Both official clients support the same commands on Windows, macOS and Linux. The root/ prefix means your own cloud home directory, not a local folder.

CESIUMCLOUD CLI REFERENCE — Python and npm (0.2.1)
====================================================
Usage: cesiumcloud COMMAND [arguments]. Use cesiumcloud help for this reference.
Linux/macOS examples use / paths; Windows examples use quotes around local paths.

ACCOUNT
  cesiumcloud authenticate                     Approve device code at CesiumCloud website
  cesiumcloud whoami                           Show signed-in account
  cesiumcloud logout                           Remove local CLI credential; does not revoke key remotely

UPLOAD / DOWNLOAD
  cesiumcloud upload "E:\Downloads\dog.png"      Upload local file
  cesiumcloud upload "./My Documents"          Upload local folder (recursively)
  cesiumcloud download "E:\restore"             Full-account restore into local folder
  cesiumcloud download dog.png --location "E:\Downloads"
  cesiumcloud download "images/dog.png" --location "E:\Downloads"
      Download ONLY one named cloud file into the local folder. The folder is
      created if needed. Existing local files are never overwritten. Relative
      filenames use the current cloud directory set by cesiumcloud dir.
      Quote local Windows paths and names containing spaces/parentheses.
      Both Python and npm display local live progress as file bytes arrive.
      Progress updates never issue extra Worker requests. 100% is shown
      only after the file is safely published; transfer retries can still
      issue the normal Range requests.

BROWSING
  cesiumcloud list                             List 15 items of current cloud directory
  cesiumcloud list -10                         List 10 items
  cesiumcloud list 20                          List 20 items (also -n 20)
  cesiumcloud list -a                          List all files (paginated)
  cesiumcloud list -long                       Show full names and metadata
  cesiumcloud list -next 15                    Next 15 results after list
  cesiumcloud list -10 images/dogs [and] images/cats
  cesiumcloud list -sort size                  Default sorting (largest first)
  cesiumcloud list -sort name                  Persist sort by name
  cesiumcloud list -sort lastmodified          Persist newest-modified-first sorting
  cesiumcloud list -sort datecreated           Persist newest-created-first sorting
  cesiumcloud list -sort reset                 Reset sort to size
  cesiumcloud search dog.png                   Search filename
  cesiumcloud search .png                      Search extension
  cesiumcloud search ext:png                   Search extension (alternate)
  cesiumcloud search dog [and] .png           Search multiple terms
  cesiumcloud dir                              Go to cloud root and show it
  cesiumcloud dir images/dogs                  Change virtual directory
  cesiumcloud list -5 dogs [and] cats         List multiple directories
  cesiumcloud dir ..                           Up to parent directory
  cesiumcloud dir -                            Back in navigation history
  cesiumcloud dir /                            Go to root directory

RENAME (changes virtual filename; same stored bytes)
  cesiumcloud rename dog.png cat.png
  cesiumcloud rename root/images/dog.png cat.png
  cesiumcloud rename root/images/dog.png cat -ne
      Without -ne, omitted NEW extension inherits the original one.
      With -ne, remove the original extension if new name has none.
      A plain new name stays in the original file's cloud directory.
      Rename refuses existing target paths. Folder rename not supported;
      use move for entire directories.

MOVE (changes virtual paths, without transferring or rewriting file bytes)
  cesiumcloud move root/images/dog.png to root/things
  cesiumcloud move root/passwords.txt [and] root/securitypasswords.txt [to] root/important/secure/critical
  cesiumcloud move root/images [and] root/notes [to] root/archived
  cesiumcloud move images/dog.png [and] images/cat.png [to] root/things
  cesiumcloud move root/things/dog.png to root
      Accepts file and whole-directory sources (1-20 sources per invocation,
      max 1000 affected files). Directory moves preserve their folder name
      and subfolders. File moves preserve original basenames/extensions.
      Destination directories are virtual and created automatically as needed.
      Move rejects target collisions, duplicate sources, and recursive moves.
      The server applies each batch of path changes in one D1 transaction.
      These are logical CesiumCloud paths, NOT local filesystem paths.

DELETE (PERMANENT, not recoverable through the CLI)
  cesiumcloud delete dog.png
  cesiumcloud delete root/images/dog.png [and] root/notes/old.txt
  cesiumcloud delete root/images/dog.png root/notes/old.txt
  cesiumcloud delete -resume                  Finish a pending physical removal
      Files are permanently removed from backing storage, not just hidden.
      Other files that share storage packs are preserved and verified.
      Each selected file is processed in sequence; batch delete is not atomic.
      Directory deletion is deliberately unavailable.

PATHS & SHELL RULES
  root/ is the top of YOUR authenticated cloud namespace (for rename,
  move, delete). Bare filenames use the current virtual directory.
  For browsing, use '/' as root, e.g. 'cesiumcloud list -10 /'.
  Use [and] to separate multiple files or directories without quotes.
  This works in Windows CMD, PowerShell, Bash and Zsh. A shell pipe
  is NOT a CesiumCloud separator. Quote paths containing spaces.
  Use 'to' or the literal '[to]' as the move destination separator.
  Put quotes around paths containing spaces or special shell characters.
  An extensionless filename matches only when unambiguous; otherwise
  include its extension. '/' is the cloud separator, not Windows '\'.

MORE HELP
  cesiumcloud help
  cesiumcloud --help
  cesiumcloud move --help
  cesiumcloud rename --help
  cesiumcloud delete --help
  cesiumcloud list --help

FILE MANAGEMENT GUARANTEES
  Browsing uses indexed metadata rather than streaming file payloads.
  Move/rename do not rewrite payload bytes. Single-file download streams
  only the requested segments. Delete is destructive and can require
  repacking unaffected files; resume cleanup if interrupted.

For the full help directly in a terminal, run cesiumcloud help or cesiumcloud --help. The virtual move endpoint is POST /v1/catalog/move with JSON {"sources":["images/dog.png","notes"],"destination":"important"}; it requires a write-enabled credential and never transfers file contents.

Live download progress (0.2.1): Both Python and npm CLIs show continuously updated bytes received and percent complete while a selected cloud file downloads. No additional Worker requests are used to report progress: measurements come from the existing data stream. The CLI shows 100% only after safely publishing the completed file.

Download one named file with --location (0.2.1)

Both Python and npm CLIs can now download exactly one virtual file to a specified local directory, without restoring every backed-up file.

cesiumcloud download dog.png --location "C:/Users/matth/Desktop"
cesiumcloud download "images/dogs/dog.png" --location "E:/Downloads"
cesiumcloud download "photo (1).jpg" --location "./restored"

Filenames are resolved relative to the current virtual cloud directory. The file is saved into the local folder with its basename. Downloads refuse to overwrite an existing local file and only publish the output after a complete transfer. Interrupted range downloads can resume remaining bytes. This uses GET /v1/catalog/file?path=<cloud-path> for authenticated service database metadata lookup, then GET /v1/virtual-files/<pack>/segments/<index> for each relevant file segment. Other files in shared packs are not downloaded. The existing full-restore command (download DIRECTORY) without --location still performs a full backup restore.

Readable CLI tables (0.1.9)

File listings now use terminal-width-aware aligned columns instead of long, wrapping per-file sentences. Default output shows NAME, EXT, SIZE, MODIFIED (LOCAL), and UPLOADED (LOCAL). Local timestamps are compact: YYYY-MM-DD HH:MM. Narrow terminals show fewer columns instead of wrapping. Long filenames are middle-truncated; use cesiumcloud list -long to see complete filenames and all metadata. Commands cesiumcloud list 20, list -20, and list -n 20 now all specify 20 items, and -next 20 paginates the same way as before.

Indexed directory listing and pagination (0.1.8)

Lists never open or iterate through backing storage objects. CesiumCloud now stores each pack's file segment metadata in the authenticated, account-scoped CesiumCloud metadata index index as uploads commit. The database handles filtering by directory, sorting, pagination and searching; it returns only the requested page of entries, regardless of backup pack byte size. An upload of three 64 GB packs needs no additional Drive reads when listing files. Earlier clients scanned the entire catalog before printing any output; the new GET /v1/catalog/browse?mode=list&dir=&limit=10&offset=0 returns ten direct directory entries and the total count. The mode=all, mode=search, and mode=exists variants share the same indexed metadata. The existing backed-up bytes and physical deletion mechanism remain unchanged. For an indexed account, common lists are typically answered in under a second, depending on the user's network and account size.

Fast file catalog (0.1.8)

File listings and directory lookups now use a per-account indexed metadata cache in CesiumCloud metadata index. The old repeated remote index lookups could make cesiumcloud list and cesiumcloud dir appear frozen. Immutable backup-pack manifests are cached after validation, with a one-time backfill for older packs. Navigation to root, a parent directory, or the previous directory runs locally without contacting the API. An initial backfill may take several seconds; subsequent listings are significantly faster. No user file contents are cached by the file browser.

New API: GET /v1/catalog/index?cursor=0 (authenticated, paginated). Older virtual-file endpoints remain available for compatibility.

Command-line file browser and permanent deletion (0.1.8)

Both clients support list, search, dir, rename, and delete. Listing defaults to 15 entries sorted by size, including immediate virtual directories, extensions, file sizes, last-modified and uploaded timestamps.

cesiumcloud list -10
cesiumcloud list -a
cesiumcloud list -10 images/dogs [and] images/cats
cesiumcloud list -next 15 images/dogs
cesiumcloud list -sort name
cesiumcloud search .png
cesiumcloud dir ..
cesiumcloud dir -
cesiumcloud rename images/dogs/pic.png better-name
cesiumcloud rename images/dogs/pic.png better-name -ne
cesiumcloud delete images/dogs/unwanted.png
cesiumcloud delete -resume

When deleting a file, surviving segments in shared packs are reuploaded into staged replacement backing storage objects. After database cutover, the old storage objects are permanently deleted and confirmed absent before their storage accounting is released. After an interrupted purge, use delete -resume. Deletion is irreversible and may require temporary storage quota. A literal pipe must be quoted in a terminal, since unquoted pipes are shell operators. To list inside an archive, first extract and upload it as a directory.

API routes: GET /v1/virtual-files, GET /v1/catalog/renames, POST /v1/catalog/rename, POST /v1/catalog/swap, POST /v1/packs (internal staged option), DELETE /v1/packs/{packId}. The clients orchestrate multi-pack physical file deletions.

Download recovery and integrity

Both the Python and npm CesiumCloud 0.2.1 CLIs detect incomplete downloads and use byte-range recovery. The npm restore verifies storage-object integrity checksums when provided and reassembles files split across multiple packs. Restores must use a new output directory when retrying; interrupted partial files are preserved rather than silently overwritten or removed. This does not add progress Worker requests to uploads.

Authentication

Sign in to the CesiumCloud dashboard as the owner, go to Owner controls → API access, choose an account, and generate a read-only or read/write key. Supply it in the Authorization header to every protected endpoint. There is no password or third-party authorization exchange for API clients.

Authorization: Bearer tc_live_YOUR_KEY

Keep API keys in server-side secret storage. Do not embed them in public HTML, JavaScript, mobile applications, or URLs. Browser cross-origin use is not enabled by default; this API is intended for trusted backend integrations.

Quick start

curl https://api.cesiummc.space/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://api.cesiummc.space/v1/files \
  -H "Authorization: Bearer YOUR_API_KEY"

Readable API responses

API responses include human-readable storage sizes, capitalized roles, and dates in UTC. File sizes use decimal units: 1 KB = 1,000 bytes, 1 GB = 1,000,000,000 bytes, and 1 TB = 1,000,000,000,000 bytes. The original numeric byte counts and timestamp fields are also preserved for programs that need exact values.

{
  "email": "[email protected]",
  "role": "Admin",
  "total_storage": "50 GB",
  "used_storage": "234.82 KB",
  "reserved_storage": "0 B",
  "available_storage": "49.9998 GB",
  "created_at": "October 26th, 2026 at 3:32 PM UTC",
  "access": "Read / Write",
  "storage": {
    "quota_bytes": 50000000000,
    "used_bytes": 234823,
    "reserved_bytes": 0,
    "available_bytes": 49999765177,
    "usage_percentage": 0.00047
  },
  "created_at_iso": "2026-10-26T15:32:00.000Z",
  "created_at_unix_ms": 1793028720000,
  "user": {
    "email": "[email protected]",
    "role": "admin",
    "quota": 50000000000,
    "used": 234823,
    "reserved": 0
  },
  "permission": "write"
}

GET /v1/files retains the original files array, file IDs, byte counts, and Unix timestamps, while adding count, size (for example, 234.82 KB), uploaded_at, and uploaded_at_iso.

Endpoints

curl -X POST https://api.cesiummc.space/v1/transfer/client-queue/batch \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"files":[{"clientKey":"12345678-1234-4123-8123-123456789abc","path":"backups/data.bin","size":1000000000000,"mimeType":"application/octet-stream"}]}'

Legacy streaming packed backups (compatibility)

The current independent-file web uploader and updated Node/Python SDK use the client-held Altare metadata queue described above. Creating new packed backups through the old direct Google upload method is disabled. Existing stored packs remain readable or deletable, and previously started transfers may be finalized.

The pack contains a 16-byte header, a gzip-compressed file index (maximum 2 MiB), and contiguous file data. Very large original files can span multiple packs. A whole-backup restore downloads packed streams rather than requesting every original file separately. Original paths and byte offsets are retained for reconstruction.

The retired POST /v1/uploads route still returns 410 Gone for new legacy objects. Use the independent-file /v1/transfer/client-queue API followed by /v1/transfer/grant and Altare /v2/uploads for new file uploads. Existing legacy packs remain readable and deletable. New pack creation returns HTTP 410.

Backup client for large directories

Use the maintained CesiumCloud command-line client rather than older standalone scripts. The current Python and npm clients upload independent files through the shared Altare queue, including live progress reporting. Earlier packed-backup clients are retired for new uploads. The Python client currently retries interrupted chunks during a process but does not persist a checkpoint across sessions.

cesiumcloud authenticate
cesiumcloud upload "/home/user/My Backup Folder"
cesiumcloud download "/home/user/Empty Restore Folder"

Keep independent copies of important files and keep saved credentials private.

Programmatic pack protocol

Construct CesiumCloud Pack V1 locally and call POST /v1/packs with {"sizeBytes":N,"sourceBytes":M,"segments":K}. This returns packId and an authorized uploadUrl. PUT data to that HTTPS URL with the resumable Content-Range protocol. When the final upload response returns its id, call POST /v1/packs/{packId}/commit with {"driveFileId":"..."}. CesiumCloud verifies the completed transfer before recording the backup. Use GET /v1/packs and GET /v1/packs/{packId}/download for restoration.

Per-account concurrency and service limits

The client-held queue has no fixed waiting-ticket count; it admits up to 24 active independent-file transfers across API and web clients. Altare paces Google Drive write starts to 50 per second. Older pack and upload-session endpoints retain their separate legacy limits, including the 25/5 older upload-slot policy and the five simultaneous pack-session policy. Each account permits up to 20 download streams. Clients must still respect quota, temporary errors and Retry-After responses.

Download a file

curl -L "https://api.cesiummc.space/v1/files/FILE_ID/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o my-file.bin

Response errors

JSON error responses include an error description. Expect HTTP 401 for missing or revoked keys, 403 for insufficient permissions, 404 for unknown or inaccessible files, 409 for quota/range conflicts, and 5xx for upstream failures. Large file transfers remain subject to service limits.

Current limitations: CesiumCloud enforces storage quotas per account but does not yet meter monthly bandwidth. Customer data is backed up periodically to offsite storage, but recovery time and complete restoration of every file version are not guaranteed. The storage service may require periodic administrator reauthorization. Do not promise paid API capacity until those limitations are addressed.

cesiumcloud e2ee migrate "root/app/index.html"
cesiumcloud e2ee migrate "root/app/index.html" --purge-original --i-backed-up-key
cesiumcloud e2ee keygen
cesiumcloud e2ee upload "My confidential file.pdf"
cesiumcloud e2ee download "My confidential file.pdf.ccenc" --location "E:/Downloads"