Content Enrichment API / Enrichment
List enriched hotel summaries
PageMore page actions
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.
Limitdefaults to 50, or to 100 whenHotelIDsis set, and is capped at 100.- Every filter is AND-ed with the others;
Pagination.Totalcounts the hotels left after filtering. HotelIDsandExternalHotelIDstake up to 100 elements each; rows keep the default order, not the order ofHotelIDs.Sort: 'feedback_activity'and theLastFeedbackAtandLastFeedbackReplyAtfields need thecontent.authoring:readpermission; 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-IDstring (uuid) requiredProject UUID. Required for all project-scoped endpoints.
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.
CountryCodestringFilter to hotels in this ISO 3166-1 alpha-2 country code. Omit to include all countries.
StatusstringFilter by the hotel's status in your project, one value (see
Statuson the rows). Any other value answers 400.TextStatusstringFilter by your project's text state of the hotel, one value (see
TextStatuson the rows). Any other value answers 400.IsFullyEnrichedbooleanWhen true, restrict the list to hotels that have completed full enrichment.
SearchstringFree-text search term matched against hotel name and related identity fields.
CodeKindstringFilter 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.
TextEnrichmentStatusstring deprecatedDeprecated: use
TextStatus. Filter by the per-hotel generated-text state: 'enriched' (texts generated), 'enriching' (generation in progress), or 'none' (no texts yet).TagIDsarray of string (uuid)Filter to hotels carrying all of these project tags, AND-combined with
TagName. An unknown or foreign tag returns 404.TagNamestringFilter by a single project tag name, case-insensitive, AND-combined with
TagIDs. An unknown name returns 404.ExternalHotelIDsarray of map of string to stringFilter 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.
HotelIDsarray 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.
SortstringPage 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.
LimitintegerMaximum number of items to return. Defaults to 50, or to 100 when HotelIDs is set, and is capped at 100.
OffsetintegerNumber of items to skip before collecting the page. Defaults to 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-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ListEnrichedHotelSummariesResponse
Paginated list response wrapping the project's hotel summaries.
Dataarray of object EnrichedHotelSummary requiredThe page of enriched hotel summaries.
24 fields
IDstring (uuid) requiredUnique hotel UUID.
Namestring requiredNormalized English (en-US) hotel display name.
ExternalHotelIDsmap of string to stringExternal identifiers this hotel is known by, omitted when it has none. Current keys are
ProductID,GiataandPeakworkGoalID, each only when it applies; the map is open, so read the keys you need.GlobalHotelIDstringCross-tenant global hotel identifier. Omitted when the hotel has no global ID assigned.
Starsnumber (float) requiredThe hotel's default star grade (StarsMap.default.Stars); 0 when unrated.
StarsMapmap of string to object StarsMap requiredGrades 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.
3 fields
Starsnumber (float) requiredThe 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.
Superiorboolean requiredTrue 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.
Garniboolean requiredTrue 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.
CountryCodestring requiredISO 3166-1 alpha-2 country code.
Citystring requiredCity or town, derived from the hotel's address. Empty when unavailable.
CityNamesmap of string to stringLocalized 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.
Statusstring requiredThe 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), elsedraft.TextEnrichmentStatusstring required deprecatedDeprecated: use
TextStatus. Derived per-hotel generated-text state: 'enriched' (texts generated), 'enriching' (generation in progress), or 'none' (no texts yet).TextStatusstringYour project's text state of the hotel, first match wins:
generating,failed(latest generation failed; older texts stay),generated(texts held), elsenone.LastEnrichedAtstring (date-time)Timestamp of the most recent enrichment run for this hotel (RFC3339). Empty when the hotel has never been enriched.
FullyEnrichedAtstring (date-time)Timestamp when the hotel completed full enrichment (RFC3339). Empty when the hotel is not fully enriched.
Latitudenumber (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).
Longitudenumber (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).
Tagsarray of object ProjectTagSummaryThis project's internal tags applied to the hotel. Present only when the hotel carries one or more; omitted otherwise.
3 fields
IDstring (uuid) requiredUnique project tag UUID.
Namestring requiredTag display name.
DescriptionstringTag description. Omitted when the tag has none.
LastFeedbackAtstring (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.
LastFeedbackReplyAtstring (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.
Imagesarray of object SummaryImageThe 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.
4 fields
URLstring (uri) requiredImage URL.
Widthinteger requiredImage width in pixels.
Heightinteger requiredImage height in pixels.
BlurHashstring requiredBlurHash placeholder string for progressive loading. Empty when the image has none.
GeneratedTextsmap of string to object SummaryGeneratedTextsThe 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
Summaryobject GeneratedTextDetail requiredOne generated text for a (locale, template key) pair. Every text served here is AI-generated and therefore carries a
Compliancemarker envelope.4 fields
Textstring requiredThe generated text, sanitized for display.
GeneratedAtstring (date-time)Per-text generation timestamp (RFC3339). Omitted for legacy / unstamped texts.
TextTypestringSet to 'rules' for rule-based texts (policies, house rules). Omitted for marketing texts.
Complianceobject ComplianceRegulatory marker envelope, present whenever the text is non-empty;
AIGeneratedis alwaystrue. Omitted on an empty text.1 field
AIGeneratedbooleanEU 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.
NearestPOIsarray of object NearestPOIThe nearest point of interest per type, at most one each: currently
beachandairport; a type with none is absent. Omitted when there is none or the content could not be built.3 fields
Typestring requiredPOI category, currently
beachorairport; more types may be added.Distancenumber (double) requiredDistance in Unit: meters below 1 km, else km to one decimal. 0 with Unit
mwhen the hotel lies inside the area, for a beach on its sand.Unitstring requiredUnit for Distance:
mfor meters (below 1 km),kmfor kilometers.
CreatedAtstring (date-time) requiredTimestamp when the hotel record was created (RFC3339).
UpdatedAtstring (date-time) requiredTimestamp when the hotel record was last updated (RFC3339).
Paginationobject Pagination requiredPagination metadata for a list response.
3 fields
Totalinteger requiredTotal number of items matching the request across all pages.
Limitinteger requiredMaximum number of items returned in this page.
Offsetinteger requiredNumber of items skipped before this page.
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-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
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-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
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-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
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-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
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-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Retry-AfterintegerNumber of seconds to wait before retrying the request. Present on 429 responses.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
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-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
Example response: Internal server error
{
"Error": {
"Code": "INTERNAL_ERROR",
"Message": "Failed to list hotels"
}
}