openavail

Quickstart

Get an agent booking slots on a real calendar in under five minutes.

Overview

Openavail sits between your AI agent and your calendar provider. Instead of your agent calling Google or Outlook directly, it calls Openavail. Openavail checks your rules, arbitrates conflicts, and forwards only the approved writes.

The full booking flow is two API calls:

  1. POST /v1/availability — check if a range is free and create a hold
  2. POST /v1/bookings/{hold_id}/confirm — commit the hold to the calendar

Prerequisites

  • A Google Workspace or Microsoft 365 account signed into the Openavail dashboard
  • A connected calendar (Dashboard → Calendars → Connect)
  • An agent registered in the dashboard (Dashboard → Agents → New agent) with at least one API key

Step 1 — Get an API key

From the dashboard, navigate to Agents, open your agent, and create a key. Copy it — it won't be shown again.

ak_01HX7QQM…

All requests authenticate with Authorization: Bearer <key>.

Step 2 — Check availability

POST /v1/availability HTTP/1.1
Host: api.openavail.com
Authorization: Bearer ak_01HX7QQM…
Content-Type: application/json
Idempotency-Key: my-agent:check:abc123

{
  "owner_email": "[email protected]",
  "duration_minutes": 45,
  "meeting_class": "recruiting_interview",
  "window": {
    "start": "2026-06-01T09:00:00Z",
    "end":   "2026-06-01T18:00:00Z"
  }
}

A successful 200 response includes a hold_id (a reservation that expires after expires_at), a ranked list of candidate slots, a resolved_calendar_type field showing which calendar type was used, and a warnings array (non-empty if live free/busy data was unavailable for any calendar).

If the window has no free slots, the response is 409 NO_SLOTS_AVAILABLE. You can add "next_available_lookahead_hours": 24 to the request body to receive a next_available: { start, end } hint pointing at the nearest free slot beyond your window (up to 72 hours ahead).

If a calendar owner has connected multiple calendars, Openavail uses their designated primary calendar as the booking write target. To target a specific calendar, pass "calendar_type": "work" (or "personal" / "other"). If no calendar matching the hint exists, Openavail falls back to the primary. The owner sets calendar types and the primary in the dashboard.

Step 3 — Confirm the booking

Pick a slot from the response and confirm the hold before expires_at:

POST /v1/bookings/{hold_id}/confirm HTTP/1.1
Authorization: Bearer ak_01HX7QQM…
Content-Type: application/json

{
  "start": "2026-06-01T14:00:00Z",
  "end":   "2026-06-01T14:45:00Z",
  "meeting_class": "recruiting_interview",
  "title": "Interview — Jeremiah O",
  "attendees": [
    { "email": "[email protected]", "displayName": "Jane Candidate" }
  ]
}

title and attendees are optional. When title is omitted it defaults to the meeting class name. attendees defaults to an empty list.

Openavail writes the event to the calendar and returns a booking_id and correlation_id.

What's next

  • Read Concepts to understand arbitration, holds, and priority
  • See the full POST /v1/availability reference for all request and response fields
  • Set up rule layers to control which agents can book what