API docs
Book a demo

Content Enrichment API / Templates

List text templates

Page

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

    Project UUID. Required for all project-scoped endpoints.

    Example
    $YGO_PROJECT_ID

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.

  • Status string

    Filter by lifecycle status. When omitted, templates of every status are returned.

    Values
    active inactive
    Example
    active
  • EntityType string

    Filter by the entity a template targets: 'hotel' for hotel-level texts, 'room' for room-level texts. When omitted, both kinds are returned.

    Values
    hotel room
    Example
    hotel
  • IncludeStats boolean

    When true, each returned template includes a UsageStats object summarizing how many generated texts use it. Defaults to false.

    Example
    false
  • Limit integer

    Maximum number of templates to return. Defaults to 50 and is capped at 100.

    Default
    50
    Example
    50
    Limits
    min 1, max 100
  • Offset integer

    Number of templates to skip for pagination. Defaults to 0.

    Default
    0
    Example
    0
    Limits
    min 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-ID string

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

    Example
    abc123def456ghi789

Body

application/json object ListTextTemplatesResponse

Paginated list response wrapping the project's text templates.

  • Data array of object TextTemplate required

    The text templates for this page, ordered by template key.

    Each item

    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.

    13 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
    • UsageStats object TemplateUsageStats

      Aggregated usage counts for a template, included only when IncludeStats is true in the request.

      3 fields
      • TextCount integer

        Total number of generated texts that use this template across the project.

        Example
        1240
      • HotelCount integer

        Number of distinct hotels that have at least one generated text from this template.

        Example
        620
      • LastGeneratedAt string (date-time) nullable

        Timestamp of the most recent text generated from this template (RFC3339). Null when the template has never been used.

        Example
        2026-04-12T09:15:00Z
    • 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-10T12:30:00Z
  • Pagination object Pagination required

    Pagination metadata for a list response.

    3 fields
    • Total integer required

      Total number of templates matching the request, across all pages.

      Example
      2
    • Limit integer required

      Maximum number of items returned in this page.

      Example
      50
    • Offset integer required

      Number of items skipped before this page.

      Example
      0
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-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
        Status
      • Message string required

        Human-readable validation error message for this field.

        Example
        Status must be 'active' or 'inactive'
      • 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: 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-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
        Status
      • Message string required

        Human-readable validation error message for this field.

        Example
        Status must be 'active' or 'inactive'
      • 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 the content.authoring:read permission 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
        Status
      • Message string required

        Human-readable validation error message for this field.

        Example
        Status must be 'active' or 'inactive'
      • 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.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-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
        Status
      • Message string required

        Human-readable validation error message for this field.

        Example
        Status must be 'active' or 'inactive'
      • 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"
  }
}
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
        Status
      • Message string required

        Human-readable validation error message for this field.

        Example
        Status must be 'active' or 'inactive'
      • 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
        Status
      • Message string required

        Human-readable validation error message for this field.

        Example
        Status must be 'active' or 'inactive'
      • 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 list text templates"
  }
}