Upload and list files from your app

Besides the Console, your code can manage files through your project's storage address: https://<your-project>.pgbhub.app/storage.

Which key to use

• Uploads, deletes and signed links need your project's secret key (Authorization: Bearer pgb_sec_...). Use them from a server.
• Listing and checking usage accept any project key.
• Reading a public file needs no key at all.

For a browser app, the usual pattern is: your server creates a signed upload link, and the browser sends the file straight to it. See Private buckets and signed links.

With the TypeScript SDK

import { createClient } from "@pgb/sdk";

const pgb = createClient("my-project", { key: process.env.PGB_SECRET_KEY });

// List files
const files = await pgb.storage.list("users/");

// Where a public file lives
const url = pgb.storage.getPublicUrl("users/avatar_1.png");

// Delete
await pgb.storage.delete("users/avatar_1.png");

getPublicUrl only works for public buckets. For private ones, create a signed link instead.

The Python (client.storage.create_signed_url, upload_to_signed_url, create_bucket, set_bucket_visibility), Go and Rust SDKs offer the signed-link and bucket calls too. See their guides in Use the Python SDK and Use the Go and Rust SDKs.

With plain HTTP

All requests go to your project address.

Request	What it does	Key
POST /storage/upload with {"path": "...", "content_type": "..."}	Returns a temporary upload link (valid 15 minutes) for one file	Secret
GET /storage/list?prefix=...&limit=...	Lists files (up to 1000)	Any project key
DELETE /storage/delete with {"path": "..."}	Deletes a file	Secret
GET /storage/usage	Shows how much storage the project uses	Any project key
POST /storage/sign with {"bucket": "...", "path": "...", "method": "GET"}	Creates a signed link for a bucket file	Secret
GET /storage/<bucket>/<path>	Reads a file	None for public buckets, secret key for private

In listings, private files are left out for publishable keys. With a secret key they appear marked as private, with no public address.

Example upload from a server:

curl -X POST https://my-project.pgbhub.app/storage/upload \
  -H "Authorization: Bearer pgb_sec_..." -H "Content-Type: application/json" \
  -d '{"path": "reports/march.pdf", "content_type": "application/pdf"}'

Then send the file to the returned upload link with a PUT and the same content type.

Good to know

• Storage is a file store reached over these HTTPS endpoints. It is not a general file-system mount.
• A "not found" answer can mean the file does not exist or that you lack access to a private file.
• Large uploads are better sent straight from the browser to a signed upload link than through your own server.