API docs
Book a demo

Content Enrichment API / Templates

Save text template

Page

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-ID string (uuid) required

    Project UUID. Required for all project-scoped endpoints.

    Example
    $YGO_PROJECT_ID

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.

  • TemplateKey string required

    Stable 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.

    Example
    summary
    Limits
    max length 100
  • Name string

    Human-readable template name for display. Optional.

    Example
    Hotel Summary
  • EntityType string required

    Whether the template produces a hotel-level text or a room-level text.

    Values
    hotel room
    Example
    hotel
  • Description string

    Free-text note describing what the template is for. Optional.

    Example
    Short marketing summary shown at the top of the hotel page.
  • Instruction string required

    Default 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.

    Example
    Write a concise, factual two-sentence summary highlighting the hotel's location, standout amenity, and overall character. Avoid superlatives.
    Limits
    max length 12000
  • LocaleInstructions map of string to string

    Per-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.

    Example
    {
      "de-DE": "Schreibe eine sachliche Zusammenfassung in zwei Saetzen und verwende die Sie-Form."
    }
    Limits
    max keys 100, each value: max length 2500
  • Status string

    Lifecycle status. Only 'active' templates are used during text generation. Defaults to 'active' when omitted.

    Values
    active inactive
    Example
    active
  • RenderLayout string

    Optional rendering hint suggesting how a client should display this template's generated text. Leave empty or omit when no hint is needed.

    Values
    prose highlights roomcards summary
    Example
    prose
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-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object SaveTextTemplateResponse

Single-object response envelope wrapping the saved text template.

  • Data object TextTemplate required

    A 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
    • ID string (uuid) required

      Unique template UUID.

      Example
      0192fb40-1aa2-7def-9abc-1122334455aa
    • ProjectID string (uuid) required

      UUID of the project that owns this template.

      Example
      0192fb00-0000-7000-8000-000000000001
    • TemplateKey string required

      Stable 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.

      Example
      summary
    • Name string

      Human-readable template name for display. May be empty.

      Example
      Hotel Summary
    • EntityType string required

      Whether the template produces a hotel-level text or a room-level text.

      Values
      hotel room
      Example
      hotel
    • Description string

      Free-text note describing what the template is for. May be empty.

      Example
      Short marketing summary shown at the top of the hotel page.
    • Instruction string required

      Default authoring instruction that guides text generation when no locale-specific override applies.

      Example
      Write a concise, factual two-sentence summary highlighting the hotel's location, standout amenity, and overall character. Avoid superlatives.
    • LocaleInstructions map of string to string required

      Per-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.

      Example
      {
        "de-DE": "Schreibe eine sachliche Zusammenfassung in zwei Saetzen und verwende die Sie-Form."
      }
    • Status string required

      Lifecycle status. Only 'active' templates are used during text generation.

      Values
      active inactive
      Example
      active
    • RenderLayout string

      Optional rendering hint suggesting how a client should display this template's generated text. Empty when no hint is set.

      Values
      prose highlights roomcards summary
      Example
      prose
    • CreatedAt string (date-time) required

      Timestamp when the template was created (RFC3339).

      Example
      2026-03-01T08:00:00Z
    • UpdatedAt string (date-time) required

      Timestamp when the template was last updated (RFC3339).

      Example
      2026-04-12T09:15:00Z
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-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      VALIDATION_ERROR
    • Message string required

      Human-readable error message.

      Example
      Request validation failed
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        TemplateKey
      • Message string required

        Human-readable validation error message for this field.

        Example
        TemplateKey is required
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-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
        {
          "Max": 100
        }
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-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      VALIDATION_ERROR
    • Message string required

      Human-readable error message.

      Example
      Request validation failed
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        TemplateKey
      • Message string required

        Human-readable validation error message for this field.

        Example
        TemplateKey is required
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-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
        {
          "Max": 100
        }
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-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      VALIDATION_ERROR
    • Message string required

      Human-readable error message.

      Example
      Request validation failed
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        TemplateKey
      • Message string required

        Human-readable validation error message for this field.

        Example
        TemplateKey is required
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-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
        {
          "Max": 100
        }
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-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      VALIDATION_ERROR
    • Message string required

      Human-readable error message.

      Example
      Request validation failed
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        TemplateKey
      • Message string required

        Human-readable validation error message for this field.

        Example
        TemplateKey is required
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-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
        {
          "Max": 100
        }
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-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      VALIDATION_ERROR
    • Message string required

      Human-readable error message.

      Example
      Request validation failed
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        TemplateKey
      • Message string required

        Human-readable validation error message for this field.

        Example
        TemplateKey is required
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-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
        {
          "Max": 100
        }
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-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789
  • Retry-After integer

    Number of seconds to wait before retrying the request. Present on 429 responses.

    Example
    30
    Limits
    min 1

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      VALIDATION_ERROR
    • Message string required

      Human-readable error message.

      Example
      Request validation failed
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        TemplateKey
      • Message string required

        Human-readable validation error message for this field.

        Example
        TemplateKey is required
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-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
        {
          "Max": 100
        }
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-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      VALIDATION_ERROR
    • Message string required

      Human-readable error message.

      Example
      Request validation failed
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        TemplateKey
      • Message string required

        Human-readable validation error message for this field.

        Example
        TemplateKey is required
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-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
        {
          "Max": 100
        }
Example response: Internal server error
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to save text template"
  }
}