Content Enrichment API / Hotel Stars
Save hotel stars
PageMore page actions
POST /v2/project/content/saveHotelStars
Set your project's own star grade for one hotel. Upsert: each hotel carries at most one grade per project, and saving replaces any previous grade. This project's getEnrichedHotel, listEnrichedHotels and listEnrichedHotelSummaries then serve it as StarsMap.project and StarsMap.default, and as the top-level Stars (normally on the next read, at the latest about a minute later); no other project sees the grade. The hotel must belong to the calling project (404 otherwise), Stars must be greater than 0 and at most 10 with at most one decimal, and Superior must not be sent: a project grade has no Superior (400 otherwise).
Example request
curl -X POST 'https://api.ygo.ai/v2/project/content/saveHotelStars' \
-H "Authorization: Bearer $YGO_API_KEY" \
-H "X-Project-ID: $YGO_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"Stars": 4.5
}'Authorization
Authorization: Bearer <key>
Project-scoped API key
Headers
X-Project-IDstring (uuid) requiredProject UUID. Required for all project-scoped endpoints.
Request body required
application/json object SaveHotelStarsRequest
Request body for setting your project's star grade for a hotel. A project grade has no Superior: a body with Superior set to true or false is refused with 400 (null counts as absent).
HotelIDstring (uuid) requiredUUID of the hotel to grade. The hotel must belong to the calling project; a hotel outside the project's scope returns 404.
Starsnumber (float) requiredYour project's grade for the hotel: greater than 0 and at most 10, with at most one decimal (for example 4 or 4.5). A missing value reads as 0 and is refused.
Example request: Grade a hotel 4.5 stars
{
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"Stars": 4.5
}Example request: Grade a hotel 4 stars
{
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"Stars": 4
}Responses
200 OK
Grade saved. Any previous grade of this project for the hotel was replaced.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object SaveHotelStarsResponse
Single-object response envelope wrapping the saved grade.
Dataobject HotelStars requiredYour project's own star grade for a hotel.
2 fields
HotelIDstring (uuid) requiredUUID of the hotel the grade applies to.
Starsnumber (float) requiredThe saved grade, greater than 0 and at most 10, with at most one decimal.
Example response: The saved grade
{
"Data": {
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"Stars": 4.5
}
}Example response: The saved grade, a whole star
{
"Data": {
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"Stars": 4
}
}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; which keys are present depends on Code. Optional.
Example response: HotelID missing
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "HotelID",
"Message": "HotelID is required"
}
]
}
}Example response: HotelID is not a valid UUID
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Invalid HotelID format"
}
}Example response: Superior sent: a project grade has no Superior
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "A project grade has no Superior",
"Fields": [
{
"Field": "Superior",
"Message": "A project grade has no Superior"
}
]
}
}Example response: Malformed request body
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Invalid request body"
}
}Example response: Stars missing, below 0.1, above 10, or snapping to 0
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Stars must be greater than 0 and at most 10, with at most one decimal",
"Fields": [
{
"Field": "Stars",
"Code": "OUT_OF_RANGE",
"Message": "Stars must be greater than 0 and at most 10, with at most one decimal",
"Params": {
"Min": 0.1,
"Max": 10
}
}
]
}
}Example response: Stars with more than one decimal (no field code)
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Stars must be greater than 0 and at most 10, with at most one decimal",
"Fields": [
{
"Field": "Stars",
"Message": "Stars must be greater than 0 and at most 10, with at most one decimal"
}
]
}
}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; which keys are present depends on Code. Optional.
Example response: Invalid API key
{
"Error": {
"Code": "UNAUTHORIZED",
"Message": "Invalid API key"
}
}403 Forbidden
Forbidden - Valid API key but insufficient permissions for this operation. Also returned with code INSUFFICIENT_SCOPE when the API key does not carry the content.catalog:write permission this endpoint requires.
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; which keys are present depends on Code. Optional.
Example response: Missing required scope
{
"Error": {
"Code": "INSUFFICIENT_SCOPE",
"Message": "token lacks scope content.catalog:write"
}
}Example response: Project access required
{
"Error": {
"Code": "FORBIDDEN",
"Message": "Project access required"
}
}404 Not Found
Not Found - The hotel is not in the calling project's scope, or HotelID is the all-zeros UUID.
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; which keys are present depends on Code. Optional.
Example response: Hotel not in the project
{
"Error": {
"Code": "NOT_FOUND",
"Message": "Hotel 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; which keys are present depends 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; which keys are present depends on Code. Optional.
Example response: The grade could not be saved
{
"Error": {
"Code": "INTERNAL_ERROR",
"Message": "Failed to save project hotel stars"
}
}Example response: Hotel membership could not be checked
{
"Error": {
"Code": "INTERNAL_ERROR",
"Message": "Failed to verify hotel access"
}
}