Skip to main content
GET
/
api
/
v1
/
calendar
/
availability
Get Calendar Availability
curl --request GET \
  --url https://api.example.com/api/v1/calendar/availability
{
  "user_id": 123,
  "start_date": "<string>",
  "end_date": "<string>",
  "duration_minutes": 123,
  "available_slots": [
    {
      "start": "<string>",
      "end": "<string>",
      "duration_minutes": 123
    }
  ],
  "count": 123,
  "error": "<string>",
  "message": "<string>"
}
Get available time slots for scheduling based on the user’s calendar and availability settings.

​
Query Parameters

​
start_date
string
Start date for the range. If not provided, defaults to the current date.
​
end_date
string
End date for the range. If not provided, defaults to 7 days from the start date.
​
duration
integer
default:30
Duration in minutes for the time slots.

​
Response

​
user_id
integer
User ID.
​
start_date
string
Start date of the range.
​
end_date
string
End date of the range.
​
duration_minutes
integer
Duration in minutes.
​
available_slots
array
List of available time slots.
​
count
integer
Total number of available slots.

​
Example Request

curl -X GET 'https://api.klen.ai/api/v1/calendar/availability?start_date=2025-05-01&end_date=2025-05-07&duration=60' \
  -H 'Authorization: Bearer klen_YOUR_API_KEY'

​
Example Response

{
  "user_id": 123,
  "start_date": "2025-05-01",
  "end_date": "2025-05-07",
  "duration_minutes": 60,
  "available_slots": [
    {
      "start": "2025-05-01T09:00:00.000Z",
      "end": "2025-05-01T10:00:00.000Z",
      "duration_minutes": 60
    },
    {
      "start": "2025-05-01T13:00:00.000Z",
      "end": "2025-05-01T14:00:00.000Z",
      "duration_minutes": 60
    },
    {
      "start": "2025-05-02T10:00:00.000Z",
      "end": "2025-05-02T11:00:00.000Z",
      "duration_minutes": 60
    },
    {
      "start": "2025-05-02T14:00:00.000Z",
      "end": "2025-05-02T15:00:00.000Z",
      "duration_minutes": 60
    },
    {
      "start": "2025-05-05T09:00:00.000Z",
      "end": "2025-05-05T10:00:00.000Z",
      "duration_minutes": 60
    }
    // ... more slots
  ],
  "count": 15
}

​
Error Responses

​
error
string
Error code.
​
message
string
Error message.

​
Invalid Parameters (400)

{
  "error": "invalid_parameter_format",
  "message": "Invalid date format. Expected YYYY-MM-DD"
}

{
  "error": "invalid_duration",
  "message": "Duration must be between 1 and 180 minutes"
}

​
Unauthorized (401)

{
  "error": "authentication_required",
  "message": "API key is required"
}

​
Permission Denied (403)

{
  "error": "permission_denied",
  "message": "This API key does not have can_read_calendar permission"
}

​
Server Error (500)

{
  "error": "server_error",
  "message": "An unexpected server error occurred"
}

​
Notes

  • The available slots are calculated based on:
    • The user’s availability schedules
    • Existing calendar events
    • Buffer time between meetings
    • Advance notice requirements
    • Business hours
  • All times are returned in UTC (ISO 8601 format)
  • You can convert the times to the user’s local timezone if needed