{
  "openapi": "3.0.3",
  "info": {
    "title": "ClubATX API",
    "version": "1.0.0",
    "description": "Manage athletes, teams, fixtures, and training sessions with dashboard-issued API keys. Athlete and training booking responses can contain personal data."
  },
  "servers": [
    {
      "url": "https://api.clubathletix.com",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/images/headshot": {
      "post": {
        "tags": [
          "Images"
        ],
        "operationId": "createHeadshot",
        "summary": "Create a transparent headshot with a black shirt",
        "description": "Requires a read_write API key. Edits a PNG, JPEG, or WebP source of at most 10 MB from the configured Vercel Blob store using OpenAI. Saves a new PNG in the same folder and store with matching public/private access; preserves the source. Requests preservation of identity, face, head, ears, and hair; generative edits may introduce small changes. Optionally supply athlete_slug to replace that athlete\u2019s photo_url after upload. With only athlete_slug, the current athlete photo is the source; source_url overrides it when both are supplied. Unknown athletes fail before generation. Concurrent photo changes return 409 without replacing the record. Database update failures return 500 with an unconfirmed update. The saved PNG remains available in data on either error; original Blobs are retained.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "source_url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048,
                    "description": "Direct HTTPS URL in the configured public or private Blob store; no query or fragment."
                  },
                  "athlete_slug": {
                    "type": "string",
                    "maxLength": 100,
                    "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
                    "description": "Optional athlete to update. Uses their current photo_url as source when source_url is omitted."
                  }
                },
                "anyOf": [
                  {
                    "required": [
                      "source_url"
                    ]
                  },
                  {
                    "required": [
                      "athlete_slug"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "PNG saved in the source folder and store",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "source_url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "pathname": {
                          "type": "string"
                        },
                        "content_type": {
                          "type": "string",
                          "enum": [
                            "image/png"
                          ]
                        },
                        "athlete": {
                          "type": "object",
                          "description": "Present only when athlete_slug was supplied and its record updated.",
                          "properties": {
                            "slug": {
                              "type": "string"
                            },
                            "photo_url": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or source store"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Write access required"
          },
          "404": {
            "description": "Athlete or source image not found"
          },
          "413": {
            "description": "Source exceeds 10 MB"
          },
          "415": {
            "description": "Unsupported or mismatched image type"
          },
          "429": {
            "description": "OpenAI rate limit"
          },
          "502": {
            "description": "Image editing or upload failed"
          },
          "503": {
            "description": "Image editing or storage not configured/available"
          },
          "504": {
            "description": "Processing timed out"
          },
          "409": {
            "description": "PNG saved, but athlete was removed or photo changed during processing; record not replaced",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "description": "Generated PNG metadata when upload succeeded",
                      "properties": {
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "pathname": {
                          "type": "string"
                        },
                        "source_url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "content_type": {
                          "type": "string",
                          "enum": [
                            "image/png"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Athlete lookup failed, or PNG saved but athlete photo update could not be confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "description": "Generated PNG metadata when upload succeeded",
                      "properties": {
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "pathname": {
                          "type": "string"
                        },
                        "source_url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "content_type": {
                          "type": "string",
                          "enum": [
                            "image/png"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/fixtures/{id}/performance": {
      "get": {
        "tags": [
          "Fixtures"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fixture performance, including nullable extended player metrics. PUT verifies supplied metrics by reading the saved rows back.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fixture_id": {
                      "type": "integer"
                    },
                    "fixture": {
                      "type": "object"
                    },
                    "match_stats": {
                      "type": "object",
                      "nullable": true
                    },
                    "players": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "passes": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "completed_passes": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "dribbles": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "interceptions": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "saves": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "pass_success_rate_percent": {
                            "type": "number",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 100,
                            "multipleOf": 0.01
                          }
                        }
                      }
                    },
                    "unresolved_count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Write access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Fixture not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Canonical teams do not match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Save or verification failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "API unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "getFixturePerformance",
        "summary": "Read consolidated fixture performance"
      },
      "put": {
        "tags": [
          "Fixtures"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fixture performance, including nullable extended player metrics. PUT verifies supplied metrics by reading the saved rows back.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fixture_id": {
                      "type": "integer"
                    },
                    "fixture": {
                      "type": "object"
                    },
                    "match_stats": {
                      "type": "object",
                      "nullable": true
                    },
                    "players": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "passes": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "completed_passes": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "dribbles": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "interceptions": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "saves": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 32767
                          },
                          "pass_success_rate_percent": {
                            "type": "number",
                            "nullable": true,
                            "minimum": 0,
                            "maximum": 100,
                            "multipleOf": 0.01
                          }
                        }
                      }
                    },
                    "unresolved_count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Write access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Fixture not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Canonical teams do not match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Save or verification failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "API unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "putFixturePerformance",
        "summary": "Import consolidated fixture performance",
        "description": "Requires read_write access. Atomically replaces the supplied provider player set and saves team metrics and official scores. Include passes, completed_passes and pass_success_rate_percent when verified; percentages never imply a count.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FixturePerformanceInput"
              }
            }
          }
        }
      }
    },
    "/v1/athletes/{slug}/trend": {
      "get": {
        "tags": [
          "Athletes"
        ],
        "operationId": "getPlayerTrend",
        "summary": "Get player metric trend",
        "description": "Returns the newest limit distinct athlete-linked matches in chronological order, including team/opponent names, score and match-video URL. Exactly one analytics row per match: source filters the provider; otherwise prefer veo, then source alphabetically, team ID and jersey. Providers are never merged. Inclusive fixture-date filters apply before selection. Missing measurements remain null. per_60 normalizes count and distance metrics with exact played_seconds; zero or missing playing time yields null. Speeds, percentages and time are not normalized. Comparison splits the returned distinct matches into the latest window_size matches and preceding window_size matches before filtering by provider. Each metric needs window_size measured samples in both periods for change and direction; partial averages and counts remain available. Normalized period averages are weighted by measured playing seconds. minutes_played is derived from played_seconds, never tracked_minutes. Summary retains per-provider first-to-latest changes. Percentage change is null with a zero baseline. Direction describes numeric change, not performance quality. Unlinked or undated matches and analytics rows without recorded played_seconds are excluded before provider selection and match limiting. A recorded zero is retained; tracked_minutes alone is not actual playing time. This dashboard-key endpoint is intended for trusted backend integration; an athlete frontend must enforce athlete authorization on its own server.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": "Maximum distinct matches, not provider rows."
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 50,
              "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "window_size",
            "in": "query",
            "description": "Number of matches per comparison period. Request at least twice this limit for complete comparisons.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 3
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent measurements and provider-specific summaries",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlayerTrend"
                }
              }
            }
          },
          "400": {
            "description": "Invalid filters"
          },
          "401": {
            "description": "Invalid or missing API key"
          },
          "404": {
            "description": "Athlete not found"
          },
          "500": {
            "description": "Lookup failed"
          },
          "503": {
            "description": "API service unavailable"
          }
        }
      }
    },
    "/v1/athletes": {
      "get": {
        "tags": [
          "Athletes"
        ],
        "operationId": "listAthletes",
        "summary": "List athletes",
        "description": "Returns athlete records ordered by name. Pass search for typo-tolerant matching across name, email, and slug.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10000,
              "default": 0
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Optional fuzzy search across athlete name, email, and slug.",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of athletes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AthleteList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "post": {
        "tags": [
          "Athletes"
        ],
        "operationId": "createAthlete",
        "summary": "Create an athlete",
        "description": "Requires an API key with read and write access.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAthlete"
              },
              "example": {
                "slug": "example-athlete",
                "first_name": "Example"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Athlete created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AthleteResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/athletes/{slug}": {
      "parameters": [
        {
          "name": "slug",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "The athlete's unique slug"
        }
      ],
      "get": {
        "tags": [
          "Athletes"
        ],
        "operationId": "getAthlete",
        "summary": "Get an athlete",
        "responses": {
          "200": {
            "description": "Athlete found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AthleteResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "patch": {
        "tags": [
          "Athletes"
        ],
        "operationId": "updateAthlete",
        "summary": "Update an athlete",
        "description": "Requires an API key with read and write access. Slug cannot be changed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAthlete"
              },
              "example": {
                "last_name": "Athlete"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Athlete updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AthleteResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/v1/organizations": {
      "get": {
        "tags": ["Organizations"],
        "operationId": "listOrganizations",
        "summary": "List organizations",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } },
          { "name": "search", "in": "query", "description": "Matches organization names and short names.", "schema": { "type": "string", "maxLength": 120 } }
        ],
        "responses": {
          "200": { "description": "A page of organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationList" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "description": "Could not list organizations" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "post": {
        "tags": ["Organizations"],
        "operationId": "createOrganization",
        "summary": "Create an organization",
        "description": "Requires an API key with read and write access.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganization" } } } },
        "responses": {
          "201": { "description": "Organization created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/organizations/{id}": {
      "parameters": [
        { "name": "id", "in": "path", "required": true, "description": "Organization UUID.", "schema": { "type": "string", "format": "uuid" } }
      ],
      "get": {
        "tags": ["Organizations"], "operationId": "getOrganization", "summary": "Get an organization",
        "responses": {
          "200": { "description": "Organization found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "patch": {
        "tags": ["Organizations"], "operationId": "updateOrganization", "summary": "Update an organization", "description": "Requires an API key with read and write access.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganization" } } } },
        "responses": {
          "200": { "description": "Organization updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "delete": {
        "tags": ["Organizations"], "operationId": "deleteOrganization", "summary": "Delete an organization", "description": "Requires an API key with read and write access. Organizations referenced by teams cannot be deleted.",
        "responses": {
          "200": { "description": "Organization deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/organizations/{id}/crest": {
      "parameters": [
        { "name": "id", "in": "path", "required": true, "description": "Organization UUID.", "schema": { "type": "string", "format": "uuid" } }
      ],
      "post": {
        "tags": ["Organizations"], "operationId": "uploadOrganizationCrest", "summary": "Upload an organization crest", "description": "Uploads a PNG or JPEG up to 5 MB. The organization must have a short name, which is lowercased and used in the Blob path.",
        "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary" } } } } } },
        "responses": {
          "200": { "description": "Crest uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" },
          "413": { "description": "Crest exceeds 5 MB" }, "415": { "description": "Unsupported image type" }, "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "delete": {
        "tags": ["Organizations"], "operationId": "deleteOrganizationCrest", "summary": "Delete an organization crest", "description": "Deletes the Blob and clears crest_url.",
        "responses": {
          "200": { "description": "Crest deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/teams": {
      "get": {
        "tags": ["Teams"],
        "operationId": "listTeams",
        "summary": "List teams",
        "description": "Returns teams ordered by name. Search matches the team name, and organization_id filters by an organization UUID or the literal value null.",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } },
          { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 120 } },
          { "name": "organization_id", "in": "query", "description": "Organization UUID, or null for teams without an organization.", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "A page of teams", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamList" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "description": "Could not list teams" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "post": {
        "tags": ["Teams"],
        "operationId": "createTeam",
        "summary": "Create a team",
        "description": "Requires an API key with read and write access. If crest_url is omitted or null, the selected organization's crest_url is copied to the new team.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeam" } } } },
        "responses": {
          "201": { "description": "Team created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/teams/{name}": {
      "parameters": [
        { "name": "name", "in": "path", "required": true, "description": "The team's exact, URL-encoded name.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }
      ],
      "get": {
        "tags": ["Teams"], "operationId": "getTeam", "summary": "Get a team",
        "responses": {
          "200": { "description": "Team found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "patch": {
        "tags": ["Teams"], "operationId": "updateTeam", "summary": "Update a team", "description": "Requires an API key with read and write access. Include name to rename the team.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeam" } } } },
        "responses": {
          "200": { "description": "Team updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "delete": {
        "tags": ["Teams"], "operationId": "deleteTeam", "summary": "Delete a team", "description": "Requires an API key with read and write access.",
        "responses": {
          "200": { "description": "Team deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures": {
      "get": {
        "tags": ["Fixtures"],
        "operationId": "findFixturesByDate",
        "summary": "Find matches by date",
        "description": "Returns fixtures whose match_date equals the requested calendar date, ordered by start_time and id. Each fixture includes home_roster and away_roster arrays of linked lineup athletes. Roster entries contain only slug and position; lineup rows without an athlete slug are omitted.",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "description": "Match date in YYYY-MM-DD format",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Fixtures on the requested date",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FixtureList" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": {
            "description": "Fixture search failed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "post": {
        "tags": ["Fixtures"],
        "operationId": "createFixture",
        "summary": "Create a league fixture",
        "description": "Creates a fixture from existing division, division-team, and optional field records. end_time is calculated from start_time, two halves, and the half-time break. Requires a read and write API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/CreateFixture" } }
          }
        },
        "responses": {
          "201": { "description": "Fixture created" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not create fixture" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures/{id}": {
      "parameters": [
        { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Fixture ID" }
      ],
      "get": {
        "tags": ["Fixtures"],
        "operationId": "getFixtureImportContext",
        "summary": "Get canonical fixture and lineup context",
        "description": "Returns the fixture, canonical home and away team names, and jersey-bearing lineup rows used to confirm an analytics import.",
        "responses": {
          "200": { "description": "Canonical fixture context" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not retrieve fixture context" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "patch": {
        "tags": ["Fixtures"],
        "operationId": "updateFixture",
        "summary": "Update a fixture",
        "description": "Updates selected fixture fields and revalidates the division, teams, field size, venue, and schedule. When changing start_time or half_duration_minutes, half_time_break_minutes is required so end_time can be recalculated. Requires a read and write API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFixture" } }
          }
        },
        "responses": {
          "200": { "description": "Fixture updated" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not update fixture" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "delete": {
        "tags": ["Fixtures"],
        "operationId": "deleteFixture",
        "summary": "Delete a fixture",
        "description": "Permanently deletes a fixture. Related rows with cascading foreign keys are also deleted; restrictive references return a conflict. Requires a read and write API key.",
        "responses": {
          "200": { "description": "Fixture deleted" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not delete fixture" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures/{id}/finalize": {
      "post": {
        "tags": ["Fixtures"],
        "operationId": "finalizeFixture",
        "summary": "Finalize a fixture result",
        "description": "Calculates the official home and away scores from the fixture's saved goal events and records the finalization time. Repeating the request recalculates the finalized result from the current saved events. Requires a read and write API key.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Fixture ID" }
        ],
        "responses": {
          "200": {
            "description": "Fixture finalized",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FixtureFinalizationResult" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": {
            "description": "Could not finalize the fixture result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures/{id}/formation": {
      "patch": {
        "tags": ["Fixtures"],
        "operationId": "changeFixtureFormation",
        "summary": "Change a fixture team's formation",
        "description": "Atomically returns the team's previous athletes and positions, saves a new formation, and clears all positions while keeping the athletes as substitutes. Requires a read and write API key.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Fixture ID" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["side", "formation"],
                "properties": {
                  "side": { "type": "string", "enum": ["home", "away"] },
                  "formation": { "type": "string", "minLength": 1, "maxLength": 80 }
                }
              },
              "example": { "side": "home", "formation": "4-3-3" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Formation changed and previous lineup returned",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormationChangeResult" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not change fixture formation" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures/{id}/feedback-url": {
      "get": {
        "tags": ["Fixtures"],
        "operationId": "getFixtureFeedbackUrl",
        "summary": "Get a signed athlete and coach feedback link",
        "description": "Returns the signed public match-page URL athletes and coaches use to submit fixture feedback for one fixture side. Requires a read and write API key because the URL authorizes feedback submissions.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Fixture ID" },
          { "name": "side", "in": "query", "required": true, "schema": { "type": "string", "enum": ["home", "away"] }, "description": "Lineup to open first" }
        ],
        "responses": {
          "200": {
            "description": "Signed fixture feedback link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["fixture_id", "fixture_slug", "side", "url"],
                      "properties": {
                        "fixture_id": { "type": "integer" },
                        "fixture_slug": { "type": "string", "readOnly": true },
                        "side": { "type": "string", "enum": ["home", "away"] },
                        "url": { "type": "string", "format": "uri" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not create fixture feedback link" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures/{id}/stats": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Fixture ID",
          "schema": { "type": "integer", "minimum": 1 }
        }
      ],
      "get": {
        "tags": ["Fixtures"],
        "operationId": "getFixtureMatchStats",
        "summary": "Get a fixture's team comparison statistics",
        "description": "Returns the saved match-stat payload directly. The teams object contains exactly two entries keyed by team name.",
        "responses": {
          "200": {
            "description": "The graph-ready team comparison",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchStats" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "description": "Could not retrieve fixture match stats" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "put": {
        "tags": ["Fixtures"],
        "operationId": "putFixtureMatchStats",
        "summary": "Save a fixture's team comparison statistics",
        "description": "Creates or fully replaces the fixture's match-stat payload. Requires a read and write API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/MatchStats" } }
          }
        },
        "responses": {
          "200": {
            "description": "The saved graph-ready team comparison",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchStats" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "description": "Could not save fixture match stats" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "patch": {
        "tags": ["Fixtures"],
        "operationId": "replaceFixtureKeyEvents",
        "summary": "Replace a fixture's complete Veo event feed",
        "description": "Preserves the saved match and teams objects and replaces the entire key_events array. The fixture must already have a complete stats payload. Requires a read and write API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["key_events"],
                "properties": {
                  "key_events": { "type": "array", "items": { "$ref": "#/components/schemas/KeyEvent" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "The saved complete match analytics payload" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not save fixture match stats" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures/{id}/playing-time": {
      "parameters": [
        { "name": "id", "in": "path", "required": true, "description": "Fixture ID", "schema": { "type": "integer", "minimum": 1 } },
        { "name": "side", "in": "query", "required": true, "description": "Fixture team whose playing time is being read or saved", "schema": { "type": "string", "enum": ["home", "away"] } }
      ],
      "get": {
        "tags": ["Fixtures"],
        "operationId": "getFixturePlayingTime",
        "summary": "Get player playing time for one fixture team",
        "description": "Returns saved playing-time records in descending duration order, with exact seconds and the current lineup identity for each player.",
        "responses": {
          "200": { "description": "Saved player playing time", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayingTimeResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not retrieve fixture playing time" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "put": {
        "tags": ["Fixtures"],
        "operationId": "putFixturePlayingTime",
        "summary": "Save player playing time for one fixture team",
        "description": "Atomically upserts the supplied players by their unique fixture jersey numbers. Existing records for omitted players are preserved. Durations are exact whole seconds. Requires a read and write API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PlayingTimeInput" },
              "example": {
                "source": "veo",
                "players": [
                  { "jersey_number": 1, "played_seconds": 4810 },
                  { "jersey_number": 11, "played_seconds": 1600 }
                ]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Saved and verified player playing time", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayingTimeResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not save or verify fixture playing time" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures/{id}/player-stats": {
      "parameters": [
        { "name": "id", "in": "path", "required": true, "description": "Fixture ID", "schema": { "type": "integer", "minimum": 1 } },
        { "name": "side", "in": "query", "required": true, "description": "Fixture team whose player statistics are being read or saved", "schema": { "type": "string", "enum": ["home", "away"] } }
      ],
      "get": {
        "tags": ["Fixtures"],
        "operationId": "getFixturePlayerStats",
        "summary": "Get player statistics for one fixture team",
        "description": "Returns per-player Veo metrics linked to the current fixture lineup and canonical athlete.",
        "responses": {
          "200": { "description": "Saved player statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerStatsResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not retrieve fixture player statistics" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "put": {
        "tags": ["Fixtures"],
        "operationId": "putFixturePlayerStats",
        "summary": "Save player statistics for one fixture team",
        "description": "Upserts complete player-stat rows by unique fixture jersey and verifies every saved value. Existing rows for omitted players are preserved. Requires a read and write API key.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerStatsInput" } } }
        },
        "responses": {
          "200": { "description": "Saved and verified player statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerStatsResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not save or verify fixture player statistics" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures/{id}/athletes": {
      "get": {
        "tags": ["Fixtures"],
        "operationId": "listFixtureLineupPlayers",
        "summary": "List one fixture team's lineup players",
        "description": "Returns lineup rows, including their IDs and players without an athlete slug. Requires a read API key.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Fixture ID" },
          { "name": "side", "in": "query", "required": true, "schema": { "type": "string", "enum": ["home", "away"] } }
        ],
        "responses": {
          "200": { "description": "Lineup rows for the selected fixture team" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not retrieve fixture lineup" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "post": {
        "tags": ["Fixtures"],
        "operationId": "addFixtureAthlete",
        "summary": "Add athletes to fixture teams",
        "description": "The side query parameter selects the home or away fixture team for all athletes in the request. Accepts one athlete object or an array of athlete objects. Each slug and starting position may appear only once in an array. Adds or replaces each athlete in array order. Without position the athlete is a substitute; with a position the athlete is a starter and the current starter in that position moves to substitutes. An athlete already on this fixture is moved to the requested side and position. Array requests return one result per athlete, including each result's status. If a database operation fails, the response includes failed_index and completed results; earlier changes are not rolled back. Requires a read and write API key.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Fixture ID" },
          { "name": "side", "in": "query", "required": true, "schema": { "type": "string", "enum": ["home", "away"] }, "description": "Fixture team for every athlete in the request" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/FixtureAthleteInput" },
                  { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FixtureAthleteInput" } }
                ]
              },
              "example": [
                { "slug": "first-athlete", "position": "ST" },
                { "slug": "second-athlete" }
              ]
            }
          }
        },
        "responses": {
          "200": { "description": "Array processed, or existing fixture athlete replaced or moved" },
          "201": { "description": "Single athlete added to the fixture lineup" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not add all fixture athletes; completed contains earlier saved results when a batch fails" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/fixtures/{id}/athletes/{lineupId}": {
      "delete": {
        "tags": ["Fixtures"],
        "operationId": "removeFixtureLineupPlayer",
        "summary": "Remove one fixture lineup player",
        "description": "Deletes the lineup row only when its ID, fixture ID, and selected home or away team all match. Returns the deleted row. Requires a read and write API key.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Fixture ID" },
          { "name": "lineupId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Fixture lineup row ID" },
          { "name": "side", "in": "query", "required": true, "schema": { "type": "string", "enum": ["home", "away"] } }
        ],
        "responses": {
          "200": { "description": "Lineup player removed; data contains the deleted row" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "500": { "description": "Could not remove fixture lineup player" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/venues": {
      "get": {
        "tags": ["Venues"], "operationId": "listVenues", "summary": "List venues and fields", "description": "Returns venue/location records with their nested fields. Fields use the same Full, Half, and 3/4 size specification as divisions.",
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 120 } }],
        "responses": { "200": { "description": "A page of venues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Could not list venues" }, "503": { "$ref": "#/components/responses/Unavailable" } }
      },
      "post": {
        "tags": ["Venues"], "operationId": "createVenue", "summary": "Create a venue", "description": "Creates a venue/location. Requires a read and write API key.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVenue" } } } },
        "responses": { "201": { "description": "Venue created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/Unavailable" } }
      }
    },
    "/v1/venues/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }],
      "get": { "tags": ["Venues"], "operationId": "getVenue", "summary": "Get a venue", "responses": { "200": { "description": "Venue and fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "patch": { "tags": ["Venues"], "operationId": "updateVenue", "summary": "Update a venue", "description": "Renaming a venue cascades its display name to fields and fixtures. Requires a read and write API key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVenue" } } } }, "responses": { "200": { "description": "Venue updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } },
      "delete": { "tags": ["Venues"], "operationId": "deleteVenue", "summary": "Delete an unused venue", "description": "A venue assigned to fields or fixtures cannot be deleted. Requires a read and write API key.", "responses": { "200": { "description": "Venue deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }
    },
    "/v1/venues/{id}/fields": {
      "post": { "tags": ["Venues"], "operationId": "createVenueField", "summary": "Add a field to a venue", "description": "Adds a Full, Half, or 3/4 field. Requires a read and write API key.", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVenueField" } } } }, "responses": { "201": { "description": "Field created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }
    },
    "/v1/venues/{id}/fields/{fieldId}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }],
      "patch": { "tags": ["Venues"], "operationId": "updateVenueField", "summary": "Update a venue field", "description": "Changing field size can affect fixture compatibility with its division. Requires a read and write API key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVenueField" } } } }, "responses": { "200": { "description": "Field updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } },
      "delete": { "tags": ["Venues"], "operationId": "deleteVenueField", "summary": "Delete an unused venue field", "description": "A field assigned to a fixture or training session cannot be deleted. Requires a read and write API key.", "responses": { "200": { "description": "Field deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }
    },
    "/v1/training-fields": {
      "get": {
        "tags": ["Trainings"],
        "operationId": "listTrainingFields",
        "summary": "List training fields",
        "description": "Returns the valid facility and field combinations accepted when creating training sessions.",
        "responses": {
          "200": { "description": "Available training fields", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingField" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "description": "Could not load training fields" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/trainings": {
      "get": {
        "tags": ["Trainings"],
        "operationId": "listTrainingSessions",
        "summary": "List training sessions",
        "description": "Returns sessions with their field, eligible birth years, and attendee bookings. The default window is now through 28 days from now.",
        "parameters": [
          { "name": "from", "in": "query", "description": "Inclusive lower time bound; defaults to now", "schema": { "type": "string", "format": "date-time" } },
          { "name": "to", "in": "query", "description": "Inclusive upper time bound; defaults to 28 days from now", "schema": { "type": "string", "format": "date-time" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }
        ],
        "responses": {
          "200": { "description": "Training sessions in the requested window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingList" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "description": "Could not load training sessions" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "post": {
        "tags": ["Trainings"],
        "operationId": "createTrainingSession",
        "summary": "Create a training session",
        "description": "Publishes one training session. Recurring schedules are created by making one request per date. Requires a read and write API key.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTraining" }, "example": { "facility": "PF Academy", "field": "Field 1", "date": "2026-10-01", "start_time": "18:00", "duration_minutes": 60, "birth_years": [2012, 2013], "capacity": 12, "timezone": "America/Vancouver", "coach_name": "Coach Name" } } } },
        "responses": {
          "201": { "description": "Training session created" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "500": { "description": "Could not create training session" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/trainings/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "description": "Training session ID", "schema": { "type": "integer", "minimum": 1 } }],
      "patch": {
        "tags": ["Trainings"],
        "operationId": "updateTrainingSessionCoach",
        "summary": "Change a training session coach",
        "description": "Updates only the assigned coach. Requires a read and write API key.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["coach_name"], "properties": { "coach_name": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "example": { "coach_name": "Coach Name" } } } },
        "responses": {
          "200": { "description": "Coach updated" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "description": "Could not update training session" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "delete": {
        "tags": ["Trainings"],
        "operationId": "deleteTrainingSession",
        "summary": "Delete a training session",
        "description": "Permanently deletes the session; related bookings are deleted by the database relationship. Requires a read and write API key.",
        "responses": {
          "200": { "description": "Training session deleted" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "description": "Could not delete training session" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/trainings/{id}/attendees/{bookingId}": {
      "delete": {
        "tags": ["Trainings"],
        "operationId": "removeTrainingAttendee",
        "summary": "Remove a training attendee",
        "description": "Deletes a booking only when its booking ID and training session ID both match. Requires a read and write API key.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "description": "Training session ID", "schema": { "type": "integer", "minimum": 1 } },
          { "name": "bookingId", "in": "path", "required": true, "description": "Training booking ID", "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": { "description": "Attendee booking removed" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "description": "Could not remove training attendee" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/trainings/{id}/widget-link": {
      "get": {
        "tags": ["Trainings"],
        "operationId": "getTrainingAttendeeWidgetLink",
        "summary": "Get a public training attendee widget link",
        "description": "Returns the signed public widget URL for a training session. The signing secret is never returned.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "description": "Training session ID", "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": { "description": "Signed public widget URL", "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "description": "Could not create the public widget link" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Dashboard API key (catx_\u2026). Create one in the API keys section."
      }
    },
    "schemas": {
      "FixturePerformancePlayerInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "side",
          "jersey_number",
          "played_seconds",
          "source_team",
          "source_player_id",
          "source_player_name",
          "fixture_lineup_id",
          "athlete_slug",
          "tracked_minutes",
          "distance_miles",
          "average_speed_mph",
          "top_speed_mph",
          "sprints",
          "high_intensity_runs",
          "total_events",
          "goals",
          "assists",
          "goal_involvements",
          "conversion_rate_percent",
          "shots",
          "total_attempts",
          "tackles",
          "corners",
          "free_kicks",
          "throw_ins",
          "fouls",
          "penalty_kicks",
          "goal_kicks"
        ],
        "properties": {
          "side": {
            "type": "string",
            "enum": [
              "home",
              "away"
            ]
          },
          "jersey_number": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
          },
          "played_seconds": {
            "type": "integer",
            "minimum": 0,
            "maximum": 86400
          },
          "source_team": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 120
          },
          "source_player_id": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 200
          },
          "source_player_name": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 200
          },
          "fixture_lineup_id": {
            "type": "integer",
            "nullable": true,
            "minimum": 1
          },
          "athlete_slug": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          },
          "tracked_minutes": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1440
          },
          "distance_miles": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000
          },
          "average_speed_mph": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "top_speed_mph": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "sprints": {
            "type": "integer",
            "minimum": 0
          },
          "high_intensity_runs": {
            "type": "integer",
            "minimum": 0
          },
          "total_events": {
            "type": "integer",
            "minimum": 0
          },
          "goals": {
            "type": "integer",
            "minimum": 0
          },
          "assists": {
            "type": "integer",
            "minimum": 0
          },
          "goal_involvements": {
            "type": "integer",
            "minimum": 0
          },
          "conversion_rate_percent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "shots": {
            "type": "integer",
            "minimum": 0
          },
          "total_attempts": {
            "type": "integer",
            "minimum": 0
          },
          "tackles": {
            "type": "integer",
            "minimum": 0
          },
          "corners": {
            "type": "integer",
            "minimum": 0
          },
          "free_kicks": {
            "type": "integer",
            "minimum": 0
          },
          "throw_ins": {
            "type": "integer",
            "minimum": 0
          },
          "fouls": {
            "type": "integer",
            "minimum": 0
          },
          "penalty_kicks": {
            "type": "integer",
            "minimum": 0
          },
          "goal_kicks": {
            "type": "integer",
            "minimum": 0
          },
          "passes": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 32767
          },
          "completed_passes": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 32767
          },
          "dribbles": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 32767
          },
          "interceptions": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 32767
          },
          "saves": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 32767
          },
          "pass_success_rate_percent": {
            "type": "number",
            "nullable": true,
            "minimum": 0,
            "maximum": 100,
            "multipleOf": 0.01
          }
        },
        "description": "Legacy required metrics remain unchanged. Extended metrics are optional and nullable; send verified source values when available, or null when unknown. completed_passes must not exceed passes when both are supplied. Do not calculate counts from a percentage. A complete import replaces the provider player set, so omitted extended fields are saved as null."
      },
      "FixturePerformanceInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "video_url",
          "match_stats",
          "players"
        ],
        "properties": {
          "source": {
            "type": "string",
            "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$",
            "minLength": 1,
            "maxLength": 50
          },
          "video_url": {
            "type": "string",
            "nullable": true,
            "format": "uri",
            "description": "HTTPS match recording URL, or null."
          },
          "match_stats": {
            "$ref": "#/components/schemas/MatchStats"
          },
          "players": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/FixturePerformancePlayerInput"
            }
          }
        }
      },
      "PlayerTrendWindowComparison": {
        "type": "object",
        "properties": {
          "previous_average": {
            "type": "number",
            "nullable": true
          },
          "recent_average": {
            "type": "number",
            "nullable": true
          },
          "change": {
            "type": "number",
            "nullable": true
          },
          "change_percent": {
            "type": "number",
            "nullable": true
          },
          "previous_sample_count": {
            "type": "integer"
          },
          "recent_sample_count": {
            "type": "integer"
          },
          "direction": {
            "type": "string",
            "enum": [
              "increase",
              "decrease",
              "unchanged",
              "insufficient_data"
            ]
          }
        }
      },
      "PlayerTrendMetrics": {
        "type": "object",
        "properties": {
          "tracked_minutes": {
            "type": "number",
            "nullable": true
          },
          "distance_miles": {
            "type": "number",
            "nullable": true
          },
          "average_speed_mph": {
            "type": "number",
            "nullable": true
          },
          "top_speed_mph": {
            "type": "number",
            "nullable": true
          },
          "sprints": {
            "type": "number",
            "nullable": true
          },
          "high_intensity_runs": {
            "type": "number",
            "nullable": true
          },
          "total_events": {
            "type": "number",
            "nullable": true
          },
          "goals": {
            "type": "number",
            "nullable": true
          },
          "assists": {
            "type": "number",
            "nullable": true
          },
          "goal_involvements": {
            "type": "number",
            "nullable": true
          },
          "conversion_rate_percent": {
            "type": "number",
            "nullable": true
          },
          "shots": {
            "type": "number",
            "nullable": true
          },
          "total_attempts": {
            "type": "number",
            "nullable": true
          },
          "tackles": {
            "type": "number",
            "nullable": true
          },
          "corners": {
            "type": "number",
            "nullable": true
          },
          "free_kicks": {
            "type": "number",
            "nullable": true
          },
          "throw_ins": {
            "type": "number",
            "nullable": true
          },
          "fouls": {
            "type": "number",
            "nullable": true
          },
          "penalty_kicks": {
            "type": "number",
            "nullable": true
          },
          "goal_kicks": {
            "type": "number",
            "nullable": true
          },
          "played_seconds": {
            "type": "number",
            "nullable": true
          },
          "passes": {
            "type": "number",
            "nullable": true
          },
          "completed_passes": {
            "type": "number",
            "nullable": true
          },
          "pass_success_rate_percent": {
            "type": "number",
            "nullable": true
          },
          "dribbles": {
            "type": "number",
            "nullable": true
          },
          "interceptions": {
            "type": "number",
            "nullable": true
          },
          "saves": {
            "type": "number",
            "nullable": true
          }
        },
        "required": [
          "tracked_minutes",
          "distance_miles",
          "average_speed_mph",
          "top_speed_mph",
          "sprints",
          "high_intensity_runs",
          "total_events",
          "goals",
          "assists",
          "goal_involvements",
          "conversion_rate_percent",
          "shots",
          "total_attempts",
          "tackles",
          "corners",
          "free_kicks",
          "throw_ins",
          "fouls",
          "penalty_kicks",
          "goal_kicks",
          "played_seconds",
          "passes",
          "completed_passes",
          "pass_success_rate_percent",
          "dribbles",
          "interceptions",
          "saves"
        ]
      },
      "PlayerTrendMetricSummary": {
        "type": "object",
        "properties": {
          "sample_count": {
            "type": "integer"
          },
          "first": {
            "type": "number",
            "nullable": true
          },
          "latest": {
            "type": "number",
            "nullable": true
          },
          "average": {
            "type": "number",
            "nullable": true
          },
          "change": {
            "type": "number",
            "nullable": true
          },
          "change_percent": {
            "type": "number",
            "nullable": true
          },
          "direction": {
            "type": "string",
            "enum": [
              "increase",
              "decrease",
              "unchanged",
              "insufficient_data"
            ]
          }
        },
        "required": [
          "sample_count",
          "first",
          "latest",
          "average",
          "change",
          "change_percent",
          "direction"
        ]
      },
      "PlayerTrend": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "athlete": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string"
                  },
                  "first_name": {
                    "type": "string"
                  },
                  "last_name": {
                    "type": "string",
                    "nullable": true
                  }
                }
              },
              "points": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "fixture_id": {
                      "type": "integer"
                    },
                    "match_date": {
                      "type": "string",
                      "format": "date"
                    },
                    "start_time": {
                      "type": "string",
                      "nullable": true
                    },
                    "division_team_id": {
                      "type": "integer"
                    },
                    "jersey_number": {
                      "type": "integer"
                    },
                    "source": {
                      "type": "string"
                    },
                    "metrics": {
                      "$ref": "#/components/schemas/PlayerTrendMetrics"
                    },
                    "minutes_played": {
                      "type": "number",
                      "nullable": true
                    },
                    "side": {
                      "type": "string",
                      "enum": [
                        "home",
                        "away"
                      ]
                    },
                    "team": {
                      "type": "string",
                      "nullable": true
                    },
                    "opponent": {
                      "type": "string",
                      "nullable": true
                    },
                    "video_url": {
                      "type": "string",
                      "nullable": true
                    },
                    "home_score": {
                      "type": "integer",
                      "nullable": true
                    },
                    "away_score": {
                      "type": "integer",
                      "nullable": true
                    },
                    "per_60": {
                      "type": "object",
                      "properties": {
                        "distance_miles": {
                          "type": "number",
                          "nullable": true
                        },
                        "sprints": {
                          "type": "number",
                          "nullable": true
                        },
                        "high_intensity_runs": {
                          "type": "number",
                          "nullable": true
                        },
                        "total_events": {
                          "type": "number",
                          "nullable": true
                        },
                        "goals": {
                          "type": "number",
                          "nullable": true
                        },
                        "assists": {
                          "type": "number",
                          "nullable": true
                        },
                        "goal_involvements": {
                          "type": "number",
                          "nullable": true
                        },
                        "shots": {
                          "type": "number",
                          "nullable": true
                        },
                        "total_attempts": {
                          "type": "number",
                          "nullable": true
                        },
                        "tackles": {
                          "type": "number",
                          "nullable": true
                        },
                        "corners": {
                          "type": "number",
                          "nullable": true
                        },
                        "free_kicks": {
                          "type": "number",
                          "nullable": true
                        },
                        "throw_ins": {
                          "type": "number",
                          "nullable": true
                        },
                        "fouls": {
                          "type": "number",
                          "nullable": true
                        },
                        "penalty_kicks": {
                          "type": "number",
                          "nullable": true
                        },
                        "goal_kicks": {
                          "type": "number",
                          "nullable": true
                        },
                        "passes": {
                          "type": "number",
                          "nullable": true
                        },
                        "completed_passes": {
                          "type": "number",
                          "nullable": true
                        },
                        "dribbles": {
                          "type": "number",
                          "nullable": true
                        },
                        "interceptions": {
                          "type": "number",
                          "nullable": true
                        },
                        "saves": {
                          "type": "number",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              },
              "summary": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "source": {
                      "type": "string"
                    },
                    "sample_count": {
                      "type": "integer"
                    },
                    "metrics": {
                      "type": "object",
                      "properties": {
                        "tracked_minutes": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "distance_miles": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "average_speed_mph": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "top_speed_mph": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "sprints": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "high_intensity_runs": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "total_events": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "goals": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "assists": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "goal_involvements": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "conversion_rate_percent": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "shots": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "total_attempts": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "tackles": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "corners": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "free_kicks": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "throw_ins": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "fouls": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "penalty_kicks": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "goal_kicks": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "played_seconds": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "passes": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "completed_passes": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "pass_success_rate_percent": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "dribbles": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "interceptions": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        },
                        "saves": {
                          "$ref": "#/components/schemas/PlayerTrendMetricSummary"
                        }
                      }
                    }
                  }
                }
              },
              "comparison": {
                "type": "object",
                "properties": {
                  "window_size": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 3
                  },
                  "recent_fixture_ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "previous_fixture_ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "by_source": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "source": {
                          "type": "string"
                        },
                        "metrics": {
                          "type": "object",
                          "properties": {
                            "tracked_minutes": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "distance_miles": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "average_speed_mph": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "top_speed_mph": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "sprints": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "high_intensity_runs": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "total_events": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "goals": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "assists": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "goal_involvements": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "conversion_rate_percent": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "shots": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "total_attempts": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "tackles": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "corners": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "free_kicks": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "throw_ins": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "fouls": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "penalty_kicks": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "goal_kicks": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "played_seconds": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "passes": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "completed_passes": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "pass_success_rate_percent": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "dribbles": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "interceptions": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "saves": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "minutes_played": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            }
                          }
                        },
                        "per_60": {
                          "type": "object",
                          "properties": {
                            "distance_miles": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "sprints": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "high_intensity_runs": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "total_events": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "goals": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "assists": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "goal_involvements": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "shots": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "total_attempts": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "tackles": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "corners": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "free_kicks": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "throw_ins": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "fouls": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "penalty_kicks": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "goal_kicks": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "passes": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "completed_passes": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "dribbles": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "interceptions": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            },
                            "saves": {
                              "$ref": "#/components/schemas/PlayerTrendWindowComparison"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer"
              },
              "returned": {
                "type": "integer"
              },
              "has_more": {
                "type": "boolean"
              },
              "source": {
                "type": "string",
                "nullable": true
              },
              "from": {
                "type": "string",
                "nullable": true,
                "format": "date"
              },
              "to": {
                "type": "string",
                "nullable": true,
                "format": "date"
              }
            }
          }
        }
      },
      "Organization": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name", "short_name", "crest_url", "created_at"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "short_name": { "type": "string", "nullable": true },
          "crest_url": { "type": "string", "format": "uri", "nullable": true },
          "created_at": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "CreateOrganization": {
        "type": "object", "additionalProperties": false, "required": ["name"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 160 },
          "short_name": { "type": "string", "maxLength": 40, "nullable": true },
          "crest_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }
        }
      },
      "UpdateOrganization": {
        "type": "object", "additionalProperties": false, "minProperties": 1,
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 160 },
          "short_name": { "type": "string", "maxLength": 40, "nullable": true },
          "crest_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }
        }
      },
      "OrganizationResult": {
        "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Organization" } }
      },
      "OrganizationList": {
        "type": "object", "required": ["data", "count", "limit", "offset", "search"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } },
          "count": { "type": "integer", "nullable": true },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "search": { "type": "string" }
        }
      },
      "Team": {
        "type": "object",
        "additionalProperties": true,
        "required": ["name"],
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string", "readOnly": true },
          "short_name": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "created_by": { "type": "string", "format": "uuid", "nullable": true },
          "photo_url": { "type": "string", "format": "uri", "nullable": true },
          "year_group": { "type": "integer", "nullable": true },
          "theme": { "type": "string", "nullable": true },
          "crest_url": { "type": "string", "format": "uri", "nullable": true },
          "away_theme": { "type": "string", "nullable": true },
          "agent_id": { "type": "string", "nullable": true },
          "analyst_id": { "type": "string", "nullable": true },
          "organization_id": { "type": "string", "format": "uuid", "nullable": true }
        }
      },
      "CreateTeam": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 160 },
          "short_name": { "type": "string", "maxLength": 40, "nullable": true },
          "photo_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true },
          "year_group": { "type": "integer", "minimum": 1900, "maximum": 2100, "nullable": true },
          "theme": { "$ref": "#/components/schemas/TeamTheme" },
          "crest_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true },
          "away_theme": { "$ref": "#/components/schemas/TeamTheme" },
          "agent_id": { "type": "string", "minLength": 1, "maxLength": 160, "nullable": true },
          "analyst_id": { "type": "string", "minLength": 1, "maxLength": 160, "nullable": true },
          "organization_id": { "type": "string", "format": "uuid", "nullable": true }
        }
      },
      "UpdateTeam": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 160 },
          "short_name": { "type": "string", "maxLength": 40, "nullable": true },
          "photo_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true },
          "year_group": { "type": "integer", "minimum": 1900, "maximum": 2100, "nullable": true },
          "theme": { "$ref": "#/components/schemas/TeamTheme" },
          "crest_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true },
          "away_theme": { "$ref": "#/components/schemas/TeamTheme" },
          "agent_id": { "type": "string", "minLength": 1, "maxLength": 160, "nullable": true },
          "analyst_id": { "type": "string", "minLength": 1, "maxLength": 160, "nullable": true },
          "organization_id": { "type": "string", "format": "uuid", "nullable": true }
        }
      },
      "TeamTheme": {
        "type": "string",
        "nullable": true,
        "enum": ["cyan", "rose", "zinc", "slate", "red", "yellow", "amber", "green", "lime", "sky", "blue", "pink", "purple", "indigo", "fuschia", "gray", "orange", "white", "black", "neutral", "navy", null]
      },
      "TeamResult": {
        "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Team" } }
      },
      "TeamList": {
        "type": "object",
        "required": ["data", "count", "limit", "offset", "search"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } },
          "count": { "type": "integer", "nullable": true },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "search": { "type": "string" },
          "organization_id": { "type": "string", "format": "uuid", "nullable": true }
        }
      },
      "VenueField": {
        "type": "object", "required": ["id", "name", "size_type", "facility_type"],
        "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size_type": { "type": "string", "enum": ["Full", "Half", "3/4"] }, "facility_type": { "type": "string", "enum": ["TURF", "GRASS", "GYM"] }, "created_at": { "type": "string", "format": "date-time" } }
      },
      "Venue": {
        "type": "object", "required": ["id", "name", "fields"],
        "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "short_alias": { "type": "string", "nullable": true }, "street_1": { "type": "string", "nullable": true }, "street_2": { "type": "string", "nullable": true }, "city_town": { "type": "string", "nullable": true }, "state_province": { "type": "string", "nullable": true }, "postal_zip_code": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/VenueField" } } }
      },
      "CreateVenue": {
        "type": "object", "additionalProperties": false, "required": ["name"],
        "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "short_alias": { "type": "string", "maxLength": 60, "nullable": true }, "street_1": { "type": "string", "maxLength": 200, "nullable": true }, "street_2": { "type": "string", "maxLength": 200, "nullable": true }, "city_town": { "type": "string", "maxLength": 100, "nullable": true }, "state_province": { "type": "string", "maxLength": 100, "nullable": true }, "postal_zip_code": { "type": "string", "maxLength": 24, "nullable": true } }
      },
      "UpdateVenue": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "short_alias": { "type": "string", "maxLength": 60, "nullable": true }, "street_1": { "type": "string", "maxLength": 200, "nullable": true }, "street_2": { "type": "string", "maxLength": 200, "nullable": true }, "city_town": { "type": "string", "maxLength": 100, "nullable": true }, "state_province": { "type": "string", "maxLength": 100, "nullable": true }, "postal_zip_code": { "type": "string", "maxLength": 24, "nullable": true } } },
      "CreateVenueField": { "type": "object", "additionalProperties": false, "required": ["name", "size_type", "facility_type"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "size_type": { "type": "string", "enum": ["Full", "Half", "3/4"] }, "facility_type": { "type": "string", "enum": ["TURF", "GRASS", "GYM"] } } },
      "UpdateVenueField": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "size_type": { "type": "string", "enum": ["Full", "Half", "3/4"] }, "facility_type": { "type": "string", "enum": ["TURF", "GRASS", "GYM"] } } },
      "VenueResult": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Venue" } } },
      "VenueList": { "type": "object", "required": ["data", "count", "limit", "offset", "search"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Venue" } }, "count": { "type": "integer", "nullable": true }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "search": { "type": "string" } } },
      "TrainingField": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "venue": { "type": "string" },
          "name": { "type": "string" },
          "location": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "short_alias": { "type": "string", "nullable": true } } }
        }
      },
      "CreateTraining": {
        "type": "object",
        "additionalProperties": false,
        "required": ["facility", "field", "date", "start_time", "duration_minutes", "birth_years", "capacity", "timezone", "coach_name"],
        "properties": {
          "facility": { "type": "string", "minLength": 1, "maxLength": 160 },
          "field": { "type": "string", "minLength": 1, "maxLength": 160 },
          "date": { "type": "string", "format": "date" },
          "start_time": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" },
          "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 480 },
          "birth_years": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "integer", "minimum": 1900, "maximum": 2100 } },
          "capacity": { "type": "integer", "minimum": 1, "maximum": 32767 },
          "timezone": { "type": "string", "description": "IANA timezone name" },
          "coach_name": { "type": "string", "minLength": 1, "maxLength": 160 }
        }
      },
      "TrainingList": {
        "type": "object",
        "required": ["data", "count", "from", "to", "limit", "offset"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingSession" } },
          "count": { "type": "integer", "nullable": true },
          "from": { "type": "string", "format": "date-time" },
          "to": { "type": "string", "format": "date-time" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" }
        }
      },
      "TrainingSession": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": { "type": "integer" },
          "starts_at": { "type": "string", "format": "date-time" },
          "timezone": { "type": "string" },
          "duration_minutes": { "type": "integer" },
          "capacity": { "type": "integer" },
          "coach_name": { "type": "string" },
          "status": { "type": "string" },
          "birth_years": { "type": "array", "items": { "type": "object", "properties": { "birth_year": { "type": "integer" } } } },
          "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingBooking" } }
        }
      },
      "TrainingBooking": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "athlete_slug": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "athlete": { "type": "object", "properties": { "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true } } }
        }
      },
      "FixtureAthleteInput": {
        "type": "object",
        "additionalProperties": false,
        "required": ["slug"],
        "properties": {
          "slug": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
          "position": { "type": "string", "enum": ["GK", "LB", "LCB", "CB", "RCB", "RB", "LWB", "RWB", "SW", "CDM", "LDM", "RDM", "LM", "LCM", "CM", "RCM", "RM", "CAM", "LAM", "RAM", "LW", "RW", "LF", "CF", "RF", "LS", "ST", "RS", "SS"] }
        }
      },
      "CreateAthlete": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "slug",
          "first_name"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          },
          "first_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "maxLength": 120
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "maxLength": 254
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "maxLength": 40
          },
          "date_of_birth": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "street_1": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "street_2": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "city_town": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "state_province": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "postal_zip_code": {
            "type": "string",
            "nullable": true,
            "maxLength": 30
          },
          "country": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "photo_url": {
            "type": "string",
            "nullable": true,
            "maxLength": 2048
          },
          "pac": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "sho": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "pas": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "dri": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "def": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "phy": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          }
        }
      },
      "UpdateAthlete": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "first_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "maxLength": 120
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "maxLength": 254
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "maxLength": 40
          },
          "date_of_birth": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "street_1": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "street_2": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "city_town": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "state_province": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "postal_zip_code": {
            "type": "string",
            "nullable": true,
            "maxLength": 30
          },
          "country": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "photo_url": {
            "type": "string",
            "nullable": true,
            "maxLength": 2048
          },
          "pac": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "sho": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "pas": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "dri": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "def": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          },
          "phy": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99,
            "nullable": true
          }
        }
      },
      "Athlete": {
        "type": "object",
        "description": "A full row from public.athletes. Fields may include personal data.",
        "additionalProperties": true,
        "properties": {
          "slug": {
            "type": "string"
          },
          "first_name": {
            "type": "string"
          }
        }
      },
      "AthleteResult": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Athlete"
          }
        }
      },
      "AthleteList": {
        "type": "object",
        "required": [
          "data",
          "count",
          "limit",
          "offset",
          "search"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Athlete"
            }
          },
          "count": {
            "type": "integer",
            "nullable": true
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "search": {
            "type": "string"
          }
        }
      },
      "Fixture": {
        "type": "object",
        "description": "A full row from public.fixtures with home and away rosters.",
        "additionalProperties": true,
        "required": ["home_roster", "away_roster"],
        "properties": {
          "id": { "type": "integer" },
          "slug": { "type": "string", "readOnly": true },
          "match_date": { "type": "string", "format": "date" },
          "start_time": { "type": "string" },
          "home_roster": { "type": "array", "items": { "$ref": "#/components/schemas/FixtureRosterAthlete" } },
          "away_roster": { "type": "array", "items": { "$ref": "#/components/schemas/FixtureRosterAthlete" } }
        }
      },
      "FixtureFinalizationResult": {
        "type": "object",
        "additionalProperties": false,
        "required": ["data"],
        "properties": {
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": ["home_score", "away_score", "finalized_at"],
            "properties": {
              "home_score": { "type": "integer", "minimum": 0 },
              "away_score": { "type": "integer", "minimum": 0 },
              "finalized_at": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "FixtureRosterAthlete": {
        "type": "object",
        "additionalProperties": false,
        "required": ["slug", "position"],
        "properties": {
          "slug": { "type": "string" },
          "position": { "type": "string", "nullable": true }
        }
      },
      "FixtureList": {
        "type": "object",
        "required": ["data", "count", "date", "limit", "offset"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Fixture" } },
          "count": { "type": "integer", "nullable": true },
          "date": { "type": "string", "format": "date" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" }
        }
      },
      "CreateFixture": {
        "type": "object",
        "additionalProperties": false,
        "required": ["division_id", "match_date", "start_time", "half_duration_minutes", "half_time_break_minutes", "home_division_team_id", "away_division_team_id", "venue", "field_id", "stage"],
        "properties": {
          "division_id": { "type": "integer", "minimum": 1 },
          "match_date": { "type": "string", "format": "date" },
          "start_time": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" },
          "half_duration_minutes": { "type": "integer", "minimum": 5, "maximum": 60 },
          "half_time_break_minutes": { "type": "integer", "minimum": 0, "maximum": 30 },
          "home_division_team_id": { "type": "integer", "minimum": 1 },
          "away_division_team_id": { "type": "integer", "minimum": 1 },
          "venue": { "type": "string", "minLength": 1, "maxLength": 200 },
          "field_id": { "type": "integer", "minimum": 1, "nullable": true },
          "stage": { "type": "string", "enum": ["league"] }
        }
      },
      "UpdateFixture": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "division_id": { "type": "integer", "minimum": 1 },
          "match_date": { "type": "string", "format": "date" },
          "start_time": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" },
          "half_duration_minutes": { "type": "integer", "minimum": 5, "maximum": 60 },
          "half_time_break_minutes": { "type": "integer", "minimum": 0, "maximum": 30 },
          "home_division_team_id": { "type": "integer", "minimum": 1 },
          "away_division_team_id": { "type": "integer", "minimum": 1 },
          "venue": { "type": "string", "minLength": 1, "maxLength": 200 },
          "field_id": { "type": "integer", "minimum": 1, "nullable": true },
          "stage": { "type": "string", "enum": ["league"] }
        }
      },
      "PlayingTimeInput": {
        "type": "object",
        "additionalProperties": false,
        "required": ["source", "players"],
        "properties": {
          "source": { "type": "string", "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$", "minLength": 1, "maxLength": 50 },
          "players": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["jersey_number", "played_seconds"],
              "properties": {
                "jersey_number": { "type": "integer", "minimum": 0, "maximum": 99 },
                "played_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }
              }
            }
          }
        }
      },
      "PlayingTimeRecord": {
        "type": "object",
        "additionalProperties": false,
        "required": ["lineup_id", "athlete_slug", "player_name", "jersey_number", "played_seconds", "source", "created_at", "updated_at"],
        "properties": {
          "lineup_id": { "type": "integer", "minimum": 1 },
          "athlete_slug": { "type": "string" },
          "player_name": { "type": "string", "nullable": true },
          "jersey_number": { "type": "integer", "minimum": 0, "maximum": 99, "nullable": true },
          "played_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 },
          "source": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "PlayingTimeResult": {
        "type": "object",
        "additionalProperties": false,
        "required": ["data", "side", "total_played_seconds"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlayingTimeRecord" } },
          "side": { "type": "string", "enum": ["home", "away"] },
          "total_played_seconds": { "type": "integer", "minimum": 0 }
        }
      },
      "PlayerStatMetrics": {
        "type": "object",
        "required": ["tracked_minutes", "distance_miles", "average_speed_mph", "top_speed_mph", "sprints", "high_intensity_runs", "total_events", "goals", "assists", "goal_involvements", "conversion_rate_percent", "shots", "total_attempts", "tackles", "corners", "free_kicks", "throw_ins", "fouls", "penalty_kicks", "goal_kicks"],
        "properties": {
          "tracked_minutes": { "type": "integer", "minimum": 0, "maximum": 1440 },
          "distance_miles": { "type": "number", "minimum": 0, "maximum": 1000 },
          "average_speed_mph": { "type": "number", "minimum": 0, "maximum": 100 },
          "top_speed_mph": { "type": "number", "minimum": 0, "maximum": 100 },
          "sprints": { "type": "integer", "minimum": 0 },
          "high_intensity_runs": { "type": "integer", "minimum": 0 },
          "total_events": { "type": "integer", "minimum": 0 },
          "goals": { "type": "integer", "minimum": 0 },
          "assists": { "type": "integer", "minimum": 0 },
          "goal_involvements": { "type": "integer", "minimum": 0 },
          "conversion_rate_percent": { "type": "number", "minimum": 0, "maximum": 100 },
          "shots": { "type": "integer", "minimum": 0 },
          "total_attempts": { "type": "integer", "minimum": 0 },
          "tackles": { "type": "integer", "minimum": 0 },
          "corners": { "type": "integer", "minimum": 0 },
          "free_kicks": { "type": "integer", "minimum": 0 },
          "throw_ins": { "type": "integer", "minimum": 0 },
          "fouls": { "type": "integer", "minimum": 0 },
          "penalty_kicks": { "type": "integer", "minimum": 0 },
          "goal_kicks": { "type": "integer", "minimum": 0 }
        }
      },
      "PlayerStatsInput": {
        "type": "object",
        "additionalProperties": false,
        "required": ["source", "players"],
        "properties": {
          "source": { "type": "string", "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$", "minLength": 1, "maxLength": 50 },
          "players": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "allOf": [
                { "$ref": "#/components/schemas/PlayerStatMetrics" },
                {
                  "type": "object",
                  "required": ["jersey_number"],
                  "properties": { "jersey_number": { "type": "integer", "minimum": 0, "maximum": 99 } }
                }
              ]
            }
          }
        }
      },
      "PlayerStatsRecord": {
        "allOf": [
          { "$ref": "#/components/schemas/PlayerStatMetrics" },
          {
            "type": "object",
            "required": ["lineup_id", "athlete_slug", "player_name", "jersey_number", "source", "created_at", "updated_at"],
            "properties": {
              "lineup_id": { "type": "integer", "minimum": 1 },
              "athlete_slug": { "type": "string" },
              "player_name": { "type": "string", "nullable": true },
              "jersey_number": { "type": "integer", "minimum": 0, "maximum": 99, "nullable": true },
              "source": { "type": "string" },
              "created_at": { "type": "string", "format": "date-time" },
              "updated_at": { "type": "string", "format": "date-time" }
            }
          }
        ]
      },
      "PlayerStatsResult": {
        "type": "object",
        "additionalProperties": false,
        "required": ["data", "side"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerStatsRecord" } },
          "side": { "type": "string", "enum": ["home", "away"] }
        }
      },
      "MatchStats": {
        "type": "object",
        "additionalProperties": false,
        "required": ["match", "teams", "key_events"],
        "properties": {
          "match": {
            "type": "object",
            "additionalProperties": false,
            "required": ["title", "sport", "score"],
            "properties": {
              "title": { "type": "string", "minLength": 1, "maxLength": 200 },
              "sport": { "type": "string", "enum": ["football"] },
              "score": {
                "type": "object",
                "minProperties": 2,
                "maxProperties": 2,
                "additionalProperties": { "type": "integer", "minimum": 0 }
              }
            }
          },
          "teams": {
            "type": "object",
            "minProperties": 2,
            "maxProperties": 2,
            "additionalProperties": { "$ref": "#/components/schemas/TeamMatchStats" }
          },
          "key_events": { "type": "array", "items": { "$ref": "#/components/schemas/KeyEvent" } }
        }
      },
      "KeyEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": ["source_event_id", "sequence", "period", "minute", "added_time", "match_time_seconds", "video_time_seconds", "team", "source_team", "event_type", "status", "jersey_number", "player_name", "athlete_slug", "attribution"],
        "properties": {
          "source_event_id": { "type": "string", "minLength": 1, "maxLength": 200, "nullable": true },
          "sequence": { "type": "integer", "minimum": 0 },
          "period": { "type": "integer", "minimum": 1, "nullable": true },
          "minute": { "type": "integer", "minimum": 0, "nullable": true },
          "added_time": { "type": "integer", "minimum": 0, "nullable": true },
          "match_time_seconds": { "type": "number", "minimum": 0, "nullable": true },
          "video_time_seconds": { "type": "number", "minimum": 0, "nullable": true },
          "team": { "type": "string", "minLength": 1, "maxLength": 120 },
          "source_team": { "type": "string", "minLength": 1, "maxLength": 120 },
          "event_type": { "type": "string", "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$", "maxLength": 80 },
          "status": { "type": "string", "minLength": 1, "maxLength": 80, "nullable": true },
          "jersey_number": { "type": "integer", "minimum": 0, "nullable": true },
          "player_name": { "type": "string", "minLength": 1, "maxLength": 200, "nullable": true },
          "athlete_slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 100, "nullable": true },
          "attribution": { "type": "string", "enum": ["ai", "manual"], "nullable": true }
        }
      },
      "TeamMatchStats": {
        "type": "object",
        "additionalProperties": false,
        "required": ["possession_percent", "completed_passes", "passes_by_third", "events", "attempt_locations"],
        "properties": {
          "possession_percent": { "type": "number", "minimum": 0, "maximum": 100 },
          "completed_passes": { "type": "integer", "minimum": 0 },
          "passes_by_third": {
            "type": "object",
            "additionalProperties": false,
            "required": ["defensive_third", "middle_third", "attacking_third"],
            "properties": {
              "defensive_third": { "type": "integer", "minimum": 0 },
              "middle_third": { "type": "integer", "minimum": 0 },
              "attacking_third": { "type": "integer", "minimum": 0 }
            }
          },
          "events": {
            "type": "object",
            "additionalProperties": false,
            "required": ["goals", "shots", "total_attempts", "corners", "free_kicks", "goal_kicks", "throw_ins", "fouls", "tackles", "dribbles", "interceptions", "loose_balls", "saves"],
            "properties": {
              "goals": { "type": "integer", "minimum": 0 },
              "shots": { "type": "integer", "minimum": 0 },
              "total_attempts": { "type": "integer", "minimum": 0 },
              "corners": { "type": "integer", "minimum": 0 },
              "free_kicks": { "type": "integer", "minimum": 0 },
              "goal_kicks": { "type": "integer", "minimum": 0 },
              "throw_ins": { "type": "integer", "minimum": 0 },
              "fouls": { "type": "integer", "minimum": 0 },
              "tackles": { "type": "integer", "minimum": 0 },
              "dribbles": { "type": "integer", "minimum": 0 },
              "interceptions": { "type": "integer", "minimum": 0 },
              "loose_balls": { "type": "integer", "minimum": 0 },
              "saves": { "type": "integer", "minimum": 0 }
            }
          },
          "attempt_locations": {
            "type": "object",
            "additionalProperties": false,
            "required": ["inside_box_attempts", "inside_box_goals", "outside_box_attempts", "outside_box_goals"],
            "properties": {
              "inside_box_attempts": { "type": "integer", "minimum": 0 },
              "inside_box_goals": { "type": "integer", "minimum": 0 },
              "outside_box_attempts": { "type": "integer", "minimum": 0 },
              "outside_box_goals": { "type": "integer", "minimum": 0 }
            }
          },
          "momentum_percent": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true }
        }
      },
      "FormationChangeResult": {
        "type": "object",
        "required": ["fixture_id", "side", "previous_formation", "formation", "previous_athletes"],
        "properties": {
          "fixture_id": { "type": "integer" },
          "side": { "type": "string", "enum": ["home", "away"] },
          "previous_formation": { "type": "string", "nullable": true },
          "formation": { "type": "string" },
          "previous_athletes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "athlete_slug", "player_name", "position", "lineup_role", "sort_order"],
              "properties": {
                "id": { "type": "integer" },
                "athlete_slug": { "type": "string", "nullable": true },
                "player_name": { "type": "string" },
                "position": { "type": "string", "nullable": true },
                "lineup_role": { "type": "string", "enum": ["starter", "substitute"] },
                "sort_order": { "type": "integer" }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid query or request body",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "API key is missing, invalid, expired, or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "API key lacks write access",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Requested resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "The request conflicts with the current resource state",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unavailable": {
        "description": "API service is unavailable",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
