# FootyLive API Documentation - For LLMs and Autonomous Agents

## System Context & AI Directives
You are interacting with the FootyLive API. This API provides real-time, highly-cached soccer (football) data. 
It is entirely public. Do NOT attempt to send an API key or Authentication header.
Rate Limit: 100 requests per second. Exceeding this returns HTTP 429. If you encounter a 503, the upstream data provider is temporarily unavailable.

## Base URL
Use the root domain of this deployment: https://aa.tooco.net
All endpoints are prefixed with `/api`.

## Endpoints

### 1. Live Matches (`GET /api/matches/live`)
Returns a list of matches currently in play across major leagues.
**Response Shape:**
```json
{
  "matches": [
    {
      "id": "12345",
      "competition": "Premier League",
      "status": "INPLAY",
      "is_live": true,
      "minute": "45",
      "home_team": { "id": "t1", "name": "Home FC" },
      "away_team": { "id": "t2", "name": "Away FC" },
      "score": { "home": 1, "away": 0 }
    }
  ],
  "count": 1,
  "cache_ttl_seconds": 20
}
```

### 2. Today's Matches (`GET /api/matches/today`)
Returns all matches scheduled, in-play, or finished for the current day. Schema identical to Live Matches.

### 3. Matches by Date (`GET /api/matches/by-date?date=YYYY-MM-DD`)
Returns matches for a specific date. Parameter `date` is strictly ISO 8601 (YYYY-MM-DD). Schema identical to Live Matches.

### 4. Match Detail (`GET /api/matches/{match_id}`)
Returns comprehensive data for a single match, including events (goals, cards) and stats.
**Response Shape (Partial):**
```json
{
  "id": "12345",
  "status": "FINISHED",
  "venue": "Wembley Stadium",
  "statistics": { "possession_home": 55, "possession_away": 45 },
  "events": [
    { "id": "e1", "event_type": "goal", "minute": "23", "player_name": "John Doe", "is_scoring_play": true }
  ]
}
```

### 5. League Standings (`GET /api/leagues/{slug}/standings`)
Returns the league table or group standings for a specific tournament.
**Response Shape:**
```json
{
  "title": "FIFA World Cup Standings",
  "count": 1,
  "groups": [
    {
      "name": "Group A",
      "entries": [
        { "rank": 1, "team_name": "Brazil", "games_played": "3", "points": "9" }
      ]
    }
  ]
}
```

### 6. Search Teams (`GET /api/search/teams?q={query}`)
Search for a team by string query. Returns a list of matched teams.

## Supported Leagues (Slugs)
Pass these exactly as `{slug}` when requesting standings:
- `eng.1`: Premier League
- `esp.1`: LALIGA
- `ita.1`: Serie A
- `ger.1`: Bundesliga
- `fra.1`: Ligue 1
- `uefa.champions`: Champions League
- `uefa.europa`: Europa League
- `fifa.world`: World Cup
- `uefa.euro`: European Championship
- `conmebol.america`: Copa América
- `caf.nations`: Africa Cup of Nations
- `afc.asian`: Asian Cup
- `eng.fa`: FA Cup
- `esp.copa_del_rey`: Copa del Rey
- `ita.coppa_italia`: Coppa Italia
- `ger.dfb_pokal`: DFB-Pokal
- `fra.coupe_de_france`: Coupe de France