{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: Get enriched hotel",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ygo.ai",
      "description": "Production and Sandbox (determined by API key)"
    }
  ],
  "paths": {
    "/v2/project/content/getEnrichedHotel": {
      "post": {
        "summary": "Get enriched hotel",
        "description": "Retrieve one fully enriched hotel with its rooms, images, points of interest, factual attributes, check-in and check-out times and per-locale generated texts.\n\nThe response is returned synchronously. Resolve the hotel with exactly one selector; each returns the same hotel.\n\n- `HotelID` is the hotel UUID, `GlobalHotelID` the cross-tenant identifier, `ExternalHotelID` a map of your own identifiers.\n- `ExternalHotelID` sub-keys are `productid`, `giata` and `peakworkgoalid`; several are AND-combined, so a conflict returns 404.\n- No selector, more than one, an unsupported sub-key, a non-numeric or non-positive `giata` or `peakworkgoalid`, or a `giata` above 2147483647 returns 400.\n- The hotel must be in your project's content set; an unknown or out-of-scope hotel returns 404.\n- 429 means the rate limit was hit; wait `Retry-After` seconds.",
        "operationId": "getEnrichedHotel",
        "tags": [
          "Content Enrichment API/Enrichment"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Project-ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetEnrichedHotelRequest"
              },
              "examples": {
                "byHotelID": {
                  "summary": "Resolve by hotel UUID",
                  "value": {
                    "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc"
                  }
                },
                "byGlobalHotelID": {
                  "summary": "Resolve by global hotel ID",
                  "value": {
                    "GlobalHotelID": "ES-MALLR-K7MP2"
                  }
                },
                "byProductID": {
                  "summary": "Resolve by the project's own product ID",
                  "value": {
                    "ExternalHotelID": {
                      "productid": "HTL-MAJ-4711"
                    }
                  }
                },
                "byProductIDAndGiata": {
                  "summary": "Resolve by product ID and GIATA together (both must match the same hotel)",
                  "value": {
                    "ExternalHotelID": {
                      "productid": "HTL-MAJ-4711",
                      "giata": "668370"
                    }
                  }
                },
                "byPeakworkGoalID": {
                  "summary": "Resolve by the hotel's Peakwork Goal ID",
                  "value": {
                    "ExternalHotelID": {
                      "peakworkgoalid": "864521"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enriched hotel retrieved successfully.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetEnrichedHotelResponse"
                },
                "examples": {
                  "byHotelID": {
                    "$ref": "#/components/examples/EnrichedHotelResult"
                  },
                  "byGlobalHotelID": {
                    "$ref": "#/components/examples/EnrichedHotelResult"
                  },
                  "byProductID": {
                    "$ref": "#/components/examples/EnrichedHotelResult"
                  },
                  "byProductIDAndGiata": {
                    "$ref": "#/components/examples/EnrichedHotelResult"
                  },
                  "byPeakworkGoalID": {
                    "$ref": "#/components/examples/EnrichedHotelResult"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Address": {
        "type": "object",
        "description": "Postal address and contact details extracted from enrichment details. Present only when address data is available.",
        "properties": {
          "Street": {
            "type": "string",
            "description": "Street name and number.",
            "example": "Carrer de la Mar 12"
          },
          "City": {
            "type": "string",
            "description": "City or town.",
            "example": "Palma"
          },
          "CityNames": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Localized city display names keyed by BCP 47 language tag, present only when they have been generated. Fall back to `City`.",
            "example": {
              "en-US": "Rome",
              "de-DE": "Rom",
              "it-IT": "Roma"
            }
          },
          "State": {
            "type": "string",
            "description": "State, province, or region.",
            "example": "Illes Balears"
          },
          "PostalCode": {
            "type": "string",
            "description": "Postal or ZIP code.",
            "example": "07015"
          },
          "Phone": {
            "type": "string",
            "description": "The hotel's phone number, as its sources state it. Omitted when none is known.",
            "example": "+34 971 000 000"
          },
          "Email": {
            "type": "string",
            "description": "The hotel's email address, as its sources state it. Omitted when none is known.",
            "example": "info@bahia-azul.example"
          }
        }
      },
      "Bedding": {
        "type": "object",
        "required": [
          "Type",
          "Quantity"
        ],
        "description": "A single bed entry within a bedding configuration.",
        "properties": {
          "Type": {
            "type": "string",
            "description": "Bed type. Known codes: SINGLE, TWIN, DOUBLE, QUEEN, KING, SOFA_BED, BUNK_BED, EXTRA_BED, CRIB, CHILD_BED, DAY_BED, MURPHY_BED, CHAIR_BED; older records can hold other values.",
            "example": "DOUBLE"
          },
          "Quantity": {
            "type": "integer",
            "description": "Number of beds of this type.",
            "example": 1
          },
          "Name": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Bed type name per room Name locale (BCP 47) in en, de, fr, it, nl, es, tr or he, shown after Quantity: singular for 1, else the counted form, plural if inflected. Absent for an unknown Type or no such locale; use Type.",
            "example": {
              "en-US": "double bed",
              "de-DE": "Doppelbett"
            }
          }
        }
      },
      "CheckIn": {
        "type": "object",
        "description": "Earliest check-in time. The whole object is omitted when no valid time is available.",
        "properties": {
          "From": {
            "type": "string",
            "description": "Earliest check-in time as a 24-hour 'HH:MM' clock string.",
            "example": "15:00"
          }
        }
      },
      "CheckOut": {
        "type": "object",
        "description": "Latest check-out time. The whole object is omitted when no valid time is available.",
        "properties": {
          "Until": {
            "type": "string",
            "description": "Latest check-out time as a 24-hour 'HH:MM' clock string.",
            "example": "11:00"
          }
        }
      },
      "Compliance": {
        "type": "object",
        "properties": {
          "AIGenerated": {
            "type": "boolean",
            "description": "EU AI Act Article 50(2) machine-readable marker: true when the text content of the enclosing object is AI-generated. Always stated explicitly when the envelope is present.",
            "example": true
          }
        }
      },
      "DetectionConfidence": {
        "type": "number",
        "format": "float",
        "nullable": true,
        "minimum": 0,
        "maximum": 1,
        "description": "Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.",
        "example": 0.94
      },
      "EnrichedHotel": {
        "type": "object",
        "required": [
          "ID",
          "Name",
          "Names",
          "Stars",
          "StarsMap",
          "AccommodationType",
          "Location",
          "FactualAttributes",
          "POIs",
          "GeneratedTexts",
          "Images",
          "Rooms",
          "Status",
          "CreatedAt",
          "UpdatedAt"
        ],
        "description": "A fully enriched hotel with its identity, location, factual attributes, structured check-in / check-out times, per-locale generated texts, guest rating, images, and rooms.",
        "properties": {
          "ID": {
            "type": "string",
            "format": "uuid",
            "description": "Unique hotel UUID.",
            "example": "0192fb17-5dc6-7abc-8def-123456789abc"
          },
          "Name": {
            "type": "string",
            "description": "Normalized English (en-US) hotel display name.",
            "example": "Bahia Azul Beach Resort"
          },
          "Names": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Per-locale display names keyed by BCP 47 language tag, always including en-US. Other locales appear only when a localized name has been generated.",
            "example": {
              "en-US": "Bahia Azul Beach Resort",
              "de-DE": "Bahia Azul Strandresort"
            }
          },
          "ExternalHotelIDs": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "External identifiers this hotel is known by, omitted when it has none. Current keys are `ProductID`, `Giata` and `PeakworkGoalID`, each only when it applies; the map is open, so read the keys you need.",
            "example": {
              "ProductID": "HTL-MAJ-4711",
              "Giata": "668370",
              "PeakworkGoalID": "864521"
            }
          },
          "GlobalHotelID": {
            "type": "string",
            "description": "Cross-tenant global hotel identifier. Omitted when the hotel has no global ID assigned.",
            "example": "ES-MALLR-K7MP2"
          },
          "Stars": {
            "type": "number",
            "format": "float",
            "description": "The hotel's default star grade (StarsMap.default.Stars); 0 when unrated.",
            "example": 4
          },
          "StarsMap": {
            "$ref": "#/components/schemas/StarsMap"
          },
          "AccommodationType": {
            "type": "string",
            "description": "Accommodation kind, for example hotel, apartment, aparthotel, resort, villa, hostel, guesthouse, bed_and_breakfast, cruise_ship or holiday_village. The set of values may be extended, so read it as an open string.",
            "example": "hotel"
          },
          "Chain": {
            "type": "string",
            "description": "Hotel company the property belongs to. Omitted when the hotel has no chain recorded.",
            "example": "Accor"
          },
          "Brand": {
            "type": "string",
            "description": "Product line within the chain the property is marketed under. Omitted when the hotel has no brand recorded.",
            "example": "Novotel"
          },
          "Location": {
            "$ref": "#/components/schemas/Location"
          },
          "FactualAttributes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FactualAttribute"
            },
            "description": "Hotel-level factual attributes (amenities, facilities, grouped on-site facility families, and group header rows)."
          },
          "POIs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/POI"
            },
            "description": "Nearby points of interest with localized names and, where there is one to show, distances."
          },
          "CheckIn": {
            "$ref": "#/components/schemas/CheckIn"
          },
          "CheckOut": {
            "$ref": "#/components/schemas/CheckOut"
          },
          "GeneratedTexts": {
            "$ref": "#/components/schemas/GeneratedTexts"
          },
          "GuestRating": {
            "$ref": "#/components/schemas/GuestRating"
          },
          "RenderLayouts": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Optional rendering hints, not enrichment data: template key to layout hint such as `prose`, `highlights`, `roomcards` or `summary`. Only keys whose template carries a hint are included.",
            "example": {
              "Summary": "prose",
              "HouseRules": "highlights"
            }
          },
          "Images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Image"
            },
            "description": "Hotel-level images, deduplicated and sorted by category priority. An image pinned in your project's content set (see PinnedImageID) is served first, ahead of that order."
          },
          "PinnedImageID": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the pinned image promoted to the front of `Images`, always the first entry's ID. Omitted when no pin is in effect.",
            "example": "0192fb20-1aa2-7def-9abc-1122334455aa"
          },
          "Rooms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EnrichedRoom"
            },
            "description": "Enriched room types belonging to this hotel."
          },
          "Tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProjectTagSummary"
            },
            "description": "Internal tags of your project's content set applied to the hotel (your project's, or instead those of the project YGO set it to share content from). Present only when the hotel carries one or more; omitted otherwise."
          },
          "Status": {
            "type": "string",
            "enum": [
              "draft",
              "active",
              "inactive",
              "closed_temporarily",
              "closed_permanently",
              "removed"
            ],
            "description": "The hotel's status in your project, first match wins: `closed_permanently`, `closed_temporarily`, `removed` (out of the catalog), `inactive`, `active` (active in the catalog, with texts), else `draft`.",
            "example": "active"
          },
          "TextStatus": {
            "type": "string",
            "enum": [
              "none",
              "generating",
              "generated",
              "failed"
            ],
            "description": "Your project's text state of the hotel, first match wins: `generating`, `failed` (latest generation failed; older texts stay), `generated` (texts held), else `none`.",
            "example": "generated"
          },
          "CreatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the hotel record was created (RFC3339).",
            "example": "2026-03-01T08:00:00Z"
          },
          "UpdatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the hotel record was last updated (RFC3339).",
            "example": "2026-04-12T09:15:00Z"
          }
        }
      },
      "EnrichedRoom": {
        "type": "object",
        "required": [
          "ID",
          "Name",
          "FactualAttributes",
          "RenderLayouts",
          "Images",
          "Status",
          "CreatedAt",
          "UpdatedAt"
        ],
        "description": "An enriched room type belonging to a hotel.",
        "properties": {
          "ID": {
            "type": "string",
            "format": "uuid",
            "description": "Unique room UUID.",
            "example": "0192fb30-2bb3-7abc-8def-99887766aabb"
          },
          "Name": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Localized room names keyed by BCP 47 language tag. Always contains en-US when a base room name exists.",
            "example": {
              "en-US": "Double Room Sea View",
              "de-DE": "Doppelzimmer mit Meerblick"
            }
          },
          "SizeSqm": {
            "type": "integer",
            "description": "Room size in square meters. 0 when unknown.",
            "example": 26
          },
          "Beddings": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Bedding"
              }
            },
            "description": "Bedding configurations. The outer array lists alternative configurations; each inner array lists the beds in one configuration."
          },
          "FactualAttributes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FactualAttribute"
            },
            "description": "Room-level factual attributes."
          },
          "GeneratedTexts": {
            "$ref": "#/components/schemas/GeneratedTexts"
          },
          "RenderLayouts": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Optional rendering hints keyed by room template namespace (empty string for bare template keys). One layout governs the whole room card.",
            "example": {
              "": "roomcards"
            }
          },
          "ExternalRoomIDs": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Your own identifiers for this room, omitted when it has none. Current key is `ProductRoomIDs`, sorted and included only for confident matches; several ids can map to one room.",
            "example": {
              "ProductRoomIDs": [
                "11824",
                "11902"
              ]
            }
          },
          "Images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Image"
            },
            "description": "Room-level images, deduplicated and sorted by category priority."
          },
          "Status": {
            "type": "string",
            "description": "Room lifecycle status (e.g. active).",
            "example": "active"
          },
          "CreatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the room record was created (RFC3339).",
            "example": "2026-03-01T08:00:00Z"
          },
          "UpdatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the room record was last updated (RFC3339).",
            "example": "2026-04-10T12:30:00Z"
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": [
          "Code",
          "Message"
        ],
        "description": "Error detail containing a machine-readable code and human-readable message.",
        "properties": {
          "Code": {
            "type": "string",
            "description": "Machine-readable error code for programmatic handling.",
            "example": "VALIDATION_ERROR"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable error message.",
            "example": "Request validation failed"
          },
          "Fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldError"
            },
            "description": "Field-level validation errors. Only present for VALIDATION_ERROR responses."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "Error"
        ],
        "description": "Standard v2 error response wrapper.",
        "properties": {
          "Error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        }
      },
      "FactualAttribute": {
        "type": "object",
        "required": [
          "Key",
          "Name",
          "ValueType"
        ],
        "description": "A factual attribute. A single fact carries a scalar `Value`; a grouped facility family carries `Instances` and an empty `Value`; a group header carries `ValueType` `group`.",
        "properties": {
          "Key": {
            "type": "string",
            "description": "Canonical attribute key.",
            "example": "wifi"
          },
          "Type": {
            "type": "string",
            "description": "Ontology kind resolved from the attribute tree at serve time. For this surface the value is 'factual'.",
            "example": "factual"
          },
          "Name": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Localized attribute display names keyed by BCP 47 language tag.",
            "example": {
              "en-US": "Free WiFi",
              "de-DE": "Kostenloses WLAN"
            }
          },
          "Value": {
            "type": "string",
            "description": "Scalar value for a single fact, empty for grouped families and headers. It carries the polarity, so always render the attribute with its `Value`, never from `Name` alone.",
            "example": "true"
          },
          "ValueType": {
            "type": "string",
            "description": "How Value should be interpreted: 'boolean', 'text', or 'group' for a group header row.",
            "example": "boolean"
          },
          "ParentKey": {
            "type": "string",
            "description": "Key of the parent category this attribute belongs to (used by clients as a section grouping).",
            "example": "facilities_and_services"
          },
          "Details": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Additional free-text properties in the source language, such as description or Category; their translations are under DetailsLocalized. Omitted when empty."
          },
          "IsFree": {
            "type": "boolean",
            "nullable": true,
            "description": "Whether the amenity is free of charge. true (free), false (paid), or null when unknown / not applicable.",
            "example": true
          },
          "IsOnSite": {
            "type": "boolean",
            "description": "Whether the facility or activity is on the hotel's premises (true) or only in the surrounding area (false), for example a golf course 12 km away. Hotel facts only; omitted when not determined, never null.",
            "example": false
          },
          "GTCodes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "DRV GlobalTypes codes for this attribute, general to specific: concept code, optional SubType refinement, then a free-of-charge qualifier. Omitted when the attribute has no mapping.",
            "example": [
              "GT03-POOL",
              "ST03-INSW"
            ]
          },
          "ValueLocalized": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Per-locale translations of the free-text Value, keyed by BCP 47 language tag; a boolean Value normally carries none. Present only when translations exist, otherwise fall back to Value."
          },
          "DetailsLocalized": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "description": "Per-locale translations of the free-text Details, keyed by property key, then by BCP 47 language tag. Present only when translations exist, otherwise fall back to Details."
          },
          "Instances": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FactualInstance"
            },
            "description": "Named outlets for a grouped on-site facility family, such as each restaurant or bar. Present only for grouped families, omitted for single-fact attributes."
          }
        }
      },
      "FactualInstance": {
        "type": "object",
        "required": [
          "Name"
        ],
        "description": "One named outlet within a grouped on-site facility family.",
        "properties": {
          "Name": {
            "type": "string",
            "description": "Display name of the outlet.",
            "example": "La Marea"
          },
          "Details": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Per-outlet free-text properties, such as description or hours. Omitted when empty."
          },
          "DetailsLocalized": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "description": "Per-property, per-locale translations of this outlet's free-text details, keyed propertyKey then BCP 47 language tag. Fall back to `Details`; omitted when empty."
          }
        }
      },
      "FeatureDetection": {
        "type": "object",
        "required": [
          "Label",
          "Confidence"
        ],
        "description": "One feature of the image with the confidence measured for it.",
        "properties": {
          "Label": {
            "type": "string",
            "description": "The feature label, from the same vocabulary as Features.",
            "example": "sea_view"
          },
          "Confidence": {
            "$ref": "#/components/schemas/DetectionConfidence"
          }
        }
      },
      "FieldError": {
        "type": "object",
        "required": [
          "Field",
          "Message"
        ],
        "description": "A single field-level validation error.",
        "properties": {
          "Field": {
            "type": "string",
            "description": "Name of the field that failed validation.",
            "example": "HotelID"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable validation error message for this field.",
            "example": "Provide exactly one of HotelID, GlobalHotelID, or ExternalHotelID"
          },
          "Code": {
            "type": "string",
            "enum": [
              "REQUIRED",
              "TOO_LONG",
              "TOO_SHORT",
              "OUT_OF_RANGE",
              "TOO_MANY",
              "INVALID_FORMAT",
              "NOT_ALLOWED",
              "CONFLICT",
              "INVALID_ENCODING",
              "INSECURE_SCHEME",
              "UNSAFE_CONTENT",
              "REQUIRED_WHEN_ENABLED"
            ],
            "description": "Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.",
            "example": "REQUIRED"
          },
          "Params": {
            "type": "object",
            "additionalProperties": true,
            "description": "Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.",
            "example": {
              "Max": 100
            }
          }
        }
      },
      "GeneratedTextDetail": {
        "type": "object",
        "required": [
          "Text"
        ],
        "description": "One generated text for a (locale, template key) pair. Every text served here is AI-generated and therefore carries a `Compliance` marker envelope.",
        "properties": {
          "Text": {
            "type": "string",
            "description": "The generated text, sanitized for display.",
            "example": "Set on a quiet stretch of the Bay of Palma, Bahia Azul Beach Resort pairs direct beach access with bright, contemporary rooms and a sea-view rooftop pool."
          },
          "GeneratedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Per-text generation timestamp (RFC3339). Omitted for legacy / unstamped texts.",
            "example": "2026-04-12T09:15:00Z"
          },
          "TextType": {
            "type": "string",
            "description": "Set to 'rules' for rule-based texts (policies, house rules). Omitted for marketing texts.",
            "example": "rules"
          },
          "Compliance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Compliance"
              }
            ],
            "description": "Regulatory marker envelope, present whenever the text is non-empty; `AIGenerated` is always `true`. Omitted on an empty text."
          }
        }
      },
      "GeneratedTexts": {
        "type": "object",
        "description": "Generated texts keyed by locale (BCP 47 language tag) then by template key; each value is a GeneratedTextDetail.",
        "additionalProperties": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/GeneratedTextDetail"
          }
        }
      },
      "GetEnrichedHotelRequest": {
        "type": "object",
        "description": "Request body for fetching one enriched hotel. Provide exactly one selector: `HotelID`, `GlobalHotelID` or `ExternalHotelID`.",
        "properties": {
          "HotelID": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the enriched hotel to retrieve, one of three mutually exclusive selectors. The hotel must be in your project's content set: your project's, or instead that of the project YGO set it to share content from.",
            "example": "0192fb17-5dc6-7abc-8def-123456789abc"
          },
          "GlobalHotelID": {
            "type": "string",
            "description": "Cross-tenant global hotel identifier, one of three mutually exclusive selectors. The resolved hotel must be in your project's content set (see `HotelID`).",
            "example": "ES-MALLR-K7MP2"
          },
          "ExternalHotelID": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Resolve the hotel by your own identifiers, AND-combined when several are given. Sub-key names are case-insensitive; `productid` compares exactly, `giata` and `peakworkgoalid` are positive integers compared by number, `giata` up to 2147483647.",
            "example": {
              "productid": "HTL-MAJ-4711"
            }
          }
        }
      },
      "GetEnrichedHotelResponse": {
        "type": "object",
        "required": [
          "Data"
        ],
        "description": "Single-object response envelope wrapping the enriched hotel.",
        "properties": {
          "Data": {
            "$ref": "#/components/schemas/EnrichedHotel"
          }
        }
      },
      "GuestRating": {
        "type": "object",
        "required": [
          "ReviewScore"
        ],
        "description": "Guest rating of the hotel: the guest review scores we hold, calibrated per platform and aggregated on a 0 to 100 scale, with category scores and summaries. Omitted when the hotel has no rating.",
        "properties": {
          "ReviewScore": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Overall guest score from 0 to 100: the aggregate of the guest review scores we hold, each calibrated per review platform.",
            "example": 93
          },
          "SubScores": {
            "$ref": "#/components/schemas/GuestRatingSubScores"
          },
          "Texts": {
            "$ref": "#/components/schemas/GuestRatingTexts"
          }
        }
      },
      "GuestRatingSubScores": {
        "type": "object",
        "description": "Category scores from 0 to 100 showing how a category compares with the hotel overall. A category without data is absent, never 0; omitted when no category has data.",
        "properties": {
          "Cleanliness": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Score for cleanliness, 0 to 100.",
            "example": 96
          },
          "Service": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Score for staff and service, 0 to 100.",
            "example": 96
          },
          "Location": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Score for the location, 0 to 100.",
            "example": 91
          },
          "Rooms": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Score for the rooms, 0 to 100.",
            "example": 95
          },
          "Food": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Score for food and drink, 0 to 100.",
            "example": 91
          },
          "Value": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Score for value for money, 0 to 100.",
            "example": 90
          },
          "Facilities": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Score for the facilities, 0 to 100.",
            "example": 93
          }
        }
      },
      "GuestRatingText": {
        "type": "object",
        "required": [
          "Summary"
        ],
        "description": "What guests say about the hotel in one locale: a short summary with the points most often praised and criticized.",
        "properties": {
          "Summary": {
            "type": "string",
            "description": "Short paragraph summarizing guest opinion of the hotel.",
            "example": "Guests consistently describe their stay as a peaceful, relaxing retreat highlighted by exceptionally friendly and attentive staff. Rooms and grounds are praised for being spotless and comfortable, while the delicious breakfast and calm adults-only setting make it an ideal getaway."
          },
          "Pros": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "type": "string"
            },
            "description": "Up to 5 points guests praise. Omitted when there are none.",
            "example": [
              "Warm, attentive, and professional staff",
              "Spotless rooms and well-kept grounds",
              "Peaceful, child-free atmosphere",
              "Superb and varied breakfast spread",
              "Modern, spacious guest rooms"
            ]
          },
          "Cons": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "type": "string"
            },
            "description": "Up to 3 points guests criticize. Omitted when there are none.",
            "example": [
              "Extra charges for some premium drinks and minibar",
              "Lunch and dinner buffets can feel repetitive to some"
            ]
          },
          "GeneratedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Generation timestamp of this text (RFC3339). Omitted for an unstamped text.",
            "example": "2026-11-05T18:10:57Z"
          },
          "Compliance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Compliance"
              }
            ],
            "description": "Regulatory marker envelope, present on every served text; `AIGenerated` is always `true`."
          }
        }
      },
      "GuestRatingTexts": {
        "type": "object",
        "description": "AI-generated summaries of guest opinion keyed by locale (BCP 47 language tag); they quote no review. Omitted when no text has been generated.",
        "additionalProperties": {
          "$ref": "#/components/schemas/GuestRatingText"
        }
      },
      "Image": {
        "type": "object",
        "required": [
          "ID",
          "URL"
        ],
        "description": "An enriched image with vision-derived metadata.",
        "properties": {
          "ID": {
            "type": "string",
            "format": "uuid",
            "description": "Unique image UUID.",
            "example": "0192fb20-1aa2-7def-9abc-1122334455aa"
          },
          "URL": {
            "type": "string",
            "format": "uri",
            "description": "Image URL.",
            "example": "https://cdn.ygo.ai/hotels/bahia-azul/exterior-pool.jpg"
          },
          "Source": {
            "type": "string",
            "description": "Detected provenance of the pixels: `photo`, `render`, `illustration` or `ai_generated`. Omitted when the image carries no provenance assessment.",
            "example": "photo"
          },
          "Category": {
            "type": "string",
            "description": "Vision-derived image category (e.g. exterior, room, pool, restaurant).",
            "example": "exterior"
          },
          "Features": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Vision-derived feature tags depicted in the image.",
            "example": [
              "pool",
              "sea_view"
            ]
          },
          "Mood": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Vision-derived mood descriptors.",
            "example": [
              "relaxing"
            ]
          },
          "Tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional vision-derived tags.",
            "example": [
              "rooftop",
              "sunset"
            ]
          },
          "Flags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Quality / content flags raised by vision analysis. Omitted when empty."
          },
          "AppealScore": {
            "type": "integer",
            "description": "Appeal score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.",
            "example": 88
          },
          "QualityScore": {
            "type": "integer",
            "description": "Technical quality score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.",
            "example": 91
          },
          "AppealScoreVersion": {
            "type": "string",
            "description": "Version stamp of the scorer that produced AppealScore, for example `app-v4`; it may name an earlier version. Absent when AppealScore is -1 or a legacy score from before stamps existed.",
            "example": "app-v4"
          },
          "QualityScoreVersion": {
            "type": "string",
            "description": "Version stamp of the scorer that produced QualityScore, for example `qs-v4`; it may name an earlier version. Absent when QualityScore is -1, a legacy score, or a first-seen image's provisional score.",
            "example": "qs-v4"
          },
          "Width": {
            "type": "integer",
            "description": "Image width in pixels.",
            "example": 1600
          },
          "Height": {
            "type": "integer",
            "description": "Image height in pixels.",
            "example": 1067
          },
          "Format": {
            "type": "string",
            "description": "Image format (e.g. jpeg, png, webp).",
            "example": "jpeg"
          },
          "FileSize": {
            "type": "integer",
            "description": "File size in bytes.",
            "example": 412000
          },
          "DominantColor": {
            "type": "string",
            "description": "Dominant color as a hex string.",
            "example": "#2E6F95"
          },
          "BlurHash": {
            "type": "string",
            "description": "BlurHash placeholder string for progressive loading.",
            "example": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH"
          },
          "FileMetadata": {
            "type": "object",
            "description": "What the image file itself states in its embedded IPTC/EXIF/XMP metadata: capture date and copyright notice. Omitted when the file states neither; inside it, a value the file did not state has no key.",
            "properties": {
              "CaptureDate": {
                "type": "string",
                "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$",
                "description": "Date the photograph was taken, at the precision the file stated: `2012-06-14`, `2012-06` or `2012`. It carries no time of day and no timezone.",
                "example": "2012-06-14"
              },
              "Copyright": {
                "type": "string",
                "description": "The copyright notice the file carries, as the file wrote it. It names who to ask; it is not a machine-readable licence.",
                "example": "© 2012 Hotel Sol S.A."
              }
            },
            "example": {
              "CaptureDate": "2012-06-14",
              "Copyright": "© 2012 Hotel Sol S.A."
            }
          },
          "Descriptions": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Neutral alt text describing what the image shows, not marketing copy, keyed by BCP 47 language tag. More locales may be added after an image is first analyzed.",
            "example": {
              "en-US": "Rooftop infinity pool overlooking the Bay of Palma at sunset."
            }
          },
          "Compliance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Compliance"
              }
            ],
            "description": "EU AI Act Article 50(2) marker for this image. Always present with `AIGenerated` true: the category, features, mood, tags, scores and descriptions are model output, `FileMetadata` is not."
          },
          "Presence": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PresenceDetection"
            },
            "description": "People and animals seen in the image, from the closed vocabulary person, adult, child, animal. Omitted when the image carries no presence measurement."
          },
          "Safety": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/DetectionConfidence"
            },
            "description": "Safety confidences keyed by dimension, `Inappropriate` and `OffTopic`, each between 0 and 1 or null. Omitted when the image carries no safety measurement."
          },
          "TextDetections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TextDetection"
            },
            "description": "Texts read off the image, each with its kind. Omitted when the image carries no text measurement."
          },
          "FeatureDetections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeatureDetection"
            },
            "description": "The image's features with the confidence measured for each, running parallel to `Features`. Omitted when the image carries no feature measurement."
          },
          "Nudity": {
            "type": "object",
            "description": "Nudity assessment: exposure score, reason and explicit flag, independent of `Safety.Inappropriate`. Omitted when the assessment did not run or the image's `Presence` shows no person.",
            "required": [
              "Score",
              "Reason",
              "Explicit"
            ],
            "properties": {
              "Score": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100,
                "description": "Exposure score from 0 to 100. Anchors: 20 beach or casual wear, 40 standard swimwear, 60 revealing swimwear or lingerie, 80 partial nudity, 100 explicit.",
                "example": 60
              },
              "Reason": {
                "type": "string",
                "description": "One model-written sentence naming what drives the score, at most 240 characters. Not sanitized for markup, so escape it before rendering.",
                "example": "Adult in revealing swimwear by the pool."
              },
              "Explicit": {
                "type": "boolean",
                "description": "True from a score of 90 up. Whether a child is in the picture is answered by `Presence`, not here.",
                "example": false
              }
            }
          }
        }
      },
      "Location": {
        "type": "object",
        "required": [
          "Latitude",
          "Longitude",
          "CountryCode"
        ],
        "description": "Geographic location of the hotel.",
        "properties": {
          "Latitude": {
            "type": "number",
            "format": "double",
            "description": "Latitude in decimal degrees.",
            "example": 39.5696
          },
          "Longitude": {
            "type": "number",
            "format": "double",
            "description": "Longitude in decimal degrees.",
            "example": 2.6502
          },
          "CountryCode": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code.",
            "example": "ES"
          },
          "Address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "POI": {
        "type": "object",
        "required": [
          "ID",
          "Name",
          "Type"
        ],
        "description": "A nearby point of interest: one place, or an area (IsArea) such as part of a town or a beach. POI data partly © OpenStreetMap contributors, available under the ODbL.",
        "properties": {
          "ID": {
            "type": "string",
            "format": "uuid",
            "description": "Unique POI UUID. Stable identifier used as the entity id when submitting feedback about this POI.",
            "example": "0192fb20-1aa2-7def-9abc-1122334455aa"
          },
          "Name": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Localized POI names keyed by BCP 47 language tag, always with en-US. For an area (IsArea true) it is the area's official local name, translated per locale.",
            "example": {
              "en-US": "Palma Cathedral",
              "de-DE": "Kathedrale von Palma"
            }
          },
          "Type": {
            "type": "string",
            "description": "POI category (e.g. landmark, beach, airport, restaurant).",
            "example": "landmark"
          },
          "Distance": {
            "type": "number",
            "format": "double",
            "description": "Distance in Unit: meters under 1 km, else km to one decimal; for an area, to its nearest edge, its centre without an outline, or the distance its source stated. Omitted with Unit when unknown, at the hotel or InArea.",
            "example": 3.2
          },
          "Unit": {
            "type": "string",
            "enum": [
              "m",
              "km"
            ],
            "description": "Unit for Distance: m for meters, km for kilometers. Present exactly when Distance is present.",
            "example": "km"
          },
          "IsArea": {
            "type": "boolean",
            "description": "True for a POI that is an area rather than one place: an area of a town (a historic centre, an old town, a district, a promenade), or a beach located by its OpenStreetMap outline. Omitted when false.",
            "example": true
          },
          "InArea": {
            "type": "boolean",
            "description": "True when the hotel lies inside the area's outline, for a beach on its sand; Distance and Unit are then omitted. Implies IsArea; not set when a stated distance is kept, omitted when false.",
            "example": true
          },
          "Latitude": {
            "type": "number",
            "format": "double",
            "description": "Latitude of the POI in decimal degrees (WGS-84). For an area (IsArea) it is the area's representative point: the centroid of its outline, which can lie off a line or an irregular area, or its single point. Sent together with Longitude; both are omitted when the POI has no known position, an area that could not be located included.",
            "example": 39.5675
          },
          "Longitude": {
            "type": "number",
            "format": "double",
            "description": "Longitude of the POI in decimal degrees (WGS-84). Present exactly when Latitude is present.",
            "example": 2.6484
          },
          "Details": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Additional POI properties. Omitted when empty."
          }
        }
      },
      "PresenceDetection": {
        "type": "object",
        "required": [
          "Label",
          "Confidence"
        ],
        "description": "One person or animal seen in the image.",
        "properties": {
          "Label": {
            "type": "string",
            "description": "What was seen: `person`, `adult`, `child` or `animal`.",
            "example": "adult"
          },
          "Confidence": {
            "$ref": "#/components/schemas/DetectionConfidence"
          }
        }
      },
      "ProjectTagSummary": {
        "type": "object",
        "required": [
          "ID",
          "Name"
        ],
        "description": "A reference to one internal tag of your project's content set applied to the hotel: the tag id, display name and optional description.",
        "properties": {
          "ID": {
            "type": "string",
            "format": "uuid",
            "description": "Unique project tag UUID.",
            "example": "0192fc01-1111-7abc-8def-aaaaaaaaaaaa"
          },
          "Name": {
            "type": "string",
            "description": "Tag display name.",
            "example": "Summer Campaign"
          },
          "Description": {
            "type": "string",
            "description": "Tag description. Omitted when the tag has none.",
            "example": "Hotels in the 2026 summer campaign"
          }
        }
      },
      "StarsMap": {
        "type": "object",
        "description": "Grades by source, in default's order: project (content set's, if set), national, association, canonical (own site); new keys may appear. default is always present: the first one set, else the collected rating or 0.",
        "additionalProperties": {
          "$ref": "#/components/schemas/StarsMapEntry"
        }
      },
      "StarsMapEntry": {
        "type": "object",
        "required": [
          "Stars",
          "Superior",
          "Garni"
        ],
        "description": "One star grade from one source, or the computed default. Stars, Superior and Garni are always present; further members may be added, so ignore members you do not read.",
        "properties": {
          "Stars": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 10,
            "description": "The grade (for example 4 or 4.5), with at most one decimal except a default taken from the collected rating. Only default may be 0 (unrated), and default.Stars always equals the top-level Stars.",
            "example": 4
          },
          "Superior": {
            "type": "boolean",
            "description": "True when the grade is a Superior class on top of Stars, such as the \"S\" suffix of a national classification; a \"4 Superior\" is Stars 4 with Superior true, never 4.5. False when the source sets no Superior.",
            "example": true
          },
          "Garni": {
            "type": "boolean",
            "description": "True when the source classifies the hotel as a garni, a hotel that serves breakfast but no other meals, such as the \"Garni\" suffix of a national classification. False when the source sets no Garni.",
            "example": false
          }
        }
      },
      "TextDetection": {
        "type": "object",
        "required": [
          "Content",
          "Label",
          "Confidence"
        ],
        "description": "One text read off the image.",
        "properties": {
          "Content": {
            "type": "string",
            "description": "The text as it appears on the image. A password or access code printed after a password label is masked.",
            "example": "POOL BAR"
          },
          "Label": {
            "type": "string",
            "description": "Kind of text: `overlay`, `price`, `promotional`, `watermark`, `signage` or `document`.",
            "example": "signage"
          },
          "Confidence": {
            "$ref": "#/components/schemas/DetectionConfidence"
          }
        }
      }
    },
    "parameters": {
      "X-Project-ID": {
        "name": "X-Project-ID",
        "in": "header",
        "required": true,
        "description": "Project UUID. Required for all project-scoped endpoints.",
        "example": "$YGO_PROJECT_ID",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "headers": {
      "Retry-After": {
        "description": "Number of seconds to wait before retrying the request. Present on 429 responses.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "example": 30
        }
      },
      "X-Trace-ID": {
        "description": "Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.",
        "schema": {
          "type": "string",
          "example": "abc123def456ghi789"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad Request: the request body failed validation.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "noSelector": {
                "summary": "No selector provided",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "HotelID",
                        "Message": "Provide exactly one of HotelID, GlobalHotelID, or ExternalHotelID"
                      }
                    ]
                  }
                }
              },
              "multipleSelectors": {
                "summary": "More than one selector provided",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "HotelID",
                        "Message": "Provide exactly one of HotelID, GlobalHotelID, or ExternalHotelID (multiple were provided)"
                      }
                    ]
                  }
                }
              },
              "invalidExternalHotelID": {
                "summary": "Unsupported ExternalHotelID sub-key",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "ExternalHotelID",
                        "Message": "Unsupported ExternalHotelID key: hrs"
                      }
                    ]
                  }
                }
              },
              "emptyExternalHotelID": {
                "summary": "ExternalHotelID has no supported sub-key",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "ExternalHotelID",
                        "Message": "ExternalHotelID must contain at least one supported sub-key"
                      }
                    ]
                  }
                }
              },
              "invalidGiata": {
                "summary": "giata is not a positive number",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "ExternalHotelID",
                        "Message": "ExternalHotelID.giata must be a positive number"
                      }
                    ]
                  }
                }
              },
              "invalidPeakworkGoalID": {
                "summary": "peakworkgoalid is not a positive number",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "ExternalHotelID",
                        "Message": "ExternalHotelID.peakworkgoalid must be a positive number"
                      }
                    ]
                  }
                }
              },
              "invalidHotelID": {
                "summary": "HotelID is not a valid UUID",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Invalid HotelID format"
                  }
                }
              },
              "invalidBody": {
                "summary": "Malformed request body",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Invalid request body"
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden: the API key may not act on this project, or does not carry the `content.catalog:read` permission this endpoint requires (`INSUFFICIENT_SCOPE`).",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "insufficientScope": {
                "summary": "Missing required scope",
                "value": {
                  "Error": {
                    "Code": "INSUFFICIENT_SCOPE",
                    "Message": "token lacks scope content.catalog:read"
                  }
                }
              },
              "noProjectAccess": {
                "summary": "Project access required",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Project access required"
                  }
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error: unexpected server error. Quote the `X-Trace-ID` response header when contacting support.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "internalError": {
                "summary": "Internal server error",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to load hotel"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found: the hotel does not exist or is not in your project's scope.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "hotelNotFound": {
                "summary": "Hotel not found",
                "value": {
                  "Error": {
                    "Code": "NOT_FOUND",
                    "Message": "Hotel not found"
                  }
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests: the rate limit was exceeded. `Retry-After` carries the number of seconds to wait before retrying.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "rateLimited": {
                "summary": "Limit exceeded",
                "value": {
                  "Error": {
                    "Code": "RATE_LIMIT_EXCEEDED",
                    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized: the API key is missing or invalid.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidKey": {
                "summary": "Invalid API key",
                "value": {
                  "Error": {
                    "Code": "UNAUTHORIZED",
                    "Message": "Invalid API key"
                  }
                }
              }
            }
          }
        }
      }
    },
    "examples": {
      "EnrichedHotelResult": {
        "summary": "A fully enriched Mallorca-style hotel",
        "value": {
          "Data": {
            "ID": "0192fb17-5dc6-7abc-8def-123456789abc",
            "Name": "Bahia Azul Beach Resort",
            "Names": {
              "en-US": "Bahia Azul Beach Resort",
              "de-DE": "Bahia Azul Strandresort"
            },
            "ExternalHotelIDs": {
              "ProductID": "HTL-MAJ-4711",
              "Giata": "668370",
              "PeakworkGoalID": "864521"
            },
            "GlobalHotelID": "ES-MALLR-K7MP2",
            "Stars": 4.5,
            "StarsMap": {
              "default": {
                "Stars": 4.5,
                "Superior": false,
                "Garni": false
              },
              "project": {
                "Stars": 4.5,
                "Superior": false,
                "Garni": false
              }
            },
            "AccommodationType": "resort",
            "Chain": "Meliá Hotels International",
            "Brand": "Sol by Meliá",
            "Location": {
              "Latitude": 39.5696,
              "Longitude": 2.6502,
              "CountryCode": "ES",
              "Address": {
                "Street": "Carrer de la Mar 12",
                "City": "Palma",
                "CityNames": {
                  "en-US": "Palma",
                  "de-DE": "Palma"
                },
                "State": "Illes Balears",
                "PostalCode": "07015",
                "Phone": "+34 971 000 000",
                "Email": "info@bahia-azul.example"
              }
            },
            "FactualAttributes": [
              {
                "Key": "wifi",
                "Type": "factual",
                "Name": {
                  "en-US": "Free WiFi",
                  "de-DE": "Kostenloses WLAN"
                },
                "Value": "true",
                "ValueType": "boolean",
                "ParentKey": "facilities_and_services",
                "IsFree": true,
                "GTCodes": [
                  "GT03-INTE",
                  "AT03-FRCH"
                ]
              },
              {
                "Key": "parking",
                "Type": "factual",
                "Name": {
                  "en-US": "Parking",
                  "de-DE": "Parkplatz"
                },
                "Value": "true",
                "ValueType": "boolean",
                "ParentKey": "facilities_and_services",
                "IsFree": false,
                "GTCodes": [
                  "GT03-CAPA",
                  "AT03-EXCO"
                ]
              },
              {
                "Key": "golf_course",
                "Type": "factual",
                "Name": {
                  "en-US": "Golf course",
                  "de-DE": "Golfplatz"
                },
                "Value": "true",
                "ValueType": "boolean",
                "ParentKey": "leisure_and_wellness",
                "IsFree": null,
                "GTCodes": [
                  "GT03-GOLF"
                ],
                "IsOnSite": false
              },
              {
                "Key": "restaurant",
                "Type": "factual",
                "Name": {
                  "en-US": "Restaurants",
                  "de-DE": "Restaurants"
                },
                "ValueType": "group",
                "ParentKey": "food_and_drink",
                "IsFree": null,
                "GTCodes": [
                  "GT03-REST"
                ],
                "Instances": [
                  {
                    "Name": "La Marea",
                    "Details": {
                      "description": "Mediterranean a la carte restaurant with sea views.",
                      "hours": "19:00-23:00"
                    }
                  },
                  {
                    "Name": "Buffet Central",
                    "Details": {
                      "description": "Main buffet restaurant serving breakfast, lunch and dinner."
                    }
                  }
                ]
              }
            ],
            "POIs": [
              {
                "ID": "0192fb20-1aa2-7def-9abc-3344556677cc",
                "Name": {
                  "en-US": "Es Portitxol",
                  "de-DE": "Es Portitxol"
                },
                "Type": "attraction",
                "IsArea": true,
                "InArea": true
              },
              {
                "ID": "0192fb20-1aa2-7def-9abc-2233445566bb",
                "Name": {
                  "en-US": "Can Pere Antoni Beach",
                  "de-DE": "Strand Can Pere Antoni"
                },
                "Type": "beach",
                "Distance": 250,
                "Unit": "m"
              },
              {
                "ID": "0192fb20-1aa2-7def-9abc-4455667788dd",
                "Name": {
                  "en-US": "Palma Old Town",
                  "de-DE": "Altstadt von Palma"
                },
                "Type": "attraction",
                "Distance": 2.4,
                "Unit": "km",
                "IsArea": true
              },
              {
                "ID": "0192fb20-1aa2-7def-9abc-1122334455aa",
                "Name": {
                  "en-US": "Palma Cathedral",
                  "de-DE": "Kathedrale von Palma"
                },
                "Type": "landmark",
                "Distance": 3.2,
                "Unit": "km",
                "Latitude": 39.5675,
                "Longitude": 2.6484
              }
            ],
            "CheckIn": {
              "From": "15:00"
            },
            "CheckOut": {
              "Until": "11:00"
            },
            "GeneratedTexts": {
              "en-US": {
                "Summary": {
                  "Text": "Set on a quiet stretch of the Bay of Palma, Bahia Azul Beach Resort pairs direct beach access with bright, contemporary rooms and a sea-view rooftop pool.",
                  "Compliance": {
                    "AIGenerated": true
                  }
                },
                "HouseRules": {
                  "Text": "Check-in is from 15:00 and check-out is until 11:00. Pets are not permitted. Quiet hours apply between 23:00 and 08:00.",
                  "GeneratedAt": "2026-04-12T09:15:00Z",
                  "TextType": "rules",
                  "Compliance": {
                    "AIGenerated": true
                  }
                }
              },
              "de-DE": {
                "Summary": {
                  "Text": "Das Bahia Azul Strandresort liegt an einem ruhigen Abschnitt der Bucht von Palma und verbindet direkten Strandzugang mit hellen, modernen Zimmern und einem Dachpool mit Meerblick.",
                  "Compliance": {
                    "AIGenerated": true
                  }
                },
                "HouseRules": {
                  "Text": "Der Check-in ist ab 15:00 Uhr und der Check-out bis 11:00 Uhr moeglich. Haustiere sind nicht gestattet. Ruhezeiten gelten zwischen 23:00 und 08:00 Uhr.",
                  "GeneratedAt": "2026-04-12T09:15:00Z",
                  "TextType": "rules",
                  "Compliance": {
                    "AIGenerated": true
                  }
                }
              }
            },
            "GuestRating": {
              "ReviewScore": 93,
              "SubScores": {
                "Cleanliness": 96,
                "Facilities": 93,
                "Food": 91,
                "Location": 91,
                "Rooms": 95,
                "Service": 96,
                "Value": 90
              },
              "Texts": {
                "en-US": {
                  "Summary": "Guests consistently describe their stay as a peaceful, relaxing retreat highlighted by exceptionally friendly and attentive staff. Rooms and grounds are praised for being spotless and comfortable, while the delicious breakfast and calm adults-only setting make it an ideal getaway.",
                  "Pros": [
                    "Warm, attentive, and professional staff",
                    "Spotless rooms and well-kept grounds",
                    "Peaceful, child-free atmosphere",
                    "Superb and varied breakfast spread",
                    "Modern, spacious guest rooms"
                  ],
                  "Cons": [
                    "Extra charges for some premium drinks and minibar",
                    "Lunch and dinner buffets can feel repetitive to some"
                  ],
                  "GeneratedAt": "2026-11-05T18:10:57Z",
                  "Compliance": {
                    "AIGenerated": true
                  }
                }
              }
            },
            "RenderLayouts": {
              "Summary": "prose",
              "HouseRules": "highlights"
            },
            "Images": [
              {
                "ID": "0192fb20-1aa2-7def-9abc-1122334455aa",
                "URL": "https://cdn.ygo.ai/hotels/bahia-azul/exterior-pool.jpg",
                "Source": "photo",
                "Category": "exterior",
                "Features": [
                  "pool",
                  "sea_view"
                ],
                "Mood": [
                  "relaxing"
                ],
                "Tags": [
                  "rooftop",
                  "sunset"
                ],
                "AppealScore": 88,
                "QualityScore": 91,
                "AppealScoreVersion": "app-v4",
                "QualityScoreVersion": "qs-v4",
                "Width": 1600,
                "Height": 1067,
                "Format": "jpeg",
                "FileSize": 412000,
                "DominantColor": "#2E6F95",
                "BlurHash": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH",
                "FileMetadata": {
                  "CaptureDate": "2012-06-14",
                  "Copyright": "© 2012 Hotel Sol S.A."
                },
                "Descriptions": {
                  "en-US": "Rooftop infinity pool overlooking the Bay of Palma at sunset."
                },
                "Compliance": {
                  "AIGenerated": true
                },
                "Presence": [
                  {
                    "Label": "person",
                    "Confidence": 0.91
                  },
                  {
                    "Label": "adult",
                    "Confidence": 0.86
                  }
                ],
                "Safety": {
                  "Inappropriate": 0.02,
                  "OffTopic": null
                },
                "TextDetections": [
                  {
                    "Content": "POOL BAR",
                    "Label": "signage",
                    "Confidence": 0.74
                  }
                ],
                "FeatureDetections": [
                  {
                    "Label": "pool",
                    "Confidence": 0.96
                  },
                  {
                    "Label": "sea_view",
                    "Confidence": 0.9
                  }
                ]
              }
            ],
            "Rooms": [
              {
                "ID": "0192fb30-2bb3-7abc-8def-99887766aabb",
                "Name": {
                  "en-US": "Double Room Sea View",
                  "de-DE": "Doppelzimmer mit Meerblick"
                },
                "SizeSqm": 26,
                "Beddings": [
                  [
                    {
                      "Type": "DOUBLE",
                      "Quantity": 1,
                      "Name": {
                        "en-US": "double bed",
                        "de-DE": "Doppelbett"
                      }
                    }
                  ],
                  [
                    {
                      "Type": "TWIN",
                      "Quantity": 2,
                      "Name": {
                        "en-US": "twin beds",
                        "de-DE": "Einzelbetten"
                      }
                    }
                  ]
                ],
                "FactualAttributes": [
                  {
                    "Key": "air_conditioning",
                    "Type": "factual",
                    "Name": {
                      "en-US": "Air Conditioning",
                      "de-DE": "Klimaanlage"
                    },
                    "Value": "true",
                    "ValueType": "boolean",
                    "ParentKey": "room_facilities",
                    "IsFree": true,
                    "GTCodes": [
                      "GT05-AICO",
                      "AT05-FRCH"
                    ]
                  }
                ],
                "GeneratedTexts": {
                  "en-US": {
                    "RoomDescription": {
                      "Text": "A bright 26 sqm room with a private balcony framing the bay, a king-size bed and a walk-in rain shower.",
                      "Compliance": {
                        "AIGenerated": true
                      }
                    }
                  }
                },
                "RenderLayouts": {
                  "": "roomcards"
                },
                "ExternalRoomIDs": {
                  "ProductRoomIDs": [
                    "11824",
                    "11902"
                  ]
                },
                "Images": [
                  {
                    "ID": "0192fb31-3cc4-7abc-8def-aabbccddeeff",
                    "URL": "https://cdn.ygo.ai/hotels/bahia-azul/room-seaview.jpg",
                    "Category": "room",
                    "Features": [
                      "balcony",
                      "sea_view"
                    ],
                    "Mood": [
                      "bright"
                    ],
                    "Tags": [
                      "king_bed"
                    ],
                    "AppealScore": 80,
                    "QualityScore": 84,
                    "AppealScoreVersion": "app-v4",
                    "QualityScoreVersion": "qs-v4",
                    "Width": 1500,
                    "Height": 1000,
                    "Format": "jpeg",
                    "FileSize": 356000,
                    "DominantColor": "#D9E2EC",
                    "BlurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
                    "Descriptions": {
                      "en-US": "Sea-view double room with a private balcony."
                    },
                    "Compliance": {
                      "AIGenerated": true
                    }
                  }
                ],
                "Status": "active",
                "CreatedAt": "2026-03-01T08:00:00Z",
                "UpdatedAt": "2026-04-10T12:30:00Z"
              }
            ],
            "Tags": [
              {
                "ID": "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
                "Name": "Summer Campaign",
                "Description": "Hotels in the 2026 summer campaign"
              }
            ],
            "Status": "active",
            "TextStatus": "generated",
            "CreatedAt": "2026-03-01T08:00:00Z",
            "UpdatedAt": "2026-04-12T09:15:00Z"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Project-scoped API key"
      }
    }
  }
}
