Search API Reference
Learn about the search endpoints and how to find relevant documents in your namespaces.
RAGaaS provides both semantic and hybrid search capabilities to help you find the most relevant documents.
POST/v1/search
Semantic Search
Search for relevant documents using semantic search.
Authorization
- Name
Authorization*- Type
- string
- Description
- Bearer token authentication. Include your API key as
Bearer your_api_key
Request Body
- Name
query*- Type
- string
- Description
- The search query to find relevant documents
- Name
namespaceId*- Type
- string
- Description
- ID of the namespace to search in
- Name
topK- Type
- number(optional)
- Description
- Number of results to return (1-100)
- Name
scoreThreshold- Type
- number(optional)
- Description
- Minimum similarity score threshold (0-1)
- Name
filter- Type
- object(optional)
- Description
- Filter configuration for the search results
- Name
metadata- Type
- object(optional)
- Description
- Metadata filters to apply on the search results
- Name
searchType- Type
- enum<string>(optional)
- Description
- Type of search to performAvailable options:
SEMANTIC
Request
POST
/v1/searchcurl -X POST https://api.ragaas.dev/v1/search \
-H "Authorization: Bearer $RAGAAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "How to implement authentication?",
"namespaceId": "ns_123",
"topK": 5,
"scoreThreshold": 0.7,
"filter": {
"metadata": {
"category": "security",
"status": "published"
}
},
"searchType": "SEMANTIC"
}'
Response Body
- Name
success*- Type
- boolean
- Description
- Indicates whether the request is successful or not. This is always true for success responses.
- Name
message*- Type
- string
- Description
- Human readable message mentioning the result of the request
- Name
data*- Type
- object
- Description
- Data returned from the API.
- Name
results*- Type
- array<object>
- Description
- List of search results
- Name
content*- Type
- string
- Description
- The matched content from the document
- Name
score*- Type
- number
- Description
- Similarity score of the match (0-1)
- Name
metadata*- Type
- object
- Description
- Metadata associated with the document
- Name
id*- Type
- string
- Description
- Unique identifier of the document
- Name
source*- Type
- string
- Description
- Source of the document
- Name
type*- Type
- string
- Description
- Type of the document
Response
POST
/v1/search{
"success": true,
"message": "Search completed successfully",
"data": {
"results": [
{
"content": "To implement authentication, first configure your API key...",
"score": 0.92,
"metadata": {
"id": "doc_123",
"source": "authentication-guide.md",
"type": "TEXT"
}
},
{
"content": "Authentication can be implemented using JWT tokens...",
"score": 0.85,
"metadata": {
"id": "doc_124",
"source": "security-best-practices.md",
"type": "TEXT"
}
}
]
}
}
POST/v1/search/hybrid
Hybrid Search
Search for relevant documents using hybrid search (semantic + keyword).
Authorization
- Name
Authorization*- Type
- string
- Description
- Bearer token authentication. Include your API key as
Bearer your_api_key
Request Body
- Name
query*- Type
- string
- Description
- The search query to find relevant documents
- Name
namespaceId*- Type
- string
- Description
- ID of the namespace to search in
- Name
topK- Type
- number(optional)
- Description
- Number of results to return (1-100)
- Name
scoreThreshold- Type
- number(optional)
- Description
- Minimum similarity score threshold (0-1)
- Name
filter- Type
- object(optional)
- Description
- Filter configuration for the search results
- Name
metadata- Type
- object(optional)
- Description
- Metadata filters to apply on the search results
- Name
hybridConfig*- Type
- object
- Description
- Configuration for hybrid search
- Name
semanticWeight*- Type
- number
- Description
- Weight for semantic search results (0-1)
- Name
keywordWeight*- Type
- number
- Description
- Weight for keyword search results (0-1)
- Name
searchType- Type
- enum<string>(optional)
- Description
- Type of search to performAvailable options:
HYBRID
Request
POST
/v1/search/hybridcurl -X POST https://api.ragaas.dev/v1/search/hybrid \
-H "Authorization: Bearer $RAGAAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Connection refused error postgres",
"namespaceId": "ns_123",
"topK": 3,
"scoreThreshold": 0.5,
"hybridConfig": {
"semanticWeight": 0.3,
"keywordWeight": 0.7
},
"filter": {
"metadata": {
"category": "errors",
"database": "postgres"
}
},
"searchType": "HYBRID"
}'
Response Body
- Name
success*- Type
- boolean
- Description
- Indicates whether the request is successful or not. This is always true for success responses.
- Name
message*- Type
- string
- Description
- Human readable message mentioning the result of the request
- Name
data*- Type
- object
- Description
- Data returned from the API.
- Name
results*- Type
- array<object>
- Description
- List of search results
- Name
content*- Type
- string
- Description
- The matched content from the document
- Name
score*- Type
- number
- Description
- Similarity score of the match (0-1)
- Name
metadata*- Type
- object
- Description
- Metadata associated with the document
- Name
id*- Type
- string
- Description
- Unique identifier of the document
- Name
source*- Type
- string
- Description
- Source of the document
- Name
type*- Type
- string
- Description
- Type of the document
Response
POST
/v1/search/hybrid{
"success": true,
"message": "Search completed successfully",
"data": {
"results": [
{
"content": "Error: Connection refused when connecting to PostgreSQL...",
"score": 0.95,
"metadata": {
"id": "doc_125",
"source": "postgres-troubleshooting.md",
"type": "TEXT"
}
},
{
"content": "Common PostgreSQL connection errors and solutions...",
"score": 0.88,
"metadata": {
"id": "doc_126",
"source": "database-errors.md",
"type": "TEXT"
}
}
]
}
}
Error Codes
- Name
NAMESPACE_NOT_FOUND- Description
The specified namespace does not exist
- Name
INVALID_SEARCH_REQUEST- Description
Invalid search request parameters
- Name
INVALID_HYBRID_CONFIG- Description
Invalid hybrid search configuration (weights must sum to 1.0)
- Name
SEARCH_FAILED- Description
Internal error while performing the search
Weight Guidelines
For hybrid search, consider these weight combinations:
- Name
Technical Content (0.3/0.7)- Description
Better for error messages and API documentation
- Name
Natural Language (0.8/0.2)- Description
Better for knowledge base and support articles
- Name
Balanced (0.5/0.5)- Description
- Good for mixed content types