{
 "openapi": "3.1.0",
 "info": {
  "title": "Valley Seeds API",
  "version": "1.0.0",
  "description": "Live state of the Santa Ynez Valley twin. open_now is computed at request time from each venue's hours; only status 'verified' hours are confirmed by an independent source."
 },
 "servers": [
  {
   "url": "https://valleyseeds.co/api/v1"
  }
 ],
 "paths": {
  "/status": {
   "get": {
    "summary": "Data freshness and source health",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/towns": {
   "get": {
    "summary": "Live towns",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/venues": {
   "get": {
    "summary": "Venues",
    "parameters": [
     {
      "name": "town",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "open_now",
      "in": "query",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "serves",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "wine",
        "beer",
        "cider",
        "cocktails",
        "spirits",
        "coffee",
        "food"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "count": {
           "type": "integer"
          },
          "venues": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "town": {
              "type": "string"
             },
             "category": {
              "type": "string"
             },
             "open_now": {
              "type": [
               "boolean",
               "null"
              ]
             },
             "open_now_basis": {
              "type": "string"
             },
             "status": {
              "type": "string",
              "enum": [
               "verified",
               "listed",
               "unknown"
              ]
             },
             "confidence": {
              "type": "number"
             },
             "hours": {
              "type": "array",
              "items": {
               "type": "object"
              }
             },
             "offerings": {
              "type": [
               "object",
               "null"
              ]
             },
             "location": {
              "type": [
               "object",
               "null"
              ]
             },
             "map_url": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/venues/{id}": {
   "get": {
    "summary": "One venue",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "string"
          },
          "name": {
           "type": "string"
          },
          "town": {
           "type": "string"
          },
          "category": {
           "type": "string"
          },
          "open_now": {
           "type": [
            "boolean",
            "null"
           ]
          },
          "open_now_basis": {
           "type": "string"
          },
          "status": {
           "type": "string",
           "enum": [
            "verified",
            "listed",
            "unknown"
           ]
          },
          "confidence": {
           "type": "number"
          },
          "hours": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "offerings": {
           "type": [
            "object",
            "null"
           ]
          },
          "location": {
           "type": [
            "object",
            "null"
           ]
          },
          "map_url": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/events": {
   "get": {
    "summary": "Upcoming public events",
    "parameters": [
     {
      "name": "town",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "count": {
           "type": "integer"
          },
          "events": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "town": {
              "type": "string"
             },
             "start": {
              "type": "string",
              "format": "date-time"
             },
             "end": {
              "type": [
               "string",
               "null"
              ]
             },
             "url": {
              "type": [
               "string",
               "null"
              ]
             },
             "availability": {
              "type": [
               "string",
               "null"
              ],
              "enum": [
               "InStock",
               "SoldOut",
               null
              ]
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/events/submissions": {
   "post": {
    "summary": "Submit an event for review",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "name",
         "category",
         "town",
         "date",
         "start_time",
         "venue_name",
         "organizer",
         "contact_email",
         "consent"
        ],
        "properties": {
         "name": {
          "type": "string"
         },
         "category": {
          "type": "string",
          "enum": [
           "live-music",
           "wine-tasting",
           "food",
           "class",
           "market",
           "festival",
           "art",
           "family",
           "other"
          ]
         },
         "town": {
          "type": "string"
         },
         "date": {
          "type": "string",
          "format": "date"
         },
         "start_time": {
          "type": "string"
         },
         "end_time": {
          "type": "string"
         },
         "venue_name": {
          "type": "string"
         },
         "address": {
          "type": "string"
         },
         "url": {
          "type": "string"
         },
         "description": {
          "type": "string"
         },
         "organizer": {
          "type": "string"
         },
         "contact_email": {
          "type": "string"
         },
         "consent": {
          "type": "boolean"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Received, pending review"
     },
     "400": {
      "description": "Invalid"
     },
     "429": {
      "description": "Rate limited"
     }
    }
   }
  }
 }
}