{ "openapi": "3.0.3", "info": { "title": "The Cricket News Cricket API", "version": "1.0.0", "description": "Send your key in the X-API-Key header. All responses are JSON: {\"status\":\"success\",\"data\":...,\"meta\":...} or {\"status\":\"error\",\"error\":{\"code\",\"message\"}}." }, "servers": [ { "url": "https://thecricket.news/api/v1" } ], "tags": [ { "name": "Auth", "description": "Sign in with email + password to get a short-lived access token (JWT) and a refresh token." }, { "name": "Account", "description": "Your own profile, plan, usage and API keys." }, { "name": "Matches", "description": "Fixtures, live matches and results." }, { "name": "Scores", "description": "Live score, scorecard, ball-by-ball, commentary, overs and partnerships." }, { "name": "Series", "description": "Series / tournaments, squads, points table and stats." }, { "name": "Teams", "description": "Teams and their players." }, { "name": "Players", "description": "Player profiles and career stats." }, { "name": "Venues", "description": "Grounds / stadiums." }, { "name": "News", "description": "Published news articles, categories, tags and authors." }, { "name": "Rankings", "description": "ICC team and player rankings." }, { "name": "Meta", "description": "Master data, search, health and public plan list." }, { "name": "Realtime", "description": "WebSocket live updates." } ], "paths": { "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Sign in (email + password) - returns access_token + refresh_token", "operationId": "post_auth_login", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "string" }, "password": { "type": "string", "description": "string" } } } } } } } }, "/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Exchange a refresh token for a new token pair (refresh tokens are single-use)", "operationId": "post_auth_refresh", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string", "description": "string" } } } } } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Revoke the current access token (+ refresh token). \"all\": true signs out every device", "operationId": "post_auth_logout", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string", "description": "string (optional)" }, "all": { "type": "boolean", "description": "bool (optional)" } } } } } } } }, "/account/me": { "get": { "tags": [ "Account" ], "summary": "Who am I (user, key in use, effective scopes)", "operationId": "get_account_me", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/account/subscription": { "get": { "tags": [ "Account" ], "summary": "Active plan, expiry, quota used / remaining", "operationId": "get_account_subscription", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/account/usage": { "get": { "tags": [ "Account" ], "summary": "Requests per day + top endpoints", "operationId": "get_account_usage", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Last N days (1-90, default 30)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/account/keys": { "get": { "tags": [ "Account" ], "summary": "List your API keys (never the secret)", "operationId": "get_account_keys", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] }, "post": { "tags": [ "Account" ], "summary": "Disabled - keys are issued by the administrator (403 keys_admin_only)", "operationId": "post_account_keys", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/account/keys/{id}": { "delete": { "tags": [ "Account" ], "summary": "Revoke one of your keys", "operationId": "delete_account_keys_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/matches": { "get": { "tags": [ "Matches" ], "summary": "All matches with filters", "operationId": "get_matches", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Comma separated match states", "schema": { "type": "string", "description": "comma separated: upcoming,toss_done,live,innings_break,completed,abandoned" } }, { "name": "series_id", "in": "query", "required": false, "description": "Only this series (includes its sub-series)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "team_id", "in": "query", "required": false, "description": "Matches of this team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "venue_id", "in": "query", "required": false, "description": "Matches at this venue", "schema": { "type": "integer", "minimum": 0 } }, { "name": "match_type_id", "in": "query", "required": false, "description": "Match type id (see /meta/match-types)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "required": false, "description": "Match format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20", "T10", "The100", "Custom" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Start date <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "required": false, "description": "Search in title / match number", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only (returned in the admin's featured order unless sort is given)", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by start time (prefix - for newest first) or by the admin's featured order", "schema": { "type": "string", "enum": [ "start_datetime", "-start_datetime", "featured" ] } }, { "name": "include", "in": "query", "required": false, "description": "Related objects to embed (default: all)", "schema": { "type": "string", "description": "comma separated: innings,series,teams,venue,match_type" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/matches/featured": { "get": { "tags": [ "Matches" ], "summary": "Featured matches in the order set by the admin (Featured Order screen)", "operationId": "get_matches_featured", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Comma separated match states", "schema": { "type": "string", "description": "comma separated: upcoming,toss_done,live,innings_break,completed,abandoned" } }, { "name": "series_id", "in": "query", "required": false, "description": "Only this series (includes its sub-series)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "team_id", "in": "query", "required": false, "description": "Matches of this team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "venue_id", "in": "query", "required": false, "description": "Matches at this venue", "schema": { "type": "integer", "minimum": 0 } }, { "name": "match_type_id", "in": "query", "required": false, "description": "Match type id (see /meta/match-types)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "required": false, "description": "Match format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20", "T10", "The100", "Custom" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Start date <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "required": false, "description": "Search in title / match number", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only (returned in the admin's featured order unless sort is given)", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by start time (prefix - for newest first) or by the admin's featured order", "schema": { "type": "string", "enum": [ "start_datetime", "-start_datetime", "featured" ] } }, { "name": "include", "in": "query", "required": false, "description": "Related objects to embed (default: all)", "schema": { "type": "string", "description": "comma separated: innings,series,teams,venue,match_type" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/matches/live": { "get": { "tags": [ "Matches" ], "summary": "Matches in progress (toss done / live / innings break)", "operationId": "get_matches_live", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Comma separated match states", "schema": { "type": "string", "description": "comma separated: upcoming,toss_done,live,innings_break,completed,abandoned" } }, { "name": "series_id", "in": "query", "required": false, "description": "Only this series (includes its sub-series)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "team_id", "in": "query", "required": false, "description": "Matches of this team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "venue_id", "in": "query", "required": false, "description": "Matches at this venue", "schema": { "type": "integer", "minimum": 0 } }, { "name": "match_type_id", "in": "query", "required": false, "description": "Match type id (see /meta/match-types)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "required": false, "description": "Match format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20", "T10", "The100", "Custom" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Start date <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "required": false, "description": "Search in title / match number", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only (returned in the admin's featured order unless sort is given)", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by start time (prefix - for newest first) or by the admin's featured order", "schema": { "type": "string", "enum": [ "start_datetime", "-start_datetime", "featured" ] } }, { "name": "include", "in": "query", "required": false, "description": "Related objects to embed (default: all)", "schema": { "type": "string", "description": "comma separated: innings,series,teams,venue,match_type" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/matches/upcoming": { "get": { "tags": [ "Matches" ], "summary": "Fixtures (soonest first)", "operationId": "get_matches_upcoming", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Comma separated match states", "schema": { "type": "string", "description": "comma separated: upcoming,toss_done,live,innings_break,completed,abandoned" } }, { "name": "series_id", "in": "query", "required": false, "description": "Only this series (includes its sub-series)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "team_id", "in": "query", "required": false, "description": "Matches of this team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "venue_id", "in": "query", "required": false, "description": "Matches at this venue", "schema": { "type": "integer", "minimum": 0 } }, { "name": "match_type_id", "in": "query", "required": false, "description": "Match type id (see /meta/match-types)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "required": false, "description": "Match format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20", "T10", "The100", "Custom" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Start date <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "required": false, "description": "Search in title / match number", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only (returned in the admin's featured order unless sort is given)", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by start time (prefix - for newest first) or by the admin's featured order", "schema": { "type": "string", "enum": [ "start_datetime", "-start_datetime", "featured" ] } }, { "name": "include", "in": "query", "required": false, "description": "Related objects to embed (default: all)", "schema": { "type": "string", "description": "comma separated: innings,series,teams,venue,match_type" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/matches/recent": { "get": { "tags": [ "Matches" ], "summary": "Finished matches (latest first)", "operationId": "get_matches_recent", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Comma separated match states", "schema": { "type": "string", "description": "comma separated: upcoming,toss_done,live,innings_break,completed,abandoned" } }, { "name": "series_id", "in": "query", "required": false, "description": "Only this series (includes its sub-series)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "team_id", "in": "query", "required": false, "description": "Matches of this team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "venue_id", "in": "query", "required": false, "description": "Matches at this venue", "schema": { "type": "integer", "minimum": 0 } }, { "name": "match_type_id", "in": "query", "required": false, "description": "Match type id (see /meta/match-types)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "required": false, "description": "Match format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20", "T10", "The100", "Custom" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Start date <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "required": false, "description": "Search in title / match number", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only (returned in the admin's featured order unless sort is given)", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by start time (prefix - for newest first) or by the admin's featured order", "schema": { "type": "string", "enum": [ "start_datetime", "-start_datetime", "featured" ] } }, { "name": "include", "in": "query", "required": false, "description": "Related objects to embed (default: all)", "schema": { "type": "string", "description": "comma separated: innings,series,teams,venue,match_type" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/matches/{id}": { "get": { "tags": [ "Matches" ], "summary": "One match with series, teams, venue, innings, toss, result, rules", "operationId": "get_matches_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/matches/{id}/squads": { "get": { "tags": [ "Matches" ], "summary": "Playing XI, impact players and substitutes of both teams", "operationId": "get_matches_id_squads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/matches/{id}/awards": { "get": { "tags": [ "Matches" ], "summary": "Player of the match and other awards", "operationId": "get_matches_id_awards", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/matches/{id}/officials": { "get": { "tags": [ "Matches" ], "summary": "On-field / third / reserve umpires and the match referee", "operationId": "get_matches_id_officials", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/matches/{id}/live": { "get": { "tags": [ "Scores" ], "summary": "Compact live widget: score, CRR/RRR, batters, bowler, last 12 balls", "operationId": "get_matches_id_live", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "scores.read", "description": "Required scope: `scores.read`" } }, "/matches/{id}/scorecard": { "get": { "tags": [ "Scores" ], "summary": "Full scorecard: batting, bowling, extras, fall of wickets, partnerships, did not bat", "operationId": "get_matches_id_scorecard", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "scores.read", "description": "Required scope: `scores.read`" } }, "/matches/{id}/balls": { "get": { "tags": [ "Scores" ], "summary": "Ball-by-ball data. Poll with since_id for new balls", "operationId": "get_matches_id_balls", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "innings", "in": "query", "required": false, "description": "Innings number", "schema": { "type": "integer", "minimum": 0 } }, { "name": "over_from", "in": "query", "required": false, "description": "From over (0-based)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "over_to", "in": "query", "required": false, "description": "To over (0-based)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "since_id", "in": "query", "required": false, "description": "Only balls newer than this id", "schema": { "type": "integer", "minimum": 0 } }, { "name": "before_id", "in": "query", "required": false, "description": "Only balls older than this id", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows (default 120, max 500)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "scores.read", "description": "Required scope: `scores.read`" } }, "/matches/{id}/commentary": { "get": { "tags": [ "Scores" ], "summary": "Commentary, newest first", "operationId": "get_matches_id_commentary", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "innings", "in": "query", "required": false, "description": "Innings number", "schema": { "type": "integer", "minimum": 0 } }, { "name": "since_id", "in": "query", "required": false, "description": "Only newer than this id", "schema": { "type": "integer", "minimum": 0 } }, { "name": "before_id", "in": "query", "required": false, "description": "Load more: older than this id", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows (default 30, max 500)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "scores.read", "description": "Required scope: `scores.read`" } }, "/matches/{id}/overs": { "get": { "tags": [ "Scores" ], "summary": "Over-by-over summary (runs, wickets, bowler, ball symbols)", "operationId": "get_matches_id_overs", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "innings", "in": "query", "required": false, "description": "Innings number", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "scores.read", "description": "Required scope: `scores.read`" } }, "/matches/{id}/partnerships": { "get": { "tags": [ "Scores" ], "summary": "All partnerships", "operationId": "get_matches_id_partnerships", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "scores.read", "description": "Required scope: `scores.read`" } }, "/matches/{id}/events": { "get": { "tags": [ "Scores" ], "summary": "Toss, innings start/end, DLS, substitutions, rain etc.", "operationId": "get_matches_id_events", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "scores.read", "description": "Required scope: `scores.read`" } }, "/series": { "get": { "tags": [ "Series" ], "summary": "Series list", "operationId": "get_series", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Series type", "schema": { "type": "string", "enum": [ "International", "Domestic", "League" ] } }, { "name": "status", "in": "query", "required": false, "description": "By dates", "schema": { "type": "string", "enum": [ "upcoming", "ongoing", "completed" ] } }, { "name": "league_id", "in": "query", "required": false, "description": "League", "schema": { "type": "integer", "minimum": 0 } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only", "schema": { "type": "boolean" } }, { "name": "season", "in": "query", "required": false, "description": "e.g. 2026 or 2025-26", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Domestic series country", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "required": false, "description": "Sub-series of this series", "schema": { "type": "integer", "minimum": 0 } }, { "name": "with_sub", "in": "query", "required": false, "description": "Include sub-series in the list", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Order (featured = admin's featured order; default for featured=1)", "schema": { "type": "string", "enum": [ "start_date", "-start_date", "featured", "name" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "series.read", "description": "Required scope: `series.read`" } }, "/series/featured": { "get": { "tags": [ "Series" ], "summary": "Featured series in the order set by the admin", "operationId": "get_series_featured", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "series.read", "description": "Required scope: `series.read`" } }, "/series/{id}": { "get": { "tags": [ "Series" ], "summary": "Series detail (id or slug) with sub-series, formats, teams, match counts", "operationId": "get_series_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "series.read", "description": "Required scope: `series.read`" } }, "/series/{id}/matches": { "get": { "tags": [ "Series" ], "summary": "Matches of a series", "operationId": "get_series_id_matches", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "status", "in": "query", "required": false, "description": "Comma separated match states", "schema": { "type": "string", "description": "comma separated: upcoming,toss_done,live,innings_break,completed,abandoned" } }, { "name": "series_id", "in": "query", "required": false, "description": "Only this series (includes its sub-series)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "team_id", "in": "query", "required": false, "description": "Matches of this team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "venue_id", "in": "query", "required": false, "description": "Matches at this venue", "schema": { "type": "integer", "minimum": 0 } }, { "name": "match_type_id", "in": "query", "required": false, "description": "Match type id (see /meta/match-types)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "required": false, "description": "Match format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20", "T10", "The100", "Custom" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Start date <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "required": false, "description": "Search in title / match number", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only (returned in the admin's featured order unless sort is given)", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by start time (prefix - for newest first) or by the admin's featured order", "schema": { "type": "string", "enum": [ "start_datetime", "-start_datetime", "featured" ] } }, { "name": "include", "in": "query", "required": false, "description": "Related objects to embed (default: all)", "schema": { "type": "string", "description": "comma separated: innings,series,teams,venue,match_type" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/series/{id}/teams": { "get": { "tags": [ "Series" ], "summary": "Teams in a series", "operationId": "get_series_id_teams", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "series.read", "description": "Required scope: `series.read`" } }, "/series/{id}/squads": { "get": { "tags": [ "Series" ], "summary": "Squads of a series", "operationId": "get_series_id_squads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "team_id", "in": "query", "required": false, "description": "Only this team", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "series.read", "description": "Required scope: `series.read`" } }, "/series/{id}/points-table": { "get": { "tags": [ "Series" ], "summary": "Points table with NRR and last-5 form (flat; every row has its group). 404 points_table_not_available when the series has no table", "operationId": "get_series_id_points_table", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "group_id", "in": "query", "required": false, "description": "Only this group", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "series.read", "description": "Required scope: `series.read`" } }, "/series/{id}/points-table/groups": { "get": { "tags": [ "Series" ], "summary": "Group-wise points tables (ICC style: Group A, Group B ...)", "operationId": "get_series_id_points_table_groups", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "series.read", "description": "Required scope: `series.read`" } }, "/series/{id}/stats": { "get": { "tags": [ "Series" ], "summary": "Most runs, sixes, wickets, best strike rate / economy", "operationId": "get_series_id_stats", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "limit", "in": "query", "required": false, "description": "Rows per list (default 10, max 50)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "stats.read", "description": "Required scope: `stats.read`" } }, "/teams": { "get": { "tags": [ "Teams" ], "summary": "Teams list", "operationId": "get_teams", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Country", "schema": { "type": "string" } }, { "name": "team_type_id", "in": "query", "required": false, "description": "Team type", "schema": { "type": "integer", "minimum": 0 } }, { "name": "league_id", "in": "query", "required": false, "description": "League", "schema": { "type": "integer", "minimum": 0 } }, { "name": "gender", "in": "query", "required": false, "description": "Gender", "schema": { "type": "string", "enum": [ "Male", "Female", "Mixed" ] } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only", "schema": { "type": "boolean" } }, { "name": "series_id", "in": "query", "required": false, "description": "Teams in this series", "schema": { "type": "integer", "minimum": 0 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "teams.read", "description": "Required scope: `teams.read`" } }, "/teams/{id}": { "get": { "tags": [ "Teams" ], "summary": "Team detail (id or slug) with formats, captains, featured players", "operationId": "get_teams_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "teams.read", "description": "Required scope: `teams.read`" } }, "/teams/{id}/players": { "get": { "tags": [ "Teams" ], "summary": "Players of a team", "operationId": "get_teams_id_players", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "teams.read", "description": "Required scope: `teams.read`" } }, "/teams/{id}/matches": { "get": { "tags": [ "Teams" ], "summary": "Matches of a team (newest first)", "operationId": "get_teams_id_matches", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "status", "in": "query", "required": false, "description": "Comma separated match states", "schema": { "type": "string", "description": "comma separated: upcoming,toss_done,live,innings_break,completed,abandoned" } }, { "name": "series_id", "in": "query", "required": false, "description": "Only this series (includes its sub-series)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "team_id", "in": "query", "required": false, "description": "Matches of this team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "venue_id", "in": "query", "required": false, "description": "Matches at this venue", "schema": { "type": "integer", "minimum": 0 } }, { "name": "match_type_id", "in": "query", "required": false, "description": "Match type id (see /meta/match-types)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "required": false, "description": "Match format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20", "T10", "The100", "Custom" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Start date <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "required": false, "description": "Search in title / match number", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only (returned in the admin's featured order unless sort is given)", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by start time (prefix - for newest first) or by the admin's featured order", "schema": { "type": "string", "enum": [ "start_datetime", "-start_datetime", "featured" ] } }, { "name": "include", "in": "query", "required": false, "description": "Related objects to embed (default: all)", "schema": { "type": "string", "description": "comma separated: innings,series,teams,venue,match_type" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/players": { "get": { "tags": [ "Players" ], "summary": "Players list", "operationId": "get_players", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Country", "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "description": "Playing role", "schema": { "type": "string", "enum": [ "Batsman", "Bowler", "All-Rounder", "Wicket-Keeper" ] } }, { "name": "gender", "in": "query", "required": false, "description": "Gender", "schema": { "type": "string", "enum": [ "Male", "Female" ] } }, { "name": "team_id", "in": "query", "required": false, "description": "Players of this team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "players.read", "description": "Required scope: `players.read`" } }, "/players/{id}": { "get": { "tags": [ "Players" ], "summary": "Player profile (id or slug)", "operationId": "get_players_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "players.read", "description": "Required scope: `players.read`" } }, "/players/{id}/stats": { "get": { "tags": [ "Players" ], "summary": "Career batting + bowling stats per format", "operationId": "get_players_id_stats", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "format", "in": "query", "required": false, "description": "Only this format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20", "T10", "The100", "Custom" ] } }, { "name": "match_type_id", "in": "query", "required": false, "description": "Only this match type", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "stats.read", "description": "Required scope: `stats.read`" } }, "/players/{id}/matches": { "get": { "tags": [ "Players" ], "summary": "Matches the player played", "operationId": "get_players_id_matches", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/venues": { "get": { "tags": [ "Venues" ], "summary": "Venues list", "operationId": "get_venues", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Country", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "City", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "venues.read", "description": "Required scope: `venues.read`" } }, "/venues/{id}": { "get": { "tags": [ "Venues" ], "summary": "Venue detail (id or slug)", "operationId": "get_venues_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "venues.read", "description": "Required scope: `venues.read`" } }, "/venues/{id}/matches": { "get": { "tags": [ "Venues" ], "summary": "Matches at a venue", "operationId": "get_venues_id_matches", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "status", "in": "query", "required": false, "description": "Comma separated match states", "schema": { "type": "string", "description": "comma separated: upcoming,toss_done,live,innings_break,completed,abandoned" } }, { "name": "series_id", "in": "query", "required": false, "description": "Only this series (includes its sub-series)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "team_id", "in": "query", "required": false, "description": "Matches of this team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "venue_id", "in": "query", "required": false, "description": "Matches at this venue", "schema": { "type": "integer", "minimum": 0 } }, { "name": "match_type_id", "in": "query", "required": false, "description": "Match type id (see /meta/match-types)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "required": false, "description": "Match format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20", "T10", "The100", "Custom" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Start date <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "required": false, "description": "Search in title / match number", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only (returned in the admin's featured order unless sort is given)", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by start time (prefix - for newest first) or by the admin's featured order", "schema": { "type": "string", "enum": [ "start_datetime", "-start_datetime", "featured" ] } }, { "name": "include", "in": "query", "required": false, "description": "Related objects to embed (default: all)", "schema": { "type": "string", "description": "comma separated: innings,series,teams,venue,match_type" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "matches.read", "description": "Required scope: `matches.read`" } }, "/news": { "get": { "tags": [ "News" ], "summary": "Published articles", "operationId": "get_news", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Category id or slug (includes sub-categories)", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Tag id or slug", "schema": { "type": "string" } }, { "name": "author", "in": "query", "required": false, "description": "Author id or slug", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "required": false, "description": "Featured only", "schema": { "type": "boolean" } }, { "name": "team_id", "in": "query", "required": false, "description": "Tagged with team", "schema": { "type": "integer", "minimum": 0 } }, { "name": "player_id", "in": "query", "required": false, "description": "Tagged with player", "schema": { "type": "integer", "minimum": 0 } }, { "name": "series_id", "in": "query", "required": false, "description": "Tagged with series", "schema": { "type": "integer", "minimum": 0 } }, { "name": "match_id", "in": "query", "required": false, "description": "Tagged with match", "schema": { "type": "integer", "minimum": 0 } }, { "name": "venue_id", "in": "query", "required": false, "description": "Tagged with venue", "schema": { "type": "integer", "minimum": 0 } }, { "name": "from", "in": "query", "required": false, "description": "Published on/after", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Published on/before", "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "required": false, "description": "Order", "schema": { "type": "string", "enum": [ "latest", "popular" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "news.read", "description": "Required scope: `news.read`" } }, "/news/categories": { "get": { "tags": [ "News" ], "summary": "Category tree with article counts", "operationId": "get_news_categories", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "news.read", "description": "Required scope: `news.read`" } }, "/news/tags": { "get": { "tags": [ "News" ], "summary": "Tags with article counts", "operationId": "get_news_tags", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max (default 100)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "news.read", "description": "Required scope: `news.read`" } }, "/news/authors": { "get": { "tags": [ "News" ], "summary": "Active authors", "operationId": "get_news_authors", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "news.read", "description": "Required scope: `news.read`" } }, "/news/authors/{id}": { "get": { "tags": [ "News" ], "summary": "Author profile (id or slug)", "operationId": "get_news_authors_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "news.read", "description": "Required scope: `news.read`" } }, "/news/{id}": { "get": { "tags": [ "News" ], "summary": "Full article (id or slug) with SEO, related entities and more stories", "operationId": "get_news_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" }, { "name": "count_view", "in": "query", "required": false, "description": "Frontend keys only, legacy: count a page view (skips the cache - prefer POST /news/{id}/view)", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "news.read", "description": "Required scope: `news.read`" } }, "/news/{id}/view": { "post": { "tags": [ "News" ], "summary": "Frontend keys only: count one page view (max 1 per visitor IP / article / 30 min)", "operationId": "post_news_id_view", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id (slug also accepted where noted)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "news.read", "description": "Required scope: `news.read`" } }, "/rankings": { "get": { "tags": [ "Rankings" ], "summary": "ICC rankings (Top 10) grouped by format + type", "operationId": "get_rankings", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "Format", "schema": { "type": "string", "enum": [ "Test", "ODI", "T20I" ] } }, { "name": "type", "in": "query", "required": false, "description": "Ranking type", "schema": { "type": "string", "enum": [ "Team", "Batting", "Bowling", "All-Rounder" ] } }, { "name": "gender", "in": "query", "required": false, "description": "Default Men", "schema": { "type": "string", "enum": [ "Men", "Women" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per group (1-10, default 10; larger values are capped)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "rankings.read", "description": "Required scope: `rankings.read`" } }, "/search": { "get": { "tags": [ "Meta" ], "summary": "Search teams, players, series, venues, matches and news at once", "operationId": "get_search", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Required, 2-100 chars", "schema": { "type": "string" } }, { "name": "types", "in": "query", "required": false, "description": "Groups to search", "schema": { "type": "string", "description": "comma separated: teams,players,series,venues,matches,news" } }, { "name": "limit", "in": "query", "required": false, "description": "Per group (default 5, max 20)", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "search.read", "description": "Required scope: `search.read`" } }, "/meta/match-types": { "get": { "tags": [ "Meta" ], "summary": "Match types", "operationId": "get_meta_match_types", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "meta.read", "description": "Required scope: `meta.read`" } }, "/meta/team-types": { "get": { "tags": [ "Meta" ], "summary": "Team types", "operationId": "get_meta_team_types", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "meta.read", "description": "Required scope: `meta.read`" } }, "/meta/leagues": { "get": { "tags": [ "Meta" ], "summary": "Leagues", "operationId": "get_meta_leagues", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "meta.read", "description": "Required scope: `meta.read`" } }, "/meta/countries": { "get": { "tags": [ "Meta" ], "summary": "Countries used by teams / players / venues", "operationId": "get_meta_countries", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "meta.read", "description": "Required scope: `meta.read`" } }, "/meta/scopes": { "get": { "tags": [ "Meta" ], "summary": "All API scopes", "operationId": "get_meta_scopes", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/plans": { "get": { "tags": [ "Meta" ], "summary": "Public plan list (payment is offline - the admin activates plans)", "operationId": "get_plans", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/health": { "get": { "tags": [ "Meta" ], "summary": "Service health", "operationId": "get_health", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/openapi.json": { "get": { "tags": [ "Meta" ], "summary": "OpenAPI 3 specification of this API", "operationId": "get_openapi_json", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/ws/token": { "get": { "tags": [ "Realtime" ], "summary": "Short-lived token to open the WebSocket (wss) connection", "operationId": "get_ws_token", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-required-scope": "ws.connect", "description": "Required scope: `ws.connect`" } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Success": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": [], "meta": { "type": "object" }, "request_id": { "type": "string" } } }, "Error": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "request_id": { "type": "string" } } } } } }