Quick start

1Get your API key

Create a key on the API Keys page and send it as a Bearer token on every /v1 request.

2Search

Required: vertical, term, location, datetime (RFC3339), plus party_size for entertainment (the ticket quantity). Travel (hotels) is the one exception to datetime: it takes check_in and check_out instead, plus rooms; see the Hotels page. datetimeis always 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.

Returns a venues array and a count; each venue has a stable ven_ id. Each venue also includes a top-level image field with a representative photo from the provider; the same URL appears as photo_url inside metadata. If the provider returns no photo, image is omitted from the response. When some providers answered and others failed, the response is still 200 and lists the failures in providers_failed; when every provider failed it is 502 search_failed, which is safe to retry.

curl -X POST https://api.opheliaos.com/v1/venues/search \
  -H "Authorization: Bearer YOUR_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "dining",
    "term": "sushi",
    "location": "New York, NY",
    "datetime": "2026-11-14T19:30:00-05:00",
    "party_size": 2
  }'

3Create a booking

Required: venue_id and a customer. For dining, customer.name, party_size (1–20) and a datetime in the future are also required; see Required fields. The customer must be the real guest: an example.com email, a US number in a 555 exchange (like +1 212 555 0123) or a name like "Customer Name" is refused with 400 placeholder_customer before anything runs. To book a slot from availability, also send its availability_id.

The request is held (suspended) server-side for up to 150 seconds until the booking reaches its next step (requires_action or a final status) and returns it inline with 200; no wait parameter is needed. If it is still processing when the hold ends you get 202; poll GET /v1/bookings/{id}. Set your HTTP client's timeout above 150 seconds, or the booking keeps running after your client has given up.

Optional but recommended: send a unique Idempotency-Key header (e.g. a UUID) per booking so a retried request does not double-book (you generate it, not us). A key is remembered for your organization indefinitely: sending it again returns the booking it first created, whatever the body says.

curl -X POST "https://api.opheliaos.com/v1/bookings" \
  -H "Authorization: Bearer YOUR_LIVE_KEY" \
  -H "Idempotency-Key: 6f1c2b0e-8d4a-4f6e-9b3a-2c7d5e1f0a94" \
  -H "Content-Type: application/json" \
  -d '{
    "venue_id": "ven_12345678",
    "datetime": "2026-11-14T19:30:00-05:00",
    "party_size": 2,
    "customer": {
      "name": "Jane Smith",
      "phone_number": "+15555555555",
      "email": "jane.smith.diner@gmail.com"
    }
  }'

Booking for a person who has connected their own account? Send your id for them as end_user and the booking runs signed in as them; see Sessions.

4Complete an action

When status is requires_action, next_action.requirements names the fields to send (for a code, otp_code) and next_action.expires_at says how long you have. Submit them via POST /v1/bookings/{booking_id}/continue, which is held the same way as create.