List free slots

List open booking slots on a calendar between two dates, using the same availability check your AI agents use (business hours, existing appointments and connected calendars).

GET https://api.centerfy.ai/webhooks/inbound/calendars/:id/free-slots

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	Authenticates the request; or use Authorization: Bearer `<key>`.

Path parameters

Name	Type	Required	Description
`id`	`string (uuid)`	Yes	The calendar id.

Query parameters

Name	Type	Required	Default	Description
`start`	`string (YYYY-MM-DD)`	Yes	—	First day to search.
`end`	`string (YYYY-MM-DD)`	Yes	—	Last day to search (inclusive); at most 31 days after start counting both ends.
`timezone`	`string`	No	—	IANA time zone the days are read in and slots are returned in, e.g. America/New_York. Defaults to your company time zone.
`duration_minutes`	`integer`	No	—	Slot length in minutes; 1–1440. Defaults to the calendar’s booking_duration_minutes.

Example

curl -X GET "https://api.centerfy.ai/webhooks/inbound/calendars/{id}/free-slots?start={start}&end={end}" \
  -H "x-api-key: $CENTERFY_API_KEY"

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.calendars.freeSlots("<calendarId>", {});
console.log(result);

centerfy calendars free-slots <calendarId> '{}'

MCP tool: centerfy_calendars_free_slots (see MCP server)

Response

{
  "status": "success",
  "calendar_id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b",
  "start": "2026-10-07",
  "end": "2026-10-07",
  "timezone": "America/New_York",
  "source": "centerfy",
  "total": 2,
  "slots": [
    {
      "start_time": "2026-10-07T09:00:00-04:00",
      "end_time": "2026-10-07T09:30:00-04:00",
      "duration_minutes": 30,
      "day_of_week": "wednesday"
    },
    {
      "start_time": "2026-10-07T09:30:00-04:00",
      "end_time": "2026-10-07T10:00:00-04:00",
      "duration_minutes": 30,
      "day_of_week": "wednesday"
    }
  ]
}

Errors

400 — if start/end aren’t valid YYYY-MM-DD dates, end is before start, the range is over 31 days, or the timezone is unknown.
404 — if the calendar is not in this sub-account.
409 — if business hours aren’t configured for this sub-account — set them in Settings → Company first.
502 — if the availability check fails.

Notes

source is centerfy, ghl or hubspot depending on where the calendar’s availability lives.