{
  "openapi": "3.0.3",
  "info": {
    "title": "Fare Deals API",
    "version": "1.2.0",
    "description": "Cheap flights from any city, to one place or anywhere, with the cheapest days to fly. Fares are the cheapest Aviasales travellers found in the last 48 hours; always say the live price is on the booking page. Booking links are affiliate links (disclosure field). Prices are in the shopper's currency (currency field); US dollars unless another country is given.",
    "contact": {
      "email": "faredealshelp@outlook.com"
    }
  },
  "servers": [
    {
      "url": "https://faredeals.pages.dev/v1"
    }
  ],
  "paths": {
    "/deals": {
      "get": {
        "operationId": "findDeals",
        "summary": "Cheapest recent fares from a city, to a place or anywhere. Read the say field aloud.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "City or airport, for example New York or JFK"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "City or airport, or anywhere (default)"
          },
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Departure month 2026-11 or date 2026-11-14"
          },
          {
            "name": "return",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Return month or date"
          },
          {
            "name": "one_way",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "nonstop",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "max_price",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Budget in US dollars"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Two-letter country for the currency, for example US, GB, CA, AU, DE. Leave out to use the traveller's location."
          }
        ],
        "responses": {
          "200": {
            "description": "Fares",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "say": {
                      "type": "string"
                    },
                    "from": {
                      "type": "string"
                    },
                    "to": {
                      "type": "string"
                    },
                    "trip": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "deals": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "from": {
                            "type": "string"
                          },
                          "to": {
                            "type": "string",
                            "description": "IATA city code"
                          },
                          "to_name": {
                            "type": "string"
                          },
                          "price": {
                            "type": "integer"
                          },
                          "depart": {
                            "type": "string"
                          },
                          "return": {
                            "type": "string",
                            "nullable": true
                          },
                          "stops": {
                            "type": "integer",
                            "nullable": true
                          },
                          "airline": {
                            "type": "string",
                            "nullable": true
                          },
                          "book_url": {
                            "type": "string",
                            "description": "Affiliate booking link on Aviasales"
                          },
                          "compare_skyscanner": {
                            "type": "string",
                            "nullable": true,
                            "description": "The same trip on Skyscanner, to compare prices (not an affiliate link)"
                          }
                        }
                      }
                    },
                    "note": {
                      "type": "string"
                    },
                    "disclosure": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Plain-sentence error, safe to read out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Plain-sentence error, safe to read out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Plain-sentence error, safe to read out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cheapest-dates": {
      "get": {
        "operationId": "cheapestDates",
        "summary": "Cheapest departure days for a route in a month.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "month",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "2026-11"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Two-letter country for the currency, for example US, GB, CA, AU, DE. Leave out to use the traveller's location."
          }
        ],
        "responses": {
          "200": {
            "description": "Days",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "say": {
                      "type": "string"
                    },
                    "days": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "from": {
                            "type": "string"
                          },
                          "to": {
                            "type": "string",
                            "description": "IATA city code"
                          },
                          "to_name": {
                            "type": "string"
                          },
                          "price": {
                            "type": "integer"
                          },
                          "depart": {
                            "type": "string"
                          },
                          "return": {
                            "type": "string",
                            "nullable": true
                          },
                          "stops": {
                            "type": "integer",
                            "nullable": true
                          },
                          "airline": {
                            "type": "string",
                            "nullable": true
                          },
                          "book_url": {
                            "type": "string",
                            "description": "Affiliate booking link on Aviasales"
                          },
                          "compare_skyscanner": {
                            "type": "string",
                            "nullable": true,
                            "description": "The same trip on Skyscanner, to compare prices (not an affiliate link)"
                          }
                        }
                      }
                    },
                    "note": {
                      "type": "string"
                    },
                    "disclosure": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Plain-sentence error, safe to read out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Plain-sentence error, safe to read out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/places": {
      "get": {
        "operationId": "lookUpPlace",
        "summary": "Look up a city or airport code.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Place",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "country": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Plain-sentence error, safe to read out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Service status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}