{
  "openapi": "3.0.3",
  "info": {
    "title": "Corfu Cottages Availability API",
    "description": "Public, no API key. Live availability for AI assistants and developers. Stay search uses the same Combnext/Octorate listall webhook as the on-site date picker. No cookies, captcha, or JavaScript required. CORS: Access-Control-Allow-Origin: *.",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://www.corfucottages.com"
    }
  ],
  "paths": {
    "/api/v1/availability.json": {
      "get": {
        "operationId": "searchAvailability",
        "summary": "Search availability for a stay or a calendar month",
        "description": "Pass checkin+checkout+guests for a stay search, or month=YYYY-MM for per-property free ranges. Public, no auth.",
        "parameters": [
          {
            "name": "checkin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-12-01"
            },
            "description": "ISO YYYY-MM-DD check-in (required with checkout unless month is set)"
          },
          {
            "name": "checkout",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-12-08"
            },
            "description": "ISO YYYY-MM-DD check-out (exclusive end of stay nights)"
          },
          {
            "name": "guests",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 30,
              "default": 2,
              "example": 2
            }
          },
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}$",
              "example": "2026-12"
            },
            "description": "If set, returns free date ranges per property for that month"
          }
        ],
        "responses": {
          "200": {
            "description": "Stay search or month ranges",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "object"
                    },
                    "available": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "area": {
                            "type": "string"
                          },
                          "sleeps": {
                            "type": "integer"
                          },
                          "bedrooms": {
                            "type": "number"
                          },
                          "has_pool": {
                            "type": "boolean"
                          },
                          "price_total": {
                            "type": "number"
                          },
                          "price_per_night": {
                            "type": "number"
                          },
                          "currency": {
                            "type": "string",
                            "example": "EUR"
                          },
                          "min_stay": {
                            "type": "integer"
                          },
                          "property_url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "booking_url": {
                            "type": "string",
                            "format": "uri",
                            "example": "https://www.corfucottages.com/korakiana-cottage.html?checkin=2026-12-01&checkout=2026-12-08&guests=2"
                          }
                        }
                      }
                    },
                    "unavailable": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "reason": {
                            "type": "string",
                            "enum": [
                              "booked",
                              "min_stay",
                              "capacity",
                              "closed_season"
                            ]
                          }
                        }
                      }
                    },
                    "generated_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                },
                "example": {
                  "query": {
                    "checkin": "2026-12-01",
                    "checkout": "2026-12-08",
                    "nights": 7,
                    "guests": 2
                  },
                  "available": [
                    {
                      "slug": "korakiana-cottage",
                      "name": "Korakiana Cottage",
                      "area": "Ano Korakiana",
                      "sleeps": 6,
                      "bedrooms": 3,
                      "has_pool": false,
                      "price_total": 1050,
                      "price_per_night": 150,
                      "currency": "EUR",
                      "min_stay": 3,
                      "property_url": "https://www.corfucottages.com/korakiana-cottage.html",
                      "booking_url": "https://www.corfucottages.com/korakiana-cottage.html?checkin=2026-12-01&checkout=2026-12-08&guests=2"
                    }
                  ],
                  "unavailable": [
                    {
                      "slug": "harmony-house",
                      "name": "Harmony House",
                      "reason": "booked"
                    }
                  ],
                  "generated_at": "2026-11-06T10:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid parameters (includes working example URL)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "example": {
                      "type": "string",
                      "example": "https://www.corfucottages.com/api/v1/availability.json?checkin=2026-12-01&checkout=2026-12-08&guests=2"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/properties/{slug}/availability.json": {
      "get": {
        "operationId": "getPropertyAvailability",
        "summary": "Free / blocked nights for one property",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "korakiana-cottage"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Per-property free ranges and blocked nights",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    },
    "/api/v1/properties/{slug}/availability.ics": {
      "get": {
        "operationId": "getPropertyAvailabilityIcs",
        "summary": "iCalendar feed of unavailable nights for one property",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "text/calendar",
            "content": {
              "text/calendar": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/availability.html": {
      "get": {
        "operationId": "availabilityHtml",
        "summary": "Server-rendered HTML fallback (no JavaScript)",
        "parameters": [
          {
            "name": "checkin",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "checkout",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "guests",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 2
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plain HTML list of available / unavailable properties",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/properties.json": {
      "get": {
        "operationId": "listProperties",
        "summary": "Static property catalog (amenities, seasons, URLs, availability templates)",
        "responses": {
          "200": {
            "description": "Catalog JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/quote": {
      "get": {
        "operationId": "liveStayQuote",
        "summary": "Live EUR stay totals (redirects to the same list webhook the site uses)",
        "parameters": [
          {
            "name": "arrival",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "departure",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to Combnext listall webhook JSON"
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "llms.txt guide for AI agents",
    "url": "https://www.corfucottages.com/llms.txt"
  }
}