---
description: Sportmicro multi-sport API integration rules
globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.py", "**/*.go", "**/*.php", "**/*.rb", "**/*.cs"]
---

# Sportmicro API Rules

## API scope
- Sportmicro publishes separate APIs per sport. Pick the correct base URL for the integration, for example:
  - https://football.sportmicro.com
  - https://basketball.sportmicro.com
  - https://tennis.sportmicro.com
  - https://baseball.sportmicro.com
- For docs, use https://docs.sportmicro.com/docs/{sport}/sportmicro
- For schemas, use https://docs.sportmicro.com/openapi/{sport}.json

## Authentication
- Send the API key in the Authorization header:
  - Authorization: Bearer {API-KEY}
- Never hardcode the token.
- Read the token from environment variables such as:
  - process.env.SPORTMICRO_API_KEY
  - os.getenv("SPORTMICRO_API_KEY")
  - getenv("SPORTMICRO_API_KEY")
- For WebSockets and SSE-style live endpoints, pass the token in the query string:
  - ?token={API-KEY}

## Query conventions
- Sportmicro endpoints commonly use PostgREST-style filters:
  - id=eq.142
  - season_id=eq.2405
  - league_id=eq.1052
  - type=eq.total
  - start_time=gte.2026-06-11
  - start_time=lt.2026-06-12
- Use or=(...) for OR conditions:
  - or=(home_team_id.eq.4143,away_team_id.eq.4143)
- Use offset and limit for pagination.
- Default and maximum limit is commonly 50.
- Use lang=en when translated fields are needed.

## Response handling
- Do not assume Sportmonks-style wrappers such as { "data": ... }.
- Many Sportmicro list endpoints return a top-level JSON array.
- Single-resource lookups are often the same endpoint filtered by id=eq.{id}.
- Nested fields such as scores, status, round, competitors, or time details may be embedded JSON objects.
- In Axios, response.data is the HTTP client payload, but the API payload itself is often already an array or object.

## Common endpoint families
- Discovery: /classes, /countries, /leagues, /tournaments, /seasons, /rounds, /teams, /players, /coaches, /referees, /arenas
- Matches: /matches, /matches-by-date, /matches-live, /matches-lineups, /matches-statistics, /matches-incidents, /matches-highlights, /matches-graphs, /matches-weather, /matches-tv-channels
- Competition data: /standings, /coverage, /coverage-live, /cup-bracket
- Media and enrichment: /news-matches, /agg-news-matches, /media-teams, /media-players, /media-leagues
- Odds on supported sports: /moneyline, /spread, /totals, /asian-handicaps, /correct-score, /double-chance, /draw-no-bet, /odd-even and related markets

## Realtime
- WebSocket pattern:
  - wss://{sport}.sportmicro.com/live/{type}?token={API-KEY}
- Event-specific WebSocket pattern:
  - wss://{sport}.sportmicro.com/live/{type}/{event_id}?token={API-KEY}
- SSE pattern:
  - https://{sport}.sportmicro.com/live/{type}?token={API-KEY}
- Common live types include:
  - score
  - time
  - graph
  - incident
  - statistics
  - innings
  - point-by-points
  - live-count

## Examples
- Get matches:
  - GET https://football.sportmicro.com/matches
- Get a single match:
  - GET https://football.sportmicro.com/matches?id=eq.142
- Get matches in a date window:
  - GET https://football.sportmicro.com/matches?start_time=gte.2026-06-11&start_time=lt.2026-06-12
- Get standings for a season:
  - GET https://basketball.sportmicro.com/standings?league_id=eq.1748&season_id=eq.4176&type=eq.total
- Get teams by league:
  - GET https://football.sportmicro.com/teams-by-league?league_id=eq.1052

## Error handling
- Handle 401 and 403 as auth or plan-access failures.
- Handle 404 as missing route or unsupported resource.
- Handle 429 with retry and backoff.
- Handle empty arrays as valid no-result responses.

## Best practices
- Use leagues, tournaments, seasons, and teams endpoints to resolve IDs before building deeper queries.
- Cache stable lookup data such as league, season, team, and tournament IDs.
- Respect the update period and recommended call frequency documented on endpoint pages.
- Use the sport-specific OpenAPI file when generating types or validating schemas.
- If you are unsure whether an endpoint exists for a sport, check:
  - https://docs.sportmicro.com/ai/sportmicro-endpoint-summary.txt
  - https://docs.sportmicro.com/ai/sportmicro-all-endpoints.txt
  - https://docs.sportmicro.com/openapi/{sport}.json