API docs
Book a demo

Content Enrichment API / Text Generation

Preview text

Page

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

    Project UUID. Required for all project-scoped endpoints.

    Example
    $YGO_PROJECT_ID

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.

  • HotelIDs array 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.

    Example
    [
      "0192fb17-5dc6-7abc-8def-123456789abc"
    ]
  • TagIDs array 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.

    Example
    [
      "0192fb40-7aa1-7abc-8def-aabbccddeeff"
    ]
  • TemplateKeys array of string

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

    Example
    [
      "Summary",
      "HouseRules"
    ]
  • Locales array of string

    Optional subset of BCP 47 language tags to preview. Empty means the locales configured on the matched templates (always including en-US).

    Example
    [
      "en-US",
      "de-DE"
    ]
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-ID string

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

    Example
    abc123def456ghi789

Body

application/json object PreviewTextResponse

Single-object response envelope wrapping the preview result.

  • Data object PreviewResult required

    The full preview: one entry per selected hotel plus the grand total of texts that would be generated under fill_missing.

    2 fields
    • Hotels array of object PreviewHotel required

      One preview entry per selected hotel, in the resolved selection order.

      Each item

      The preview for a single hotel: its per-template-and-locale text statuses, its what-changed summary, and how many texts would be generated for it under fill_missing.

      5 fields
      • HotelID string (uuid) required

        Hotel UUID.

        Example
        0192fb17-5dc6-7abc-8def-123456789abc
      • HotelName string required

        Hotel display name.

        Example
        Bahia Azul Beach Resort
      • Texts array of object PreviewText required

        Per (template, locale) freshness status rows for this hotel.

        Each item

        The freshness status of one (template, locale) pair for a hotel. For room templates the status aggregates across the hotel's active rooms (worst-case: missing beats stale beats fresh) and Count is the number of room texts that would be generated.

        5 fields
        • TemplateKey string required

          Template key this row refers to.

          Example
          Summary
        • EntityType string required

          Whether this template applies to the hotel or to its rooms.

          Values
          hotel room
          Example
          hotel
        • Locale string required

          BCP 47 language tag this row refers to.

          Example
          de-DE
        • Status string required

          Freshness 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).

          Values
          missing fresh stale
          Example
          missing
        • Count integer required

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

          Example
          1
      • WhatChanged array of object PreviewChange required

        Source categories that were refreshed more recently than this hotel's stored text, ordered deterministically. Empty when nothing newer changed.

        Each item

        One source category that was refreshed more recently than the hotel's stored text.

        2 fields
        • Category string required

          Source data category that changed.

          Values
          attributes POIs images
          Example
          attributes
        • CompletedAt string (date-time) required

          Completion timestamp of the latest run that refreshed this category (RFC3339).

          Example
          2026-06-25T14:02:00Z
      • TextsToGenerate integer required

        Number of texts this hotel would (re)generate under fill_missing.

        Example
        5
    • TotalTextsToGenerate integer required

      Total number of texts across all hotels that a fill_missing run would (re)generate.

      Example
      5
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-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
        HotelIDs
      • Message string required

        Human-readable validation error message for this field.

        Example
        HotelIDs or TagIDs 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: 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-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
        HotelIDs
      • Message string required

        Human-readable validation error message for this field.

        Example
        HotelIDs or TagIDs 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 the content.generation:write 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
        HotelIDs
      • Message string required

        Human-readable validation error message for this field.

        Example
        HotelIDs or TagIDs 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 - One of the selected hotels 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
        HotelIDs
      • Message string required

        Human-readable validation error message for this field.

        Example
        HotelIDs or TagIDs 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: 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-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
        HotelIDs
      • Message string required

        Human-readable validation error message for this field.

        Example
        HotelIDs or TagIDs 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
        HotelIDs
      • Message string required

        Human-readable validation error message for this field.

        Example
        HotelIDs or TagIDs 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 preview text"
  }
}