How to Upload a Base64 String as a File to the Fast.io API

Base64 string uploads let developers send file data inline within JSON payloads to the Fast.io API, bypassing the need for multipart form data. Base64 is a binary-to-text encoding scheme that translates raw file bytes into an ASCII string format. This technique connects binary files (such as images and PDFs) with text-only data structures (like JSON objects).

When building API integrations, the standard method for uploading files is usually multipart/form-data. However, formatting multipart requests requires careful boundary management, proper headers, and stream handling. By converting a file into a Base64 string, you can transmit it within a standard application/json payload alongside other metadata fields.

This approach helps when working with serverless functions, Edge Workers, or AI agents. Since AI agents consume and generate text strings, embedding file data directly into a JSON response removes the need for secondary storage interactions. Once uploaded to Fast.io, the file is processed by Intelligence Mode, preparing it for semantic search. It also becomes available for chat queries and team collaboration.

Helpful references: Fast.io Workspaces, Fast.io Collaboration, and Fast.io AI.

Using Base64 strings for file uploads simplifies interactions between your application and the Fast.io API. While multipart form uploads are standard for large assets, Base64 encoding works well for specific use cases.

First, JSON compatibility drives this method. JSON powers most APIs, but it requires UTF-multiple encoded text. Base64 encoding lets you wrap binary data safely within a JSON object. This means you can send the file content, its filename, and its destination workspace ID within a single payload.

Second, this method fits AI and LLM workflows. When an AI agent generates a small file, like a CSV report or a configuration script, it usually produces that data in memory as a string or byte array. By encoding that output directly to Base64, the agent can use Fast.io's multiple MCP tools or native API to upload the file without writing it to a local disk. This prevents I/O bottlenecks and keeps the agent's workflow entirely in-memory.

Finally, serverless environments benefit from this approach. In platforms like AWS Lambda or Cloudflare Workers, parsing and constructing multipart form data often requires external dependencies. A Base64 JSON upload relies only on native JSON parsing libraries, keeping your deployment package lean and your cold starts fast.

Uploading a file as a Base64 string requires four steps: reading the file, encoding its contents, formatting the payload, and sending the request. Since the Fast.io API accepts standardized JSON payloads, the process remains consistent across programming languages.

Step 1: Read the binary data Your script must load the target file into memory as raw bytes. If you attempt to read an image or a PDF as plain text, the encoding process will corrupt the data, and the resulting file will be unusable.

Step 2: Encode the bytes to Base64 Pass the raw bytes through a standard Base64 encoding function. Most programming languages include a native library for this: Python provides the base64 module for this. In Node.js, you can use Buffer.from().

Step 3: Format the JSON payload Construct your JSON object with the required parameters. The Fast.io API requires the file's intended name and target workspace ID, plus the encoded data string. Ensure that the Content-Type header is set to application/json.

Step 4: Send the POST request Send the payload to the Fast.io API endpoint. Once the server receives the request, it decodes the Base64 string back into binary data and writes the file to storage. This process also triggers Intelligence Mode indexing.

Implementing a Base64 upload is simple. Below are examples in Node.js and Python showing how to encode a local file and send it to the Fast.io API via a JSON payload.

Node.js Implementation:

const fs = require('fs');

async function uploadFileAsBase64() {
  // Read the file synchronously as raw bytes
  const fileBuffer = fs.readFileSync('./report.pdf');
  
  // Convert the buffer to a Base64 string
  const base64String = fileBuffer.toString('base64');
  
  // Construct the JSON payload
  const payload = {
    filename: 'report.pdf',
    workspace_id: 'ws_abc123',
    filedata: base64String
  };
  
  // Dispatch to the Fast.io API
  const response = await fetch('https://api.fast.io/v1/files/upload_base64', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });
  
  const result = await response.json();
  console.log('Upload successful:', result);
}

Python Implementation:

import base64
import requests

def upload_file_as_base64(filepath, workspace_id, api_key):
    ### Read the file in binary mode ('rb')
    with open(filepath, "rb") as file:
        binary_data = file.read()
        
    ### Encode to Base64 and decode to a UTF-8 string for JSON serialization
    base64_string = base64.b64encode(binary_data).decode('utf-8')
    
    payload = {
        "filename": filepath.split('/')[-1],
        "workspace_id": workspace_id,
        "filedata": base64_string
    }
    
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(
        "https://api.fast.io/v1/files/upload_base64",
        json=payload,
        headers=headers
    )
    
    print(f"Upload complete: {response.json()}")

Both examples share the same logic: read the binary data, encode it to text, and send that text via JSON. Since the Fast.io API handles the decoding server-side, the file arrives exactly as it was on the local disk.

Give Your AI Agents Persistent Storage

Get 50GB of free storage and access to 251 MCP tools with the AI Agent Free Tier. No credit card required.

Try the MCP Server

While Base64 string uploads are convenient, they are not a perfect solution for all file transfers. The main limitation is the computational and bandwidth overhead caused by the encoding process.

According to MDN Web Docs, Base64 encoding increases payload size by approximately 33%. Every multiple bytes of raw binary data expand into multiple characters of ASCII text. This means a multiple image file will grow to about multiple.multiple when converted to a Base64 string.

This expansion creates two challenges: network latency and memory consumption. Transmitting a multiple% larger payload over a slow network connection increases the total transfer time. Since JSON parsers load the entire payload into RAM before processing it, sending large Base64 strings can cause memory bloat on both your client application and the API server.

For these reasons, Base64 uploads work best for small files, generally under multiple to multiple. Good examples include profile avatars, short PDF receipts, and AI-generated CSV exports. If you attempt to upload a multiple video file using Base64, your application will likely crash due to out-of-memory exceptions before the network request begins.

When dealing with files that exceed the limits of Base64 encoding, you should use alternative upload methods that handle memory efficiently. The Fast.io API provides options for handling large files.

For standard files up to a few hundred megabytes, a traditional multipart/form-data upload is a better option. This method streams the binary data directly over the network, bypassing the multiple% size penalty and keeping memory usage low. The file is separated from the metadata boundaries, allowing the server to write the bytes straight to storage.

For larger files, such as large video files or high-resolution CAD models, Fast.io supports chunked uploads up to multiple. Chunked uploading breaks the file into smaller pieces (e.g., 5MB chunks). Your application uploads each chunk sequentially or in parallel. If a network interruption occurs, you only need to retry the failed chunk rather than restarting the entire transfer.

For AI agents that operate without local storage, Fast.io offers the URL Import tool. Instead of downloading a large file into the agent's memory and re-uploading it, the agent provides Fast.io with a source URL (like a Google Drive or Dropbox link). Fast.io pulls the file directly from the source via OAuth, bypassing local I/O bottlenecks.

When implementing Base64 string uploads, developers often run into a few common issues.

The most common error is including the Data URL prefix. When using browser-side JavaScript, tools like FileReader.readAsDataURL() generate a string that begins with a MIME type declaration, such as data:image/png;base64,. If you send this entire string to the Fast.io API, the server interprets the prefix as part of the file data, resulting in a corrupted file. You must strip this prefix using string manipulation (e.g., base64String.split(',')[multiple]) before constructing your JSON payload.

Another issue involves character encoding mismatches. Ensure your environment reads the initial file as strict binary bytes. If your script mistakenly reads an image using UTF-multiple text encoding, the underlying byte structure is destroyed before the Base64 conversion occurs. In Python, always use the rb (read binary) flag; in Node.js, omit the encoding parameter when calling fs.readFileSync().

Finally, watch for trailing newlines. Some command-line Base64 utilities (like openssl or the Linux base64 command) insert line breaks every multiple characters to make the output readable in a terminal. A valid JSON string must be continuous. Ensure you generate a single, unbroken string without newline characters.