Skip to main content

​
Overview

The recommendations API returns personalized event suggestions based on the user’s career profile, joined circles, and historical interactions. It combines tag-based matching with advanced career impact scoring and optional behavioral reranking.
Requires authentication and a completed career profile. Returns empty results for users without profiles.

​
Authentication

Requires a valid Supabase authentication token in the request headers. 
Authorization: Bearer <supabase_access_token>

​
Rate Limiting

  • Limit: 20 requests per minute per user
  • Window: Sliding window (1 minute)
  • Response: HTTP 429 if rate limit exceeded

​
Request

​
HTTP Method

GET /api/events/recommendations

​
Query Parameters

​
limit
number
default:"10"
Maximum number of recommendations to return (max 50)
​
tags
string
Comma-separated list of tags to search for specific eventsExample: tags=python,machine-learning,ai
​
sessionId
string
Session ID for telemetry tracking (optional)

​
Headers

​
X-Request-Id
string
Optional request ID for tracing and debugging

​
Response

​
Success Response (200)

​
success
boolean
required
Always true for successful requests
​
data
object
required

​
Error Responses

{
  "success": false,
  "error": "Authentication required"
}

​
Examples

​
Get Personalized Recommendations

curl -X GET "https://kurecal.app/api/events/recommendations?limit=20" \
  -H "Authorization: Bearer <token>"

​
Search by Specific Tags

curl -X GET "https://kurecal.app/api/events/recommendations?tags=python,machine-learning&limit=10" \
  -H "Authorization: Bearer <token>"

​
How It Works

​
Recommendation Pipeline

  1. Profile Enrichment: User’s career profile is enriched with joined circle names for instant personalization boost
  2. Tag Matching: Events are ranked by tag similarity to user’s:
    • Primary skills
    • Skills to learn
    • Interests
    • Career goals
    • Joined circles
  3. Career Alignment: Each event receives an alignment score (0-100) based on:
    • Skill relevance
    • Career stage match
    • Networking value
    • Industry relevance
    • Timing factors
  4. Diversity Enhancement: Results are reranked to provide variety across:
    • Event types (conference, workshop, meetup)
    • Topics and skills
    • Date ranges
  5. Behavioral Reranking (Optional): If DISCOVERY_RERANK=advanced, user interaction history further refines order

​
Scoring Strategy Selection

Recommendations use the scoring strategy configured via environment variables:
  • DISCOVERY_SCORING=server (default): Pure alignment core
  • DISCOVERY_SCORING=legacy: Legacy enhanced scoring
  • DISCOVERY_SCORING=shadow: Both strategies with delta logging

​
Telemetry

If user has analytics consent, the API logs:
  • Top 10 recommended events with scores
  • Kendall’s tau correlation between tag ranking and alignment ranking
  • Divergence count (how many pairs switched order)
  • Tag match counts and processing time

​
Performance Notes

  • Processing Time: Typically 200-800ms depending on profile complexity
  • Cache Strategy: No caching; each request is freshly calculated for personalization accuracy
  • Sampling Rate: Matching telemetry sampled at 1% (configurable via MATCHING_TELEMETRY_SAMPLE_RATE)
For faster search results without personalization, use GET /api/events/filtered with fastSearch=true.

Build docs developers (and LLMs) love

Get started for freeTalk to us