For the complete documentation index, see llms.txt.

GET /v1/principals/{principalId}/availability

Get Principal Availability

Get normalized availability blocks for a principal (calendar owner). **Use Case**: Find mutual free time for scheduling across calendars. Access: the caller itself, a host the caller's account manages (see `/v1/hosts`), a principal connected to the caller, or a principal who has granted the caller consent with `availability:read:freebusy` scope. Otherwise returns `403`, including for principals that don't exist. Same rule as `GET /v1/availability/slots`. Requires a secret key or user session; publishable keys get `403`.

Auth required: Yes

Parameters

• principalId (path, string) (required) — Principal (calendar owner) UUID
• from (query, string) — Start of date range (ISO 8601)
• to (query, string) — End of date range (ISO 8601)
• granularity (query, string) — Block granularity. Accepted but currently unused — reserved for future use.

Responses

• 200: Availability blocks
• 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