{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: Preview text",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ygo.ai",
      "description": "Production and Sandbox (determined by API key)"
    }
  ],
  "paths": {
    "/v2/project/content/previewText": {
      "post": {
        "summary": "Preview text",
        "description": "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.\n\nHotels are selected by HotelIDs and/or TagIDs (combined and deduplicated, capped at 100), and every selected hotel must belong to the calling project.",
        "operationId": "previewText",
        "tags": [
          "Content Enrichment API/Text Generation"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Project-ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreviewTextRequest"
              },
              "examples": {
                "byHotelIDs": {
                  "summary": "Preview all active templates for one hotel",
                  "value": {
                    "HotelIDs": [
                      "0192fb17-5dc6-7abc-8def-123456789abc"
                    ]
                  }
                },
                "scopedPreview": {
                  "summary": "Preview a single template in two locales",
                  "value": {
                    "HotelIDs": [
                      "0192fb17-5dc6-7abc-8def-123456789abc"
                    ],
                    "TemplateKeys": [
                      "Summary"
                    ],
                    "Locales": [
                      "en-US",
                      "de-DE"
                    ]
                  }
                },
                "byTag": {
                  "summary": "Preview every project hotel carrying a tag",
                  "value": {
                    "TagIDs": [
                      "0192fb40-7aa1-7abc-8def-aabbccddeeff"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preview computed successfully.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewTextResponse"
                },
                "examples": {
                  "byHotelIDs": {
                    "summary": "A hotel with one missing and one stale text",
                    "value": {
                      "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
                      }
                    }
                  },
                  "scopedPreview": {
                    "summary": "A single template previewed in two locales",
                    "value": {
                      "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
                      }
                    }
                  },
                  "byTag": {
                    "summary": "Two tag-resolved hotels, everything already fresh",
                    "value": {
                      "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": {
            "$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": "HotelIDs"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable validation error message for this field.",
            "example": "HotelIDs or TagIDs is required"
          },
          "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
            }
          }
        }
      },
      "PreviewChange": {
        "type": "object",
        "required": [
          "Category",
          "CompletedAt"
        ],
        "description": "One source category that was refreshed more recently than the hotel's stored text.",
        "properties": {
          "Category": {
            "type": "string",
            "enum": [
              "attributes",
              "POIs",
              "images"
            ],
            "description": "Source data category that changed.",
            "example": "attributes"
          },
          "CompletedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Completion timestamp of the latest run that refreshed this category (RFC3339).",
            "example": "2026-06-25T14:02:00Z"
          }
        }
      },
      "PreviewHotel": {
        "type": "object",
        "required": [
          "HotelID",
          "HotelName",
          "Texts",
          "WhatChanged",
          "TextsToGenerate"
        ],
        "description": "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.",
        "properties": {
          "HotelID": {
            "type": "string",
            "format": "uuid",
            "description": "Hotel UUID.",
            "example": "0192fb17-5dc6-7abc-8def-123456789abc"
          },
          "HotelName": {
            "type": "string",
            "description": "Hotel display name.",
            "example": "Bahia Azul Beach Resort"
          },
          "Texts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PreviewText"
            },
            "description": "Per (template, locale) freshness status rows for this hotel."
          },
          "WhatChanged": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PreviewChange"
            },
            "description": "Source categories that were refreshed more recently than this hotel's stored text, ordered deterministically. Empty when nothing newer changed."
          },
          "TextsToGenerate": {
            "type": "integer",
            "description": "Number of texts this hotel would (re)generate under fill_missing.",
            "example": 5
          }
        }
      },
      "PreviewResult": {
        "type": "object",
        "required": [
          "Hotels",
          "TotalTextsToGenerate"
        ],
        "description": "The full preview: one entry per selected hotel plus the grand total of texts that would be generated under fill_missing.",
        "properties": {
          "Hotels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PreviewHotel"
            },
            "description": "One preview entry per selected hotel, in the resolved selection order."
          },
          "TotalTextsToGenerate": {
            "type": "integer",
            "description": "Total number of texts across all hotels that a fill_missing run would (re)generate.",
            "example": 5
          }
        }
      },
      "PreviewText": {
        "type": "object",
        "required": [
          "TemplateKey",
          "EntityType",
          "Locale",
          "Status",
          "Count"
        ],
        "description": "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.",
        "properties": {
          "TemplateKey": {
            "type": "string",
            "description": "Template key this row refers to.",
            "example": "Summary"
          },
          "EntityType": {
            "type": "string",
            "enum": [
              "hotel",
              "room"
            ],
            "description": "Whether this template applies to the hotel or to its rooms.",
            "example": "hotel"
          },
          "Locale": {
            "type": "string",
            "description": "BCP 47 language tag this row refers to.",
            "example": "de-DE"
          },
          "Status": {
            "type": "string",
            "enum": [
              "missing",
              "fresh",
              "stale"
            ],
            "description": "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).",
            "example": "missing"
          },
          "Count": {
            "type": "integer",
            "description": "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
          }
        }
      },
      "PreviewTextRequest": {
        "type": "object",
        "description": "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.",
        "properties": {
          "HotelIDs": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "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": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "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": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "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": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "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"
            ]
          }
        }
      },
      "PreviewTextResponse": {
        "type": "object",
        "required": [
          "Data"
        ],
        "description": "Single-object response envelope wrapping the preview result.",
        "properties": {
          "Data": {
            "$ref": "#/components/schemas/PreviewResult"
          }
        }
      }
    },
    "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": {
              "missingSelection": {
                "summary": "Neither HotelIDs nor TagIDs provided",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Request validation failed",
                    "Fields": [
                      {
                        "Field": "HotelIDs",
                        "Message": "HotelIDs or TagIDs is required"
                      }
                    ]
                  }
                }
              },
              "unknownTemplateKeys": {
                "summary": "One or more template keys are not active templates of the project",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "unknown or inactive template keys: Headline"
                  }
                }
              },
              "tooManyHotels": {
                "summary": "Selection exceeds the per-request cap",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "selection must not exceed 100 hotels"
                  }
                }
              }
            }
          }
        }
      },
      "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.generation:write 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.generation:write"
                  }
                }
              },
              "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 preview text"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found - One of the selected hotels 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": {
              "hotelNotFound": {
                "summary": "A selected hotel is not in the project",
                "value": {
                  "Error": {
                    "Code": "NOT_FOUND",
                    "Message": "hotel 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"
      }
    }
  }
}
