Find Mutual Availability
Find overlapping free time across 2-10 principals (calendar owners). **Use Case**: Schedule a meeting with multiple attendees by finding times when all participants are available. The caller needs access to every principal in the list. Each principal must be one of: - the caller itself; - a host the caller's account manages (see `/v1/hosts`) — no connection or consent needed; - connected to the caller (an active connection counts as consent); - a grantor of an active consent to the caller with at least `availability:read:freebusy` scope. Otherwise the request returns `403`. Consent is held by the account, not by individual hosts: a customer connected to the account can be queried alongside any host that account manages. The response includes a `consents` array for principals reached through explicit consent. Requires a secret key or user session; publishable keys get `403`.
Auth required: Yes
principal_ids (query, array) (required) — Principal UUIDs whose availability will be intersected.
Pass as comma-separated: ?principal_ids=uuid1,uuid2,uuid3
duration_minutes (query, integer) — Minimum meeting duration in minutes. Defaults to 30.from (query, string) (required) — Start of search window (ISO 8601)to (query, string) (required) — End of search window (ISO 8601)timezone (query, string) — Timezone for results (IANA format)limit (query, integer) — Maximum number of slots to returnslot_interval (query, integer) — Candidate slot cadence in minutes. Defaults to `min(duration_minutes, 15)`.
Values smaller than `duration_minutes` produce overlapping candidates.
200: Mutual availability slots400: Validation error401: Authentication required or invalid403: Authenticated but insufficient permissions404: Resource not foundRequires 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