# How to Implement the Fastio Semantic Search API

The Fastio Semantic Search API enables developers to execute vector-based searches against workspace files without managing an external vector database. This guide covers the complete implementation process, from authenticating your requests to formatting queries and handling the response payload. By replacing custom storage and vector database stacks, your team can execute precise meaning-based queries across entire workspaces in milliseconds.

Source: https://fast.io/resources/fastio-semantic-search-api-implementation/
Last reviewed: 2026-02-24

## How to implement Fastio semantic search API implementation guide reliably

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](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/).

## What to check before scaling Fastio semantic search API implementation guide

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}`.

## Enabling Intelligence Mode on Your Workspace

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.

## The Semantic Search API Request Payload

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/.

## The Semantic Search API Response Payload

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).

## Implementing Search in Node.js

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.

```javascript
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.

## Implementing Search in Python

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.

```python
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:

```json
{"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.

## Hybrid Search: Combining Semantics with Metadata

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.

## Handling Rate Limits and Pagination

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`.

## Best Practices for Query Formulation

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.

## Troubleshooting Implementation Issues

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/.

## Frequently asked questions

### How do I use Fastio for semantic search?

Enable workspace intelligence, then send GET https://api.fast.io/current/workspace/{workspace_id}/ai/search/. Content search is GET /current/workspace/{workspace_id}/storage/search/ with search_in=content. Content matches the AI summary and meaning index, so you do not need an external vector database.

### Does Fastio API support vector search?

Yes. Fastio provides native semantic search at GET /current/workspace/{workspace_id}/ai/search/ and content search at GET /current/workspace/{workspace_id}/storage/search/?search_in=content. Workspace intelligence builds the meaning index so you can query files without a separate vector database.

### What is the maximum file size supported for semantic indexing?

Upload with POST /current/upload/ using multipart fields name, size, chunk, action=create, instance_id, and folder_id. Larger files use the chunked session on the same /current/upload/ route. Once a file is in an intelligence-enabled workspace, search it with GET /current/workspace/{workspace_id}/ai/search/ or GET /current/workspace/{workspace_id}/storage/search/?search_in=content.

### Can I filter semantic search results by file type?

Yes. On GET /current/workspace/{workspace_id}/storage/search/ set search_in to filename, content, or both, and use name_match values auto, exact, prefix, contains, or glob. search_in=content matches the meaning index. Combine filename matching with meaning search using search_in=both.

### How long does it take for new files to become searchable?

After upload returns 201 with new_file_id, query GET /current/workspace/{workspace_id}/ai/search/ or GET /current/workspace/{workspace_id}/storage/search/?search_in=content. Read search_metadata.semantic_available on the response to see what that request actually received.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.