Run Builtin-Rerank Search

Semantic search with built-in quality refinement - the sweet spot between speed and accuracy.

Builtin-rerank performs dense semantic search, then uses Floreal's native reranking to boost result quality. It's faster than hybrid but more accurate than pure dense search.

When to Use Builtin-Rerank Search

✅ Good for:

• Natural language queries needing a quality boost: "creative developer who loves UX"
• When speed matters but quality can't be compromised
• Semantic-focused searches where exact keywords aren't critical
• Cost-conscious production deployments (no external reranking APIs)
• Middle-ground between dense and hybrid search

❌ Not ideal for:

• Queries where exact keywords matter (use Hybrid or Sparse instead)
• Simple queries where dense search alone is sufficient
• When you need absolute best quality (use Hybrid instead)

How It Works

1. Dense Search - Converts query to semantic embedding and finds similar CVs (5-8s)
2. Native Reranking - Floreal's built-in reranker rescores results for better relevance (5-12s)
3. Top Results - Returns the best matches after reranking

Processing time: 10 to 20 seconds

Request Parameters

Parameter tips:

• Set top_k higher (30-50) to give reranker more candidates to evaluate
• Set rerank_top_n to your desired final count (typically 20-30)
• More candidates = better reranking quality but slightly slower

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 2 to 3 seconds
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/builtin-rerank

{
  "query": "creative frontend developer who loves building beautiful user experiences",
  "top_k": 40,
  "rerank_top_n": 25
}

Why this benefits from builtin-rerank:

• Semantic query (concepts, not just keywords)
• Needs quality refinement beyond basic dense search
• Doesn't require keyword matching (sparse search unnecessary)

Example Response

202 Accepted

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "searchGroupId": "660e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "searchType": "builtin-rerank",
  "query": "creative frontend developer who loves building beautiful user experiences",
  "estimatedTime": "10 to 20 seconds",
  "statusUrl": "/v1/public/searches/550e8400-e29b-41d4-a716-446655440000",
  "resultsUrl": "/v1/public/searches/550e8400-e29b-41d4-a716-446655440000/results"
}

Tips for Better Results

• Best for semantic queries: Natural language descriptions work best
• Use realistic top_k: Set to 1.5-2x your desired final results (e.g., top_k=40, rerank_top_n=25)
• Compare quality: Use searchGroupId to compare with dense or hybrid
• Balance speed vs quality: 2x slower than dense, but 1.5x faster than hybrid

When to choose what:

• Use Dense: Speed is critical, simple semantic queries
• Use Builtin-Rerank: Need better quality than dense but faster than hybrid
• Use Hybrid: Keywords matter, need absolute best quality
• Use Sparse: Only exact keyword matching matters

Builtin-Rerank vs Hybrid

Builtin-Rerank (this endpoint):

• ✅ Dense search + Floreal's native reranking
• ✅ Faster (10-20s)
• ✅ Lower cost (no external APIs)
• ❌ No keyword matching (sparse search)

Hybrid:

• ✅ Dense + Sparse + Cohere reranking
• ✅ Best quality
• ✅ Handles both concepts AND keywords
• ❌ Slower (15-30s)
• ❌ Higher cost

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 builtin-rerank with other search types:

# Run builtin-rerank search
POST /v1/public/searches/builtin-rerank
{ "query": "creative problem solver", "searchGroupId": "abc-123", "top_k": 40, "rerank_top_n": 25 }

# Run dense search with same groupId
POST /v1/public/searches/dense
{ "query": "creative problem solver", "searchGroupId": "abc-123" }

# Run hybrid search with same groupId
POST /v1/public/searches/hybrid
{ "query": "creative problem solver", "searchGroupId": "abc-123" }

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

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

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "searchGroupId": "660e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "searchType": "builtin-rerank",
  "query": "creative frontend developer who loves building user experiences",
  "estimatedTime": "10 to 20 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"
}