# How to Implement Semantic Search with Fastio API

How to implement semantic search with Fastio API starts with enabling Intelligence Mode on a workspace. This auto-indexes files for natural language queries, going beyond keyword matches to retrieve contextually relevant content. Agents can then use the AI chat endpoints to search workspaces, respecting file permissions automatically. Fastio handles vector embeddings internally, so developers focus on API calls rather than infrastructure.

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

## What Is Semantic Search in Fastio?

Semantic search in Fastio finds files by meaning, not exact keywords. For example, query "Q3 contracts with Acme" to retrieve relevant documents even without those words in filenames.

It relies on Intelligence Mode, which indexes files with vector embeddings for RAG. Queries go through AI chat endpoints that retrieve and cite sources. This improves retrieval accuracy for agent workflows.

Unlike keyword search, semantic search understands context. It combines full-text indexing with AI to handle synonyms, intent, and relationships.

## Prerequisites and Account Setup

Start by creating a Fastio account (see /pricing/ for plans and the 14-day Business Trial).

Use the API base URL `https://api.fast.io/current/`. Authenticate with JWT or API keys via `/current/user/auth/`.

Code example for agent signup (adapt for your LLM):

```bash
curl -X POST https://api.fast.io/current/user/ \\
  -d "first_name=Agent" \\
  -d "last_name=Search" \\
  -d "email=agent@example.com" \\
  -d "password=securepass123"
```

Verify email, then create an organization:

```bash
curl -X POST https://api.fast.io/current/org/ \\
  -H "Authorization: Bearer $JWT_TOKEN" \\
  -d "name=My Agent Org" \\
  -d "domain=agent-search"
```

## Create and Configure a Workspace

Workspaces hold files. Create one:

```bash
curl -X POST https://api.fast.io/current/org/{org_id}/workspace/ \\
  -H "Authorization: Bearer $JWT_TOKEN" \\
  -d "folder_name=semantic-search-ws" \\
  -d "name=Semantic Search Workspace"
```

Enable Intelligence Mode for auto-indexing:

1. POST `/current/workspace/{workspace_id}/intelligence/` with `enabled=true`.

Files uploaded now get indexed automatically (`ai_state: ready`).

Check status: GET `/current/workspace/{workspace_id}/storage/root/` for `ai` fields on nodes.

## Upload Files for Indexing

Chunked uploads for large files. First initiate:

```bash
curl -X POST https://api.fast.io/current/workspace/{workspace_id}/upload/initiate/ \\
  -H "Authorization: Bearer $JWT_TOKEN" \\
  -d "filename=document.pdf" \\
  -d "size=10485760"
```

Upload chunks, complete with `/upload/complete/`.

Or import from URL: POST `/current/workspace/{workspace_id}/upload/web/` with `source_url`.

Wait for `ai_state: ready` in storage details. Indexed files support semantic queries.

## Execute Semantic Searches via API

Use `chat_with_files` for semantic search. Default scope is full workspace.

Create chat:

```bash
curl -X POST https://api.fast.io/current/ai/chat/ \\
  -H "Authorization: Bearer $JWT_TOKEN" \\
  -d "type=chat_with_files" \\
  -d "query_text=Find contracts mentioning indemnity from last quarter" \\
  -d "workspace_id={workspace_id}"
```

Poll message: GET `/current/ai/message/{message_id}/`.

Response includes citations with `nodeId`, `page`, `snippet`.

For scoped: `folders_scope=nodeId:3` limits to subfolders.

Numbered API flow:
1. POST `/ai/chat/` create.
2. GET `/ai/message/{id}/` poll.
3. Parse citations for relevant files.

## Scoped Searches and Permissions

Permissions are enforced automatically. Queries respect member roles.

Scope to folder: `folders_scope={folder_node_id}:2`.

Multi-file: `files_scope={node1}:{version1},{node2}:{version2}`.

For shares: Use `context_type=share` endpoints.

Edge case: Non-indexed files (`ai_state != ready`) ignored in RAG.

Test with small set first.

## Best Practices and Troubleshooting

- Monitor credits: GET `/org/{org_id}/billing/usage/`.
- Poll activity: `/activity/poll/{entity_id}`.
- Handle errors: Check `error.code` like 1667 for limits.
- Scale: Poll the realtime activity feed or use the WebSocket events feed.

Common issues:
| Issue | Fix |
|-------|-----|
| No results | Ensure intelligence on, files ready |
| 402 | Transfer org or upgrade |
| 429 | Respect rate limits |

Integrate with MCP for a consolidated MCP toolset in agent frameworks.

## Frequently asked questions

### How do I query Fastio via API?

Authenticate with JWT, use `/ai/chat/` for semantic queries or `/storage/search/` for keyword. Base: https://api.fast.io/current/.

### Does Fastio support vector embeddings?

Yes, Intelligence Mode auto-generates embeddings for RAG. No external DB needed; query via chat endpoints.

### Does Fastio offer a trial or free tier?

Fastio does not offer a free tier. It provides a 14-day Business Trial requiring a credit card, with plans starting at Starter ($29/mo); see /pricing/.

### How to handle large files?

Chunked uploads up to 1 GB. Previews and indexing automatic.

### Can agents collaborate with humans?

Yes, invite via members API. Shared workspaces with real-time presence.

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