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 Calendar directly, it calls Openavail. Openavail checks your rules, arbitrates conflicts, and forwards only the approved writes.

The recommended first booking flow is approval-first:

  1. POST /v1/booking-proposals — create a durable proposal and discover candidates without reserving time
  2. The calendar owner approves or rejects in Dashboard → Approvals
  3. Openavail books automatically if an approved candidate is still valid

This guide uses the REST API directly. If you prefer a typed client or an MCP interface, see the TypeScript SDK or MCP server docs instead.

Prerequisites

  • A Google Workspace account signed into the Openavail dashboard (Microsoft 365 coming soon)
  • 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 — Create a proposal

POST /v1/booking-proposals HTTP/1.1
Host: api.openavail.com
Authorization: Bearer ak_01HX7QQM…
Content-Type: application/json

{
  "owner_email": "alex@acme.com",
  "title": "Recruiting interview",
  "duration_minutes": 45,
  "meeting_class": "recruiting_interview",
  "requested_window": {
    "start": "2026-06-01T09:00:00Z",
    "end":   "2026-06-01T18:00:00Z"
  },
  "preferred_times": [
    { "start": "2026-06-01T14:00:00Z", "end": "2026-06-01T14:45:00Z" }
  ],
  "attendees": [
    { "email": "candidate@example.com", "displayName": "Jane Candidate" }
  ]
}

A successful 201 response includes proposal_id, status, requested_window, expires_at, candidate curation metadata, and candidate history. In beta, broad proposal windows are curated to 20 valid review candidates. Preferred candidates are preserved first, and invalid preferred candidates are preserved with invalid_reasons such as WORKING_HOURS, OFF_DAY, or duration_mismatch without reducing the valid candidate budget. The response does not include an owner review URL; approval happens inside the authenticated dashboard. The agent can poll GET /v1/booking-proposals/{proposal_id} or read pending notifications for booking_proposal.booked, booking_proposal.rejected, or booking_proposal.needs_new_window.

If the requested window cannot produce any valid proposal candidates, the endpoint returns 409 NO_SLOTS_AVAILABLE. When the failure is rule-related, the response includes a reason_code such as WORKING_HOURS or OFF_DAY.

For approval-mode agents, grant read_freebusy and create_booking_proposals.

Auto-booking alternative

Trusted agents can still use the explicit hold flow:

  1. POST /v1/availability/search
  2. POST /v1/holds
  3. POST /v1/bookings/{hold_id}/confirm

That agent needs read_freebusy, create_holds, and create_bookings. Use this only for agents you trust to reserve and book without owner review.

What's next

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