# Availability

Ask for physical room windows before you know the duration, or concrete eligible starts once the selection is more complete. Neither response creates a reservation.

## Inputs and outputs

[Room availability](/api/docs#/Studio%20availability/v2CustomerAvailability) accepts a local `date` or paired `date_from`/`date_to`, up to 31 inclusive local days, plus supported room/setup filters. Target pagination and interval pagination are independent; follow both response contracts.

Without `duration_minutes`, `data.kind=windows` groups physical free intervals by room. Supplying only a setup identifies its room; it does not silently choose a duration.

With a duration and optional setup, `kind=starts` returns concrete setup variants on the customer start grid. No arbitrary first setup is chosen. Use the returned eligible starts instead of inventing a start from a visually empty calendar.

## Time and calendar confidence

Read the studio `timezone`, `duration_basis=local_wall_time`, UTC boundaries and calendar metadata. A date/time without its studio timezone is incomplete scheduling information.

DST gap starts are unavailable. Repeated starts select the earlier occurrence. A nominal end in a DST gap can have `ends_at=null` and `end_status=gap_time`; midnight ends are next-day exclusive. Preserve these distinctions in your interface.

`verified` means no unresolved configured calendar guard, not that Google was polled during this request. `checked_at` is advisory. Where a calendar/infrastructure error is retryable, respect `Retry-After` and do not display an uncertain slot as confirmed.

## Combine with other capabilities

A room-first interface can display windows, collect a [service/setup choice](/api/docs/guides/v2/catalog), then ask for starts. A service-first interface can enter directly with its compatible setup and duration. Both send a [complete quote](/api/docs/guides/v2/quotes) before admission.

[Tour availability](/api/docs#/Studio%20native%20checkout/v2GetTourAvailability) is separate: preserve setup-bound geometry versus studio-wide tagged roomless slots. Do not copy ordinary availability inputs into a Tour request.

## Permissions, effects and failure

Use the operation's current availability/session authority. Reads create no hold, payment, booking or receipt. Admission rechecks capacity and can refuse a slot that was previously available. On a conflict, refresh the relevant selection and let the customer choose again; a second write is not a substitute for recovery of an uncertain first write.

## Example

Ask for eligible starts after choosing a compatible setup and duration:

```sh
curl --get "https://app.podyx.com/api/v2/rooms/availability" \
  -H "Authorization: Bearer $PODYX_API_KEY" \
  --data-urlencode "setup_id=$SETUP_ID" \
  --data-urlencode 'date=2026-11-02' \
  --data-urlencode 'duration_minutes=45'
```

Remove the duration to inspect physical windows instead. Supply the concrete selected start to the quote; do not infer a hold from either read.