# List enriched hotels

Content Enrichment API / Enrichment

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

Return a paginated array of full enriched hotels for the calling project.

Each row is the same full hotel `getEnrichedHotel` returns, built and returned synchronously. Because every row is a full build the page is hard-capped at 50 hotels.

- `Limit` above 50 is clamped to 50; for a lean roster use `listEnrichedHotelSummaries`.
- Filters: country, status, full-enrichment flag, text-enrichment state, code kind and free-text search.
- `TagIDs` and `TagName` narrow to hotels carrying all named tags; an unknown tag returns 404.
- `ExternalHotelIDs` holds up to 50 selectors, OR-ed with each other and AND-ed with every other filter.
- Only hotels belonging to your project are returned.
- 429 means the rate limit was hit; wait `Retry-After` seconds.

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

## Example request

```bash
curl -X POST 'https://api.ygo.ai/v2/project/content/listEnrichedHotels' \
  -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, `ListEnrichedHotelsRequest`

Request body for listing full enriched 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 50 elements; a longer array returns 400.

  Each item: One selector: `productid`, `giata` or `peakworkgoalid`, the last two positive integers as strings (`giata` up to 2147483647) or a 400. Sub-keys are AND-combined, so a hotel matches only when it matches every sub-key in it.

  Example:

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

  Limits: max items 50
- `Limit` (integer)

  Maximum number of hotels to return, default 50. Because each row is a full hotel build, a higher value is clamped down to 50.

  Default: `50`

  Example: `50`

  Limits: min 1
- `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 hotels carrying all of these project tags

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

#### Example request: byTagName. Restrict to hotels carrying a single tag by name

```json
{
  "TagName": "Summer Campaign",
  "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
}
```

## Responses

### 200 OK

Enriched hotels 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, `ListEnrichedHotelsResponse`

Paginated list response wrapping the full enriched hotels.

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

  The page of full enriched hotels (at most 50 per page).

  Each item: A fully enriched hotel with its identity, location, factual attributes, structured check-in / check-out times, per-locale generated texts, guest rating, images, rooms, and the project's internal tags applied to it.

  - `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`
  - `Names` (map of string to string, **required**)

    Per-locale display names keyed by BCP 47 language tag, always including en-US. Other locales appear only when a localized name has been generated.

    Example:

    ```json
    {
      "en-US": "Bahia Azul Beach Resort",
      "de-DE": "Bahia Azul Strandresort"
    }
    ```
  - `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`
  - `AccommodationType` (string, **required**)

    Accommodation kind, for example hotel, apartment, aparthotel, resort, villa, hostel, guesthouse, bed_and_breakfast, cruise_ship or holiday_village. The set of values may be extended, so read it as an open string.

    Example: `hotel`
  - `Chain` (string)

    Hotel company the property belongs to. Omitted when the hotel has no chain recorded.

    Example: `Accor`
  - `Brand` (string)

    Product line within the chain the property is marketed under. Omitted when the hotel has no brand recorded.

    Example: `Novotel`
  - `Location` (object, `Location`, **required**)

    Geographic location of the hotel.

    - `Latitude` (number (double), **required**)

      Latitude in decimal degrees.

      Example: `39.5696`
    - `Longitude` (number (double), **required**)

      Longitude in decimal degrees.

      Example: `2.6502`
    - `CountryCode` (string, **required**)

      ISO 3166-1 alpha-2 country code.

      Example: `ES`
    - `Address` (object, `Address`)

      Postal address and contact details extracted from enrichment details. Present only when address data is available.

      - `Street` (string)

        Street name and number.

        Example: `Carrer de la Mar 12`
      - `City` (string)

        City or town.

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

        Localized city display names keyed by BCP 47 language tag, present only when they have been generated. Fall back to `City`.

        Example:

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

        State, province, or region.

        Example: `Illes Balears`
      - `PostalCode` (string)

        Postal or ZIP code.

        Example: `07015`
      - `Phone` (string)

        The hotel's phone number, as its sources state it. Omitted when none is known.

        Example: `+34 971 000 000`
      - `Email` (string)

        The hotel's email address, as its sources state it. Omitted when none is known.

        Example: `info@bahia-azul.example`
  - `FactualAttributes` (array of object, `FactualAttribute`, **required**)

    Hotel-level factual attributes (amenities, facilities, grouped on-site facility families, and group header rows).

    Each item: A factual attribute. A single fact carries a scalar `Value`; a grouped facility family carries `Instances` and an empty `Value`; a group header carries `ValueType` `group`.

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

      Canonical attribute key.

      Example: `wifi`
    - `Type` (string)

      Ontology kind resolved from the attribute tree at serve time. For this surface the value is 'factual'.

      Example: `factual`
    - `Name` (map of string to string, **required**)

      Localized attribute display names keyed by BCP 47 language tag.

      Example:

      ```json
      {
        "en-US": "Free WiFi",
        "de-DE": "Kostenloses WLAN"
      }
      ```
    - `Value` (string)

      Scalar value for a single fact, empty for grouped families and headers. It carries the polarity, so always render the attribute with its `Value`, never from `Name` alone.

      Example: `true`
    - `ValueType` (string, **required**)

      How Value should be interpreted: 'boolean', 'text', or 'group' for a group header row.

      Example: `boolean`
    - `ParentKey` (string)

      Key of the parent category this attribute belongs to (used by clients as a section grouping).

      Example: `facilities_and_services`
    - `Details` (map of string to string)

      Additional free-text properties in the source language, such as description or Category; their translations are under DetailsLocalized. Omitted when empty.
    - `IsFree` (boolean, nullable)

      Whether the amenity is free of charge. true (free), false (paid), or null when unknown / not applicable.

      Example: `true`
    - `IsOnSite` (boolean)

      Whether the facility or activity is on the hotel's premises (true) or only in the surrounding area (false), for example a golf course 12 km away. Hotel facts only; omitted when not determined, never null.

      Example: `false`
    - `GTCodes` (array of string)

      DRV GlobalTypes codes for this attribute, general to specific: concept code, optional SubType refinement, then a free-of-charge qualifier. Omitted when the attribute has no mapping.

      Example:

      ```json
      [
        "GT03-POOL",
        "ST03-INSW"
      ]
      ```
    - `ValueLocalized` (map of string to string)

      Per-locale translations of the free-text Value, keyed by BCP 47 language tag; a boolean Value normally carries none. Present only when translations exist, otherwise fall back to Value.
    - `DetailsLocalized` (map of string to map of string to string)

      Per-locale translations of the free-text Details, keyed by property key, then by BCP 47 language tag. Present only when translations exist, otherwise fall back to Details.
    - `Instances` (array of object, `FactualInstance`)

      Named outlets for a grouped on-site facility family, such as each restaurant or bar. Present only for grouped families, omitted for single-fact attributes.

      Each item: One named outlet within a grouped on-site facility family.

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

        Display name of the outlet.

        Example: `La Marea`
      - `Details` (map of string to string)

        Per-outlet free-text properties, such as description or hours. Omitted when empty.
      - `DetailsLocalized` (map of string to map of string to string)

        Per-property, per-locale translations of this outlet's free-text details, keyed propertyKey then BCP 47 language tag. Fall back to `Details`; omitted when empty.
  - `POIs` (array of object, `POI`, **required**)

    Nearby points of interest with localized names and, where there is one to show, distances.

    Each item: A nearby point of interest: one place, or an area (IsArea) such as part of a town or a beach. POI data partly © OpenStreetMap contributors, available under the ODbL.

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

      Unique POI UUID. Stable identifier used as the entity id when submitting feedback about this POI.

      Example: `0192fb20-1aa2-7def-9abc-1122334455aa`
    - `Name` (map of string to string, **required**)

      Localized POI names keyed by BCP 47 language tag, always with en-US. For an area (IsArea true) it is the area's official local name, translated per locale.

      Example:

      ```json
      {
        "en-US": "Palma Cathedral",
        "de-DE": "Kathedrale von Palma"
      }
      ```
    - `Type` (string, **required**)

      POI category (e.g. landmark, beach, airport, restaurant).

      Example: `landmark`
    - `Distance` (number (double))

      Distance in Unit: meters under 1 km, else km to one decimal; for an area, to its nearest edge, its centre without an outline, or the distance its source stated. Omitted with Unit when unknown, at the hotel or InArea.

      Example: `3.2`
    - `Unit` (string)

      Unit for Distance: m for meters, km for kilometers. Present exactly when Distance is present.

      Values: `m`, `km`

      Example: `km`
    - `IsArea` (boolean)

      True for a POI that is an area rather than one place: an area of a town (a historic centre, an old town, a district, a promenade), or a beach located by its OpenStreetMap outline. Omitted when false.

      Example: `true`
    - `InArea` (boolean)

      True when the hotel lies inside the area's outline, for a beach on its sand; Distance and Unit are then omitted. Implies IsArea; not set when a stated distance is kept, omitted when false.

      Example: `true`
    - `Latitude` (number (double))

      Latitude of the POI in decimal degrees (WGS-84). For an area (IsArea) it is the area's representative point: the centroid of its outline, which can lie off a line or an irregular area, or its single point. Sent together with Longitude; both are omitted when the POI has no known position, an area that could not be located included.

      Example: `39.5675`
    - `Longitude` (number (double))

      Longitude of the POI in decimal degrees (WGS-84). Present exactly when Latitude is present.

      Example: `2.6484`
    - `Details` (map of string to string)

      Additional POI properties. Omitted when empty.
  - `CheckIn` (object, `CheckIn`)

    Earliest check-in time. The whole object is omitted when no valid time is available.

    - `From` (string)

      Earliest check-in time as a 24-hour 'HH:MM' clock string.

      Example: `15:00`
  - `CheckOut` (object, `CheckOut`)

    Latest check-out time. The whole object is omitted when no valid time is available.

    - `Until` (string)

      Latest check-out time as a 24-hour 'HH:MM' clock string.

      Example: `11:00`
  - `GeneratedTexts` (map of string to map of string to object, `GeneratedTexts`, **required**)

    Generated texts keyed by locale (BCP 47 language tag) then by template key; each value is a GeneratedTextDetail.

    Each value: 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`
  - `GuestRating` (object, `GuestRating`)

    Guest rating of the hotel: the guest review scores we hold, calibrated per platform and aggregated on a 0 to 100 scale, with category scores and summaries. Omitted when the hotel has no rating.

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

      Overall guest score from 0 to 100: the aggregate of the guest review scores we hold, each calibrated per review platform.

      Example: `93`

      Limits: min 0, max 100
    - `SubScores` (object, `GuestRatingSubScores`)

      Category scores from 0 to 100 showing how a category compares with the hotel overall. A category without data is absent, never 0; omitted when no category has data.

      - `Cleanliness` (integer)

        Score for cleanliness, 0 to 100.

        Example: `96`

        Limits: min 0, max 100
      - `Service` (integer)

        Score for staff and service, 0 to 100.

        Example: `96`

        Limits: min 0, max 100
      - `Location` (integer)

        Score for the location, 0 to 100.

        Example: `91`

        Limits: min 0, max 100
      - `Rooms` (integer)

        Score for the rooms, 0 to 100.

        Example: `95`

        Limits: min 0, max 100
      - `Food` (integer)

        Score for food and drink, 0 to 100.

        Example: `91`

        Limits: min 0, max 100
      - `Value` (integer)

        Score for value for money, 0 to 100.

        Example: `90`

        Limits: min 0, max 100
      - `Facilities` (integer)

        Score for the facilities, 0 to 100.

        Example: `93`

        Limits: min 0, max 100
    - `Texts` (map of string to object, `GuestRatingTexts`)

      AI-generated summaries of guest opinion keyed by locale (BCP 47 language tag); they quote no review. Omitted when no text has been generated.

      Each value: What guests say about the hotel in one locale: a short summary with the points most often praised and criticized.

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

        Short paragraph summarizing guest opinion of the hotel.

        Example: `Guests consistently describe their stay as a peaceful, relaxing retreat highlighted by exceptionally friendly and attentive staff. Rooms and grounds are praised for being spotless and comfortable, while the delicious breakfast and calm adults-only setting make it an ideal getaway.`
      - `Pros` (array of string)

        Up to 5 points guests praise. Omitted when there are none.

        Example:

        ```json
        [
          "Warm, attentive, and professional staff",
          "Spotless rooms and well-kept grounds",
          "Peaceful, child-free atmosphere",
          "Superb and varied breakfast spread",
          "Modern, spacious guest rooms"
        ]
        ```

        Limits: max items 5
      - `Cons` (array of string)

        Up to 3 points guests criticize. Omitted when there are none.

        Example:

        ```json
        [
          "Extra charges for some premium drinks and minibar",
          "Lunch and dinner buffets can feel repetitive to some"
        ]
        ```

        Limits: max items 3
      - `GeneratedAt` (string (date-time))

        Generation timestamp of this text (RFC3339). Omitted for an unstamped text.

        Example: `2026-11-05T18:10:57Z`
      - `Compliance` (object, `Compliance`)

        Regulatory marker envelope, present on every served text; `AIGenerated` is always `true`.

        - `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`
  - `RenderLayouts` (map of string to string)

    Optional rendering hints, not enrichment data: template key to layout hint such as `prose`, `highlights`, `roomcards` or `summary`. Only keys whose template carries a hint are included.

    Example:

    ```json
    {
      "Summary": "prose",
      "HouseRules": "highlights"
    }
    ```
  - `Images` (array of object, `Image`, **required**)

    Hotel-level images, deduplicated and sorted by category priority. An image pinned in your project (see PinnedImageID) is served first, ahead of that order.

    Each item: An enriched image with vision-derived metadata.

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

      Unique image UUID.

      Example: `0192fb20-1aa2-7def-9abc-1122334455aa`
    - `URL` (string (uri), **required**)

      Image URL.

      Example: `https://cdn.ygo.ai/hotels/bahia-azul/exterior-pool.jpg`
    - `Source` (string)

      Detected provenance of the pixels: `photo`, `render`, `illustration` or `ai_generated`. Omitted when the image carries no provenance assessment.

      Example: `photo`
    - `Category` (string)

      Vision-derived image category (e.g. exterior, room, pool, restaurant).

      Example: `exterior`
    - `Features` (array of string)

      Vision-derived feature tags depicted in the image.

      Example:

      ```json
      [
        "pool",
        "sea_view"
      ]
      ```
    - `Mood` (array of string)

      Vision-derived mood descriptors.

      Example:

      ```json
      [
        "relaxing"
      ]
      ```
    - `Tags` (array of string)

      Additional vision-derived tags.

      Example:

      ```json
      [
        "rooftop",
        "sunset"
      ]
      ```
    - `Flags` (array of string)

      Quality / content flags raised by vision analysis. Omitted when empty.
    - `AppealScore` (integer)

      Appeal score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.

      Example: `88`
    - `QualityScore` (integer)

      Technical quality score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.

      Example: `91`
    - `AppealScoreVersion` (string)

      Version stamp of the scorer that produced AppealScore, for example `app-v4`; it may name an earlier version. Absent when AppealScore is -1 or a legacy score from before stamps existed.

      Example: `app-v4`
    - `QualityScoreVersion` (string)

      Version stamp of the scorer that produced QualityScore, for example `qs-v4`; it may name an earlier version. Absent when QualityScore is -1, a legacy score, or a first-seen image's provisional score.

      Example: `qs-v4`
    - `Width` (integer)

      Image width in pixels.

      Example: `1600`
    - `Height` (integer)

      Image height in pixels.

      Example: `1067`
    - `Format` (string)

      Image format (e.g. jpeg, png, webp).

      Example: `jpeg`
    - `FileSize` (integer)

      File size in bytes.

      Example: `412000`
    - `DominantColor` (string)

      Dominant color as a hex string.

      Example: `#2E6F95`
    - `BlurHash` (string)

      BlurHash placeholder string for progressive loading.

      Example: `LKO2?U%2Tw=w]~RBVZRi};RPxuwH`
    - `FileMetadata` (object)

      What the image file itself states in its embedded IPTC/EXIF/XMP metadata: capture date and copyright notice. Omitted when the file states neither; inside it, a value the file did not state has no key.

      Example:

      ```json
      {
        "CaptureDate": "2012-06-14",
        "Copyright": "© 2012 Hotel Sol S.A."
      }
      ```

      - `CaptureDate` (string)

        Date the photograph was taken, at the precision the file stated: `2012-06-14`, `2012-06` or `2012`. It carries no time of day and no timezone.

        Example: `2012-06-14`

        Limits: pattern ^\d{4}(-\d{2}(-\d{2})?)?$
      - `Copyright` (string)

        The copyright notice the file carries, as the file wrote it. It names who to ask; it is not a machine-readable licence.

        Example: `© 2012 Hotel Sol S.A.`
    - `Descriptions` (map of string to string)

      Neutral alt text describing what the image shows, not marketing copy, keyed by BCP 47 language tag. More locales may be added after an image is first analyzed.

      Example:

      ```json
      {
        "en-US": "Rooftop infinity pool overlooking the Bay of Palma at sunset."
      }
      ```
    - `Compliance` (object, `Compliance`)

      EU AI Act Article 50(2) marker for this image. Always present with `AIGenerated` true: the category, features, mood, tags, scores and descriptions are model output, `FileMetadata` is not.

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

      People and animals seen in the image, from the closed vocabulary person, adult, child, animal. Omitted when the image carries no presence measurement.

      Each item: One person or animal seen in the image.

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

        What was seen: `person`, `adult`, `child` or `animal`.

        Example: `adult`
      - `Confidence` (number (float), `DetectionConfidence`, **required**, nullable)

        Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

        Example: `0.94`

        Limits: min 0, max 1
    - `Safety` (map of string to number (float), `DetectionConfidence`)

      Safety confidences keyed by dimension, `Inappropriate` and `OffTopic`, each between 0 and 1 or null. Omitted when the image carries no safety measurement.

      Each value: nullable. Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

      Example: `0.94 (each value)`

      Limits: each value: min 0, each value: max 1
    - `TextDetections` (array of object, `TextDetection`)

      Texts read off the image, each with its kind. Omitted when the image carries no text measurement.

      Each item: One text read off the image.

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

        The text as it appears on the image. A password or access code printed after a password label is masked.

        Example: `POOL BAR`
      - `Label` (string, **required**)

        Kind of text: `overlay`, `price`, `promotional`, `watermark`, `signage` or `document`.

        Example: `signage`
      - `Confidence` (number (float), `DetectionConfidence`, **required**, nullable)

        Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

        Example: `0.94`

        Limits: min 0, max 1
    - `FeatureDetections` (array of object, `FeatureDetection`)

      The image's features with the confidence measured for each, running parallel to `Features`. Omitted when the image carries no feature measurement.

      Each item: One feature of the image with the confidence measured for it.

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

        The feature label, from the same vocabulary as Features.

        Example: `sea_view`
      - `Confidence` (number (float), `DetectionConfidence`, **required**, nullable)

        Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

        Example: `0.94`

        Limits: min 0, max 1
    - `Nudity` (object)

      Nudity assessment: exposure score, reason and explicit flag, independent of `Safety.Inappropriate`. Omitted when the assessment did not run or the image's `Presence` shows no person.

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

        Exposure score from 0 to 100. Anchors: 20 beach or casual wear, 40 standard swimwear, 60 revealing swimwear or lingerie, 80 partial nudity, 100 explicit.

        Example: `60`

        Limits: min 0, max 100
      - `Reason` (string, **required**)

        One model-written sentence naming what drives the score, at most 240 characters. Not sanitized for markup, so escape it before rendering.

        Example: `Adult in revealing swimwear by the pool.`
      - `Explicit` (boolean, **required**)

        True from a score of 90 up. Whether a child is in the picture is answered by `Presence`, not here.

        Example: `false`
  - `PinnedImageID` (string (uuid))

    UUID of the pinned image promoted to the front of `Images`, always the first entry's ID. Omitted when no pin is in effect.

    Example: `0192fb20-1aa2-7def-9abc-1122334455aa`
  - `Rooms` (array of object, `EnrichedRoom`, **required**)

    Enriched room types belonging to this hotel.

    Each item: An enriched room type belonging to a hotel.

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

      Unique room UUID.

      Example: `0192fb30-2bb3-7abc-8def-99887766aabb`
    - `Name` (map of string to string, **required**)

      Localized room names keyed by BCP 47 language tag. Always contains en-US when a base room name exists.

      Example:

      ```json
      {
        "en-US": "Double Room Sea View",
        "de-DE": "Doppelzimmer mit Meerblick"
      }
      ```
    - `SizeSqm` (integer)

      Room size in square meters. 0 when unknown.

      Example: `26`
    - `Beddings` (array of array of object, `Bedding`)

      Bedding configurations. The outer array lists alternative configurations; each inner array lists the beds in one configuration.

      Each item: A single bed entry within a bedding configuration.

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

        Bed type. Known codes: SINGLE, TWIN, DOUBLE, QUEEN, KING, SOFA_BED, BUNK_BED, EXTRA_BED, CRIB, CHILD_BED, DAY_BED, MURPHY_BED, CHAIR_BED; older records can hold other values.

        Example: `DOUBLE`
      - `Quantity` (integer, **required**)

        Number of beds of this type.

        Example: `1`
      - `Name` (map of string to string)

        Bed type name per room Name locale (BCP 47) in en, de, fr, it, nl, es, tr or he, shown after Quantity: singular for 1, else the counted form, plural if inflected. Absent for an unknown Type or no such locale; use Type.

        Example:

        ```json
        {
          "en-US": "double bed",
          "de-DE": "Doppelbett"
        }
        ```
    - `FactualAttributes` (array of object, `FactualAttribute`, **required**)

      Room-level factual attributes.

      Each item: A factual attribute. A single fact carries a scalar `Value`; a grouped facility family carries `Instances` and an empty `Value`; a group header carries `ValueType` `group`.

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

        Canonical attribute key.

        Example: `wifi`
      - `Type` (string)

        Ontology kind resolved from the attribute tree at serve time. For this surface the value is 'factual'.

        Example: `factual`
      - `Name` (map of string to string, **required**)

        Localized attribute display names keyed by BCP 47 language tag.

        Example:

        ```json
        {
          "en-US": "Free WiFi",
          "de-DE": "Kostenloses WLAN"
        }
        ```
      - `Value` (string)

        Scalar value for a single fact, empty for grouped families and headers. It carries the polarity, so always render the attribute with its `Value`, never from `Name` alone.

        Example: `true`
      - `ValueType` (string, **required**)

        How Value should be interpreted: 'boolean', 'text', or 'group' for a group header row.

        Example: `boolean`
      - `ParentKey` (string)

        Key of the parent category this attribute belongs to (used by clients as a section grouping).

        Example: `facilities_and_services`
      - `Details` (map of string to string)

        Additional free-text properties in the source language, such as description or Category; their translations are under DetailsLocalized. Omitted when empty.
      - `IsFree` (boolean, nullable)

        Whether the amenity is free of charge. true (free), false (paid), or null when unknown / not applicable.

        Example: `true`
      - `IsOnSite` (boolean)

        Whether the facility or activity is on the hotel's premises (true) or only in the surrounding area (false), for example a golf course 12 km away. Hotel facts only; omitted when not determined, never null.

        Example: `false`
      - `GTCodes` (array of string)

        DRV GlobalTypes codes for this attribute, general to specific: concept code, optional SubType refinement, then a free-of-charge qualifier. Omitted when the attribute has no mapping.

        Example:

        ```json
        [
          "GT03-POOL",
          "ST03-INSW"
        ]
        ```
      - `ValueLocalized` (map of string to string)

        Per-locale translations of the free-text Value, keyed by BCP 47 language tag; a boolean Value normally carries none. Present only when translations exist, otherwise fall back to Value.
      - `DetailsLocalized` (map of string to map of string to string)

        Per-locale translations of the free-text Details, keyed by property key, then by BCP 47 language tag. Present only when translations exist, otherwise fall back to Details.
      - `Instances` (array of object, `FactualInstance`)

        Named outlets for a grouped on-site facility family, such as each restaurant or bar. Present only for grouped families, omitted for single-fact attributes.

        Each item: One named outlet within a grouped on-site facility family.

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

          Display name of the outlet.

          Example: `La Marea`
        - `Details` (map of string to string)

          Per-outlet free-text properties, such as description or hours. Omitted when empty.
        - `DetailsLocalized` (map of string to map of string to string)

          Per-property, per-locale translations of this outlet's free-text details, keyed propertyKey then BCP 47 language tag. Fall back to `Details`; omitted when empty.
    - `GeneratedTexts` (map of string to map of string to object, `GeneratedTexts`)

      Generated texts keyed by locale (BCP 47 language tag) then by template key; each value is a GeneratedTextDetail.

      Each value: 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`
    - `RenderLayouts` (map of string to string, **required**)

      Optional rendering hints keyed by room template namespace (empty string for bare template keys). One layout governs the whole room card.

      Example:

      ```json
      {
        "": "roomcards"
      }
      ```
    - `ExternalRoomIDs` (map of string to array of string)

      Your own identifiers for this room, omitted when it has none. Current key is `ProductRoomIDs`, sorted and included only for confident matches; several ids can map to one room.

      Example:

      ```json
      {
        "ProductRoomIDs": [
          "11824",
          "11902"
        ]
      }
      ```
    - `Images` (array of object, `Image`, **required**)

      Room-level images, deduplicated and sorted by category priority.

      Each item: An enriched image with vision-derived metadata.

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

        Unique image UUID.

        Example: `0192fb20-1aa2-7def-9abc-1122334455aa`
      - `URL` (string (uri), **required**)

        Image URL.

        Example: `https://cdn.ygo.ai/hotels/bahia-azul/exterior-pool.jpg`
      - `Source` (string)

        Detected provenance of the pixels: `photo`, `render`, `illustration` or `ai_generated`. Omitted when the image carries no provenance assessment.

        Example: `photo`
      - `Category` (string)

        Vision-derived image category (e.g. exterior, room, pool, restaurant).

        Example: `exterior`
      - `Features` (array of string)

        Vision-derived feature tags depicted in the image.

        Example:

        ```json
        [
          "pool",
          "sea_view"
        ]
        ```
      - `Mood` (array of string)

        Vision-derived mood descriptors.

        Example:

        ```json
        [
          "relaxing"
        ]
        ```
      - `Tags` (array of string)

        Additional vision-derived tags.

        Example:

        ```json
        [
          "rooftop",
          "sunset"
        ]
        ```
      - `Flags` (array of string)

        Quality / content flags raised by vision analysis. Omitted when empty.
      - `AppealScore` (integer)

        Appeal score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.

        Example: `88`
      - `QualityScore` (integer)

        Technical quality score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.

        Example: `91`
      - `AppealScoreVersion` (string)

        Version stamp of the scorer that produced AppealScore, for example `app-v4`; it may name an earlier version. Absent when AppealScore is -1 or a legacy score from before stamps existed.

        Example: `app-v4`
      - `QualityScoreVersion` (string)

        Version stamp of the scorer that produced QualityScore, for example `qs-v4`; it may name an earlier version. Absent when QualityScore is -1, a legacy score, or a first-seen image's provisional score.

        Example: `qs-v4`
      - `Width` (integer)

        Image width in pixels.

        Example: `1600`
      - `Height` (integer)

        Image height in pixels.

        Example: `1067`
      - `Format` (string)

        Image format (e.g. jpeg, png, webp).

        Example: `jpeg`
      - `FileSize` (integer)

        File size in bytes.

        Example: `412000`
      - `DominantColor` (string)

        Dominant color as a hex string.

        Example: `#2E6F95`
      - `BlurHash` (string)

        BlurHash placeholder string for progressive loading.

        Example: `LKO2?U%2Tw=w]~RBVZRi};RPxuwH`
      - `FileMetadata` (object)

        What the image file itself states in its embedded IPTC/EXIF/XMP metadata: capture date and copyright notice. Omitted when the file states neither; inside it, a value the file did not state has no key.

        Example:

        ```json
        {
          "CaptureDate": "2012-06-14",
          "Copyright": "© 2012 Hotel Sol S.A."
        }
        ```

        - `CaptureDate` (string)

          Date the photograph was taken, at the precision the file stated: `2012-06-14`, `2012-06` or `2012`. It carries no time of day and no timezone.

          Example: `2012-06-14`

          Limits: pattern ^\d{4}(-\d{2}(-\d{2})?)?$
        - `Copyright` (string)

          The copyright notice the file carries, as the file wrote it. It names who to ask; it is not a machine-readable licence.

          Example: `© 2012 Hotel Sol S.A.`
      - `Descriptions` (map of string to string)

        Neutral alt text describing what the image shows, not marketing copy, keyed by BCP 47 language tag. More locales may be added after an image is first analyzed.

        Example:

        ```json
        {
          "en-US": "Rooftop infinity pool overlooking the Bay of Palma at sunset."
        }
        ```
      - `Compliance` (object, `Compliance`)

        EU AI Act Article 50(2) marker for this image. Always present with `AIGenerated` true: the category, features, mood, tags, scores and descriptions are model output, `FileMetadata` is not.

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

        People and animals seen in the image, from the closed vocabulary person, adult, child, animal. Omitted when the image carries no presence measurement.

        Each item: One person or animal seen in the image.

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

          What was seen: `person`, `adult`, `child` or `animal`.

          Example: `adult`
        - `Confidence` (number (float), `DetectionConfidence`, **required**, nullable)

          Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

          Example: `0.94`

          Limits: min 0, max 1
      - `Safety` (map of string to number (float), `DetectionConfidence`)

        Safety confidences keyed by dimension, `Inappropriate` and `OffTopic`, each between 0 and 1 or null. Omitted when the image carries no safety measurement.

        Each value: nullable. Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

        Example: `0.94 (each value)`

        Limits: each value: min 0, each value: max 1
      - `TextDetections` (array of object, `TextDetection`)

        Texts read off the image, each with its kind. Omitted when the image carries no text measurement.

        Each item: One text read off the image.

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

          The text as it appears on the image. A password or access code printed after a password label is masked.

          Example: `POOL BAR`
        - `Label` (string, **required**)

          Kind of text: `overlay`, `price`, `promotional`, `watermark`, `signage` or `document`.

          Example: `signage`
        - `Confidence` (number (float), `DetectionConfidence`, **required**, nullable)

          Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

          Example: `0.94`

          Limits: min 0, max 1
      - `FeatureDetections` (array of object, `FeatureDetection`)

        The image's features with the confidence measured for each, running parallel to `Features`. Omitted when the image carries no feature measurement.

        Each item: One feature of the image with the confidence measured for it.

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

          The feature label, from the same vocabulary as Features.

          Example: `sea_view`
        - `Confidence` (number (float), `DetectionConfidence`, **required**, nullable)

          Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

          Example: `0.94`

          Limits: min 0, max 1
      - `Nudity` (object)

        Nudity assessment: exposure score, reason and explicit flag, independent of `Safety.Inappropriate`. Omitted when the assessment did not run or the image's `Presence` shows no person.

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

          Exposure score from 0 to 100. Anchors: 20 beach or casual wear, 40 standard swimwear, 60 revealing swimwear or lingerie, 80 partial nudity, 100 explicit.

          Example: `60`

          Limits: min 0, max 100
        - `Reason` (string, **required**)

          One model-written sentence naming what drives the score, at most 240 characters. Not sanitized for markup, so escape it before rendering.

          Example: `Adult in revealing swimwear by the pool.`
        - `Explicit` (boolean, **required**)

          True from a score of 90 up. Whether a child is in the picture is answered by `Presence`, not here.

          Example: `false`
    - `Status` (string, **required**)

      Room lifecycle status (e.g. active).

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

      Timestamp when the room record was created (RFC3339).

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

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

      Example: `2026-04-10T12:30:00Z`
  - `Tags` (array of object, `ProjectTagSummary`)

    This project's internal tags applied to the hotel (never another project's tags). 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 and display name.

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

      Unique project tag UUID.

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

      Tag display name.

      Example: `Summer Campaign`
  - `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`
  - `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`
  - `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 (at most 50 for this endpoint).

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

    Number of items skipped before this page.

    Example: `0`

##### Example: firstPage. A page of full enriched hotels

```json
{
  "Data": [
    {
      "ID": "0192fb17-5dc6-7abc-8def-123456789abc",
      "Name": "Bahia Azul Beach Resort",
      "Names": {
        "en-US": "Bahia Azul Beach Resort",
        "de-DE": "Bahia Azul Strandresort"
      },
      "ExternalHotelIDs": {
        "ProductID": "HTL-MAJ-4711",
        "Giata": "668370"
      },
      "GlobalHotelID": "ES-MALLR-K7MP2",
      "Stars": 4,
      "StarsMap": {
        "default": {
          "Stars": 4,
          "Superior": false,
          "Garni": false
        }
      },
      "AccommodationType": "resort",
      "Chain": "Meliá Hotels International",
      "Brand": "Sol by Meliá",
      "Location": {
        "Latitude": 39.5696,
        "Longitude": 2.6502,
        "CountryCode": "ES",
        "Address": {
          "Street": "Carrer de la Mar 12",
          "City": "Palma",
          "CityNames": {
            "en-US": "Palma",
            "de-DE": "Palma"
          },
          "State": "Illes Balears",
          "PostalCode": "07015",
          "Phone": "+34 971 000 000",
          "Email": "info@bahia-azul.example"
        }
      },
      "FactualAttributes": [
        {
          "Key": "wifi",
          "Type": "factual",
          "Name": {
            "en-US": "Free WiFi",
            "de-DE": "Kostenloses WLAN"
          },
          "Value": "true",
          "ValueType": "boolean",
          "ParentKey": "facilities_and_services",
          "IsFree": true,
          "GTCodes": [
            "GT03-INTE",
            "AT03-FRCH"
          ]
        }
      ],
      "POIs": [
        {
          "ID": "0192fb20-1aa2-7def-9abc-3344556677cc",
          "Name": {
            "en-US": "Es Portitxol",
            "de-DE": "Es Portitxol"
          },
          "Type": "attraction",
          "IsArea": true,
          "InArea": true
        },
        {
          "ID": "0192fb20-1aa2-7def-9abc-1122334455aa",
          "Name": {
            "en-US": "Palma Cathedral",
            "de-DE": "Kathedrale von Palma"
          },
          "Type": "landmark",
          "Distance": 3.2,
          "Unit": "km",
          "Latitude": 39.5675,
          "Longitude": 2.6484
        }
      ],
      "CheckIn": {
        "From": "15:00"
      },
      "CheckOut": {
        "Until": "11:00"
      },
      "GeneratedTexts": {
        "en-US": {
          "Summary": {
            "Text": "Set on a quiet stretch of the Bay of Palma, Bahia Azul Beach Resort pairs direct beach access with bright, contemporary rooms and a sea-view rooftop pool.",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "GuestRating": {
        "ReviewScore": 93,
        "SubScores": {
          "Cleanliness": 96,
          "Facilities": 93,
          "Food": 91,
          "Location": 91,
          "Rooms": 95,
          "Service": 96,
          "Value": 90
        },
        "Texts": {
          "en-US": {
            "Summary": "Guests consistently describe their stay as a peaceful, relaxing retreat highlighted by exceptionally friendly and attentive staff. Rooms and grounds are praised for being spotless and comfortable, while the delicious breakfast and calm adults-only setting make it an ideal getaway.",
            "Pros": [
              "Warm, attentive, and professional staff",
              "Spotless rooms and well-kept grounds",
              "Peaceful, child-free atmosphere",
              "Superb and varied breakfast spread",
              "Modern, spacious guest rooms"
            ],
            "Cons": [
              "Extra charges for some premium drinks and minibar",
              "Lunch and dinner buffets can feel repetitive to some"
            ],
            "GeneratedAt": "2026-11-05T18:10:57Z",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "RenderLayouts": {
        "Summary": "prose"
      },
      "Images": [
        {
          "ID": "0192fb20-1aa2-7def-9abc-1122334455aa",
          "URL": "https://cdn.ygo.ai/hotels/bahia-azul/exterior-pool.jpg",
          "Source": "photo",
          "Category": "exterior",
          "Features": [
            "pool",
            "sea_view"
          ],
          "Mood": [
            "relaxing"
          ],
          "Tags": [
            "rooftop",
            "sunset"
          ],
          "AppealScore": 88,
          "QualityScore": 91,
          "AppealScoreVersion": "app-v4",
          "QualityScoreVersion": "qs-v4",
          "Width": 1600,
          "Height": 1067,
          "Format": "jpeg",
          "FileSize": 412000,
          "DominantColor": "#2E6F95",
          "BlurHash": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH",
          "FileMetadata": {
            "CaptureDate": "2012-06-14",
            "Copyright": "© 2012 Hotel Sol S.A."
          },
          "Descriptions": {
            "en-US": "Rooftop infinity pool overlooking the Bay of Palma at sunset."
          },
          "Compliance": {
            "AIGenerated": true
          },
          "Presence": [
            {
              "Label": "person",
              "Confidence": 0.91
            },
            {
              "Label": "adult",
              "Confidence": 0.86
            }
          ],
          "Safety": {
            "Inappropriate": 0.02,
            "OffTopic": null
          },
          "TextDetections": [
            {
              "Content": "POOL BAR",
              "Label": "signage",
              "Confidence": 0.74
            }
          ],
          "FeatureDetections": [
            {
              "Label": "pool",
              "Confidence": 0.96
            },
            {
              "Label": "sea_view",
              "Confidence": 0.9
            }
          ]
        }
      ],
      "Rooms": [
        {
          "ID": "0192fb30-2bb3-7abc-8def-99887766aabb",
          "Name": {
            "en-US": "Double Room Sea View",
            "de-DE": "Doppelzimmer mit Meerblick"
          },
          "SizeSqm": 26,
          "Beddings": [
            [
              {
                "Type": "DOUBLE",
                "Quantity": 1,
                "Name": {
                  "en-US": "double bed",
                  "de-DE": "Doppelbett"
                }
              }
            ],
            [
              {
                "Type": "TWIN",
                "Quantity": 2,
                "Name": {
                  "en-US": "twin beds",
                  "de-DE": "Einzelbetten"
                }
              }
            ]
          ],
          "FactualAttributes": [
            {
              "Key": "air_conditioning",
              "Type": "factual",
              "Name": {
                "en-US": "Air Conditioning",
                "de-DE": "Klimaanlage"
              },
              "Value": "true",
              "ValueType": "boolean",
              "ParentKey": "room_facilities",
              "IsFree": true,
              "GTCodes": [
                "GT05-AICO",
                "AT05-FRCH"
              ]
            }
          ],
          "RenderLayouts": {
            "": "roomcards"
          },
          "ExternalRoomIDs": {
            "ProductRoomIDs": [
              "11824",
              "11902"
            ]
          },
          "Images": [],
          "Status": "active",
          "CreatedAt": "2026-03-01T08:00:00Z",
          "UpdatedAt": "2026-04-10T12:30:00Z"
        }
      ],
      "Tags": [
        {
          "ID": "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
          "Name": "Summer Campaign"
        }
      ],
      "Status": "active",
      "TextStatus": "generated",
      "CreatedAt": "2026-03-01T08:00:00Z",
      "UpdatedAt": "2026-04-12T09:15: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",
      "Names": {
        "en-US": "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
        }
      },
      "AccommodationType": "resort",
      "Chain": "Meliá Hotels International",
      "Brand": "Sol by Meliá",
      "Location": {
        "Latitude": 39.5696,
        "Longitude": 2.6502,
        "CountryCode": "ES",
        "Address": {
          "Street": "Carrer de la Mar 12",
          "City": "Palma",
          "State": "Illes Balears",
          "PostalCode": "07015"
        }
      },
      "FactualAttributes": [],
      "POIs": [],
      "GeneratedTexts": {
        "en-US": {
          "Summary": {
            "Text": "A short walk from the old town, the hotel pairs a rooftop terrace with calm, light-filled rooms.",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "GuestRating": {
        "ReviewScore": 93,
        "SubScores": {
          "Cleanliness": 96,
          "Facilities": 93,
          "Food": 91,
          "Location": 91,
          "Rooms": 95,
          "Service": 96,
          "Value": 90
        },
        "Texts": {
          "en-US": {
            "Summary": "Guests consistently describe their stay as a peaceful, relaxing retreat highlighted by exceptionally friendly and attentive staff. Rooms and grounds are praised for being spotless and comfortable, while the delicious breakfast and calm adults-only setting make it an ideal getaway.",
            "Pros": [
              "Warm, attentive, and professional staff",
              "Spotless rooms and well-kept grounds",
              "Peaceful, child-free atmosphere",
              "Superb and varied breakfast spread",
              "Modern, spacious guest rooms"
            ],
            "Cons": [
              "Extra charges for some premium drinks and minibar",
              "Lunch and dinner buffets can feel repetitive to some"
            ],
            "GeneratedAt": "2026-11-05T18:10:57Z",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "Images": [],
      "Rooms": [],
      "Status": "active",
      "TextStatus": "generated",
      "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",
      "Names": {
        "en-US": "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
        }
      },
      "AccommodationType": "resort",
      "Chain": "Meliá Hotels International",
      "Brand": "Sol by Meliá",
      "Location": {
        "Latitude": 39.5696,
        "Longitude": 2.6502,
        "CountryCode": "ES"
      },
      "FactualAttributes": [],
      "POIs": [],
      "GeneratedTexts": {
        "en-US": {
          "Summary": {
            "Text": "Set back from the promenade, the hotel offers quiet rooms, a garden pool and a short walk to the beach.",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "GuestRating": {
        "ReviewScore": 93,
        "SubScores": {
          "Cleanliness": 96,
          "Facilities": 93,
          "Food": 91,
          "Location": 91,
          "Rooms": 95,
          "Service": 96,
          "Value": 90
        },
        "Texts": {
          "en-US": {
            "Summary": "Guests consistently describe their stay as a peaceful, relaxing retreat highlighted by exceptionally friendly and attentive staff. Rooms and grounds are praised for being spotless and comfortable, while the delicious breakfast and calm adults-only setting make it an ideal getaway.",
            "Pros": [
              "Warm, attentive, and professional staff",
              "Spotless rooms and well-kept grounds",
              "Peaceful, child-free atmosphere",
              "Superb and varied breakfast spread",
              "Modern, spacious guest rooms"
            ],
            "Cons": [
              "Extra charges for some premium drinks and minibar",
              "Lunch and dinner buffets can feel repetitive to some"
            ],
            "GeneratedAt": "2026-11-05T18:10:57Z",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "Images": [],
      "Rooms": [],
      "Tags": [
        {
          "ID": "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
          "Name": "Summer Campaign"
        },
        {
          "ID": "0192fc02-2222-7abc-8def-bbbbbbbbbbbb",
          "Name": "Beachfront"
        }
      ],
      "Status": "active",
      "TextStatus": "generated",
      "CreatedAt": "2026-03-01T08:00:00Z",
      "UpdatedAt": "2026-04-12T09:15:00Z"
    }
  ],
  "Pagination": {
    "Total": 1,
    "Limit": 50,
    "Offset": 0
  }
}
```

##### Example: byTagName. A page narrowed to hotels carrying a single named tag

```json
{
  "Data": [
    {
      "ID": "0192fb17-5dc6-7abc-8def-123456789abc",
      "Name": "Bahia Azul Beach Resort",
      "Names": {
        "en-US": "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
        }
      },
      "AccommodationType": "resort",
      "Chain": "Meliá Hotels International",
      "Brand": "Sol by Meliá",
      "Location": {
        "Latitude": 39.5696,
        "Longitude": 2.6502,
        "CountryCode": "ES"
      },
      "FactualAttributes": [],
      "POIs": [],
      "GeneratedTexts": {
        "en-US": {
          "Summary": {
            "Text": "A family-run hotel in the hills, with a terrace restaurant and rooms that look out over the valley.",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "GuestRating": {
        "ReviewScore": 93,
        "SubScores": {
          "Cleanliness": 96,
          "Facilities": 93,
          "Food": 91,
          "Location": 91,
          "Rooms": 95,
          "Service": 96,
          "Value": 90
        },
        "Texts": {
          "en-US": {
            "Summary": "Guests consistently describe their stay as a peaceful, relaxing retreat highlighted by exceptionally friendly and attentive staff. Rooms and grounds are praised for being spotless and comfortable, while the delicious breakfast and calm adults-only setting make it an ideal getaway.",
            "Pros": [
              "Warm, attentive, and professional staff",
              "Spotless rooms and well-kept grounds",
              "Peaceful, child-free atmosphere",
              "Superb and varied breakfast spread",
              "Modern, spacious guest rooms"
            ],
            "Cons": [
              "Extra charges for some premium drinks and minibar",
              "Lunch and dinner buffets can feel repetitive to some"
            ],
            "GeneratedAt": "2026-11-05T18:10:57Z",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "Images": [],
      "Rooms": [],
      "Tags": [
        {
          "ID": "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
          "Name": "Summer Campaign"
        }
      ],
      "Status": "active",
      "TextStatus": "generated",
      "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",
      "Names": {
        "en-US": "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
        }
      },
      "AccommodationType": "resort",
      "Chain": "Meliá Hotels International",
      "Brand": "Sol by Meliá",
      "Location": {
        "Latitude": 39.5696,
        "Longitude": 2.6502,
        "CountryCode": "ES"
      },
      "FactualAttributes": [],
      "POIs": [],
      "GeneratedTexts": {
        "en-US": {
          "Summary": {
            "Text": "Close to the harbour, the hotel combines a sea-view breakfast room with simple, well-kept rooms.",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "GuestRating": {
        "ReviewScore": 93,
        "SubScores": {
          "Cleanliness": 96,
          "Facilities": 93,
          "Food": 91,
          "Location": 91,
          "Rooms": 95,
          "Service": 96,
          "Value": 90
        },
        "Texts": {
          "en-US": {
            "Summary": "Guests consistently describe their stay as a peaceful, relaxing retreat highlighted by exceptionally friendly and attentive staff. Rooms and grounds are praised for being spotless and comfortable, while the delicious breakfast and calm adults-only setting make it an ideal getaway.",
            "Pros": [
              "Warm, attentive, and professional staff",
              "Spotless rooms and well-kept grounds",
              "Peaceful, child-free atmosphere",
              "Superb and varied breakfast spread",
              "Modern, spacious guest rooms"
            ],
            "Cons": [
              "Extra charges for some premium drinks and minibar",
              "Lunch and dinner buffets can feel repetitive to some"
            ],
            "GeneratedAt": "2026-11-05T18:10:57Z",
            "Compliance": {
              "AIGenerated": true
            }
          }
        }
      },
      "Images": [],
      "Rooms": [],
      "Status": "active",
      "TextStatus": "generated",
      "CreatedAt": "2026-03-01T08:00:00Z",
      "UpdatedAt": "2026-04-12T09:15:00Z"
    },
    {
      "ID": "0192fb18-6ed7-7abc-8def-223456789abc",
      "Name": "Costa Verde City Hotel",
      "Names": {
        "en-US": "Costa Verde City Hotel"
      },
      "ExternalHotelIDs": {
        "ProductID": "ESVALEN0007",
        "Giata": "7654321",
        "PeakworkGoalID": "864522"
      },
      "Stars": 3,
      "StarsMap": {
        "default": {
          "Stars": 3,
          "Superior": false,
          "Garni": false
        }
      },
      "AccommodationType": "hotel",
      "Location": {
        "Latitude": 39.4699,
        "Longitude": -0.3763,
        "CountryCode": "ES"
      },
      "FactualAttributes": [],
      "POIs": [],
      "GeneratedTexts": {},
      "Images": [],
      "Rooms": [],
      "Status": "draft",
      "TextStatus": "none",
      "CreatedAt": "2026-03-04T10:30:00Z",
      "UpdatedAt": "2026-03-20T14:05:00Z"
    }
  ],
  "Pagination": {
    "Total": 2,
    "Limit": 50,
    "Offset": 0
  }
}
```

### 400 Bad Request

Bad Request: the request body failed validation.

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 50 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: invalidBody. Malformed request body

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

### 401 Unauthorized

Unauthorized: the API key is missing or invalid.

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, or does not carry the `content.catalog:read` permission this endpoint requires (`INSUFFICIENT_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: insufficientScope. Missing required scope

```json
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.catalog: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 your 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 / TagName

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

### 429 Too Many Requests

Too Many Requests: the rate limit was exceeded. `Retry-After` carries 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. Quote the `X-Trace-ID` response header 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"
  }
}
```
