{ "openapi": "3.1.0", "info": { "title": "FPL Rivals API", "version": "1.0.0", "description": "Free, keyless JSON API for Fantasy Premier League (FPL): players, prices, fixtures, gameweeks, live scores, managers and leagues. It is built on the official FPL API, cached so it stays fast and does not overload FPL, with names, positions and prices in pounds joined in so you rarely need a second lookup.\n\n### Typical flows\n\n**Look up a manager.** Call `GET /search?q=&type=manager`. Each result in `data.managers` has an `id`: that is the manager id (FPL calls it the entry id). Use it with `GET /managers/{id}` for their season summary and rank, `GET /managers/{id}/history` for every gameweek, `GET /managers/{id}/picks/current` for the current squad with live points, `GET /managers/{id}/transfers` and `GET /managers/{id}/chips`.\n\n**Explore a mini-league.** Take a manager id, call `GET /managers/{id}/leagues` and pick a league `id`. `GET /leagues/{league_id}/standings` returns the table, and each row's `entry` is a manager id you can pass straight back to `/managers/{id}/picks/current` to compare rivals. Head-to-head leagues also have `GET /leagues/{league_id}/matches`.\n\n**Research a player.** Call `GET /search?q=&type=player` to get a player `id`. `GET /players/{id}` gives current price, form, ownership, expected stats, availability and the next five fixtures. `GET /players/{id}/history` has every match this season, `GET /players/{id}/price-history` the price by gameweek, and `GET /players/compare?ids=,` puts up to five side by side.\n\n**Plan a gameweek.** `GET /game` has the next deadline. Then `GET /injuries`, `GET /fixtures/difficulty?next=5`, `GET /fixtures/blanks-doubles`, `GET /analytics/captaincy`, `GET /transfers/trending` and `GET /prices/changes`.\n\n**Follow a live gameweek.** `GET /gameweeks/current/live` has every player's points so far, `GET /fixtures?gw=current` the scores, and `GET /managers/{id}/picks/current` a manager's points pick by pick.\n\n**Find the best players by any stat.** `GET /players?sort=&position=&limit=10`, for example `sort=form`, `sort=expected_goals` or `sort=selected_by_percent`, with `max_price` to cap the budget.\n\n### Conventions\n\n- Every success is `{ \"data\": ..., \"meta\": { \"generated_at\", \"stale\", \"source\" } }`. Lists that page add `total`, `limit` and `offset` to `meta`.\n- `price` is in millions of pounds (`12.5`). FPL's raw `now_cost` is the same in tenths (`125`), and is kept alongside.\n- Any `{gw}` or `gw` accepts a number or `current`, `next` or `previous`. `team` accepts an id, a short name (`ARS`) or a name (`Arsenal`). `position` is `GKP`, `DEF`, `MID` or `FWD`.\n- FPL sends many decimals as strings, e.g. `\"form\": \"5.3\"` and `\"selected_by_percent\": \"41.2\"`. They are passed through as FPL sends them.\n- Player objects keep every FPL field and add `team_name`, `team_short_name`, `position`, `price`, `start_price` and `photo_url`. On `/players`, pass `fields=all` or a comma-separated list to choose what comes back.\n\n### Freshness, limits and errors\n\n- Responses are cached for 60 seconds, and the FPL data behind them for up to 5 minutes (30 for per-player history). `meta.stale` is `true` when FPL was down and the last good copy was served instead, which is common for an hour or so while FPL scores a gameweek.\n- No key or sign-up. Up to 600 requests per minute per IP, and 60 per minute for uncached `/managers`, `/leagues` and `/players/{id}/...` requests. Over the limit you get `429` with a `Retry-After` header.\n- Errors are `{ \"error\": { \"code\", \"message\" } }`: `bad_request` (400), `not_found` (404), `rate_limited` (429), `fpl_unavailable` (502).\n\nData comes from the official Fantasy Premier League game. FPL Rivals is not affiliated with the Premier League.", "contact": { "name": "FPL Rivals", "url": "https://fplrivals.org/contact/", "email": "support@fplrivals.org" } }, "servers": [ { "url": "https://api.fplrivals.org/api/v1" } ], "externalDocs": { "description": "Human-readable docs", "url": "https://fplrivals.org/api/" }, "tags": [ { "name": "Meta" }, { "name": "Search" }, { "name": "Game" }, { "name": "Gameweeks" }, { "name": "Fixtures" }, { "name": "Teams" }, { "name": "Players" }, { "name": "Prices" }, { "name": "Analytics" }, { "name": "Managers" }, { "name": "Leagues" } ], "paths": { "/": { "get": { "operationId": "getIndex", "tags": [ "Meta" ], "summary": "List every endpoint", "description": "The API's name, links to these docs and the OpenAPI spec, the rate limits, and every endpoint with a one-line summary. A good first call for an agent.", "parameters": [], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "tags": [ "Meta" ], "summary": "This OpenAPI spec", "description": "The full OpenAPI 3.1 description of this API, including the typical flows above. Not wrapped in the `data` envelope.", "parameters": [], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/game": { "get": { "operationId": "getGame", "tags": [ "Game" ], "summary": "Current season and gameweek state", "description": "The season (e.g. `2026/27`), the current and next gameweek with deadlines, how many gameweeks there are, the total number of FPL players, the upcoming nightly price-change deadlines, and FPL's event status (whether bonus points have been added and leagues updated).", "parameters": [], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/rules": { "get": { "operationId": "getRules", "tags": [ "Game" ], "summary": "Game rules, positions and chips", "description": "Squad rules per position (how many to pick and play), the chips with the gameweeks each can be played in, the season phases, and FPL's raw `game_settings` and `game_config` (budget, transfer rules, scoring and more).", "parameters": [], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/search": { "get": { "operationId": "search", "tags": [ "Search" ], "summary": "Search players, teams and managers by name", "description": "Finds players, Premier League teams and FPL managers in one call. Player matching ignores accents and case (`odegaard` finds Ødegaard) and ranks exact and prefix matches of the short name first, then by ownership. Managers are matched on their real name or their FPL team name and need at least 3 characters. Each result's `id` is what the other endpoints take: `players[].id` for `/players/{id}`, `teams[].id` for `/teams/{team}`, `managers[].id` for `/managers/{id}`.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "What to search for: a player, team, manager or FPL team name. At least 2 characters.", "schema": { "type": "string" }, "example": "haaland" }, { "name": "type", "in": "query", "required": false, "description": "Limit to some kinds, comma-separated: `player`, `team`, `manager`. Default all three.", "schema": { "type": "string" }, "example": "player,manager" }, { "name": "limit", "in": "query", "required": false, "description": "Results per kind, 1 to 50. Default 10.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Matches grouped by kind.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "players": [ { "id": 411, "web_name": "Haaland", "name": "Erling Haaland", "team_short_name": "MCI", "position": "FWD", "price": 15.6 } ], "teams": [], "managers": [ { "id": 1234567, "player_name": "Sam Haaland", "entry_name": "Haaland Heroes" } ] }, "meta": { "generated_at": "2026-09-23T10:00:00Z", "stale": false, "source": "fantasy.premierleague.com via fplrivals.org" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/gameweeks": { "get": { "operationId": "listGameweeks", "tags": [ "Gameweeks" ], "summary": "Every gameweek of the season", "description": "One row per gameweek: id, name, deadline, whether it is finished, current or next, the average and highest score.", "parameters": [], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/gameweeks/{gw}": { "get": { "operationId": "getGameweek", "tags": [ "Gameweeks" ], "summary": "One gameweek in detail", "description": "Everything FPL records about a gameweek: average and highest scores, chip plays, transfers made, and the most selected, captained, vice-captained and transferred-in players plus the top scorer, each resolved to a name (`*_player`). Includes the gameweek's fixtures.", "parameters": [ { "$ref": "#/components/parameters/Gameweek" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/gameweeks/{gw}/live": { "get": { "operationId": "getGameweekLive", "tags": [ "Gameweeks" ], "summary": "Live player points for a gameweek", "description": "Every player's points and underlying stats (minutes, goals, assists, clean sheets, saves, bonus, BPS, defensive contributions, expected stats) for the gameweek, highest first. Updates during matches. Pass `include=explain` for FPL's per-fixture breakdown of how the points were earned.", "parameters": [ { "$ref": "#/components/parameters/Gameweek" }, { "$ref": "#/components/parameters/Team" }, { "$ref": "#/components/parameters/Position" }, { "name": "include", "in": "query", "required": false, "description": "`explain` adds the per-fixture points breakdown.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/gameweeks/{gw}/dream-team": { "get": { "operationId": "getDreamTeam", "tags": [ "Gameweeks" ], "summary": "Team of the week", "description": "The highest-scoring XI of a finished gameweek and its top player, with points.", "parameters": [ { "$ref": "#/components/parameters/Gameweek" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/fixtures": { "get": { "operationId": "listFixtures", "tags": [ "Fixtures" ], "summary": "Fixtures and results", "description": "Every fixture of the season, or those matching the filters: kickoff time, both teams with their score and FPL difficulty rating (1 easiest to 5 hardest), and whether it has started or finished.", "parameters": [ { "name": "gw", "in": "query", "required": false, "description": "Only this gameweek: a number, `current`, `next` or `previous`.", "schema": { "type": "string" }, "example": "next" }, { "$ref": "#/components/parameters/Team" }, { "name": "finished", "in": "query", "required": false, "description": "Only finished (`true`) or unfinished (`false`) fixtures.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/fixtures/{id}": { "get": { "operationId": "getFixture", "tags": [ "Fixtures" ], "summary": "One fixture with match stats", "description": "A single fixture with its per-player stats: goals, assists, cards, saves, bonus and BPS, each with the player's name.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Fixture id, from `/fixtures`.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/fixtures/difficulty": { "get": { "operationId": "getFixtureDifficulty", "tags": [ "Fixtures" ], "summary": "Fixture difficulty for every team", "description": "Each team's upcoming run of fixtures with FPL difficulty ratings, total and average difficulty and any blank gameweeks, easiest run first. The standard way to find teams with good fixtures.", "parameters": [ { "name": "next", "in": "query", "required": false, "description": "How many gameweeks to look ahead, 1 to 10. Default 5.", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "required": false, "description": "First gameweek of the window. Default the next gameweek.", "schema": { "type": "string" }, "example": "next" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/fixtures/blanks-doubles": { "get": { "operationId": "getBlanksAndDoubles", "tags": [ "Fixtures" ], "summary": "Blank and double gameweeks", "description": "For every remaining gameweek that has them, which teams have no fixture (blank) and which have two or more (double), plus fixtures not yet scheduled into a gameweek.", "parameters": [], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/teams": { "get": { "operationId": "listTeams", "tags": [ "Teams" ], "summary": "The 20 Premier League teams", "description": "Every team with FPL's strength ratings (overall, attack and defence, home and away) and badge URL.", "parameters": [], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/teams/{team}": { "get": { "operationId": "getTeam", "tags": [ "Teams" ], "summary": "One team: squad, fixtures and results", "description": "A team's strength ratings, its full FPL squad by position, its next six fixtures with difficulty, and its last five results.", "parameters": [ { "name": "team", "in": "path", "required": true, "description": "Team id, short name (`ARS`) or name (`Arsenal`).", "schema": { "type": "string" }, "example": "ARS" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/table": { "get": { "operationId": "getTable", "tags": [ "Teams" ], "summary": "Premier League table", "description": "The league table computed from finished fixtures: played, won, drawn, lost, goals, goal difference, points and the last five results.", "parameters": [], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/players": { "get": { "operationId": "listPlayers", "tags": [ "Players" ], "summary": "List, filter and sort players", "description": "All players, filterable by team, position, price, availability and name, sortable by any numeric FPL field. Returns a compact set of the most useful fields by default; use `fields` for more or fewer. Examples: top scorers `sort=total_points`; in-form midfielders `position=MID&sort=form`; cheap defenders `position=DEF&max_price=4.5&sort=total_points`; most owned `sort=selected_by_percent`.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Name contains, accent-insensitive.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Team" }, { "$ref": "#/components/parameters/Position" }, { "name": "min_price", "in": "query", "required": false, "description": "Minimum price in £m.", "schema": { "type": "number" }, "example": 4.5 }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum price in £m.", "schema": { "type": "number" }, "example": 8.0 }, { "name": "status", "in": "query", "required": false, "description": "FPL availability codes, comma-separated: `a` available, `d` doubtful, `i` injured, `s` suspended, `u` unavailable, `n` not eligible.", "schema": { "type": "string" } }, { "name": "available", "in": "query", "required": false, "description": "`true` for available players only, `false` for everyone else.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by: `price` or any player field, e.g. `total_points` (default), `form`, `ep_next`, `selected_by_percent`, `expected_goals`, `expected_assists`, `points_per_game`, `bonus`, `web_name`.", "schema": { "type": "string" }, "example": "form" }, { "name": "order", "in": "query", "required": false, "description": "`asc` or `desc`. Default `desc` for numbers, `asc` for names.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/players/compare": { "get": { "operationId": "comparePlayers", "tags": [ "Players" ], "summary": "Compare players side by side", "description": "Two to five players with every field plus their next five fixtures, in the order given.", "parameters": [ { "name": "ids", "in": "query", "required": true, "description": "2 to 5 player ids, comma-separated.", "schema": { "type": "string" }, "example": "411,12" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/players/{id}": { "get": { "operationId": "getPlayer", "tags": [ "Players" ], "summary": "One player in full", "description": "Every FPL field for a player: price and price changes, points, form, ownership, expected goals and assists, ICT index, set-piece order, availability with `status_label` and news, plus their next five fixtures with difficulty.", "parameters": [ { "$ref": "#/components/parameters/PlayerId" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/players/{id}/history": { "get": { "operationId": "getPlayerHistory", "tags": [ "Players" ], "summary": "A player's match-by-match season", "description": "One row per match this season (points, minutes, goals, assists, bonus, expected stats, price, ownership, transfers, opponent), and a summary of each past season.", "parameters": [ { "$ref": "#/components/parameters/PlayerId" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/players/{id}/price-history": { "get": { "operationId": "getPlayerPriceHistory", "tags": [ "Players" ], "summary": "A player's price by gameweek", "description": "Start-of-season and current price, and one row per gameweek with price, ownership and transfers in and out.", "parameters": [ { "$ref": "#/components/parameters/PlayerId" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/prices": { "get": { "operationId": "listPrices", "tags": [ "Prices" ], "summary": "Every player's current price", "description": "Current price, start-of-season price and change, this gameweek's change, ownership and transfers for every player, most expensive first. Takes the same filters and sorting as `/players`.", "parameters": [ { "$ref": "#/components/parameters/Team" }, { "$ref": "#/components/parameters/Position" }, { "name": "min_price", "in": "query", "required": false, "description": "Minimum price in £m.", "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum price in £m.", "schema": { "type": "number" } }, { "name": "sort", "in": "query", "required": false, "description": "Default `price`. Also e.g. `cost_change_start` for biggest risers since the season began.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/prices/changes": { "get": { "operationId": "getPriceChanges", "tags": [ "Prices" ], "summary": "Predicted and recent price changes", "description": "FPL's own price-change projections: players likely to rise or fall at the next nightly deadline (likelihood 4 or 5 either way), each with `progress` towards a change (100 is the line), a likelihood per upcoming deadline, and players who have already risen or fallen this gameweek. `deadlines` lists the upcoming nightly price-change times.", "parameters": [], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/injuries": { "get": { "operationId": "listInjuries", "tags": [ "Players" ], "summary": "Injured, doubtful and suspended players", "description": "Every player not fully available, with FPL's news, when it was added, chance of playing this and next round, and a plain `status_label`. Most owned first.", "parameters": [ { "$ref": "#/components/parameters/Team" }, { "$ref": "#/components/parameters/Position" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/transfers/trending": { "get": { "operationId": "getTrendingTransfers", "tags": [ "Players" ], "summary": "Most transferred in and out", "description": "The players most transferred in and most transferred out by all FPL managers in the current gameweek, with net transfers.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many of each, 1 to 50. Default 10.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/analytics/captaincy": { "get": { "operationId": "getCaptaincyPicks", "tags": [ "Analytics" ], "summary": "Captain candidates", "description": "Players likely to play next gameweek ranked by `ep_next`, FPL's own expected points for the next gameweek, with their fixture(s) that gameweek. A double gameweek shows two.", "parameters": [ { "$ref": "#/components/parameters/Team" }, { "$ref": "#/components/parameters/Position" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/analytics/differentials": { "get": { "operationId": "getDifferentials", "tags": [ "Analytics" ], "summary": "Low-owned players in form", "description": "Players likely to play whose ownership is at or below `max_ownership` percent, ranked by form then expected points.", "parameters": [ { "name": "max_ownership", "in": "query", "required": false, "description": "Ownership ceiling in percent. Default 10.", "schema": { "type": "number" } }, { "$ref": "#/components/parameters/Team" }, { "$ref": "#/components/parameters/Position" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/analytics/value": { "get": { "operationId": "getValuePicks", "tags": [ "Analytics" ], "summary": "Best value players", "description": "Points per million this season, highest first, with form per million alongside.", "parameters": [ { "name": "min_minutes", "in": "query", "required": false, "description": "Ignore players with fewer minutes than this. Default 1.", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Team" }, { "$ref": "#/components/parameters/Position" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/managers/{id}": { "get": { "operationId": "getManager", "tags": [ "Managers" ], "summary": "A manager's season summary", "description": "Name, FPL team name, country, overall points and rank, this gameweek's points and rank, team value and bank, and the year they started. Leagues are at `/managers/{id}/leagues`.", "parameters": [ { "$ref": "#/components/parameters/ManagerId" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/managers/{id}/history": { "get": { "operationId": "getManagerHistory", "tags": [ "Managers" ], "summary": "A manager's gameweek-by-gameweek season", "description": "`current`: every gameweek's points, total, gameweek and overall rank, transfers and their cost, bench points, team value and bank. `past`: each previous season's points and final rank. `chips`: chips played.", "parameters": [ { "$ref": "#/components/parameters/ManagerId" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/managers/{id}/picks/{gw}": { "get": { "operationId": "getManagerPicks", "tags": [ "Managers" ], "summary": "A manager's squad for a gameweek", "description": "The 15 players picked for a gameweek in squad order (slots 1 to 11 start, 12 to 15 are the bench), captain and vice, multipliers, each player's live points, the chip played, automatic substitutions and the gameweek summary. Use `current` for the squad right now.", "parameters": [ { "$ref": "#/components/parameters/ManagerId" }, { "$ref": "#/components/parameters/Gameweek" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/managers/{id}/transfers": { "get": { "operationId": "getManagerTransfers", "tags": [ "Managers" ], "summary": "Every transfer a manager has made", "description": "All transfers this season, newest first: gameweek, time, the players in and out with names, and the prices paid and received.", "parameters": [ { "$ref": "#/components/parameters/ManagerId" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/managers/{id}/chips": { "get": { "operationId": "getManagerChips", "tags": [ "Managers" ], "summary": "Chips played and still available", "description": "Chips the manager has played (with gameweek) and those still available, each with the gameweek window it can be used in.", "parameters": [ { "$ref": "#/components/parameters/ManagerId" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/managers/{id}/leagues": { "get": { "operationId": "getManagerLeagues", "tags": [ "Managers" ], "summary": "Leagues a manager is in", "description": "Every classic and head-to-head league the manager has joined, with their rank in each, plus the cup. Each league's `id` works with `/leagues/{id}/standings`.", "parameters": [ { "$ref": "#/components/parameters/ManagerId" } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/leagues/{id}/standings": { "get": { "operationId": "getLeagueStandings", "tags": [ "Leagues" ], "summary": "League table", "description": "A classic or head-to-head league's standings, 50 per page: rank, last rank, manager name, FPL team name, gameweek and total points. Each row's `entry` is a manager id for `/managers/{id}`. League `314` is the overall global league.", "parameters": [ { "$ref": "#/components/parameters/LeagueId" }, { "name": "type", "in": "query", "required": false, "description": "`classic` or `h2h`. Default: try classic, then head-to-head.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page of 50 standings, from 1.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } }, "/leagues/{id}/matches": { "get": { "operationId": "getLeagueMatches", "tags": [ "Leagues" ], "summary": "Head-to-head league matches", "description": "Match results for a head-to-head league, optionally for one gameweek, with both managers, their points and the winner.", "parameters": [ { "$ref": "#/components/parameters/LeagueId" }, { "name": "gw", "in": "query", "required": false, "description": "Only this gameweek: a number, `current`, `next` or `previous`.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page of results, from 1.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The requested data in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/FplUnavailable" } } } } }, "components": { "parameters": { "Gameweek": { "name": "gw", "in": "path", "required": true, "description": "Gameweek number (1 to 38), or `current`, `next` or `previous`.", "schema": { "type": "string" }, "example": "current" }, "PlayerId": { "name": "id", "in": "path", "required": true, "description": "Player id, from `/search` or `/players`.", "schema": { "type": "integer" }, "example": 411 }, "ManagerId": { "name": "id", "in": "path", "required": true, "description": "Manager (entry) id, from `/search?type=manager`, a league's standings, or the number in an FPL team URL.", "schema": { "type": "integer" }, "example": 1234567 }, "LeagueId": { "name": "id", "in": "path", "required": true, "description": "League id, from `/managers/{id}/leagues` or the number in an FPL league URL.", "schema": { "type": "integer" }, "example": 314 }, "Team": { "name": "team", "in": "query", "required": false, "description": "Team id, short name (`ARS`) or name (`Arsenal`).", "schema": { "type": "string" }, "example": "LIV" }, "Position": { "name": "position", "in": "query", "required": false, "description": "`GKP`, `DEF`, `MID` or `FWD`.", "schema": { "type": "string", "enum": [ "GKP", "DEF", "MID", "FWD" ] } }, "Fields": { "name": "fields", "in": "query", "required": false, "description": "`all` for every field, or a comma-separated list, e.g. `id,web_name,price,form`.", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 1000.", "schema": { "type": "integer" } }, "Offset": { "name": "offset", "in": "query", "required": false, "description": "Rows to skip, for paging.", "schema": { "type": "integer" } } }, "schemas": { "Envelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "description": "The result. An object or a list, as each endpoint describes." }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Meta": { "type": "object", "properties": { "generated_at": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean", "description": "True when FPL was unavailable and the last good copy was served." }, "source": { "type": "string" }, "total": { "type": "integer", "description": "Paged lists only: rows before paging." }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "not_found", "rate_limited", "fpl_unavailable", "internal" ] }, "message": { "type": "string", "description": "What went wrong and what to do about it." }, "retry_after": { "type": "integer", "description": "Seconds to wait. Only on 429." } } } } } }, "responses": { "BadRequest": { "description": "A parameter is missing or invalid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such player, manager, league, gameweek, team or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests. Wait for the `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "FplUnavailable": { "description": "The official FPL API is down and there is no cached copy. Retry in a few minutes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }