Content Enrichment API / Image Pins
Save hotel image pin
PageMore page actions
POST /v2/project/content/saveHotelImagePin
Pin one of a hotel's images as the first image of the served gallery. Upsert: each hotel carries at most one pin per project, and saving replaces any previous pin. The hotel must belong to the calling project (404 otherwise), the image must belong to that hotel (404 otherwise) and be active (400 otherwise), and a room-level image can be pinned only while the hotel has no hotel-level images (400 otherwise).
Example request
curl -X POST 'https://api.ygo.ai/v2/project/content/saveHotelImagePin' \
-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",
"ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa"
}'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 SaveHotelImagePinRequest
Request body for pinning a hotel image. Both ids are required, valid, non-nil UUIDs.
HotelIDstring (uuid) requiredUUID of the hotel to pin an image for. The hotel must belong to the calling project; a hotel outside the project's scope returns 404.
ImageIDstring (uuid) requiredUUID of the image to pin. The image must belong to the hotel (404 otherwise) and be active (400 otherwise). A room-level image can be pinned only while the hotel has no hotel-level images (400 otherwise).
Example request: Pin an image as the hotel's first gallery image
{
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa"
}Responses
200 OK
Image pinned successfully. Any previous pin for this 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 SaveHotelImagePinResponse
Single-object response envelope wrapping the saved pin.
Dataobject HotelImagePin requiredThe project's pinned first image for a hotel.
3 fields
HotelIDstring (uuid) requiredUUID of the hotel the pin applies to.
ImageIDstring (uuid) requiredUUID of the pinned image, as saved. Note that getEnrichedHotel echoes the pin as PinnedImageID — the id of the served image at the front of Images — which can differ from this id when the gallery serves a deduplicated equivalent of the pinned image.
CreatedBystring requiredAudit identity of who saved the pin: a user token records the user's email; a project (proj_) machine token records its project-scoped identity (e.g. 'project:<project-uuid>').
Example response: The saved pin
{
"Data": {
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
"CreatedBy": "editor@example.com"
}
}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 or not a valid UUID
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Request validation failed",
"Fields": [
{
"Field": "HotelID",
"Message": "HotelID must be a valid UUID"
}
]
}
}Example response: ImageID missing or not a valid UUID
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Request validation failed",
"Fields": [
{
"Field": "ImageID",
"Message": "ImageID must be a valid UUID"
}
]
}
}Example response: The image is not active
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Request validation failed",
"Fields": [
{
"Field": "ImageID",
"Message": "Image is not active"
}
]
}
}Example response: Room-level image while the hotel has hotel-level images
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Request validation failed",
"Fields": [
{
"Field": "ImageID",
"Message": "A room-level image cannot be pinned while the hotel has hotel-level images"
}
]
}
}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; 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 the image does not belong to the hotel.
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"
}
}Example response: Image does not exist or belongs to another hotel
{
"Error": {
"Code": "NOT_FOUND",
"Message": "Image not found for this hotel"
}
}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: Internal server error
{
"Error": {
"Code": "INTERNAL_ERROR",
"Message": "Internal error"
}
}