Documentation Index
Fetch the complete documentation index at: https://docs.joinfindu.com/llms.txt
Use this file to discover all available pages before exploring further.
Matching Algorithm API Reference
The FindU matching API provides personalized college recommendations and manages student-school interactions.
Base URL
Production: https://findu-matching-production.up.railway.app
Development: https://findu-matching-development.up.railway.app
Authentication
All endpoints require a valid Supabase JWT token:
Authorization: Bearer YOUR_JWT_TOKEN
Endpoints
Get Recommendations
Retrieve personalized college recommendations for a student.
curl -X POST https://api.findu.app/recommendations \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"student_id": "123e4567-e89b-12d3-a456-426614174000",
"limit": 20,
"offset": 0
}'
Request Body
| Parameter | Type | Required | Description |
|---|
| student_id | string | Yes | UUID of the student |
| limit | integer | No | Number of recommendations (default: 20) |
| offset | integer | No | Pagination offset (default: 0) |
Response
{
"recommendations": [
{
"school_id": "456e7890-e89b-12d3-a456-426614174000",
"name": "Example University",
"match_score": 0.875,
"match_grade": "A",
"match_reasons": [
"Strong academic fit",
"Within your budget",
"Preferred location"
],
"components": {
"academic": 0.92,
"financial": 0.85,
"campus": 0.88,
"outcomes": 0.82
}
}
],
"metadata": {
"total_count": 150,
"learning_phase": "refinement",
"algorithm_version": "2.1.0"
}
}
Record Swipe
Record a student’s interaction with a school recommendation.
curl -X POST https://api.findu.app/swipe \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"student_id": "123e4567-e89b-12d3-a456-426614174000",
"school_id": "456e7890-e89b-12d3-a456-426614174000",
"direction": "right",
"interaction_type": "swipe",
"time_spent": 5.2
}'
Request Body
| Parameter | Type | Required | Description |
|---|
| student_id | string | Yes | UUID of the student |
| school_id | string | Yes | UUID of the school |
| direction | string | Yes | ”left” (dislike) or “right” (like) |
| interaction_type | string | No | Type of interaction (default: “swipe”) |
| time_spent | float | No | Seconds spent viewing |
Response
{
"success": true,
"swipe_count": 25,
"learning_phase": "refinement",
"ui_message": "Getting better at finding your matches!"
}
Get Match Details
Get detailed match information between a student and school.
curl -X GET "https://api.findu.app/match/123e4567-e89b-12d3-a456-426614174000/456e7890-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response
{
"overall_score": 0.875,
"grade": "A",
"components": {
"academic": {
"score": 0.92,
"factors": {
"sat_match": 0.95,
"selectivity_fit": 0.88,
"program_strength": 0.93
}
},
"financial": {
"score": 0.85,
"factors": {
"affordability": 0.82,
"aid_availability": 0.90,
"value_score": 0.83
}
}
},
"explanation": "This school is an excellent match based on your academic profile and preferences. The strong engineering program aligns with your interests, and the financial aid package makes it affordable."
}
Mobile-Optimized Endpoints
Compressed Recommendations
Get recommendations with compressed field names for mobile.
GET /m/recommendations/{student_id}
Response
{
"r": [
{
"i": "456e7890-e89b-12d3-a456-426614174000",
"n": "Example University",
"s": 87.5,
"g": "A",
"c": "Example City",
"st": "CA"
}
]
}
i = idn = names = scoreg = gradec = cityst = state
Batch School Fetch
Fetch multiple schools in one request.
Request Body
{
"school_ids": [
"456e7890-e89b-12d3-a456-426614174000",
"789a1234-e89b-12d3-a456-426614174000"
]
}
Minimal Onboarding API
Create Minimal Profile
Create a student profile with minimal information.
POST /v2/onboarding/minimal
Request Body
{
"name": "John Doe",
"email": "john@example.com",
"graduation_year": "2024",
"gpa": 3.8,
"test_scores": {
"sat": 1400
}
}
Get Category Schools
Get the 6 archetype schools for preference discovery.
GET /v2/onboarding/category-schools
Response
{
"categories": [
{
"id": "ivy-plus",
"name": "Ivy Plus",
"description": "Highly selective research universities",
"example_school": {
"name": "Harvard University",
"image_url": "https://..."
}
}
]
}
Error Handling
{
"error": {
"code": "INVALID_STUDENT_ID",
"message": "Student not found",
"details": {
"student_id": "123e4567-e89b-12d3-a456-426614174000"
}
}
}
Common Error Codes
| Code | Description |
|---|
| INVALID_STUDENT_ID | Student ID not found |
| INVALID_SCHOOL_ID | School ID not found |
| MISSING_PROFILE | Student profile incomplete |
| RATE_LIMITED | Too many requests |
| INTERNAL_ERROR | Server error |
Rate Limiting
- Recommendations: 60 requests per minute
- Swipes: 300 requests per minute
- Batch operations: 20 requests per minute
Headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200
Webhooks
Swipe Events
Configure webhooks to receive swipe events:
{
"event": "swipe.recorded",
"data": {
"student_id": "123e4567-e89b-12d3-a456-426614174000",
"school_id": "456e7890-e89b-12d3-a456-426614174000",
"direction": "right",
"timestamp": "2024-01-15T10:30:00Z"
}
}
SDK Examples
Python
from findu import MatchingClient
client = MatchingClient(api_key="YOUR_API_KEY")
# Get recommendations
recs = client.get_recommendations(
student_id="123e4567-e89b-12d3-a456-426614174000",
limit=20
)
# Record swipe
client.record_swipe(
student_id="123e4567-e89b-12d3-a456-426614174000",
school_id="456e7890-e89b-12d3-a456-426614174000",
direction="right"
)
TypeScript
import { FindUClient } from '@findu/sdk';
const client = new FindUClient({ apiKey: 'YOUR_API_KEY' });
// Get recommendations
const recs = await client.recommendations.get({
studentId: '123e4567-e89b-12d3-a456-426614174000',
limit: 20
});
// Record swipe
await client.swipes.record({
studentId: '123e4567-e89b-12d3-a456-426614174000',
schoolId: '456e7890-e89b-12d3-a456-426614174000',
direction: 'right'
});
