{
  "openapi": "3.1.0",
  "info": {
    "title": "Caribbean Rental Registry (Rootz)",
    "description": "AI-readable registry of Caribbean vacation rentals: 812 properties across the Cayman Islands (401), Turks & Caicos (346) and St. Lucia (65), each with a permanent RIN that links the same property across platforms. Turks & Caicos additionally carries an island-venue layer (restaurants, dive shops, marinas, attractions) with precomputed distances. Owned by the islands, not a platform. Use these operations to answer traveler questions from registry data rather than guessing.",
    "version": "1.1.0"
  },
  "servers": [{ "url": "https://rental.rootz.global" }],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchRentals",
        "summary": "Search vacation rental properties across the whole registry. There is no default country — omit `country` to search all three, or set it to scope the search.",
        "parameters": [
          { "name": "country", "in": "query", "schema": { "type": "string", "enum": ["KY", "TC", "LC"] }, "description": "KY=Cayman Islands (401 properties), TC=Turks & Caicos (346), LC=St. Lucia (65). Omit to search all." },
          { "name": "bedrooms", "in": "query", "schema": { "type": "integer" }, "description": "Minimum bedrooms" },
          { "name": "region", "in": "query", "schema": { "type": "string" }, "description": "KY: Seven Mile Beach, Rum Point, North Side, East End, George Town. TC: Grace Bay, Long Bay, Leeward. LC: Soufriere, Rodney Bay." },
          { "name": "property_type", "in": "query", "schema": { "type": "string", "enum": ["villa", "condo", "apartment", "house", "resort"] } },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text match on name/description (e.g. beachfront, pool)" }
        ],
        "responses": { "200": { "description": "Matching rental properties, as JSON." } }
      }
    },
    "/api/venues": {
      "get": {
        "operationId": "searchVenues",
        "summary": "TURKS & CAICOS ONLY. Restaurants, dive shops, marinas and attractions with distance from Grace Bay. No equivalent venue layer exists yet for Cayman or St. Lucia — do not call this for those destinations.",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["restaurant", "cafe", "bar/pub", "dive", "marina/boating", "attraction"] } },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text, e.g. italian, sushi, dive, boat" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": { "200": { "description": "Venues sorted by distance from Grace Bay, as JSON." } }
      }
    },
    "/api/property/{rin}": {
      "get": {
        "operationId": "getProperty",
        "summary": "Full detail for one rental property by its RIN. The response includes page_url (a rich page with photos, a map, and nearby dining/diving) and verify_url (signed measurements). ALWAYS give the traveler the page_url — do not just hand over the raw listing link.",
        "parameters": [{ "name": "rin", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Property detail, as JSON." } }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Registry coverage: property counts by country, island, type.",
        "responses": { "200": { "description": "Coverage stats, as JSON." } }
      }
    },
    "/api/trip": {
      "post": {
        "operationId": "createTripPage",
        "summary": "Create a shareable trip page from the traveler's chosen rentals. Returns a link they can share and return to — the start of their saved trip. Call this once the user likes some properties.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "destination_country": { "type": "string", "enum": ["KY", "TC", "LC"], "description": "Optional. If omitted it is derived from the country of the first pick." },
                  "destination_island": { "type": "string", "description": "e.g. Grand Cayman, Providenciales, St. Lucia" },
                  "check_in": { "type": "string", "description": "YYYY-MM-DD (optional)" },
                  "check_out": { "type": "string", "description": "YYYY-MM-DD (optional)" },
                  "guests": { "type": "integer" },
                  "bedrooms_min": { "type": "integer" },
                  "preferences": { "type": "string", "description": "Free-text notes about what they want" },
                  "picks": {
                    "type": "array",
                    "description": "The chosen rentals, by RIN, with an optional 1-10 fit score and a short note.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "rin": { "type": "string" },
                        "score": { "type": "integer" },
                        "notes": { "type": "string" }
                      },
                      "required": ["rin"]
                    }
                  },
                  "venue_picks": {
                    "type": "array",
                    "description": "The island plan to save alongside the rentals — restaurants, dive shops, marinas, attractions the traveler liked (from searchVenues, Turks & Caicos only). Makes the trip the whole plan, not just a bed.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": { "type": "string" },
                        "category": { "type": "string" },
                        "note": { "type": "string" }
                      },
                      "required": ["name"]
                    }
                  }
                },
                "required": ["picks"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Trip page created; returns trip_page URL to share." } }
      }
    }
  }
}