Content Enrichment API / Templates
Save text template
PageMore page actions
POST /v2/project/content/saveTextTemplate
Create a new text template or update an existing one. The template is matched within the project by its TemplateKey: an existing key updates that template, a new key creates one. The saved template is returned.
TemplateKey, EntityType, and Instruction are required. The default Instruction and each per-locale instruction are checked for safety before the template is stored.
Example request
curl -X POST 'https://api.ygo.ai/v2/project/content/saveTextTemplate' \
-H "Authorization: Bearer $YGO_API_KEY" \
-H "X-Project-ID: $YGO_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"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"
}'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 SaveTextTemplateRequest
Request body for creating or updating a text template. The template is matched within the project by TemplateKey.
TemplateKeystring requiredStable key identifying the template within the project (max 100 characters). 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. Saving with an existing key updates that template; a new key creates one.
NamestringHuman-readable template name for display. Optional.
EntityTypestring requiredWhether the template produces a hotel-level text or a room-level text.
DescriptionstringFree-text note describing what the template is for. Optional.
Instructionstring requiredDefault authoring instruction that guides text generation when no locale-specific override applies. Required. Limited to 12,000 characters (Unicode characters, not bytes); longer instructions are rejected.
LocaleInstructionsmap of string to stringPer-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. Optional; omit or pass an empty object for no overrides. Each per-locale instruction is limited to 2,500 characters, counted independently of the base instruction, and a template carries at most 100 locale entries.
StatusstringLifecycle status. Only 'active' templates are used during text generation. Defaults to 'active' when omitted.
RenderLayoutstringOptional rendering hint suggesting how a client should display this template's generated text. Leave empty or omit when no hint is needed.
Example request: Create a new hotel summary template
{
"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"
}Example request: Update the room description template's instruction
{
"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. Mention any balcony or terrace. Keep it neutral and concrete.",
"LocaleInstructions": {},
"Status": "active",
"RenderLayout": "roomcards"
}Responses
200 OK
Text template created or updated successfully. Returns the saved template.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object SaveTextTemplateResponse
Single-object response envelope wrapping the saved text template.
Dataobject TextTemplate requiredA project-scoped text template. It controls one generated text per locale for either a hotel or a room, using a default authoring instruction plus optional per-locale instruction overrides.
12 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.
CreatedAtstring (date-time) requiredTimestamp when the template was created (RFC3339).
UpdatedAtstring (date-time) requiredTimestamp when the template was last updated (RFC3339).
Example response: Newly created hotel summary template
{
"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-04-12T09:15:00Z",
"UpdatedAt": "2026-04-12T09:15:00Z"
}
}Example response: Updated room description template
{
"Data": {
"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. Mention any balcony or terrace. Keep it neutral and concrete.",
"LocaleInstructions": {},
"Status": "active",
"RenderLayout": "roomcards",
"CreatedAt": "2026-03-01T08:00:00Z",
"UpdatedAt": "2026-04-12T09:15:00Z"
}
}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: Required fields not provided
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Request validation failed",
"Fields": [
{
"Field": "TemplateKey",
"Message": "TemplateKey is required"
},
{
"Field": "EntityType",
"Message": "EntityType is required"
},
{
"Field": "Instruction",
"Message": "Instruction is required"
}
]
}
}Example response: EntityType is not a valid value
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "EntityType must be 'hotel' or 'room'"
}
}Example response: RenderLayout is not a valid value
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "RenderLayout must be one of prose, highlights, roomcards, summary"
}
}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 both the content.authoring:write and content.generation:write permissions 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 - 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"
}
}409 Conflict
Conflict - The template could not be saved because it conflicts with the current state of an existing template.
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: Template conflict
{
"Error": {
"Code": "ALREADY_EXISTS",
"Message": "Text template conflicts with an existing template"
}
}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 save text template"
}
}