Concepts
Core mental model for Openavail.
The arbitration model
Openavail is a neutral arbitration endpoint. Agents do not write to calendars directly — they ask Openavail first. Openavail applies your rule set, checks the live calendar state, and returns a decision: accept, reject, counter, or preempt.
This means:
- Openavail holds the only OAuth token that can write to the calendar. Agents authenticate with API keys scoped to specific calendar owners.
- Every decision is deterministic and logged. The same request made twice with the same state produces the same decision.
- Conflicts are resolved by priority, not by arrival order.
Holds
A hold is a temporary reservation of a time slot. When an agent calls POST /v1/availability, Openavail creates a hold against the matching slots. The hold is not visible on the calendar yet — it is a server-side reservation that prevents other agents from claiming the same slot while the first agent decides.
Holds expire after ttl_seconds (default 300). If the agent does not confirm, the slot is released automatically.
This two-phase pattern — hold then confirm — is what prevents double-booking races. See Two-phase commit for the full flow.
Meeting classes and priority
Every booking request must include a meeting_class string. Meeting classes are configured in the dashboard and carry a numeric priority (0–100).
When two agents compete for the same slot, the one with the higher-priority meeting class wins. If priority is equal, the agent that called first wins (by hold creation timestamp).
A special rule: a committed booking older than sacred_meeting_age_hours (default 24) is sacred and cannot be displaced by any agent regardless of priority. This protects committed meetings from being bumped at the last minute.
Rule layers
Rules cascade from org to individual:
Org defaults → calendar owner overrides
The calendar owner's rules win on any field they explicitly set; otherwise they inherit the org default. Rules control:
- Working hours and blackout windows
- Buffer time between meetings
- Maximum daily meeting counts
- Per-class priority boosts
See Rule layers for the full configuration reference.
Audit rows
Every decision Openavail makes — accept, reject, preempt, counter — produces an audit row. The row records:
| Field | What it captures |
|---|---|
decision_id | Unique identifier (dec_…) |
action | accept, reject, preempt, counter |
actor.agent_id | Which registered agent made the request |
actor.api_key | Which specific key (for revocation tracing) |
owner | The calendar owner whose time was affected |
rule_fired | Which rule produced the decision |
latency_ms | P99 end-to-end latency |
Audit rows are immutable. They cannot be deleted — they can only be exported or expire per your retention policy.
Google account types
How Openavail treats a connected Google account depends on whether it is a personal account or a Google Workspace account. The distinction is determined automatically at sign-in — you do not configure it manually.
| Personal Google account | Google Workspace account | |
|---|---|---|
| How to identify | @gmail.com or any address without a Workspace tenant | Corporate or edu address backed by a Workspace tenant |
| Plan assigned | Individual | Team |
| Domain deduplication | Not applied | Teammates signing in with the same domain are provisioned as members of the same workspace |
| JIT provisioning | No — each sign-in creates a separate workspace | Yes — the first user from a domain creates the workspace; subsequent users from the same domain join it |
Why it matters for agents: Agents identify calendar owners by email (owner_email in API requests). The email is stable regardless of account type or Google Workspace setup. The account type only affects how the dashboard is organised.
Multiple calendars and the primary calendar
A calendar owner can connect more than one calendar (for example, a work Google calendar and a personal one). When an agent calls POST /v1/availability, Openavail:
- Unions free/busy data from all of the owner's connected calendars to give an accurate availability picture.
- Writes the hold and any resulting booking to the owner's designated primary calendar.
The owner sets their primary calendar in the dashboard (Dashboard → Calendars → Set as primary). If the primary is disconnected, agents receive CALENDAR_NOT_FOUND until a new primary is set.
To target a specific calendar type, agents can pass "calendar_type": "work" (or "personal" / "other") alongside owner_email. Openavail resolves to the matching calendar and falls back to the primary if no match exists. The resolved_calendar_type field in the response confirms which calendar was selected.