# Preview text

Content Enrichment API / Text Generation

`POST https://api.ygo.ai/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.

Exact spec (OpenAPI 3.0, JSON): https://docs.ygo.ai/reference/previewText.json

## Example request

```bash
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

Schema: 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:

  ```json
  [
    "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:

  ```json
  [
    "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:

  ```json
  [
    "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:

  ```json
  [
    "en-US",
    "de-DE"
  ]
  ```

#### Example request: byHotelIDs. Preview all active templates for one hotel

```json
{
  "HotelIDs": [
    "0192fb17-5dc6-7abc-8def-123456789abc"
  ]
}
```

#### Example request: scopedPreview. Preview a single template in two locales

```json
{
  "HotelIDs": [
    "0192fb17-5dc6-7abc-8def-123456789abc"
  ],
  "TemplateKeys": [
    "Summary"
  ],
  "Locales": [
    "en-US",
    "de-DE"
  ]
}
```

#### Example request: byTag. Preview every project hotel carrying a tag

```json
{
  "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`

#### application/json

Schema: 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.

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

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

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

      - `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: byHotelIDs. A hotel with one missing and one stale text

```json
{
  "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: scopedPreview. A single template previewed in two locales

```json
{
  "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: byTag. Two tag-resolved hotels, everything already fresh

```json
{
  "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`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

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

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

    - `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:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: missingSelection. Neither HotelIDs nor TagIDs provided

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Request validation failed",
    "Fields": [
      {
        "Field": "HotelIDs",
        "Message": "HotelIDs or TagIDs is required"
      }
    ]
  }
}
```

##### Example: unknownTemplateKeys. One or more template keys are not active templates of the project

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "unknown or inactive template keys: Headline"
  }
}
```

##### Example: tooManyHotels. Selection exceeds the per-request cap

```json
{
  "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`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

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

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

    - `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:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: invalidKey. Invalid API key

```json
{
  "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`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

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

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

    - `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:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: insufficientScope. Missing required scope

```json
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.generation:write"
  }
}
```

##### Example: noProjectAccess. Project access required

```json
{
  "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`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

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

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

    - `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:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: hotelNotFound. A selected hotel is not in the project

```json
{
  "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

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

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

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

    - `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:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: rateLimited. Limit exceeded

```json
{
  "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`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

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

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

    - `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:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: internalError. Internal server error

```json
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to preview text"
  }
}
```
