Run Hybrid Search

Best-of-both-worlds: combines semantic understanding with exact keyword matching, then AI-reranks for maximum relevance.

Hybrid search runs both dense (semantic) and sparse (keyword) searches simultaneously, merges the results, and uses AI reranking to deliver the highest quality matches.

When to Use Hybrid Search

✅ Good for:

• Complex queries mixing concepts and keywords: "senior Python developer who can lead teams"
• Maximum quality needed: production searches, critical hires
• Unclear if semantic or keyword search is better
• Queries with both technical skills AND soft requirements
• When you want the absolute best results and can accept slower processing

❌ Not ideal for:

• Simple keyword-only queries (use Sparse instead)
• Simple semantic queries (use Dense instead)
• Speed-critical applications (15-30s vs 5-10s)
• High-volume automated searches (higher compute cost)

How It Works

1. Parallel Search - Runs dense and sparse searches simultaneously (5-10s)
2. Result Fusion - Merges both result sets, prioritizing candidates found by both algorithms
3. AI Reranking - Cohere AI scores each candidate against your exact query for optimal relevance
4. Top Results - Returns the best matches after AI evaluation

Processing time: 15 to 30 seconds

Request Parameters

Understanding the parameters:

• top_k=20 means 20 from dense + 20 from sparse = ~40 candidates go to reranking
• rerank_top_n=30 means return the best 30 after AI reranking
• Tip: Set rerank_top_n slightly higher than top_k for best coverage

Response Flow

This endpoint returns immediately with a searchId. The actual search runs asynchronously in the background.

Next steps:

1. Save the returned searchId
2. Poll GET /v1/public/searches/:searchId every 3 to 5 seconds (note: slower than dense/sparse)
3. When status is "completed", fetch results from GET /v1/public/searches/:searchId/results

Rate limit

For rate limit, please check the rate limit in the dedicated API documentation section.

Example Request

POST /v1/public/searches/hybrid

{
  "query": "experienced backend engineer who knows Python and can lead teams, preferably with startup experience",
  "top_k": 30,
  "rerank_top_n": 20
}

Why this query benefits from hybrid:

• Has keywords: "Python", "backend engineer"
• Has concepts: "can lead teams", "startup experience"
• Needs both exact matches AND semantic understanding

Example Response

202 Accepted

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "searchGroupId": "660e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "searchType": "hybrid",
  "query": "experienced backend engineer who knows Python and can lead teams, preferably with startup experience",
  "estimatedTime": "15 to 30 seconds",
  "statusUrl": "/v1/public/searches/550e8400-e29b-41d4-a716-446655440000",
  "resultsUrl": "/v1/public/searches/550e8400-e29b-41d4-a716-446655440000/results"
}

Tips for Better Results

• Use for complex queries: Mix specific skills with soft requirements
• Set appropriate top_k: Use 30-50 to give reranker enough candidates to evaluate
• Balance quality vs speed: Hybrid is 2-3x slower but delivers best quality
• Compare with other methods: Use searchGroupId to see if hybrid actually performs better for your query

Error Responses

Result Expiration

• Search results are stored in the database and can be retrieved anytime using the same searchId

Comparing Algorithms

Use searchGroupId to compare hybrid with other search types on the same query:

# Run hybrid search
POST /v1/public/searches/hybrid
{ "query": "Python developer with leadership skills", "searchGroupId": "abc-123", "top_k": 30, "rerank_top_n": 20 }

# Run dense search with same groupId
POST /v1/public/searches/dense
{ "query": "Python developer with leadership skills", "searchGroupId": "abc-123" }

# Run sparse search with same groupId
POST /v1/public/searches/sparse
{ "query": "Python developer with leadership skills", "searchGroupId": "abc-123" }

# Compare all results
GET /v1/public/searches/groups/abc-123/results

curl -X POST "https://api.floreal.ai/v1/public/searches/hybrid" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "string"
  }'

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "searchGroupId": "660e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "searchType": "hybrid",
  "query": "experienced backend engineer who knows Python and can lead teams",
  "estimatedTime": "15 to 30 seconds",
  "statusUrl": "/v1/public/searches/550e8400-e29b-41d4-a716-446655440000",
  "resultsUrl": "/v1/public/searches/550e8400-e29b-41d4-a716-446655440000/results"
}

{
  "error": "string",
  "message": "string"
}

{
  "error": "string"
}

{
  "error": "string",
  "message": "string"
}