{
  "openapi": "3.1.0",
  "info": {
    "title": "Timeless Puglia published accommodation",
    "version": "1.1",
    "description": "Find public property descriptions and canonical links. Use the booking site with check-in, check-out and guest count for the current total, availability and rate conditions."
  },
  "servers": [
    {
      "url": "https://book.timelesspuglia.com"
    }
  ],
  "paths": {
    "/api/v1/booking-engine/public/ai/catalog": {
      "get": {
        "operationId": "listPublishedStays",
        "summary": "Find published stays by city or property slug",
        "description": "Use a city name or slug returned by the catalogue. When both filters are supplied, a stay must match both. Follow pagination.nextUrl while it has a value.",
        "security": [],
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "description": "Published destination name, such as Ostuni.",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "slug",
            "in": "query",
            "description": "A property slug returned in a previous result.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Use a small page when exploring a destination.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            },
            "example": 10
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public catalogue snapshot. An unmatched filter returns an empty properties array.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalogue"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Catalogue": {
        "type": "object",
        "required": [
          "canonicalOrigin",
          "generatedAt",
          "cities",
          "pagination",
          "properties"
        ],
        "properties": {
          "canonicalOrigin": {
            "type": "string",
            "format": "uri"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Time of this catalogue snapshot."
          },
          "cities": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "propertyCount",
                "guideUrl"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "propertyCount": {
                  "type": "integer",
                  "minimum": 0
                },
                "guideUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "apartmentsUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Published booking link for this destination."
                }
              }
            },
            "description": "Destination directory for this public catalogue. A city or slug filter narrows the properties and pagination.total."
          },
          "pagination": {
            "type": "object",
            "required": [
              "total",
              "offset",
              "limit",
              "returned",
              "hasMore",
              "nextUrl"
            ],
            "properties": {
              "total": {
                "type": "integer",
                "minimum": 0,
                "description": "Number of stays matching this request before pagination."
              },
              "returned": {
                "type": "integer",
                "minimum": 0
              },
              "hasMore": {
                "type": "boolean"
              },
              "nextUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              },
              "offset": {
                "type": "integer",
                "minimum": 0
              },
              "limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 200
              }
            }
          },
          "properties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Stay"
            }
          }
        }
      },
      "Stay": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "city",
          "canonicalUrl"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "canonicalUrl": {
            "type": "string",
            "format": "uri"
          },
          "accommodationType": {
            "type": "string"
          },
          "maxGuests": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Recorded capacity. Null means unknown."
          },
          "bedrooms": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Zero can describe a studio. Null means unknown."
          },
          "bathrooms": {
            "type": [
              "number",
              "null"
            ],
            "description": "Can include a half bathroom. Null means unknown."
          },
          "id": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Public English description when supplied."
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ],
            "minimum": -90,
            "maximum": 90
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ],
            "minimum": -180,
            "maximum": 180
          },
          "amenities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Facilities explicitly listed for this property. An unlisted facility has no positive confirmation."
          },
          "verifiedReviewCount": {
            "type": "integer",
            "minimum": 0
          },
          "verifiedReviewAverage": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 5,
            "description": "Average on a five-point scale when available."
          },
          "primaryImage": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Primary public photograph when available."
          },
          "representativeImages": {
            "type": "array",
            "maxItems": 8,
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "futureCalendarStatus": {
            "type": "string",
            "description": "A general calendar signal. Check the exact dates and party size on the booking site for availability and total price."
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "How to check date-specific prices and conditions",
    "url": "https://book.timelesspuglia.com/agents/booking-guide.md"
  }
}
