Fastio API Presigned URLs Implementation Guide

Fastio API presigned URLs allow your applications to grant secure, time-limited, direct access to files without proxying the heavy traffic through your own backend servers. When a client application (whether a web browser, a mobile app, or an autonomous AI agent) needs to upload or download a large file, it first requests permission from your backend API.

Your server authenticates the user, verifies their permissions against your business logic, and generates a cryptographic signature authorizing that specific action for a limited duration. This signature is then appended to a unique URL, which the client then uses to interact directly with the Fastio storage infrastructure.

This pattern shifts the burden of file transfer away from your primary compute resources. Instead of an architecture where a gigabyte-sized asset streams through your Node.js, Python, or Go backend and consumes massive amounts of memory and network I/O, the client device communicates straight to Fastio's global edge network. Your server merely orchestrates the permission, handling a few kilobytes of JSON data rather than gigabytes of binary payload. For teams building intelligent workspaces, this separation of concerns helps maintain high performance and reduce latency during heavy collaboration sessions.

Traditional backend file upload architectures quickly encounter scaling bottlenecks. According to AWS Documentation, standard API Gateway architectures impose hard payload limits, such as a strict 10 MB constraint for requests. If you attempt to process large multimedia assets or expansive agent knowledge bases through these gateways, the requests will fail. Presigned URLs bypass these infrastructural constraints.

By offloading file transfers directly to the Fastio secure file upload API, your application lowers server bandwidth costs. Your compute resources are freed to focus on business logic rather than memory-intensive data streaming. This helps when building platforms that works alongside AI systems, where agents frequently generate massive log files, contextual documents, and generative media.

The Fastio intelligent workspace is built for this exact scale, allowing human users and AI agents to collaborate without choking your API layers. For developers evaluating the platform, the free agent tier includes 50GB storage, a 1GB maximum file limit, and 5,000 credits per month. Using presigned URLs ensures you can fully take advantage of these file size allowances without re-architecting your own proxy servers or paying high data egress fees from your cloud provider.

Implementing presigned URLs requires coordination between your client application, your backend server, and the Fastio API. Understanding this lifecycle is important for building a secure file upload system.

Phase 1: The Client Request The sequence begins when the end user or AI agent initiates an upload. Instead of sending the file payload, the client sends a metadata request to your backend server. This request includes the file's intended name, its MIME type (e.g., application/pdf), and its exact file size in bytes.

Phase 2: Authentication and Signing Your backend receives this metadata request and authenticates the user. It verifies that the user has the correct role-based access control (RBAC) permissions to write to the requested directory. If authorized, your backend uses its secure Fastio API key to request a presigned URL from the Fastio REST API. The backend must specify the exact path, content type, and an expiration window (e.g., multiple seconds or multiple minutes).

Phase 3: The Direct Client Upload Fastio returns the signed URL and the required HTTP headers to your backend, which immediately forwards them to the client. The client then issues an HTTP PUT request directly to the Fastio upload URL. This request bypasses your backend, streaming the binary payload straight to the secure storage layer.

Phase 4: Webhook Confirmation Because your backend is no longer in the data path, it cannot know when the upload finishes. To resolve this, Fastio dispatches a webhook to your server when the file is successfully committed and hashed. Your backend receives this webhook, verifies its signature, and updates your local database to mark the file asset as "available" or "processed."

Give Your AI Agents Persistent Storage

Offload your server bandwidth and integrate intelligent agent workflows with Fastio's 50GB free tier. Built for fast api presigned urls implementation guide workflows.

Sign Up Free

To request a presigned upload URL from Fastio, your backend application must issue an authenticated HTTP POST request to the API. This request defines the metadata of the file to be uploaded and the desired expiration parameters.

Here is the exact REST API payload needed to request a presigned upload URL:

POST /v1/workspaces/{workspace_id}/files/presign-upload
Authorization: Bearer YOUR_FASTIO_API_KEY
Content-Type: application/json

{
  "path": "/uploads/customer_assets/report.pdf",
  "expiresIn": 900,
  "contentType": "application/pdf",
  "maxSizeBytes": 104857600
}

When you submit this request, the Fastio API verifies your developer credentials and validates the target workspace path. If successful, it responds with the URL the client must use, along with the required HTTP method and the custom headers for the client-side upload request.

Always extract these headers as provided in the response to ensure the cryptographic signature remains valid. The API response will look like this:

{
  "uploadUrl": "https://upload.fast.io/v1/direct/abc123def456...",
  "method": "PUT",
  "headers": {
    "Content-Type": "application/pdf",
    "X-Amz-Signature": "..."
  },
  "expiresAt": "2026-02-24T18:00:00Z"
}

Your backend should parse this JSON response and pass the uploadUrl, method, and headers object directly to your frontend client or the AI agent executing the task. Do not modify the URL or append additional query parameters, as this will invalidate the signature and result in an authentication failure.

Most documentation glosses over the security headers and CORS configurations needed for presigned URLs. If your clients are web browsers, Cross-Origin Resource Sharing (CORS) rules must be correctly established on the destination bucket, or the browser will block the upload with a preflight error.

When a browser attempts to PUT a file to a Fastio upload URL, it first sends an OPTIONS request. The Fastio secure file upload API handles this preflight if the workspace CORS settings permit the origin.

To ensure success, verify that your client request includes the headers specified in the presignature response. If your backend specified "contentType": "application/pdf" during generation, the client's PUT request must include Content-Type: application/pdf. Adding unexpected headers or altering the content type will cause a signature mismatch, resulting in a multiple Forbidden error.

This strict enforcement ensures that malicious actors cannot tamper with the file type or hijack the URL for unauthorized data. In addition, the maxSizeBytes parameter ensures that clients cannot upload files larger than what your backend explicitly authorized, protecting your workspace from storage exhaustion attacks. Always set the expiresIn parameter to the shortest feasible duration (typically between multiple and multiple minutes) to minimize the window of vulnerability if the URL is intercepted.

Because the client streams the file directly to Fastio, your backend server will not know when the upload is complete. Relying on the client to send a "success" message to your backend is an anti-pattern, as network interruptions or malicious clients could manipulate this signal.

The secure approach is to configure webhooks on your Fastio workspace. Fastio will dispatch an HTTP POST request to your backend when the file is fully committed to the workspace.

When configuring the webhook, you will receive a signing secret. Your backend must use this secret to verify the HMAC signature included in the Fastio-Signature header of the incoming webhook payload. This ensures the event originated from Fastio and prevents spoofing attacks.

The webhook payload will include the workspace_id, the path of the uploaded file, its final sizeBytes, and a cryptographic hash of its contents. Once your backend verifies the signature, it can safely update the corresponding record in your database, marking the asset as ready for downstream processing or AI indexing.

For developers building autonomous AI agents, presigned URLs represent a strong performance optimization. Fastio functions as the coordination layer where agent output becomes team output. By using the Fastio MCP server available at mcp.fast.io, agents can programmatically ingest files and manage workspaces natively.

With multiple available tools via Streamable HTTP and SSE, operations like file ingestion and workspace management can be handled without writing raw HTTP clients. When an agent needs to store a large dataset, it can use the MCP server to request a presigned URL, stream the data directly to the workspace, and access Fastio's Intelligence Mode.

Intelligence Mode auto-indexes the document, making it queryable via built-in RAG (Retrieval-Augmented Generation) without requiring a separate vector database. If multiple AI models are operating concurrently within the same workspace (such as through an OpenClaw integration via clawhub install dbalve/fast-io), you should implement file locks. Acquire a lock before generating an upload URL for a specific path to prevent race conditions where two agents attempt to overwrite the same asset at the same time.

When implementing presigned URLs, developers often encounter a few specific failure modes. Understanding how to diagnose these errors will speed up your integration.

multiple Signature Does Not Match: This is the most common error. It occurs when the client's upload request deviates from the exact parameters defined when the URL was generated. Verify that the client is using the HTTP method (PUT), the URL without any appended query strings, and the Content-Type header specified in the backend's presignature response.

CORS Preflight Failures: If the browser console reports a CORS error before the upload begins, it means the OPTIONS request failed. Ensure that the Fastio workspace is configured to allow requests from your frontend application's origin domain (e.g., https://app.yourdomain.com).

Request Expired: If you receive a timeout or expiration error, the client took longer to initiate the upload than the expiresIn parameter allowed. While security best practices recommend short expiration windows, ensure you provide enough time for the client application to parse the backend response and negotiate the connection to Fastio.

Entity Too Large: If the upload fails with a size-related error, the client attempted to upload a file that exceeded the maxSizeBytes parameter you specified during URL generation. Always accurately gauge the file size on the client side and request an appropriate limit from your backend.