How to Build Agent Workspaces: Fastio API Quickstart

The Fastio API lets developers programmatically create and manage intelligent agent workspaces. Most storage API tutorials ignore agentic frameworks and RAG integrations. Traditional cloud storage platforms treat files as passive objects. When you upload a PDF to a standard bucket, it just sits there until someone downloads it. This creates bottlenecks for autonomous agents. They need active knowledge systems, not static archives.

Fastio acts as an active environment where humans and AI models collaborate directly. A workspace built through the API becomes the persistent coordination layer for your intelligent systems. Files you upload are available to Ripley, the built-in RAG agent, and to semantic search. You can add agents and humans as workspace members, then review every change in the audit log.

Get an API key in Settings > Devices & Agents > API Keys, or create one with POST /current/user/auth/key/. Authenticated calls send Authorization: Bearer {api_key} to https://api.fast.io/current/. From there you can create workspaces, invite members, import files from a URL, and ask Ripley for cited answers. Building on an architecture designed for AI workflows helps teams ship faster. It also removes the maintenance overhead of fragmented microservices.

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

Authentication requires a Bearer token. Create an API key in Settings > Devices & Agents > API Keys, or with POST /current/user/auth/key/. This token grants your application programmatic access to workspace resources. These tokens carry broad permissions, so store them securely as environment variables instead of hardcoding them into source files.

To verify your connection, list the workspaces you can access. Here is a curl request for your first API call:

curl -X GET "https://api.fast.io/current/workspaces/all/" \
  -H "Authorization: Bearer YOUR_API_KEY"

If the token is valid, the server returns your workspaces. Profile IDs are 19-digit numeric strings. Keep the trailing slashes on every path. For a production application, parse this response to see whether the target workspace already exists.

Error handling at this stage is simple. Error code 1650 means the token is invalid. Error code 1680 means access is denied. HTTP 429 with error code 1671 means you are rate limited; back off until the x-ve-limit-expires header. Implementing retry logic and clear error logging during this initial setup will save debugging time as your architecture scales.

Developers often spend days configuring vector databases and chunking strategies before an agent can answer simple questions about a document. Fastio handles this with workspace intelligence. Ripley, the built-in RAG agent, answers questions against the files in the workspace and returns cited answers.

Create a workspace with POST /current/org/{org_id}/create/workspace/. Then start a Ripley chat with POST /current/workspace/{workspace_id}/ai/agent/ and send a message with POST /current/workspace/{workspace_id}/ai/agent/{chat_id}/message/. Semantic search is available at GET /current/workspace/{workspace_id}/storage/search/.

Once the workspace exists, you can upload PDF reports, source code, or text logs. As soon as the files are in the workspace, your agents can search by meaning. They no longer need to process the whole document locally. Instead, they can ask targeted questions and receive cited answers from Ripley.

This architecture reduces computational overhead and minimizes token usage. The agent only processes the relevant material returned by the platform. You can set up an intelligent workspace in under five minutes and start feeding it domain-specific knowledge.

Intelligent systems rely on fresh data to remain accurate. You can stream local files through the API using multipart form data, and you can import a file from a URL so the platform pulls it server-side.

A small local file is one request to POST /current/upload/. Send multipart fields name, size, chunk (the bytes), action=create, instance_id (the workspace id), and folder_id=root. A successful small upload returns HTTP 201 with result, id, and new_file_id. 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 a file that already lives at a URL, use server-side import:

curl -X POST "https://api.fast.io/current/web_upload/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "source_url=https://example.com/report.pdf" \
  -d "file_name=report.pdf" \
  -d "profile_id=1234567890123456789" \
  -d "profile_type=workspace" \
  -d "folder_id=root"

The backend fetches the file into the workspace folder you named. Watch for the new node with GET /current/events/search/ or long-poll GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}. Your agent can wait on that activity, then ask Ripley about the imported file.

Give Your AI Agents Persistent Storage

Create an API key, list your workspaces, and start uploading into a workspace with built-in RAG. Start building with the Fastio API today.

Start 14-Day Trial

The Model Context Protocol standardizes how language models interact with external environments. Rather than writing custom integration code for every operation, you can connect your agent directly to the platform's toolset.

Official guidance is to use the MCP server for agent integrations. Connect over Streamable HTTP at https://mcp.fast.io/mcp (use https://mcp.fast.io/mcp/key with a Bearer header; legacy SSE is https://mcp.fast.io/sse). Named mode exposes 19 consolidated tools, including auth, workspace, share, fileshare, storage, upload, download, ai, find, event, member, and how-to.

For developers using OpenClaw, you can install the skill with a single command: clawhub install dbalve/fast-io. This package gives your model file management, search, and Ripley through those tools.

Agents can list folders, create Send, Receive, or Exchange shares, search document contents, and ask Ripley for a cited answer. A tools/call looks like this:

{"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"}}}

Because the tools execute within the Fastio infrastructure, they inherit the permission model of the workspace. Your agent stays inside its assigned workspace or share, which reduces the risk of data leakage.

Production environments rarely feature a single AI agent operating in isolation. Teams deploy multiple specialized models working in parallel. Concurrent writes introduce the risk of race conditions, where two agents attempt to overwrite the same document at the same time.

Before an agent modifies a file or folder, it acquires a lock on that storage node. While it holds the lock, it sends a heartbeat. When the write is done, it releases the lock.

curl -X POST "https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/lock/" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/lock/heartbeat/" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X DELETE "https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/lock/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Locks apply to storage nodes (files and folders). By coordinating writes this way, multi-agent systems stay orderly under load. You can deploy multiple researchers, writers, and analysts into the same directory without overlapping writes on the same node.

Many developer agencies build intelligent workspaces on behalf of external clients. A common workflow involves an AI agent creating an organization, building a directory structure, populating it with targeted research, and then inviting the client to take over day-to-day use.

Create the organization with POST /current/org/create/. Create the workspace with POST /current/org/{org_id}/create/workspace/. Add the client with POST /current/workspace/{workspace_id}/members/{email_or_user_id}/. List members with GET /current/workspace/{workspace_id}/members/list/.

For a branded handoff, create a Send, Receive, or Exchange share with POST /current/workspace/{workspace_id}/create/share/, or a durable single-file link with POST /current/workspace/{workspace_id}/create/fileshare/. The client opens a branded portal instead of a raw dump of files.

This workflow is valuable for service providers who package autonomous agents as specialized products. The developer focuses on building the intelligence layer and configuring the MCP tools. The client joins as a member or reviews the work through a share. Audit logs stay available through GET /current/events/search/.

Active workspaces generate constant event traffic. Files are updated, agents acquire locks, and humans leave comments on shared assets. Tight polling loops waste resources and delay agent responses.

For file and workspace activity, search the audit log with GET /current/events/search/, or long-poll with GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}. Your architecture can wait on those endpoints and wake agents only when new activity appears.

curl -X GET "https://api.fast.io/current/events/search/" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET "https://api.fast.io/current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

For example, an analysis agent can stay idle until activity/poll or events/search shows a new PDF in the workspace. Combined with the audit log, teams can see exactly how and when their models interact with the workspace. This establishes accountability for every action taken by the software.