Overview

Availability

Get bookable slots for a specific venue before creating a booking.

Returns live reservation availability for a specific venue. Supply a venue ID, party size, and preferred datetime to POST /v1/availability/search to retrieve all available booking slots. The venue must come from POST /v1/venues/search first; an unknown venue_id returns 404 ("venue not found; run venues/search first"). The response also says whether the venue requires a card down (card_required) and, on each OpenTable and Resy slot, what booking it commits the guest to (terms; see Restaurant terms).

Required: venue_id. Recommended: party_size (defaults to 2) and datetime (defaults to 24 hours from now). Optional: window_minutes, check_card_required.

venue_idThe venue identifier returned from venue search, e.g. ven_1a2b3c4d.party_sizeNumber of guests. Slots are returned for this party size. Defaults to 2.datetimePreferred time, RFC3339 or a local time without an offset (2026-11-14T19:00:00). Interpreted as the venue's local wall-clock time; a timezone suffix is converted to local automatically; no suffix is treated as already local. A date that has already passed is moved to today at the same time of day. Slots are returned in a window centered on this time.window_minutesHow wide a time window to return slots for, centered on the requested datetime.check_card_requiredRarely needed. card_required is reported whenever the restaurant states it, flag or not: OpenTable on every read, Resy whenever it is known. When true and OpenTable's card policy cannot be read directly, Ophelia falls back to clicking a slot to learn it, which briefly holds a table.

curl

curl -X POST https://api.opheliaos.com/v1/availability/search \
  -H "Authorization: Bearer YOUR_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "venue_id": "ven_1a2b3c4d",
    "party_size": 2,
    "datetime": "2026-11-14T19:00:00-08:00"
  }'

Response

json

{
  "venue_id": "ven_1a2b3c4d",
  "slots": [
    {
      "availability_id": "avail_0772690bf37353a0",
      "kind": "time",
      "venue_id": "ven_1a2b3c4d",
      "datetime": "2026-11-14T17:30:00-08:00",
      "datetime_utc": "2026-11-15T01:30:00Z",
      "display_time": "5:30 PM",
      "party_size": 2,
      "status": "available",
      "price_required": false,
      "deposit_required": false,
      "terms": {
        "source": "opentable_restref",
        "card_required": true,
        "card_policy": "hold",
        "cancellation_fee": { "amount_cents": 2500, "currency": "USD", "per": "guest", "from_text": true },
        "cancellation_cutoff_hours": 24,
        "policies": [
          { "kind": "cancellation", "text": "This restaurant requires a credit card to secure this reservation. ... No-shows or cancellations less than 24 hours in advance may be subject to a charge of $25.00 per person." },
          { "kind": "booking_policy", "text": "We have a 15 minute grace period. Please call us if you are running later than 15 minutes after your reservation time." }
        ],
        "read_for": { "date": "2026-11-14", "time": "17:30", "party_size": 2 }
      }
    },
    {
      "availability_id": "avail_ccc14b2ec218b03e",
      "kind": "time",
      "venue_id": "ven_1a2b3c4d",
      "datetime": "2026-11-14T17:45:00-08:00",
      "datetime_utc": "2026-11-15T01:45:00Z",
      "display_time": "5:45 PM",
      "party_size": 2,
      "status": "available",
      "price_required": false,
      "deposit_required": false
    },
    {
      "availability_id": "avail_b1b40a7a228f943b",
      "kind": "time",
      "venue_id": "ven_1a2b3c4d",
      "datetime": "2026-11-14T19:45:00-08:00",
      "datetime_utc": "2026-11-15T03:45:00Z",
      "display_time": "7:45 PM",
      "party_size": 2,
      "status": "available",
      "price_required": false,
      "deposit_required": false
    }
  ],
  "card_required": true
}

Each slot's datetime carries the venue's local offset, datetime_utc is the same instant in UTC, and display_time gives the human-readable local time ready to render in your UI. kind says what distinguishes the options: time for a reservation time, room for a hotel room (no clock; see Hotels), itinerary for a flight. Every OpenTable and Resy slot carries its own terms; the example shows them on the first slot only, to keep it short.

To book a slot, send its availability_id and its datetime to POST /v1/bookings. The booking is held to the time the slot was offered at: a different datetime is refused with 400 slot_not_offered. An availability_id is good for 15 minutes; after that it is ignored and the booking runs on venue_id and datetime alone.

card_required is true when any open slot needs a card, and omitted when the policy is unknown. When it is true, the booking needs a card: include metadata.payment, or pay through AgentCard. Each slot's terms says what that card is for and what a late cancellation costs: see Restaurant terms.