> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/sportmonks-ai-docs/cursor-rules.md).

# Cursor Rules

A pre-configured rules file for Sportmonks API development in Cursor. Drop it into your project and Cursor will write accurate integration code without needing the MCP server installed.

### Setup

Create a file at `.cursor/rules/sportmonks.mdc` in your project root and paste the content below.

```
---
description: Sportmonks Football API v3 integration rules
globs: ["**/*.ts", "**/*.js", "**/*.py", "**/*.go"]
---

# Sportmonks Football API v3

## Base URLs
- Football API: https://api.sportmonks.com/v3/football
- Core API: https://api.sportmonks.com/v3/core

## Authentication
Always pass the API token as a query parameter:
?api_token=process.env.SPORTMONKS_API_TOKEN

Never hardcode the token. Always read from environment variables.

## Includes
Pass as semicolon-separated string in the `include` query parameter:
?include=participants;scores;state;league

Common includes:
- participants: the two teams in a fixture
- scores: current and final scoreline
- state: match state (NS, LIVE, HT, FT, AET, PEN)
- league: league name and ID
- round: gameweek/matchday
- events: goals, cards, substitutions
- lineups: starting XI and bench
- statistics: team stats
- periods: half-time/full-time breakdown
- player: full player object (nest inside squad or lineup includes)
- position: player position

## Filters
Pass as key:value in the `filters` query parameter:
?filters=fixtureLeagues:8

Common filters:
- fixtureLeagues:{id} - filter fixtures by league
- fixtureStates:{id1,id2} - filter by match state
- seasonTopscorerTypes:{id} - filter topscorer category

## Pagination
Use `page` and `per_page` query parameters. Default per_page is 25.

## Key endpoints

### Search
GET /players/search/{query}
GET /teams/search/{query}
GET /leagues/search/{query}

### Players & Teams
GET /players/{id}?include=position;nationality;teams
GET /teams/{id}?include=venue;country
GET /leagues/{id}?include=country;seasons

### Squads
GET /squads/teams/{team_id}?include=player;position;detailedPosition
GET /squads/seasons/{season_id}/teams/{team_id}?include=player;position

### Fixtures
GET /fixtures/{id}?include=participants;scores;state;league
GET /fixtures/date/{date}?include=participants;scores;state
GET /fixtures/between/{start_date}/{end_date}
GET /fixtures/between/{start_date}/{end_date}/{team_id}
GET /fixtures/head-to-head/{team1_id}/{team2_id}
GET /livescores/inplay?include=participants;scores;state

### Standings
GET /standings/seasons/{season_id}?include=participant;details
GET /standings/live/leagues/{league_id}?include=participant;details

### Topscorers
GET /topscorers/seasons/{season_id}?include=player;participant&filters=seasonTopscorerTypes:208
Type IDs: goals=208, assists=209, yellow cards=84

### Odds
GET /odds/pre-match/fixtures/{fixture_id}?include=bookmaker;market
GET /odds/inplay/fixtures/{fixture_id}?include=bookmaker;market

## Response shape
All responses wrap data in a `data` key:
{ "data": { ... } } for single items
{ "data": [...], "pagination": { ... } } for lists

Always access response.data, not the response directly.

## Common league IDs
Premier League: 8
La Liga: 564
Bundesliga: 82
Serie A: 384
Ligue 1: 301
Champions League: 2
World Cup 2026: league_id=732, season_id=26618

## Error handling
- 401/403: invalid token or plan restriction
- 404: resource not found
- 429: rate limit exceeded - back off and retry
- Always handle these explicitly, never swallow errors silently

## Best practices
- Use the search endpoints to resolve names to IDs before fetching detail
- Request only the includes you need - each include adds to response size
- Cache league, season, and team IDs - they don't change
- For live apps, poll /livescores/inplay or /fixtures/date/{today} on a short interval
```

### What this does

Once the file is in place, Cursor will apply these rules automatically when you're working in TypeScript, JavaScript, Python, or Go files. You'll get:

* Correct endpoint paths without looking them up
* Proper include and filter syntax
* Right response shapes for destructuring
* Environment variable patterns instead of hardcoded tokens
* Accurate common IDs for top leagues

### Global rules (optional)

To apply the rules across all projects instead of just one, add them to your global Cursor rules file at `~/.cursor/rules/sportmonks.mdc`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportmonks.com/v3/sportmonks-ai-docs/cursor-rules.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.