{
  "openapi": "3.1.1",
  "info": {
    "title": "MoodTrip Actions API",
    "version": "1.0.0",
    "description": "Hotel search and booking actions for ChatGPT integration"
  },
  "servers": [
    {
      "url": "https://api.moodtrip.ai",
      "description": "MoodTrip Actions API"
    }
  ],
  "paths": {
    "/api/actions/search": {
      "post": {
        "operationId": "searchHotels",
        "summary": "Search for hotels",
        "description": "Search for hotels using either natural language query or structured parameters. If dates are provided, returns live rates. Otherwise returns hotel metadata.",
        "security": [
          {
            "oauth2": ["mcp:tools"]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing token"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/actions/search-semantic": {
      "post": {
        "operationId": "searchHotelsSemanticQuery",
        "summary": "Semantic hotel search",
        "description": "Advanced semantic search using natural language queries to find hotels matching traveler intent, mood, and preferences. Returns hotels with relevance scores and semantic attributes.",
        "security": [
          {
            "oauth2": ["mcp:tools"]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Semantic search results with relevance scores",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticSearchResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing token"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/actions/fetch": {
      "post": {
        "operationId": "fetchHotel",
        "summary": "Fetch hotel details",
        "description": "Get detailed information about a specific hotel, including pricing if dates are provided",
        "security": [
          {
            "oauth2": ["mcp:tools"]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FetchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Hotel details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HotelDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing token"
          },
          "404": {
            "description": "Hotel not found"
          }
        }
      }
    },
    "/api/actions/ask-hotel": {
      "post": {
        "operationId": "askHotelQuestion",
        "summary": "Ask a question about a specific hotel",
        "description": "Get AI-powered answers to natural language questions about hotel amenities, services, and features (Beta)",
        "security": [
          {
            "oauth2": ["mcp:tools"]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["hotelId", "query"],
                "properties": {
                  "hotelId": {
                    "type": "string",
                    "description": "Unique hotel identifier"
                  },
                  "query": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 500,
                    "description": "Natural language question about the hotel"
                  },
                  "allowWebSearch": {
                    "type": "boolean",
                    "default": false,
                    "description": "Enable web search for additional information"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI-generated answer to the hotel question",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "answer": {
                          "type": "string",
                          "description": "AI-generated answer"
                        },
                        "citations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Source citations (if web search used)"
                        },
                        "latency_ms": {
                          "type": "number",
                          "description": "Response time in milliseconds"
                        },
                        "search_used": {
                          "type": "boolean",
                          "description": "Whether web search was used"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing token"
          },
          "404": {
            "description": "Hotel not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.moodtrip.ai/api/oauth-authorize",
            "tokenUrl": "https://api.moodtrip.ai/api/oauth-token",
            "scopes": {
              "mcp:tools": "Access to search and fetch hotel data"
            }
          }
        }
      }
    },
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Natural language search query (e.g., 'Hotels in Paris for 2 adults Dec 1-5'). Alternative to structured parameters."
          },
          "cityName": {
            "type": "string",
            "description": "City name to search in"
          },
          "countryCode": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code (e.g., 'US', 'FR')"
          },
          "checkin": {
            "type": "string",
            "format": "date",
            "description": "Check-in date (YYYY-MM-DD). If provided with checkout, returns live rates."
          },
          "checkout": {
            "type": "string",
            "format": "date",
            "description": "Check-out date (YYYY-MM-DD). If provided with checkin, returns live rates."
          },
          "occupancies": {
            "type": "array",
            "description": "Guest configuration per room. Defaults to 1 adult if not provided.",
            "items": {
              "type": "object",
              "required": ["adults"],
              "properties": {
                "adults": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 9,
                  "description": "Number of adults in room"
                },
                "children": {
                  "type": "array",
                  "description": "Ages of children in room",
                  "items": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 17
                  }
                }
              }
            }
          },
          "currency": {
            "type": "string",
            "default": "USD",
            "description": "Currency code for pricing (e.g., 'USD', 'EUR', 'GBP')"
          },
          "guestNationality": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code of guest nationality"
          },
          "minStars": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "description": "Minimum hotel star rating filter"
          },
          "minRating": {
            "type": "number",
            "minimum": 0,
            "maximum": 10,
            "description": "Minimum guest review rating (0-10)"
          },
          "maxPrice": {
            "type": "number",
            "description": "Maximum price per night filter"
          }
        },
        "oneOf": [
          {
            "required": ["query"],
            "description": "Natural language search"
          },
          {
            "required": ["cityName", "countryCode"],
            "description": "Structured search"
          }
        ]
      },
      "FetchRequest": {
        "type": "object",
        "required": ["hotelId"],
        "properties": {
          "hotelId": {
            "type": "string",
            "description": "Unique hotel identifier"
          },
          "checkin": {
            "type": "string",
            "format": "date"
          },
          "checkout": {
            "type": "string",
            "format": "date"
          },
          "adults": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string",
            "default": "USD"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hotel"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "query": {
                "type": "object"
              }
            }
          },
          "facets": {
            "type": "object"
          }
        }
      },
      "Hotel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "stars": {
            "type": "integer"
          },
          "rating": {
            "type": "number"
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "thumbnail": {
            "type": "string"
          },
          "cheapestRate": {
            "type": "object",
            "properties": {
              "price": {
                "type": "number"
              },
              "currency": {
                "type": "string"
              }
            }
          },
          "bookingUrl": {
            "type": "string",
            "format": "uri",
            "description": "Direct link to hotel details page with dates pre-filled"
          },
          "galleryUrl": {
            "type": "string",
            "format": "uri",
            "description": "Link to photo gallery and booking flow"
          }
        }
      },
      "SemanticSearchRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string",
            "description": "Natural language search query (e.g., 'romantic getaway in Paris with spa', 'family-friendly beach resort in Bali')"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 10,
            "description": "Maximum number of results to return"
          },
          "includeRates": {
            "type": "boolean",
            "default": true,
            "description": "Include real-time pricing when dates are provided"
          },
          "checkin": {
            "type": "string",
            "format": "date",
            "description": "Check-in date (YYYY-MM-DD)"
          },
          "checkout": {
            "type": "string",
            "format": "date",
            "description": "Check-out date (YYYY-MM-DD)"
          },
          "adults": {
            "type": "integer",
            "minimum": 1,
            "default": 2,
            "description": "Number of adults"
          },
          "children": {
            "type": "array",
            "description": "Ages of children",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 17
            }
          },
          "currency": {
            "type": "string",
            "default": "USD",
            "description": "Currency code for pricing"
          },
          "language": {
            "type": "string",
            "default": "en",
            "description": "Language code for results"
          },
          "guestNationality": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code of guest nationality"
          }
        }
      },
      "SemanticSearchResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SemanticHotel"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "query": {
                "type": "string"
              },
              "semanticAnalysis": {
                "type": "object",
                "properties": {
                  "mood": {
                    "type": "string"
                  },
                  "travelType": {
                    "type": "string"
                  },
                  "amenities": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "SemanticHotel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "stars": {
            "type": "integer"
          },
          "rating": {
            "type": "number"
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "thumbnail": {
            "type": "string"
          },
          "relevanceScore": {
            "type": "number",
            "description": "Semantic relevance score (0-100)"
          },
          "semanticAttributes": {
            "type": "object",
            "description": "Extracted semantic attributes matching the query"
          },
          "cheapestRate": {
            "type": "object",
            "properties": {
              "price": {
                "type": "number"
              },
              "currency": {
                "type": "string"
              }
            }
          },
          "bookingUrl": {
            "type": "string",
            "format": "uri",
            "description": "Direct link to hotel details page with dates pre-filled"
          },
          "galleryUrl": {
            "type": "string",
            "format": "uri",
            "description": "Link to photo gallery and booking flow"
          }
        }
      },
      "HotelDetails": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "stars": {
            "type": "integer"
          },
          "rating": {
            "type": "number"
          },
          "address": {
            "type": "string"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "facilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pricing": {
            "type": "object"
          }
        }
      }
    }
  }
}