For agent builders

One endpoint.
Every agent.

Stop letting your agents talk to Google directly. Route every calendar write through Openavail. We hold the only real token, enforce your priority rules, and log every decision.

POST /v1/bookings · sample

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

{
  "owner_email": "[email protected]",
  "calendar_type": "work",
  "duration_minutes": 60,
  "meeting_class": "external_customer_call",
  "window": {
    "start": "2026-06-10T09:00:00Z",
    "end":   "2026-06-10T17:00:00Z"
  }
}

← 200 OK
{
  "hold_id": "hld_4f8b2a…",
  "expires_at": "2026-06-10T09:05:00Z",
  "slots": [{ "start": "2026-06-10T10:00:00Z", "end": "2026-06-10T11:00:00Z" }],
  "resolved_calendar_type": "work",
  "warnings": []
}

How it works

Register your agent

POST to /v1/agents with an agent_id and the permission scopes you need. Openavail returns an agent identifier and an empty key set.

Create an API key

Call POST /v1/agents/{id}/keys. Copy the raw key — it is shown exactly once. Send it as Bearer ak_… on every request.

Send booking requests

Hit POST /v1/availability with the owner_email, slot window, meeting class, and duration. Openavail checks all connected calendars and returns available slots with a hold.

Read the decision

Every response is Accept, Reject, or CounterPropose. If you hold preempt permission and your priority wins, you get Preempt with displaced booking info.

Request format

Ask, then receive a verdict.

Every booking request returns a deterministic decision — Accept, Reject, or CounterPropose — within a single HTTP round-trip. No polling. No callbacks. No ambiguity.

✓Arbiter P99 ≤ 200 ms — availability includes a live calendar sync

✓Idempotent on booking_id

✓Every response includes an audit_row_id

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

{
  "owner_email": "[email protected]",
  "calendar_type": "work",
  "duration_minutes": 60,
  "meeting_class": "external_customer_call",
  "window": {
    "start": "2026-06-10T09:00:00Z",
    "end":   "2026-06-10T17:00:00Z"
  }
}

← 200 OK
{
  "hold_id": "hld_4f8b2a…",
  "expires_at": "2026-06-10T09:05:00Z",
  "slots": [{ "start": "2026-06-10T10:00:00Z", "end": "2026-06-10T11:00:00Z" }],
  "resolved_calendar_type": "work",
  "warnings": []
}

Response decisions

Four verdicts, four actions.

Every booking request returns one of four decisions in the same HTTP response. The arbiter logic — priority order, tiebreakers, preempt rules — lives in arbitration. Here's how an agent reacts to each verdict.

ResponseWhen you get itWhat to do

Accept

No conflict. Slot is free and all rules pass.

Booking is committed. Nothing more to do.

Reject

Slot is blocked by a higher-priority booking, a hard rule (working hours, hard block, daily limit), or the agent lacks the preempt permission.

Inspect reason_code. If NO_CAPACITY, the slot is taken by a higher-priority class — try a different slot. If WORKING_HOURS or similar, your window is outside the owner's rules.

CounterPropose

Slot is blocked, but other slots in the same hold window are still free.

Pick from alternatives[] and confirm one. Each entry includes start, end, and reason_code.

Preempt

Your meeting class outranks an existing booking and your agent holds the preempt permission.

The displaced booking is moved to needs_reschedule. The displaced agent is notified via their pending_notifications envelope.

Permission scopes

Only the access each agent needs.

read_freebusy

Check whether a slot is available without seeing event details.

Scheduling assistants, time-pickers.

read_events

See full event metadata: title, attendees, meeting class, priority.

Context-aware agents, conflict explainers.

create_holds

Reserve a slot temporarily while a booking is being confirmed by another party.

Multi-party schedulers, poll-based flows.

create_bookings

Write a confirmed event to the calendar owner's calendar.

Sales bots, recruiting agents, focus-time schedulers.

preempt

Displace a lower-priority booking when a higher-priority one arrives.

Executive assistants, CEO meeting handlers.

Permissions are scoped at agent registration and enforced on every request. Revoke individually or rotate the API key without removing the agent.

Transport protocols

RESTAvailable

JSON over HTTPS. All endpoints versioned under /v1/.

MCPComing soon

Model Context Protocol transport. Expose Openavail tools directly inside your agent runtime. Ships alongside the v1 GA release.

Ready to connect your first agent?

Read the quickstart or request access to the v1 enterprise preview.

REST and MCP transports · P99 ≤ 200 ms · Idempotent endpoints · Every decision logged

One endpoint.Every agent.