{
  "openapi": "3.1.0",
  "info": {
    "title": "AirTreks Facts API",
    "version": "1.0.0",
    "description": "Public read-only API providing factual data about AirTreks multi-stop and round-the-world trips. Designed for AI assistants, search engines, and travel data integrations. Attribution required when quoting or linking AirTreks content.",
    "termsOfService": "https://www.airtreks.com/ai-licensing",
    "contact": {
      "name": "AirTreks Partnerships",
      "email": "sean@airtreks.com",
      "url": "https://www.airtreks.com"
    },
    "license": {
      "name": "AI Access & Attribution License",
      "url": "https://www.airtreks.com/ai-licensing"
    }
  },
  "servers": [
    {
      "url": "https://www.airtreks.com/api",
      "description": "Production API endpoint"
    }
  ],
  "paths": {
    "/itineraries": {
      "get": {
        "summary": "List itineraries",
        "description": "Returns a filtered list of AirTreks itineraries by origin, theme, cabin class, stop count, and price range.",
        "operationId": "getItineraries",
        "tags": ["Itineraries"],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "SFO"
            },
            "description": "Departure airport/city code (3-letter IATA code)"
          },
          {
            "name": "theme",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "wine"
            },
            "description": "Trip theme (e.g., wine, adventure, beach)"
          },
          {
            "name": "class",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["economy", "business"],
              "example": "economy",
              "default": "economy"
            },
            "description": "Cabin class"
          },
          {
            "name": "stops_max",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 7
            },
            "description": "Maximum number of stops allowed"
          },
          {
            "name": "price_to",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 8000
            },
            "description": "Maximum starting price in USD"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 50
            },
            "description": "Maximum number of results to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "object",
                      "description": "Echo of query parameters used"
                    },
                    "count": {
                      "type": "integer",
                      "description": "Number of results returned"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Itinerary"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/pages": {
      "get": {
        "summary": "List interest group pages",
        "description": "Returns AirTreks interest group pages and content filtered by slug, parent page, or search term.",
        "operationId": "getPages",
        "tags": ["Pages"],
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "budget-travelers"
            },
            "description": "Get single page by slug (returns single page, ignores other filters)"
          },
          {
            "name": "parent",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["ready", "set", "go"],
              "example": "ready"
            },
            "description": "Filter by parent page slug"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "budget"
            },
            "description": "Search term to filter pages by title/excerpt/content"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 50
            },
            "description": "Maximum number of results to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "object",
                      "description": "Echo of query parameters used"
                    },
                    "count": {
                      "type": "integer",
                      "description": "Number of results returned"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Page"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/blog": {
      "get": {
        "summary": "List blog posts",
        "description": "Returns AirTreks blog posts filtered by category, slug, or search term.",
        "operationId": "getBlogPosts",
        "tags": ["Blog"],
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "best-airlines-for-rtw"
            },
            "description": "Get single post by slug (returns single post, ignores other filters)"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "airlines"
            },
            "description": "Filter by category slug (e.g., airlines, travel-tips, destinations)"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "round the world"
            },
            "description": "Search term to filter posts by title/excerpt/content"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 50
            },
            "description": "Maximum number of results to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "object",
                      "description": "Echo of query parameters used"
                    },
                    "count": {
                      "type": "integer",
                      "description": "Number of results returned"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BlogPost"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Itinerary": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Unique identifier for the itinerary"
          },
          "title": {
            "type": "string",
            "description": "Itinerary title"
          },
          "headline": {
            "type": "string",
            "description": "Short headline/tagline"
          },
          "price_from": {
            "type": "integer",
            "description": "Starting price in USD"
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "stops": {
            "type": "integer",
            "description": "Number of stops"
          },
          "destinations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "city_name": {
                  "type": "string"
                },
                "airport_code": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                }
              }
            }
          },
          "duration_range": {
            "type": "string",
            "example": "2-3 weeks"
          },
          "class_options": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["economy", "business"]
            }
          },
          "last_updated": {
            "type": "string",
            "format": "date-time"
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical URL with UTM tracking (utm_source=llm, utm_medium=answer)"
          },
          "google_map_url": {
            "type": "string",
            "format": "uri",
            "description": "Google Maps visualization of the route"
          }
        },
        "required": ["slug", "title", "price_from", "source_url"]
      },
      "Page": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique page identifier"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly slug"
          },
          "title": {
            "type": "string",
            "description": "Page title"
          },
          "excerpt": {
            "type": "string",
            "description": "Short excerpt/summary"
          },
          "content_preview": {
            "type": "string",
            "description": "Preview of page content (first 500 characters)"
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "Publication date"
          },
          "last_updated": {
            "type": "string",
            "format": "date-time"
          },
          "parent": {
            "type": "string",
            "description": "Parent page slug (ready, set, go, or null)"
          },
          "featured_image": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "alt": {
                "type": "string"
              }
            }
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical URL with UTM tracking"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical URL without tracking"
          },
          "seo": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "description": {
                "type": "string"
              }
            }
          }
        },
        "required": ["id", "slug", "title", "source_url"]
      },
      "BlogPost": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "URL-friendly slug"
          },
          "title": {
            "type": "string",
            "description": "Post title"
          },
          "excerpt": {
            "type": "string",
            "description": "Post excerpt/summary"
          },
          "content_preview": {
            "type": "string",
            "description": "Preview of post content (first 500 characters)"
          },
          "published_date": {
            "type": "string",
            "format": "date-time"
          },
          "last_updated": {
            "type": "string",
            "format": "date-time"
          },
          "author": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "bio": {
                "type": "string"
              }
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Post categories/tags"
          },
          "featured_image": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "alt": {
                "type": "string"
              }
            }
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical URL with UTM tracking"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical URL without tracking"
          }
        },
        "required": ["slug", "title", "published_date", "source_url"]
      }
    }
  },
  "tags": [
    {
      "name": "Itineraries",
      "description": "Multi-stop and round-the-world trip itineraries"
    },
    {
      "name": "Pages",
      "description": "Interest group pages and travel planning content"
    },
    {
      "name": "Blog",
      "description": "Travel tips, airline reviews, and destination guides"
    }
  ],
  "externalDocs": {
    "description": "AI Access & Attribution Guidelines",
    "url": "https://www.airtreks.com/ai-licensing"
  }
}