# LetsBookings — The agent API for cheaper stays.

> This file is for AI agents and LLMs. Humans should visit the project README.
> Full agent guide: /AGENTS.md

## What is LetsBookings?

LetsBookings scans short-term rental platforms (Airbnb, Booking.com, Vrbo, and more) and returns **total-price** offers — nightly rate plus cleaning, service fees, and taxes. The same listing that looks cheap at $89/night is often $150+ all-in; we rank by what the guest actually pays.

---

## TRAFFIC CONTROL — Which method to use

| If you are...                                      | Best approach                                          |
|----------------------------------------------------|--------------------------------------------------------|
| ChatGPT / GPT-based agent                          | Bearer token + POST /api/search + poll                 |
| Claude (claude.ai / Claude Code / Claude Desktop)  | MCP (planned) → Bearer token + POST /api/search        |
| Perplexity, Gemini, Copilot                        | Bearer token + POST /api/search + poll                 |
| OpenClaw, Hermes, Manus, autonomous agents         | Bearer token + POST /api/search                        |
| Cursor, Windsurf, IDE agents                       | MCP (planned) or Bearer + REST                         |
| Any other agent                                    | Bearer token + POST /api/search + poll                 |

Website search (when live) is human-only (bot protection). Agents must use the API.

Base URL (production): `https://letsbooking.bitscorp.co`
Local default: `http://localhost:8787`

## Default search is agentic

| Client | Endpoint |
|--------|----------|
| Homepage | `POST /api/public/agent` |
| SDKs / MCP (default) | `POST /api/agent/search` |
| Chat follow-ups | `POST /api/agent/chat` |
| Classic async poll (opt-in) | `POST /api/search` + `GET /api/results/{id}` |

```
POST /api/agent/search
Authorization: Bearer <api_key>
{ "query": "Barcelona 2 guests under 100€/night", "mode": "react"|"crew", "session_id": optional }
→ { "status": "completed", "offers": [...], "message": "...", "agentic": true, "session_id": "..." }
```

```
POST /api/public/agent   # no auth — homepage demo
{ "query": "..." }
```

- **react** — model-driven Thought→Action→Observation tool loop with self-correction
- **crew** — Searcher → Evaluator → Presenter multi-agent
- Session memory for follow-ups ("closer to the Gothic quarter")
- Long-term preferences via tools
- LLM: xAI Grok when `XAI_API_KEY` is set; otherwise heuristic tool loop
- UI: `/` (default), `/agent` · status: `GET /api/agent/status`

## Official SDKs

| Language | Package | Install | Repo |
|----------|---------|---------|------|
| Python | `letsbooking` | `pip install git+https://github.com/letsbooking/letsbooking-python.git` | https://github.com/letsbooking/letsbooking-python |
| JavaScript / TypeScript | `letsbooking` | `npm install github:letsbooking/letsbooking-js` | https://github.com/letsbooking/letsbooking-js |
| MCP | `letsbooking-mcp` | `npx -y github:letsbooking/letsbooking-mcp` | https://github.com/letsbooking/letsbooking-mcp |

Python:
```python
from letsbooking import LetsBooking
client = LetsBooking(api_key="lb_live_…")
result = client.search("Barcelona 2 guests Aug 10-14 2026")
print(result.cheapest.summary())
```

JavaScript:
```js
import { LetsBooking, offerSummary } from "letsbooking";
const client = new LetsBooking({ apiKey: "lb_live_…" });
const result = await client.search("Barcelona 2 guests Aug 10-14 2026");
console.log(offerSummary(result.cheapest));
```

---

## PROGRAMMATIC SEARCH — API key required

### Step 1 — Request an API key (recommended)

Humans: open https://letsbooking.bitscorp.co and submit the form under **Request an API key**.

Agents / scripts:
POST /api/access/request
Content-Type: application/json

{
  "name": "My Agent",
  "email": "you@example.com",
  "company": "optional",
  "use_case": "stay search for booking bot"
}

An admin reviews at /admin and issues a Bearer API key.

Admin (with ADMIN_API_KEY):
- GET /api/admin/requests?status=pending
- POST /api/admin/requests/{id}/approve
- POST /api/admin/keys/mint  { "label": "...", "email": "..." }

### Alternate — challenge token (legacy)

POST /api/agent-access/request → verify with tweet_url (local accepts any URL).

### Step 2 — Start a search

POST /api/search
Authorization: Bearer YOUR_API_KEY
# or: X-API-Key: YOUR_API_KEY
Content-Type: application/json

Natural language (recommended):
{"query": "Barcelona entire place 2 guests July 10-14 2026 under 150/night total"}

Or structured (faster, no NL parse):
{
  "location": "Barcelona",
  "check_in": "2026-07-10",
  "check_out": "2026-07-14",
  "guests": 2,
  "currency": "EUR",
  "max_total_price": 800
}

Response: {"search_id": "ws_...", "status": "searching", "parsed": {...}}

If ambiguous: HTTP 422 with `needs_clarification: true` and `follow_up_questions`.

### Step 3 — Poll for results

GET /api/results/{searchId}
Authorization: Bearer YOUR_TOKEN

Poll every 10 seconds.

While searching: { "status": "searching", "progress": {"checked": 2, "total": 3, "found": 12} }
When done: { "status": "completed", "total_results": 24, "cheapest_total": 412.0, "offers": [...] }
If expired: { "status": "expired" }

### Step 4 — Read offers

Each offer includes:
- id, title, source (airbnb|booking|vrbo|direct|sandbox)
- location, check_in, check_out, nights, guests
- price: nightly, cleaning_fee, service_fee, taxes, **total**, total_per_night
- rating, reviews, amenities, property_type
- url (null until unlock)

Sort default: ascending by `price.total`.

### Step 5 — Unlock booking URL (planned)

POST /api/v1/bookings/unlock
Body: {"offer_id": "stay_..."}
Returns confirmed total + deep link to the source platform or direct host.

---

## Understanding total price

Always compare `price.total` (and `total_per_night`), never bare nightly rates.

Example:
- Nightly $95 × 4 nights = $380
- Cleaning $45 + service $62 + taxes $28
- **Total $515** → $128.75 / night all-in

---

## Live sources (Airbnb + Booking.com)

`POST /api/search` fans out with **Playwright** (headless Chromium) — no RapidAPI:

- **airbnb** — opens Airbnb search URL, parses listings + prices from page/JSON
- **booking** — opens Booking.com searchresults, parses property cards + totals

Pass `"sources": ["airbnb", "booking"]` (default) on structured search.

Poll response extras:
- `mode`: `live` | `sandbox`
- `sources_ok`: sources that returned offers
- `source_errors`: per-source failures (blocked, captcha, timeout, layout change)
- offer `url`: deep link to airbnb.com or booking.com for that listing/dates

Check: `GET /api/sources` (Bearer) or `GET /health` (`playwright_enabled`).

Set `PLAYWRIGHT_ENABLED=false` to force sandbox-only.

## Sandbox

Fake inventory when live keys are missing or `sources` includes `sandbox`. Marked `source: "sandbox"`. Not bookable.

OpenAPI: /openapi.yaml
Health: GET /health