Quickstart & API Key Authentication

Authenticate requests with persistent Agent API Keys, understand HTTP status codes, and make your first API call in 30 seconds.

1. Authentication Header

Similar to Channex's user-api-key header, Traveate authenticates every agent request using the x-agent-api-key HTTP header:

POST https://traveate.com/api/v1/agent-actions/get_property HTTP/1.1
Host: traveate.com
Content-Type: application/json
x-agent-api-key: traveate_ak_concierge_dev_key

{
  "property_id": "hope-homestay"
}

2. Development API Keys (Seeded)

3. Standard Error Format & Status Codes

All error responses return a structured JSON object with an error.code and human-readable error.message:

{
  "error": {
    "code": "STALE_PREVIEW",
    "message": "Underlying availability or rates changed since preview was generated. Please create a fresh preview."
  }
}

Connect Your Own AI Agent (MCP & HTTP)

Connect Claude Desktop, Cursor, Google Antigravity, or your own custom Python/TypeScript agent to Traveate in minutes.

Option 1: Connect via Model Context Protocol (MCP `stdio`)

Add the traveate-hospitality server to your MCP client configuration (e.g. mcp_config.json or claude_desktop_config.json):

{
  "mcpServers": {
    "traveate-hospitality": {
      "command": "node",
      "args": ["src/mcp/server.ts"],
      "env": {
        "TRAVEATE_API_URL": "https://traveate.com",
        "TRAVEATE_AGENT_API_KEY": "traveate_ak_concierge_dev_key"
      }
    }
  }
}

Option 2: Connect a Custom Agent over HTTP (TypeScript / Python)

If you are building a custom WhatsApp bot, voice concierge, or automated revenue agent, call POST /api/v1/agent-actions/:tool_name directly:

// TypeScript / Node.js Agent Example
const response = await fetch('https://traveate.com/api/v1/agent-actions/get_availability', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-agent-api-key': 'traveate_ak_concierge_dev_key',
  },
  body: JSON.stringify({
    property_id: 'hope-homestay',
    check_in_date: '2026-11-22',
    check_out_date: '2026-11-24',
    adults: 5,
  }),
});

const availability = await response.json();
console.log(availability.unit_types[0].rate_plans);

Homestay vs. Independent Hotel Data Models

How onboarding our second property (Rock Hyrax Hotel) alongside Hope Homestay unlocked a unified data model that handles both "Entire Place" vacation rentals and multi-room full-service hotels.

Side-by-Side Comparison

Archetype 1: Entire-Place Homestay (Hope Homestay)

Modeling a whole-home vacation rental where 1 to 8 guests book the entire property exclusively, with Airbnb flat-rate + fee pricing and Booking.com occupancy-tiered pricing.

Why Whole-Place Inventory Matters for Homestays

At Hope Homestay (4 en-suite bedrooms in Syokimau), selling individual bedrooms to separate, unrelated guests on the same date is impractical because guests share the living room, dining room, and kitchen.

By setting inventory_model: 'unique' on the property and creating a single UnitType (Entire Four-Bedroom Homestay (Whole House)) with inventory_count: 1 and max_occupancy: 8:

• Any confirmed booking—whether for 1 guest or 8 guests—immediately drops available_units from 1 to 0 for those dates.
• The physical house unit (SEED_IDS.units.room1) is automatically assigned to booking.unit_id upon confirmation.

Channel-Specific Pricing Configuration

1. Airbnb Flat Rate ($50/night + $10 Airbnb Fee = $60 Total)

On Airbnb (Listing #797494517027686373), the nightly rate is a flat $50/night regardless of the number of guests (1–8), plus a $10/night (20%) Airbnb service fee for a total of $60/night:

{
  "name": "Airbnb — Entire Place Flat Rate ($50/night + $10 Airbnb Fee = $60 Total)",
  "currency": "USD",
  "base_price_cents": 5000,
  "meal_plan": "room_only",
  "metadata": {
    "channel": "airbnb",
    "pricing_model": "flat_entire_place",
    "channel_fee": {
      "code": "AIRBNB_SERVICE_FEE",
      "name": "Airbnb Service Fee ($10/night)",
      "rate_pct": 20,
      "per_night_cents": 1000
    }
  }
}

2. Booking.com Occupancy-Tiered Pricing (2 Pax = $32 → 8 Pax = $60)

On Booking.com (hotel/ke/hope-homestay-syokimau), the entire 4-bedroom house is still sold exclusively, but the rate scales with the number of guests (pax = adults + children):

{
  "name": "Booking.com — Entire Place (Occupancy-Based 1–8 Pax)",
  "currency": "USD",
  "base_price_cents": 3200,
  "meal_plan": "room_only",
  "metadata": {
    "channel": "booking_com",
    "pricing_model": "occupancy_tiered",
    "occupancy_pricing": {
      "1": 3200,
      "2": 3200,
      "3": 3500,
      "4": 4000,
      "5": 4500,
      "6": 5000,
      "7": 5500,
      "8": 6000
    }
  }
}

Archetype 2: Full-Service Independent Hotel (Rock Hyrax Hotel)

Modeling an independent hotel with 5 pooled room categories (26 units), multi-board meal plans (BB / HB / FB), an on-site restaurant, and a 35-delegate conference hall.

1. Pooled Room Categories & Multi-Board Rate Plans

Validated against https://rockhyraxhotel.com, Rock Hyrax Hotel in Nakuru has inventory_model: 'pooled' across 5 room categories (26 rooms total). Each room category offers three meal-plan rate plans using metadata.price_offset_cents:

2. Restaurant & Conference Facilities in Property.policies.facilities

Unlike a homestay, an independent hotel generates significant revenue from dining and corporate conferencing. Traveate models these in Property.policies.facilities so AI concierge agents can answer corporate retreat and dining inquiries accurately:

{
  "entity_classification": "independent_full_service_hotel",
  "facilities": {
    "dining": [
      {
        "name": "Rock Hyrax Restaurant & Garden Terrace",
        "url": "https://rockhyraxhotel.com/restaurant/",
        "hours": "06:30 - 22:30",
        "cuisines": ["Kenyan Nyama Choma & Local Delicacies", "Continental", "Buffet & A La Carte"]
      }
    ],
    "conferencing": [
      {
        "name": "Hyrax Executive Conference & Banquet Hall",
        "url": "https://rockhyraxhotel.com/conferencing/",
        "capacity_persons": 35,
        "layouts": { "boardroom": 20, "u_shape": 25, "classroom": 30, "theatre": 35 },
        "equipment": ["HD LCD Projector & Screen", "PA System & Wireless Microphones", "High-Speed Fiber Wi-Fi"],
        "packages": [
          { "code": "FULL_DAY_CONFERENCE", "name": "Full-Day Conference Package", "rate_per_person_kes": 2800 },
          { "code": "HALF_DAY_CONFERENCE", "name": "Half-Day Conference Package", "rate_per_person_kes": 2200 }
        ]
      }
    ]
  }
}

Autonomous Agent Onboarding & Owner Verification

Owners shouldn't have to fill out 50 form fields. Give an agent a hotel name, website URL, or Google Maps link — let the agent research and onboard the property, and let the owner verify or correct it in the Dashboard.

The 3-Step Agent Onboarding Workflow

1. Owner Provides a Minimal Prompt: The owner gives the agent a property name and a public URL (e.g., https://rockhyraxhotel.com, a Booking.com link, or a Google Maps link).
2. Agent Researches & Calls onboard_property_preview / confirm: The agent extracts room categories, amenities, coordinates, restaurant details, and conference capacity, and stamps policies.onboarding_provenance with verification_status: 'pending_owner_review'.
3. Owner Verifies or Corrects in /dashboard: The owner opens /dashboard?property_id=rock-hyrax-hotel, adjusts any room rate, unit count, check-in time, or conference capacity, and clicks Save & Verify Property Details (calling POST /api/v1/properties/:id/verify-update or POST /api/v1/unit-types/:id/verify-update).

// POST /api/v1/properties/00000000-0000-4000-8000-000000000210/verify-update
{
  "check_in_time": "13:00",
  "conference_capacity": 40,
  "mark_verified": true,
  "confirmed_by": "rock-hyrax-general-manager"
}

Two-Step Preview → Confirm Write Protocol

How Traveate prevents AI hallucinations, race conditions, and double-bookings using state-hashed ActionPreviews and immutable AuditLogs.

How State-Hashed Previews Work

Every write action in Traveate is split into a *_preview tool and a *_confirm tool:

Agent calls create_booking_preview(...)
  │
  ├─► 1. Validates dates, occupancy, restrictions, and calculates exact PriceBreakdown
  ├─► 2. Computes SHA-256 state_hash of (UnitType + RatePlan + RateCalendar + CalendarBlocks + Overlapping Bookings)
  ├─► 3. Stores ActionPreview (status='pending', expires in 15 mins)
  └─► 4. Returns preview_id + human-readable resolved_proposal

Human Operator or Authorized Agent calls create_booking_confirm({ preview_id })
  │
  ├─► 1. Re-computes SHA-256 state_hash inside a SQLite transaction
  ├─► 2. If state_hash !== preview.state_hash ──► Throws 409 STALE_PREVIEW (prevents double-booking!)
  ├─► 3. Inserts Booking (auto-assigns unit_id if inventory_model === 'unique')
  └─► 4. Writes immutable AuditLog row (actor_type, actor_id, before, after)

Unified Availability & Pricing Engine (ARI)

How calculateAvailability in src/core/availability.ts resolves inventory and nightly prices across date overrides, guest occupancy tiers, channel fees, and meal boards.

Nightly Rate Precedence Order

For each night d in [check_in_date, check_out_date), Traveate resolves the nightly rate in strict priority order:

1. RatePlan-Specific Date Override (rate_calendar_plan): A row in rate_calendar matching both (unit_type_id, rate_plan_id, date).
2. UnitType Default Date Override (rate_calendar_default): A row in rate_calendar matching (unit_type_id, rate_plan_id IS NULL, date) (plus any price_offset_cents on the RatePlan).
3. Guest Occupancy Tier (RatePlan.metadata.occupancy_pricing): Maps total guest count String(adults + children) to minor units (used by Hope Homestay's Booking.com rate plan: 2 pax = 3200 .. 8 pax = 6000).
4. RatePlan Base Price (rate_plan_base): rate_plan.base_price_cents (used by Hope Homestay's Airbnb flat $50 rate plan) or unit_type.base_price_cents + price_offset_cents (used by Rock Hyrax Hotel's BB / HB / FB rate plans).
5. UnitType Base Price (unit_type_base): Fallback to unit_type.base_price_cents.

Taxes & Channel Fees

• Statutory Taxes (Property.tax_config.taxes): Percentage taxes applied to subtotal_cents (e.g. Rock Hyrax Hotel's 16% Kenya VAT + 2% Tourism Levy).
• Channel Service Fees (RatePlan.metadata.channel_fee): Per-night or percentage channel fees appended to price_breakdown.taxes (e.g. Hope Homestay's Airbnb +$10/night fee so $50/night base becomes $60/night total).

Properties & Unit Types Collection

Read, onboard, update, and owner-verify properties and sellable unit types.

Availability, Rates & Calendar Blocks (ARI)

Query real-time availability and nightly quotes across all channels, set date-specific rate overrides, and manage maintenance or owner blocks.

Bookings & Guests Collection

Retrieve reservations and guest profiles, and execute two-step booking creation, modification, and cancellation flows.

Reviews, Messaging & Regional Landmarks

Tools for guest communication across WhatsApp / OTAs, Google Business Profile review responses, and regional landmark directions.

Open Channel Manager (Two-Way iCal + Gmail IMAP OTA Email Poller)

How Traveate syncs availability two-way with Airbnb and Booking.com without paid middleware, and upgrades iCal date blocks into full guest reservations by polling hopehomestayke@gmail.com.

How Stage 1 (Two-Way iCal) & Stage 2 (Gmail IMAP OTA Upgrade) Work Together

1. Scheduled Inbound iCal Poller (poll_channel_feeds)
   ├─► Fetches https://www.airbnb.com/calendar/ical/797494517027686373.ics?t=...
   └─► Upserts idempotent CalendarBlock (reason='channel_sync', external_uid)
       ──► Immediately blocks dates so no double-booking can occur!

2. Built-In Gmail IMAP-TLS OTA Email Poller (POST /api/v1/ota-emails/poll-gmail)
   ├─► Connects to imap.gmail.com:993 (hopehomestayke@gmail.com) via node:tls
   ├─► Decodes HTML / quoted-printable Airbnb & Booking.com confirmation emails
   ├─► Extracts guest name, email, phone, pax count, payout, and confirmation code
   └─► Atomically upgrades the matching channel_sync CalendarBlock into a full
       Booking + Guest record WITHOUT double-deducting availability!

Channel-Specific Outbound iCal Export URLs (Loop-Safe)

Each channel-specific .ics endpoint automatically excludes blocks imported from that same channel so Airbnb and Booking.com never echo their own blocks back:

• Hope Homestay (For Airbnb Step 1): GET /api/v1/properties/hope-homestay/airbnb.ics
• Hope Homestay (For Booking.com): GET /api/v1/properties/hope-homestay/booking_com.ics
• Rock Hyrax Hotel (Master iCal): GET /api/v1/properties/rock-hyrax-hotel/ical.ics

Living Property Memory & Dual-Persona AI Architecture

How Traveate remembers every property's unique edge cases in property_knowledge, learns continuously from host rejection feedback, and enforces a strict security boundary between the Guest Website/WhatsApp Concierge and the Host Operations Copilot.

1. Living Property Playbook (property_knowledge)

Instead of hardcoding property quirks in prompts, Traveate stores structured operational rules per property (pricing_quirk, checkin_checkout, house_rule, guest_faq, operations_sop, feedback_learned) and grows smarter through three loops:

• Reject & Teach Loop (POST /api/v1/previews/:id/reject): When a host rejects an ActionPreview and provides a rejection_reason (e.g., "Peak December bookings between Dec 15 and Jan 5 require a 3-night minimum stay"), Traveate automatically saves a feedback_learned rule linked to source_preview_id.
• Host Copilot Chat Training: Saying "Remember for Hope Homestay: Airport pickup from JKIA Terminal 1A is $20 flat..." invokes remember_property_knowledge (source: "copilot_chat").
• Automatic Playbook Retrieval: Both the Guest Concierge and Host Copilot call list_property_knowledge to cite verified rules when answering inquiries.

2. Dual-Persona Split: Guest Concierge vs. Host Operations Copilot

Interactive API & MCP Playground

Test live get_availability quotes across Hope Homestay (try changing Guests from 2 to 8 to see Booking.com occupancy tiers $32–$60 vs Airbnb flat $50 + $10 = $60) and Rock Hyrax Hotel (BB / HB / FB meal plans).

// Click "Run MCP Tool: get_availability" above to query http://localhost:3456/api/v1/agent-actions/get_availability

Live AI Concierge & Onboarding Webhook Playground

Send a natural-language guest or onboarding prompt to POST /api/v1/concierge/chat and inspect the exact MCP tool trace and ActionPreview generated:

// Click "Send to Concierge Agent" above to call POST /api/v1/concierge/chat