Search API

Semantic search across ingested documents using vector similarity.

Overview

The Search API enables:

• Semantic search - Find documents by meaning, not just keywords
• Search with reranking - Two-stage retrieval with Cohere rerank
• Filtered search - Filter by classification, metadata, or document IDs
• RAG context retrieval - Get relevant chunks for LLM prompts

Endpoints

Method	Endpoint	Description
POST	/v1/data/search	Semantic search
POST	/v1/data/search-and-rerank	Search with Cohere reranking

Semantic Search

Find relevant document chunks using vector similarity (pgvector).

POST /v1/data/search

Request

cURL

curl -X POST https://api.gateflow.ai/v1/data/search \
  -H "Authorization: Bearer gw_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the refund policy?",
    "top_k": 5,
    "min_similarity": 0.7
  }'

Python

import requests

response = requests.post(
    "https://api.gateflow.ai/v1/data/search",
    headers={
        "Authorization": "Bearer gw_prod_...",
        "Content-Type": "application/json"
    },
    json={
        "query": "What is the refund policy?",
        "top_k": 5,
        "min_similarity": 0.7
    }
)

TypeScript

const response = await fetch('https://api.gateflow.ai/v1/data/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_prod_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'What is the refund policy?',
    top_k: 5,
    min_similarity: 0.7,
  }),
});

Parameters

Parameter	Type	Required	Default	Description
query	string	Yes	-	Search query
top_k	integer	No	10	Maximum results to return
document_ids	array	No	null	Filter to specific documents
data_classifications	array	No	null	Filter by classification levels
metadata_filter	object	No	null	Filter by custom metadata
min_similarity	number	No	0.0	Minimum similarity score (0-1)

Response

{
  "results": [
    {
      "chunk_id": "550e8400-e29b-41d4-a716-446655440001",
      "document_id": "550e8400-e29b-41d4-a716-446655440000",
      "document_name": "Company Policies",
      "content": "Our refund policy allows customers to return products within 30 days...",
      "similarity_score": 0.92,
      "rerank_score": null,
      "metadata": {
        "department": "legal"
      },
      "page_number": 5,
      "section_header": "Refund Policy"
    }
  ],
  "total_chunks_searched": 1500,
  "query_embedding_time_ms": 45,
  "search_time_ms": 12,
  "total_time_ms": 57,
  "cost_usd": 0.00002
}

Filtering Examples

Filter by document IDs:

{
  "query": "refund policy",
  "document_ids": ["doc-123", "doc-456"]
}

Filter by classification:

{
  "query": "sensitive data",
  "data_classifications": ["internal", "confidential"]
}

Filter by metadata:

{
  "query": "policy update",
  "metadata_filter": {
    "department": "legal",
    "year": 2024
  }
}

Search and Rerank

Two-stage search: initial vector similarity followed by Cohere reranking for higher precision.

POST /v1/data/search-and-rerank

Request

{
  "query": "What is the return policy for electronics?",
  "top_k": 20,
  "top_n": 5,
  "rerank_model": "rerank-english-v3.0"
}

Parameters

Parameter	Type	Required	Default	Description
query	string	Yes	-	Search query
top_k	integer	No	20	Initial results from vector search
top_n	integer	No	5	Final results after reranking
document_ids	array	No	null	Filter to specific documents
data_classifications	array	No	null	Filter by classification levels
metadata_filter	object	No	null	Filter by custom metadata
rerank_model	string	No	rerank-english-v3.0	Cohere rerank model

Available Rerank Models

Model	Languages	Use Case
rerank-english-v3.0	English	English documents
rerank-multilingual-v3.0	100+	Multilingual documents
rerank-english-v2.0	English	Legacy support

Response

{
  "results": [
    {
      "chunk_id": "chunk-001",
      "document_id": "doc-123",
      "document_name": "Return Policy Guide",
      "content": "Electronics can be returned within 30 days...",
      "similarity_score": 0.85,
      "rerank_score": 0.94,
      "page_number": 3,
      "section_header": "Electronics Returns"
    }
  ],
  "initial_results_count": 20,
  "reranked_results_count": 5,
  "query_embedding_time_ms": 45,
  "search_time_ms": 12,
  "rerank_time_ms": 150,
  "total_time_ms": 207,
  "embedding_cost_usd": 0.00002,
  "rerank_cost_usd": 0.0001,
  "total_cost_usd": 0.00012
}

Use with RAG

Python Example

import openai
import requests

# 1. Search for relevant context
search_response = requests.post(
    "https://api.gateflow.ai/v1/data/search",
    headers={
        "Authorization": "Bearer gw_prod_...",
        "Content-Type": "application/json"
    },
    json={
        "query": "What is the refund policy?",
        "top_k": 3
    }
).json()

# 2. Build context from results
context = "\n\n".join([
    f"[{r['document_name']}]: {r['content']}"
    for r in search_response["results"]
])

# 3. Send to LLM with context
client = openai.OpenAI(
    base_url="https://api.gateflow.ai/v1",
    api_key="gw_prod_..."
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "system",
            "content": f"Answer based on this context:\n\n{context}"
        },
        {
            "role": "user",
            "content": "What is the refund policy?"
        }
    ]
)

print(response.choices[0].message.content)

Pricing

Operation	Cost
Query embedding	~$0.00002 per query
Vector search	Included
Cohere rerank	~$0.10 per 1000 searches

Error Codes

Code	Description
400	Invalid query or parameters
401	Invalid API key
404	Document not found
500	Search failed

See Also

• Documents API - Manage documents
• Semantic Search - Search concepts
• RAG Injection - RAG patterns