How to Integrate Fastio API with Java Spring Boot

Fastio is an intelligent workspace platform that auto-indexes files and provides a native Model Context Protocol (MCP) server for AI agents. Rather than treating storage as a passive repository, it turns every uploaded document into queryable knowledge immediately. This native intelligence layer removes the need to build separate vector databases or extraction pipelines in your application.

According to the JetBrains State of Developer Ecosystem 2023 report, 72% of Java developers use Spring Boot for their backend services. Integrating Fastio brings built-in Retrieval-Augmented Generation (RAG) and intelligent file management directly to these enterprise stacks. Most external tutorials focus on Node.js or Python, leaving Java developers without tailored implementation paths. This guide bridges that gap and provides a clear strategy for connecting Spring Boot microservices to Fastio's agentic infrastructure.

When you connect your Java application to Fastio, you gain access to 19 named-mode MCP tools via Streamable HTTP at https://mcp.fast.io/mcp (or https://mcp.fast.io/mcp/key with a Bearer header). Legacy SSE is https://mcp.fast.io/sse. Your backend can upload files, list storage, ask Ripley a cited question, and invite teammates without writing custom coordination logic.

Developers building internal portals or client-facing applications can create workspaces on the fly with POST /current/org/{org_id}/create/workspace/. An agent uploads the files, then invites a human with POST /current/workspace/{workspace_id}/members/{email_or_user_id}/ so they can review the same workspace from your Java service layer.

Before writing the integration code, you need a Spring Boot environment configured for reactive web requests. The non-blocking nature of file transfers and streaming AI responses makes Spring WebFlux the preferred client choice over the traditional RestTemplate.

You will need a Spring Boot multiple.x project running Java multiple or higher. Add the spring-boot-starter-webflux dependency to your Maven pom.xml or Gradle build file. This provides the WebClient necessary for efficient, reactive HTTP calls.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

You also need a Fastio account. Start from the pricing page, then generate an API key in Settings > Devices & Agents > API Keys, or with POST /current/user/auth/key/. Workspace IDs are 19-digit numeric strings; list them with GET /current/workspaces/all/. Store the key in your application.yml file under a secure property key. Never hardcode this credential in your source files.

fastio:
  api:
    key: ${FASTIO_API_KEY}
    base-url: "https://api.fast.io/current/"

Setting up externalized configuration ensures your API key remains safe during source control commits. Use environment variables in your production deployment environment to populate the ${FASTIO_API_KEY} placeholder securely at runtime.

To communicate securely with Fastio, configure a centralized WebClient bean that automatically injects your API key into every request header. This approach keeps your service layer clean and centralizes authentication logic.

Create a configuration class named FastIoClientConfig. Inject your base URL and API key properties, then build the WebClient instance.

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.WebClient;

@Configuration
public class FastIoClientConfig {

@Value("${fastio.api.base-url}")
    private String baseUrl;

@Value("${fastio.api.key}")
    private String apiKey;

@Bean
    public WebClient fastIoWebClient(WebClient.Builder builder) {
        return builder
            .baseUrl(baseUrl)
            .defaultHeader("Authorization", "Bearer " + apiKey)
            .build();
    }
}

This bean ensures all outgoing requests carry Authorization: Bearer {api_key}. Keep the trailing slash on https://api.fast.io/current/. Set Content-Type on each call: uploads use multipart/form-data, and most other POST bodies use application/x-www-form-urlencoded. JSON is for MCP tools/call payloads and the few REST routes that take nested or array parameters. Centralizing the Bearer header prevents unauthorized errors when you add new endpoint integrations later.

The best way to handle file uploads in Spring Boot with Fastio is to use Spring WebFlux's WebClient to stream multipart form data directly to the API. Streaming prevents memory exhaustion when processing large documents or media files.

When your backend receives a file upload from a client, you should pass that stream directly to Fastio rather than saving it temporarily to your local disk. This zero-I/O approach drastically improves application performance and reduces server storage costs.

Create a FastIoStorageService class to manage the transfer. Use the MultipartBodyBuilder to construct the payload dynamically.

import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.http.MediaType;
import org.springframework.http.client.MultipartBodyBuilder;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.BodyInserters;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@Service
public class FastIoStorageService {

private final WebClient webClient;

public FastIoStorageService(WebClient fastIoWebClient) {
        this.webClient = fastIoWebClient;
    }

public Mono<String> uploadFileStream(
        String filename,
        long size,
        String workspaceId,
        Flux<DataBuffer> fileStream) {
        MultipartBodyBuilder builder = new MultipartBodyBuilder();
        builder.part("name", filename);
        builder.part("size", String.valueOf(size));
        builder.part("action", "create");
        builder.part("instance_id", workspaceId);
        builder.part("folder_id", "root");
        builder.asyncPart("chunk", fileStream, DataBuffer.class)
               .filename(filename);

return webClient.post()
            .uri("https://api.fast.io/current/upload/")
            .contentType(MediaType.MULTIPART_FORM_DATA)
            .body(BodyInserters.fromMultipartData(builder.build()))
            .retrieve()
            .bodyToMono(String.class);
    }
}

A successful small upload returns HTTP 201 with {"result":true,"id":"<upload_id>","new_file_id":"<node_id>"}. Fastio automatically indexes the file immediately upon upload, so the document is searchable and available to Ripley and your other agents through the workspace context. You do not need to build a separate indexing job. Same-name upload into the same folder overwrites in place and keeps the old content as a recoverable version. The node_id stays stable.

For larger payloads, start a chunked session: POST the same form to https://api.fast.io/current/upload/ without chunk to receive an upload {id}, send each piece to POST /current/upload/{id}/chunk/?order=N&size=N (multipart field chunk), finish with POST /current/upload/{id}/complete/, then read GET /current/upload/{id}/details/?wait=60 for {session:{status,new_file_id}}. Up to 200 files of 4MB or less can go through POST /current/upload/batch/.

Add AI to Your Java Stack

Connect Spring Boot to Fastio workspaces, Ripley RAG, and 19 MCP tools.

Start 14-Day Trial

Fastio exposes multiple Model Context Protocol (MCP) tools that mirror its UI capabilities. Instead of building complex logic to manage agent states or search queries, you can trigger these built-in tools directly from your Java service.

To execute an MCP tool, POST a JSON-RPC tools/call to https://mcp.fast.io/mcp/key with the same Bearer header. Named mode exposes 19 tools, including upload, storage, find, ai, share, fileshare, and event. Code mode for headless agents exposes 6 tools: auth, upload, search, execute, room, and how-to. The ai tool (ask) is read-only RAG through Ripley and returns a cited answer. The following call imports a remote file into a workspace:

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"upload","arguments":{"action":"web-import","url":"https://example.com/report.pdf",
 "profile_type":"workspace","profile_id":"1234567890123456789"}}}

public Mono<String> importRemoteFile(String workspaceId, String sourceUrl) {
    String toolPayload = String.format(
        "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\","
        + "\"params\":{\"name\":\"upload\",\"arguments\":{\"action\":\"web-import\","
        + "\"url\":\"%s\",\"profile_type\":\"workspace\",\"profile_id\":\"%s\"}}}",
        sourceUrl, workspaceId);

return webClient.post()
        .uri("https://mcp.fast.io/mcp/key")
        .contentType(MediaType.APPLICATION_JSON)
        .bodyValue(toolPayload)
        .retrieve()
        .bodyToMono(String.class);
}

Your Java backend stays stateless. Fastio keeps the workspace files, audit log, and Ripley chats. Tool updates apply on the MCP server, so WebClient keeps posting the same tools/call shape.

Reactive Spring Boot services stay in sync with Fastio by reading the audit log and long-polling activity. GET /current/events/search/ returns workspace history. GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp} waits up to 95 seconds for the next event. When a new node_id appears, start Ripley with POST /current/workspace/{workspace_id}/ai/agent/ and send a message with POST /current/workspace/{workspace_id}/ai/agent/{chat_id}/message/.

Coordination Rooms emit room.message.created and room.participant.status_changed. Agents wait on a room with the MCP room tool (wait, messages, post).

public Mono<String> pollWorkspaceActivity(String entityId, String lastActivity) {
    return webClient.get()
        .uri("https://api.fast.io/current/activity/poll/{entityId}?wait=95&lastactivity={lastActivity}",
                entityId, lastActivity)
        .retrieve()
        .bodyToMono(String.class);
}

Pair the poll with GET /current/events/search/ when you need a broader audit trail. Once activity arrives, teammates and agents work from the same files, and Ripley can answer questions about the new document.

Deploying an API integration to production requires handling network instability and rate limits gracefully. When calling the Fastio API, wrap your WebClient calls with retry logic to recover from temporary connection drops.

Spring WebFlux provides native retry operators. You can append .retryWhen(Retry.backoff(multiple, Duration.ofSeconds(multiple))) to your Mono chains. This configuration attempts the request up to three times with exponential backoff if a transient error occurs. HTTP 429 with error code 1671 means you hit the rate limit. Back off until the x-ve-limit-expires header, then retry. Proper retry hygiene prevents a single dropped packet from failing a multi-step document transfer.

For more advanced resilience, consider integrating a library like Resilience4j. It allows you to configure circuit breakers that stop sending requests to Fastio if the service experiences an extended outage. This structural protection prevents your application threads from locking up while waiting for timeout exceptions.

Additionally, monitor the size of files passing through your upload endpoints. While Fastio supports massive files, your Spring Boot server still needs enough memory to buffer the network stream. Configure your application's spring.servlet.multipart.max-file-size property to match Fastio's limits. This ensures you reject oversized files at the gateway before initiating an API transfer, saving both bandwidth and processing time.