Content Enrichment API / Templates
List text templates
PageMore page actions
POST /v2/project/content/listTextTemplates
Return the text templates configured for the calling project, ordered by template key.
Text templates control the generated texts produced during enrichment. Each template targets a hotel or a room and carries a default authoring instruction with optional per-locale overrides. Results can be filtered by lifecycle status and by target entity type, and are paginated.
Example request
curl -X POST 'https://api.ygo.ai/v2/project/content/listTextTemplates' \
-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 ListTextTemplatesRequest
Request body for listing text templates. All fields are optional; an empty body returns the first page of all templates.
StatusstringFilter by lifecycle status. When omitted, templates of every status are returned.
EntityTypestringFilter by the entity a template targets: 'hotel' for hotel-level texts, 'room' for room-level texts. When omitted, both kinds are returned.
IncludeStatsbooleanWhen true, each returned template includes a UsageStats object summarizing how many generated texts use it. Defaults to false.
LimitintegerMaximum number of templates to return. Defaults to 50 and is capped at 100.
OffsetintegerNumber of templates to skip for pagination. Defaults to 0.
Example request: List all templates (default pagination)
{
"Limit": 50,
"Offset": 0
}Example request: Active hotel templates only, with usage stats
{
"Status": "active",
"EntityType": "hotel",
"IncludeStats": true,
"Limit": 50,
"Offset": 0
}Responses
200 OK
Text templates retrieved successfully.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ListTextTemplatesResponse
Paginated list response wrapping the project's text templates.
Dataarray of object TextTemplate requiredThe text templates for this page, ordered by template key.
13 fields
IDstring (uuid) requiredUnique template UUID.
ProjectIDstring (uuid) requiredUUID of the project that owns this template.
TemplateKeystring requiredStable key identifying the template within the project. The generated text for this template is stored under this key (e.g. 'summary', 'room_description'). A key may be namespaced with a leading 'group.' prefix to define a variant within a template group.
NamestringHuman-readable template name for display. May be empty.
EntityTypestring requiredWhether the template produces a hotel-level text or a room-level text.
DescriptionstringFree-text note describing what the template is for. May be empty.
Instructionstring requiredDefault authoring instruction that guides text generation when no locale-specific override applies.
LocaleInstructionsmap of string to string requiredPer-locale authoring instructions keyed by BCP 47 language tag (e.g. 'de-DE'). When a locale has an entry here, it overrides the default Instruction for that locale; otherwise the default Instruction is used. An empty object means no per-locale overrides.
Statusstring requiredLifecycle status. Only 'active' templates are used during text generation.
RenderLayoutstringOptional rendering hint suggesting how a client should display this template's generated text. Empty when no hint is set.
UsageStatsobject TemplateUsageStatsAggregated usage counts for a template, included only when IncludeStats is true in the request.
3 fields
TextCountintegerTotal number of generated texts that use this template across the project.
HotelCountintegerNumber of distinct hotels that have at least one generated text from this template.
LastGeneratedAtstring (date-time) nullableTimestamp of the most recent text generated from this template (RFC3339). Null when the template has never been used.
CreatedAtstring (date-time) requiredTimestamp when the template was created (RFC3339).
UpdatedAtstring (date-time) requiredTimestamp when the template was last updated (RFC3339).
Paginationobject Pagination requiredPagination metadata for a list response.
3 fields
Totalinteger requiredTotal number of templates matching the request, across all pages.
Limitinteger requiredMaximum number of items returned in this page.
Offsetinteger requiredNumber of items skipped before this page.
Example response: A project's hotel and room templates
{
"Data": [
{
"ID": "0192fb40-1aa2-7def-9abc-1122334455aa",
"ProjectID": "0192fb00-0000-7000-8000-000000000001",
"TemplateKey": "summary",
"Name": "Hotel Summary",
"EntityType": "hotel",
"Description": "Short marketing summary shown at the top of the hotel page.",
"Instruction": "Write a concise, factual two-sentence summary highlighting the hotel's location, standout amenity, and overall character. Avoid superlatives.",
"LocaleInstructions": {
"de-DE": "Schreibe eine sachliche Zusammenfassung in zwei Saetzen und verwende die Sie-Form."
},
"Status": "active",
"RenderLayout": "prose",
"CreatedAt": "2026-03-01T08:00:00Z",
"UpdatedAt": "2026-04-10T12:30:00Z"
},
{
"ID": "0192fb40-2bb3-7def-9abc-2233445566bb",
"ProjectID": "0192fb00-0000-7000-8000-000000000001",
"TemplateKey": "room_description",
"Name": "Room Description",
"EntityType": "room",
"Description": "Per-room descriptive paragraph used on room cards.",
"Instruction": "Describe the room in one short paragraph: size, bedding, view, and the most notable in-room features. Keep it neutral and concrete.",
"LocaleInstructions": {},
"Status": "active",
"RenderLayout": "roomcards",
"CreatedAt": "2026-03-01T08:00:00Z",
"UpdatedAt": "2026-03-01T08:00:00Z"
}
],
"Pagination": {
"Total": 2,
"Limit": 50,
"Offset": 0
}
}Example response: Active hotel templates with usage statistics
{
"Data": [
{
"ID": "0192fb40-1aa2-7def-9abc-1122334455aa",
"ProjectID": "0192fb00-0000-7000-8000-000000000001",
"TemplateKey": "summary",
"Name": "Hotel Summary",
"EntityType": "hotel",
"Description": "Short marketing summary shown at the top of the hotel page.",
"Instruction": "Write a concise, factual two-sentence summary highlighting the hotel's location, standout amenity, and overall character. Avoid superlatives.",
"LocaleInstructions": {
"de-DE": "Schreibe eine sachliche Zusammenfassung in zwei Saetzen und verwende die Sie-Form."
},
"Status": "active",
"RenderLayout": "prose",
"CreatedAt": "2026-03-01T08:00:00Z",
"UpdatedAt": "2026-04-10T12:30:00Z",
"UsageStats": {
"TextCount": 1240,
"HotelCount": 620,
"LastGeneratedAt": "2026-04-12T09:15:00Z"
}
}
],
"Pagination": {
"Total": 1,
"Limit": 50,
"Offset": 0
}
}400 Bad Request
Bad Request - Validation error or invalid request body.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.
Example response: Status is not a valid value
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Status must be 'active' or 'inactive'"
}
}Example response: EntityType is not a valid value
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "EntityType must be 'hotel' or 'room'"
}
}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.authoring:read 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.authoring:read"
}
}Example response: Project access required
{
"Error": {
"Code": "FORBIDDEN",
"Message": "Project access required"
}
}404 Not Found
Not Found - The requested resource 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: Project not found
{
"Error": {
"Code": "NOT_FOUND",
"Message": "Project 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 list text templates"
}
}