Content Enrichment API / Enrichment
List enriched hotels
PageMore page actions
POST /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.
Limitabove 50 is clamped to 50; for a lean roster uselistEnrichedHotelSummaries.- Filters: country, status, full-enrichment flag, text-enrichment state, code kind and free-text search.
TagIDsandTagNamenarrow to hotels carrying all named tags; an unknown tag returns 404.ExternalHotelIDsholds 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-Afterseconds.
Example request
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-IDstring (uuid) requiredProject UUID. Required for all project-scoped endpoints.
Request body
application/json object ListEnrichedHotelsRequest
Request body for listing full enriched 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 50 elements; a longer array returns 400.
LimitintegerMaximum number of hotels to return, default 50. Because each row is a full hotel build, a higher value is clamped down to 50.
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 hotels carrying all of these project tags
{
"TagIDs": [
"0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
"0192fc02-2222-7abc-8def-bbbbbbbbbbbb"
],
"Limit": 50,
"Offset": 0
}Example request: Restrict to hotels carrying a single tag by name
{
"TagName": "Summer Campaign",
"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
}Responses
200 OK
Enriched hotels retrieved successfully.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ListEnrichedHotelsResponse
Paginated list response wrapping the full enriched hotels.
Dataarray of object EnrichedHotel requiredThe page of full enriched hotels (at most 50 per page).
26 fields
IDstring (uuid) requiredUnique hotel UUID.
Namestring requiredNormalized English (en-US) hotel display name.
Namesmap of string to string requiredPer-locale display names keyed by BCP 47 language tag, always including en-US. Other locales appear only when a localized name has been generated.
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.
AccommodationTypestring requiredAccommodation 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.
ChainstringHotel company the property belongs to. Omitted when the hotel has no chain recorded.
BrandstringProduct line within the chain the property is marketed under. Omitted when the hotel has no brand recorded.
Locationobject Location requiredGeographic location of the hotel.
4 fields
Latitudenumber (double) requiredLatitude in decimal degrees.
Longitudenumber (double) requiredLongitude in decimal degrees.
CountryCodestring requiredISO 3166-1 alpha-2 country code.
Addressobject AddressPostal address and contact details extracted from enrichment details. Present only when address data is available.
7 fields
StreetstringStreet name and number.
CitystringCity or town.
CityNamesmap of string to stringLocalized city display names keyed by BCP 47 language tag, present only when they have been generated. Fall back to
City.StatestringState, province, or region.
PostalCodestringPostal or ZIP code.
PhonestringThe hotel's phone number, as its sources state it. Omitted when none is known.
EmailstringThe hotel's email address, as its sources state it. Omitted when none is known.
FactualAttributesarray of object FactualAttribute requiredHotel-level factual attributes (amenities, facilities, grouped on-site facility families, and group header rows).
13 fields
Keystring requiredCanonical attribute key.
TypestringOntology kind resolved from the attribute tree at serve time. For this surface the value is 'factual'.
Namemap of string to string requiredLocalized attribute display names keyed by BCP 47 language tag.
ValuestringScalar value for a single fact, empty for grouped families and headers. It carries the polarity, so always render the attribute with its
Value, never fromNamealone.ValueTypestring requiredHow Value should be interpreted: 'boolean', 'text', or 'group' for a group header row.
ParentKeystringKey of the parent category this attribute belongs to (used by clients as a section grouping).
Detailsmap of string to stringAdditional free-text properties in the source language, such as description or Category; their translations are under DetailsLocalized. Omitted when empty.
IsFreeboolean nullableWhether the amenity is free of charge. true (free), false (paid), or null when unknown / not applicable.
IsOnSitebooleanWhether 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.
GTCodesarray of stringDRV 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.
ValueLocalizedmap of string to stringPer-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.
DetailsLocalizedmap of string to map of string to stringPer-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.
Instancesarray of object FactualInstanceNamed outlets for a grouped on-site facility family, such as each restaurant or bar. Present only for grouped families, omitted for single-fact attributes.
3 fields
Namestring requiredDisplay name of the outlet.
Detailsmap of string to stringPer-outlet free-text properties, such as description or hours. Omitted when empty.
DetailsLocalizedmap of string to map of string to stringPer-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.
POIsarray of object POI requiredNearby points of interest with localized names and, where there is one to show, distances.
10 fields
IDstring (uuid) requiredUnique POI UUID. Stable identifier used as the entity id when submitting feedback about this POI.
Namemap of string to string requiredLocalized 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.
Typestring requiredPOI category (e.g. landmark, beach, airport, restaurant).
Distancenumber (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.
UnitstringUnit for Distance: m for meters, km for kilometers. Present exactly when Distance is present.
IsAreabooleanTrue 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.
InAreabooleanTrue 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.
Latitudenumber (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.
Longitudenumber (double)Longitude of the POI in decimal degrees (WGS-84). Present exactly when Latitude is present.
Detailsmap of string to stringAdditional POI properties. Omitted when empty.
CheckInobject CheckInEarliest check-in time. The whole object is omitted when no valid time is available.
1 field
FromstringEarliest check-in time as a 24-hour 'HH:MM' clock string.
CheckOutobject CheckOutLatest check-out time. The whole object is omitted when no valid time is available.
1 field
UntilstringLatest check-out time as a 24-hour 'HH:MM' clock string.
GeneratedTextsmap of string to map of string to object GeneratedTexts requiredGenerated texts keyed by locale (BCP 47 language tag) then by template key; each value is a GeneratedTextDetail.
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.
GuestRatingobject GuestRatingGuest 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.
3 fields
ReviewScoreinteger requiredOverall guest score from 0 to 100: the aggregate of the guest review scores we hold, each calibrated per review platform.
SubScoresobject GuestRatingSubScoresCategory 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.
7 fields
CleanlinessintegerScore for cleanliness, 0 to 100.
ServiceintegerScore for staff and service, 0 to 100.
LocationintegerScore for the location, 0 to 100.
RoomsintegerScore for the rooms, 0 to 100.
FoodintegerScore for food and drink, 0 to 100.
ValueintegerScore for value for money, 0 to 100.
FacilitiesintegerScore for the facilities, 0 to 100.
Textsmap of string to object GuestRatingTextsAI-generated summaries of guest opinion keyed by locale (BCP 47 language tag); they quote no review. Omitted when no text has been generated.
5 fields
Summarystring requiredShort paragraph summarizing guest opinion of the hotel.
Prosarray of stringUp to 5 points guests praise. Omitted when there are none.
Consarray of stringUp to 3 points guests criticize. Omitted when there are none.
GeneratedAtstring (date-time)Generation timestamp of this text (RFC3339). Omitted for an unstamped text.
Complianceobject ComplianceRegulatory marker envelope, present on every served text;
AIGeneratedis alwaystrue.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.
RenderLayoutsmap of string to stringOptional rendering hints, not enrichment data: template key to layout hint such as
prose,highlights,roomcardsorsummary. Only keys whose template carries a hint are included.Imagesarray of object Image requiredHotel-level images, deduplicated and sorted by category priority. An image pinned in your project (see PinnedImageID) is served first, ahead of that order.
26 fields
IDstring (uuid) requiredUnique image UUID.
URLstring (uri) requiredImage URL.
SourcestringDetected provenance of the pixels:
photo,render,illustrationorai_generated. Omitted when the image carries no provenance assessment.CategorystringVision-derived image category (e.g. exterior, room, pool, restaurant).
Featuresarray of stringVision-derived feature tags depicted in the image.
Moodarray of stringVision-derived mood descriptors.
Tagsarray of stringAdditional vision-derived tags.
Flagsarray of stringQuality / content flags raised by vision analysis. Omitted when empty.
AppealScoreintegerAppeal 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.
QualityScoreintegerTechnical 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.
AppealScoreVersionstringVersion 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.QualityScoreVersionstringVersion 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.WidthintegerImage width in pixels.
HeightintegerImage height in pixels.
FormatstringImage format (e.g. jpeg, png, webp).
FileSizeintegerFile size in bytes.
DominantColorstringDominant color as a hex string.
BlurHashstringBlurHash placeholder string for progressive loading.
FileMetadataobjectWhat 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.
2 fields
CaptureDatestringDate the photograph was taken, at the precision the file stated:
2012-06-14,2012-06or2012. It carries no time of day and no timezone.CopyrightstringThe copyright notice the file carries, as the file wrote it. It names who to ask; it is not a machine-readable licence.
Descriptionsmap of string to stringNeutral 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.
Complianceobject ComplianceEU AI Act Article 50(2) marker for this image. Always present with
AIGeneratedtrue: the category, features, mood, tags, scores and descriptions are model output,FileMetadatais not.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.
Presencearray of object PresenceDetectionPeople and animals seen in the image, from the closed vocabulary person, adult, child, animal. Omitted when the image carries no presence measurement.
2 fields
Labelstring requiredWhat was seen:
person,adult,childoranimal.Confidencenumber (float) DetectionConfidence required nullableConfidence 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.
Safetymap of string to number (float) DetectionConfidenceSafety confidences keyed by dimension,
InappropriateandOffTopic, each between 0 and 1 or null. Omitted when the image carries no safety measurement.TextDetectionsarray of object TextDetectionTexts read off the image, each with its kind. Omitted when the image carries no text measurement.
3 fields
Contentstring requiredThe text as it appears on the image. A password or access code printed after a password label is masked.
Labelstring requiredKind of text:
overlay,price,promotional,watermark,signageordocument.Confidencenumber (float) DetectionConfidence required nullableConfidence 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.
FeatureDetectionsarray of object FeatureDetectionThe image's features with the confidence measured for each, running parallel to
Features. Omitted when the image carries no feature measurement.2 fields
Labelstring requiredThe feature label, from the same vocabulary as Features.
Confidencenumber (float) DetectionConfidence required nullableConfidence 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.
NudityobjectNudity assessment: exposure score, reason and explicit flag, independent of
Safety.Inappropriate. Omitted when the assessment did not run or the image'sPresenceshows no person.3 fields
Scoreinteger requiredExposure score from 0 to 100. Anchors: 20 beach or casual wear, 40 standard swimwear, 60 revealing swimwear or lingerie, 80 partial nudity, 100 explicit.
Reasonstring requiredOne model-written sentence naming what drives the score, at most 240 characters. Not sanitized for markup, so escape it before rendering.
Explicitboolean requiredTrue from a score of 90 up. Whether a child is in the picture is answered by
Presence, not here.
PinnedImageIDstring (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.Roomsarray of object EnrichedRoom requiredEnriched room types belonging to this hotel.
12 fields
IDstring (uuid) requiredUnique room UUID.
Namemap of string to string requiredLocalized room names keyed by BCP 47 language tag. Always contains en-US when a base room name exists.
SizeSqmintegerRoom size in square meters. 0 when unknown.
Beddingsarray of array of object BeddingBedding configurations. The outer array lists alternative configurations; each inner array lists the beds in one configuration.
3 fields
Typestring requiredBed 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.
Quantityinteger requiredNumber of beds of this type.
Namemap of string to stringBed 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.
FactualAttributesarray of object FactualAttribute requiredRoom-level factual attributes.
13 fields
Keystring requiredCanonical attribute key.
TypestringOntology kind resolved from the attribute tree at serve time. For this surface the value is 'factual'.
Namemap of string to string requiredLocalized attribute display names keyed by BCP 47 language tag.
ValuestringScalar value for a single fact, empty for grouped families and headers. It carries the polarity, so always render the attribute with its
Value, never fromNamealone.ValueTypestring requiredHow Value should be interpreted: 'boolean', 'text', or 'group' for a group header row.
ParentKeystringKey of the parent category this attribute belongs to (used by clients as a section grouping).
Detailsmap of string to stringAdditional free-text properties in the source language, such as description or Category; their translations are under DetailsLocalized. Omitted when empty.
IsFreeboolean nullableWhether the amenity is free of charge. true (free), false (paid), or null when unknown / not applicable.
IsOnSitebooleanWhether 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.
GTCodesarray of stringDRV 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.
ValueLocalizedmap of string to stringPer-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.
DetailsLocalizedmap of string to map of string to stringPer-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.
Instancesarray of object FactualInstanceNamed outlets for a grouped on-site facility family, such as each restaurant or bar. Present only for grouped families, omitted for single-fact attributes.
3 fields
Namestring requiredDisplay name of the outlet.
Detailsmap of string to stringPer-outlet free-text properties, such as description or hours. Omitted when empty.
DetailsLocalizedmap of string to map of string to stringPer-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.
GeneratedTextsmap of string to map of string to object GeneratedTextsGenerated texts keyed by locale (BCP 47 language tag) then by template key; each value is a GeneratedTextDetail.
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.
RenderLayoutsmap of string to string requiredOptional rendering hints keyed by room template namespace (empty string for bare template keys). One layout governs the whole room card.
ExternalRoomIDsmap of string to array of stringYour 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.Imagesarray of object Image requiredRoom-level images, deduplicated and sorted by category priority.
26 fields
IDstring (uuid) requiredUnique image UUID.
URLstring (uri) requiredImage URL.
SourcestringDetected provenance of the pixels:
photo,render,illustrationorai_generated. Omitted when the image carries no provenance assessment.CategorystringVision-derived image category (e.g. exterior, room, pool, restaurant).
Featuresarray of stringVision-derived feature tags depicted in the image.
Moodarray of stringVision-derived mood descriptors.
Tagsarray of stringAdditional vision-derived tags.
Flagsarray of stringQuality / content flags raised by vision analysis. Omitted when empty.
AppealScoreintegerAppeal 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.
QualityScoreintegerTechnical 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.
AppealScoreVersionstringVersion 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.QualityScoreVersionstringVersion 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.WidthintegerImage width in pixels.
HeightintegerImage height in pixels.
FormatstringImage format (e.g. jpeg, png, webp).
FileSizeintegerFile size in bytes.
DominantColorstringDominant color as a hex string.
BlurHashstringBlurHash placeholder string for progressive loading.
FileMetadataobjectWhat 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.
2 fields
CaptureDatestringDate the photograph was taken, at the precision the file stated:
2012-06-14,2012-06or2012. It carries no time of day and no timezone.CopyrightstringThe copyright notice the file carries, as the file wrote it. It names who to ask; it is not a machine-readable licence.
Descriptionsmap of string to stringNeutral 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.
Complianceobject ComplianceEU AI Act Article 50(2) marker for this image. Always present with
AIGeneratedtrue: the category, features, mood, tags, scores and descriptions are model output,FileMetadatais not.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.
Presencearray of object PresenceDetectionPeople and animals seen in the image, from the closed vocabulary person, adult, child, animal. Omitted when the image carries no presence measurement.
2 fields
Labelstring requiredWhat was seen:
person,adult,childoranimal.Confidencenumber (float) DetectionConfidence required nullableConfidence 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.
Safetymap of string to number (float) DetectionConfidenceSafety confidences keyed by dimension,
InappropriateandOffTopic, each between 0 and 1 or null. Omitted when the image carries no safety measurement.TextDetectionsarray of object TextDetectionTexts read off the image, each with its kind. Omitted when the image carries no text measurement.
3 fields
Contentstring requiredThe text as it appears on the image. A password or access code printed after a password label is masked.
Labelstring requiredKind of text:
overlay,price,promotional,watermark,signageordocument.Confidencenumber (float) DetectionConfidence required nullableConfidence 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.
FeatureDetectionsarray of object FeatureDetectionThe image's features with the confidence measured for each, running parallel to
Features. Omitted when the image carries no feature measurement.2 fields
Labelstring requiredThe feature label, from the same vocabulary as Features.
Confidencenumber (float) DetectionConfidence required nullableConfidence 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.
NudityobjectNudity assessment: exposure score, reason and explicit flag, independent of
Safety.Inappropriate. Omitted when the assessment did not run or the image'sPresenceshows no person.3 fields
Scoreinteger requiredExposure score from 0 to 100. Anchors: 20 beach or casual wear, 40 standard swimwear, 60 revealing swimwear or lingerie, 80 partial nudity, 100 explicit.
Reasonstring requiredOne model-written sentence naming what drives the score, at most 240 characters. Not sanitized for markup, so escape it before rendering.
Explicitboolean requiredTrue from a score of 90 up. Whether a child is in the picture is answered by
Presence, not here.
Statusstring requiredRoom lifecycle status (e.g. active).
CreatedAtstring (date-time) requiredTimestamp when the room record was created (RFC3339).
UpdatedAtstring (date-time) requiredTimestamp when the room record was last updated (RFC3339).
Tagsarray of object ProjectTagSummaryThis project's internal tags applied to the hotel (never another project's tags). Present only when the hotel carries one or more; omitted otherwise.
2 fields
IDstring (uuid) requiredUnique project tag UUID.
Namestring requiredTag display name.
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.TextStatusstringYour project's text state of the hotel, first match wins:
generating,failed(latest generation failed; older texts stay),generated(texts held), elsenone.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 (at most 50 for this endpoint).
Offsetinteger requiredNumber of items skipped before this page.
Example response: A page of full enriched hotels
{
"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 response: A filtered page with a single match
{
"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 response: A page narrowed to hotels carrying all requested tags
{
"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 response: A page narrowed to hotels carrying a single named tag
{
"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 response: A page narrowed to hotels matching the supplied external-identity selectors
{
"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-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 50 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: Malformed request body
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Invalid request body"
}
}401 Unauthorized
Unauthorized: the API key is missing or invalid.
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, or does not carry the content.catalog:read permission this endpoint requires (INSUFFICIENT_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: Missing required scope
{
"Error": {
"Code": "INSUFFICIENT_SCOPE",
"Message": "token lacks scope content.catalog: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 your 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 / TagName
{
"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-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. Quote the X-Trace-ID response header 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"
}
}