Skip to main content

​
Overview

The filtered events API provides powerful server-side filtering with full-text search, career-impact scoring, and intelligent caching. It supports pagination, multi-field search, tag-based filtering, and personalized recommendation ranking.
This endpoint requires authentication and completed career onboarding.

​
Authentication

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

​
Rate Limiting

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

​
Request

​
HTTP Method

POST /api/events/filtered

​
Headers

​
Content-Type
string
required
Must be application/json
​
X-Request-Id
string
Optional request ID for tracing
​
X-Request-Timestamp
string
Optional ISO timestamp for request timing analytics

​
Body Parameters

​
searchTerm
string
Full-text search across event titles, descriptions, tags, and organizers. Supports semantic expansion for broader matches.Example: "machine learning"
​
categories
string[]
Filter by event category IDs (e.g., conference, workshop, hackathon)Example: ["conf-001", "workshop-002"]
​
tags
string[]
Filter by exact tag matches (case-insensitive). Uses AND logic with other filters.Example: ["AI", "Python", "Data Science"]
​
locations
string[]
Filter by event locations (normalized, case-insensitive)Example: ["san francisco", "new york"]
​
format
string
default:"all"
Filter by event formatOptions: all, virtual, in-person, hybrid
​
budget
string
default:"all"
Filter by price rangeOptions: all, free-only, low, moderate, high, unlimited
​
cost
string
default:"all"
Simple cost filterOptions: all, free, paid
​
difficulty
string
default:"all"
Filter by difficulty levelOptions: all, beginner, intermediate, advanced
​
dateRange
object
Filter events by date range
​
sortBy
string
default:"date"
Sort fieldOptions: default, date, popularity, career-impact, title, location
​
sortDirection
string
default:"asc"
Sort order (auto-set to desc for career-impact)Options: asc, desc
​
page
number
default:"1"
Page number (1-indexed)
​
pageSize
number
default:"50"
Results per page (max 100)
​
recommended
boolean
default:"false"
Filter to only recommended events (score ≥ 70)
​
sessionId
string
Session ID for telemetry tracking
​
surface
string
UI surface context for analyticsOptions: calendar, discover, default
​
fastSearch
boolean
default:"false"
Skip enrichment and counts for instant search (typing-as-you-search)

​
Response

​
Success Response (200)

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

​
Error Responses

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

​
Examples

curl -X POST https://kurecal.app/api/events/filtered \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "searchTerm": "AI conference",
    "page": 1,
    "pageSize": 20
  }'

​
Advanced Filtering

curl -X POST https://kurecal.app/api/events/filtered \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "tags": ["Python", "Machine Learning"],
    "format": "virtual",
    "cost": "free",
    "dateRange": {
      "start": "2026-03-01T00:00:00Z",
      "end": "2026-06-30T23:59:59Z"
    },
    "sortBy": "career-impact",
    "recommended": true
  }'

​
Performance Notes

​
Caching Strategy

  • Cache TTL: 2-5 minutes depending on query complexity
  • Cache Key: SHA-1 hash of normalized filters + user ID
  • Cache Headers: X-Cache: HIT/MISS indicates cache status

​
Query Optimization

  • Search Expansion: Terms < 3 chars use FTS only; longer queries expand with semantic matches
  • Tag Search: Disabled for common single-word terms (e.g., “data”, “ai”)
  • Organizer Search: Only enabled for queries > 10 characters
  • Parallel Execution: Tag, organizer, and FTS searches run concurrently

​
Enrichment Strategy

  • Fast Search Mode: Set fastSearch: true to skip career scoring and counts
  • Enrichment Window: First 5 pages enriched by default; configurable via ENRICH_MAX_PAGE
  • Cold Start: Users without profiles receive baseline quality scores
Career-impact sorting fetches a larger result window (5x page size) to ensure accurate pagination after scoring.

Build docs developers (and LLMs) love

Get started for freeTalk to us