{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: List text templates",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ygo.ai",
      "description": "Production and Sandbox (determined by API key)"
    }
  ],
  "paths": {
    "/v2/project/content/listTextTemplates": {
      "post": {
        "summary": "List text templates",
        "description": "Return the text templates configured for the calling project, ordered by template key.\n\nText 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.",
        "operationId": "listTextTemplates",
        "tags": [
          "Content Enrichment API/Templates"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Project-ID"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListTextTemplatesRequest"
              },
              "examples": {
                "allTemplates": {
                  "summary": "List all templates (default pagination)",
                  "value": {
                    "Limit": 50,
                    "Offset": 0
                  }
                },
                "activeHotelTemplates": {
                  "summary": "Active hotel templates only, with usage stats",
                  "value": {
                    "Status": "active",
                    "EntityType": "hotel",
                    "IncludeStats": true,
                    "Limit": 50,
                    "Offset": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Text templates retrieved successfully.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListTextTemplatesResponse"
                },
                "examples": {
                  "allTemplates": {
                    "summary": "A project's hotel and room templates",
                    "value": {
                      "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
                      }
                    }
                  },
                  "activeHotelTemplates": {
                    "summary": "Active hotel templates with usage statistics",
                    "value": {
                      "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": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorDetail": {
        "type": "object",
        "required": [
          "Code",
          "Message"
        ],
        "description": "Error detail containing a machine-readable code and human-readable message.",
        "properties": {
          "Code": {
            "type": "string",
            "description": "Machine-readable error code for programmatic handling.",
            "example": "VALIDATION_ERROR"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable error message.",
            "example": "Request validation failed"
          },
          "Fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldError"
            },
            "description": "Field-level validation errors. Only present for VALIDATION_ERROR responses."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "Error"
        ],
        "description": "Standard v2 error response wrapper.",
        "properties": {
          "Error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        }
      },
      "FieldError": {
        "type": "object",
        "required": [
          "Field",
          "Message"
        ],
        "description": "A single field-level validation error.",
        "properties": {
          "Field": {
            "type": "string",
            "description": "Name of the field that failed validation.",
            "example": "Status"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable validation error message for this field.",
            "example": "Status must be 'active' or 'inactive'"
          },
          "Code": {
            "type": "string",
            "enum": [
              "REQUIRED",
              "TOO_LONG",
              "TOO_SHORT",
              "OUT_OF_RANGE",
              "TOO_MANY",
              "INVALID_FORMAT",
              "NOT_ALLOWED",
              "CONFLICT",
              "INVALID_ENCODING",
              "INSECURE_SCHEME",
              "UNSAFE_CONTENT",
              "REQUIRED_WHEN_ENABLED"
            ],
            "description": "Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.",
            "example": "TOO_LONG"
          },
          "Params": {
            "type": "object",
            "additionalProperties": true,
            "description": "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
            }
          }
        }
      },
      "ListTextTemplatesRequest": {
        "type": "object",
        "description": "Request body for listing text templates. All fields are optional; an empty body returns the first page of all templates.",
        "properties": {
          "Status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Filter by lifecycle status. When omitted, templates of every status are returned.",
            "example": "active"
          },
          "EntityType": {
            "type": "string",
            "enum": [
              "hotel",
              "room"
            ],
            "description": "Filter by the entity a template targets: 'hotel' for hotel-level texts, 'room' for room-level texts. When omitted, both kinds are returned.",
            "example": "hotel"
          },
          "IncludeStats": {
            "type": "boolean",
            "description": "When true, each returned template includes a UsageStats object summarizing how many generated texts use it. Defaults to false.",
            "example": false
          },
          "Limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50,
            "description": "Maximum number of templates to return. Defaults to 50 and is capped at 100.",
            "example": 50
          },
          "Offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0,
            "description": "Number of templates to skip for pagination. Defaults to 0.",
            "example": 0
          }
        }
      },
      "ListTextTemplatesResponse": {
        "type": "object",
        "required": [
          "Data",
          "Pagination"
        ],
        "description": "Paginated list response wrapping the project's text templates.",
        "properties": {
          "Data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TextTemplate"
            },
            "description": "The text templates for this page, ordered by template key."
          },
          "Pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "required": [
          "Total",
          "Limit",
          "Offset"
        ],
        "description": "Pagination metadata for a list response.",
        "properties": {
          "Total": {
            "type": "integer",
            "description": "Total number of templates matching the request, across all pages.",
            "example": 2
          },
          "Limit": {
            "type": "integer",
            "description": "Maximum number of items returned in this page.",
            "example": 50
          },
          "Offset": {
            "type": "integer",
            "description": "Number of items skipped before this page.",
            "example": 0
          }
        }
      },
      "TemplateUsageStats": {
        "type": "object",
        "description": "Aggregated usage counts for a template, included only when IncludeStats is true in the request.",
        "properties": {
          "TextCount": {
            "type": "integer",
            "description": "Total number of generated texts that use this template across the project.",
            "example": 1240
          },
          "HotelCount": {
            "type": "integer",
            "description": "Number of distinct hotels that have at least one generated text from this template.",
            "example": 620
          },
          "LastGeneratedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "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"
          }
        }
      },
      "TextTemplate": {
        "type": "object",
        "required": [
          "ID",
          "ProjectID",
          "TemplateKey",
          "EntityType",
          "Instruction",
          "LocaleInstructions",
          "Status",
          "CreatedAt",
          "UpdatedAt"
        ],
        "description": "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.",
        "properties": {
          "ID": {
            "type": "string",
            "format": "uuid",
            "description": "Unique template UUID.",
            "example": "0192fb40-1aa2-7def-9abc-1122334455aa"
          },
          "ProjectID": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the project that owns this template.",
            "example": "0192fb00-0000-7000-8000-000000000001"
          },
          "TemplateKey": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "Human-readable template name for display. May be empty.",
            "example": "Hotel Summary"
          },
          "EntityType": {
            "type": "string",
            "enum": [
              "hotel",
              "room"
            ],
            "description": "Whether the template produces a hotel-level text or a room-level text.",
            "example": "hotel"
          },
          "Description": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "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": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "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": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Lifecycle status. Only 'active' templates are used during text generation.",
            "example": "active"
          },
          "RenderLayout": {
            "type": "string",
            "enum": [
              "prose",
              "highlights",
              "roomcards",
              "summary"
            ],
            "description": "Optional rendering hint suggesting how a client should display this template's generated text. Empty when no hint is set.",
            "example": "prose"
          },
          "UsageStats": {
            "$ref": "#/components/schemas/TemplateUsageStats"
          },
          "CreatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the template was created (RFC3339).",
            "example": "2026-03-01T08:00:00Z"
          },
          "UpdatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the template was last updated (RFC3339).",
            "example": "2026-04-10T12:30:00Z"
          }
        }
      }
    },
    "parameters": {
      "X-Project-ID": {
        "name": "X-Project-ID",
        "in": "header",
        "required": true,
        "description": "Project UUID. Required for all project-scoped endpoints.",
        "example": "$YGO_PROJECT_ID",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "headers": {
      "Retry-After": {
        "description": "Number of seconds to wait before retrying the request. Present on 429 responses.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "example": 30
        }
      },
      "X-Trace-ID": {
        "description": "Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.",
        "schema": {
          "type": "string",
          "example": "abc123def456ghi789"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad Request - Validation error or invalid request body.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidStatus": {
                "summary": "Status is not a valid value",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Status must be 'active' or 'inactive'"
                  }
                }
              },
              "invalidEntityType": {
                "summary": "EntityType is not a valid value",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "EntityType must be 'hotel' or 'room'"
                  }
                }
              },
              "invalidBody": {
                "summary": "Malformed request body",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Invalid request body"
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "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": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "insufficientScope": {
                "summary": "Missing required scope",
                "value": {
                  "Error": {
                    "Code": "INSUFFICIENT_SCOPE",
                    "Message": "token lacks scope content.authoring:read"
                  }
                }
              },
              "noProjectAccess": {
                "summary": "Project access required",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Project access required"
                  }
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error - Unexpected server error. Include the X-Trace-ID header value when contacting support.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "internalError": {
                "summary": "Internal server error",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to list text templates"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found - The requested resource does not exist or is not in the calling project's scope.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "projectNotFound": {
                "summary": "Project not found",
                "value": {
                  "Error": {
                    "Code": "NOT_FOUND",
                    "Message": "Project not found"
                  }
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests. The response includes a `Retry-After` header with the number of seconds to wait before retrying.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "rateLimited": {
                "summary": "Limit exceeded",
                "value": {
                  "Error": {
                    "Code": "RATE_LIMIT_EXCEEDED",
                    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized - Invalid or missing API key.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidKey": {
                "summary": "Invalid API key",
                "value": {
                  "Error": {
                    "Code": "UNAUTHORIZED",
                    "Message": "Invalid API key"
                  }
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Project-scoped API key"
      }
    }
  }
}
