Github Copilot

Add a workspace instructions file to your project and Copilot will write accurate Sportmonks integration code - correct endpoints, proper auth patterns, right response shapes - without you needing to explain the API every time.

How it works

GitHub Copilot reads .github/copilot-instructions.md in your repository and uses it as persistent context for all Copilot suggestions in that workspace. Add Sportmonks API knowledge there and Copilot will apply it automatically.

Setup

1. Create the instructions file

In your project root, create .github/copilot-instructions.md and paste the following:

# Sportmonks Football API v3

## Base URL
https://api.sportmonks.com/v3/football

## Authentication
Always use the `api_token` query parameter. Read from environment variables:
- Node.js: `process.env.SPORTMONKS_API_TOKEN`
- Python: `os.environ["SPORTMONKS_API_TOKEN"]`
- Go: `os.Getenv("SPORTMONKS_API_TOKEN")`

Never hardcode the token.

## Key endpoints
- Search players: GET /players/search/{query}
- Search teams: GET /teams/search/{query}
- Search leagues: GET /leagues/search/{query}
- Player profile: GET /players/{id}?include=position;nationality;teams
- Team profile: GET /teams/{id}?include=venue;country
- Current squad: GET /squads/teams/{team_id}?include=player;position;detailedPosition
- Fixtures by date: GET /fixtures/date/{YYYY-MM-DD}?include=participants;scores;state
- Fixture detail: GET /fixtures/{id}?include=participants;scores;state;events;lineups;statistics
- Head to head: GET /fixtures/head-to-head/{team1_id}/{team2_id}?per_page=5&order=desc
- Live scores: GET /livescores/inplay?include=participants;scores;state
- Standings: GET /standings/live/leagues/{league_id}?include=participant;details
- Topscorers: GET /topscorers/seasons/{season_id}?include=player;participant&filters=seasonTopscorerTypes:208

## Includes
Semicolon-separated string: ?include=participants;scores;state;league

## Filters
Key:value syntax: ?filters=fixtureLeagues:8

## Response shape
All responses: { "data": ... }
Lists: { "data": [...], "pagination": { "has_more": bool, "current_page": int } }
Always access `.data`, not the root response.

## Common IDs
Premier League: 8 | La Liga: 564 | Bundesliga: 82 | Serie A: 384
Champions League: 2 | World Cup 2026: league_id=732, season_id=26618
Topscorer types: goals=208, assists=209, yellow cards=84

## Error handling
401/403 - invalid token or subscription restriction
404 - resource not found
429 - rate limit, back off and retry with exponential backoff

2. Commit the file

git add .github/copilot-instructions.md
git commit -m "Add Sportmonks API context for Copilot"

3. Reload VS Code

Open the Command Palette → Developer: Reload Window. Copilot will pick up the new instructions.

What changes

Before the instructions file, Copilot might generate:

// Incorrect - wrong auth method and made-up endpoint
const res = await fetch('https://api.sportmonks.com/fixtures', {
  headers: { Authorization: `Bearer ${token}` }
});

After the instructions file:

// Correct - proper endpoint and auth pattern
const res = await fetch(
  `https://api.sportmonks.com/v3/football/fixtures/date/${date}?include=participants;scores;state&api_token=${process.env.SPORTMONKS_API_TOKEN}`
);

Copilot Chat

You can also ask Copilot Chat directly and it will use the instructions as context:

@workspace Build a function that fetches live scores and returns an array of { home, away, score, state }

@workspace Write a TypeScript client for the Sportmonks standings endpoint with proper error handling