# List text templates

Content Enrichment API / Templates

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

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

## Example request

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

Schema: 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: allTemplates. List all templates (default pagination)

```json
{
  "Limit": 50,
  "Offset": 0
}
```

#### Example request: activeHotelTemplates. Active hotel templates only, with usage stats

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

#### application/json

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

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

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

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

  - `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: allTemplates. A project's hotel and room templates

```json
{
  "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: activeHotelTemplates. Active hotel templates with usage statistics

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

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

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

##### Example: invalidStatus. Status is not a valid value

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Status must be 'active' or 'inactive'"
  }
}
```

##### Example: invalidEntityType. EntityType is not a valid value

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "EntityType must be 'hotel' or 'room'"
  }
}
```

##### Example: invalidBody. Malformed request body

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

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

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

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

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

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

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

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

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

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

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

##### Example: projectNotFound. Project not found

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

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

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

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

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

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