Skip to main content
POST
/
v1
/
availability
Find Mutual Availability
curl --request POST \
  --url https://api.example.com/v1/availability \
  --header 'Content-Type: application/json' \
  --data '
{
  "attendees": [
    "<string>"
  ],
  "duration_minutes": 123,
  "date_range": {
    "start_date": "<string>",
    "end_date": "<string>"
  },
  "context": "<string>"
}
'
{
  "slots": [
    {
      "start_time": "<string>",
      "end_time": "<string>",
      "score": 123,
      "timezone": "<string>",
      "reason": "<string>"
    }
  ],
  "total_found": 123,
  "search_window": {
    "start": "<string>",
    "end": "<string>",
    "days": 123
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.syncline.run/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

POST https://api.syncline.run/v1/availability

​
Request Body

​
attendees
string[]
required
Array of email addresses. Must be exactly 2 for MVP.
["alice@example.com", "bob@example.com"]
​
duration_minutes
integer
default:30
Meeting duration in minutes. Min: 15, Max: 120.
​
date_range
object
Optional custom date range. Defaults to user’s availability_window_days preference (14 days).
​
context
string
Optional meeting context for better title generation.Example: "Introduction call after LinkedIn connection"

​
Response

​
slots
TimeSlot[]
Array of 5 time slots, ranked by quality (best first).
​
total_found
integer
Total number of slots found (always 5 or less)
​
search_window
object
Date range searched

​
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"
  }
}
Status: 400 Bad Request
{
  "error": {
    "code": "user_not_found",
    "message": "User alice@example.com has not connected their calendar",
    "field": "attendees",
    "email": "alice@example.com"
  }
}
Status: 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"
}
Status: 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
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
Final score = Base (1.0) × All factors Learn more: Smart Ranking Explained

​
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

Schedule Meeting

Book one of the available slots

Smart Ranking

Deep dive into the ranking algorithm