# SportFeeds API — Full Reference

Base URL: https://api.sportfeeds.com/v1
Auth: `Authorization: Bearer <YOUR_API_KEY>` on every request.
Get a key at https://sportfeeds.com/dashboard.

## The only endpoint you need: GET /posts

SportFeeds exposes a single retrieval endpoint. The mode is inferred from
your query parameters — there is no per-mode path. The legacy split routes
(/posts/leagues, /posts/teams, /posts/players, /posts/games, /posts/nearby,
/posts/trending) are deprecated and return HTTP 410 for new accounts. Do not
call them.

### Modes (inferred from params)

| Mode      | Trigger params                                       |
|-----------|------------------------------------------------------|
| trending  | (no filters), or `sort=trending`                    |
| leagues   | `leagues=NFL,NBA`                                   |
| teams     | `teams=<ids>` (+ `id_type`)                        |
| players   | `players=<ids>` (+ `id_type`)                      |
| games     | `match=<teamA>,<teamB>` + `start_time=<iso>`       |
| nearby    | `lat=<n>` + `lng=<n>` (+ optional `radius_km`)    |

### Common query parameters

- `leagues`            — Comma-separated league codes: NFL, NCAAFB, NBA, WNBA, NCAAMB, MLB, NHL, PGA, GOLF, EPL, MLS, FIFA, SOCCER, CRICKET, RUGBY, MMA (or ALL). Case-insensitive.
- `sports`             — Comma-separated parent sports: americanfootball, football, basketball, baseball, hockey, golf, cricket, rugby, mma. Case-insensitive.
                          `football` = association football (soccer); the NFL/NCAA game is `americanfootball`. `soccer` is accepted as an alias for `football`.
- `teams`              — Comma-separated team IDs. Triggers team mode.
- `players`            — Comma-separated player IDs. Triggers player mode.
- `sources`            — Comma-separated X.com handles or numeric X.com account IDs (max 500).
- `id_type`            — One of: `code`, `espn_uid`, `espn_guid`, `sportfeeds`,
                          `sportsstack`. Required when `teams=` or `players=` is set.
- `match`              — Two team IDs (teamA,teamB) for a game. Requires `start_time`.
- `start_time`         — ISO 8601 timestamp of game kickoff. Required with `match`.
- `include_pregame`    — `true` to include pregame posts.
- `lat`, `lng`         — Decimal degrees. Triggers nearby mode.
- `radius_km`          — Defaults to 50.
- `media_type`         — `image` or `video`.
- `aspect_ratio`       — `landscape`, `portrait`, or `square`.
- `highlight`          — `true` for highlight posts only.
- `has_player`         — `true` to require at least one tagged player.
- `custom_sources`     — `true` to include posts from your custom sources.
- `min_score`          — Numeric quality threshold.
- `sort`               — `recent` (default), `trending`, or `top`.
- `since`              — ISO timestamp. Returns only posts created after it. Use for polling.
- `since_id`           — Returns only posts with id greater than this.
- `limit`              — Default 20, max 100.
- `page`               — Default 1.

### cURL examples

```bash
# Trending
curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/posts"

# By league
curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/posts?leagues=NFL&limit=20"

# By team (ESPN GUID)
curl -H "Authorization: Bearer $KEY" \
  "https://api.sportfeeds.com/v1/posts?id_type=espn_guid&teams=1f6592b3-ff53-d321-8dc5-6038d48c1786"

# By player (ESPN GUID)
curl -H "Authorization: Bearer $KEY" \
  "https://api.sportfeeds.com/v1/posts?id_type=espn_guid&players=b4376163-318a-7510-fe79-bbb7ee9acf0d"

# By game
curl -H "Authorization: Bearer $KEY" \
  "https://api.sportfeeds.com/v1/posts?id_type=espn_guid&match=teamA,teamB&start_time=2024-01-15T20:00:00Z"

# Nearby geo
curl -H "Authorization: Bearer $KEY" \
  "https://api.sportfeeds.com/v1/posts?lat=40.7128&lng=-74.0060&radius_km=50"

# Polling with watermark
curl -H "Authorization: Bearer $KEY" \
  "https://api.sportfeeds.com/v1/posts?leagues=NFL&since=2024-01-15T20:00:00Z"
```

### Response shape

```json
{
  "pagination": { "page": 1, "limit": 20, "has_next": true, "has_prev": false },
  "items": [
    {
      "id": "1750000000000000000",
      "text": "…",
      "author_username": "espn",
      "author_id": "2557521",
      "league": "NFL",
      "post_url": "https://x.com/espn/status/…",
      "created_at": "2024-01-15T20:00:00Z",
      "like_count": 1234, "retweet_count": 567, "reply_count": 89, "quote_count": 12,
      "media_type": "image",
      "highlight": false,
      "teams": [ /* … */ ],
      "players": [ /* … */ ],
      "media": [ /* … */ ]
    }
  ]
}
```

### Errors

| Status | error_code              | When                                  |
|--------|-------------------------|---------------------------------------|
| 401    | UNAUTHORIZED            | Missing/invalid/revoked API key       |
| 402    | SUBSCRIPTION_REQUIRED   | No active subscription                |
| 410    | ENDPOINT_DEPRECATED     | You hit a split /posts/{mode} route   |
| 429    | QUOTA_EXCEEDED          | Monthly call cap reached              |
| 400    | INVALID_PARAMETER       | Bad/missing required parameter        |

### Polling pattern

Use `since=<iso>` set to the `created_at` of the newest post you previously
received. Poll on your own cadence — the response is cached for 60s.

## Links

- Docs:       https://sportfeeds.com/docs
- OpenAPI:    https://sportfeeds.com/openapi.json
- Dashboard:  https://sportfeeds.com/dashboard