How to Use Fastio API Presigned URLs for Client-Side Uploads

Traditional file upload architectures rely on the application server acting as an intermediary proxy. When a user uploads a document, video, or large dataset, the file travels from their browser to your backend server, which then streams that exact same file to your final cloud storage destination. While this approach is simple to understand and implement, it creates a big bottleneck as your application grows.

Proxying files consumes backend resources that should be reserved for business logic. Every active upload ties up server memory and holds open long-running network connections. It also burns through CPU cycles just to move bytes from network sockets. If multiple users attempt to upload large files concurrently, your server can easily exhaust its connection pool or run out of memory. This can cause the entire application to crash for every user on the system.

The financial cost is also an issue. This architecture forces you to pay for bandwidth twice. You pay once when the file data enters your infrastructure from the client, and you pay again when your server pushes the file to the storage layer. For data-heavy applications, these transfer costs add up fast. To solve this, modern web architectures use direct client-to-storage uploads with secure, temporary links.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

A presigned URL is a temporary, cryptographically signed web address. It grants a client direct access to a specific Fastio workspace destination without requiring native API credentials. Fastio presigned URLs let browsers securely upload files directly to your agent workspaces without bottlenecking your application server.

Instead of giving the frontend your permanent API keys, your backend generates a temporary link. Handing out permanent keys would be a major security risk. This temporary link contains embedded authentication signatures and a strict expiration timer. It also includes specific restrictions on exactly what can be uploaded. When the frontend uses this link, it speaks directly to Fastio's edge network, bypassing your application infrastructure entirely.

This approach is important for applications deploying AI agents at scale. Because Fastio provides an intelligent workspace rather than basic commodity storage, getting files into the system quickly is a top priority. Once a file lands in the workspace via a presigned URL, Fastio's built-in Intelligence Mode automatically indexes it. This makes it immediately available to the multiple MCP tools that your agents use to reason and take action.

According to the AWS Compute Blog, direct client uploads can reduce application server bandwidth costs by 100% for file operations. Because the file data bypasses your application server, your backend infrastructure only handles the lightweight JSON requests required to generate the URL and confirm the upload. It no longer has to process the megabytes or gigabytes of actual file data.

In practical terms, this means an application server that previously struggled to handle multiple large video uploads can easily manage many more concurrent uploads. The backend merely orchestrates the permission slips, while the heavy lifting of moving data is offloaded to Fastio's globally distributed infrastructure. This architectural shift improves scalability and reduces latency for the end user. It also stabilizes your core application performance under heavy load.

Implementing direct client-side uploads requires coordinating state between your frontend application, your backend server, and the Fastio API. The process follows a strict multi-step sequence to maintain security while ensuring good performance.

• Request URL from backend: The client application signals its intent to upload a file by sending the file's metadata, such as its name and size, to your backend server. The backend authenticates the user and validates their permissions before requesting a secure presigned URL from the Fastio API.
• Upload file from frontend: The backend returns the signed URL to the client. The browser then executes a direct HTTP PUT request to this URL. This transfers the file data straight to the Fastio workspace.
• Notify backend of completion: Once the direct upload finishes, the client application sends a confirmation message to your backend. Alternatively, the backend can listen for Fastio webhooks to confirm the file has landed and is ready for agent processing.

Give Your AI Agents Persistent Storage

Start using Fastio API for direct client-side uploads. Get secure, free workspace storage with built-in agent intelligence and no bandwidth costs. Built for fast api presigned urls client side uploads workflows.

Try the API Free

The first phase begins when the user selects a file in their browser or application. Before any file data moves over the network, your frontend must ask your backend for permission. Your backend server is the only component that holds your Fastio API keys and has the authority to dictate where files should be stored.

Your backend endpoint should accept the requested file name and content type from the client. It must first verify that the current user is authenticated and authorized to perform this specific action. Once authorized, the backend calls the Fastio API to generate the upload URL.

// Example Backend Implementation (Node.js)
app.post('/api/get-upload-url', async (req, res) => {
  const { filename, contentType, size } = req.body;
  
  // Verify user authentication here
  // Validate file type and size restrictions
  if (size > MAX_FILE_SIZE) {
    return res.status(400).json({ error: 'File exceeds size limit' });
  }
  
  try {
    // Request presigned URL from Fastio
    const response = await fetch('https://api.fast.io/v1/workspaces/WORKSPACE_ID/presigned-urls', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.FASTIO_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        filename: filename,
        contentType: contentType,
        expiresIn: EXPIRATION_TIME // URL valid for a short time
      })
    });
    
    const data = await response.json();
    // Return the secure URL to the frontend
    res.json({ uploadUrl: data.url, fileId: data.fileId });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate upload slot' });
  }
});

Notice that we explicitly set an expiration time using the expiresIn parameter. Presigned URLs should always be short-lived. If a URL is intercepted or leaked, it becomes useless after the expiration window closes. This protects your workspace from unauthorized access.

Once the frontend receives the presigned URL, it can begin the actual data transfer. Because Fastio is designed for agent and human collaboration, its API endpoints automatically handle the Cross-Origin Resource Sharing restrictions required for browsers to make direct cross-domain requests.

The client must use the exact HTTP method specified by the URL, which is typically PUT. It must also include the exact Content-Type header that was declared when generating the URL. If the headers mismatch, the cryptographically signed signature will fail validation, and the upload will be rejected by the server.

// Example Frontend Implementation (Browser)
async function uploadFileDirectly(file) {
  // Get the URL from our backend
  const authResponse = await fetch('/api/get-upload-url', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      filename: file.name,
      contentType: file.type,
      size: file.size
    })
  });
  
  const { uploadUrl, fileId } = await authResponse.json();
  
  // Upload directly to Fastio using the presigned URL
  const uploadResponse = await fetch(uploadUrl, {
    method: 'PUT',
    headers: {
      'Content-Type': file.type // Must match exactly
    },
    body: file
  });
  
  if (!uploadResponse.ok) {
    throw new Error('Direct upload failed');
  }
  
  // Proceed to notification phase
  return fileId;
}

For developers working with the Fastio free agent tier, remember that while you receive generous free storage and monthly credits with no credit card required, there is a strict maximum limit per individual file. Make sure your frontend validates file sizes before requesting a URL to provide fast feedback to the user.

The final step connects the isolated file upload to your application's core business logic. Because the file went directly to Fastio, your backend server does not know when the upload finishes. You must establish a reliable communication channel to confirm the file transfer worked.

The most straightforward approach is client-side confirmation. After the PUT request succeeds, the frontend makes a final API call to your backend, passing the fileId and stating that the upload is complete. Your backend can then update its database and link the file to the correct user profile. This allows you to trigger subsequent processing workflows.

However, client-side confirmation is vulnerable to network interruptions. If the user closes their browser or loses connection right after the upload finishes but before the confirmation request sends, your backend remains unaware of the new file.

For production apps, you should use Fastio webhooks. You can set up your Fastio workspace to send a server-to-server webhook event directly to your backend whenever a new file lands securely in the system. This guarantees your backend is notified, allowing you to build reliable workflows without constantly polling the API.

When implementing direct uploads, development teams frequently encounter challenges with browser security models and metadata tracking. Cross-Origin Resource Sharing is a strict browser security mechanism that prevents malicious scripts from making arbitrary requests to other domains. Fastio explicitly configures its presigned URL endpoints to accept PUT requests from any origin, so you don't have to handle the complex manual configuration yourself.

Passing metadata alongside the file requires careful planning. You cannot just append form data or extra body parameters to a direct PUT request. The request body must strictly contain the raw file bytes to match the cryptographic signature. Instead, metadata must be encoded during the URL generation phase.

When your backend requests the presigned URL from Fastio, it can attach custom metadata tags to the requested file record. Once the file upload completes from the client side, Fastio automatically associates those tags with the final stored object. This ensures that when your AI agents or downstream services query the file later, they receive the metadata alongside the file contents. You could pass along the original uploader ID or the workflow status, for example.

Implementing direct uploads solves the bandwidth problem, but where those files land matters even more. Fastio is designed as an intelligent workspace, not just basic commodity storage. It serves as the active coordination layer where agent output becomes real team output.

When you bypass your server and upload directly to Fastio, you drop files into an environment that is natively understood by large language models. Humans use the web interface, while agents use the built-in tooling. Every single UI capability has a corresponding agent tool, ensuring parity between human and machine workers.

You can use OpenClaw by running clawhub install dbalve/fast-io in your terminal. This gives your existing AI models immediate access to manage these files via natural language commands. Agents can create organizations and build workspaces to share with team members. They can also perform an ownership transfer to a human client while retaining administrative access. This makes Fastio a strong infrastructure choice for developers building AI systems.