Run Dense Search

Find candidates who mean what you're looking for, even if they say it differently.

Dense search understands the semantic meaning of your query, matching candidates based on concepts rather than exact keywords.

When to Use Dense Search

✅ Good for:

• Natural language queries: "experienced frontend developer who loves React"
• Conceptual matches: "someone who can lead a team through rapid growth"
• Fuzzy requirements: "creative problem solver with startup experience"
• Synonym handling: Finds "UI Engineer" when you search "Frontend Developer"

❌ Not ideal for:

• Exact keyword matching (use Sparse Search instead)
• Long lists of technical skills: "Python, Docker, Kubernetes, PostgreSQL"

How It Works

1. Semantic Embedding - Converts your query into a numerical representation that captures meaning
2. Vector Similarity - Finds CVs with similar semantic representations using cosine similarity
3. Ranked Results - Returns top matches ordered by relevance score

Processing time: 5 to 10 seconds

Request Parameters

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

Example Request

POST /v1/public/searches/dense

{
  "query": "senior backend engineer with microservices experience who can mentor junior developers",
  "top_k": 20
}

Example Response

202 Accepted

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "searchGroupId": "660e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "searchType": "dense",
  "query": "senior backend engineer with microservices experience who can mentor junior developers",
  "estimatedTime": "5 to 10 seconds",
  "statusUrl": "/v1/public/searches/550e8400-e29b-41d4-a716-446655440000",
  "resultsUrl": "/v1/public/searches/550e8400-e29b-41d4-a716-446655440000/results"
}

Tips for Better Results

• Be descriptive: "frontend developer who loves building user experiences" beats "frontend dev"
• Use natural language: Write queries as you'd speak them
• Include context: "startup experience" or "enterprise background" helps narrow results
• Combine concepts: "technical leader who can code" works well

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 run the same query with different algorithms and compare results:

# Run dense search
POST /v1/public/searches/dense
{ "query": "...", "searchGroupId": "abc-123" }

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

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

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

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "searchGroupId": "660e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "searchType": "dense",
  "query": "senior backend engineer with microservices experience",
  "estimatedTime": "5 to 10 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"
}