The Retrieval API provides semantic search capabilities across your indexed documents, enabling precise information retrieval with citations and source tracking.
Semantic Search Perform semantic search across your entire knowledge base using natural language queries.
Endpoint POST /api/retrieval/searchRequest Body Natural language search query
Maximum number of results to return (1-100)
Filter results by document metadata Limit search to specific documents
Filter by document creation date
Search strategy: semantic, keyword, or hybrid
Include source citations in results
Response Array of search results ordered by relevance Unique identifier for the text chunk
The relevant text content
Source document identifier
Page number in source document (if applicable)
Additional metadata from the source document
Total number of matching results
Query execution time in milliseconds
Example curl -X POST https://api.polyvia.ai/api/retrieval/search \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "What are the security best practices?", "limit": 5, "search_mode": "hybrid", "include_citations": true }'
{ "results" : [ { "chunk_id" : "chunk_abc123" , "content" : "Security best practices include implementing multi-factor authentication, encrypting data at rest and in transit, and conducting regular security audits." , "score" : 0.94 , "document_id" : "doc_xyz789" , "document_name" : "Security Guidelines 2024" , "page_number" : 12 , "metadata" : { "tags" : [ "security" , "compliance" ], "author" : "Security Team" } } ], "total_results" : 15 , "query_time_ms" : 127 }
Hybrid Search Combine semantic and keyword search for optimal results.
How It Works Hybrid search leverages both:
Semantic search : Understands meaning and context using vector embeddingsKeyword search : Matches exact terms and phrases using BM25 algorithm
Results are ranked using a weighted combination of both scores.
Configuration Weight for semantic search (0-1)
Weight for keyword search (0-1)
Example { "query" : "machine learning algorithms" , "search_mode" : "hybrid" , "semantic_weight" : 0.6 , "keyword_weight" : 0.4 }
Retrieve by Document Retrieve specific chunks from a document with optional filtering.
Endpoint GET /api/retrieval/document/{document_id}Path Parameters Query Parameters Retrieve chunks from a specific page
Example curl "https://api.polyvia.ai/api/retrieval/document/doc_xyz789?page=5&limit=10" \ -H "Authorization: Bearer YOUR_API_KEY"
Advanced Filtering Filter by Date Range { "query" : "quarterly reports" , "filters" : { "date_range" : { "start" : "2024-01-01" , "end" : "2024-03-31" } } }
{ "query" : "compliance requirements" , "filters" : { "tags" : [ "legal" , "compliance" ] } }
Filter by Multiple Criteria { "query" : "financial analysis" , "filters" : { "tags" : [ "finance" ], "document_ids" : [ "doc_123" , "doc_456" ], "date_range" : { "start" : "2024-01-01" } } }
Search Modes Comparison
Semantic Best for:
Conceptual queries
Paraphrased questions
Cross-lingual search
Example: “How to improve customer satisfaction”
Keyword Best for:
Exact term matching
Technical identifiers
Product codes
Example: “SKU-12345”
Hybrid Best for:
General queries
Mixed intent
Balanced precision/recall
Example: “Q4 2024 revenue report”Ranking and Relevance Results are ranked using multiple signals:
Semantic similarity : Cosine similarity between query and document embeddingsKeyword match : BM25 score for term frequency and document lengthRecency : Newer documents receive a slight boostSource authority : Documents with more citations rank higher
Use semantic mode for conceptual questions and keyword mode for exact matches. hybrid mode provides the best balance for most use cases.
Rate Limits
Free tier : 100 queries per dayPro tier : 1,000 queries per dayEnterprise : Unlimited queries
Large result sets (limit > 50) count as multiple queries against your quota.
