PRAP v1.0|STATUS: READY|SESSION: ANON

⚠️ This interface is optimized for AI browser agents, not humans.← Return to Human UI

PRICEROOM AGENT PROTOCOL

Machine-native OTA interface for AI browser agents

[QUICK_ACTIONS]

[CONVERSATIONAL_SEARCH]

Natural language dialogue with clarifying questions

[STRUCTURED_SEARCH]

Form-based hotel search with filters

[VIEW_API_SCHEMA]

Machine-readable API documentation

[CONVERSE_API]

Multi-turn conversation endpoint

[CAPABILITIES]

1. HOTEL_SEARCH

Search hotels by location, dates, guests. Returns JSON with prices from multiple OTAs.

2. A2A_NEGOTIATION

Agent-to-Agent price negotiation. Submit offers, receive counters. Max 3 rounds.

3. HANDOFF_GENERATION

Generate time-limited URLs for human payment verification. Direct booking disabled.

4. PRICE_COMPARISON

Compare against Booking.com, Expedia, Hotels.com in real-time.

[API_ENDPOINTS]

GET/api/agent/capabilities→ Schema documentation

GET/api/agent/suggest?q=London→ Location autocomplete (REQUIRED FIRST)

GET/api/agent/search?region_id=...→ Hotel search with live prices

GET/api/agent/hotel/:id→ Hotel details (JSON)

POST/api/agent/negotiate/start→ Start negotiation

POST/api/agent/negotiate/round→ Submit offer

POST/api/agent/lock-deal→ Generate handoff URL

[TYPICAL_WORKFLOW]

STEP 1: Get location suggestions → GET /api/agent/suggest?q=Paris

STEP 2: Select location → Use region_id from suggestions (e.g., region_id=2734)

STEP 3: Search hotels → GET /api/agent/search?region_id=2734&check_in=2025-02-01&check_out=2025-02-03

STEP 4: Select hotel → Note hotel_id from search results

STEP 5: Start negotiation → POST /api/agent/negotiate/start {hotel_id, target_price}

STEP 6: Submit offers → POST /api/agent/negotiate/round {negotiation_id, offer_price, urgency}

STEP 7: Generate handoff → POST /api/agent/lock-deal {negotiation_id, handoff_type}

STEP 8: Return handoff_url to human user for payment

[CONSTRAINTS]

Max Negotiation Rounds

Handoff Expiry (Accepted)

15 min

Handoff Expiry (Pending)

30 min

Direct Booking

DISABLED

[RATE_LIMITS]

SEARCH: 100 requests/hour

NEGOTIATE: 20 requests/hour

LOCK_DEAL: 10 requests/hour

[EXAMPLE_WORKFLOW]

// 1. Get location suggestions for "Paris"
GET /api/agent/suggest?q=Paris

// Response:
{
  "suggestions": [
    {
      "id": "paris-city",
      "name": "Paris, France",
      "type": "city",
      "region_id": 2734,
      "coordinates": { "lat": 48.8566, "lon": 2.3522 }
    }
  ]
}

// 2. Search hotels using region_id from suggestion
GET /api/agent/search?region_id=2734&check_in=2025-02-01&check_out=2025-02-03&adults=2

// Response includes hotels with LIVE PRICES from providers

// 3. Start negotiation for selected hotel
POST /api/agent/negotiate/start
{
  "hotel_id": "paris_123",
  "target_price": 180,
  "currency": "EUR",
  "check_in": "2025-02-01",
  "check_out": "2025-02-03",
  "rooms": [{"adults": 2}]
}

// 4. Hotel counters at €200. Submit counter-offer.
POST /api/agent/negotiate/round
{
  "negotiation_id": "neg_abc123",
  "offer_price": 185,
  "justification": "Found €180 on Booking.com",
  "urgency": "high"
}

// 5. Deal accepted at €190. Generate handoff.
POST /api/agent/lock-deal
{
  "negotiation_id": "neg_abc123",
  "handoff_type": "accepted",
  "message_to_human": "Negotiated 15% off! €190 instead of €225."
}

// Response:
{
  "handoff_url": "https://priceroom.com/agent/handoff/xyz789...",
  "expires_at": "2025-01-15T12:15:00Z",
  "savings_percent": 15
}