One endpoint.
Every agent.

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

{
  "owner_email":    "alex@acme.com",
  "calendar_type":  "work",
  "duration_minutes": 60,
  "meeting_class":  "Critical",
  "earliest_start": "2026-06-10T09:00:00Z",
  "latest_end":     "2026-06-10T17:00:00Z",
  "max_results":    50
}

← 200 OK
{
  "requested_window": {
    "start": "2026-06-10T09:00:00Z",
    "end": "2026-06-10T17:00:00Z"
  },
  "candidates": [{ "start": "2026-06-10T10:00:00Z", "end": "2026-06-10T11:00:00Z", "risk": "free" }],
  "candidate_limit": 50,
  "available_candidate_count": 12,
  "candidates_truncated": false,
  "candidate_set": "exhaustive",
  "resolved_calendar_type": "work",
  "warnings": []
}

hold → confirm · TypeScript

// 1. Search availability — no reservation yet
const { candidates } = await client.searchAvailability({ ... });

// 2. Pick a candidate (e.g. present to user, await confirmation)
const chosen = candidates[0];

// 3. Reserve that candidate
const hold = await client.createHold({
  ownerEmail: 'alex@acme.com',
  meetingClass: 'Critical',
  holdScope: 'candidate',
  candidate: { start: chosen.start, end: chosen.end },
});

// 4. Confirm the hold → committed booking
const booking = await client.confirmHold({
  holdId:    hold.holdId,
  start:     chosen.start,
  end:       chosen.end,
  title:     'Q3 roadmap sync',
  attendees: [{ email: 'alex@acme.com' }],
});

console.log('Booking committed:', booking.bookingId);

rejection handling · TypeScript

import { ArbitrationRejectedError } from '@openavail/sdk';

try {
  const booking = await client.confirmHold({ holdId, start, end, title });
} catch (err) {
  if (err instanceof ArbitrationRejectedError) {
    if (err.alternatives.length > 0) {
      // COUNTER_PROPOSED: your slot is blocked but the hold window has
      // other free slots. alternatives[] are within the same holdId —
      // confirm immediately without a new availability check.
      const alt = err.alternatives[0];
      const retry = await client.confirmHold({
        holdId,           // same hold, different slot
        start: alt.start,
        end:   alt.end,
        title,
      });
    } else {
      // REJECTED: hard block (rule violation, higher-priority booking,
      // no preempt permission). No alternatives — start a new
      // searchAvailability call with a different window.
    }
  }
}

notifications · TypeScript

// Inline hint: only notifications from the last 60 minutes appear here.
const { bookingId, pendingNotifications } = await client.confirmHold({ ... });

// At session start, fetch the full unacked backlog (any age up to 7 days):
const allPending = await client.getPendingNotifications();

for (const n of allPending) {
  if (n.kind === 'booking.displaced') {
    console.log('Booking displaced — rescheduling:', n.payload);
  }
}

// Ack all at once (up to 100 IDs per call).
// Un-acked notifications persist for 7 days; after that they are swept.
await client.ackNotifications(allPending.map((n) => n.id));