{
  "openapi": "3.1.0",
  "info": {
    "title": "321 Daily API",
    "version": "1.0.0",
    "description": "Free public API for Brevard County, Florida (Space Coast) local data. News, rocket launches, beach conditions, events, and fishing reports.",
    "contact": {
      "email": "help@321daily.com",
      "url": "https://321daily.com"
    },
    "license": {
      "name": "Free for non-commercial use"
    }
  },
  "servers": [
    {
      "url": "https://321daily.com/api/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/briefing": {
      "get": {
        "operationId": "getDailyBriefing",
        "summary": "Get today's complete daily briefing",
        "description": "Returns top news, upcoming launches, beach conditions, local events, and fishing report in one call.",
        "parameters": [
          {
            "name": "sections",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated: news,launches,beach,events,fishing. Default: all."
          },
          {
            "name": "news_limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 5,
              "maximum": 20
            },
            "description": "Number of news articles"
          },
          {
            "name": "events_limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 5,
              "maximum": 20
            },
            "description": "Number of events"
          }
        ],
        "responses": {
          "200": {
            "description": "Daily briefing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Briefing"
                }
              }
            }
          }
        }
      }
    },
    "/articles": {
      "get": {
        "operationId": "getArticles",
        "summary": "Get latest news articles",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "Local",
                "Government",
                "Space & Tech",
                "Sports",
                "Schools",
                "Development",
                "Weather",
                "Food & Drink",
                "Outdoors",
                "Arts & Culture",
                "Business"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search title and summary"
          },
          {
            "name": "balanced",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "When true, applies launch-mix balancing to keep launch-heavy stories from dominating the main feed."
          },
          {
            "name": "launch_cap",
            "in": "query",
            "schema": {
              "type": "number",
              "default": 0.12,
              "minimum": 0.05,
              "maximum": 0.5
            },
            "description": "Maximum allowed launch share when balanced=true."
          },
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 120,
              "minimum": 40,
              "maximum": 300
            },
            "description": "Candidate pool size used for balanced feed selection."
          }
        ],
        "responses": {
          "200": {
            "description": "Articles list",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/launches": {
      "get": {
        "operationId": "getLaunches",
        "summary": "Get upcoming rocket launches from Cape Canaveral",
        "responses": {
          "200": {
            "description": "Launches list",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/beach": {
      "get": {
        "operationId": "getBeachReport",
        "summary": "Get current beach conditions for Space Coast beaches",
        "responses": {
          "200": {
            "description": "Beach conditions",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/events-live": {
      "get": {
        "operationId": "getEvents",
        "summary": "Get upcoming events in Brevard County",
        "responses": {
          "200": {
            "description": "Events list",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/fishing": {
      "get": {
        "operationId": "getFishingReport",
        "summary": "Get current fishing conditions and species activity",
        "responses": {
          "200": {
            "description": "Fishing report",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Briefing": {
        "type": "object",
        "properties": {
          "meta": {
            "type": "object",
            "properties": {
              "version": {
                "type": "string"
              },
              "generated_at": {
                "type": "string",
                "format": "date-time"
              },
              "region": {
                "type": "string"
              },
              "source": {
                "type": "string"
              }
            }
          },
          "news": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Article"
            }
          },
          "launches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Launch"
            }
          },
          "beach": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Beach"
            }
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          },
          "fishing": {
            "type": "object"
          }
        }
      },
      "Article": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Launch": {
        "type": "object",
        "properties": {
          "mission": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "vehicle": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date-time"
          },
          "pad": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "webcast_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Beach": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "surf": {
            "type": "string"
          },
          "water_temp_f": {
            "type": "number"
          },
          "wind": {
            "type": "string"
          },
          "tide": {
            "type": "string"
          },
          "uv_index": {
            "type": "number"
          },
          "flag": {
            "type": "string"
          },
          "flag_meaning": {
            "type": "string"
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "start": {
            "type": "string",
            "format": "date-time"
          },
          "category": {
            "type": "string"
          },
          "price": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}