🤖 AI Agent Integration Guide

Complete documentation for integrating ChatGPT, Claude, and other AI agents with CielStay's semantic search API.

✨ Hybrid Semantic Search

CielStay uses a 3-stage hybrid semantic search powered by pgvector embeddings:

Stage 1 - Semantic Retrieval: Vector similarity search returns top 500-2000 candidates based on conceptual understanding
Stage 2 - Structured Filtering: Apply hard constraints (bedrooms, bathrooms, pets, dates)
Stage 3 - Multi-Signal Ranking: Location (50%), explicit criteria (25%), visual appeal (15%), semantic fit (10%)

What this means for agents:

Send natural, descriptive language — the more specific, the better
Use concepts, not keywords: "romantic getaway" instead of just "2 bedroom"
Include context: location names, amenities, vibe, purpose of stay
Synonyms work automatically: "cozy" = "warm" = "comfortable"
Multi-destination queries work: "near Anza Borrego, San Diego, and Legoland"

🚀 Quick Start

For Free ChatGPT Users (No GPT Access)

Free users can manually construct search URLs and ask ChatGPT to fetch and analyze results:

Step 1 - Create a search session:
https://www.cielstay.com/api/session/YOUR-UNIQUE-ID/search?q=YOUR_DETAILED_QUERYStep 2 - Refine using same ID:
https://www.cielstay.com/api/session/YOUR-UNIQUE-ID/search?q=REFINEMENT_QUERY

Example Queries (Good vs. Great)

❌ Basic (keyword)	✅ Great (semantic)
cabin hot tub	romantic mountain cabin with hot tub and fireplace for anniversary weekend near ski resort
beach house 4 bedroom	luxurious beachfront villa with infinity pool for family reunion sleeps 10 with chef's kitchen
downtown loft	modern downtown loft walking distance to restaurants art galleries theaters rooftop terrace

For Custom GPTs (Paid ChatGPT Users)

Use the two-step consent flow to respect user privacy:

Create lightweight session: GET /?title=5+word+description → Returns session URL
Ask user for consent: "CielStay has created a session at [URL]. Would you like me to send your detailed preferences?"
If approved, send full query: GET /session/[sessionId]?q=detailed+semantic+query

👤 Collecting Guest Resonance Profiles

Key Insight: Semantic search improves dramatically with rich context about the guest's travel style, preferences, and group dynamics. More context = better matches.

Recommended Flow: Progressive Disclosure

🎯 Best Practice: Start Simple, Deepen Progressively

Initial Query (Basic Intent):
Start with the guest's core request: location, dates, basics
"4 bedroom house near San Diego beaches for family of 5"
Show Results + Offer Enhancement:
After first search: "I found 12 properties. Would you like to share more about your travel style so I can refine these results? (e.g., Are you looking for quiet/social? Active/relaxing? Kid-focused?)"
If User Agrees, Collect Resonance Profile:
Ask follow-up questions naturally:
- "What's the purpose of your trip?" (reunion, celebration, work retreat)
- "What's your group like?" (active family, quiet couple, friend group)
- "What matters most?" (privacy, amenities, walkability, views)
- "Any dealbreakers?" (must have pool, no stairs, pet-friendly)
Send Enriched Refinement Query:
Combine answers into semantic-rich refinement:
"family of 5 with young kids celebrating birthday weekend, want pool and game room, prefer quiet neighborhood with outdoor space for kids to run around"

What to Collect (Non-Sensitive Only)

✅ Collect These (Great for Semantic Search)

Trip purpose (vacation, reunion, retreat)
Group composition (family, friends, couples)
Travel style (active, relaxing, cultural)
Property vibe (cozy, modern, luxury, rustic)
Must-have amenities (pool, hot tub, kitchen)
Preferred activities (hiking, beaches, dining)
Pace preference (home base vs. road trip)
Priorities (privacy, walkability, views)

❌ Don't Collect These (Privacy-Sensitive)

Names or contact information
Exact income or financial details
Medical conditions or disabilities
Specific ages (use "young kids", "teens")
Ethnicity, religion, or identity markers
Reasons that might imply vulnerability
Payment method preferences
Previous booking failures or disputes

Example: Good vs. Great Query Enrichment

Initial Query (Basic):

"4 bedroom house near San Diego"

After Collecting Resonance Profile (Enhanced):

"4 bedroom family-friendly house near San Diego beaches for family of 5 with young kids celebrating birthday, want heated pool and game room, prefer quiet safe neighborhood with fenced yard and outdoor space for kids to play, looking for home base for day trips to Legoland and San Diego Zoo, relaxed cozy vibe"

💡 Result: The enriched query gives semantic search much more signal to find the perfect match, not just any match.

Sample Agent Dialogue

User: Find me a vacation rental in San Diego
Agent: [searches with basic query]
Agent: I found 47 properties in San Diego. To help narrow this down to your perfect match, would you mind sharing:
• When are you planning to visit?
• How many people in your group?
• What's the purpose of your trip? (vacation, celebration, work)
User: March 15-22, family of 5, celebrating my daughter's 8th birthday
Agent: Wonderful! A few more quick questions to find the best fit:
• What kind of vibe? (cozy/modern, quiet/social, budget/luxury)
• Any must-have amenities? (pool, game room, outdoor space)
• Planning to explore or stay mostly at the house?
User: Cozy and kid-friendly. Pool is a must. Want to do day trips to Legoland and the Zoo.
Agent: [refines with enriched query:]
"family-friendly house with pool game room for family of 5 celebrating daughter's birthday, cozy kid-safe vibe, home base for Legoland and San Diego Zoo day trips, March 15-22"

Perfect! Here are 5 properties that match your family celebration...

⚠️ Privacy Note: Always get user consent before collecting additional context. Make it clear that sharing more details helps find better matches, but is completely optional. Never store or transmit sensitive personal information.

📡 API Endpoints

GET /api/session/:sessionId/search

Create or continue a search session. Session ID can be any string.

Query Parameters:

q (required): Natural language search query
limit (optional): Max results (default: 20)
offset (optional): Pagination offset (default: 0)

// Example Request
GET /api/session/my-search-123/search?q=cozy+cabin+near+Anza+Borrego&limit=5

// Example Response
{
  "success": true,
  "sessionId": "my-search-123",
  "results": [
    {
      "listing": {
        "id": "...",
        "title": "Desert Oasis Cabin",
        "city": "Borrego Springs",
        "bedrooms": 2,
        "bathrooms": 1,
        "price": 150,
        ...
      },
      "score": 0.87,
      "reasoning": "Location: 0.95, Semantic: 0.82, Visual: 0.75, Explicit: 0.90"
    }
  ],
  "count": 5,
  "manifest": {
    "filters": {...},
    "preferences": {...}
  }
}

POST /api/search/intelligent

Stateless semantic search (no session tracking).

// Example Request
POST /api/search/intelligent
Content-Type: application/json

{
  "query": "romantic mountain cabin with hot tub",
  "limit": 10,
  "useTypes": 7,  // 1=Stay, 2=Rent, 4=Sale (bitwise)
  "allowPets": false
}

// Response: Same structure as session search

📋 Resonance Manifest Schema

For advanced agents that want to track and refine user preferences across sessions, use the manifest schema:

{
  "filters": {
    "locations": ["San Diego", "Anza Borrego"],
    "bedrooms": { "min": 2, "max": 4 },
    "bathrooms": { "min": 2 },
    "priceRange": { "min": 100, "max": 300 },
    "propertyTypes": ["cabin", "house"],
    "amenities": ["hot_tub", "fireplace", "mountain_view"],
    "allowPets": true,
    "dates": {
      "checkIn": "2026-03-15",
      "checkOut": "2026-03-22"
    }
  },
  "preferences": {
    "vibe": ["cozy", "romantic", "secluded"],
    "purpose": "anniversary weekend",
    "priorities": ["privacy", "views", "outdoor_access"],
    "groupSize": 2,
    "specialRequests": [
      "close to hiking trails",
      "stargazing opportunities"
    ]
  },
  "context": {
    "previousSearches": ["mountain cabin", "hot tub cabins"],
    "viewedListings": ["listing-id-1", "listing-id-2"],
    "bookmarkedListings": ["listing-id-3"],
    "conversationHistory": [
      {"role": "user", "content": "Find me a romantic cabin"},
      {"role": "assistant", "content": "Here are 5 romantic cabins..."}
    ]
  }
}

How to use manifests:

First search creates session with initial manifest
Each refinement updates relevant manifest fields
System preserves context across multiple queries
Manifest visible in session URL for transparency

📖 Full manifest documentation: See RESONANCE_MANIFESTS.md for complete schema and examples.

💡 Best Practices

✅ Use Natural Language

"Family-friendly beach house with game room and heated pool near Legoland" beats "4 bedroom pool house"

✅ Preserve Session IDs

Use the same session ID for all refinements. System automatically creates session if it doesn't exist.

✅ Include Context

Mention purpose ("anniversary", "family reunion"), vibe ("cozy", "luxury"), and activities ("skiing", "hiking")

✅ Multi-Destination Works

"Central to Anza Borrego, San Diego Zoo, and Legoland" - system finds properties with good centrality

✅ Respect Rate Limits

Semantic search uses embeddings (compute-intensive). Reasonable usage welcome, please cache when possible.

🤝 Support & Feedback

We welcome AI agent integrations! If you have questions, feature requests, or need help implementing: