Check Availability

Check Availability

Check available appointment time slots using a natural language query.

Endpoint

POST /api/v1/check-availability

Request Body

{
  "query": "next Monday afternoon"
}

Response — Slots Available

{
  "message": "On Monday, March 3rd, these times are available: 10:00, 11:00, 13:00, 14:00, 15:00.",
  "slots": [
    { "date": "2026-03-03", "time": "10:00", "day": "Monday" },
    { "date": "2026-03-03", "time": "11:00", "day": "Monday" },
    { "date": "2026-03-03", "time": "13:00", "day": "Monday" },
    { "date": "2026-03-03", "time": "14:00", "day": "Monday" },
    { "date": "2026-03-03", "time": "15:00", "day": "Monday" }
  ],
  "status": "available"
}

Response — No Slots Available

When the requested time is fully booked, alternative time slots on nearby days are suggested:

{
  "message": "Unfortunately, no appointments are available on Monday. Alternatives: Tuesday March 4th at 10:00, 11:00, 14:00.",
  "slots": [],
  "alternatives": [
    { "date": "2026-03-04", "time": "10:00", "day": "Tuesday" },
    { "date": "2026-03-04", "time": "11:00", "day": "Tuesday" },
    { "date": "2026-03-04", "time": "14:00", "day": "Tuesday" }
  ],
  "status": "unavailable"
}

Response — Holiday

{
  "message": "On Monday, October 3rd, we are closed due to German Unity Day.",
  "status": "holiday",
  "holiday": "German Unity Day"
}

Response — Closed

{
  "message": "We are closed on Sundays.",
  "status": "closed"
}

Natural Language Examples

The query field accepts free-form text in German or English:

• "next Monday"
• "tomorrow at 2pm"
• "nächste Woche Dienstag"
• "morgen Nachmittag"
• "Do you have anything on Friday?"
• "Haben Sie am Freitag noch etwas frei?"

Notes

• The response language matches the input language automatically
• Up to 5 slots are returned per query
• Alternative suggestions are spaced apart by the appointment duration
• If Google Calendar is temporarily unavailable, the API returns an error rather than assuming the calendar is free