Pandafile Pro · SDKs and CLI

Official SDKs and command line

Send a file of any size in three lines of code. The official libraries for JavaScript/TypeScript and Python, and the pandafile command line, create the transfer, upload every file with resumable uploads, complete it and hand you the link.

They are thin, dependency-light wrappers around the public API: typed for every endpoint (generated from the OpenAPI document), with automatic idempotency keys, retries, pagination and webhook verification. The API is included with Pro and Team; create a key in Dashboard → Domain & API.

JavaScript / TypeScript

Node 18+, browsers, Deno, Bun. ESM and CommonJS, no dependencies.

npm install @pandafile/sdk

Python

Python 3.9+, sync and async clients, only needs httpx.

pip install pandafile

Command line

macOS, Linux, Windows. Progress bar, resume, --json.

npm install -g @pandafile/sdk

Install and authenticate

JavaScript

npm install @pandafile/sdk
export PANDAFILE_API_KEY=pf_live_YOUR_KEY   # or pf_test_… for test mode

Python

pip install pandafile
export PANDAFILE_API_KEY=pf_live_YOUR_KEY   # or pf_test_… for test mode

CLI

npm install -g @pandafile/sdk      # or run it once with: npx @pandafile/sdk …
pandafile login                    # paste your key; stored owner-only (0600) in your config folder
pandafile login --test             # optional: a pf_test_ key for --test

Send files

One call creates the transfer, uploads every file (in parallel, in chunks, resuming after dropped connections) and completes it. Folders keep their structure, exactly like dropping a folder on the website.

JavaScript

import Pandafile from '@pandafile/sdk';

const pf = new Pandafile(); // PANDAFILE_API_KEY
const { url } = await pf.transfers.send({
  files: ['final-cut.mov', 'stills/'],
  recipients: ['client@example.com'],
  title: 'Final cut',
  onProgress: (p) => console.log(`${p.percent.toFixed(1)} %`),
});
console.log(url); // https://pandafile.co/d/k3x9q2m7ab

Python

from pandafile import Pandafile

pf = Pandafile()  # PANDAFILE_API_KEY
result = pf.transfers.send(
    ["final-cut.mov", "stills/"],
    recipients=["client@example.com"],
    title="Final cut",
    on_progress=lambda p: print(f"{p.percent:.1f} %"),
)
print(result.url)  # https://pandafile.co/d/k3x9q2m7ab

CLI

pandafile send final-cut.mov stills/ --to client@example.com --title "Final cut"
 ██████████████████░░░░░░░░░░░░░░░░░░░░░░  45%  1.2 GB / 2.7 GB  84.5 MB/s  ETA 18s  3/12 files
https://pandafile.co/d/k3x9q2m7ab

In the browser, pass File objects (folder paths from <input webkitdirectory> are kept) or { name, data }. Keep live keys on your server.

Resume big uploads

Dropped connections are retried and continue at the byte the server has. To survive a crash or a restart, save the send state and pass it back: finished files are skipped, the unfinished one continues. The CLI does this for you – run the same command again.

JavaScript

const state = loadState(); // null the first time
await pf.transfers.send({
  files: ['huge.mxf'],
  state,
  onState: (s) => saveState(s), // JSON-serialisable; contains the transfer's upload secret
});

Python

pf.transfers.send(["huge.mxf"], state=load_state(), on_state=save_state)

CLI

pandafile send huge.mxf      # Ctrl-C: "Paused. Run the same command again to resume."
pandafile send huge.mxf      # Resuming 1 file (412 GB) – transfer k3x9q2m7ab

Every endpoint, typed

Each area of the API is one object: transfers, requests (file requests), signatures, branding, team, events, hooks, me, keys and domains. Lists page automatically when you iterate them.

JavaScript

for await (const t of pf.transfers.list()) console.log(t.id, t.title); // every page
const page = await pf.transfers.list({ limit: 50 });                    // one page

const req = await pf.requests.create({ title: 'Photos from the wedding' });
const draft = await pf.signatures.create('nda.pdf');
await pf.signatures.send(draft.id, {
  signers: [{ name: 'Ada Lovelace', email: 'ada@example.com' }],
  fields: [{ signer: 0, kind: 'signature', page: 0, x: 0.1, y: 0.8, w: 0.3, h: 0.06 }],
});
await pf.transfers.update('k3x9q2m7ab', { password: 'blue-river-42', extend: true });

Python

for t in pf.transfers.list():          # every page
    print(t["id"], t["title"])
page = pf.transfers.list(limit=50).page()

req = pf.requests.create(title="Photos from the wedding")
draft = pf.signatures.create("nda.pdf")
pf.signatures.send(draft["id"], signers=[{"name": "Ada Lovelace", "email": "ada@example.com"}],
                   fields=[{"signer": 0, "kind": "signature", "page": 0, "x": 0.1, "y": 0.8, "w": 0.3, "h": 0.06}])

# async: same objects, awaitable
async with AsyncPandafile() as apf:
    async for t in apf.transfers.list():
        ...

CLI

pandafile ls                       # --history, --search, --all, --json
pandafile info k3x9q2m7ab
pandafile rm k3x9q2m7ab
pandafile request create --title "Upload your photos"
pandafile request ls
pandafile whoami

Retries, idempotency and errors – built in

  • Idempotency. Every POST, PATCH and PUT carries an Idempotency-Key, reused for its retries, so a retried create never makes two transfers. Pass your own with { idempotencyKey } / idempotency_key=.
  • Retries. 429, 5xx and network errors are retried (3 times by default) with exponential backoff, waiting Retry-After when the API sends it.
  • Typed errors. NotFoundError, AuthenticationError, PermissionError (PermissionDeniedError in Python), RateLimitError, IdempotencyError, APIError and more, each with type, code, status, param and the requestId to quote to support.
  • Versioned. Each SDK release sends the Pandafile-Version it was built for, so new API versions never change its responses under you.

JavaScript

import { NotFoundError, PandafileError } from '@pandafile/sdk';
try {
  await pf.transfers.retrieve('k3x9q2m7ab');
} catch (e) {
  if (e instanceof NotFoundError) { /* gone */ }
  else if (e instanceof PandafileError) console.error(e.code, e.message, e.requestId);
}

Python

from pandafile import NotFoundError, PandafileError
try:
    pf.transfers.retrieve("k3x9q2m7ab")
except NotFoundError:
    pass
except PandafileError as e:
    print(e.code, e.message, e.request_id)

CLI

pandafile info nope1234 --json
{ "error": { "type": "invalid_request_error", "code": "resource_missing",
             "message": "No such transfer.", "status": 404, "request_id": "req_…" } }
# exit code 1 for API errors, 2 for usage errors

Webhooks

Verify the Pandafile-Signature header against the raw body with your endpoint's whsec_… secret. During development, pandafile webhook listen polls your events and forwards them, signed, to a local URL – no tunnel needed.

JavaScript

app.post('/pandafile-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = await Pandafile.webhooks.verify(req.body, req.get('Pandafile-Signature'),
    process.env.PANDAFILE_WEBHOOK_SECRET, 300);
  if (!ok) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

Python

from pandafile import webhooks

@app.post("/pandafile-webhook")
def hook():
    body = request.get_data()  # raw bytes
    if not webhooks.verify(body, request.headers.get("Pandafile-Signature"), SECRET, tolerance=300):
        abort(400)
    event = request.get_json()
    return "", 200

CLI

pandafile webhook listen --forward http://localhost:3000/pandafile-webhook --test
Ready! Forwarding test events to http://localhost:3000/pandafile-webhook (polling every 2s, Ctrl-C to stop)
Webhook signing secret: whsec_…
10:24:03  --> transfer.ready [evt_9Lr2xQ0aVb3kT1mN5pS7dw]  <-- 200 (12 ms)

Test mode

Use a test key (pf_test_…) while you build: transfers are real uploads, but nobody is emailed, they expire after 24 hours and count toward no limit. In the CLI add --test to any command. File requests, signatures, branding and team invites need a live key.

CLI reference

CommandWhat it does
pandafile login [--key …] [--test]Check and save an API key (owner-only file in the OS config folder)
pandafile send <files/folders…>Upload and print the link. --to (repeatable), --title, --message, --password, --expires 30d|2026-12-31, --concurrency, --chunk-size, --fresh
pandafile lsYour transfers (--history, --search, --limit, --all)
pandafile info <id>Files, recipients and downloads of one transfer
pandafile rm <id> [--yes]Delete a transfer and its files now
pandafile request create|ls|close|reopen|rmFile requests
pandafile webhook listen --forward <url>Forward events, signed, to a local endpoint (--events, --secret, --interval)
pandafile whoami · logoutAccount and key in use · forget saved keys

Every command takes --json (machine-readable stdout), --test, --key and --base-url; PANDAFILE_API_KEY and PANDAFILE_TEST_KEY work too (handy in CI).

AI agents (MCP)

Want Claude, Cursor, VS Code or another AI agent to send files for you? The official Pandafile MCP server (npx -y @pandafile/mcp) is built on this SDK and gives agents tools to send files and folders, add recipients, manage transfers and create file requests.

Guides

Other languages

Uploads use the open tus protocol and everything else is plain JSON over HTTPS, so any language works: see the developer guide and the API reference, or generate a client from the OpenAPI 3.1 document.