{
  "openapi": "3.1.0",
  "info": {
    "title": "Columbia Masters Swim Team API",
    "version": "1.0.0",
    "description": "Public, read-only data for Columbia Masters Swim Team (COLM), a US Masters Swimming club. No authentication. CORS is open."
  },
  "servers": [
    {
      "url": "https://www.columbiamastersswim.org"
    }
  ],
  "paths": {
    "/api/content": {
      "get": {
        "operationId": "getClubContent",
        "summary": "Club information: practice schedule, upcoming events, board, FAQ, coaches, notices",
        "description": "Read live from the club's Google Sheet (falls back to the last saved copy; see `source`). Events include only those that haven't ended as of `asOf` (club-local date).",
        "parameters": [
          {
            "name": "section",
            "in": "query",
            "required": false,
            "description": "Return only this part of the document",
            "schema": {
              "type": "string",
              "enum": [
                "club",
                "alert",
                "about",
                "schedule",
                "events",
                "board",
                "faq",
                "coaches"
              ]
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "json (default) or md for the same content as markdown (identical to /llms.txt)",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "md"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Club content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "club": {
                      "type": "object"
                    },
                    "alert": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Site-wide notice, e.g. a pool closure"
                    },
                    "about": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "scheduleNote": {
                      "type": "string"
                    },
                    "schedule": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "day": {
                            "type": "string"
                          },
                          "time": {
                            "type": "string"
                          },
                          "location": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "day",
                          "time"
                        ]
                      }
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string",
                            "description": "YYYY-MM-DD"
                          },
                          "endDate": {
                            "type": "string",
                            "description": "YYYY-MM-DD or empty"
                          },
                          "title": {
                            "type": "string"
                          },
                          "location": {
                            "type": "string"
                          },
                          "notes": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "board": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "role": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "faq": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "question": {
                            "type": "string"
                          },
                          "answer": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "coaches": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "bio": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "asOf": {
                      "type": "string",
                      "description": "YYYY-MM-DD"
                    },
                    "source": {
                      "type": "string",
                      "enum": [
                        "sheet",
                        "fallback",
                        "partial"
                      ]
                    }
                  }
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/records": {
      "get": {
        "operationId": "queryRecords",
        "summary": "Club top times (team records) by event, course, gender, age group, year, swimmer or meet",
        "description": "Rows are each season's top club time per event/course/gender/age group. best=true keeps only the fastest matching swim per event/course/gender/age group (the club record when no year is given).",
        "parameters": [
          {
            "name": "event",
            "in": "query",
            "required": false,
            "description": "Distance and/or stroke, e.g. \"50 free\", \"200 IM\", \"backstroke\"",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "course",
            "in": "query",
            "required": false,
            "description": "Pool course",
            "schema": {
              "type": "string",
              "enum": [
                "scy",
                "scm",
                "lcm"
              ]
            }
          },
          {
            "name": "gender",
            "in": "query",
            "required": false,
            "description": "men or women",
            "schema": {
              "type": "string",
              "enum": [
                "men",
                "women"
              ]
            }
          },
          {
            "name": "ageGroup",
            "in": "query",
            "required": false,
            "description": "USMS age group, e.g. \"40-44\"",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "age",
            "in": "query",
            "required": false,
            "description": "Swimmer age; selects the matching age group",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Four-digit season year",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "swimmer",
            "in": "query",
            "required": false,
            "description": "Case-insensitive swimmer-name substring",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "meet",
            "in": "query",
            "required": false,
            "description": "Case-insensitive meet-name substring",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "best",
            "in": "query",
            "required": false,
            "description": "Only the fastest matching swim per event/course/gender/age group",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max rows (default 100)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "team": {
                      "type": "string"
                    },
                    "query": {
                      "type": "object"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "team": {
                            "type": "string"
                          },
                          "event": {
                            "type": "string"
                          },
                          "course": {
                            "type": "string"
                          },
                          "gender": {
                            "type": "string"
                          },
                          "ageGroup": {
                            "type": "string"
                          },
                          "time": {
                            "type": "string"
                          },
                          "swimmer": {
                            "type": "string"
                          },
                          "meet": {
                            "type": "string"
                          },
                          "year": {
                            "type": "string"
                          },
                          "timeInSeconds": {
                            "type": "number"
                          },
                          "date": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}