Content Enrichment API / Text Generation
Preview text
PageMore page actions
POST /v2/project/content/previewText
Synchronously report what a text-generation run would change for a selection of the project's hotels, without generating any text or writing anything. Returns, per hotel, the per-template-and-locale freshness status (missing, fresh, stale), a what-changed summary of refreshed source categories, and the number of texts a fill_missing run would generate.
Hotels are selected by HotelIDs and/or TagIDs (combined and deduplicated, capped at 100), and every selected hotel must belong to the calling project.
Example request
curl -X POST 'https://api.ygo.ai/v2/project/content/previewText' \
-H "Authorization: Bearer $YGO_API_KEY" \
-H "X-Project-ID: $YGO_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"HotelIDs": [
"0192fb17-5dc6-7abc-8def-123456789abc"
]
}'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 PreviewTextRequest
Request body for previewing a text-generation run. At least one of HotelIDs or TagIDs must be provided. HotelIDs and the hotels resolved from TagIDs are combined and deduplicated; the result is capped at 100 hotels.
HotelIDsarray of string (uuid)Explicit hotel UUIDs to preview. Each hotel must belong to the calling project; a hotel outside the project's scope returns 404. Required if TagIDs is empty.
TagIDsarray of string (uuid)Tag UUIDs. Hotels carrying ALL of the given tags (intersection) and belonging to the project are added to the selection. Required if HotelIDs is empty.
TemplateKeysarray of stringOptional subset of active template keys to preview. Each key must be an active template of the project. Empty means all active templates. Maximum 100 keys.
Localesarray of stringOptional subset of BCP 47 language tags to preview. Empty means the locales configured on the matched templates (always including en-US).
Example request: Preview all active templates for one hotel
{
"HotelIDs": [
"0192fb17-5dc6-7abc-8def-123456789abc"
]
}Example request: Preview a single template in two locales
{
"HotelIDs": [
"0192fb17-5dc6-7abc-8def-123456789abc"
],
"TemplateKeys": [
"Summary"
],
"Locales": [
"en-US",
"de-DE"
]
}Example request: Preview every project hotel carrying a tag
{
"TagIDs": [
"0192fb40-7aa1-7abc-8def-aabbccddeeff"
]
}Responses
200 OK
Preview computed successfully.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object PreviewTextResponse
Single-object response envelope wrapping the preview result.
Dataobject PreviewResult requiredThe full preview: one entry per selected hotel plus the grand total of texts that would be generated under fill_missing.
2 fields
Hotelsarray of object PreviewHotel requiredOne preview entry per selected hotel, in the resolved selection order.
5 fields
HotelIDstring (uuid) requiredHotel UUID.
HotelNamestring requiredHotel display name.
Textsarray of object PreviewText requiredPer (template, locale) freshness status rows for this hotel.
5 fields
TemplateKeystring requiredTemplate key this row refers to.
EntityTypestring requiredWhether this template applies to the hotel or to its rooms.
Localestring requiredBCP 47 language tag this row refers to.
Statusstring requiredFreshness of the stored text for this (template, locale) pair: 'missing' (not generated yet), 'fresh' (up to date), or 'stale' (generated before its source data last changed).
Countinteger requiredNumber of underlying texts this row represents that would be generated under fill_missing. For hotel templates it is 0 or 1; for room templates it is the per-room text total.
WhatChangedarray of object PreviewChange requiredSource categories that were refreshed more recently than this hotel's stored text, ordered deterministically. Empty when nothing newer changed.
2 fields
Categorystring requiredSource data category that changed.
CompletedAtstring (date-time) requiredCompletion timestamp of the latest run that refreshed this category (RFC3339).
TextsToGenerateinteger requiredNumber of texts this hotel would (re)generate under fill_missing.
TotalTextsToGenerateinteger requiredTotal number of texts across all hotels that a fill_missing run would (re)generate.
Example response: A hotel with one missing and one stale text
{
"Data": {
"Hotels": [
{
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"HotelName": "Bahia Azul Beach Resort",
"Texts": [
{
"TemplateKey": "Summary",
"EntityType": "hotel",
"Locale": "en-US",
"Status": "fresh",
"Count": 0
},
{
"TemplateKey": "Summary",
"EntityType": "hotel",
"Locale": "de-DE",
"Status": "missing",
"Count": 1
},
{
"TemplateKey": "HouseRules",
"EntityType": "hotel",
"Locale": "en-US",
"Status": "stale",
"Count": 1
},
{
"TemplateKey": "RoomDescription",
"EntityType": "room",
"Locale": "en-US",
"Status": "missing",
"Count": 3
}
],
"WhatChanged": [
{
"Category": "attributes",
"CompletedAt": "2026-06-25T14:02:00Z"
},
{
"Category": "images",
"CompletedAt": "2026-06-24T18:30:00Z"
}
],
"TextsToGenerate": 5
}
],
"TotalTextsToGenerate": 5
}
}Example response: A single template previewed in two locales
{
"Data": {
"Hotels": [
{
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"HotelName": "Bahia Azul Beach Resort",
"Texts": [
{
"TemplateKey": "Summary",
"EntityType": "hotel",
"Locale": "en-US",
"Status": "fresh",
"Count": 0
},
{
"TemplateKey": "Summary",
"EntityType": "hotel",
"Locale": "de-DE",
"Status": "missing",
"Count": 1
}
],
"WhatChanged": [],
"TextsToGenerate": 1
}
],
"TotalTextsToGenerate": 1
}
}Example response: Two tag-resolved hotels, everything already fresh
{
"Data": {
"Hotels": [
{
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"HotelName": "Bahia Azul Beach Resort",
"Texts": [
{
"TemplateKey": "Summary",
"EntityType": "hotel",
"Locale": "en-US",
"Status": "fresh",
"Count": 0
}
],
"WhatChanged": [],
"TextsToGenerate": 0
},
{
"HotelID": "0192fb18-6ed7-7abc-8def-223456789abc",
"HotelName": "Costa Verde Garden Hotel",
"Texts": [
{
"TemplateKey": "Summary",
"EntityType": "hotel",
"Locale": "en-US",
"Status": "fresh",
"Count": 0
}
],
"WhatChanged": [],
"TextsToGenerate": 0
}
],
"TotalTextsToGenerate": 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; which keys are present depends on Code. Optional.
Example response: Neither HotelIDs nor TagIDs provided
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Request validation failed",
"Fields": [
{
"Field": "HotelIDs",
"Message": "HotelIDs or TagIDs is required"
}
]
}
}Example response: One or more template keys are not active templates of the project
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "unknown or inactive template keys: Headline"
}
}Example response: Selection exceeds the per-request cap
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "selection must not exceed 100 hotels"
}
}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.generation: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.generation:write"
}
}Example response: Project access required
{
"Error": {
"Code": "FORBIDDEN",
"Message": "Project access required"
}
}404 Not Found
Not Found - One of the selected hotels 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; which keys are present depends on Code. Optional.
Example response: A selected hotel is 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: Internal server error
{
"Error": {
"Code": "INTERNAL_ERROR",
"Message": "Failed to preview text"
}
}