---
title: "Find free appointment slots in a connected calendar, without any saved agent configuration; windows defaults to 24 hours every day when omitted"
method: POST
path: "/v1/integrations/{id}/availability"
---

# Find free appointment slots in a connected calendar, without any saved agent configuration; windows defaults to 24 hours every day when omitted

`POST /v1/integrations/{id}/availability`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/integrations/{id}/availability`
- Auth: HTTP bearer

Returns free slots in a connected calendar WITHOUT any saved agent - the same computation as check_availability during a call, just without the agent's rules. windows omitted means 24 hours every day; if you send it, a weekday left out has no window. to must be after from and at most 31 days later. The response carries only start/end and timezone - no event titles or descriptions.

## Path parameters

- `id` string, required

## Request body

- object
  - `calendarId` string, required: Calendar id from list_calendars, for example primary.
  - `busyCalendarIds` string[]: Other calendars in the same connection whose events also block a slot; nothing is written into them, so read-only calendars are fine. At most 4, without duplicates and without calendarId itself.
  - `from` string, date-time, required: Lower bound of the search window, RFC 3339 with an offset.
  - `to` string, date-time, required: Upper bound of the search window, RFC 3339 with an offset. Must be after from and at most 31 days later, otherwise calendar_invalid_range.
  - `slotMinutes` union: Length of each offered slot in minutes. Defaults to 30.
    - 15
    - 30
    - 45
    - 60
    - 90
    - 120
  - `windows` object: Availability windows per weekday, local HH:MM time in timezone. A weekday left out of this object has no window that day. Omit the whole field for 24 hours every day.
    - `mon` object[]: Availability windows on Monday. An empty array means no availability that day.
      - `from` string, required: Start of this window as local time HH:MM in the given timezone, for example 09:00.
      - `to` string, required: End of this window as local time HH:MM in the given timezone, for example 17:00.
    - `tue` object[]: Availability windows on Tuesday. An empty array means no availability that day.
      - `from` string, required: Start of this window as local time HH:MM in the given timezone, for example 09:00.
      - `to` string, required: End of this window as local time HH:MM in the given timezone, for example 17:00.
    - `wed` object[]: Availability windows on Wednesday. An empty array means no availability that day.
      - `from` string, required: Start of this window as local time HH:MM in the given timezone, for example 09:00.
      - `to` string, required: End of this window as local time HH:MM in the given timezone, for example 17:00.
    - `thu` object[]: Availability windows on Thursday. An empty array means no availability that day.
      - `from` string, required: Start of this window as local time HH:MM in the given timezone, for example 09:00.
      - `to` string, required: End of this window as local time HH:MM in the given timezone, for example 17:00.
    - `fri` object[]: Availability windows on Friday. An empty array means no availability that day.
      - `from` string, required: Start of this window as local time HH:MM in the given timezone, for example 09:00.
      - `to` string, required: End of this window as local time HH:MM in the given timezone, for example 17:00.
    - `sat` object[]: Availability windows on Saturday. An empty array means no availability that day.
      - `from` string, required: Start of this window as local time HH:MM in the given timezone, for example 09:00.
      - `to` string, required: End of this window as local time HH:MM in the given timezone, for example 17:00.
    - `sun` object[]: Availability windows on Sunday. An empty array means no availability that day.
      - `from` string, required: Start of this window as local time HH:MM in the given timezone, for example 09:00.
      - `to` string, required: End of this window as local time HH:MM in the given timezone, for example 17:00.
  - `minNoticeMinutes` integer: Minimum notice before the earliest offered slot, in minutes. Defaults to 120.
  - `bufferMinutes` integer: Buffer kept free immediately before and after every busy event, in minutes. Defaults to 0.
  - `timezone` string: IANA timezone the windows and returned slots are interpreted in. Defaults to Europe/Prague.
  - `limit` integer: Maximum number of slots to return, 1 to 50. Defaults to 20.

## Response `200`

Free slots (start/end only, no title or description) and the timezone they are in

- object
  - `slots` object[], required
    - `start` string, required
    - `end` string, required
  - `timezone` string, required

## Other responses

- `400`: Error codes: calendar_unsupported (request), validation (request), calendar_invalid_calendar (request), calendar_too_many_events (request), calendar_invalid_range (request), calendar_invalid_timezone (request), calendar_invalid_windows (request), calendar_no_windows (request), calendar_invalid_rules (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: calendar_not_found (account).
- `409`: Error codes: calendar_read_only (account), calendar_busy (busy), calendar_refresh_in_progress (busy), calendar_unauthorized (account), calendar_oauth_failed (account), calendar_credentials_unavailable (account), calendar_invalid_credentials (account).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `502`: Error codes: calendar_provider_error (service), calendar_invalid_provider_response (service).
- `503`: Error codes: calendar_not_configured (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)