How to Implement Semantic Search with Fastio API

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.

• Mastering Google Drive API Search Queries: Syntax, Filtering, and RAG LimitationsThe Google Drive API files.list endpoint filters objects through a specialized query parameter called q, supporting...
• How to Implement the Fastio Semantic Search APIThe Fastio Semantic Search API enables developers to execute vector-based searches against workspace files without...
• Google Drive Indexing for AI Agents: Scalable File Search ArchitectureGoogle Drive indexing for AI agents structures cloud drive hierarchies into searchable workspace chunks, allowing...
• How to Connect Perplexity to Google Drive for Agentic SearchConnecting Perplexity to Google Drive lets research teams query private documents alongside live web sources. Direct...
• How to Integrate Fastio API with Semantic Kernel WorkflowsIntegrating Fastio API with Semantic Kernel workflows gives .NET AI agents persistent file storage, secure RAG, and...
• Fastio API Presigned URLs Implementation GuideFastio API presigned URLs allow your applications to grant secure, time-limited, direct access to files without...

More on this subject: Agent Integrations and APIs (191 guides)

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/. Get a JWT from GET /current/user/auth/ with HTTP Basic auth, or create an API key with POST /current/user/auth/key/; send either as a Bearer token.

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

curl -X POST https://api.fast.io/current/user/ \
  -d "first_name=Agent" \
  -d "last_name=Search" \
  -d "email_address=agent@example.com" \
  -d "password=$PASSWORD" \
  -d "tos_agree=true" \
  -d "agent=true"

Verify email, then create an organization:

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

A new organization must select a paid plan before it can create workspaces or use resources.

Workspaces hold files. Create one:

curl -X POST https://api.fast.io/current/org/{org_id}/create/workspace/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d "folder_name=semantic-search-ws" \
  -d "name=Semantic Search Workspace" \
  -d "perm_join=Member or above" \
  -d "perm_member_manage=Admin or above"

Intelligence Mode, which auto-indexes files, is on by default for a new workspace. To turn it on later, POST /current/workspace/{workspace_id}/update/ with intelligence=true.

Uploaded files are then indexed automatically and reach the indexed AI state.

Check status: GET /current/workspace/{workspace_id}/storage/root/list/ and read each node's ai.state field.

Build Semantic Search Now

Get started with Fastio intelligent workspaces. Explore plans and the 14-day Business Trial at /pricing/.

Start 14-Day Trial

Chunked uploads for large files. First create an upload session:

curl -X POST https://api.fast.io/current/upload/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d "name=document.pdf" \
  -d "size=10485760" \
  -d "action=create" \
  -d "instance_id={workspace_id}" \
  -d "folder_id=root"

Upload chunks to /current/upload/{upload_id}/chunk/, then complete with /current/upload/{upload_id}/complete/.

Or import from URL: POST /current/web_upload/ with source_url, file_name, profile_id (the workspace ID) and profile_type=workspace.

Wait for the file's ai.state to reach indexed. Indexed files support semantic queries.

Use an AI chat for semantic search with cited answers. With no files attached, the agent can search the whole indexed workspace.

Create chat:

curl -X POST https://api.fast.io/current/workspace/{workspace_id}/ai/agent/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d "question=Find contracts mentioning indemnity from last quarter"

The response returns thread.thread_id (the chat ID) and turn.turn_id (the message ID). Long-poll GET /current/activity/poll/{workspace_id}?wait=95 until the ai_chat:{chat_id} key changes, then GET /current/workspace/{workspace_id}/ai/agent/{chat_id}/message/{message_id}/details/.

The answer's result.citations list each cited file's nodeId with page and snippet entries.

To focus a chat on one folder, attach it as a folder reference item in the references array.

Numbered API flow:

1. POST /ai/agent/ to create the chat.
2. Long-poll /activity/poll/{workspace_id}, then GET .../message/{message_id}/details/.
3. Parse citations for relevant files.

Permissions are enforced automatically. Queries respect member roles.

On /storage/search/, scope to a folder: folders_scope={folder_node_id}:2.

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

For shares: use the /current/share/{share_id}/ versions of the search and AI routes.

Edge case: files whose ai.state is not indexed are left out of RAG.

Test with small set first.

• Monitor credits: GET /current/org/{org_id}/billing/usage/limits/credits/.
• Poll activity: /activity/poll/{entity_id}.
• Handle errors: check the HTTP status, such as 429 for rate limits.
• Scale: Poll the realtime activity feed or use the WebSocket events feed.

Common issues:

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