{
    "openapi": "3.1.0",
    "info": {
        "title": "stats.innerpulse.net NFL analytics API",
        "version": "1.0.0",
        "description": "Read-only NFL team, player, game and model data for the current season, built from nflverse play-by-play. No key needed. Responses are cached for up to 5 minutes; please keep to about one request a second. Every response carries the season, the week the data runs through and a scope note saying what the numbers cover. Metric keys are defined at /metrics. Credit stats.innerpulse.net when you use the numbers.",
        "contact": {
            "url": "https://stats.innerpulse.net/developers"
        }
    },
    "servers": [
        {
            "url": "https://stats.innerpulse.net/api/v1"
        }
    ],
    "paths": {
        "/meta": {
            "get": {
                "operationId": "getMeta",
                "summary": "Season, current week, weeks complete and when the data was built",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/teams": {
            "get": {
                "operationId": "listTeams",
                "summary": "All 32 teams: record, points and power score, A to Z",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/teams/{team}": {
            "get": {
                "operationId": "getTeam",
                "summary": "One team: record, power score, season stats with league ranks, schedule, injuries, roster",
                "parameters": [
                    {
                        "name": "team",
                        "in": "path",
                        "required": true,
                        "description": "Team abbreviation, e.g. KC, SF, LA, LAC, JAX",
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z]{2,3}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/rankings": {
            "get": {
                "operationId": "getPowerRankings",
                "summary": "Power rankings: all 32 teams best to worst by power score",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/standings": {
            "get": {
                "operationId": "getStandings",
                "summary": "Division standings, playoff seeds and tiebreak records",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/odds": {
            "get": {
                "operationId": "getPlayoffOdds",
                "summary": "Playoff, division, bye and Super Bowl odds from 10,000 simulated seasons",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/players": {
            "get": {
                "operationId": "getPositionLeaderboard",
                "summary": "Leaderboard for one position group (qualified players, season to date)",
                "parameters": [
                    {
                        "name": "group",
                        "in": "query",
                        "required": true,
                        "description": "Position group",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "DB",
                                "FRONT",
                                "K",
                                "QB",
                                "RB",
                                "TE",
                                "WR"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/players/{player_id}": {
            "get": {
                "operationId": "getPlayer",
                "summary": "One player: bio, season stats with ranks, game log",
                "parameters": [
                    {
                        "name": "player_id",
                        "in": "path",
                        "required": true,
                        "description": "nflverse GSIS id, e.g. 00-0033873 (find it with /search)",
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d{2}-\\d{7}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/games": {
            "get": {
                "operationId": "listGames",
                "summary": "Every game in a week with scores, lines and the model pick",
                "parameters": [
                    {
                        "name": "week",
                        "in": "query",
                        "required": false,
                        "description": "Week 1-22 (19-22 playoffs). Defaults to the current week.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 22
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/games/{game_id}": {
            "get": {
                "operationId": "getGame",
                "summary": "One game: result, model pick, box score, scoring, top performers, team stats",
                "parameters": [
                    {
                        "name": "game_id",
                        "in": "path",
                        "required": true,
                        "description": "season_week_away_home, e.g. 2026_10_CAR_NO",
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d{4}_\\d{2}_[A-Z]{2,3}_[A-Z]{2,3}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/model": {
            "get": {
                "operationId": "getModelPicks",
                "summary": "The model's picks for a week and its season record",
                "parameters": [
                    {
                        "name": "week",
                        "in": "query",
                        "required": false,
                        "description": "Week 1-22 (19-22 playoffs). Defaults to the current week.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 22
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/metrics": {
            "get": {
                "operationId": "listMetrics",
                "summary": "Every metric key with its label, definition, format and which direction is better",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/search": {
            "get": {
                "operationId": "search",
                "summary": "Find teams, players, games, coaches, pages and metrics by name",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Name or words to find (2+ characters)",
                        "schema": {
                            "type": "string",
                            "minLength": 2
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "all",
                                "team",
                                "player"
                            ],
                            "default": "all"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 40,
                            "default": 10
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Envelope": {
                "type": "object",
                "properties": {
                    "api": {
                        "type": "string",
                        "example": "v1"
                    },
                    "endpoint": {
                        "type": "string"
                    },
                    "season": {
                        "type": "integer",
                        "example": 2026
                    },
                    "data_through": {
                        "type": "object",
                        "properties": {
                            "week": {
                                "type": "integer"
                            },
                            "label": {
                                "type": "string"
                            }
                        }
                    },
                    "current_week": {
                        "type": "integer"
                    },
                    "built_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "scope": {
                        "type": "string",
                        "description": "What the numbers cover, in words"
                    },
                    "data": {
                        "description": "The payload; shape depends on the endpoint"
                    },
                    "source": {
                        "type": "string"
                    },
                    "docs": {
                        "type": "string"
                    }
                },
                "required": [
                    "api",
                    "season",
                    "data_through",
                    "scope",
                    "data"
                ]
            },
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "integer"
                            },
                            "message": {
                                "type": "string"
                            }
                        }
                    }
                }
            }
        }
    }
}