> 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/llm-tools/github-copilot.md).

# 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:

```markdown
# 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**

```bash
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:

```typescript
// 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:

```typescript
// 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
```


---

# 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/llm-tools/github-copilot.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.