Events

GET /es/events/sim/catalogue

List of available simulations

Returns a list of games that are available for simulation.

String Parameters:

Field	Type	Required	Description
token	header	✅	authentication token provided from /auth route
source	query	❌	Data provider source (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
sport	query	❌	Sport type (Enum: SOCCER, BASKETBALL, BASEBALL, FOOTBALL)

Response:

200 OK

Schema

Field	Type	Required	Description
id	string	✅	Kero UUID of the event
sim_game_id	string	✅	ID of the game in the stats source
name	string	✅	Title of the event
source	string	✅	Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta
sport	string	✅	Enum: "SOCCER", "BASKETBALL", "BASEBALL", "FOOTBALL"
team_home_position	string	✅	Indicates if the home team is on the "LEFT" or "RIGHT"
short_name	string	✅	Short title of the event
event_image	string	❌	URL to the event image
league	League	✅	League object containing league metadata
started_at	integer	✅	Timestamp of the event’s start in UNIX seconds
team_a	Team	✅	Home team object
team_b	Team	✅	Away team object

League Object

Field	Type	Required	Description
id	integer	✅	Kero ID for the league
name	string	✅	Full name of the league (tournament)
source_league_id	string	✅	Primary league ID from the external data source (related to the provider in the source field)
location	string	✅	Country or region where the league is based
source_name	string	❌	Data provider source (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
sources	[]LeagueSource	❌	A list of league sources

League Source Object

Field	Type	Required	Description
id	integer	✅	Kero ID for the league source
source	string	✅	Data provider source (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
source_season_id	string	✅	Season ID from the external data source
source_league_id	string	✅	League ID from the external data source
source_league_name	string	✅	League name from the external data source

Team Object

Field	Type	Required	Description
id	integer	✅	Kero team ID
name	string	✅	Full name of the team
short_name	string	✅	abbreviated name of the team
common_name	string	✅	team name preferable for mapping
image	string	❌	Public URL of the team’s logo or image
source	TeamSource	❌	Primary source info (e.g., from betradar)
sources	[]TeamSource	✅	List of all source mappings for the team

Team Source Object

Field	Type	Required	Description
source	string	✅	Name of the data provider (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
source_team_id	string	✅	Team ID within the external data provider
source_team_name	string	❌	Team name within the external data provider

JSON

[
    {
        "id": "e0d4310d-9273-42dd-affc-a606fe3f3ca3",
        "name": "KANSAS CITY CHIEFS @ PHILADELPHIA EAGLES",
        "game_id": "11064151",
        "source": "genius",
        "sport": "FOOTBALL",
        "team_home_position": "RIGHT",
        "short_name": "CHIEFS @ EAGLES",
        "league": {
            "id": 7,
            "name": "NFL",
            "location": "USA",
            "sources": [
                {
                    "id": 26,
                    "source": "betradar",
                    "source_season_id": "sr:season:127985",
                    "source_league_id": "9956",
                    "source_league_name": "NFL"
                },
                {
                    "id": 23,
                    "source": "betradar",
                    "source_season_id": "sr:season:127985",
                    "source_league_id": "47",
                    "source_league_name": "NFL"
                },
                {
                    "id": 24,
                    "source": "sportradar",
                    "source_season_id": "sr:season:127985",
                    "source_league_id": "sr:tournament:31",
                    "source_league_name": "NFL"
                },
                {
                    "id": 25,
                    "source": "genius",
                    "source_season_id": "158559",
                    "source_league_id": "296",
                    "source_league_name": "NFL"
                }
            ],
            "source_league_id": "296",
            "source_name": "genius"
        },
        "team_a": {
            "id": 139,
            "name": "Kansas City Chiefs",
            "short_name": "KC",
            "common_name": "Chiefs",
            "image": "https://storage.googleapis.com/kero-cdn.rushsports.io/team_images/American Football/NFL/kc.png",
            "sources": [
                {
                    "id": 362,
                    "source": "betradar",
                    "source_team_id": "35266",
                    "source_team_name": ""
                },
                {
                    "id": 363,
                    "source": "sportradar",
                    "source_team_id": "sr:competitor:4422",
                    "source_team_name": ""
                },
                {
                    "id": 414,
                    "source": "genius",
                    "source_team_id": "86068",
                    "source_team_name": "Kansas City Chiefs"
                }
            ]
        },
        "team_b": {
            "id": 146,
            "name": "Philadelphia Eagles",
            "short_name": "PHI",
            "common_name": "Eagles",
            "image": "https://storage.googleapis.com/kero-cdn.rushsports.io/team_images/American Football/NFL/phi.png",
            "sources": [
                {
                    "id": 376,
                    "source": "betradar",
                    "source_team_id": "35261",
                    "source_team_name": ""
                },
                {
                    "id": 377,
                    "source": "sportradar",
                    "source_team_id": "sr:competitor:4428",
                    "source_team_name": ""
                },
                {
                    "id": 421,
                    "source": "genius",
                    "source_team_id": "89169",
                    "source_team_name": "Philadelphia Eagles"
                }
            ]
        }
    },
    {
        "id": "2c2b7728-f5b0-4399-a47f-4f13d1c18854",
        "name": "INTERNAZIONALE VS FIORENTINA 10.02.2025",
        "game_id": "byje5zx0wyviz3xqpyx5z70no",
        "source": "opta",
        "sport": "SOCCER",
        "team_home_position": "LEFT",
        "short_name": "INT V FIO",
        "league": {
            "id": 3,
            "name": "Serie A",
            "location": "Italy",
            "source_league_id": "1r097lpxe0xn03ihb7wi98kao",
            "source_name": "opta"
            "sources": [
                {
                    "id": 10,
                    "source": "betradar",
                    "source_season_id": "sr:season:118975",
                    "source_league_id": "33",
                    "source_league_name": "Serie A"
                },
                {
                    "id": 11,
                    "source": "sportradar",
                    "source_season_id": "sr:season:118975",
                    "source_league_id": "sr:tournament:23",
                    "source_league_name": "Serie A"
                },
                {
                    "id": 2,
                    "source": "opta",
                    "source_season_id": "b25u56idqlgo8s1rahhltqd5g",
                    "source_league_id": "1r097lpxe0xn03ihb7wi98kao",
                    "source_league_name": "Italian Serie A"
                }
            ],
        },
        "team_a": {
            "id": 52,
            "name": "Inter Milano",
            "short_name": "INT",
            "common_name": "Inter",
            "image": "https://storage.googleapis.com/kero-cdn.rushsports.io/team_images/3_Serie_A/Inter.png",
            "sources": [
                {
                    "id": 103,
                    "source": "betradar",
                    "source_team_id": "9264",
                    "source_team_name": ""
                },
                {
                    "id": 104,
                    "source": "sportradar",
                    "source_team_id": "sr:competitor:2697",
                    "source_team_name": ""
                },
                {
                    "id": 455,
                    "source": "opta",
                    "source_team_id": "3vo5mpj7catp66nrwwqiuhuup",
                    "source_team_name": "Internazionale"
                }
            ]
        },
        "team_b": {
            "id": 43,
            "name": "ACF Fiorentina",
            "short_name": "FIO",
            "common_name": "Fiorentina",
            "image": "https://storage.googleapis.com/kero-cdn.rushsports.io/team_images/3_Serie_A/Fiorentina.png",
            "sources": [
                {
                    "id": 85,
                    "source": "betradar",
                    "source_team_id": "9247",
                    "source_team_name": ""
                },
                {
                    "id": 86,
                    "source": "sportradar",
                    "source_team_id": "sr:competitor:2693",
                    "source_team_name": ""
                },
                {
                    "id": 457,
                    "source": "opta",
                    "source_team_id": "4raiad4l2j5lkfaz92pk4osb",
                    "source_team_name": "Fiorentina"
                }
            ]
        }
    }
]

Error

Schema

Field	Type	Required	Description
code	integer	❌	error integer code
status	string	✅	status of the response
msg	string	❌	some description of the error
data	object	❌	any additional data for the error response

JSON

{
    "code": 1,
    "status": "INVALID SOURCE HOST",
    "msg": "any message here",
    "data": "additional data for error response"
}

POST /es/events/sim

Simulate a game

Starts a simulation of up to 5 concurrent games.

Required String Parameters:

Field	Type	Description
token	header	authentication token provided from /auth route

Request Body:

Field	Type	Required	Default	Description
catalogue_id	string	✅	-	UUID of the catalogue item
starts_at	integer	❌	5 minutes from NOW	Timestamp in UNIX seconds (when the sim should start)

Response:

200 OK

Schema

Field	Type	Required	Description
id	string	✅	Kero UUID of the event
sim_game_id	string	✅	Simulated ID of the game in the stats source
name	string	✅	Full event name
source	string	✅	Data provider source (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
sport	string	✅	Sport type (Enum: SOCCER, BASKETBALL, BASEBALL, FOOTBALL)
team_home_position	string	✅	Side of the home team (LEFT or RIGHT)
short_name	string	✅	Short display version of the event name
league	League	✅	League info (see below)
started_at	integer	✅	Game start time as UNIX timestamp (seconds)
team_a	Team	✅	Home team data (see below)
team_b	Team	✅	Away team data (see below)

League Object

Field	Type	Required	Description
id	integer	✅	Kero ID for the league
name	string	✅	Full name of the league (tournament)
source_league_id	string	✅	Primary league ID from the external data source (related to the provider in the source field)
location	string	✅	Country or region where the league is based
source_name	string	❌	Data provider source (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
sources	[]LeagueSource	❌	A list of league sources

League Source Object

Field	Type	Required	Description
id	integer	✅	Kero ID for the league source
source	string	✅	Data provider source (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
source_season_id	string	✅	Season ID from the external data source
source_league_id	string	✅	League ID from the external data source
source_league_name	string	✅	League name from the external data source

Team Object

Field	Type	Required	Description
id	integer	✅	Kero team ID
name	string	✅	Full name of the team
short_name	string	✅	abbreviated name of the team
common_name	string	✅	team name preferable for mapping
image	string	❌	Public URL of the team’s logo or image
source	TeamSource	❌	Primary source info (e.g., from betradar)
sources	[]TeamSource	✅	List of all source mappings for the team

Team Source Object

Field	Type	Required	Description
source	string	✅	Name of the data provider (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
source_team_id	string	✅	Team ID within the external data provider
source_team_name	string	❌	Team name within the external data provider

JSON

{
    "id": "7e58fb90-e607-4f42-8797-f5b822b5c8ba",
    "sport": "BASEBALL",
    "source": "betradar",
    "team_home_position": "RIGHT",
    "team_a": {
        "id": 186,
        "name": "Los Angeles Dodgers",
        "short_name": "LAD",
        "common_name": "Dodgers",
        "image": "https://storage.googleapis.com/kero-cdn.rushsports.io/team_images/Baseball/MLB/lad.png",
        "sources": [
            {
                "id": 85,
                "source": "betradar",
                "source_team_id": "24450"
            },
            {
                "id": 85,
                "source": "sportradar",
                "source_team_id": "sr:competitor:3638"
            }
        ]
    },
    "team_b": {
        "id": 174,
        "name": "Chicago Cubs",
        "short_name": "CHC",
        "common_name": "Cubs",
        "image": "https://storage.googleapis.com/kero-cdn.rushsports.io/team_images/Baseball/MLB/chc.png",
        "sources": [
            {
                "id": 86,
                "source": "betradar",
                "source_team_id": "24419"
            },
            {
                "id": 86,
                "source": "betradar",
                "source_team_id": "sr:competitor:3627"
            }
        ]
    },
    "started_at": 1746625608,
    "league": {
        "name": "MLB",
        "source_league_id": "25"
        "location": "USA",
        "source_name": "opta",
        "sources": [
            {
                "id": 10,
                "source": "betradar",
                "source_season_id": "sr:season:118975",
                "source_league_id": "25",
                "source_league_name": "MLB"
            }
        ]
    },
    "name": "REPLY LOS ANGELES DODGERS @ CHICAGO CUBS",
    "short_name": "RPL LAD @ CHC",
    "sim_game_id": "rpl_55308649_8"
}

Error

Schema

Field	Type	Required	Description
code	integer	❌	error integer code
status	string	✅	status of the response
msg	string	❌	some description of the error
data	object	❌	any additional data for the error response

JSON

{
    "code": 1,
    "status": "INVALID SOURCE HOST",
    "msg": "any message here",
    "data": "additional data for error response"
}

POST /es/events/sim/:sim_game_id/stop

Stop game simulation

Stops the provided sim if present.

Required String Parameters:

Field	Type	Description
token	header	authentication token provided from /auth route
path	sim_game_id	sim_game_id field value of the simulated game to stop

Response:

204 NO CONTENT

Empty response

Error

Schema

Field	Type	Required	Description
code	integer	❌	error integer code
status	string	✅	status of the response
msg	string	❌	some description of the error
data	object	❌	any additional data for the error response

JSON

{
    "code": 1,
    "status": "INVALID SOURCE HOST",
    "msg": "any message here",
    "data": "additional data for error response"
}

POST /es/events/:game_id/:source/subscribe

Subscribe to a specific game

Subscribes your account to a specific game in the provided source.

Required String Parameters:

Field	Type	Description
token	header	Authentication token provided from /auth route
game_id	path	ID of the game in the provided stats source
source	path	Stats source name (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)

Response:

200 OK

Empty response

Error

Schema

Field	Type	Required	Description
code	integer	❌	error integer code
status	string	✅	status of the response
msg	string	❌	some description of the error
data	object	❌	any additional data for the error response

JSON

{
    "code": 1,
    "status": "INVALID SOURCE HOST",
    "msg": "any message here",
    "data": "additional data for error response"
}

POST /es/events/:game_id/:source/unsubscribe

Unsubscribe from a specific game

Unsubscribes your account to a specific game in the provided source.

Required String Parameters:

Field	Type	Description
token	header	Authentication token provided from /auth route
game_id	path	ID of the game in the provided stats source
source	path	Stats source name (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)

Response:

200 OK

Empty response

Error

Schema

Field	Type	Required	Description
code	integer	❌	error integer code
status	string	✅	status of the response
msg	string	❌	some description of the error
data	object	❌	any additional data for the error response

JSON

{
    "code": 1,
    "status": "INVALID SOURCE HOST",
    "msg": "any message here",
    "data": "additional data for error response"
}

GET /es/events

List all available events

Returns a page of events that you are allowed to subscribe to (or defined by the passed parameters).

Parameters:

Field	Type	Data Type	Required	Description
token	header	string	✅	authentication token provided from /auth route
sport	query	string	❌	Sport type (Enum: SOCCER, BASKETBALL, BASEBALL, FOOTBALL)
live	query	boolean	❌	when true only returns events which are already started and not finished yet
ended	query	boolean	❌	when true only returns events which are already finished
search	query	string	❌	filter for events by team names
page	query	integer	✅	number of page (starts from 1)
size	query	integer	✅	size of page
available	query	boolean	❌	when true shows games available for subscription (which are not already subscribed)

Response:

200 OK

Schema

Field	Type	Required	Description
page	integer	✅	page number passed in the request
size	integer	✅	page size passed in the request
last_page	boolean	✅	true if the current page is the last page
content	[]Event	✅	array of events

Event Object

Field	Type	Required	Description
id	string	✅	Unique identifier of the event (Kero UUID)
name	string	✅	Full event name
short_name	string	✅	Short display version of the event name
game_id	string	✅	Game ID from the source system
sport	string	✅	Sport type (Enum: SOCCER, BASKETBALL, BASEBALL, FOOTBALL)
source	string	✅	Data provider source (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
team_home_position	string	✅	Side of the home team (LEFT or RIGHT)
team_a	Team	✅	Home team data (see below)
team_b	Team	✅	Away team data (see below)
started_at	integer	✅	Game start time as UNIX timestamp (seconds)
league	League	✅	League info (see below)
alternate_game_ids	object	❌	Map of provider-specific game IDs (key = provider name (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta), value = provider id)

League Object

Field	Type	Required	Description
id	integer	✅	Kero ID for the league
name	string	✅	Full name of the league (tournament)
source_league_id	string	✅	Primary league ID from the external data source (related to the provider in the source field)
location	string	✅	Country or region where the league is based
source_name	string	❌	Data provider source (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
sources	[]LeagueSource	❌	A list of league sources

League Source Object

Field	Type	Required	Description
id	integer	✅	Kero ID for the league source
source	string	✅	Data provider source (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
source_season_id	string	✅	Season ID from the external data source
source_league_id	string	✅	League ID from the external data source
source_league_name	string	✅	League name from the external data source

Team Object

Field	Type	Required	Description
id	integer	✅	Kero team ID
name	string	✅	Full name of the team
short_name	string	✅	abbreviated name of the team
common_name	string	✅	team name preferable for mapping
image	string	❌	Public URL of the team’s logo or image
source	TeamSource	❌	Primary source info (e.g., from betradar)
sources	[]TeamSource	✅	List of all source mappings for the team

Team Source Object

Field	Type	Required	Description
source	string	✅	Name of the data provider (Enum: betradar, sportradar, nba_cdn, genius, statsapi_nhl, opta)
source_team_id	string	✅	Team ID within the external data provider
source_team_name	string	❌	Team name within the external data provider

JSON

{
    "page": 1,
    "size": 1,
    "last_page": false,
    "content": [
        {
            "id": "a2cc09b0-89a0-4084-9f51-b597b205bfca",
            "name": "HATAYSPOR VS FENERBAHÇE 26.05.2025",
            "short_name": "HAT V FB",
            "game_id": "28lozs8y9gicrbumgx9lgpwr8",
            "sport": "SOCCER",
            "source": "opta",
            "team_home_position": "LEFT",
            "team_a": {
                "id": 971,
                "name": "Hatayspor Antakya",
                "short_name": "HAT",
                "common_name": "Hatayspor Antakya",
                "image": "https://storage.googleapis.com/kero-cdn.rushsports.io/team_images/35_Super_Lig/Hatayspor.png",
                "source": {
                    "source": "opta",
                    "source_team_id": "efy1nhpn5l6hc27znhsptegba",
                    "source_team_name": "Hatayspor"
                },
                "sources": [
                    {
                        "source": "betradar",
                        "source_team_id": "14287013"
                    },
                    {
                        "source": "sportradar",
                        "source_team_id": "sr:competitor:3091"
                    },
                    {
                        "source": "opta",
                        "source_team_id": "efy1nhpn5l6hc27znhsptegba",
                        "source_team_name": "Hatayspor"
                    }
                ]
            },
            "team_b": {
                "id": 213,
                "name": "Fenerbahce Istanbul",
                "short_name": "FEN",
                "common_name": "Fenerbahce Istanbul",
                "image": "https://storage.googleapis.com/kero-cdn.rushsports.io/team_images/9_UEFA_Champions_League/Fenerbahce.png",
                "source": {
                    "source": "opta",
                    "source_team_id": "8lroq0cbhdxj8124qtxwrhvmm",
                    "source_team_name": "Fenerbahçe"
                },
                "sources": [
                    {
                        "source": "betradar",
                        "source_team_id": "5930"
                    },
                    {
                        "source": "sportradar",
                        "source_team_id": "sr:competitor:3052"
                    },
                    {
                        "source": "opta",
                        "source_team_id": "8lroq0cbhdxj8124qtxwrhvmm",
                        "source_team_name": "Fenerbahçe"
                    }
                ]
            },
            "started_at": 1748278800,
            "league": {
                "id": 35,
                "name": "Super Lig",
                "source_league_id": "482ofyysbdbeoxauk19yg7tdt",
                "location": "Turkiye"
            },
            "alternate_game_ids": {
                "betradar": "51472457",
                "opta": "28lozs8y9gicrbumgx9lgpwr8"
            }
        }
    ]
}

Error

Schema

Field	Type	Required	Description
code	integer	❌	error integer code
status	string	✅	status of the response
msg	string	❌	some description of the error
data	object	❌	any additional data for the error response

JSON

{
    "code": 1,
    "status": "INVALID SOURCE HOST",
    "msg": "any message here",
    "data": "additional data for error response"
}