{
  "openapi": "3.1.0",
  "info": {
    "title": "Hot Air Cappadocia Balloon - Public API",
    "summary": "Read-only Cappadocia balloon flight-status, weather forecast, and currency-rate endpoints.",
    "description": "Public, read-only endpoints intended for AI agents, integrations, and partners. Booking, payment, reservation-lookup, reviews, and admin endpoints are intentionally NOT part of this specification and must not be called by third parties. Data is served from the same origin as the website. All responses are JSON. Timestamps are ISO 8601 (UTC). Prices and rates are informational; the authoritative booking price is confirmed at checkout. Versioning: the documented paths live under /api/v1. Breaking changes ship under a new path (/api/v2). /api/v1 stays available for at least 12 months after v2 is announced. Deprecations are announced with Deprecation and Sunset response headers and on the API page. Every response carries an API-Version header. Errors are JSON with an error code and a message (see the Error schema). No authentication is required.",
    "version": "1.0.0",
    "contact": {
      "name": "Hot Air Cappadocia Balloon",
      "url": "https://hotaircappadociaballoon.com",
      "email": "fly@hotaircappadociaballoon.com"
    }
  },
  "servers": [
    {
      "url": "https://hotaircappadociaballoon.com",
      "description": "Production"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "flight-status",
      "description": "Daily Civil Aviation flight authorization for Cappadocia"
    },
    {
      "name": "weather",
      "description": "Sunrise-window weather forecast"
    },
    {
      "name": "currency",
      "description": "Informational exchange rates"
    }
  ],
  "paths": {
    "/api/v1/flight-status": {
      "get": {
        "tags": [
          "flight-status"
        ],
        "operationId": "getFlightStatus",
        "summary": "Today's Cappadocia balloon flight authorization",
        "description": "Returns the current day's flight authorization for the three Cappadocia flight sectors (A, B, C) as published by SHM Kapadokya (the local Civil Aviation authority), plus sunrise and sunset times. Updated by a scheduled job several times daily; cached ~5 minutes.",
        "responses": {
          "200": {
            "description": "Current flight-status payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlightStatusData"
                }
              }
            },
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              }
            }
          },
          "503": {
            "description": "No data has been fetched yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NoDataError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              }
            }
          },
          "500": {
            "description": "Internal error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/api/v1/forecast": {
      "get": {
        "tags": [
          "weather"
        ],
        "operationId": "getForecast",
        "summary": "7-day Goreme sunrise flight-likelihood forecast",
        "description": "Returns a multi-day forecast for the Goreme sunrise launch window, including a derived flight-likelihood status and the driving weather metrics (wind, gusts, cloud cover, precipitation, temperature). Cached ~1 hour.",
        "responses": {
          "200": {
            "description": "Forecast payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastResponse"
                }
              }
            },
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              }
            }
          },
          "500": {
            "description": "Internal error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastError"
                }
              }
            },
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/api/v1/exchange-rate": {
      "get": {
        "tags": [
          "currency"
        ],
        "operationId": "getExchangeRate",
        "summary": "Informational currency exchange rates (base EUR)",
        "description": "Returns exchange rates with EUR as the base currency, used to display approximate prices in other currencies. Informational only; not authoritative for payment. Always responds 200, falling back to a degraded EUR-only table if the upstream rate source is unavailable.",
        "responses": {
          "200": {
            "description": "Exchange-rate table.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExchangeRate"
                }
              }
            },
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SectorStatus": {
        "type": "string",
        "enum": [
          "flyable",
          "not_flyable",
          "pending",
          "unknown"
        ],
        "description": "Authorization state for a flight sector."
      },
      "Sector": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/SectorStatus"
          },
          "label": {
            "type": "string",
            "description": "Human-readable status label."
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional detail or note."
          }
        },
        "required": [
          "status",
          "label"
        ]
      },
      "FlightStatusData": {
        "type": "object",
        "properties": {
          "fetchedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When this payload was fetched (ISO 8601)."
          },
          "lastUpdatedBySHM": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the source authority last updated the notice."
          },
          "validFor": {
            "type": "object",
            "properties": {
              "from": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "to": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "description": "The window the authorization applies to."
          },
          "sectors": {
            "type": "object",
            "properties": {
              "A": {
                "$ref": "#/components/schemas/Sector"
              },
              "B": {
                "$ref": "#/components/schemas/Sector"
              },
              "C": {
                "$ref": "#/components/schemas/Sector"
              }
            },
            "required": [
              "A",
              "B",
              "C"
            ],
            "description": "Per-sector authorization for the three Cappadocia flight sectors."
          },
          "sunrise": {
            "type": [
              "string",
              "null"
            ],
            "description": "Local sunrise time."
          },
          "sunset": {
            "type": [
              "string",
              "null"
            ],
            "description": "Local sunset time."
          },
          "source": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "authority": {
                "type": "string"
              }
            },
            "required": [
              "name",
              "url",
              "authority"
            ],
            "description": "Attribution for the authorization data."
          },
          "checkedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the scheduled job last checked SHM for a new bulletin (ISO 8601)."
          },
          "outlook": {
            "$ref": "#/components/schemas/FlightOutlook"
          }
        },
        "required": [
          "fetchedAt",
          "sectors",
          "source"
        ]
      },
      "ForecastResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "forecast": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ForecastDay"
            }
          }
        },
        "required": [
          "ok",
          "forecast"
        ]
      },
      "ForecastDay": {
        "type": "object",
        "properties": {
          "day": {
            "type": "string",
            "description": "Short weekday, e.g. 'Thu'."
          },
          "date": {
            "type": "string",
            "description": "Short date, e.g. '2 Jul'."
          },
          "dateISO": {
            "type": "string",
            "format": "date",
            "description": "ISO date, e.g. '2026-07-02'."
          },
          "status": {
            "type": "string",
            "enum": [
              "likely",
              "watch",
              "unlikely"
            ],
            "description": "Derived flight likelihood for the sunrise window."
          },
          "reason": {
            "type": "string",
            "description": "Short reason code for the status, e.g. 'calm', 'wind'."
          },
          "temperature": {
            "type": "integer",
            "description": "Climb-hour temperature at 06:00 local, degrees Celsius."
          },
          "wind_max": {
            "type": "integer",
            "description": "Max wind speed in the sunrise window, km/h."
          },
          "wind_gusts": {
            "type": "integer",
            "description": "Max wind gusts in the sunrise window, km/h."
          },
          "cloud_cover": {
            "type": "integer",
            "description": "Average cloud cover in the sunrise window, percent."
          },
          "precipitation": {
            "type": "number",
            "description": "Total precipitation in the sunrise window, mm."
          },
          "weather_code": {
            "type": "integer",
            "description": "WMO weather code at climb hour."
          }
        },
        "required": [
          "day",
          "date",
          "dateISO",
          "status",
          "reason",
          "temperature",
          "wind_max",
          "wind_gusts",
          "cloud_cover",
          "precipitation",
          "weather_code"
        ]
      },
      "ExchangeRate": {
        "type": "object",
        "properties": {
          "base": {
            "type": "string",
            "enum": [
              "EUR"
            ],
            "description": "Base currency for all rates."
          },
          "rates": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Map of currency code to rate relative to EUR, e.g. { \"EUR\": 1, \"USD\": 1.08, \"TRY\": 44.2 }."
          },
          "available": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Currency codes with a live rate."
          },
          "rateDate": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date the upstream rates apply to."
          },
          "fetchedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When rates were fetched (ISO 8601)."
          },
          "source": {
            "type": "string",
            "description": "Rate source identifier; 'fallback' when degraded."
          },
          "degraded": {
            "type": "boolean",
            "description": "True when the live source was unavailable and a fallback table was returned."
          }
        },
        "required": [
          "base",
          "rates",
          "available",
          "fetchedAt",
          "source",
          "degraded"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine-readable error code: not_found (no endpoint at this path), method_not_allowed (only GET, HEAD and OPTIONS are supported), internal_error (unexpected server failure).",
            "enum": [
              "not_found",
              "method_not_allowed",
              "internal_error"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message."
          },
          "hint": {
            "type": "string",
            "description": "Optional advice on how to fix the request."
          },
          "docs": {
            "type": "string",
            "format": "uri",
            "description": "Optional link to the API documentation."
          }
        },
        "required": [
          "error",
          "message"
        ]
      },
      "NoDataError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "no_data_yet"
            ]
          },
          "message": {
            "type": "string"
          },
          "source": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        },
        "required": [
          "error",
          "message"
        ]
      },
      "ForecastError": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "ok",
          "error"
        ]
      },
      "FlightOutlook": {
        "type": "object",
        "description": "What the latest bulletin means for the next sunrise. state is 'unavailable' when there is no data or it is too old to rely on; otherwise morning, dateISO and sectors are present.",
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "ok",
              "unavailable"
            ]
          },
          "morning": {
            "type": "string",
            "enum": [
              "today",
              "tomorrow"
            ],
            "description": "Which sunrise the outlook is for."
          },
          "dateISO": {
            "type": "string",
            "format": "date",
            "description": "Date of that sunrise, Türkiye time."
          },
          "sectors": {
            "type": "object",
            "description": "Outlook per flight sector.",
            "properties": {
              "A": {
                "$ref": "#/components/schemas/SectorOutlook"
              },
              "B": {
                "$ref": "#/components/schemas/SectorOutlook"
              },
              "C": {
                "$ref": "#/components/schemas/SectorOutlook"
              }
            },
            "required": [
              "A",
              "B",
              "C"
            ]
          }
        },
        "required": [
          "state"
        ]
      },
      "SectorOutlook": {
        "type": "string",
        "enum": [
          "cancelled",
          "clear",
          "notYet",
          "pending"
        ],
        "description": "cancelled: a no-fly bulletin covers that morning. clear: no restriction covers this morning. notYet: no restriction has been published yet for tomorrow's morning. pending: the bulletin itself is pending or unknown."
      }
    },
    "headers": {
      "ApiVersion": {
        "description": "Major version of the API that produced the response.",
        "schema": {
          "type": "string",
          "enum": [
            "1"
          ]
        }
      },
      "Allow": {
        "description": "Methods the endpoint supports.",
        "schema": {
          "type": "string",
          "example": "GET, HEAD, OPTIONS"
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "No endpoint at this path. Returned for any unknown path under /api.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "not_found",
              "message": "There is no API endpoint at /api/v1/unknown.",
              "hint": "The public API lives under /api/v1: flight-status, forecast and exchange-rate. Its OpenAPI description is https://hotaircappadociaballoon.com/openapi.json.",
              "docs": "https://hotaircappadociaballoon.com/en/developers"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "The method is not supported. The endpoints are read-only.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          },
          "Allow": {
            "$ref": "#/components/headers/Allow"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "method_not_allowed",
              "message": "POST is not supported here. This endpoint is read-only.",
              "hint": "Use GET.",
              "docs": "https://hotaircappadociaballoon.com/en/developers"
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "API documentation with examples",
    "url": "https://hotaircappadociaballoon.com/en/developers"
  }
}
