API docs
Book a demo

Content Enrichment API / Enrichment

List enriched hotel summaries

Page

POST /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.

Example request

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 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
    [
      "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
    [
      {
        "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: First page with default page size
{
  "Limit": 50,
  "Offset": 0
}
Example request: Filter by country, active status, and a search term
{
  "CountryCode": "ES",
  "Status": "active",
  "Search": "beach resort",
  "Limit": 25,
  "Offset": 0
}
Example request: Restrict to the project's hotels carrying all of these tags
{
  "TagIDs": [
    "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
    "0192fc02-2222-7abc-8def-bbbbbbbbbbbb"
  ],
  "Limit": 50,
  "Offset": 0
}
Example request: Restrict to hotels matching either of two external-identity selectors
{
  "ExternalHotelIDs": [
    {
      "productid": "HTL-MAJ-4711"
    },
    {
      "giata": "7654321",
      "peakworkgoalid": "864522"
    }
  ],
  "Limit": 50,
  "Offset": 0
}
Example request: Fetch named hotels by id in one request
{
  "HotelIDs": [
    "0192fb17-5dc6-7abc-8def-123456789abc",
    "0192fb18-6ed7-7abc-8def-223456789abc",
    "0192fb19-7fe8-7abc-8def-323456789abc"
  ]
}
Example request: The most recent feedback activity first
{
  "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

Body

application/json 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.

    24 fields
    • 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
      {
        "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.

      3 fields
      • 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
      {
        "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.

      3 fields
      • 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
      4 fields
      • 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.

      1 field
      • 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.

        4 fields
        • 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.

          1 field
          • 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.

      3 fields
      • 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.

    3 fields
    • 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 response: A page of enriched hotel summaries
{
  "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 response: A filtered page with a single match
{
  "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 response: A page narrowed to hotels carrying all requested tags
{
  "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 response: A page narrowed to hotels matching the supplied external-identity selectors
{
  "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 response: The named hotels that belong to the project; the third id is not one of the project's hotels and is absent
{
  "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 response: 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
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: TextEnrichmentStatus is not a recognized value
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "TextEnrichmentStatus must be 'enriched', 'enriching', or 'none'"
  }
}
Example response: A TagID is not a valid UUID
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid TagID format"
  }
}
Example response: ExternalHotelIDs has more than the allowed number of selectors
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "ExternalHotelIDs cannot contain more than 100 selectors"
  }
}
Example response: An ExternalHotelIDs selector has an unsupported sub-key
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "ExternalHotelIDs",
        "Message": "Unsupported ExternalHotelIDs key: hrs"
      }
    ]
  }
}
Example response: An ExternalHotelIDs selector has a peakworkgoalid that is not a positive number
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "ExternalHotelIDs",
        "Message": "ExternalHotelIDs.peakworkgoalid must be a positive number"
      }
    ]
  }
}
Example response: HotelIDs has more than the allowed number of ids
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "HotelIDs cannot contain more than 100 ids",
    "Fields": [
      {
        "Field": "HotelIDs",
        "Message": "HotelIDs cannot contain more than 100 ids"
      }
    ]
  }
}
Example response: A HotelIDs element is not a valid, non-nil UUID
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid HotelIDs format",
    "Fields": [
      {
        "Field": "HotelIDs",
        "Message": "Invalid HotelIDs format"
      }
    ]
  }
}
Example response: Sort is not an allowed value
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Sort must be empty or 'feedback_activity'",
    "Fields": [
      {
        "Field": "Sort",
        "Message": "Sort must be empty or 'feedback_activity'"
      }
    ]
  }
}
Example response: Malformed request body
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Invalid API key
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Missing required scope
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.catalog:read"
  }
}
Example response: Sort feedback_activity sent without content.authoring:read
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.authoring:read"
  }
}
Example response: Project access required
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: An unknown or foreign tag was supplied in TagIDs
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Limit exceeded
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Internal server error
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to list hotels"
  }
}