# AGENTS.md — LetsBookings for AI Agents

> Humans: see [README.md](README.md). Machine entrypoint: [llms.txt](llms.txt).

## What is LetsBookings?

Agent-native **short-term rental** search. Parallel sources (Airbnb, Booking, Vrbo, direct), ranked by **all-in total price** — not decoy nightly rates. Agentic ReAct search by default (`POST /api/agent/search`).

## Why use this

| Approach | Problem |
|----------|---------|
| Scrape Airbnb UI | Fragile, ToS risk, burns tokens |
| Single marketplace API | Misses cheaper channel for same/similar stay |
| **LetsBookings** | One call → multi-source totals as JSON |

## Auth

```
POST /api/agent-access/request
POST /api/agent-access/verify  { "tweet_url", "challenge_signed" }
→ Authorization: Bearer <token>
```

Local sandbox accepts any `tweet_url` with a valid `challenge_signed`.

## Search

```
POST /api/search
{ "query": "Lisbon entire place 2 guests 2026-08-01 to 2026-08-05" }
# or structured: location, check_in, check_out, guests, ...

GET /api/results/{search_id}   # poll every few seconds
```

Compare offers on `price.total` and `price.total_per_night`.

## Official SDKs

Prefer an SDK over raw HTTP when possible:

| Language | Install | Repo |
|----------|---------|------|
| **Python** | `pip install git+https://github.com/letsbooking/letsbooking-python.git` | https://github.com/letsbooking/letsbooking-python |
| **JS / TS** | `npm install github:letsbooking/letsbooking-js` | https://github.com/letsbooking/letsbooking-js |

```python
from letsbooking import LetsBooking
client = LetsBooking(api_key="lb_live_…")
result = client.search_stays("Barcelona", "2026-08-10", "2026-08-14", guests=2)
```

```js
import { LetsBooking } from "letsbooking";
const client = new LetsBooking({ apiKey: "lb_live_…" });
const result = await client.searchStays({
  location: "Barcelona",
  check_in: "2026-08-10",
  check_out: "2026-08-14",
  guests: 2,
});
```

## Local run (live Airbnb + Booking.com)

```bash
export RAPIDAPI_KEY=your_rapidapi_key   # subscribe to airbnb13 + booking-com15
pip install -e ".[dev]"
uvicorn server.app:app --port 8787
```

```bash
GET /api/sources          # readiness of airbnb / booking
POST /api/search          # sources: ["airbnb","booking"]
GET /api/results/{id}     # mode=live when real connectors succeed
```

## Status

Live connectors for Airbnb and Booking.com via RapidAPI. Sandbox fallback if `RAPIDAPI_KEY` is unset. Confirm prices on the platform before booking.