API reference · Smart Suggestions
Smart Suggestions
Multi-constraint slot finder. Optimizes across free/busy plus soft preferences.
★
Aspirational surface. This resource is part of the developer-platform roadmap. The field shapes follow the same conventions as live resources and are stable for prototype integrations.
Endpoints
POST
/v1/scheduling/suggest
Multi-constraint slot suggestions
Multi-constraint slot finder
HTTP
POST /v1/scheduling/suggest
Combines free/busy across participants with soft preferences — preferred days, time of day, max inter-meeting travel — and returns ranked slot candidates.
JSON
{
"intent": "find_meeting_time",
"participants": ["usr_a", "usr_b", "external:x@example.com"],
"duration_minutes": 60,
"constraints": {
"earliest": "2026-05-22T09:00:00-07:00",
"latest": "2026-05-29T17:00:00-07:00",
"preferred_days": ["tue","wed","thu"],
"preferred_time_of_day": "afternoon",
"max_travel_minutes_between_meetings": 20
},
"location": {"address":"Downtown LA","type":"in_person"},
"limit": 5
}Response — each candidate includes a score and the constraint deltas:
JSON
{
"object": "list",
"data": [
{
"start": "2026-05-22T14:00:00-07:00",
"end": "2026-05-22T15:00:00-07:00",
"score": 0.92,
"matches": ["preferred_time_of_day", "max_travel_minutes_between_meetings"],
"misses": []
}
]
}Tradeoffs
The optimizer is greedy, not exact. For meetings with > 8 participants or > 7 day horizons, we recommend tightening earliest/latest and working_hours to keep latency under 500ms.