Run Sparse Search

Find candidates with exact keyword matches and technical terms.

Sparse search uses BM25 algorithm to find exact keyword matches in CVs, making it ideal for technical skill searches and specific terminology.

When to Use Sparse Search

✅ Good for:

• Exact keyword matching: "Python, FastAPI, PostgreSQL, Docker"
• Technical skills and certifications: "AWS Solutions Architect", "PMP certified"
• Specific tools and technologies: "Jira, Confluence, Kubernetes"
• Company names: "worked at Google or Meta"
• Acronyms and abbreviations: "CI/CD", "REST API", "ML/AI"

❌ Not ideal for:

• Natural language queries (use Dense Search instead)
• Conceptual matching: "someone who can lead teams"
• Queries with typos or synonyms

How It Works

1. Tokenization - Breaks query into keywords and calculates term importance
2. BM25 Matching - Finds CVs containing those exact terms using sparse vectors
3. Ranked Results - Returns top matches ordered by keyword 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

Rate limit

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

Example Request

POST /v1/public/searches/sparse

{
  "query": "Python, FastAPI, PostgreSQL, Docker, Kubernetes, AWS",
  "top_k": 20
}

Example Response

202 Accepted

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "searchGroupId": "660e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "searchType": "sparse",
  "query": "Python, FastAPI, PostgreSQL, Docker, Kubernetes, AWS",
  "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

• Use comma-separated keywords: "React, TypeScript, Node.js" works better than "React TypeScript Node.js"
• Include exact terms: Spell out acronyms when relevant ("Continuous Integration" vs "CI")
• List required and nice-to-have skills: Put must-haves first
• Use specific names: "Stanford University" instead of "top university"

Sparse vs Dense Comparison

Example comparison:

Good for Sparse:

• "Python, FastAPI, PostgreSQL, Docker"
• "AWS certified solutions architect"
• "Stanford University Computer Science"

Better for Dense:

• "someone who can build scalable backend systems"
• "team player with leadership potential"
• "creative problem solver"

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 sparse search
POST /v1/public/searches/sparse
{ "query": "Python, Docker, AWS", "searchGroupId": "abc-123" }

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

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

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

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "searchGroupId": "660e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "searchType": "sparse",
  "query": "Python, FastAPI, PostgreSQL, Docker, Kubernetes",
  "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"
}