For the complete documentation index, see llms.txt.

GET /v1/availability/slots

Get Available Time Slots

Get bookable time slots for a principal. Requires authentication. **Direct mode**: The caller needs access to the principal: the caller itself, a host the caller's account manages (see `/v1/hosts`), a principal connected to the caller, or a grantor of an active consent to the caller with `availability:read:freebusy` scope. Otherwise returns `403`, including for principals that don't exist. No event details are included. A publishable key reaches only the caller's own account and managed hosts; connections, consents and `consent_id` mode need a secret key. **Consent-scoped mode** (`consent_id`): Returns availability scoped by the referenced consent's permissions. The authenticated user must be the grantee on the consent. Response includes a `consent` audit trail. With `availability:read:details` scope, slots include event titles and descriptions.

Auth required: Yes

Parameters

• business_id (query, string) — Business UUID to check availability for. Also accepted as `principal_id` (alias).
• principal_id (query, string) — Alias for `business_id`. Send either (at least one required).
• duration_minutes (query, integer) — Meeting duration in minutes. Defaults to 30.
• from (query, string) (required) — Start of date range (ISO 8601)
• to (query, string) (required) — End of date range (ISO 8601)
• timezone (query, string) — Timezone for results (IANA format)
• buffer (query, integer) — Buffer time in minutes between bookings
• group_by_day (query, boolean) — Group slots by date
• slot_interval (query, integer) — Candidate slot cadence in minutes. Controls how far apart the start times of returned slots are. Defaults to `min(duration_minutes, 15)`. Values smaller than `duration_minutes` produce overlapping candidates (caller picks one; the rest become moot once booked).
• consent_id (query, string) — Consent UUID. When provided, authentication is required and the response is scoped by the consent's permissions. The authenticated user must be the grantee on this consent.

Responses

• 200: Available time slots
• 400: Validation error
• 401: Authentication required or invalid
• 403: Authenticated but insufficient permissions
• 404: Resource not found

Authentication

Requires authentication. Pass a Bearer token (Supabase JWT) or an API key (`Authorization: Bearer vennio_sk_live_*`) in the request headers.

Base URL: https://api.vennio.app