{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: List enriched hotel summaries",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ygo.ai",
      "description": "Production and Sandbox (determined by API key)"
    }
  ],
  "paths": {
    "/v2/project/content/listEnrichedHotelSummaries": {
      "post": {
        "summary": "List enriched hotel summaries",
        "description": "Return a paginated roster of the calling project's hotels, built and returned synchronously. Only hotels belonging to your project are returned. Rows also carry up to five images, the Summary text per locale and the nearest beach and airport; no rooms, attributes or other texts.\n\n- `Limit` defaults to 50, or to 100 when `HotelIDs` is set, and is capped at 100.\n- Every filter is AND-ed with the others; `Pagination.Total` counts the hotels left after filtering.\n- `HotelIDs` and `ExternalHotelIDs` take up to 100 elements each; rows keep the default order, not the order of `HotelIDs`.\n- `Sort: 'feedback_activity'` and the `LastFeedbackAt` and `LastFeedbackReplyAt` fields need the `content.authoring:read` permission; without it the fields are omitted and the sort returns 403.\n- An unknown tag returns 404.",
        "operationId": "listEnrichedHotelSummaries",
        "tags": [
          "Content Enrichment API/Enrichment"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Project-ID"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListEnrichedHotelSummariesRequest"
              },
              "examples": {
                "firstPage": {
                  "summary": "First page with default page size",
                  "value": {
                    "Limit": 50,
                    "Offset": 0
                  }
                },
                "filtered": {
                  "summary": "Filter by country, active status, and a search term",
                  "value": {
                    "CountryCode": "ES",
                    "Status": "active",
                    "Search": "beach resort",
                    "Limit": 25,
                    "Offset": 0
                  }
                },
                "byTags": {
                  "summary": "Restrict to the project's hotels carrying all of these tags",
                  "value": {
                    "TagIDs": [
                      "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
                      "0192fc02-2222-7abc-8def-bbbbbbbbbbbb"
                    ],
                    "Limit": 50,
                    "Offset": 0
                  }
                },
                "byExternalHotelID": {
                  "summary": "Restrict to hotels matching either of two external-identity selectors",
                  "value": {
                    "ExternalHotelIDs": [
                      {
                        "productid": "HTL-MAJ-4711"
                      },
                      {
                        "giata": "7654321",
                        "peakworkgoalid": "864522"
                      }
                    ],
                    "Limit": 50,
                    "Offset": 0
                  }
                },
                "byHotelIDs": {
                  "summary": "Fetch named hotels by id in one request",
                  "value": {
                    "HotelIDs": [
                      "0192fb17-5dc6-7abc-8def-123456789abc",
                      "0192fb18-6ed7-7abc-8def-223456789abc",
                      "0192fb19-7fe8-7abc-8def-323456789abc"
                    ]
                  }
                },
                "byFeedbackActivity": {
                  "summary": "The most recent feedback activity first",
                  "value": {
                    "Sort": "feedback_activity",
                    "Limit": 50,
                    "Offset": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project hotel roster retrieved successfully.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListEnrichedHotelSummariesResponse"
                },
                "examples": {
                  "firstPage": {
                    "summary": "A page of enriched hotel summaries",
                    "value": {
                      "Data": [
                        {
                          "ID": "0192fb17-5dc6-7abc-8def-123456789abc",
                          "Name": "Bahia Azul Beach Resort",
                          "ExternalHotelIDs": {
                            "ProductID": "HTL-MAJ-4711",
                            "Giata": "668370"
                          },
                          "GlobalHotelID": "ES-MALLR-K7MP2",
                          "Stars": 4,
                          "StarsMap": {
                            "default": {
                              "Stars": 4,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Palma",
                          "CityNames": {
                            "en-US": "Palma",
                            "de-DE": "Palma"
                          },
                          "Status": "active",
                          "TextEnrichmentStatus": "enriched",
                          "TextStatus": "generated",
                          "LastEnrichedAt": "2026-04-12T09:15:00Z",
                          "FullyEnrichedAt": "2026-04-12T09:15:00Z",
                          "Latitude": 39.5696,
                          "Longitude": 2.6502,
                          "Images": [
                            {
                              "URL": "https://cdn.ygo.ai/hotels/bahia-azul/exterior-pool.jpg",
                              "Width": 1600,
                              "Height": 1067,
                              "BlurHash": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH"
                            },
                            {
                              "URL": "https://cdn.ygo.ai/hotels/bahia-azul/beach.jpg",
                              "Width": 1600,
                              "Height": 1067,
                              "BlurHash": "L6PZfSi_.AyE_3t7t7R**0o#DgR4"
                            },
                            {
                              "URL": "https://cdn.ygo.ai/hotels/bahia-azul/room-sea-view.jpg",
                              "Width": 1200,
                              "Height": 800,
                              "BlurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
                            }
                          ],
                          "GeneratedTexts": {
                            "de-DE": {
                              "Summary": {
                                "Text": "Das Bahia Azul Beach Resort liegt an einem ruhigen Abschnitt der Bucht von Palma und verbindet direkten Strandzugang mit hellen, modernen Zimmern und einem Dachpool mit Meerblick.",
                                "GeneratedAt": "2026-04-12T09:15:00Z",
                                "Compliance": {
                                  "AIGenerated": true
                                }
                              }
                            },
                            "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.",
                                "GeneratedAt": "2026-04-12T09:15:00Z",
                                "Compliance": {
                                  "AIGenerated": true
                                }
                              }
                            }
                          },
                          "NearestPOIs": [
                            {
                              "Type": "beach",
                              "Distance": 0,
                              "Unit": "m"
                            },
                            {
                              "Type": "airport",
                              "Distance": 11.4,
                              "Unit": "km"
                            }
                          ],
                          "CreatedAt": "2026-03-01T08:00:00Z",
                          "UpdatedAt": "2026-04-12T09:15:00Z"
                        },
                        {
                          "ID": "0192fb18-6ed7-7abc-8def-223456789abc",
                          "Name": "Costa Verde City Hotel",
                          "ExternalHotelIDs": {
                            "ProductID": "ESVALEN0007",
                            "Giata": "7654321"
                          },
                          "Stars": 3,
                          "StarsMap": {
                            "default": {
                              "Stars": 3,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Valencia",
                          "Status": "draft",
                          "TextEnrichmentStatus": "none",
                          "TextStatus": "none",
                          "CreatedAt": "2026-03-04T10:30:00Z",
                          "UpdatedAt": "2026-03-20T14:05:00Z"
                        }
                      ],
                      "Pagination": {
                        "Total": 128,
                        "Limit": 50,
                        "Offset": 0
                      }
                    }
                  },
                  "filtered": {
                    "summary": "A filtered page with a single match",
                    "value": {
                      "Data": [
                        {
                          "ID": "0192fb17-5dc6-7abc-8def-123456789abc",
                          "Name": "Bahia Azul Beach Resort",
                          "ExternalHotelIDs": {
                            "ProductID": "HTL-MAJ-4711",
                            "Giata": "668370"
                          },
                          "GlobalHotelID": "ES-MALLR-K7MP2",
                          "Stars": 4,
                          "StarsMap": {
                            "default": {
                              "Stars": 4,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Palma",
                          "CityNames": {
                            "en-US": "Palma",
                            "de-DE": "Palma"
                          },
                          "Status": "active",
                          "TextEnrichmentStatus": "enriched",
                          "TextStatus": "generated",
                          "LastEnrichedAt": "2026-04-12T09:15:00Z",
                          "FullyEnrichedAt": "2026-04-12T09:15:00Z",
                          "Latitude": 39.5696,
                          "Longitude": 2.6502,
                          "CreatedAt": "2026-03-01T08:00:00Z",
                          "UpdatedAt": "2026-04-12T09:15:00Z"
                        }
                      ],
                      "Pagination": {
                        "Total": 1,
                        "Limit": 25,
                        "Offset": 0
                      }
                    }
                  },
                  "byTags": {
                    "summary": "A page narrowed to hotels carrying all requested tags",
                    "value": {
                      "Data": [
                        {
                          "ID": "0192fb17-5dc6-7abc-8def-123456789abc",
                          "Name": "Bahia Azul Beach Resort",
                          "ExternalHotelIDs": {
                            "ProductID": "HTL-MAJ-4711",
                            "Giata": "668370"
                          },
                          "GlobalHotelID": "ES-MALLR-K7MP2",
                          "Stars": 4,
                          "StarsMap": {
                            "default": {
                              "Stars": 4,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Palma",
                          "CityNames": {
                            "en-US": "Palma",
                            "de-DE": "Palma"
                          },
                          "Status": "active",
                          "TextEnrichmentStatus": "enriched",
                          "TextStatus": "generated",
                          "LastEnrichedAt": "2026-04-12T09:15:00Z",
                          "FullyEnrichedAt": "2026-04-12T09:15:00Z",
                          "Latitude": 39.5696,
                          "Longitude": 2.6502,
                          "Tags": [
                            {
                              "ID": "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
                              "Name": "Summer Campaign",
                              "Description": "Hotels in the 2026 summer campaign"
                            },
                            {
                              "ID": "0192fc02-2222-7abc-8def-bbbbbbbbbbbb",
                              "Name": "Beachfront"
                            }
                          ],
                          "CreatedAt": "2026-03-01T08:00:00Z",
                          "UpdatedAt": "2026-04-12T09:15:00Z"
                        }
                      ],
                      "Pagination": {
                        "Total": 1,
                        "Limit": 50,
                        "Offset": 0
                      }
                    }
                  },
                  "byExternalHotelID": {
                    "summary": "A page narrowed to hotels matching the supplied external-identity selectors",
                    "value": {
                      "Data": [
                        {
                          "ID": "0192fb17-5dc6-7abc-8def-123456789abc",
                          "Name": "Bahia Azul Beach Resort",
                          "ExternalHotelIDs": {
                            "ProductID": "HTL-MAJ-4711",
                            "Giata": "668370"
                          },
                          "GlobalHotelID": "ES-MALLR-K7MP2",
                          "Stars": 4,
                          "StarsMap": {
                            "default": {
                              "Stars": 4,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Palma",
                          "CityNames": {
                            "en-US": "Palma",
                            "de-DE": "Palma"
                          },
                          "Status": "active",
                          "TextEnrichmentStatus": "enriched",
                          "TextStatus": "generated",
                          "LastEnrichedAt": "2026-04-12T09:15:00Z",
                          "FullyEnrichedAt": "2026-04-12T09:15:00Z",
                          "Latitude": 39.5696,
                          "Longitude": 2.6502,
                          "CreatedAt": "2026-03-01T08:00:00Z",
                          "UpdatedAt": "2026-04-12T09:15:00Z"
                        },
                        {
                          "ID": "0192fb18-6ed7-7abc-8def-223456789abc",
                          "Name": "Costa Verde City Hotel",
                          "ExternalHotelIDs": {
                            "ProductID": "ESVALEN0007",
                            "Giata": "7654321",
                            "PeakworkGoalID": "864522"
                          },
                          "Stars": 3,
                          "StarsMap": {
                            "default": {
                              "Stars": 3,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Valencia",
                          "Status": "draft",
                          "TextEnrichmentStatus": "none",
                          "TextStatus": "none",
                          "CreatedAt": "2026-03-04T10:30:00Z",
                          "UpdatedAt": "2026-03-20T14:05:00Z"
                        }
                      ],
                      "Pagination": {
                        "Total": 2,
                        "Limit": 50,
                        "Offset": 0
                      }
                    }
                  },
                  "byHotelIDs": {
                    "summary": "The named hotels that belong to the project; the third id is not one of the project's hotels and is absent",
                    "value": {
                      "Data": [
                        {
                          "ID": "0192fb17-5dc6-7abc-8def-123456789abc",
                          "Name": "Bahia Azul Beach Resort",
                          "ExternalHotelIDs": {
                            "ProductID": "HTL-MAJ-4711",
                            "Giata": "668370"
                          },
                          "GlobalHotelID": "ES-MALLR-K7MP2",
                          "Stars": 4,
                          "StarsMap": {
                            "default": {
                              "Stars": 4,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Palma",
                          "CityNames": {
                            "en-US": "Palma",
                            "de-DE": "Palma"
                          },
                          "Status": "active",
                          "TextEnrichmentStatus": "enriched",
                          "TextStatus": "generated",
                          "LastEnrichedAt": "2026-04-12T09:15:00Z",
                          "FullyEnrichedAt": "2026-04-12T09:15:00Z",
                          "Latitude": 39.5696,
                          "Longitude": 2.6502,
                          "CreatedAt": "2026-03-01T08:00:00Z",
                          "UpdatedAt": "2026-04-12T09:15:00Z"
                        },
                        {
                          "ID": "0192fb18-6ed7-7abc-8def-223456789abc",
                          "Name": "Costa Verde City Hotel",
                          "ExternalHotelIDs": {
                            "ProductID": "ESVALEN0007",
                            "Giata": "7654321"
                          },
                          "Stars": 3,
                          "StarsMap": {
                            "default": {
                              "Stars": 3,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Valencia",
                          "Status": "draft",
                          "TextEnrichmentStatus": "none",
                          "TextStatus": "none",
                          "CreatedAt": "2026-03-04T10:30:00Z",
                          "UpdatedAt": "2026-03-20T14:05:00Z"
                        }
                      ],
                      "Pagination": {
                        "Total": 2,
                        "Limit": 100,
                        "Offset": 0
                      }
                    }
                  },
                  "byFeedbackActivity": {
                    "summary": "Sorted by feedback activity: the first hotel's newest event is a reply on an older comment, the second's a new comment, the third has no feedback",
                    "value": {
                      "Data": [
                        {
                          "ID": "0192fb18-6ed7-7abc-8def-223456789abc",
                          "Name": "Costa Verde City Hotel",
                          "ExternalHotelIDs": {
                            "ProductID": "ESVALEN0007",
                            "Giata": "7654321"
                          },
                          "Stars": 3,
                          "StarsMap": {
                            "default": {
                              "Stars": 3,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Valencia",
                          "Status": "draft",
                          "TextEnrichmentStatus": "none",
                          "TextStatus": "none",
                          "LastFeedbackAt": "2026-09-30T15:02:47.120554Z",
                          "LastFeedbackReplyAt": "2026-10-07T10:18:05.903311Z",
                          "CreatedAt": "2026-03-04T10:30:00Z",
                          "UpdatedAt": "2026-03-20T14:05:00Z"
                        },
                        {
                          "ID": "0192fb17-5dc6-7abc-8def-123456789abc",
                          "Name": "Bahia Azul Beach Resort",
                          "ExternalHotelIDs": {
                            "ProductID": "HTL-MAJ-4711",
                            "Giata": "668370"
                          },
                          "GlobalHotelID": "ES-MALLR-K7MP2",
                          "Stars": 4,
                          "StarsMap": {
                            "default": {
                              "Stars": 4,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Palma",
                          "Status": "active",
                          "TextEnrichmentStatus": "enriched",
                          "TextStatus": "generated",
                          "LastEnrichedAt": "2026-04-12T09:15:00Z",
                          "FullyEnrichedAt": "2026-04-12T09:15:00Z",
                          "Latitude": 39.5696,
                          "Longitude": 2.6502,
                          "LastFeedbackAt": "2026-10-07T08:41:12.483917Z",
                          "CreatedAt": "2026-03-01T08:00:00Z",
                          "UpdatedAt": "2026-04-12T09:15:00Z"
                        },
                        {
                          "ID": "0192fb19-7fe8-7abc-8def-323456789abc",
                          "Name": "Sierra Alta Mountain Lodge",
                          "ExternalHotelIDs": {
                            "ProductID": "ESGRANA0042",
                            "Giata": "8812345"
                          },
                          "Stars": 4,
                          "StarsMap": {
                            "default": {
                              "Stars": 4,
                              "Superior": false,
                              "Garni": false
                            }
                          },
                          "CountryCode": "ES",
                          "City": "Granada",
                          "Status": "active",
                          "TextEnrichmentStatus": "enriched",
                          "TextStatus": "generated",
                          "LastEnrichedAt": "2026-04-02T07:40:00Z",
                          "Latitude": 37.1773,
                          "Longitude": -3.5986,
                          "CreatedAt": "2026-03-05T11:20:00Z",
                          "UpdatedAt": "2026-04-02T07:40:00Z"
                        }
                      ],
                      "Pagination": {
                        "Total": 3,
                        "Limit": 50,
                        "Offset": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "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": {
      "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
          }
        }
      },
      "EnrichedHotelSummary": {
        "type": "object",
        "required": [
          "ID",
          "Name",
          "Stars",
          "StarsMap",
          "CountryCode",
          "City",
          "Status",
          "TextEnrichmentStatus",
          "CreatedAt",
          "UpdatedAt"
        ],
        "description": "A hotel row for lists: identity, location, status, up to five images, the Summary text per locale and the nearest beach and airport. A row whose content could not be built has no Images, GeneratedTexts or NearestPOIs.",
        "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"
          },
          "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"
          },
          "CountryCode": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code.",
            "example": "ES"
          },
          "City": {
            "type": "string",
            "description": "City or town, derived from the hotel's address. Empty when unavailable.",
            "example": "Palma"
          },
          "CityNames": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Localized city names keyed by BCP 47 language tag, present only once generated; values are non-empty, and a locale with no established exonym carries the local name. Fall back to City.",
            "example": {
              "en-US": "Rome",
              "de-DE": "Rom",
              "it-IT": "Roma"
            }
          },
          "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"
          },
          "TextEnrichmentStatus": {
            "type": "string",
            "deprecated": true,
            "enum": [
              "enriched",
              "enriching",
              "none"
            ],
            "description": "Deprecated: use `TextStatus`. Derived per-hotel generated-text state: 'enriched' (texts generated), 'enriching' (generation in progress), or 'none' (no texts yet).",
            "example": "enriched"
          },
          "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"
          },
          "LastEnrichedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the most recent enrichment run for this hotel (RFC3339). Empty when the hotel has never been enriched.",
            "example": "2026-04-12T09:15:00Z"
          },
          "FullyEnrichedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the hotel completed full enrichment (RFC3339). Empty when the hotel is not fully enriched.",
            "example": "2026-04-12T09:15:00Z"
          },
          "Latitude": {
            "type": "number",
            "format": "double",
            "description": "Latitude of the hotel's stored location in decimal degrees (WGS 84). Absent together with Longitude when the hotel has no coordinates (null or 0,0).",
            "example": 39.5696
          },
          "Longitude": {
            "type": "number",
            "format": "double",
            "description": "Longitude of the hotel's stored location in decimal degrees (WGS 84). Absent together with Latitude when the hotel has no coordinates (null or 0,0).",
            "example": 2.6502
          },
          "Tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProjectTagSummary"
            },
            "description": "This project's internal tags applied to the hotel. Present only when the hotel carries one or more; omitted otherwise."
          },
          "LastFeedbackAt": {
            "type": "string",
            "format": "date-time",
            "description": "Creation time of the newest comment on this hotel in your project, rejected ones included and withdrawn ones not, RFC 3339 UTC with fractional seconds. Omitted when none, or without content.authoring:read.",
            "example": "2026-10-07T08:41:12.483917Z"
          },
          "LastFeedbackReplyAt": {
            "type": "string",
            "format": "date-time",
            "description": "The newest review-team answer on the comments counted for LastFeedbackAt: the creation time of the newest review-team reply in such a comment's thread, or, for an answer stored on the row itself (one written before threaded replies, or the decision on a photo upload, which takes no reply), the row's update time, whichever is newer; a review-team redaction of such a row also moves it. RFC 3339 UTC with fractional seconds. Omitted when none or without content.authoring:read.",
            "example": "2026-10-07T10:18:05.903311Z"
          },
          "Images": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "$ref": "#/components/schemas/SummaryImage"
            },
            "description": "The cover image, then up to four more in the order the hotel's gallery serves them, so a pinned image stays first. Omitted when the hotel has no images or its content could not be built."
          },
          "GeneratedTexts": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SummaryGeneratedTexts"
              }
            ],
            "description": "The hotel's Summary text per locale, with your project's static texts (such as promotions or disclaimers) composed in at request time. Omitted when no locale has a Summary or the content could not be built."
          },
          "NearestPOIs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NearestPOI"
            },
            "description": "The nearest point of interest per type, at most one each: currently `beach` and `airport`; a type with none is absent. Omitted when there is none or the content could not be built."
          },
          "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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": "TextEnrichmentStatus"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable validation error message for this field.",
            "example": "TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'"
          },
          "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": "TOO_LONG"
          },
          "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."
          }
        }
      },
      "ListEnrichedHotelSummariesRequest": {
        "type": "object",
        "description": "Request body for listing the project's hotels. All fields are optional; omit the body to fetch the first page with default paging.",
        "properties": {
          "CountryCode": {
            "type": "string",
            "description": "Filter to hotels in this ISO 3166-1 alpha-2 country code. Omit to include all countries.",
            "example": "ES"
          },
          "Status": {
            "type": "string",
            "enum": [
              "draft",
              "active",
              "inactive",
              "closed_temporarily",
              "closed_permanently",
              "removed"
            ],
            "description": "Filter by the hotel's status in your project, one value (see `Status` on the rows). Any other value answers 400.",
            "example": "active"
          },
          "TextStatus": {
            "type": "string",
            "enum": [
              "none",
              "generating",
              "generated",
              "failed"
            ],
            "description": "Filter by your project's text state of the hotel, one value (see `TextStatus` on the rows). Any other value answers 400.",
            "example": "generated"
          },
          "IsFullyEnriched": {
            "type": "boolean",
            "description": "When true, restrict the list to hotels that have completed full enrichment.",
            "example": true
          },
          "Search": {
            "type": "string",
            "description": "Free-text search term matched against hotel name and related identity fields.",
            "example": "beach resort"
          },
          "CodeKind": {
            "type": "string",
            "description": "Filter to hotels carrying a code of this kind and surface that kind's master code. When omitted, no code-kind filter is applied and each hotel's canonical master code (or its smallest available code kind) is surfaced.",
            "example": "peakwork_master"
          },
          "TextEnrichmentStatus": {
            "type": "string",
            "deprecated": true,
            "enum": [
              "enriched",
              "enriching",
              "none"
            ],
            "description": "Deprecated: use `TextStatus`. Filter by the per-hotel generated-text state: 'enriched' (texts generated), 'enriching' (generation in progress), or 'none' (no texts yet).",
            "example": "enriched"
          },
          "TagIDs": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter to hotels carrying all of these project tags, AND-combined with `TagName`. An unknown or foreign tag returns 404.",
            "example": [
              "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
              "0192fc02-2222-7abc-8def-bbbbbbbbbbbb"
            ]
          },
          "TagName": {
            "type": "string",
            "description": "Filter by a single project tag name, case-insensitive, AND-combined with `TagIDs`. An unknown name returns 404.",
            "example": "Summer Campaign"
          },
          "ExternalHotelIDs": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              },
              "description": "One selector: `productid`, compared exactly, or `giata` or `peakworkgoalid`, positive integers compared by number (`giata` up to 2147483647) or a 400. Sub-keys are AND-combined, names case-insensitive; a whitespace-only value is not provided."
            },
            "description": "Filter to hotels matching any of these selectors; elements are OR-ed, sub-keys within an element AND-ed, and one matching none of your hotels adds no row. At most 100 elements; a longer array returns 400.",
            "example": [
              {
                "productid": "HTL-MAJ-4711"
              },
              {
                "giata": "7654321",
                "peakworkgoalid": "864522"
              }
            ]
          },
          "HotelIDs": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string",
              "format": "uuid",
              "description": "One hotel UUID, as returned in a summary's ID field. Must be a valid, non-nil UUID.",
              "example": "0192fb17-5dc6-7abc-8def-123456789abc"
            },
            "description": "Filter to exactly these hotel UUIDs, at most 100; a longer array or an invalid or nil UUID returns 400. Duplicates are ignored, and an id outside your project is absent from Data, not an error."
          },
          "Sort": {
            "type": "string",
            "enum": [
              "feedback_activity"
            ],
            "description": "Page order: omit for the default, or 'feedback_activity' for the newest comment or reply first, hotels without feedback last; any other value or casing returns 400. Needs content.authoring:read, else 403.",
            "example": "feedback_activity"
          },
          "Limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Maximum number of items to return. Defaults to 50, or to 100 when HotelIDs is set, and is capped at 100.",
            "example": 50
          },
          "Offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0,
            "description": "Number of items to skip before collecting the page. Defaults to 0.",
            "example": 0
          }
        }
      },
      "ListEnrichedHotelSummariesResponse": {
        "type": "object",
        "required": [
          "Data",
          "Pagination"
        ],
        "description": "Paginated list response wrapping the project's hotel summaries.",
        "properties": {
          "Data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EnrichedHotelSummary"
            },
            "description": "The page of enriched hotel summaries."
          },
          "Pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "NearestPOI": {
        "type": "object",
        "required": [
          "Type",
          "Distance",
          "Unit"
        ],
        "description": "The nearest point of interest of one type and its distance from the hotel. POI data partly © OpenStreetMap contributors, available under the ODbL.",
        "properties": {
          "Type": {
            "type": "string",
            "description": "POI category, currently `beach` or `airport`; more types may be added.",
            "example": "beach"
          },
          "Distance": {
            "type": "number",
            "format": "double",
            "description": "Distance in Unit: meters below 1 km, else km to one decimal. 0 with Unit `m` when the hotel lies inside the area, for a beach on its sand.",
            "example": 350
          },
          "Unit": {
            "type": "string",
            "enum": [
              "m",
              "km"
            ],
            "description": "Unit for Distance: `m` for meters (below 1 km), `km` for kilometers.",
            "example": "m"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "required": [
          "Total",
          "Limit",
          "Offset"
        ],
        "description": "Pagination metadata for a list response.",
        "properties": {
          "Total": {
            "type": "integer",
            "description": "Total number of items matching the request across all pages.",
            "example": 128
          },
          "Limit": {
            "type": "integer",
            "description": "Maximum number of items returned in this page.",
            "example": 50
          },
          "Offset": {
            "type": "integer",
            "description": "Number of items skipped before this page.",
            "example": 0
          }
        }
      },
      "ProjectTagSummary": {
        "type": "object",
        "required": [
          "ID",
          "Name"
        ],
        "description": "A reference to one of this project's internal tags 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 (yours, if set), national, association, canonical (the hotel's own site); new keys may appear. default is always present: the first of these, 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
          }
        }
      },
      "SummaryGeneratedTexts": {
        "type": "object",
        "additionalProperties": {
          "type": "object",
          "required": [
            "Summary"
          ],
          "properties": {
            "Summary": {
              "$ref": "#/components/schemas/GeneratedTextDetail"
            }
          }
        }
      },
      "SummaryImage": {
        "type": "object",
        "required": [
          "URL",
          "Width",
          "Height",
          "BlurHash"
        ],
        "description": "One image of a hotel row: its URL, size and BlurHash placeholder.",
        "properties": {
          "URL": {
            "type": "string",
            "format": "uri",
            "description": "Image URL.",
            "example": "https://cdn.ygo.ai/hotels/bahia-azul/exterior-pool.jpg"
          },
          "Width": {
            "type": "integer",
            "description": "Image width in pixels.",
            "example": 1600
          },
          "Height": {
            "type": "integer",
            "description": "Image height in pixels.",
            "example": 1067
          },
          "BlurHash": {
            "type": "string",
            "description": "BlurHash placeholder string for progressive loading. Empty when the image has none.",
            "example": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH"
          }
        }
      }
    },
    "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 - Validation error or invalid request body.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidTextEnrichmentStatus": {
                "summary": "TextEnrichmentStatus is not a recognized value",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'"
                  }
                }
              },
              "invalidTagID": {
                "summary": "A TagID is not a valid UUID",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Invalid TagID format"
                  }
                }
              },
              "tooManyExternalHotelIDSelectors": {
                "summary": "ExternalHotelIDs has more than the allowed number of selectors",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "ExternalHotelIDs cannot contain more than 100 selectors"
                  }
                }
              },
              "invalidExternalHotelIDSelector": {
                "summary": "An ExternalHotelIDs selector has an unsupported sub-key",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "ExternalHotelIDs",
                        "Message": "Unsupported ExternalHotelIDs key: hrs"
                      }
                    ]
                  }
                }
              },
              "invalidPeakworkGoalID": {
                "summary": "An ExternalHotelIDs selector has a peakworkgoalid that is not a positive number",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "ExternalHotelIDs",
                        "Message": "ExternalHotelIDs.peakworkgoalid must be a positive number"
                      }
                    ]
                  }
                }
              },
              "tooManyHotelIDs": {
                "summary": "HotelIDs has more than the allowed number of ids",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "HotelIDs cannot contain more than 100 ids",
                    "Fields": [
                      {
                        "Field": "HotelIDs",
                        "Message": "HotelIDs cannot contain more than 100 ids"
                      }
                    ]
                  }
                }
              },
              "invalidHotelID": {
                "summary": "A HotelIDs element is not a valid, non-nil UUID",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Invalid HotelIDs format",
                    "Fields": [
                      {
                        "Field": "HotelIDs",
                        "Message": "Invalid HotelIDs format"
                      }
                    ]
                  }
                }
              },
              "invalidSort": {
                "summary": "Sort is not an allowed value",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Sort must be empty or 'feedback_activity'",
                    "Fields": [
                      {
                        "Field": "Sort",
                        "Message": "Sort must be empty or 'feedback_activity'"
                      }
                    ]
                  }
                }
              },
              "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, lacks `content.catalog:read` (`INSUFFICIENT_SCOPE`), or sends `Sort` 'feedback_activity' without `content.authoring:read`.",
        "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"
                  }
                }
              },
              "insufficientScopeFeedbackSort": {
                "summary": "Sort feedback_activity sent without content.authoring:read",
                "value": {
                  "Error": {
                    "Code": "INSUFFICIENT_SCOPE",
                    "Message": "token lacks scope content.authoring:read"
                  }
                }
              },
              "noProjectAccess": {
                "summary": "Project access required",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Project access required"
                  }
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error - Unexpected server error. Include the X-Trace-ID header value 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 list hotels"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found - A requested tag does not exist or is not in the calling project's scope.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "tagNotFound": {
                "summary": "An unknown or foreign tag was supplied in TagIDs",
                "value": {
                  "Error": {
                    "Code": "NOT_FOUND",
                    "Message": "Tag not found"
                  }
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests. The response includes a `Retry-After` header with 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 - Invalid or missing API key.",
        "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"
                  }
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Project-scoped API key"
      }
    }
  }
}
