Skip to main content
API documentation

Cricket Data API reference

Base URL https://thecricket.news/api/v1 · JSON over HTTPS · machine-readable OpenAPI spec at /api/v1/docs.

Authentication

Send your key with every request: X-API-Key: YOUR_KEY. Apps signing in a user can use POST /auth/login and send Authorization: Bearer <access_token>. Each plan unlocks a set of scopes (shown next to every endpoint).

curl "https://thecricket.news/api/v1/series?status=ongoing" -H "X-API-Key: YOUR_KEY"

Responses & errors

Success: {"status":"success","data":…,"meta":{…}}. Errors: {"status":"error","error":{"code":"…","message":"…"}} with the right HTTP status - 401 missing / invalid key, 403 scope or plan, 404 not found, 422 invalid parameters, 429 rate limit (see Retry-After). Lists accept page and per_page (max 100).

Auth

Sign in with email + password to get a short-lived access token (JWT) and a refresh token.

POST /auth/login
Sign in (email + password) - returns access_token + refresh_token
POST /auth/refresh
Exchange a refresh token for a new token pair (refresh tokens are single-use)
POST /auth/logout
Revoke the current access token (+ refresh token). "all": true signs out every device

Account

Your own profile, plan, usage and API keys.

GET /account/me
Who am I (user, key in use, effective scopes)
GET /account/subscription
Active plan, expiry, quota used / remaining
GET /account/usage
Requests per day + top endpoints
days Last N days (1-90, default 30)
GET /account/keys
List your API keys (never the secret)
POST /account/keys
Disabled - keys are issued by the administrator (403 keys_admin_only)
DELETE /account/keys/{id}
Revoke one of your keys

Matches

Fixtures, live matches and results.

GET /matches
All matches with filters · scope matches.read
status Comma separated match states · series_id Only this series (includes its sub-series) · team_id Matches of this team · venue_id Matches at this venue · match_type_id Match type id (see /meta/match-types) · format Match format · from Start date >= (YYYY-MM-DD) · to Start date <= (YYYY-MM-DD) · q Search in title / match number · featured Featured only (returned in the admin's featured order unless sort is given) · sort Sort by start time (prefix - for newest first) or by the admin's featured order · include Related objects to embed (default: all) · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /matches/featured
Featured matches in the order set by the admin (Featured Order screen) · scope matches.read
status Comma separated match states · series_id Only this series (includes its sub-series) · team_id Matches of this team · venue_id Matches at this venue · match_type_id Match type id (see /meta/match-types) · format Match format · from Start date >= (YYYY-MM-DD) · to Start date <= (YYYY-MM-DD) · q Search in title / match number · featured Featured only (returned in the admin's featured order unless sort is given) · sort Sort by start time (prefix - for newest first) or by the admin's featured order · include Related objects to embed (default: all) · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /matches/live
Matches in progress (toss done / live / innings break) · scope matches.read
status Comma separated match states · series_id Only this series (includes its sub-series) · team_id Matches of this team · venue_id Matches at this venue · match_type_id Match type id (see /meta/match-types) · format Match format · from Start date >= (YYYY-MM-DD) · to Start date <= (YYYY-MM-DD) · q Search in title / match number · featured Featured only (returned in the admin's featured order unless sort is given) · sort Sort by start time (prefix - for newest first) or by the admin's featured order · include Related objects to embed (default: all) · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /matches/upcoming
Fixtures (soonest first) · scope matches.read
status Comma separated match states · series_id Only this series (includes its sub-series) · team_id Matches of this team · venue_id Matches at this venue · match_type_id Match type id (see /meta/match-types) · format Match format · from Start date >= (YYYY-MM-DD) · to Start date <= (YYYY-MM-DD) · q Search in title / match number · featured Featured only (returned in the admin's featured order unless sort is given) · sort Sort by start time (prefix - for newest first) or by the admin's featured order · include Related objects to embed (default: all) · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /matches/recent
Finished matches (latest first) · scope matches.read
status Comma separated match states · series_id Only this series (includes its sub-series) · team_id Matches of this team · venue_id Matches at this venue · match_type_id Match type id (see /meta/match-types) · format Match format · from Start date >= (YYYY-MM-DD) · to Start date <= (YYYY-MM-DD) · q Search in title / match number · featured Featured only (returned in the admin's featured order unless sort is given) · sort Sort by start time (prefix - for newest first) or by the admin's featured order · include Related objects to embed (default: all) · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /matches/{id}
One match with series, teams, venue, innings, toss, result, rules · scope matches.read
GET /matches/{id}/squads
Playing XI, impact players and substitutes of both teams · scope matches.read
GET /matches/{id}/awards
Player of the match and other awards · scope matches.read
GET /matches/{id}/officials
On-field / third / reserve umpires and the match referee · scope matches.read

Scores

Live score, scorecard, ball-by-ball, commentary, overs and partnerships.

GET /matches/{id}/live
Compact live widget: score, CRR/RRR, batters, bowler, last 12 balls · scope scores.read
GET /matches/{id}/scorecard
Full scorecard: batting, bowling, extras, fall of wickets, partnerships, did not bat · scope scores.read
GET /matches/{id}/balls
Ball-by-ball data. Poll with since_id for new balls · scope scores.read
innings Innings number · over_from From over (0-based) · over_to To over (0-based) · since_id Only balls newer than this id · before_id Only balls older than this id · limit Max rows (default 120, max 500)
GET /matches/{id}/commentary
Commentary, newest first · scope scores.read
innings Innings number · since_id Only newer than this id · before_id Load more: older than this id · limit Max rows (default 30, max 500)
GET /matches/{id}/overs
Over-by-over summary (runs, wickets, bowler, ball symbols) · scope scores.read
innings Innings number
GET /matches/{id}/partnerships
All partnerships · scope scores.read
GET /matches/{id}/events
Toss, innings start/end, DLS, substitutions, rain etc. · scope scores.read

Series

Series / tournaments, squads, points table and stats.

GET /series
Series list · scope series.read
type Series type · status By dates · league_id League · featured Featured only · season e.g. 2026 or 2025-26 · country Domestic series country · q Search · parent_id Sub-series of this series · with_sub Include sub-series in the list · sort Order (featured = admin's featured order; default for featured=1) · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /series/featured
Featured series in the order set by the admin · scope series.read
page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /series/{id}
Series detail (id or slug) with sub-series, formats, teams, match counts · scope series.read
GET /series/{id}/matches
Matches of a series · scope matches.read
status Comma separated match states · series_id Only this series (includes its sub-series) · team_id Matches of this team · venue_id Matches at this venue · match_type_id Match type id (see /meta/match-types) · format Match format · from Start date >= (YYYY-MM-DD) · to Start date <= (YYYY-MM-DD) · q Search in title / match number · featured Featured only (returned in the admin's featured order unless sort is given) · sort Sort by start time (prefix - for newest first) or by the admin's featured order · include Related objects to embed (default: all) · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /series/{id}/teams
Teams in a series · scope series.read
GET /series/{id}/squads
Squads of a series · scope series.read
team_id Only this team
GET /series/{id}/points-table
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 · scope series.read
group_id Only this group
GET /series/{id}/points-table/groups
Group-wise points tables (ICC style: Group A, Group B ...) · scope series.read
GET /series/{id}/stats
Most runs, sixes, wickets, best strike rate / economy · scope stats.read
limit Rows per list (default 10, max 50)

Teams

Teams and their players.

GET /teams
Teams list · scope teams.read
q Search · country Country · team_type_id Team type · league_id League · gender Gender · featured Featured only · series_id Teams in this series · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /teams/{id}
Team detail (id or slug) with formats, captains, featured players · scope teams.read
GET /teams/{id}/players
Players of a team · scope teams.read
GET /teams/{id}/matches
Matches of a team (newest first) · scope matches.read
status Comma separated match states · series_id Only this series (includes its sub-series) · team_id Matches of this team · venue_id Matches at this venue · match_type_id Match type id (see /meta/match-types) · format Match format · from Start date >= (YYYY-MM-DD) · to Start date <= (YYYY-MM-DD) · q Search in title / match number · featured Featured only (returned in the admin's featured order unless sort is given) · sort Sort by start time (prefix - for newest first) or by the admin's featured order · include Related objects to embed (default: all) · page Page number (default 1) · per_page Items per page (default 20, max 100)

Players

Player profiles and career stats.

GET /players
Players list · scope players.read
q Search · country Country · role Playing role · gender Gender · team_id Players of this team · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /players/{id}
Player profile (id or slug) · scope players.read
GET /players/{id}/stats
Career batting + bowling stats per format · scope stats.read
format Only this format · match_type_id Only this match type
GET /players/{id}/matches
Matches the player played · scope matches.read
page Page number (default 1) · per_page Items per page (default 20, max 100)

Venues

Grounds / stadiums.

GET /venues
Venues list · scope venues.read
q Search · country Country · city City · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /venues/{id}
Venue detail (id or slug) · scope venues.read
GET /venues/{id}/matches
Matches at a venue · scope matches.read
status Comma separated match states · series_id Only this series (includes its sub-series) · team_id Matches of this team · venue_id Matches at this venue · match_type_id Match type id (see /meta/match-types) · format Match format · from Start date >= (YYYY-MM-DD) · to Start date <= (YYYY-MM-DD) · q Search in title / match number · featured Featured only (returned in the admin's featured order unless sort is given) · sort Sort by start time (prefix - for newest first) or by the admin's featured order · include Related objects to embed (default: all) · page Page number (default 1) · per_page Items per page (default 20, max 100)

News

Published news articles, categories, tags and authors.

GET /news
Published articles · scope news.read
q Search · category Category id or slug (includes sub-categories) · tag Tag id or slug · author Author id or slug · featured Featured only · team_id Tagged with team · player_id Tagged with player · series_id Tagged with series · match_id Tagged with match · venue_id Tagged with venue · from Published on/after · to Published on/before · sort Order · page Page number (default 1) · per_page Items per page (default 20, max 100)
GET /news/categories
Category tree with article counts · scope news.read
GET /news/tags
Tags with article counts · scope news.read
q Search · limit Max (default 100)
GET /news/authors
Active authors · scope news.read
GET /news/authors/{id}
Author profile (id or slug) · scope news.read
GET /news/{id}
Full article (id or slug) with SEO, related entities and more stories · scope news.read
count_view Frontend keys only, legacy: count a page view (skips the cache - prefer POST /news/{id}/view)
POST /news/{id}/view
Frontend keys only: count one page view (max 1 per visitor IP / article / 30 min) · scope news.read

Rankings

ICC team and player rankings.

GET /rankings
ICC rankings (Top 10) grouped by format + type · scope rankings.read
format Format · type Ranking type · gender Default Men · limit Rows per group (1-10, default 10; larger values are capped)

Meta

Master data, search, health and public plan list.

GET /search
Search teams, players, series, venues, matches and news at once · scope search.read
q Required, 2-100 chars · types Groups to search · limit Per group (default 5, max 20)
GET /meta/match-types
Match types · scope meta.read
GET /meta/team-types
Team types · scope meta.read
GET /meta/leagues
Leagues · scope meta.read
GET /meta/countries
Countries used by teams / players / venues · scope meta.read
GET /meta/scopes
All API scopes
GET /plans
Public plan list (payment is offline - the admin activates plans)
GET /health
Service health
GET /openapi.json
OpenAPI 3 specification of this API

Realtime

WebSocket live updates.

GET /ws/token
Short-lived token to open the WebSocket (wss) connection · scope ws.connect