# Traveate REST API & MCP Tool Reference

Every operation in Traveate is available through both:
1. **REST API Endpoints** (`/api/v1/...`) for dashboards, PMS/channel integrations, and web apps.
2. **MCP Tools** (`POST /api/v1/agent-actions/:tool_name` or `stdio` MCP) for AI agents.

---

## 1. Properties & Unit Types Collection

| MCP Tool Name | REST Endpoint | Type | Description |
| :--- | :--- | :--- | :--- |
| `list_properties` | `GET /api/v1/properties` | Read | List all active properties in the organization (`hope-homestay`, `rock-hyrax-hotel`). |
| `get_property` | `GET /api/v1/properties/:id` | Read | Fetch a property by UUID or slug (`hope-homestay` or `rock-hyrax-hotel`), including policies, facilities, and tax configuration. |
| `list_unit_types` | `GET /api/v1/properties/:id/unit-types` | Read | List sellable unit categories (`Entire Four-Bedroom Homestay` or hotel room types). |
| `update_property_preview` / `confirm` | `POST /api/v1/agent-actions/update_property_preview` | Write (2-step) | Propose and confirm updates to property check-in/out times, contacts, or policies. |
| `update_unit_type_preview` / `confirm` | `POST /api/v1/agent-actions/update_unit_type_preview` | Write (2-step) | Propose and confirm updates to room category base rates, inventory counts, or occupancy. |
| `onboard_property_preview` / `confirm` | `POST /api/v1/agent-actions/onboard_property_preview` | Write (2-step) | Onboard a brand-new property, its unit types, physical units, and rate plans with zero code changes. |
| *(Owner Dashboard Action)* | `POST /api/v1/properties/:id/verify-update` | Owner Write | Direct owner verification & correction of agent-onboarded property details, restaurant, and conference capacity. |
| *(Owner Dashboard Action)* | `POST /api/v1/unit-types/:id/verify-update` | Owner Write | Direct owner verification & correction of room base rates, inventory counts, and descriptions. |
| *(Owner Dashboard Action)* | `DELETE /api/v1/unit-types/:id` | Owner Write | Soft-delete a room type and its associated units/rates (guarded with `409 Conflict` if active bookings exist or if it is the last room type). |
| *(Owner Dashboard Action)* | `DELETE /api/v1/rate-plans/:id` | Owner Write | Soft-delete a rate plan and its calendar overrides (guarded with `409 Conflict` if active bookings exist or if it is the last rate plan). |

---

## 2. Availability, Rates & Inventory (ARI)

| MCP Tool Name | REST Endpoint | Type | Description |
| :--- | :--- | :--- | :--- |
| `get_availability` | `GET /api/v1/properties/:id/availability` | Read | Calculate real-time availability and nightly price breakdowns across all `UnitType`s and `RatePlan`s (supports date overrides, Booking.com `occupancy_pricing` 1–8 pax, Airbnb `channel_fee`, and hotel `BB/HB/FB` meal offsets). |
| `get_rate_plan` | `GET /api/v1/rate-plans/:id` | Read | Retrieve a specific `RatePlan` and its cancellation tiers / pricing metadata. |
| `set_rate_calendar_preview` / `confirm` | `POST /api/v1/agent-actions/set_rate_calendar_preview` | Write (2-step) | Set date-specific nightly rate overrides or minimum-stay restrictions in `rate_calendar`. |
| `create_calendar_block_preview` / `confirm` | `POST /api/v1/agent-actions/create_calendar_block_preview` | Write (2-step) | Block a physical unit or room category for `maintenance`, `owner_stay`, or `manual` hold. |

---

## 3. Bookings & Guests Collection

| MCP Tool Name | REST Endpoint | Type | Description |
| :--- | :--- | :--- | :--- |
| `list_bookings` | `GET /api/v1/properties/:id/bookings` | Read | List bookings with optional `status`, `from_date`, and `to_date` filters. |
| `get_booking` | `GET /api/v1/bookings/:id` | Read | Fetch a single booking with its `price_breakdown` and `cancellation_policy_snapshot`. |
| `get_guest` | `GET /api/v1/guests/:id` | Read | Fetch guest profile, contact details, and stay preferences. |
| `create_booking_preview` / `confirm` | `POST /api/v1/bookings/preview` | Write (2-step) | Preview and confirm a new reservation. Auto-assigns `unit_id` when `inventory_model === 'unique'` (`Hope Homestay`). |
| `modify_booking_preview` / `confirm` | `POST /api/v1/bookings/:id/modify-preview` | Write (2-step) | Preview and confirm date or guest count modifications with recalculated pricing. |
| `cancel_booking_preview` / `confirm` | `POST /api/v1/bookings/:id/cancel-preview` | Write (2-step) | Preview and confirm a booking cancellation with penalty calculation. |
| *(Owner Dashboard Action)* | `POST /api/v1/bookings/:id/status` | Owner Write | Transition reservation status (`confirmed`, `checked_in`, `checked_out`, `cancelled`, `no_show`), record payments, or append folio notes with `AuditLog` tracking. |
| *(Owner Dashboard Action)* | `DELETE /api/v1/guests/:id` | Owner Write | Soft-delete a guest profile (guarded with `409 Conflict` if the guest has active/upcoming reservations; preserves historical folios). |

---

## 4. Open Channel Manager (Two-Way iCal & Gmail IMAP OTA Email Poller)

| MCP Tool Name | REST Endpoint | Type | Description |
| :--- | :--- | :--- | :--- |
| `export_ical_feed` | `GET /api/v1/properties/:id/ical.ics`<br>`GET /api/v1/properties/:id/airbnb.ics`<br>`GET /api/v1/properties/:id/booking_com.ics` | Read | Export RFC 5545 `.ics` calendar feed of confirmed bookings and calendar blocks. Channel-specific `.ics` endpoints automatically exclude blocks imported from that same channel to prevent circular echo loops. |
| `sync_ical_preview` / `confirm` | `POST /api/v1/agent-actions/sync_ical_preview` | Write (2-step) | Idempotently import external `.ics` VEVENT blocks into `calendar_blocks` (`reason = 'channel_sync'`). |
| `list_channel_feeds` | `GET /api/v1/channel-feeds` | Read | List registered external iCal feed subscriptions (`channel_feeds`). |
| `register_channel_feed_preview` / `confirm` | `POST /api/v1/agent-actions/register_channel_feed_preview` | Write (2-step) | Register a new Airbnb, Booking.com, VRBO, or Expedia iCal URL for automated polling. |
| `poll_channel_feeds` | `POST /api/v1/channel-feeds/poll` | Write | Poll registered iCal feeds and upsert `channel_sync` calendar blocks idempotently. |
| *(Two-Way Wizard)* | `POST /api/v1/channel-feeds/connect` | Owner Write | Save/update an inbound OTA `.ics` feed URL and optionally poll it immediately (`poll_now: true`). |
| `ingest_ota_email_preview` / `confirm` | `POST /api/v1/agent-actions/ingest_ota_email_preview` | Write (2-step) | Parse an Airbnb or Booking.com confirmation email and upgrade any matching `channel_sync` block into a full `Booking` + `Guest` record without double-counting inventory. |
| *(Gmail IMAP Poller)* | `POST /api/v1/ota-emails/poll-gmail` | Owner Write | Connect to `hopehomestayke@gmail.com` over `imap.gmail.com:993` (or parse a simulated raw email), decode HTML/quoted-printable OTA notifications, and atomically upgrade matching iCal blocks into confirmed `Booking` + `Guest` records. |

---

## 5. Living Property Memory & Dual-Persona AI Concierge

| MCP Tool Name | REST Endpoint | Type | Description |
| :--- | :--- | :--- | :--- |
| `list_property_knowledge` | `GET /api/v1/properties/:id/knowledge` | Read | Query the Living Property Playbook (`property_knowledge`) by category or keyword search (`query`). |
| `remember_property_knowledge` | `POST /api/v1/properties/:id/knowledge` | Write | Persist a new property rule, pricing quirk, check-in protocol, or edge case into `property_knowledge`. |
| *(Reject & Teach)* | `POST /api/v1/previews/:id/reject` | Owner Write | Reject a pending `ActionPreview`; if `rejection_reason` is provided, automatically records a `feedback_learned` rule in `property_knowledge`. |
| *(Guest Concierge Chat)* | `POST /api/v1/public/properties/:slug/chat` | Guest Write | Public guest-safe chat endpoint (`mode: "guest_concierge"`, locked to `:slug` and `SEED_API_KEYS.guestWidget`). |
| *(Host Copilot Chat)* | `POST /api/v1/host/copilot` | Owner Write | Host operations copilot endpoint (`mode: "host_copilot"`, supports teaching playbook rules and autonomous property onboarding). |
| *(Standalone Widget)* | `GET /widget/:slug` | Read (HTML) | Standalone embeddable Direct Website & WhatsApp Conversational Booking Widget for any property slug. |

---

## 6. Reviews, Messaging, Maps & Data Portability

| MCP Tool Name | REST Endpoint | Type | Description |
| :--- | :--- | :--- | :--- |
| `get_distance_and_nearby` | `GET /api/v1/properties/:id/nearby` | Read | Compute driving distance, travel time, and nearby regional landmarks (Syokimau/JKIA or Nakuru/Lake Nakuru). |
| `get_reviews` | `GET /api/v1/properties/:id/reviews` | Read | List Google Business Profile & OTA guest reviews (`unreplied` / `replied`). |
| *(Reviews Summary & Sync)* | `GET /api/v1/properties/:id/reviews/summary`<br>`POST /api/v1/properties/:id/reviews/sync` | Read / Write | Fetch normalised 5-star multi-channel review summary (Booking.com, Airbnb, Google) or sync reviews from public listing URLs. |
| *(Public Reviews Widget)* | `GET /widget/reviews/:slug` | Read (HTML) | Embeddable multi-channel guest reviews carousel widget for property websites. |
| `reply_to_review_preview` / `confirm` | `POST /api/v1/agent-actions/reply_to_review_preview` | Write (2-step) | Draft and confirm a public response to a guest review. |
| `list_messages` | `GET /api/v1/properties/:id/messages` | Read | List inbound and outbound guest messages across WhatsApp, Booking.com, Airbnb, and email. |
| `send_message_preview` / `confirm` | `POST /api/v1/agent-actions/send_message_preview` | Write (2-step) | Draft and confirm an outbound guest message. |
| *(Data Portability)* | `GET /api/v1/properties/:id/export` | Read | Export complete self-contained JSON bundle of a property (`schema_version: 1.2.0`). |
| *(Data Portability)* | `POST /api/v1/properties/import` | Write | Import a property JSON bundle into any Traveate instance with zero lock-in. |