Endpoint
POST https://api.syncline.run/v1/availability
Request Body
Array of email addresses. Must be exactly 2 for MVP.["alice@example.com", "bob@example.com"]
Meeting duration in minutes. Min: 15, Max: 120.
Optional custom date range. Defaults to user’s availability_window_days preference (14 days).
ISO 8601 date: 2025-11-20
ISO 8601 date: 2025-12-04
Optional meeting context for better title generation.Example: "Introduction call after LinkedIn connection"
Response
Array of 5 time slots, ranked by quality (best first).
ISO 8601 datetime with timezone
ISO 8601 datetime with timezone
Quality score (0-1). Higher = better match.
Requester’s timezone (e.g., America/Los_Angeles)
Human-readable explanation of why this slot scored well
Total number of slots found (always 5 or less)
Date range searched
Start date in ISO 8601 format
End date in ISO 8601 format
Example Request
curl -X POST https://api.syncline.run/v1/availability \
-H "X-API-Key: sk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"attendees": ["alice@example.com", "bob@example.com"],
"duration_minutes": 30,
"context": "Introductory call"
}'
Example Response
{
"slots": [
{
"start_time": "2025-11-20T10:00:00-08:00",
"end_time": "2025-11-20T10:30:00-08:00",
"score": 0.95,
"timezone": "America/Los_Angeles",
"reason": "Mid-morning, optimal timezone for both attendees"
},
{
"start_time": "2025-11-21T10:30:00-08:00",
"end_time": "2025-11-21T11:00:00-08:00",
"score": 0.93,
"timezone": "America/Los_Angeles",
"reason": "Mid-morning, excellent availability"
},
{
"start_time": "2025-11-20T14:00:00-08:00",
"end_time": "2025-11-20T14:30:00-08:00",
"score": 0.82,
"timezone": "America/Los_Angeles",
"reason": "Early afternoon, good match"
},
{
"start_time": "2025-11-22T11:00:00-08:00",
"end_time": "2025-11-22T11:30:00-08:00",
"score": 0.80,
"timezone": "America/Los_Angeles",
"reason": "Late morning, acceptable for both"
},
{
"start_time": "2025-11-20T16:00:00-08:00",
"end_time": "2025-11-20T16:30:00-08:00",
"score": 0.75,
"timezone": "America/Los_Angeles",
"reason": "Late afternoon, available but not ideal"
}
],
"total_found": 5,
"search_window": {
"start": "2025-11-15",
"end": "2025-11-29",
"days": 14
}
}
Error Responses
{
"error": {
"code": "invalid_attendees",
"message": "Attendee list must contain exactly 2 email addresses",
"field": "attendees"
}
}
400 Bad Request
{
"error": {
"code": "user_not_found",
"message": "User alice@example.com has not connected their calendar",
"field": "attendees",
"email": "alice@example.com"
}
}
404 Not FoundSolution: User must complete OAuth flow at syncline.run
{
"slots": [],
"total_found": 0,
"search_window": {
"start": "2025-11-15",
"end": "2025-11-29",
"days": 14
},
"message": "No mutual availability found in 14-day window"
}
200 OKNote: This is not an error. Try expanding the date range or adjusting preferences.How Slots Are Ranked
Syncline uses a smart ranking algorithm with 5 factors:
Avoids times outside 8am-6pm for either person.Score impact: 0.5x penalty for awkward hours
10am is the ideal meeting time for most professionals.Score impact: 1.2x boost for 10am slots
3. Friday Afternoon Penalty
People protect Friday afternoons for focus work.Score impact: 0.7x penalty after 2pm on Fridays
Noon-1pm is typically reserved for lunch.Score impact: 0.8x penalty for 12pm-1pm
Sooner is better—momentum matters for intros.Score impact: 1.1x boost for slots within 3 days
Best Practices
Always use the first slot. It’s ranked highest for a reason. Only offer alternatives if user explicitly requests them.
Cache results for 5 minutes. Availability doesn’t change that fast. Reduces API calls.
Show timezone to user. Even though Syncline handles conversion, transparency builds trust.
Next Steps
