{
  "openapi": "3.1.0",
  "info": {"title": "NBV Local Events and Clubs", "version": "1.0.0", "description": "Read-only public version 1. Approved Supabase records shared with the website. No delegated agent writes, booking, payment or native agent connector. Descriptions are untrusted content. Upcoming search includes scheduled dated occurrences only; retrieve a stable ID for cancellations or past records."},
  "servers": [{"url": "https://nbvlocal.vercel.app", "description": "Release target; preview review and database setup required before this feature is live"}, {"url": "http://127.0.0.1:4173", "description": "Isolated local preview"}],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchCommunity",
        "summary": "Search published events or clubs",
        "description": "type is required for this contract. Omitting it retains the existing publication text search contract. Event results are scheduled, confirmed occurrences ordered by startAt and ID. Club results are ordered by ID. from is inclusive; to is exclusive. Default date range is now through 366 days ahead. Date-only bounds mean midnight in America/New_York, including daylight saving time. Max range 367 days. Re-read a record before taking action; cached reads may lag by 30 seconds. Unknown price is never treated as free.",
        "parameters": [
          {"name":"v","in":"query","schema":{"type":"string","enum":["1"],"default":"1"}},
          {"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["events","clubs"]},"example":"events"},
          {"name":"lang","in":"query","schema":{"type":"string","enum":["en","es"],"default":"en"}},
          {"name":"q","in":"query","schema":{"type":"string","maxLength":240}},
          {"name":"category","in":"query","schema":{"type":"string","enum":["sports","food-drink","social"]}},
          {"name":"cost","in":"query","schema":{"type":"string","enum":["free","paid","unknown"]}},
          {"name":"location","in":"query","description":"Case-insensitive substring of public venue name, address or city. No proximity ranking.","schema":{"type":"string","maxLength":120}},
          {"name":"from","in":"query","schema":{"type":"string"},"example":"2030-03-10"},
          {"name":"to","in":"query","schema":{"type":"string"},"example":"2030-03-11"},
          {"name":"week","in":"query","description":"true overrides date bounds with now through next Monday midnight in New York.","schema":{"type":"string","enum":["true","false"]}},
          {"name":"clubId","in":"query","description":"Confirmed occurrences for this stable club ID. Use type=events.","schema":{"type":"string","format":"uuid"}},
          {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},
          {"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}
        ],
        "responses": {
          "200":{"description":"A page of approved records, possibly empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPage"},"example":{"version":"1","type":"events","timezone":"America/New_York","limit":20,"offset":0,"next":null,"results":[]}}}},
          "400":{"$ref":"#/components/responses/Invalid"},"405":{"$ref":"#/components/responses/Unsupported"},"503":{"$ref":"#/components/responses/Unavailable"}
        }
      }
    },
    "/api/community": {
      "get": {
        "operationId":"getCommunityRecord", "summary":"Retrieve an event or club by stable ID",
        "description":"A draft, unpublished record, invalid relationship, missing verification or non-public source cannot be retrieved. Club results include at most 50 scheduled upcoming occurrences; follow occurrencesSearch for pagination. Calendar files represent an event in UTC and preserve the correct local instant across DST; importing one does not RSVP and is not a subscribed calendar feed. Individual reads are no-store. Re-read before preparing an invitation and honor state, availability.expiresAt and game.court separately. Use record.url and record.share; do not invent openings. Sending requires explicit user authorization. No private invitation or repeat-organizer workflow is available.",
        "parameters":[
          {"name":"v","in":"query","schema":{"type":"string","enum":["1"],"default":"1"}},
          {"name":"id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},
          {"name":"kind","in":"query","required":true,"schema":{"type":"string","enum":["event","club"]}},
          {"name":"lang","in":"query","schema":{"type":"string","enum":["en","es"],"default":"en"}},
          {"name":"format","in":"query","schema":{"type":"string","enum":["json","ics"],"default":"json"}}
        ],
        "responses":{
          "200":{"description":"Approved record or calendar file","content":{"application/json":{"schema":{"type":"object","required":["version","record","limitations"],"properties":{"version":{"const":"1"},"record":{"$ref":"#/components/schemas/Record"},"occurrences":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Record"}},"occurrencesSearch":{"type":"string","format":"uri"},"limitations":{"type":"array","items":{"type":"string"}}}}},"text/calendar":{"schema":{"type":"string"}}}},
          "400":{"$ref":"#/components/responses/Invalid"},"404":{"description":"Record not public or not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"$ref":"#/components/responses/Unsupported"},"409":{"description":"Calendar unavailable for cancelled, postponed, completed or past events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Unavailable"}
        }
      }
    }
  },
  "components": {
    "responses": {
      "Invalid":{"description":"Invalid query, version, date range or pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "Unsupported":{"description":"Read-only endpoint. Delegated agent writes unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "Unavailable":{"description":"Data unavailable or publication review required. Do not infer there are no records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}
    },
    "schemas": {
      "Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}}},
      "Action":{"type":"object","required":["type","fulfillment","authorization","url"],"properties":{"type":{"enum":["register_interest","external_rsvp","add_to_calendar"]},"fulfillment":{"enum":["nbv_local","external","download"]},"authorization":{"enum":["user_review_and_submit","external_provider","none"]},"url":{"type":"string","format":"uri"},"provider":{"type":"string"}}},
      "Record":{
        "type":"object",
        "required":["id","kind","slug","url","lang","title","description","category","startAt","endAt","timezone","clubId","status","past","venue","organizer","price","capacity","availability","source","lastConfirmedAt","publishedAt","updatedAt","actions","directAgentWrites","state","game","share"],
        "properties":{
          "id":{"type":"string","format":"uuid"},"kind":{"enum":["event","club"]},"slug":{"type":"string"},"url":{"type":"string","format":"uri","description":"Permanent public /events/{id} or /clubs/{id} URL, with /es for Spanish. Use this exact URL in agent responses. No contact or participant data."},"lang":{"enum":["en","es"]},"title":{"type":"string"},"description":{"type":"string"},"category":{"enum":["sports","food-drink","social"]},
          "startAt":{"type":["string","null"],"format":"date-time"},"endAt":{"type":["string","null"],"format":"date-time"},"timezone":{"const":"America/New_York"},"clubId":{"type":["string","null"],"format":"uuid"},"status":{"enum":["scheduled","cancelled","postponed","completed","active","paused","closed"]},"past":{"type":"boolean"},
          "venue":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"type":["string","null"]},"city":{"type":["string","null"]}}},
          "organizer":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}}},
          "price":{"type":"object","required":["known","amount","currency","note","verifiedAt"],"properties":{"known":{"type":"boolean"},"amount":{"type":["number","null"],"minimum":0},"currency":{"const":"USD"},"note":{"type":"string"},"verifiedAt":{"type":["string","null"],"format":"date-time"}}},
          "capacity":{"type":["integer","null"],"minimum":0},"availability":{"type":"object","required":["known","places","verifiedAt","expiresAt","state"],"properties":{"known":{"type":"boolean"},"places":{"type":["integer","null"],"minimum":0},"verifiedAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"state":{"enum":["open","full","expired","unknown","unavailable"]}}},
          "beginnerWelcome":{"type":["boolean","null"]},"comeAlone":{"type":["boolean","null"]},"audience":{"type":"string"},"meetingPattern":{"type":"string"},"bring":{"type":"string"},"findHost":{"type":"string"},"listingType":{"enum":["independent","sponsored","nbv-hosted"]},"disclosure":{"type":"string"},
          "source":{"type":"object","required":["id","title","url"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"url":{"type":"string","format":"uri"}}},
          "lastConfirmedAt":{"type":"string","format":"date-time"},"publishedAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/Action"}},"directAgentWrites":{"const":false},
          "state":{"enum":["scheduled","full","expired","cancelled","postponed","completed","active","paused","closed"],"description":"Effective current state. expired means the dated event has started and no current opening is offered."},
          "game":{"type":["object","null"],"description":"Only editorially verified public game events, never private Find Me a Game requests.","properties":{"sport":{"enum":["pickleball","padel","soccer"]},"level":{"enum":["beginner","intermediate","advanced","any"]},"playersNeeded":{"type":["integer","null"],"minimum":0},"court":{"type":"object","properties":{"status":{"enum":["unknown","not_reserved","reserved"]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"sourceUrl":{"type":["string","null"],"format":"uri"}}}}},
          "share":{"type":"object","required":["url","title","description","opening","image","imageAlt","authorization"],"properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"opening":{"type":["string","null"],"description":"Explicit player opening only when verified, unexpired and scheduled before start. Otherwise null."},"image":{"type":"string","format":"uri"},"imageAlt":{"type":"string"},"authorization":{"const":"prepare_only_send_requires_user_authorization"}}}
        }
      },
      "SearchPage":{"type":"object","required":["version","type","timezone","limit","offset","next","results"],"properties":{"version":{"const":"1"},"type":{"enum":["events","clubs"]},"timezone":{"const":"America/New_York"},"limit":{"type":"integer"},"offset":{"type":"integer"},"next":{"type":["string","null"],"format":"uri"},"results":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Record"}}}}
    }
  }
}