Back to Home

API Documentation

Everything you need to integrate MatchAgent into your app.

Authentication

All authenticated endpoints require a JWT token in the Authorization header. You'll receive your API key after subscribing.

Authorization: Bearer YOUR_API_KEY

Base URL

https://api.matchagent.io

Endpoints

GET/health

Health check. Returns server status and mode (demo or db).

Response

{
  "status": "ok",
  "mode": "db",
  "version": "1.3.0"
}
GET/matches/:user_idJWT

Get ranked matches for a user. Uses ANN retrieval + full scoring pipeline.

Parameters

user_idpath— The user ID to find matches for
nquery— Number of matches to return (default: 10, max: 50)

Response

{
  "user_id": 42,
  "matches": [
    {
      "user_id": 87,
      "score": 0.847,
      "signals": {
        "values": 0.92,
        "lifestyle": 0.81,
        "personality": 0.78,
        "interests": 0.85
      },
      "explanation": "Strong alignment on family values and active lifestyle",
      "coach": {
        "opener": "You both love hiking and value family time...",
        "approach_style": "warm_direct",
        "tips": ["Ask about their favorite trail", "Mention your weekend routine"]
      },
      "energy": {
        "compatibility": "mirror",
        "score": 0.88,
        "description": "Similar energy levels — natural flow"
      }
    }
  ],
  "retrieval": "ann",
  "candidates_scored": 80,
  "latency_ms": 12
}
GET/demo/matches/:user_id

Same as /matches but uses in-memory demo data. Good for testing integration without a database.

Parameters

user_idpath— Demo user ID (1-10)
nquery— Number of matches (default: 5)

Response

{
  "user_id": 1,
  "matches": [
    {
      "user_id": 3,
      "score": 0.823,
      "signals": { ... },
      "explanation": "...",
      "coach": { ... }
    }
  ],
  "retrieval": "demo"
}
POST/profileJWT

Create or update a user profile. Automatically generates embedding for ANN search.

Request Body

{
  "user_id": 42,
  "age": 28,
  "gender": "male",
  "looking_for": "female",
  "relationship_goal": "long_term",
  "city": "Santiago",
  "country": "CL",
  "min_age": 24,
  "max_age": 34,
  "max_distance_km": 30,
  "values": {
    "family": 0.9,
    "monogamy": 1.0,
    "wants_children": 0.8,
    "faith_importance": 0.3
  },
  "lifestyle": {
    "activity_level": 0.8,
    "social_frequency": 0.6,
    "sleep_schedule": "early",
    "diet": "flexible"
  },
  "personality": {
    "openness": 0.75,
    "conscientiousness": 0.82,
    "extraversion": 0.55,
    "agreeableness": 0.78,
    "neuroticism": 0.35
  },
  "interests": ["hiking", "cooking", "photography", "travel"],
  "dealbreakers": {
    "smoking": true,
    "drugs": true
  }
}

Response

{
  "status": "created",
  "user_id": 42,
  "embedding_generated": true
}
POST/interactionsJWT

Record a user interaction (like, pass, superlike, ghost, block). Feeds into the feedback loop for future scoring.

Request Body

{
  "from_user": 42,
  "to_user": 87,
  "action": "like",
  "meta": {
    "source": "matches_feed",
    "time_spent_ms": 4500
  }
}

Response

{
  "status": "recorded",
  "interaction_id": 156,
  "mutual_match": false
}
GET/statsJWT

Engine statistics and performance metrics.

Response

{
  "total_profiles": 1234,
  "total_interactions": 5678,
  "avg_score": 0.62,
  "avg_latency_ms": 13.2,
  "ann_hit_rate": 0.94
}
GET/metrics

Raw counters for monitoring. Prometheus-compatible.

Response

{
  "requests_total": 45678,
  "matches_served": 12345,
  "ann_queries": 11890,
  "ann_fallbacks": 455,
  "avg_latency_ms": 12.8
}

Scoring Algorithm

The final score is a weighted sum of 6 signals, adjusted by feedback, temporal decay, and cold start boost:

score = (values × 0.35) + (lifestyle × 0.25) + (personality × 0.20) + (interests × 0.15)
       - (distance_penalty × 0.03) - (conflicts × 0.02)
       + feedback_adjustment + cold_start_boost - temporal_decay

# Bidirectional: final_score = sqrt(score_A→B × score_B→A)
# All signals are normalized to [0, 1]

Custom Weights (Growth+)

Growth and Enterprise plans can customize signal weights per request:

GET /matches/42?n=10&w_values=0.40&w_lifestyle=0.30&w_personality=0.15&w_interests=0.15

Rate Limits

PlanRequests/minMatches/month
Starter6010,000
Growth300100,000
Enterprise1,000Unlimited

Quick Start

1. Create a profile

curl -X POST https://api.matchagent.io/profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 42,
    "age": 28,
    "gender": "male",
    "looking_for": "female",
    "relationship_goal": "long_term",
    "city": "Santiago",
    "country": "CL",
    "min_age": 24,
    "max_age": 34,
    "values": {"family": 0.9, "monogamy": 1.0},
    "lifestyle": {"activity_level": 0.8},
    "personality": {"openness": 0.75, "extraversion": 0.55},
    "interests": ["hiking", "cooking"]
  }'

2. Get matches

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.matchagent.io/matches/42?n=10"

3. Record interactions

curl -X POST https://api.matchagent.io/interactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from_user": 42, "to_user": 87, "action": "like"}'

SDKs (Coming Soon)

JavaScript/TypeScript
Python
Ruby

Support

Starter: Email support (info@newcool.io)
Growth: Priority email support
Enterprise: Dedicated Slack channel + SLA