# List enriched hotel summaries

Content Enrichment API / Enrichment

`POST https://api.ygo.ai/v2/project/content/listEnrichedHotelSummaries`

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.

- `Limit` defaults to 50, or to 100 when `HotelIDs` is set, and is capped at 100.
- Every filter is AND-ed with the others; `Pagination.Total` counts the hotels left after filtering.
- `HotelIDs` and `ExternalHotelIDs` take up to 100 elements each; rows keep the default order, not the order of `HotelIDs`.
- `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.
- An unknown tag returns 404.

Exact spec (OpenAPI 3.0, JSON): https://docs.ygo.ai/reference/listEnrichedHotelSummaries.json

## Example request

```bash
curl -X POST 'https://api.ygo.ai/v2/project/content/listEnrichedHotelSummaries' \
  -H "Authorization: Bearer $YGO_API_KEY" \
  -H "X-Project-ID: $YGO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "Limit": 50,
  "Offset": 0
}'
```

## Authorization

`Authorization: Bearer <key>`

Project-scoped API key

## Headers

- `X-Project-ID` (string (uuid), **required**)

  Project UUID. Required for all project-scoped endpoints.

  Example: `$YGO_PROJECT_ID`

## Request body

### application/json

Schema: object, `ListEnrichedHotelSummariesRequest`

Request body for listing the project's hotels. All fields are optional; omit the body to fetch the first page with default paging.

- `CountryCode` (string)

  Filter to hotels in this ISO 3166-1 alpha-2 country code. Omit to include all countries.

  Example: `ES`
- `Status` (string)

  Filter by the hotel's status in your project, one value (see `Status` on the rows). Any other value answers 400.

  Values: `draft`, `active`, `inactive`, `closed_temporarily`, `closed_permanently`, `removed`

  Example: `active`
- `TextStatus` (string)

  Filter by your project's text state of the hotel, one value (see `TextStatus` on the rows). Any other value answers 400.

  Values: `none`, `generating`, `generated`, `failed`

  Example: `generated`
- `IsFullyEnriched` (boolean)

  When true, restrict the list to hotels that have completed full enrichment.

  Example: `true`
- `Search` (string)

  Free-text search term matched against hotel name and related identity fields.

  Example: `beach resort`
- `CodeKind` (string)

  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` (string, deprecated)

  Deprecated: use `TextStatus`. Filter by the per-hotel generated-text state: 'enriched' (texts generated), 'enriching' (generation in progress), or 'none' (no texts yet).

  Values: `enriched`, `enriching`, `none`

  Example: `enriched`
- `TagIDs` (array of string (uuid))

  Filter to hotels carrying all of these project tags, AND-combined with `TagName`. An unknown or foreign tag returns 404.

  Example:

  ```json
  [
    "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
    "0192fc02-2222-7abc-8def-bbbbbbbbbbbb"
  ]
  ```
- `TagName` (string)

  Filter by a single project tag name, case-insensitive, AND-combined with `TagIDs`. An unknown name returns 404.

  Example: `Summer Campaign`
- `ExternalHotelIDs` (array of map of string to string)

  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.

  Each item: 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.

  Example:

  ```json
  [
    {
      "productid": "HTL-MAJ-4711"
    },
    {
      "giata": "7654321",
      "peakworkgoalid": "864522"
    }
  ]
  ```

  Limits: max items 100
- `HotelIDs` (array of string (uuid))

  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.

  Each item: One hotel UUID, as returned in a summary's ID field. Must be a valid, non-nil UUID.

  Example: `0192fb17-5dc6-7abc-8def-123456789abc (each item)`

  Limits: max items 100
- `Sort` (string)

  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.

  Values: `feedback_activity`

  Example: `feedback_activity`
- `Limit` (integer)

  Maximum number of items to return. Defaults to 50, or to 100 when HotelIDs is set, and is capped at 100.

  Example: `50`

  Limits: min 1, max 100
- `Offset` (integer)

  Number of items to skip before collecting the page. Defaults to 0.

  Default: `0`

  Example: `0`

  Limits: min 0

#### Example request: firstPage. First page with default page size

```json
{
  "Limit": 50,
  "Offset": 0
}
```

#### Example request: filtered. Filter by country, active status, and a search term

```json
{
  "CountryCode": "ES",
  "Status": "active",
  "Search": "beach resort",
  "Limit": 25,
  "Offset": 0
}
```

#### Example request: byTags. Restrict to the project's hotels carrying all of these tags

```json
{
  "TagIDs": [
    "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
    "0192fc02-2222-7abc-8def-bbbbbbbbbbbb"
  ],
  "Limit": 50,
  "Offset": 0
}
```

#### Example request: byExternalHotelID. Restrict to hotels matching either of two external-identity selectors

```json
{
  "ExternalHotelIDs": [
    {
      "productid": "HTL-MAJ-4711"
    },
    {
      "giata": "7654321",
      "peakworkgoalid": "864522"
    }
  ],
  "Limit": 50,
  "Offset": 0
}
```

#### Example request: byHotelIDs. Fetch named hotels by id in one request

```json
{
  "HotelIDs": [
    "0192fb17-5dc6-7abc-8def-123456789abc",
    "0192fb18-6ed7-7abc-8def-223456789abc",
    "0192fb19-7fe8-7abc-8def-323456789abc"
  ]
}
```

#### Example request: byFeedbackActivity. The most recent feedback activity first

```json
{
  "Sort": "feedback_activity",
  "Limit": 50,
  "Offset": 0
}
```

## Responses

### 200 OK

Project hotel roster retrieved successfully.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ListEnrichedHotelSummariesResponse`

Paginated list response wrapping the project's hotel summaries.

- `Data` (array of object, `EnrichedHotelSummary`, **required**)

  The page of enriched hotel summaries.

  Each item: 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.

  - `ID` (string (uuid), **required**)

    Unique hotel UUID.

    Example: `0192fb17-5dc6-7abc-8def-123456789abc`
  - `Name` (string, **required**)

    Normalized English (en-US) hotel display name.

    Example: `Bahia Azul Beach Resort`
  - `ExternalHotelIDs` (map of string to string)

    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:

    ```json
    {
      "ProductID": "HTL-MAJ-4711",
      "Giata": "668370",
      "PeakworkGoalID": "864521"
    }
    ```
  - `GlobalHotelID` (string)

    Cross-tenant global hotel identifier. Omitted when the hotel has no global ID assigned.

    Example: `ES-MALLR-K7MP2`
  - `Stars` (number (float), **required**)

    The hotel's default star grade (StarsMap.default.Stars); 0 when unrated.

    Example: `4`
  - `StarsMap` (map of string to object, `StarsMap`, **required**)

    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.

    Each value: 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.

    - `Stars` (number (float), **required**)

      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`

      Limits: min 0, max 10
    - `Superior` (boolean, **required**)

      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` (boolean, **required**)

      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`
  - `CountryCode` (string, **required**)

    ISO 3166-1 alpha-2 country code.

    Example: `ES`
  - `City` (string, **required**)

    City or town, derived from the hotel's address. Empty when unavailable.

    Example: `Palma`
  - `CityNames` (map of string to string)

    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:

    ```json
    {
      "en-US": "Rome",
      "de-DE": "Rom",
      "it-IT": "Roma"
    }
    ```
  - `Status` (string, **required**)

    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`.

    Values: `draft`, `active`, `inactive`, `closed_temporarily`, `closed_permanently`, `removed`

    Example: `active`
  - `TextEnrichmentStatus` (string, **required**, deprecated)

    Deprecated: use `TextStatus`. Derived per-hotel generated-text state: 'enriched' (texts generated), 'enriching' (generation in progress), or 'none' (no texts yet).

    Values: `enriched`, `enriching`, `none`

    Example: `enriched`
  - `TextStatus` (string)

    Your project's text state of the hotel, first match wins: `generating`, `failed` (latest generation failed; older texts stay), `generated` (texts held), else `none`.

    Values: `none`, `generating`, `generated`, `failed`

    Example: `generated`
  - `LastEnrichedAt` (string (date-time))

    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` (string (date-time))

    Timestamp when the hotel completed full enrichment (RFC3339). Empty when the hotel is not fully enriched.

    Example: `2026-04-12T09:15:00Z`
  - `Latitude` (number (double))

    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` (number (double))

    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` (array of object, `ProjectTagSummary`)

    This project's internal tags applied to the hotel. Present only when the hotel carries one or more; omitted otherwise.

    Each item: A reference to one of this project's internal tags applied to the hotel: the tag id, display name and optional description.

    - `ID` (string (uuid), **required**)

      Unique project tag UUID.

      Example: `0192fc01-1111-7abc-8def-aaaaaaaaaaaa`
    - `Name` (string, **required**)

      Tag display name.

      Example: `Summer Campaign`
    - `Description` (string)

      Tag description. Omitted when the tag has none.

      Example: `Hotels in the 2026 summer campaign`
  - `LastFeedbackAt` (string (date-time))

    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` (string (date-time))

    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` (array of object, `SummaryImage`)

    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.

    Each item: One image of a hotel row: its URL, size and BlurHash placeholder.

    Limits: max items 5

    - `URL` (string (uri), **required**)

      Image URL.

      Example: `https://cdn.ygo.ai/hotels/bahia-azul/exterior-pool.jpg`
    - `Width` (integer, **required**)

      Image width in pixels.

      Example: `1600`
    - `Height` (integer, **required**)

      Image height in pixels.

      Example: `1067`
    - `BlurHash` (string, **required**)

      BlurHash placeholder string for progressive loading. Empty when the image has none.

      Example: `LKO2?U%2Tw=w]~RBVZRi};RPxuwH`
  - `GeneratedTexts` (map of string to object, `SummaryGeneratedTexts`)

    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.

    - `Summary` (object, `GeneratedTextDetail`, **required**)

      One generated text for a (locale, template key) pair. Every text served here is AI-generated and therefore carries a `Compliance` marker envelope.

      - `Text` (string, **required**)

        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` (string (date-time))

        Per-text generation timestamp (RFC3339). Omitted for legacy / unstamped texts.

        Example: `2026-04-12T09:15:00Z`
      - `TextType` (string)

        Set to 'rules' for rule-based texts (policies, house rules). Omitted for marketing texts.

        Example: `rules`
      - `Compliance` (object, `Compliance`)

        Regulatory marker envelope, present whenever the text is non-empty; `AIGenerated` is always `true`. Omitted on an empty text.

        - `AIGenerated` (boolean)

          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`
  - `NearestPOIs` (array of object, `NearestPOI`)

    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.

    Each item: The nearest point of interest of one type and its distance from the hotel. POI data partly © OpenStreetMap contributors, available under the ODbL.

    - `Type` (string, **required**)

      POI category, currently `beach` or `airport`; more types may be added.

      Example: `beach`
    - `Distance` (number (double), **required**)

      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` (string, **required**)

      Unit for Distance: `m` for meters (below 1 km), `km` for kilometers.

      Values: `m`, `km`

      Example: `m`
  - `CreatedAt` (string (date-time), **required**)

    Timestamp when the hotel record was created (RFC3339).

    Example: `2026-03-01T08:00:00Z`
  - `UpdatedAt` (string (date-time), **required**)

    Timestamp when the hotel record was last updated (RFC3339).

    Example: `2026-04-12T09:15:00Z`
- `Pagination` (object, `Pagination`, **required**)

  Pagination metadata for a list response.

  - `Total` (integer, **required**)

    Total number of items matching the request across all pages.

    Example: `128`
  - `Limit` (integer, **required**)

    Maximum number of items returned in this page.

    Example: `50`
  - `Offset` (integer, **required**)

    Number of items skipped before this page.

    Example: `0`

##### Example: firstPage. A page of enriched hotel summaries

```json
{
  "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
  }
}
```

##### Example: filtered. A filtered page with a single match

```json
{
  "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
  }
}
```

##### Example: byTags. A page narrowed to hotels carrying all requested tags

```json
{
  "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
  }
}
```

##### Example: byExternalHotelID. A page narrowed to hotels matching the supplied external-identity selectors

```json
{
  "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
  }
}
```

##### Example: byHotelIDs. The named hotels that belong to the project; the third id is not one of the project's hotels and is absent

```json
{
  "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
  }
}
```

##### Example: byFeedbackActivity. 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

```json
{
  "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 Bad Request

Bad Request - Validation error or invalid request body.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `TextEnrichmentStatus`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: invalidTextEnrichmentStatus. TextEnrichmentStatus is not a recognized value

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'"
  }
}
```

##### Example: invalidTagID. A TagID is not a valid UUID

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid TagID format"
  }
}
```

##### Example: tooManyExternalHotelIDSelectors. ExternalHotelIDs has more than the allowed number of selectors

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "ExternalHotelIDs cannot contain more than 100 selectors"
  }
}
```

##### Example: invalidExternalHotelIDSelector. An ExternalHotelIDs selector has an unsupported sub-key

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "ExternalHotelIDs",
        "Message": "Unsupported ExternalHotelIDs key: hrs"
      }
    ]
  }
}
```

##### Example: invalidPeakworkGoalID. An ExternalHotelIDs selector has a peakworkgoalid that is not a positive number

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "ExternalHotelIDs",
        "Message": "ExternalHotelIDs.peakworkgoalid must be a positive number"
      }
    ]
  }
}
```

##### Example: tooManyHotelIDs. HotelIDs has more than the allowed number of ids

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "HotelIDs cannot contain more than 100 ids",
    "Fields": [
      {
        "Field": "HotelIDs",
        "Message": "HotelIDs cannot contain more than 100 ids"
      }
    ]
  }
}
```

##### Example: invalidHotelID. A HotelIDs element is not a valid, non-nil UUID

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid HotelIDs format",
    "Fields": [
      {
        "Field": "HotelIDs",
        "Message": "Invalid HotelIDs format"
      }
    ]
  }
}
```

##### Example: invalidSort. Sort is not an allowed value

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Sort must be empty or 'feedback_activity'",
    "Fields": [
      {
        "Field": "Sort",
        "Message": "Sort must be empty or 'feedback_activity'"
      }
    ]
  }
}
```

##### Example: invalidBody. Malformed request body

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid request body"
  }
}
```

### 401 Unauthorized

Unauthorized - Invalid or missing API key.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `TextEnrichmentStatus`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: invalidKey. Invalid API key

```json
{
  "Error": {
    "Code": "UNAUTHORIZED",
    "Message": "Invalid API key"
  }
}
```

### 403 Forbidden

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` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `TextEnrichmentStatus`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: insufficientScope. Missing required scope

```json
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.catalog:read"
  }
}
```

##### Example: insufficientScopeFeedbackSort. Sort feedback_activity sent without content.authoring:read

```json
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.authoring:read"
  }
}
```

##### Example: noProjectAccess. Project access required

```json
{
  "Error": {
    "Code": "FORBIDDEN",
    "Message": "Project access required"
  }
}
```

### 404 Not Found

Not Found - A requested tag does not exist or is not in the calling project's scope.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `TextEnrichmentStatus`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: tagNotFound. An unknown or foreign tag was supplied in TagIDs

```json
{
  "Error": {
    "Code": "NOT_FOUND",
    "Message": "Tag not found"
  }
}
```

### 429 Too Many Requests

Too Many Requests. The response includes a `Retry-After` header with the number of seconds to wait before retrying.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`
- `Retry-After` (integer)

  Number of seconds to wait before retrying the request. Present on 429 responses.

  Example: `30`

  Limits: min 1

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `TextEnrichmentStatus`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: rateLimited. Limit exceeded

```json
{
  "Error": {
    "Code": "RATE_LIMIT_EXCEEDED",
    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
  }
}
```

### 500 Internal Server Error

Internal Server Error - Unexpected server error. Include the X-Trace-ID header value when contacting support.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `TextEnrichmentStatus`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: internalError. Internal server error

```json
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to list hotels"
  }
}
```
