Tutorial: Direct Uploads at Scale

Building scalable decentralized applications requires a robust strategy for handling data ingestion. Whether you are migrating terabytes of archival data or building a platform that accepts user-generated content (UGC), choosing the right upload method is critical for performance and security.

Filebase offers a versatile suite of upload interfaces, allowing you to choose the best tool for your specific architecture. This guide explores the technical implementation of our primary upload methods.

1. IPFS RPC API (Recommended)

For developers already familiar with the IPFS ecosystem, our IPFS RPC API is often the most natural choice. It implements the standard Kubo RPC specification, allowing you to use standard IPFS tools and libraries while backing your data with Filebase's geo-redundant infrastructure.

This method is ideal for server-side integrations where you want direct control over the IPFS add process.

# Upload a file using the IPFS RPC API
curl -X POST -H "Authorization: Bearer <api-key>" \
  "https://rpc.filebase.io/api/v0/add" \
  -F "file=@my-large-dataset.tar.gz"

The RPC API supports standard features like wrap-with-directory and CID version selection, making it a drop-in replacement for local IPFS nodes in many workflows.

2. Filebase SDK

For JavaScript and Node.js applications, the Filebase SDK provides a high-level, type-safe interface for interacting with your buckets and objects. It abstracts away the complexity of raw API calls.

The SDK is perfect for backend services that need to manage buckets, upload files, and handle IPNS naming in a unified way.

import { ObjectManager } from '@filebase/sdk'

const objectManager = new ObjectManager(process.env.FILEBASE_KEY, process.env.FILEBASE_SECRET, { 
  bucket: 'my-bucket' 
});

// Upload a file directly
const content = fs.readFileSync('local-file.png');
const uploadedObject = await objectManager.upload('remote-file.png', content);

console.log(`Uploaded to IPFS: ${uploadedObject.cid}`);

Security Note: The SDK requires your Secret Key. Never use the SDK with your secret keys in frontend client-side code (React, Vue, etc.), as this would expose your credentials to the public.

3. Pre-Signed URLs (For User Uploads)

When building an application where users upload content (like a social media dApp or NFT minting platform), you should not route files through your own backend server. This adds unnecessary latency and bandwidth costs.

Instead, use Pre-Signed URLs. This pattern allows your backend to authorize a temporary, secure upload slot directly to Filebase.

Step 1: Generate the URL (Server-Side)

Your backend authenticates the user and generates a signed URL using our S3-compatible API.

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

// Configure the S3 Client for Filebase
const s3 = new S3Client({
  region: "us-east-1",
  endpoint: "https://s3.filebase.com",
  credentials: { 
    accessKeyId: process.env.FILEBASE_KEY, 
    secretAccessKey: process.env.FILEBASE_SECRET 
  }
});

// Generate a pre-signed URL valid for 1 hour
const command = new PutObjectCommand({ 
  Bucket: "my-app-uploads", 
  Key: "user-uploads/avatar-123.png",
  ContentType: "image/png"
});

const url = await getSignedUrl(s3, command, { expiresIn: 3600 });
console.log("Upload URL:", url);

Step 2: Upload the File (Client-Side)

Your frontend then uses this URL to upload the file directly to Filebase. No keys are exposed, and the URL expires automatically.

# Client-side upload using the pre-signed URL
curl --request PUT \
  --upload-file "avatar.png" \
  --header "Content-Type: image/png" \
  "https://s3.filebase.com/my-app-uploads/user-uploads/avatar-123.png?X-Amz-Algorithm=..."

4. S3-Compatible API

If you have existing infrastructure built around AWS S3, you can simply point it to Filebase. Our API is S3-compatible, meaning tools like the AWS CLI, rclone, and various backup software work out of the box.

Endpoint: https://s3.filebase.com
Region: us-east-1

5. Web Dashboard

For ad-hoc uploads, testing, or non-technical team members, the Filebase Dashboard offers a simple drag-and-drop interface. You can create buckets and upload files or entire folders directly from your browser.

Summary