Getting Started

Integrate LoveConnet identity verification in minutes

LoveConnet is the world's first verified human identity platform for developers. Unlike traditional OAuth providers that only verify an email address, LoveConnet provides real face verification, AI-powered trust scores, and ID document checks — all accessible through a simple REST API or one of our SDKs.

What makes LoveConnet different?

✅ Face Verified
Real biometric verification, not just selfies

🛡️ Trust Scores
AI behavioral analysis across 50+ signals

🔒 Privacy First
Bracketed data only — never raw DOBs or scores

Quick Start (3 steps)

Create an app

Go to the Developer Portal and click "Create app". You'll receive a client_id and client_secret.

Generate an API key

In your app's settings, generate an API key. Keys start with lc_live_ (production) or lc_test_ (sandbox). Store it securely — it's only shown once.

Install an SDK and make your first call

Choose your language below and start verifying users in under 5 minutes.

javascriptnpm install @loveconnet/js

import { LoveConnet } from '@loveconnet/js';

const lc = new LoveConnet({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'https://yourapp.com/callback',
  apiKey: 'lc_live_xxx',
});

// Redirect user to login
await lc.login(['profile', 'verified', 'trust_score']);

Authentication

OAuth 2.0 Authorization Code Flow with PKCE

LoveConnet uses OAuth 2.0 with PKCE (Proof Key for Code Exchange, RFC 7636). PKCE is mandatory for all clients — including server-side apps. This eliminates the need to expose client secrets in mobile or frontend code and prevents authorization code interception attacks.

Important

All requests without a valid PKCE code challenge will be rejected with a 400 error. Our SDKs handle PKCE automatically — you don't need to implement it yourself.

Step 1: Authorization Request

Redirect the user's browser to the authorization endpoint. The user will see the LoveConnet consent screen showing which permissions your app is requesting.

httpGET https://loveconnet.com/api/oauth/authorize
  ?client_id=lc_abc123def456
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=openid profile email verified trust_score age
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=xyzrandom123

Parameters

client_idRequiredYour app's client ID from the portal

redirect_uriRequiredMust match one of your registered URIs exactly

response_typeRequiredAlways "code"

scopeRequired"openid" is mandatory. Add: profile, email, verified, trust_score, age

code_challengeRequiredBase64url-encoded SHA256 hash of your code_verifier

code_challenge_methodRequiredAlways "S256"

stateRecommendedRandom string to prevent CSRF — verify it on callback

Step 2: Token Exchange

After the user approves, they're redirected to your redirect_uri with an authorization code. Exchange it for tokens:

httpPOST https://loveconnet.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_FROM_CALLBACK
&redirect_uri=https://yourapp.com/callback
&client_id=lc_abc123def456
&code_verifier=YOUR_ORIGINAL_CODE_VERIFIER

The response contains your access token, refresh token, and ID token:

json{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "v1.MjAyNi0wNS0wNFQx...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "scope": "openid profile email verified trust_score"
}

Step 3: Call the API

Use the access token to call any API endpoint. Pass it as the X-User-Token header along with your API key:

httpGET https://loveconnet.com/api/v1/user/profile
X-API-Key: lc_live_xxx
X-User-Token: eyJhbGciOiJSUzI1NiIs...

→ 200 OK
{
  "sub": "clx1abc2def3",
  "name": "Sarah Johnson",
  "bio": "Love hiking and coffee ☕",
  "picture": "https://cdn.loveconnet.com/photos/..."
}

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to get a new one without re-prompting the user:

httpPOST https://loveconnet.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=v1.MjAyNi0wNS0wNFQx...
&client_id=lc_abc123def456

SDK Installation

Official SDKs for every major platform

JavaScript / TypeScriptWeb · React · Vue · Next.js

@loveconnet/js

$npm install @loveconnet/js

import { LoveConnet } from '@loveconnet/js';

const lc = new LoveConnet({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'https://yourapp.com/callback',
  apiKey: 'lc_live_xxx',
});

// Start PKCE login — opens consent screen
await lc.login(['profile', 'verified', 'trust_score']);

// On callback page — exchange code for tokens
await lc.handleCallback(window.location.href);

// Fetch verified user data
const profile = await lc.api.getProfile();
console.log(profile.name);         // "Sarah Johnson"
console.log(profile.face_verified); // true

const trust = await lc.api.getTrustScore();
console.log(trust.trust_level);     // "EXCELLENT"

React NativeiOS · Android · Expo

@loveconnet/react-native

$npm install @loveconnet/react-native

import { useLoveConnet } from '@loveconnet/react-native';

function LoginScreen() {
  const { login, user, isAuthenticated, logout } = useLoveConnet({
    clientId: 'YOUR_CLIENT_ID',
    redirectUri: 'myapp://callback',
    apiKey: 'lc_live_xxx',
  });

  if (isAuthenticated) {
    return (
      <View>
        <Text>Welcome {user.name}!</Text>
        <Text>Verified: {user.face_verified ? '✅' : '❌'}</Text>
        <Button title="Logout" onPress={logout} />
      </View>
    );
  }

  return <Button title="Sign in" onPress={() => login(['profile', 'verified'])} />;
}

PythonFastAPI · Django · Flask · Sync + Async

loveconnet

$pip install loveconnet

from loveconnet import LoveConnet, AsyncLoveConnet

# ── Synchronous (scripts, Flask, Django) ──
lc = LoveConnet(api_key="lc_live_xxx")

profile = lc.get_profile(user_token="eyJ...")
print(f"{profile.name} — Verified: {profile.face_verified}")

trust = lc.get_trust_score(user_token="eyJ...")
print(f"Trust: {trust.trust_level}")  # "EXCELLENT"

age = lc.get_age_range(user_token="eyJ...")
print(f"Over 18: {age.over_18}")       # True

# ── Asynchronous (FastAPI, async Django) ──
async with AsyncLoveConnet(api_key="lc_live_xxx") as lc:
    profile = await lc.get_profile(user_token="eyJ...")
    trust = await lc.get_trust_score(user_token="eyJ...")

Flutter / DartiOS · Android · Secure Storage

loveconnet

$flutter pub add loveconnet

import 'package:loveconnet/loveconnet.dart';

final lc = LoveConnet(
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'myapp://callback',
  apiKey: 'lc_live_xxx',
);

// Login via system browser
await lc.login(scopes: [Scope.profile, Scope.verified]);

// Handle deep link callback
final user = await lc.handleCallback(uri);
print('${user.name} — Verified: ${user.faceVerified}');

// Tokens stored in Keychain (iOS) / EncryptedSharedPrefs (Android)
await lc.restoreSession(); // Auto-restore on app start

PHPLaravel · Symfony · WordPress · PSR-18

loveconnet/sdk

$composer require loveconnet/sdk

use LoveConnet\LoveConnet;

$lc = new LoveConnet('lc_live_xxx');

$profile = $lc->getProfile($userToken);
echo $profile->name;          // "Sarah Johnson"
echo $profile->faceVerified;  // true

$trust = $lc->getTrustScore($userToken);
echo $trust->trustLevel;      // "EXCELLENT"

// Laravel — register as singleton
$this->app->singleton(LoveConnet::class, fn () =>
    new LoveConnet(config('services.loveconnet.api_key'))
);

// Controller — inject via DI
public function verify(Request $request, LoveConnet $lc) {
    $profile = $lc->getProfile($request->bearerToken());
    return response()->json(['verified' => $profile->faceVerified]);
}

API Reference

All REST endpoints with request and response examples

Base URL: https://loveconnet.com/api

Required Headers

X-API-Key: lc_live_xxx — Your API key (always required)

X-User-Token: eyJ... — User's OAuth access token (for /user/* endpoints)

GET/v1/user/profile

scope: profileFree

Returns the user's basic profile: name, bio, and primary profile photo. This is the most commonly used endpoint.

Response

json{
  "sub": "clx1abc2def3",
  "name": "Sarah Johnson",
  "bio": "Love hiking and coffee ☕",
  "picture": "https://cdn.loveconnet.com/photos/abc123.jpg"
}

GET/v1/user/email

scope: emailFree

Returns the user's email address and whether it has been verified through our email confirmation flow.

Response

json{
  "email": "[email protected]",
  "email_verified": true
}

GET/v1/user/verified

scope: verifiedFree

Returns whether the user has completed face verification (live biometric) and/or government ID verification. This is LoveConnet's signature feature.

Response

json{
  "face_verified": true,
  "id_verified": true
}

GET/v1/user/trust

scope: trust_scoreStarter

Returns the user's trust level bracket based on our AI behavioral analysis (50+ signals). The raw score is never exposed — only the bracket label and range.

Response

json{
  "trust_level": "EXCELLENT",
  "trust_bracket": "80-100"
}

GET/v1/user/age

scope: ageStarter

Returns the user's age as a range bracket (e.g. "25-34") and boolean flags for common legal thresholds. The exact date of birth is never exposed.

Response

json{
  "age_range": "25-34",
  "over_18": true,
  "over_21": true
}

POST/v1/auth/userinfo

scope: All grantedFree

Standard OIDC-style userinfo endpoint. Returns all claims the user has consented to in a single response. Useful for getting everything in one call.

Response

json{
  "sub": "clx1abc2def3",
  "name": "Sarah Johnson",
  "email": "[email protected]",
  "email_verified": true,
  "face_verified": true,
  "id_verified": true,
  "trust_level": "EXCELLENT",
  "over_18": true
}

GET/v1/app/stats

scope: None (API key only)Free

Returns your app's aggregate statistics. No user token required — just your API key.

Response

json{
  "total_users": 1250,
  "active_users": 980,
  "app_id": "lc_abc123",
  "tier": "STARTER"
}

Trust & Verification as-a-Service

Verification badges, safety scores, image/text screening, and bot detection.

GET/v1/users/:id/verifications

scope: verification_statusStarter

Returns all verification badges: email, phone, face (biometric), and government ID verification status with timestamps.

Request

curl -X GET "https://loveconnet.com/api/v1/users/:id/verifications" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "user_id": "clx1abc2def3",
  "verifications": {
    "email": { "verified": true },
    "phone": { "verified": true },
    "face": { "verified": true, "verified_at": "2026-03-15T..." },
    "identity": { "verified": false, "verified_at": null }
  },
  "fully_verified": false
}

GET/v1/users/:id/safety-score

scope: trust_scoreStarter

Returns the user's computed safety score (0-100), badge label, and the contributing factors analyzed by our AI.

Request

curl -X GET "https://loveconnet.com/api/v1/users/:id/safety-score" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "user_id": "clx1abc2def3",
  "score": 87,
  "badge": "TRUSTED",
  "factors": [
    { "name": "account_age", "impact": 15, "detail": "Account older than 90 days" },
    { "name": "verification", "impact": 25, "detail": "Face verified" },
    { "name": "behavior", "impact": 20, "detail": "No safety alerts" }
  ]
}

POST/v1/verify/image

scope: verify_contentPro

Screen any image URL for explicit/unsafe content using GPT-4o. Returns category scores for nudity, violence, hate, drugs, and spam.

Request

curl -X POST "https://loveconnet.com/api/v1/verify/image" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "safe": true,
  "confidence": 0.95,
  "categories": {
    "nudity": 0.02,
    "violence": 0.01,
    "hate": 0.0,
    "drugs": 0.0,
    "spam": 0.03
  },
  "reason": null
}

POST/v1/verify/text

scope: verify_contentPro

Screen text for scam indicators and manipulation patterns. Combines keyword-based scam detection with AI grooming/manipulation pattern analysis.

Request

curl -X POST "https://loveconnet.com/api/v1/verify/text" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "safe": true,
  "scam": {
    "detected": false,
    "warnings": []
  },
  "manipulation": {
    "score": 5,
    "indicators": []
  }
}

POST/v1/verify/bot-check

scope: None (API key only)Starter

Generate a behavioral bot detection challenge. The user must interact with the challenge and submit behavioral data (hold duration, mouse movements, etc).

Request

curl -X POST "https://loveconnet.com/api/v1/verify/bot-check" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "challenge_id": "ch_9f8a7b6c5d4e",
  "expires_at": "2026-05-04T17:15:00Z"
}

POST/v1/verify/bot-check/validate

scope: None (API key only)Starter

Validate a bot check challenge with the user's behavioral data. Returns is_human boolean and a signed verification token if passed.

Request

curl -X POST "https://loveconnet.com/api/v1/verify/bot-check/validate" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "is_human": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "reason": null
}

Safety & Content Moderation API

AI-powered image moderation, text screening, and conversation analysis.

POST/v1/moderate/image

scope: moderate_contentPro

Full image moderation powered by GPT-4o. Analyzes for nudity, violence, hate speech, drugs, and spam with confidence scores and an actionable recommendation.

Request

curl -X POST "https://loveconnet.com/api/v1/moderate/image" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "approved": true,
  "confidence": 0.93,
  "categories": {
    "nudity": 0.01,
    "violence": 0.0,
    "hate_speech": 0.0,
    "drugs": 0.0,
    "spam": 0.02
  },
  "reason": null,
  "recommendation": "APPROVE"
}

POST/v1/moderate/text

scope: moderate_contentStarter

Text safety screening combining scam keyword detection with AI manipulation/grooming pattern analysis. Returns risk level and actionable recommendation.

Request

curl -X POST "https://loveconnet.com/api/v1/moderate/text" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "safe": false,
  "risk_level": "MEDIUM",
  "scam_detection": {
    "flagged": true,
    "warning_count": 1,
    "warnings": [{
      "keyword": "send money",
      "category": "financial",
      "severity": "HIGH",
      "message": "Potential financial scam detected"
    }]
  },
  "manipulation_detection": {
    "score": 15,
    "indicators": []
  },
  "recommendation": "FLAG_FOR_REVIEW"
}

POST/v1/moderate/conversation

scope: moderate_contentPro

Analyze an entire conversation history for grooming/manipulation patterns. Pass messages as sender/receiver roles. Returns threat level with unique behavioral indicators.

Request

curl -X POST "https://loveconnet.com/api/v1/moderate/conversation" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "threat_level": "LOW",
  "average_risk_score": 8,
  "messages_analyzed": 24,
  "unique_indicators": [],
  "recommendation": "SAFE"
}

GET/v1/moderate/categories

scope: None (public)Free

List all moderation categories with descriptions and which tiers can access each type of moderation.

Request

curl -X GET "https://loveconnet.com/api/v1/moderate/categories" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "image_categories": [
    { "id": "nudity", "name": "Nudity & Sexual Content", "score_range": "0-1" },
    { "id": "violence", "name": "Violence & Gore", "score_range": "0-1" }
  ],
  "text_categories": [
    { "id": "scam", "name": "Scam Detection" },
    { "id": "grooming", "name": "Grooming Detection" }
  ],
  "tiers": {
    "image_moderation": "PRO",
    "text_moderation": "STARTER+",
    "conversation_analysis": "PRO"
  }
}

Matching & Compatibility API

Compatibility scoring, user preferences, interests, and profile photos.

POST/v1/match/compatibility

scope: matchingStarter

Calculate a multi-dimensional compatibility score between two consented users. Analyzes shared interests, lifestyle habits, relationship goals, and language overlap.

Request

curl -X POST "https://loveconnet.com/api/v1/match/compatibility" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "user_a_id": "clx1abc2def3",
  "user_b_id": "clx4ghi5jkl6",
  "overall_score": 78,
  "dimensions": {
    "shared_interests": { "score": 85, "shared": ["hiking", "cooking"], "count": 2 },
    "lifestyle": { "score": 75, "matches": 3, "total": 4 },
    "relationship_goals": { "score": 100, "a": "long_term", "b": "long_term" },
    "language": { "score": 100, "shared": ["English"] }
  }
}

GET/v1/users/:id/preferences

scope: profileStarter

Returns the user's matching preferences including age range, distance radius, preferred genders, and relationship goal.

Request

curl -X GET "https://loveconnet.com/api/v1/users/:id/preferences" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "user_id": "clx1abc2def3",
  "preferences": {
    "age_range": { "min": 25, "max": 35 },
    "max_distance_km": 50,
    "preferred_genders": ["female"],
    "relationship_goal": "long_term"
  }
}

GET/v1/users/:id/interests

scope: profileFree

Returns the user's interests, lifestyle data (smoking, drinking, exercise, diet), music tastes, languages, and relationship goal.

Request

curl -X GET "https://loveconnet.com/api/v1/users/:id/interests" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "user_id": "clx1abc2def3",
  "interests": ["hiking", "cooking", "photography"],
  "lifestyle": {
    "smoking": "never",
    "drinking": "socially",
    "exercise": "active",
    "diet": null,
    "education": "bachelors",
    "religion": null,
    "height_cm": 175
  },
  "music": {
    "top_artists": ["Burna Boy", "Wizkid"],
    "top_genres": ["Afrobeats", "R&B"]
  },
  "languages": ["English", "Twi"]
}

GET/v1/users/:id/photos

scope: photosStarter

Returns the user's profile photos with thumbnail URLs, primary flag, and display order.

Request

curl -X GET "https://loveconnet.com/api/v1/users/:id/photos" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "user_id": "clx1abc2def3",
  "photo_count": 4,
  "photos": [
    { "id": "ph_1", "url": "https://...", "thumbnail_url": "https://...", "is_primary": true, "order": 0 },
    { "id": "ph_2", "url": "https://...", "thumbnail_url": "https://...", "is_primary": false, "order": 1 }
  ]
}

Discovery API

Build dating experiences powered by LoveConnet's verified user base

What is the Discovery API?

The Discovery API enables third-party developers to build dating/social apps on top of LoveConnet's verified human identity platform. Users authenticate via Sign in with LoveConnet, and your app can browse profiles, swipe, match, and get AI-powered recommendations — all backed by verified real humans.

🔍 Browse
Paginated, filtered profile discovery with anti-scraping protection

💘 Swipe
Like, pass, superlike with mutual match detection & webhooks

🤖 AI Recs
Scored recommendations based on interests, location & verification

Required Headers

X-API-Key: lc_live_xxx — Your API key (always required)

X-User-Token: eyJ... — User's OAuth token with discovery scope

Scope & Consent Required

Discovery endpoints require the discovery scope. Users must also have discoverable consent enabled to appear in browse results. All endpoints include anti-scraping, honeypot detection, and daily quota enforcement.

Profile Discovery & Browsing

Browse, filter, and explore verified profiles with secure pagination.

GET/v1/discover/profiles

scope: discoveryFree

Browse verified profiles with filtering. Supports age range, gender, distance (requires lat/lng), interests, online status, and trust score filters. Results use signed pagination tokens to prevent scraping. Daily quota is enforced per tier.

Query Params:

age_min, age_max, gender, verified_only, min_trust_score, distance_km, lat, lng, interests, online_now, limit, page_token

Request

curl -X GET "https://loveconnet.com/api/v1/discover/profiles" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "data": [
    {
      "user_id": "clx1abc2def3",
      "name": "Sarah",
      "age": 26,
      "bio": "Love hiking and coffee ☕",
      "city": "Accra",
      "gender": "female",
      "photos": [{ "url": "https://cdn.loveconnet.com/..." }],
      "verifications": { "face": true, "id": true, "photo": true },
      "is_online": true,
      "interests": ["hiking", "cooking", "photography"]
    }
  ],
  "pagination": {
    "page_token": "eyJ0eXAiOiJKV1Qi...",
    "has_more": true,
    "limit": 10
  },
  "quota": { "remaining": 149, "limit": 150 },
  "request_id": "req_a1b2c3d4e5f6"
}

GET/v1/discover/filters

scope: None (public)Free

Returns all available filter options with types, ranges, and defaults. Use this to populate filter UIs dynamically. No authentication required.

Request

curl -X GET "https://loveconnet.com/api/v1/discover/filters" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "filters": {
    "age": { "min": 18, "max": 100, "type": "range" },
    "gender": { "options": ["male", "female", "non_binary", "other"], "type": "select" },
    "distance_km": { "min": 1, "max": 500, "type": "range", "requires": ["lat", "lng"] },
    "verified_only": { "type": "boolean", "default": true },
    "min_trust_score": { "min": 0, "max": 100, "type": "range" },
    "interests": { "type": "comma_separated" },
    "online_now": { "type": "boolean", "default": false }
  },
  "sort_options": ["last_active", "trust_score", "distance"],
  "max_page_size": 20
}

GET/v1/discover/recommendations

scope: discoveryFree

AI-powered profile recommendations scored by shared interests, city proximity, verification level, and recent activity. Returns up to 10 ranked profiles with score explanations.

Request

curl -X GET "https://loveconnet.com/api/v1/discover/recommendations" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "data": [
    {
      "user_id": "clx4ghi5jkl6",
      "name": "Ama",
      "age": 24,
      "recommendation_score": 85,
      "recommendation_reasons": [
        "Shared interests: hiking, cooking",
        "Same city",
        "Verified identity",
        "Recently active"
      ],
      "verifications": { "face": true, "id": true, "photo": false },
      "photos": [{ "url": "https://cdn.loveconnet.com/..." }]
    }
  ],
  "algorithm": "interest_match_v1",
  "request_id": "req_f6e5d4c3b2a1"
}

Swiping & Matching

Like, pass, superlike with real-time mutual match detection and 30-second undo window.

POST/v1/discover/like

scope: discoveryFree

Like a profile. Automatically checks for mutual match. If both users have liked each other, a match.created webhook is dispatched. Daily like quota enforced per tier. Honeypot detection protects against bots.

Request

curl -X POST "https://loveconnet.com/api/v1/discover/like" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..." \
  -H "Content-Type: application/json" \
  -d '{ "target_user_id": "clx4ghi5jkl6" }'

Response

json{
  "liked": true,
  "is_match": true,
  "match": {
    "user_a_id": "clx1abc2def3",
    "user_b_id": "clx4ghi5jkl6",
    "matched_at": "2026-05-05T20:00:00.000Z"
  },
  "quota": { "remaining": 49, "limit": 50 },
  "undo_available": true,
  "undo_expires_in": 30,
  "request_id": "req_b2c3d4e5f6a1"
}

POST/v1/discover/pass

scope: discoveryFree

Pass/skip a profile. The user will not appear in future discovery results for 30 days. Includes 30-second undo window.

Request

curl -X POST "https://loveconnet.com/api/v1/discover/pass" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..." \
  -H "Content-Type: application/json" \
  -d '{ "target_user_id": "clx4ghi5jkl6" }'

Response

json{
  "passed": true,
  "undo_available": true,
  "undo_expires_in": 30,
  "request_id": "req_c3d4e5f6a1b2"
}

POST/v1/discover/superlike

scope: discoveryStarter

Super-like a profile (premium action). Requires Basic tier or above. Limited daily quota. Matches from superlikes are tagged with type "superlike" in webhooks.

Request

curl -X POST "https://loveconnet.com/api/v1/discover/superlike" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..." \
  -H "Content-Type: application/json" \
  -d '{ "target_user_id": "clx4ghi5jkl6" }'

Response

json{
  "superliked": true,
  "is_match": false,
  "quota": { "remaining": 4, "limit": 5 },
  "request_id": "req_d4e5f6a1b2c3"
}

GET/v1/discover/matches

scope: discoveryFree

Retrieve all mutual matches for the authenticated user. Supports cursor-based pagination. Returns matched profiles with match type (like/superlike) and timestamp.

Request

curl -X GET "https://loveconnet.com/api/v1/discover/matches" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "data": [
    {
      "user_id": "clx4ghi5jkl6",
      "name": "Ama",
      "photos": [{ "url": "https://cdn.loveconnet.com/..." }],
      "verifications": { "face": true, "id": false, "photo": false },
      "matched_at": "2026-05-05T20:00:00.000Z",
      "match_type": "like"
    }
  ],
  "pagination": {
    "cursor": "2026-05-05T20:00:00.000Z",
    "has_more": false,
    "limit": 20
  },
  "request_id": "req_e5f6a1b2c3d4"
}

POST/v1/discover/undo

scope: discoveryFree

Undo the last like or pass action within a 30-second window. Only the most recent action can be undone. Returns 400 if the window has expired or no action is pending.

Request

curl -X POST "https://loveconnet.com/api/v1/discover/undo" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "undone": true,
  "action": "like",
  "target_user_id": "clx4ghi5jkl6",
  "request_id": "req_f6a1b2c3d4e5"
}

Safety & Analytics

Report, block, and monitor discovery analytics for your app.

POST/v1/discover/report

scope: discoveryFree

Report a profile for policy violations. Valid reasons: fake_profile, inappropriate_content, harassment, spam, underage, scam, other. Triggers a user.safety_flagged webhook to your app.

Request

curl -X POST "https://loveconnet.com/api/v1/discover/report" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..." \
  -H "Content-Type: application/json" \
  -d '{ "target_user_id": "clx4ghi5jkl6", "reason": "fake_profile", "details": "Profile uses stock photos" }'

Response

json{
  "reported": true,
  "message": "Report submitted. Our safety team will review within 24 hours.",
  "request_id": "req_a1b2c3d4e5f6"
}

POST/v1/discover/block

scope: discoveryFree

Block a user. They will be permanently excluded from this user's discovery feed and match results for this app.

Request

curl -X POST "https://loveconnet.com/api/v1/discover/block" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..." \
  -H "Content-Type: application/json" \
  -d '{ "target_user_id": "clx4ghi5jkl6" }'

Response

json{
  "blocked": true,
  "message": "User blocked. They will no longer appear in your discovery feed.",
  "request_id": "req_b2c3d4e5f6a1"
}

GET/v1/discover/stats

scope: None (API key only)Free

Returns today's aggregated discovery analytics for your app: profiles browsed, likes, passes, superlikes, matches, reports, with computed like rate and match rate percentages. API key only — no user token needed.

Request

curl -X GET "https://loveconnet.com/api/v1/discover/stats" \
  -H "X-API-Key: lc_live_xxx" \
  -H "X-User-Token: eyJ..."

Response

json{
  "period": "today",
  "date": "2026-05-05",
  "metrics": {
    "profiles_browsed": 1250,
    "likes": 340,
    "passes": 780,
    "superlikes": 45,
    "matches": 28,
    "reports": 3,
    "like_rate_percent": 27,
    "match_rate_percent": 8
  },
  "request_id": "req_c3d4e5f6a1b2"
}

Discovery Quotas by Tier

Action	Free	Starter	Pro
Browse (discover)	150/day	500/day	2,000/day
Like	50/day	200/day	1,000/day
Pass	100/day	500/day	2,000/day
Superlike	—	5/day	25/day
Report	10/day	25/day	100/day
Block	20/day	50/day	200/day

Discovery Webhooks

Configure webhook URLs in your Developer Portal to receive real-time events:

Event	Trigger	Payload
match.created	Both users liked each other	user_a_id, user_b_id, matched_at, type
user.safety_flagged	A user was reported	reported_user_id, reporter_id, reason

API Keys

How API key authentication works

Every API request requires an API key in the X-API-Key header. Keys are generated from the Developer Portal and are tied to a specific app.

lc_live_*Production keys — real user data, rate limits enforced, usage counts toward your tier quota.

lc_test_*Test keys — sandbox environment, mock data, no rate limits. Perfect for development.

Security: API keys are hashed with Argon2id and stored securely. We never store the raw key — if you lose it, generate a new one. Never expose keys in frontend code; use them server-side only.

Pricing & Tiers

Affordable plans for every developer

Free

$0forever

5,000 calls/month

Profile, email, verified scopes

User interests API

Moderation categories

2 API keys

Community support

POPULAR

Starter

$3/month

50,000 calls/month

All Free features

+ Trust scores, safety scores

Text moderation & bot detection

Compatibility scoring

5 API keys

Email support

Pro

$9/month

500,000 calls/month

All Starter features

+ GPT-4o image moderation

Conversation analysis

Content screening APIs

Webhooks

20 API keys

Priority support

Error Handling

Standardized error responses with semantic codes and request IDs

All errors return a standardized JSON body with a semantic code, human-readable message, and a unique request_id for debugging:

json{
  "error": {
    "code": "FORBIDDEN",
    "message": "Scope 'trust_score' is required for this endpoint.",
    "status": 403,
    "request_id": "req_a1b2c3d4e5f6g7h8",
    "docs_url": "https://loveconnet.com/developers/docs#errors"
  }
}

Status	Code	When
400	BAD_REQUEST	Missing params, invalid PKCE, or malformed body
401	UNAUTHORIZED	Missing/invalid API key or expired user token
402	TIER_UPGRADE_REQUIRED	Endpoint requires a higher tier
403	FORBIDDEN	Insufficient scope or app suspended
409	CONFLICT	Idempotency key reused with different params
429	RATE_LIMIT_EXCEEDED	Respect the Retry-After header
500	INTERNAL_ERROR	Our fault — auto-retried by SDKs

Tip: Every response includes an X-Request-ID header. Include it when contacting support for faster debugging.

Rate Limits

Fair usage policies per tier

Rate limits are enforced per API key using Redis-backed distributed counters. When you exceed your limit, you'll receive a 429 response with a Retry-After header indicating seconds until reset.

Global Rate Limits

Tier	Calls/month	Burst/min	Keys	Auths/month
Free	5,000	60/min	2	1,000
Starter	50,000	300/min	5	25,000
Pro	500,000	1,000/min	20	250,000
Enterprise	Unlimited	5,000/min	Unlimited	Unlimited

Per-Endpoint Rate Limits

Endpoint Category	Free	Starter	Pro
Identity (profile, email, verified)	60/min	300/min	1,000/min
Trust & Safety scores	30/min	150/min	500/min
Content moderation (image)	10/min	60/min	300/min
Content moderation (text)	30/min	150/min	500/min
Discovery (browse/like/pass)	60/min	300/min	1,000/min
Groups (discover/search)	60/min	300/min	1,000/min
Reels (feed/trending)	60/min	300/min	1,000/min
Livestream (browse/join)	60/min	300/min	1,000/min
OAuth (token/authorize)	20/min	100/min	500/min

Rate Limit Headers

Every response includes rate limit information in headers:

httpX-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1714934400
Retry-After: 42  ← only on 429 responses

Our SDKs (Python, PHP, JS) include automatic retry with exponential backoff for 429 and 5xx responses. Enterprise customers can request custom rate limits.

Security

Enterprise-grade security by default

PKCE Required

S256 code challenges are mandatory on every authentication flow. This prevents authorization code interception even on public clients.

Argon2id Key Hashing

API keys are hashed with Argon2id (winner of the Password Hashing Competition). We never store raw keys.

No Raw Sensitive Data

Trust scores return brackets (EXCELLENT/GOOD), not numbers. Ages return ranges (25-34), never exact dates of birth.

TLS 1.3 Only

All API communication is encrypted with TLS 1.3. Older protocols are rejected at the edge.

Token Audience Binding

Access tokens are bound to your app's client_id. Tokens issued to other apps are rejected.

Automatic Key Expiry

API keys expire after 365 days. You'll receive an email 30 days before expiry to rotate them.

API Versioning

Stability guarantees and deprecation policy

The LoveConnet API uses URI-based versioning. The current stable version is v1. All endpoints are prefixed with /api/v1/.

Stability Guarantees

✓Breaking changes will never be made to a stable version without a new version number

✓New fields may be added to responses (always additive, never removing)

✓New optional parameters may be added to requests

✓New endpoints may be added to existing versions

Deprecation Policy

Phase	Timeline	Action
Announcement	Day 0	Deprecation notice published on Changelog + email to all developers
Warning Headers	Day 0+	Sunset and Deprecation headers added to all deprecated endpoints
Migration Guide	Within 30 days	Detailed migration guide published with code examples
Sunset	12 months minimum	Deprecated version returns 410 Gone — migrate by this date

Deprecation Headers

httpDeprecation: true
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://loveconnet.com/developers/docs/migration/v2>; rel="successor-version"

Pagination

Three pagination patterns used across the API

Different endpoints use different pagination strategies depending on the data characteristics. All paginated responses include a pagination object.

1. Signed Page TokensDiscovery profiles

Used for browsable feeds. Tokens are cryptographically signed JWTs containing the page offset and filter state, preventing index manipulation and scraping.

http// Request
GET /v1/discover/profiles?limit=10

// Response — first page
{
  "pagination": {
    "page_token": "eyJ0eXAiOiJKV1Qi...",
    "has_more": true,
    "limit": 10
  }
}

// Request — next page
GET /v1/discover/profiles?limit=10&page_token=eyJ0eXAiOiJKV1Qi...

2. Cursor-BasedMatches, comments

Used for time-ordered lists. The cursor is a timestamp or ID marking your position. Ideal for real-time data where new items may be inserted.

http// Request
GET /v1/discover/matches?limit=20

// Response
{
  "pagination": {
    "cursor": "2026-05-05T20:00:00.000Z",
    "has_more": true,
    "limit": 20
  }
}

// Request — next page
GET /v1/discover/matches?limit=20&cursor=2026-05-05T20:00:00.000Z

3. Offset-BasedReels, streams, groups

Classic page + limit pagination. Simple and predictable. Used for feeds where total count and page jumping are useful.

http// Request
GET /v1/reels/feed?page=1&limit=10

// Response
{
  "pagination": {
    "page": 1,
    "limit": 10,
    "has_more": true
  }
}

// Request — next page
GET /v1/reels/feed?page=2&limit=10

Webhooks

Real-time event notifications for your integration

Webhooks let your app receive real-time notifications when events happen on the LoveConnet platform. Configure webhook endpoints in the Developer Portal under your app's settings.

How Webhooks Work

1. Register
Add a webhook URL + select events in the portal

2. Receive Secret
You get an HMAC-SHA256 secret for signature verification

3. Get Events
We POST JSON to your URL when events fire

4. Verify & ACK
Verify the signature, respond with 2xx

Event Types (20 events)

Event	Category	When it fires
consent.granted	Consent	User grants OAuth consent to your app
consent.revoked	Consent	User revokes your app access
consent.scopes_updated	Consent	User modifies granted scopes
user.verified	User	User completes face or ID verification
user.trust_updated	User	User's trust bracket changes
user.profile_updated	User	User updates profile fields
user.deactivated	User	User deactivates their account
user.reactivated	User	User reactivates their account
user.photo_moderated	User	Photo approved/rejected by moderation
user.safety_flagged	User	User flagged by safety system
match.created	Matching	Mutual like detected — match created
match.expired	Matching	Match expired (no conversation started)
match.unmatched	Matching	User unmatched from a connection
chat.message_sent	Chat	New message in a matched conversation
chat.message_flagged	Chat	Message flagged by safety AI
app.tier_changed	Billing	Your app tier upgraded/downgraded
app.usage_threshold	Billing	Usage hit 80% or 100% of tier limit
app.rate_limited	Billing	Rate limit triggered on your API key
webhook.disabled	System	Webhook auto-disabled after failures
test.ping	System	Manual test ping from the portal

Webhook Payload Format

json{
  "id": "evt_a1b2c3d4e5f6g7h8",
  "event": "user.verified",
  "api_version": "v1",
  "created_at": "2026-05-05T20:30:00Z",
  "data": {
    "user_id": "clx1abc2def3",
    "verification_type": "face",
    "verified_at": "2026-05-05T20:30:00Z"
  }
}

Signature Verification

Every webhook request includes an X-LoveConnet-Signature header containing the HMAC-SHA256 signature of the request body, signed with your webhook secret.

javascriptconst crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your endpoint handler:
const isValid = verifyWebhook(
  JSON.stringify(req.body),
  req.headers['x-loveconnet-signature'],
  process.env.WEBHOOK_SECRET
);
if (!isValid) return res.status(401).send('Invalid signature');

Retry Policy

Timeout10 seconds per delivery attempt

Retries5 attempts with exponential backoff (1s, 5s, 30s, 2m, 15m)

Auto-offWebhook auto-disabled after 100 consecutive failures

LogsLast 20 delivery attempts visible in the Developer Portal

Groups API

Integrate LoveConnet community groups into your app

What is the Groups API?

Browse and join LoveConnet interest-based groups. Users can discover groups by location, search by topic, view details, and join/leave groups — all through your app.

Scope: groups • Base path: /v1/groups

GET/v1/groups/categories

scope: groupsFree

List all available group categories (e.g. Fitness, Travel, Music, Photography). Use to populate category filter UIs.

Response

json{
  "data": [
    { "id": "fitness", "name": "Fitness", "slug": "fitness", "group_count": 450 },
    { "id": "travel", "name": "Travel", "slug": "travel", "group_count": 320 },
    { "id": "music", "name": "Music", "slug": "music", "group_count": 280 }
  ],
  "request_id": "req_a1b2c3d4e5f6"
}

GET/v1/groups/discover

scope: groupsFree

Discover groups by location. Pass lat/lng to find nearby groups. Returns groups sorted by relevance and activity.

Response

json{
  "data": [
    {
      "group_id": "grp_abc123",
      "name": "Accra Hikers",
      "description": "Weekly hiking adventures around Ghana",
      "category": "fitness",
      "member_count": 45,
      "type": "PUBLIC",
      "city": "Accra",
      "avatar_url": "https://cdn.loveconnet.com/..."
    }
  ],
  "request_id": "req_b2c3d4e5f6a1"
}

GET/v1/groups/search

scope: groupsFree

Search groups by name or topic. Supports optional category filter. Query must be at least 2 characters.

Response

json{
  "data": [...],
  "query": "hiking",
  "request_id": "req_c3d4e5f6a1b2"
}

GET/v1/groups/:groupId

scope: groupsFree

Get complete details for a specific group including name, description, member count, rules, and creator info.

Response

json{
  "data": {
    "group_id": "grp_abc123",
    "name": "Accra Hikers",
    "description": "Weekly hiking adventures",
    "category": "fitness",
    "member_count": 45,
    "max_members": 100,
    "type": "PUBLIC",
    "is_private": false,
    "approval_required": false,
    "city": "Accra",
    "tags": ["hiking", "outdoors", "fitness"],
    "created_at": "2026-01-15T10:00:00Z"
  },
  "request_id": "req_d4e5f6a1b2c3"
}

POST/v1/groups/:groupId/join

scope: groupsFree

Join a group on behalf of the authenticated user. Some groups require approval — in that case, a join request is submitted.

Response

json{
  "joined": true,
  "request_id": "req_e5f6a1b2c3d4"
}

POST/v1/groups/:groupId/leave

scope: groupsFree

Leave a group on behalf of the authenticated user.

Response

json{
  "left": true,
  "request_id": "req_f6a1b2c3d4e5"
}

GET/v1/groups/:groupId/members

scope: groupsFree

List members of a group with roles (ADMIN, MODERATOR, MEMBER) and join timestamps.

Response

json{
  "data": [
    { "user_id": "clx1abc2def3", "name": "Sarah", "role": "ADMIN", "joined_at": "2026-01-15T10:00:00Z" },
    { "user_id": "clx4ghi5jkl6", "name": "Ama", "role": "MEMBER", "joined_at": "2026-02-20T14:30:00Z" }
  ],
  "total": 45,
  "request_id": "req_a2b3c4d5e6f7"
}

Reels API

Short-form dating video content

What is the Reels API?

Access LoveConnet's TikTok-style dating reels. Browse feeds, get trending content, discover nearby creators, view chemistry scores, and interact with likes and views.

Scope: reels • Base path: /v1/reels • Pagination: offset-based

GET/v1/reels/feed

scope: reelsFree

Personalized reel feed for the authenticated user. Supports page, limit, type filter, and sort_by options. Returns video URLs, creator info, and engagement stats.

Response

json{
  "data": [
    {
      "reel_id": "reel_xyz789",
      "video_url": "https://cdn.loveconnet.com/reels/...",
      "thumbnail_url": "https://cdn.loveconnet.com/thumbs/...",
      "caption": "Morning hike vibes ⛰️",
      "creator": {
        "user_id": "clx1abc2def3",
        "name": "Sarah",
        "face_verified": true
      },
      "stats": { "views": 1250, "likes": 340, "comments": 28 },
      "created_at": "2026-05-05T08:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "has_more": true },
  "request_id": "req_a1b2c3d4e5f6"
}

GET/v1/reels/trending

scope: reelsFree

Trending reels ranked by engagement velocity. Great for discovery features.

Response

json{
  "data": [...],
  "pagination": { "page": 1, "limit": 10, "has_more": true },
  "request_id": "req_b2c3d4e5f6a1"
}

GET/v1/reels/nearby

scope: reelsFree

Reels from creators near the user. Accepts radius_km parameter (default 50km).

Response

json{
  "data": [...],
  "radius_km": 50,
  "pagination": { "page": 1, "limit": 10, "has_more": true },
  "request_id": "req_c3d4e5f6a1b2"
}

GET/v1/reels/:id

scope: reelsFree

Get full details for a single reel including video URL, creator, stats, music track, and category.

Response

json{
  "data": {
    "reel_id": "reel_xyz789",
    "video_url": "https://cdn.loveconnet.com/reels/...",
    "caption": "Morning hike ⛰️",
    "creator": { "user_id": "clx1abc2def3", "name": "Sarah" },
    "stats": { "views": 1250, "likes": 340, "comments": 28 },
    "music": { "title": "Essence", "artist": "Wizkid" },
    "created_at": "2026-05-05T08:00:00Z"
  },
  "request_id": "req_d4e5f6a1b2c3"
}

GET/v1/reels/:id/chemistry

scope: reelsStarter

Get the chemistry/compatibility score between the authenticated user and the reel creator. Powered by shared interests and behavioral signals.

Response

json{
  "data": {
    "score": 78,
    "factors": ["Shared interest: hiking", "Same city", "Similar age range"]
  },
  "request_id": "req_e5f6a1b2c3d4"
}

POST/v1/reels/:id/view

scope: reelsFree

Record that the user viewed a reel. Used for analytics and feed personalization.

Response

json{ "viewed": true, "request_id": "req_f6a1b2c3d4e5" }

POST/v1/reels/:id/like

scope: reelsFree

Like a reel. The creator receives a notification.

Response

json{ "liked": true, "request_id": "req_a2b3c4d5e6f7" }

POST/v1/reels/:id/unlike

scope: reelsFree

Remove a like from a reel.

Response

json{ "unliked": true, "request_id": "req_b3c4d5e6f7a8" }

Livestream API

Live video interactions and real-time engagement

What is the Livestream API?

Integrate LoveConnet live streaming into your app. Browse live streams, join as a viewer, interact via comments and reactions, send virtual gifts, and view stream analytics.

Scope: livestream • Base path: /v1/streams • Pagination: offset-based

GET/v1/streams

scope: livestreamFree

Browse live streams with optional filters: status (LIVE, SCHEDULED, ENDED), category, page, limit. Default shows currently live streams.

Response

json{
  "data": [
    {
      "stream_id": "str_abc123",
      "title": "Friday Night Q&A",
      "status": "LIVE",
      "category": "JUST_CHATTING",
      "host": { "user_id": "clx1abc2def3", "name": "Sarah", "face_verified": true },
      "viewer_count": 127,
      "thumbnail_url": "https://cdn.loveconnet.com/...",
      "started_at": "2026-05-05T20:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "has_more": true },
  "request_id": "req_a1b2c3d4"
}

GET/v1/streams/categories

scope: livestreamFree

List all available stream categories with names and emoji icons. Use to populate category filters.

Response

json{
  "data": [
    { "id": "JUST_CHATTING", "name": "Just Chatting", "emoji": "💬" },
    { "id": "SPEED_DATING", "name": "Speed Dating", "emoji": "⚡" },
    { "id": "Q_AND_A", "name": "Q&A", "emoji": "❓" },
    { "id": "MUSIC", "name": "Music & Karaoke", "emoji": "🎵" }
  ],
  "request_id": "req_b2c3d4e5"
}

GET/v1/streams/:streamId

scope: livestreamFree

Get complete details for a specific stream including host info, viewer count, status, category, and replay availability.

Response

json{
  "data": {
    "stream_id": "str_abc123",
    "title": "Friday Night Q&A",
    "description": "Ask me anything about dating in Accra!",
    "status": "LIVE",
    "category": "Q_AND_A",
    "host": { "user_id": "clx1abc2def3", "name": "Sarah", "face_verified": true },
    "viewer_count": 127,
    "has_replay": true,
    "started_at": "2026-05-05T20:00:00Z"
  },
  "request_id": "req_c3d4e5f6"
}

POST/v1/streams/:streamId/join

scope: livestreamFree

Join a live stream as a viewer. Returns connection info needed to render the stream.

Response

json{
  "joined": true,
  "viewer_count": 128,
  "request_id": "req_d4e5f6a1"
}

POST/v1/streams/:streamId/leave

scope: livestreamFree

Leave a live stream gracefully. Decrements viewer count.

Response

json{ "left": true, "request_id": "req_e5f6a1b2" }

GET/v1/streams/:streamId/comments

scope: livestreamFree

Get live comments for a stream. Accepts limit parameter (default 50). Returns threaded comments with user info.

Response

json{
  "data": [
    {
      "comment_id": "cmt_abc123",
      "user_id": "clx4ghi5jkl6",
      "user_name": "Ama",
      "content": "Great advice! 🙌",
      "created_at": "2026-05-05T20:15:00Z"
    }
  ],
  "request_id": "req_f6a1b2c3"
}

POST/v1/streams/:streamId/comment

scope: livestreamFree

Post a live comment. Supports threaded replies via optional parent_id.

Response

json{
  "data": { "comment_id": "cmt_xyz789", "content": "Love this stream!" },
  "request_id": "req_a2b3c4d5"
}

POST/v1/streams/:streamId/react

scope: livestreamFree

Send a real-time reaction to the stream (❤️, 🔥, 😂, 😍, 👏, 🎉, 💯, 🥳). Reactions are broadcast to all viewers.

Response

json{ "reacted": true, "type": "🔥", "request_id": "req_b3c4d5e6" }

GET/v1/streams/gifts/catalog

scope: livestreamFree

Browse the virtual gift catalog with prices, animations, and categories.

Response

json{
  "data": [
    { "id": "rose", "name": "Rose", "emoji": "🌹", "price_coins": 10, "category": "classic" },
    { "id": "crown", "name": "Crown", "emoji": "👑", "price_coins": 500, "category": "premium" }
  ],
  "request_id": "req_c4d5e6f7"
}

POST/v1/streams/:streamId/gift

scope: livestreamStarter

Send a virtual gift to the streamer. Requires sufficient coin balance. Supports quantity and optional message.

Response

json{
  "sent": true,
  "gift": "rose",
  "quantity": 1,
  "coins_spent": 10,
  "request_id": "req_d5e6f7a8"
}

Status API

System health, readiness, and uptime monitoring

What is the Status API?

Monitor the LoveConnet API health in real-time. Use these endpoints for load balancer readiness probes, uptime dashboards, and alerting integrations. No API key required.

Base path: /health • No authentication required

GET/health

Public

Deep health check returning system status, component health (database, Redis, memory), response time, uptime, and API version. Use for status page dashboards.

Response

json{
  "status": "healthy",
  "timestamp": "2026-05-05T21:00:00.000Z",
  "uptime": 864000,
  "version": "1.0.0",
  "checks": {
    "database": { "status": "pass", "latency_ms": 3 },
    "redis": { "status": "pass", "latency_ms": 1 },
    "memory": { "status": "pass", "latency_ms": 0, "message": "245MB / 512MB (48%)" }
  },
  "response_time_ms": 5
}

GET/health/ready

Public

Readiness probe for load balancers. Returns 200 when the service can accept traffic (database & Redis reachable). Use as K8s/ECS readiness check.

Response

json{ "status": "ready", "ready": true }

GET/health/live

Public

Liveness probe. Returns 200 if the process is running. No dependency checks — used by container orchestrators to detect hangs.

Response

json{ "status": "alive", "alive": true, "uptime": 864000, "pid": 12345 }

GET/health/stats

Public

Detailed runtime stats: uptime, memory usage (RSS, heap), Node.js version, and environment. Great for ops dashboards.

Response

json{
  "uptime_seconds": 864000,
  "uptime_formatted": "10d 0h 0m 0s",
  "memory": {
    "rss_mb": 312,
    "heap_used_mb": 245,
    "heap_total_mb": 512
  },
  "node_version": "v20.11.0",
  "environment": "production"
}

Status Values

healthyAll systems operational

degradedOne or more components reporting warnings (slow latency, high memory)

unhealthyCritical component failure (database or Redis unreachable)

Developer Portal API

Manage your apps, API keys, webhooks, and domain verification

What is the Developer Portal API?

Programmatically manage your entire developer lifecycle: register apps, rotate secrets, generate API keys, configure webhooks, and verify custom domains. All endpoints require JWT authentication as the app owner.

Base path: /developer • Auth: JWT (app owner) • Rate limited: 20/min

App Management

GET/developer/apps

All

List all your registered apps with pagination. Returns client IDs, names, status, redirect URIs, and creation dates.

json{
  "apps": [
    {
      "clientId": "lc_app_abc123",
      "name": "My Dating Widget",
      "status": "ACTIVE",
      "tier": "PRO",
      "redirectUris": ["https://myapp.com/callback"],
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

POST/developer/apps

All

json{
  "clientId": "lc_app_abc123",
  "clientSecret": "lc_secret_xyz...(shown once)",
  "name": "My Dating Widget",
  "redirectUris": ["https://myapp.com/callback"],
  "allowedScopes": ["profile", "trust"],
  "status": "ACTIVE"
}

PUT/developer/apps/:clientId

All

Update an app's name, logo, website, privacy policy, terms of service, redirect URIs, or allowed scopes.

json{ "updated": true, "clientId": "lc_app_abc123" }

DELETE/developer/apps/:clientId

All

Delete an app permanently. All API keys and webhooks are revoked. This cannot be undone.

json{ "deleted": true }

POST/developer/apps/:clientId/rotate-secret

All

Rotate the client secret. The old secret is immediately invalidated. The new secret is shown only once.

json{
  "clientId": "lc_app_abc123",
  "newSecret": "lc_secret_new...(shown once)",
  "rotatedAt": "2026-05-05T21:00:00Z"
}

API Key Management

POST/developer/apps/:clientId/keys

All

Generate a new API key for an app. Supports test and live modes. The full key is shown only once.

json{
  "keyId": "key_abc123",
  "apiKey": "lc_live_sk_...(shown once)",
  "name": "Production Key",
  "isLive": true,
  "createdAt": "2026-05-05T21:00:00Z"
}

GET/developer/apps/:clientId/keys

All

List all API keys for an app. Keys are masked (only last 4 chars shown).

json{
  "keys": [
    { "keyId": "key_abc123", "name": "Production", "maskedKey": "...x7f2", "isLive": true, "createdAt": "2026-05-05" },
    { "keyId": "key_def456", "name": "Test", "maskedKey": "...a3b1", "isLive": false, "createdAt": "2026-04-20" }
  ]
}

DELETE/developer/apps/:clientId/keys/:keyId

All

Revoke an API key immediately. All requests using this key will return 401.

json{ "revoked": true, "keyId": "key_abc123" }

Webhook Management

POST/developer/apps/:clientId/webhook

All

Configure a webhook endpoint for an app. Specify the URL and which events to subscribe to.

json{
  "webhookId": "wh_abc123",
  "url": "https://myapp.com/webhooks/loveconnet",
  "events": ["user.verified", "consent.revoked", "match.created"],
  "secret": "whsec_...(shown once)",
  "status": "ACTIVE"
}

GET/developer/webhooks

All

List all configured webhooks for your apps with status and event subscriptions.

json{
  "webhooks": [
    { "webhookId": "wh_abc123", "url": "https://myapp.com/...", "events": ["user.verified"], "status": "ACTIVE", "lastDeliveredAt": "2026-05-05T20:30:00Z" }
  ]
}

POST/developer/webhooks/test

All

Send a test.ping event to a webhook endpoint to verify it's receiving events correctly.

json{
  "delivered": true,
  "statusCode": 200,
  "responseTimeMs": 142
}

GET/developer/webhooks/logs

All

View the last 20 webhook delivery attempts with status codes, response times, and retry counts.

json{
  "logs": [
    {
      "eventId": "evt_abc123",
      "event": "user.verified",
      "statusCode": 200,
      "responseTimeMs": 85,
      "attempt": 1,
      "deliveredAt": "2026-05-05T20:30:00Z"
    }
  ]
}

Domain Verification

Verify ownership of your domain to enable Verified Badge embeds and higher trust levels. Two methods supported: DNS TXT record or file-based verification.

POST/developer/apps/:clientId/domain/challenge

Generate a domain verification challenge. Returns a unique token and instructions for both DNS and file verification methods.

json{
  "challenge": "loveconnet-verify=lc_v_abc123xyz789",
  "methods": {
    "dns": {
      "type": "TXT",
      "host": "_loveconnet-verify.myapp.com",
      "value": "lc_v_abc123xyz789"
    },
    "file": {
      "path": "/.well-known/loveconnet-verify.txt",
      "content": "lc_v_abc123xyz789"
    }
  },
  "expiresAt": "2026-05-12T21:00:00Z"
}

POST/developer/apps/:clientId/domain/verify

Attempt to verify your domain using the specified method (dns or file). On success, your app gets a verified domain badge.

json{
  "verified": true,
  "domain": "myapp.com",
  "verifiedAt": "2026-05-05T21:00:00Z",
  "method": "dns"
}

Analytics & Usage

GET/developer/apps/:clientId/analytics

Get aggregated analytics for your app: total API calls, unique users, consent grants, and error rates.

json{
  "totalCalls": 42500,
  "uniqueUsers": 1240,
  "consentGrants": 890,
  "errorRate": 0.02,
  "topEndpoints": [
    { "endpoint": "discover.profiles", "calls": 15000 },
    { "endpoint": "reels.feed", "calls": 8500 }
  ]
}

GET/developer/apps/:clientId/usage

Get detailed usage breakdown by day for the last N days (default 30). Shows per-endpoint call counts.

json{
  "usage": {
    "2026-05-05": { "discover.profiles": 500, "reels.feed": 300 },
    "2026-05-04": { "discover.profiles": 480, "reels.feed": 290 }
  },
  "total": 42500,
  "limit": 500000,
  "percentUsed": 8.5
}

GET/developer/apps/:clientId/audit-logs

View audit trail of all management actions: key rotations, webhook changes, scope updates, tier changes, etc.

json{
  "logs": [
    {
      "action": "API_KEY_GENERATED",
      "userId": "clx1abc2def3",
      "timestamp": "2026-05-05T21:00:00Z",
      "metadata": { "keyName": "Production" }
    }
  ],
  "total": 45
}

Billing & Metered Pricing

Stripe/Paystack integration, per-call metered rates, and subscription management

How Billing Works

LoveConnet uses a base tier + metered overage model (like Stripe). You choose a tier for included API calls. Each call beyond the included quota is billed per-call at metered rates. Two payment gateways supported: Stripe (USD, international) and Paystack (GHS, Ghana).

Tier Pricing (Base Subscription)

Tier	Price (USD)	Price (GHS)	Calls/month	API Keys	AI Calls
Free	$0	GH₵ 0	1,000	2	0
Growth	$49/mo	GH₵ 735/mo	10,000	5	500
Business	$199/mo	GH₵ 2,985/mo	100,000	20	5,000
Scale	$499/mo	GH₵ 7,485/mo	1,000,000	50	25,000
Enterprise	$1,999/mo	GH₵ 29,985/mo	10,000,000	200	100,000

Metered Per-Call Rates (Overage)

When you exceed your tier's included calls, each additional call is billed at metered rates. Pro and Enterprise tiers use metered billing automatically.

Category	Endpoints	Rate (per call)
Basic	profile, email, verified, trust, age, userinfo	Free
AI Compatibility	ai/compatibility, ai/icebreakers	$0.02
AI Moderation	ai/moderate-image, ai/moderate-text	$0.05 / $0.005
AI Fraud & Safety	ai/fraud-score, ai/safety-score	$0.05 / $0.03
AI Profile	ai/profile-analysis, ai/face-detect	$0.03
AI Coaching	ai/dating-advice, ai/smart-replies	$0.01
AI Insights	ai/conversation-insights, ai/weekly-insights	$0.02
Discovery	discover.profiles, discover.like, discover.pass	$0.01
Groups/Reels/Streams	groups., reels., streams.*	Free

Billing Endpoints

GET/developer/billing/subscription

Get current subscription tier, status, gateway (Stripe/Paystack), usage, and renewal date.

json{
  "tier": "PRO",
  "status": "ACTIVE",
  "gateway": "stripe",
  "currentUsage": 42500,
  "limit": 500000,
  "percentUsed": 8.5,
  "renewsAt": "2026-06-05T00:00:00Z",
  "meteredCostThisMonth": { "totalCents": 450, "breakdown": { "basic": 320, "ai": 100, "matching": 30 } }
}

GET/developer/billing/tiers

List all available tiers with pricing, limits, and features. Use to display upgrade cards in your portal.

json{
  "tiers": [
    { "id": "FREE", "name": "Free", "priceCents": 0, "callsPerMonth": 5000, "maxKeys": 2 },
    { "id": "STARTER", "name": "Starter", "priceCents": 900, "callsPerMonth": 50000, "maxKeys": 5 },
    { "id": "PRO", "name": "Pro", "priceCents": 2900, "callsPerMonth": 500000, "maxKeys": 20, "meteredBilling": true },
    { "id": "ENTERPRISE", "name": "Enterprise", "priceCents": 3900, "callsPerMonth": 5000000, "maxKeys": 100, "meteredBilling": true }
  ]
}

POST/developer/billing/checkout

Start a checkout session. Specify the tier, payment gateway (stripe or paystack), email, and success/cancel URLs. Returns a redirect URL.

json{
  "url": "https://checkout.stripe.com/pay/cs_live_...",
  "gateway": "stripe",
  "tier": "PRO",
  "expiresAt": "2026-05-05T22:00:00Z"
}

POST/developer/billing/cancel

Cancel your subscription. Access continues until the end of the current billing period, then downgrades to Free.

json{
  "cancelled": true,
  "effectiveAt": "2026-06-05T00:00:00Z",
  "message": "Your PRO plan will remain active until June 5, 2026"
}

GET/developer/billing/metered-rates

Get the per-call metered rate table used for overage billing on Pro and Enterprise tiers.

json{
  "rates": {
    "basic": { "description": "profile, email, trust", "centsPer100Calls": 10 },
    "content": { "description": "image moderation", "centsPer100Calls": 50 },
    "ai": { "description": "AI discovery, recommendations", "centsPer100Calls": 100 },
    "matching": { "description": "like, pass, compatibility", "centsPer100Calls": 100 },
    "verification": { "description": "safety, trust checks", "centsPer100Calls": 20 }
  }
}

Payment Gateway Webhooks

We handle Stripe and Paystack webhook callbacks to activate/deactivate subscriptions automatically. You don't need to integrate with these — they work behind the scenes.

POST /webhooks/developer/stripeHandles checkout.session.completed, customer.subscription.deleted

POST /webhooks/developer/paystackHandles charge.success, subscription.disable

Stripe-Style Features

Metered Billing

Pro/Enterprise tiers track every API call and bill overages at per-call rates. Usage is recorded in Redis and aggregated monthly.

Dual Gateway

Stripe (international, USD) and Paystack (Ghana, GHS) supported. Both use hosted checkout pages — no card data touches your servers.

Usage Alerts

Receive webhook events (app.usage_threshold) when you hit 80% and 100% of your tier limit. Configure thresholds in the portal.

Tier Auto-Downgrade

When a subscription is cancelled or payment fails, the app gracefully downgrades to Free at period end. No service disruption.

Revenue Share

Enterprise tier includes 3% revenue share on marketplace transactions made through your app.

Usage Dashboard

View per-endpoint call counts, daily usage charts, and cost breakdowns in the Developer Portal and via API.

AI API

Premium AI-powered dating intelligence endpoints

AI-Powered Dating Intelligence

12 premium AI endpoints powered by GPT-4o, AWS Rekognition, and custom ML models. All AI endpoints support sandbox mode (test keys return mock data), idempotency, and metered billing.

Base path: /v1/ai • Auth: X-API-Key + X-User-Token • Scope: ai

POST/v1/ai/compatibility

$0.02/call

AI-powered compatibility scoring between two users. Returns overall score, chemistry breakdown, explanation, and highlights.

Response

json{
  "data": {
    "overall_score": 87,
    "chemistry": 92,
    "explanation": "High compatibility based on shared interests",
    "highlights": ["Both enjoy hiking", "Similar communication styles"]
  },
  "request_id": "req_m1abc_x7f2k9"
}

POST/v1/ai/icebreakers

$0.01/call

Generate personalized conversation starters based on two user profiles. Optionally include reel context for targeted openers.

Response

json{
  "data": {
    "icebreakers": [
      "I noticed you are into hiking too - what is the most memorable trail?",
      "Your travel photos are amazing! Next dream destination?",
      "I see we both love sushi - favorite spot?"
    ]
  }
}

POST/v1/ai/smart-replies

$0.01/call

Generate contextual reply suggestions based on conversation history. Perfect for in-chat suggestion chips.

Response

json{
  "data": {
    "replies": [
      "That sounds amazing!",
      "I would love to hear more about that",
      "When are you free to meet up?"
    ]
  }
}

POST/v1/ai/profile-analysis

$0.03/call

Analyze a user profile and return a quality score with actionable improvement suggestions and strengths.

Response

json{
  "data": {
    "score": 72,
    "suggestions": ["Add more photos showing hobbies", "Bio could mention interests"],
    "strengths": ["Great smile", "Bio is authentic", "Verified profile"]
  }
}

POST/v1/ai/moderate-image

$0.05/call

Analyze an image for inappropriate content using GPT-4o vision. Returns safety classification across nudity, violence, hate, and spam.

Response

json{
  "data": {
    "safe": true,
    "confidence": 0.98,
    "categories": { "nudity": 0.01, "violence": 0.0, "hate": 0.0, "spam": 0.02 }
  }
}

POST/v1/ai/moderate-text

$0.005/call

Analyze text for toxicity, grooming patterns, and safety risks. Combines GPT-4o AI analysis with pattern-based scoring.

Response

json{
  "data": {
    "safe": true,
    "reason": null,
    "ai_confidence": 0.95,
    "patterns": { "score": 0, "indicators": [] }
  }
}

POST/v1/ai/fraud-score

$0.05/call

ML-powered fraud risk assessment. Returns risk score (0-100), risk level, contributing factors, and recommended action.

Response

json{
  "data": {
    "risk_score": 12,
    "risk_level": "LOW",
    "risk_factors": [],
    "recommended_action": "ALLOW",
    "confidence": 0.94,
    "model_version": "v2.1"
  }
}

POST/v1/ai/safety-score

$0.03/call

Comprehensive user safety score with trust badge and contributing factors. Use for trust badges in your app.

Response

json{
  "data": {
    "score": 92,
    "badge": "TRUSTED",
    "factors": [
      { "name": "Account age", "impact": 10, "detail": "6 months" },
      { "name": "Verified photo", "impact": 15, "detail": "Face verified" }
    ]
  }
}

POST/v1/ai/face-detect

$0.03/call

Detect and validate faces in photos using AWS Rekognition. Returns face count, quality assessment, and anti-spoofing signals.

Response

json{
  "data": {
    "valid": true,
    "faceCount": 1,
    "details": { "blur": "sharp", "occluded": false, "headPose": { "yaw": 2, "pitch": -1 } }
  }
}

POST/v1/ai/dating-advice

$0.01/call

AI relationship coach generates personalized dating tips based on user behavior and interaction patterns.

Response

json{
  "data": {
    "advice": [
      { "category": "profile", "title": "Photo Tip", "advice": "Add a photo showing hobbies", "relevance": 0.92 },
      { "category": "conversation", "title": "Ask Open Questions", "advice": "Try asking about experiences", "relevance": 0.87 }
    ]
  }
}

POST/v1/ai/conversation-insights

$0.02/call

Analyze all active conversations for health, engagement, tips, and suggested actions.

Response

json{
  "data": {
    "insights": [{
      "matchName": "Alex",
      "health": "thriving",
      "tips": ["Great energy! Keep asking thoughtful questions"],
      "suggestedActions": ["Plan a date!"]
    }]
  }
}

POST/v1/ai/weekly-insights

$0.02/call

Weekly summary: matching activity, message trends, peak hours, and personalized improvement tips.

Response

json{
  "data": {
    "week": "2026-W18",
    "matchingActivity": { "newMatches": 5, "messagesExchanged": 42 },
    "suggestions": ["Message earlier - matches respond fastest at 9am"],
    "personalizedTip": "Conversation quality improved 15% this week!"
  }
}

Sandbox Mode

Use a test API key (generated with isLive: false) to get realistic mock data from all endpoints. No real data is accessed, no AI costs are incurred, and usage is not billed. The response header X-Sandbox: true confirms sandbox mode.

Sandbox limits: 1,000 calls/day • Separate rate limit counters • All POST bodies accepted

Idempotency

All POST endpoints support the Idempotency-Key header. This ensures retries don't cause duplicate operations. Keys are cached for 24 hours.

bashcurl -X POST https://api.loveconnet.com/v1/ai/compatibility \
  -H "X-API-Key: lc_live_sk_xxx" \
  -H "Idempotency-Key: my-unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"user_id_1": "abc", "user_id_2": "def"}'

Replayed: Idempotency-Replayed: true header set on cached responses

Conflict: 409 returned if same key reused with different body

Format: Alphanumeric + dashes, max 255 characters

OpenAPI Specification

A full OpenAPI 3.0 JSON spec is available for auto-SDK generation, Postman import, and API documentation tools.

bashGET https://api.loveconnet.com/developer/openapi.json

Postman

Import → Link → paste URL

Auto SDK

Use openapi-generator-cli

Swagger UI

Point at /developer/openapi.json

Calls API

Audio and video calling with LiveKit WebRTC

Real-Time Audio & Video Calls

10 endpoints for 1:1 and group calling powered by LiveKit WebRTC. Start, answer, end, and schedule calls with full credential management for client-side integration.

Base path: /v1/calls • Auth: X-API-Key • Scope: calls

POST/v1/calls/start

$0.01

Start an audio or video call between matched users. Returns LiveKit token and room name.

Response

json{
  "data": {
    "id": "call_abc123",
    "matchId": "match_xyz",
    "callType": "VIDEO",
    "status": "RINGING",
    "token": "lk_token_xxx",
    "roomName": "room-abc123"
  }
}

POST/v1/calls/:id/answer

Free

Answer an incoming call. Returns LiveKit credentials for the receiver to join.

Response

json{
  "data": {
    "id": "call_abc123",
    "status": "CONNECTED",
    "token": "lk_token_yyy",
    "roomName": "room-abc123"
  }
}

POST/v1/calls/:id/end

Free

End an active call. Records duration and notifies both parties.

Response

json{
  "data": {
    "id": "call_abc123",
    "status": "COMPLETED",
    "duration": 185
  }
}

POST/v1/calls/:id/decline

Free

Decline an incoming call. Notifies the caller.

Response

json{
  "data": {
    "id": "call_abc123",
    "status": "DECLINED"
  }
}

GET/v1/calls/:id/credentials

Free

Get LiveKit WebRTC credentials for an ongoing call. Use when reconnecting.

Response

json{
  "data": {
    "token": "lk_token_xxx",
    "roomName": "room-abc123",
    "serverUrl": "wss://livekit.your-server.com"
  }
}

GET/v1/calls/history

Free

Get global call history. Filter by status; supports pagination via limit and offset.

Response

json{
  "data": {
    "calls": [
      { "id": "call_1", "callType": "VIDEO", "status": "COMPLETED", "duration": 342 },
      { "id": "call_2", "callType": "AUDIO", "status": "MISSED", "duration": 0 }
    ],
    "total": 24
  }
}

POST/v1/calls/:id/participants

$0.01

Add a participant to an existing call to upgrade to a group call.

Response

json{
  "data": {
    "callId": "call_abc123",
    "targetUserId": "user_456",
    "status": "INVITED"
  }
}

POST/v1/calls/schedule

Free

Schedule a future call. Supports repeating schedules and pre-call reminders.

Response

json{
  "data": {
    "id": "sched_001",
    "matchId": "match_xyz",
    "callType": "VIDEO",
    "scheduledAt": "2026-05-10T18:00:00Z",
    "status": "PENDING"
  }
}

GET/v1/calls/scheduled

Free

List all scheduled calls for a user.

Response

json{
  "data": {
    "scheduledCalls": [
      { "id": "sched_001", "scheduledAt": "2026-05-10T18:00:00Z", "callType": "VIDEO" }
    ]
  }
}

DELETE/v1/calls/scheduled/:id

Free

Cancel a scheduled call.

Response

json{
  "data": { "cancelled": true }
}

Video Dates

Scheduled video dates with chemistry ratings

Structured Video Dating

5 endpoints for managing video dates with scheduling, chemistry prompts, and post-date ratings. Build engaging video dating experiences with structured conversation prompts.

Base path: /v1/video-dates • Auth: X-API-Key • Scope: calls

POST/v1/video-dates

$0.01

Create a video date invitation. Supports scheduled dates and speed-date mode.

Response

json{
  "data": {
    "id": "vdate_001",
    "initiatorId": "user_1",
    "participantId": "user_2",
    "status": "PENDING",
    "isSpeedDate": false
  }
}

POST/v1/video-dates/:id/respond

Free

Accept or decline a video date invitation.

Response

json{
  "data": {
    "id": "vdate_001",
    "status": "ACCEPTED"
  }
}

POST/v1/video-dates/:id/rate

Free

Submit a chemistry rating and feedback after a video date.

Response

json{
  "data": {
    "rated": true,
    "chemistryRating": 4.5,
    "wouldMeetAgain": true
  }
}

GET/v1/video-dates/history

Free

Get the user's video date history with ratings and status.

Response

json{
  "data": {
    "dates": [
      { "id": "vdate_001", "status": "COMPLETED", "chemistryRating": 4.5, "wouldMeetAgain": true }
    ]
  }
}

GET/v1/video-dates/prompts

Free

Get chemistry conversation prompts for video dates. Use as ice-breaker cards during the call.

Response

json{
  "data": {
    "prompts": [
      { "category": "icebreaker", "prompt": "What made you swipe right on me?" },
      { "category": "deep", "prompt": "What does your ideal weekend look like?" },
      { "category": "fun", "prompt": "If you could teleport anywhere, where?" }
    ]
  }
}

SDKs & Libraries

Install our official TypeScript SDK for the fastest integration. Handles authentication, rate limits, retries, and TypeScript types out of the box.

Installation

bashnpm install @loveconnet/sdk

Quick Start

javascriptimport LoveConnet from '@loveconnet/sdk';

const lc = new LoveConnet({
  apiKey: 'lc_live_xxx',  // or lc_test_xxx for sandbox
});

// Scope to a specific user
const user = lc.forUser('user_jwt_token');

// AI Compatibility
const { data } = await user.ai.compatibility('user_123', 'user_456');
console.log(data.data.overall_score); // 87

// Image Moderation
const mod = await lc.ai.moderateImage('https://example.com/photo.jpg');
console.log(mod.data.data.safe); // true

Available Modules

Module	Methods	Description
`lc.ai`	12	Compatibility, moderation, fraud detection, dating advice
`lc.discovery`	6	Browse profiles, like, pass, super-like, matches
`lc.calls`	9	Start/answer/end calls, WebRTC credentials, scheduling
`lc.videoDates`	5	Create dates, respond, rate chemistry, prompts
`lc.health`	3	System health, readiness, liveness probes

Error Handling

javascriptimport { LoveConnetApiError } from '@loveconnet/sdk';

try {
  await user.ai.compatibility('a', 'b');
} catch (err) {
  if (err instanceof LoveConnetApiError) {
    console.log(err.code);    // 'RATE_LIMIT_EXCEEDED'
    console.log(err.status);  // 429
    console.log(err.message); // 'Monthly API call limit exceeded'
  }
}

Rate Limit Handling

javascriptconst lc = new LoveConnet({
  apiKey: 'lc_live_xxx',
  maxRetries: 3,
  onRateLimit: (retryAfter) => {
    console.log("Rate limited, retrying in " + retryAfter + "s");
  },
});

Error Code Registry

Complete machine-readable error catalog. Fetch programmatically via GET /developer/errors.

Authentication

Code	Status	Description
`MISSING_API_KEY`	401	No API key provided in X-API-Key header
`INVALID_API_KEY`	401	Key format is invalid (expected lc_live_* or lc_test_*)
`API_KEY_EXPIRED`	401	Key has passed its 90-day expiry
`API_KEY_REVOKED`	401	Key was manually revoked
`MISSING_USER_TOKEN`	401	X-User-Token required for user-scoped endpoints

Authorization

Code	Status	Description
`INSUFFICIENT_SCOPE`	403	Key lacks the required scope for this endpoint
`TIER_UPGRADE_REQUIRED`	403	Feature not available on your current tier
`APP_SUSPENDED`	403	Application suspended due to policy violations

Rate Limiting

Code	Status	Description
`RATE_LIMIT_EXCEEDED`	429	Monthly API call limit exceeded
`BURST_LIMIT_EXCEEDED`	429	Too many requests per second

Validation

Code	Status	Description
`INVALID_REQUEST`	400	Request body validation failed
`INVALID_USER_ID`	400	User ID is invalid or not found
`INVALID_MATCH_ID`	400	Match ID is invalid or not found
`INVALID_IMAGE_URL`	400	Image URL is invalid or inaccessible

Billing

Code	Status	Description
`SUBSCRIPTION_REQUIRED`	402	Active subscription required
`PAYMENT_FAILED`	402	Payment method failed
`METERED_QUOTA_EXCEEDED`	402	Metered usage quota exceeded

Server

Code	Status	Description
`INTERNAL_ERROR`	500	Internal server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable
`AI_SERVICE_ERROR`	502	AI provider did not respond in time

Programmatic access: Fetch the full catalog (with resolutions) via GET /api/developer/errors or the flat lookup via GET /api/developer/errors/codes.