{
  "openapi": "3.1.0",
  "info": {
    "title": "Pro Football League API",
    "version": "1.0",
    "description": "Eight fictional American football teams with rosters, season stats, a weekly scoreboard, live games you advance quarter by quarter, play-by-play, standings and stat leaders — built for polling, ETag and pagination practice."
  },
  "servers": [
    {
      "url": "https://funapi.dev/api/football-league/v1"
    }
  ],
  "tags": [
    {
      "name": "teams",
      "description": "teams and rosters"
    },
    {
      "name": "players",
      "description": "players and stats"
    },
    {
      "name": "games",
      "description": "scoreboard and live games"
    },
    {
      "name": "season",
      "description": "standings and leaders"
    }
  ],
  "paths": {
    "/teams": {
      "get": {
        "tags": [
          "teams"
        ],
        "summary": "List the 8 teams",
        "operationId": "pf-teams",
        "responses": {
          "200": {
            "description": "Teams",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "league": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "city": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "fullName": {
                            "type": "string"
                          },
                          "abbreviation": {
                            "type": "string"
                          },
                          "conference": {
                            "type": "string"
                          },
                          "venue": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "conference",
            "in": "query",
            "required": false,
            "description": "Atlantic or Pacific",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/teams/{id}": {
      "get": {
        "tags": [
          "teams"
        ],
        "summary": "One team with its record",
        "operationId": "pf-team",
        "responses": {
          "200": {
            "description": "Team",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "city": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "fullName": {
                      "type": "string"
                    },
                    "abbreviation": {
                      "type": "string"
                    },
                    "conference": {
                      "type": "string"
                    },
                    "venue": {
                      "type": "string"
                    },
                    "record": {
                      "type": "object",
                      "properties": {
                        "wins": {
                          "type": "number"
                        },
                        "losses": {
                          "type": "number"
                        },
                        "ties": {
                          "type": "number"
                        },
                        "winPct": {
                          "type": "number"
                        },
                        "streak": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown team",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      }
    },
    "/teams/{id}/roster": {
      "get": {
        "tags": [
          "teams"
        ],
        "summary": "A team's roster with season stats",
        "operationId": "pf-roster",
        "responses": {
          "200": {
            "description": "Players",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "team": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "teamId": {
                            "type": "number"
                          },
                          "firstName": {
                            "type": "string"
                          },
                          "lastName": {
                            "type": "string"
                          },
                          "position": {
                            "type": "string"
                          },
                          "number": {
                            "type": "number"
                          },
                          "stats": {
                            "type": "object",
                            "properties": {
                              "passingYards": {
                                "type": "number"
                              },
                              "passingTouchdowns": {
                                "type": "number"
                              },
                              "interceptions": {
                                "type": "number"
                              },
                              "rushingYards": {
                                "type": "number"
                              },
                              "rushingTouchdowns": {
                                "type": "number"
                              },
                              "receptions": {
                                "type": "number"
                              },
                              "receivingYards": {
                                "type": "number"
                              },
                              "receivingTouchdowns": {
                                "type": "number"
                              },
                              "tackles": {
                                "type": "number"
                              },
                              "sacks": {
                                "type": "number"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown team",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      }
    },
    "/players": {
      "get": {
        "tags": [
          "players"
        ],
        "summary": "Search and page through players",
        "operationId": "pf-players",
        "responses": {
          "200": {
            "description": "Players with Link and X-Total-Count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "teamId": {
                            "type": "number"
                          },
                          "firstName": {
                            "type": "string"
                          },
                          "lastName": {
                            "type": "string"
                          },
                          "position": {
                            "type": "string"
                          },
                          "number": {
                            "type": "number"
                          },
                          "stats": {
                            "type": "object",
                            "properties": {
                              "passingYards": {
                                "type": "number"
                              },
                              "passingTouchdowns": {
                                "type": "number"
                              },
                              "interceptions": {
                                "type": "number"
                              },
                              "rushingYards": {
                                "type": "number"
                              },
                              "rushingTouchdowns": {
                                "type": "number"
                              },
                              "receptions": {
                                "type": "number"
                              },
                              "receivingYards": {
                                "type": "number"
                              },
                              "receivingTouchdowns": {
                                "type": "number"
                              },
                              "tackles": {
                                "type": "number"
                              },
                              "sacks": {
                                "type": "number"
                              }
                            }
                          }
                        }
                      }
                    },
                    "page": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "total": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid filter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "team",
            "in": "query",
            "required": false,
            "description": "Team id",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "position",
            "in": "query",
            "required": false,
            "description": "QB, RB, WR, TE, LB",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Name search",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page, default 1",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1–100, default 10",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          }
        ]
      }
    },
    "/players/{id}": {
      "get": {
        "tags": [
          "players"
        ],
        "summary": "One player and their season stats",
        "operationId": "pf-player",
        "responses": {
          "200": {
            "description": "Player",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "teamId": {
                      "type": "number"
                    },
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "position": {
                      "type": "string"
                    },
                    "number": {
                      "type": "number"
                    },
                    "stats": {
                      "type": "object",
                      "properties": {
                        "passingYards": {
                          "type": "number"
                        },
                        "passingTouchdowns": {
                          "type": "number"
                        },
                        "interceptions": {
                          "type": "number"
                        }
                      }
                    },
                    "team": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown player",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      }
    },
    "/games": {
      "get": {
        "tags": [
          "games"
        ],
        "summary": "Scoreboard: filter by week, team or status",
        "operationId": "pf-games",
        "responses": {
          "200": {
            "description": "Games",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "week": {
                            "type": "number"
                          },
                          "startsAt": {
                            "type": "string"
                          },
                          "timeZone": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "period": {
                            "type": "number"
                          },
                          "home": {
                            "type": "object",
                            "properties": {
                              "teamId": {
                                "type": "number"
                              },
                              "score": {
                                "type": "number"
                              },
                              "byPeriod": {
                                "type": "array",
                                "items": {
                                  "type": "number"
                                }
                              },
                              "team": {
                                "type": "string"
                              },
                              "abbreviation": {
                                "type": "string"
                              }
                            }
                          },
                          "away": {
                            "type": "object",
                            "properties": {
                              "teamId": {
                                "type": "number"
                              },
                              "score": {
                                "type": "number"
                              },
                              "byPeriod": {
                                "type": "array",
                                "items": {
                                  "type": "number"
                                }
                              },
                              "team": {
                                "type": "string"
                              },
                              "abbreviation": {
                                "type": "string"
                              }
                            }
                          },
                          "venue": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid filter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "week",
            "in": "query",
            "required": false,
            "description": "1–7",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 6
          },
          {
            "name": "team",
            "in": "query",
            "required": false,
            "description": "Team id",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "scheduled, in_progress or final",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/games/{id}": {
      "get": {
        "tags": [
          "games"
        ],
        "summary": "One game — ETag changes when the score does; poll with If-None-Match for 304",
        "operationId": "pf-game",
        "responses": {
          "200": {
            "description": "Game with score by quarter",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "week": {
                      "type": "number"
                    },
                    "startsAt": {
                      "type": "string"
                    },
                    "timeZone": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "period": {
                      "type": "number"
                    },
                    "home": {
                      "type": "object",
                      "properties": {
                        "teamId": {
                          "type": "number"
                        },
                        "score": {
                          "type": "number"
                        },
                        "byPeriod": {
                          "type": "array",
                          "items": {
                            "type": "number"
                          }
                        },
                        "team": {
                          "type": "string"
                        },
                        "abbreviation": {
                          "type": "string"
                        }
                      }
                    },
                    "away": {
                      "type": "object",
                      "properties": {
                        "teamId": {
                          "type": "number"
                        },
                        "score": {
                          "type": "number"
                        },
                        "byPeriod": {
                          "type": "array",
                          "items": {
                            "type": "number"
                          }
                        },
                        "team": {
                          "type": "string"
                        },
                        "abbreviation": {
                          "type": "string"
                        }
                      }
                    },
                    "venue": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Unchanged since your ETag"
          },
          "404": {
            "description": "Unknown game",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      }
    },
    "/games/{id}/plays": {
      "get": {
        "tags": [
          "games"
        ],
        "summary": "Play-by-play; pass after=<last id> to read only new plays",
        "operationId": "pf-plays",
        "responses": {
          "200": {
            "description": "Plays",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "gameId": {
                      "type": "number"
                    },
                    "status": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "period": {
                            "type": "number"
                          },
                          "teamId": {
                            "type": "number"
                          },
                          "points": {
                            "type": "number"
                          },
                          "text": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "lastId": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown game",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "Last play id you have seen",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/games/{id}/advance": {
      "post": {
        "tags": [
          "games"
        ],
        "summary": "Play the next quarter of a game (admin) — then watch the ETag change",
        "operationId": "pf-advance",
        "responses": {
          "200": {
            "description": "Updated game",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "No token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Viewer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown game",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Game already final",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "periods out of range",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "periods": {
                    "type": "number"
                  }
                }
              },
              "example": {
                "periods": 1
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/standings": {
      "get": {
        "tags": [
          "season"
        ],
        "summary": "Standings computed from final games",
        "operationId": "pf-standings",
        "responses": {
          "200": {
            "description": "Standings by conference",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "league": {
                      "type": "string"
                    },
                    "asOf": {
                      "type": "string"
                    },
                    "conferences": {
                      "type": "object",
                      "properties": {
                        "Pacific": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "teamId": {
                                "type": "number"
                              },
                              "team": {
                                "type": "string"
                              },
                              "abbreviation": {
                                "type": "string"
                              },
                              "conference": {
                                "type": "string"
                              },
                              "wins": {
                                "type": "number"
                              },
                              "losses": {
                                "type": "number"
                              },
                              "ties": {
                                "type": "number"
                              },
                              "pointsFor": {
                                "type": "number"
                              },
                              "pointsAgainst": {
                                "type": "number"
                              },
                              "streak": {
                                "type": "string"
                              },
                              "winPct": {
                                "type": "number"
                              },
                              "pointDifferential": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "Atlantic": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "teamId": {
                                "type": "number"
                              },
                              "team": {
                                "type": "string"
                              },
                              "abbreviation": {
                                "type": "string"
                              },
                              "conference": {
                                "type": "string"
                              },
                              "wins": {
                                "type": "number"
                              },
                              "losses": {
                                "type": "number"
                              },
                              "ties": {
                                "type": "number"
                              },
                              "pointsFor": {
                                "type": "number"
                              },
                              "pointsAgainst": {
                                "type": "number"
                              },
                              "streak": {
                                "type": "string"
                              },
                              "winPct": {
                                "type": "number"
                              },
                              "pointDifferential": {
                                "type": "number"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/leaders": {
      "get": {
        "tags": [
          "season"
        ],
        "summary": "Stat leaders",
        "operationId": "pf-leaders",
        "responses": {
          "200": {
            "description": "Leaders",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stat": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": {
                            "type": "number"
                          },
                          "playerId": {
                            "type": "number"
                          },
                          "name": {
                            "type": "string"
                          },
                          "team": {
                            "type": "string"
                          },
                          "value": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown stat",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "stat",
            "in": "query",
            "required": false,
            "description": "passingYards, passingTouchdowns, rushingYards, receivingYards, tackles, sacks",
            "schema": {
              "type": "string"
            },
            "example": "passingYards"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1–20, default 5",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Use qa-admin-token / qa-viewer-token, or a JWT from POST /auth/v1/login."
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Cargo demo key: cargo-key-123."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    }
  }
}
