File Storage API

Upload any file and get a public URL. Supports multipart file upload or fetching from a remote URL. Files are stored for 30 days with unguessable URLs that serve as access tokens. No API key required — payment via x402.

POST https://pylon-file-storage-api.fly.dev/upload

Endpoints

MethodPathDescription
POST/uploadUpload a file (payment required)
GET/files/:id/:filenameServe a stored file (free, URL is access token)
GET/healthHealth check (free)
DELETE/files/:idDelete a file (requires auth)

Upload Methods

Method 1: Multipart upload — Send a file as multipart/form-data with field name file.

Method 2: URL fetch — Send JSON body with url and optional filename to fetch and store a remote file.

ParameterTypeRequiredDescription
filefileYes*File to upload (multipart)
urlstringYes*URL to fetch file from (JSON body)
filenamestringNoFilename for URL fetch mode

* Provide either file (multipart) or url (JSON body), not both.

Limits: Max file size 50MB. Files expire after 30 days.

Response

Returns JSON with the file URL and metadata:

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6",
  "url": "https://pylon-file-storage-api.fly.dev/files/a1b2c3.../report.pdf",
  "filename": "report.pdf",
  "size": 48210,
  "contentType": "application/pdf",
  "uploadedAt": "2026-02-17T17:00:00.000Z",
  "expiresAt": "2026-03-19T17:00:00.000Z"
}

Pricing

$0.005 USDC per upload — paid via x402 on Base (Coinbase L2). File retrieval is free.

Code Examples

# Upload a file
curl -X POST "https://pylon-file-storage-api.fly.dev/upload" \
  -F "file=@report.pdf"

# Upload from URL
curl -X POST "https://pylon-file-storage-api.fly.dev/upload" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf", "filename": "report.pdf"}'
import { wrapFetch } from "@x402/fetch";

const fetchWithPayment = wrapFetch(fetch, wallet);

// Upload from URL
const res = await fetchWithPayment(
  "https://pylon-file-storage-api.fly.dev/upload",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      url: "https://example.com/report.pdf",
      filename: "report.pdf"
    })
  }
);
const data = await res.json();
console.log(data.url); // public URL to the file
import requests

# Upload a file
with open("report.pdf", "rb") as f:
    response = requests.post(
        "https://pylon-file-storage-api.fly.dev/upload",
        files={"file": f},
    )

data = response.json()
print(data["url"])  # public URL
# Via the Pylon Gateway
curl -X POST "https://pylon-gateway-api.fly.dev/route" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "upload this file",
    "params": { "url": "https://example.com/data.csv" }
  }'

x402 Setup

To use Pylon APIs, you need an x402-compatible client with a funded wallet on Base. See x402.org for client libraries.