# Callbookit

> AI-powered reservation booking platform. Search venues worldwide, pay a small booking fee, and an AI agent calls the venue to make your reservation.

## Overview

Callbookit lets users book reservations at restaurants, bars, hotels, spas, and other venues across 39 cities worldwide. Instead of calling venues yourself, Callbookit's AI phone agent handles the call for you. The platform supports natural language venue search, Stripe payments, booking modifications, follow-up calls, coupon credits for failed calls, email OTP-based reservation lookup, and Apple Wallet passes.

## API Base URL

https://callbookit.com/api

## Authentication

- Frontend users: Automatic HttpOnly session cookie (`__cbk_session`)
- Developers: API key via `X-API-Key` header (register at `POST /api/developers/register`)
- API key format: `cbk_` prefix + 24 bytes base64url

## Core Endpoints

### Places (Venue Search)
- `POST /api/places/search` — Natural language venue search (e.g., "best sushi in Tokyo")
- `POST /api/places/explore` — Browse by location, category, radius, with sorting and pagination
- `GET /api/places/{placeId}` — Full venue details (photos, reviews, hours, contact info)
- `GET /api/places/photo?ref=` — Photo proxy (prevents API key exposure)

### Reservations (AI Phone Calls)
- `POST /api/reservations` — Create reservation + trigger AI phone call
- `GET /api/reservations/{id}` — Get status (syncs with Bland AI call status)
- `POST /api/reservations/{id}/modify` — Modify confirmed booking via AI call
- `POST /api/reservations/{id}/rebook` — Book alternative time via follow-up AI call
- `POST /api/reservations/lookup` — Send OTP to email for private reservation lookup
- `POST /api/reservations/verify` — Verify OTP, return matching reservations

### Payments (Stripe)
- `GET /api/payments/config` — Get Stripe publishable key
- `POST /api/payments/create-intent` — Create payment intent (fees: $1.50 restaurants, $3 doctors, $5 hotels)

### Coupons
- `POST /api/coupons/validate` — Validate coupon code (auto-issued for failed calls)

### Developer Registration
- `POST /api/developers/register` — Register for API key (max 3 per email)

### Apple Wallet
- `GET /api/wallet/{reservationId}/apple-pass` — Download .pkpass file
- `GET /api/wallet/status` — Check if Apple Wallet is configured

## Rate Limits

- Search: 60/min
- Place details: 120/min
- Create reservation: 10/min
- Status check: 30/min
- Modify/rebook: 5/min
- Payments: 20/min
- Coupons: 10/min
- Developer registration: 5/hr

## Booking Flow

1. User searches for a venue via natural language
2. User fills in booking details (name, email, phone, date, time, party size)
3. User pays booking fee via Stripe
4. AI phone agent calls the venue
5. AI analyzes call transcript to determine outcome
6. User receives email with call result and transcript
7. If call fails, user receives a coupon credit for their next booking

## Call Statuses

`pending` → `calling` → `completed` | `failed` | `no_answer` | `alternatives_available`

## Coverage

- 39 cities (25 US + 14 international)
- 20 venue categories
- 839 SEO landing pages

## MCP Server (Model Context Protocol)

Callbookit provides an MCP server for AI agents and LLM-powered applications. Connect any MCP-compatible client (Claude Desktop, Cursor, etc.) to interact with the booking platform programmatically.

### Setup
```json
{
  "mcpServers": {
    "callbookit": {
      "command": "npx",
      "args": ["-y", "@workspace/mcp-server"],
      "env": {
        "CALLBOOKIT_API_KEY": "cbk_your_api_key_here",
        "CALLBOOKIT_API_URL": "https://callbookit.com/api"
      }
    }
  }
}
```

### Available Tools (14)
- `search_venues` — Natural language venue search
- `explore_venues` — Browse by location, category, radius
- `get_venue_details` — Full venue details
- `create_payment_intent` — Create Stripe payment for booking fee
- `create_reservation` — Book + trigger AI phone call
- `get_reservation_status` — Check call/booking status
- `modify_reservation` — Modify confirmed booking via AI call
- `rebook_reservation` — Book alternative time
- `lookup_reservations` — Send OTP for email-based lookup
- `verify_reservations` — Verify OTP, get reservations
- `validate_coupon` — Check coupon validity
- `get_payment_config` — Get Stripe publishable key
- `check_wallet_status` — Check Apple Wallet availability
- `register_developer` — Register for API key

## Documentation

- Interactive API docs: https://callbookit.com/api/docs
- Full LLM context: https://callbookit.com/llms-full.txt
- Sitemap: https://callbookit.com/sitemap.xml