How to Implement the Fastio Semantic Search API

Building intelligent applications usually requires stitching together multiple tools. You deploy external storage for files, build pipelines to extract text, push everything through an embedding model, and index the vectors in a separate database. This setup introduces architectural complexity and latency. Fastio semantic search runs against workspace files natively. Upload a document to a workspace with intelligence enabled, and Fastio builds an AI summary and a meaning index. Query that index with GET https://api.fast.io/current/workspace/{workspace_id}/ai/search/, or run content search with GET https://api.fast.io/current/workspace/{workspace_id}/storage/search/?search_in=content. Content matches the AI summary and meaning index, not a raw scan of file bytes. You do not need any external vector infrastructure.

Moving to native meaning search changes how developers build. Instead of managing discrete services, your application talks to one workspace. Fewer moving parts means fewer bugs and no synchronization failures. Development teams get to market faster and spend less time on maintenance when building Retrieval-Augmented Generation workflows or knowledge retrieval systems. Skip the extraction pipelines and let Ripley, the built-in RAG agent, answer questions about documents after they are uploaded. Replacing custom storage and vector databases lets you query the meaning of files in the same workspace that holds the source of truth.

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

Before running a semantic search, configure your Fastio environment and get your API credentials. Authenticated calls go to https://api.fast.io/current/ over HTTPS. Trailing slashes are part of the path, so keep them. Workspace IDs are singular in the path (workspace/{workspace_id}). You need an active Fastio account and a workspace with intelligence enabled.

Authentication uses a Bearer token in the Authorization header. Create an API key in the UI under Settings > Devices & Agents > API Keys, or with POST https://api.fast.io/current/user/auth/key/. Store this key securely using your platform's secrets management system. Never hardcode credentials into your application source files. Every authenticated call sends Authorization: Bearer {api_key}.

Semantic search runs on the meaning index built by workspace intelligence. Enable Intelligence Mode on the workspace in the Fastio UI so uploaded files receive an AI summary and a meaning-based index.

Once intelligence is active, new uploads join that index. Content search matches the AI summary and meaning index, not a raw byte scan. To see what a given search actually received, read search_metadata.semantic_available on the response. That field reports whether the request used the meaning index.

Give Your AI Agents Persistent Storage

Start building with Fastio semantic search. Ripley answers questions against workspace files, and the MCP server exposes 19 named tools for agents.

Start 14-Day Trial

Getting the request right is the most important step for finding accurate results. Semantic search is a GET. Call GET https://api.fast.io/current/workspace/{workspace_id}/ai/search/ for the semantic route. Call GET https://api.fast.io/current/workspace/{workspace_id}/storage/search/ for storage search.

On storage search, set search_in to filename, content, or both (the default is both). search_in=content matches the AI summary and meaning index, not a raw byte scan. Pair filename matching with name_match values auto, exact, prefix, contains, or glob. You can also send case_sensitive and details=true.

Here are the two request shapes:

curl -X GET "https://api.fast.io/current/workspace/{workspace_id}/ai/search/" \
  -H "Authorization: Bearer {api_key}"

curl -X GET "https://api.fast.io/current/workspace/{workspace_id}/storage/search/?search_in=content" \
  -H "Authorization: Bearer {api_key}"

Use search_in=both when you want meaning matches together with filename matching. Unified search lives at GET https://api.fast.io/current/workspace/{workspace_id}/search/.

When a search executes, read search_metadata.semantic_available to see whether that request received the meaning index. That flag is how you confirm the semantic path actually ran.

Keep the source file in the same workspace so follow-up reads stay on the real node. File details are GET https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/details/. Download bytes with GET https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/read/. Ripley can turn a question into a cited answer with POST https://api.fast.io/current/workspace/{workspace_id}/ai/agent/, then POST https://api.fast.io/current/workspace/{workspace_id}/ai/agent/{chat_id}/message/. Agents can also call the MCP ai tool with action ask (profile_type required).

Integrating semantic search into a Node.js application is straightforward. Use the native Fetch API against the real GET routes. For server-side implementations, you construct the URL, send the Bearer token, and parse the JSON. This example wraps the semantic route inside an asynchronous function.

async function executeSemanticSearch(workspaceId, apiKey) {
  const url = `https://api.fast.io/current/workspace/${workspaceId}/ai/search/`;

const response = await fetch(url, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${apiKey}`
    }
  });

if (!response.ok) {
    throw new Error(`Search failed: ${response.status}`);
  }

return response.json();
}

This function accepts the target workspace identifier and your API key. It calls GET https://api.fast.io/current/workspace/{workspace_id}/ai/search/ and returns the parsed body. For content search against the AI summary and meaning index, GET https://api.fast.io/current/workspace/{workspace_id}/storage/search/?search_in=content with the same Authorization header. If the response is HTTP 429, back off until the x-ve-limit-expires header.

Python dominates AI and data engineering, making it a common environment for Fastio integrations. Using the requests library, you can build search into Python backends, CLI tools, or Jupyter notebooks. The implementation pattern mirrors the Node.js GET.

import requests

def execute_semantic_search(workspace_id: str, api_key: str):
    url = f"https://api.fast.io/current/workspace/{workspace_id}/ai/search/"
    headers = {
        "Authorization": f"Bearer {api_key}"
    }
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

The raise_for_status() method handles HTTP errors without extra validation boilerplate. For content search, GET https://api.fast.io/current/workspace/{workspace_id}/storage/search/?search_in=content. You can drop the REST call into a backend, or attach Fastio MCP for an OpenClaw, LangChain, or similar agent. Streamable HTTP is https://mcp.fast.io/mcp (or https://mcp.fast.io/mcp/key with a Bearer header). A JSON-RPC search looks like this:

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"storage","arguments":{"action":"search","profile_type":"workspace"}}}

Ripley answers a question through the MCP ai tool with action ask (profile_type required). The synchronous requests library works fine for most backends. For high-concurrency applications, you might want to use aiohttp or httpx instead.

Pure semantic search works well for finding conceptual connections, but real-world applications often need hard filename constraints. You might want documents about a topic whose names follow a prefix or glob. Fastio combines those channels on the storage search route.

Set search_in=content for the meaning index. Set search_in=filename and pick a name_match of auto, exact, prefix, contains, or glob when the filename is the constraint. Set search_in=both when you want both channels in one request. Unified search is GET https://api.fast.io/current/workspace/{workspace_id}/search/. Structured metadata search is GET https://api.fast.io/current/workspace/{workspace_id}/metadata/search/.

This hybrid pattern keeps RAG context on files that match both meaning and name. Combining the meaning index with filename matching improves precision without standing up a separate vector database.

When deploying the API in production, you need to account for system constraints. The API uses rate limiting to keep the platform stable. If your application sends too many requests, the gateway returns HTTP 429 with error code 1671. Back off until the x-ve-limit-expires header.

Add retry handling that waits for that header before sending the next request. Increase the delay if 429 responses continue.

When you list a folder with GET https://api.fast.io/current/workspace/{workspace_id}/storage/{parent_id}/list/, pagination is cursor-based. Query params are sort_by=name|updated|created|type (default name), sort_dir=asc|desc (default asc), page_size=100|250|500 (default 100), and cursor. The response carries pagination.has_more, pagination.next_cursor, and pagination.page_size. Rely on has_more and next_cursor, not page fullness. For meaning search, start with GET https://api.fast.io/current/workspace/{workspace_id}/ai/search/ or GET https://api.fast.io/current/workspace/{workspace_id}/storage/search/?search_in=content and read search_metadata.semantic_available.

The quality of your search results depends on how you phrase the question you send toward the meaning index. Traditional systems rely on keyword matching and boolean operators. Meaning search matches the AI summary and the meaning-based index. To get the most out of this architecture, provide queries with plenty of context and descriptive detail.

Do not submit single-word queries or disjointed keywords. Write complete sentences or descriptive phrases instead. For example, instead of querying for 'onboarding', ask 'What is the standard procedure for onboarding a new software engineer?'. The longer question gives the meaning index richer context. If you are building an application where users type the input, consider adding a query expansion layer. You can use a fast LLM to rewrite a user's brief input into a detailed semantic question before you call GET https://api.fast.io/current/workspace/{workspace_id}/ai/search/. This translation step often yields much better retrieval results.

Developers run into a few common challenges during the implementation phase. The most frequent issue is querying before the meaning index is available for those files. After you upload, call search and read search_metadata.semantic_available to see what that request actually got.

Authentication failures return 1650 Auth Invalid. Access problems return 1680 Access Denied. Confirm the Authorization: Bearer header and that the key was created under Settings > Devices & Agents > API Keys. Invalid input returns 1605. Rate limits return HTTP 429 with error code 1671; wait for x-ve-limit-expires.

If results look like filename matches only, set search_in=content or call GET https://api.fast.io/current/workspace/{workspace_id}/ai/search/ and check search_metadata.semantic_available again. You can also watch workspace activity with GET https://api.fast.io/current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}, or read the audit log at GET https://api.fast.io/current/events/search/.