# SportFeeds — Agent Integration Guide You are integrating **SportFeeds**, a B2B API that returns real-time, verified sports posts from X (Twitter), enriched with league, sport, team, player, game, media, engagement-rating and news-classification metadata. This document is written to be dropped directly into an AI coding agent's context (Claude Code, Cursor, Codex, Copilot, a custom GPT, or your own tool-calling loop). Everything an agent needs to make a correct first call — and never make an invalid one — is below. - Base URL: `https://api.sportfeeds.com/v1` - Docs (human): https://sportfeeds.com/docs - OpenAPI: https://sportfeeds.com/openapi.json - Short index: https://sportfeeds.com/llms.txt - Full text reference: https://sportfeeds.com/llms-full.txt - Get an API key: https://sportfeeds.com/dashboard --- ## 0. 60-second quick start ```bash export SPORTFEEDS_KEY="sf_live_..." # from https://sportfeeds.com/dashboard # Newest NFL posts curl -s -H "Authorization: Bearer $SPORTFEEDS_KEY" "https://api.sportfeeds.com/v1/posts?leagues=NFL&limit=10" | jq # Top-rated video highlights across all of soccer, last hour curl -s -H "Authorization: Bearer $SPORTFEEDS_KEY" "https://api.sportfeeds.com/v1/posts?sports=football&media_type=video&min_score=8&limit=20" | jq ``` If that returns `{"pagination":…,"items":[…]}` you are done wiring. Everything else in this document is refinement. --- ## 1. Authentication Every request needs an `Authorization` header. Both forms are accepted: ```http Authorization: Bearer sf_live_xxxxxxxxxxxxxxxx Authorization: sf_live_xxxxxxxxxxxxxxxx ``` Rules for agents: - **Never** put the key in a query string, a URL, a log line, or client-side code. Read it from an environment variable (`SPORTFEEDS_API_KEY`) on the server. - One key per environment. Rotate from the dashboard; old keys 401 immediately. - There is no OAuth, no refresh token, no session. The key is the whole auth story. ### Key delivery modes Each key is fixed to one delivery mode when it is created, so one account can run a Direct key and a Sync key side by side. | Mode | Who | Behaviour | |---|---|---| | `direct` | Any plan | Live, per-end-user requests. No cadence gate. `limit` max 100. | | `sync` | Paid plans only; the Sync terms are accepted when the key is created | Scheduled pulls into your own store. Paced to your plan's sync interval — an early poll returns `429 SYNC_INTERVAL_NOT_ELAPSED`. `limit` max 1000. Can request `include_geo`. | | `grandfathered` | Every key created before delivery modes shipped | Flexible. Behaviour is unchanged and still follows your account's original delivery setting. Nothing to migrate. | Pick the mode when you create the key in the dashboard. The mode cannot be changed afterwards — create a second key instead. --- ## 2. The mental model SportFeeds has **one retrieval endpoint** and **two support endpoints**. | Endpoint | Purpose | |---|---| | `GET /posts` | Every content query. Mode is inferred from the parameters you pass. | | `GET /ids` | Resolve/translate team, player, league and post IDs between providers. | | `GET /account/*` | Your plan, usage, custom sources, and X account IDs. | > **Do not call** `/posts/leagues`, `/posts/teams`, `/posts/players`, `/posts/games`, `/posts/nearby`, `/posts/trending`. > These legacy split routes are **deprecated**. They are still served for existing > integrations, but new integrations must not use them. Always use `GET /posts` with query params. ### Modes of `GET /posts` The mode is chosen for you by which parameters are present: | Mode | Trigger | |---|---| | trending | no filters, or `sort=trending` | | league / sport | `leagues=` and/or `sports=` | | teams | `teams=` (+ `id_type=`) | | players | `players=` (+ `id_type=`) | | sources | `sources=` | | game | `match=,` + `start_time=` | | nearby | `lat=` + `lng=` (+ `radius_km=`) | Modes compose. `leagues=NFL&media_type=video&min_score=8` is a perfectly valid single request — you do not need to fan out. --- ## 3. `GET /posts` — full parameter reference All parameters are optional. All values are **case-insensitive**. All list parameters are **comma-separated** and **plural**. ### Content selectors | Param | Type | Notes | |---|---|---| | `leagues` | CSV | League codes (see §4). `ALL` is accepted. | | `sports` | CSV | Parent sports (see §4). Returns every league under them. | | `teams` | CSV | Up to 10 team IDs. Requires `id_type` unless using `sportfeeds` IDs. Unmatched IDs return an empty list (HTTP 200). | | `players` | CSV | Up to 100 player IDs. Requires `id_type`. Unmatched IDs return an empty list (HTTP 200). | | `sources` | CSV | Up to 500 X handles (no @) or numeric X account IDs. | | `id_type` | string | ID system used by `teams`/`players`. See §5. | | `match` | string | `teamA,teamB` — must be paired with `start_time`. | | `start_time` | ISO 8601 | Kickoff/tipoff time of the game. | | `include_pregame` | bool | Include pregame chatter for a `match` query. | | `lat`, `lng` | float | Decimal degrees; triggers geo mode. | | `radius_km` | int | Default 145, max 4830. | ### Content filters | Param | Type | Notes | |---|---|---| | `media_type` | string | `video`, `photo`, `gif`, `animated_gif`, `none` | | `aspect_ratio` | string | `landscape`, `portrait`, `square` | | `min_duration` | int (ms) | Minimum video duration. | | `highlight` | bool | Only highlight clips. | | `has_player` | bool | Only posts with ≥1 tagged player. | | `min_score` | int 0–10 | Engagement rating floor. See §6. | | `custom_sources` | bool | Include your private custom sources (paid plans, within your source allowance). | | `user_location` | ISO-3166-1 alpha-2 | Only content whose source is cleared for that region. See §8. | ### News classification (opt-in) | Param | Type | Notes | |---|---|---| | `category` | string | `news`, `highlight`, `other` | | `news_type` | CSV | `injury, trade, signing, cut, suspension, contract_extension, roster_move, return_from_injury, retirement, coaching_change, draft, other` | | `news_status` | string | `verified` or `rumor` | | `news_origin` | string | `breaking` (first to report) or `relaying` | | `include_news` | bool | Adds the news fields to every item. Auto-on when any news filter is used. | ### Ordering & pagination | Param | Type | Notes | |---|---|---| | `sort` | string | `recent` (default), `top`, `trending` | | `since` | ISO 8601 | Posts published after this time. **Use this for polling.** | | `since_id` | string | Posts with an id greater than this. | | `limit` | int | Default 20. Max 100 on Direct and grandfathered keys; max 1000 on keys issued as Sync. Page through with `page` for more. | | `page` | int | 1-based. On a Sync key, page 1 (or no `page`) starts a poll and stamps your cadence; page 2+ requested inside your sync interval continues that poll and is **not** cadence-checked. A continuation sent after the interval has elapsed counts as a new poll. | ### Unknown parameters Unsupported parameters are currently **ignored**, and the response carries an `X-SportFeeds-Warning` header plus a `warnings[]` array naming each unknown parameter and the suggested correction. A future release will reject them with `400 INVALID_PARAMETER` (30 days' notice will be given). Every successful `/posts` response also carries `X-SportFeeds-Mode: direct` or `X-SportFeeds-Mode: sync`, telling you which delivery mode the key is configured for. It is informational — the payload is identical either way. **Agents must treat `warnings[]` as an error during development.** If it is non-empty, your query is not doing what you think it is. Common offenders: `league=` (use `leagues=`), `sport=` (use `sports=`), `team_id=`, `league_name=`, `q=`, `query=`. --- ## 4. League and sport codes These are SportFeeds' universal codes. **Do not** pass provider IDs or free-text names here — only the codes below (any casing). ### Sports (`sports=`) ``` americanfootball football basketball baseball hockey golf cricket rugby mma tennis boxing motorsport athletics cycling wrestling ``` > `football` means **association football (soccer)**. The NFL/NCAA game is > `americanfootball`. `soccer` is accepted as an alias for `football`. ### Leagues (`leagues=`) | Sport | Codes | |---|---| | americanfootball | `NFL`, `NCAAFB` | | basketball | `NBA`, `WNBA`, `NCAAMB` | | baseball | `MLB` | | hockey | `NHL` | | golf | `PGA`, `GOLF`, `DPWORLDTOUR`, `SUNSHINETOUR` | | football (soccer) | `EPL`, `MLS`, `FIFA`, `SOCCER`, `LALIGA`, `BUNDESLIGA`, `SERIEA`, `LIGUE1`, `UCL`, `SAPREMIERSHIP`, `ISL` | | cricket | `CRICKET`, `IPL`, `SA20` | | rugby | `RUGBY`, `URC`, `SUPERRUGBY`, `SIXNATIONS`, `RWC` | | mma | `MMA`, `UFC`, `PFL` | Accepted aliases (auto-mapped): `ChampionsLeague→UCL`, `PremierLeague→EPL`, `PSL`/`DStvPremiership→SAPREMIERSHIP`, `WorldCup`/`FootballWc26→FIFA`, `FootballNcaa→NCAAFB`, `NCAA→NCAAMB`, `EuropeanTour→DPWORLDTOUR`, `RugbyWorldCup→RWC`. Live coverage depth per league is published at https://sportfeeds.com/coverage. Some codes are accepted but thinly covered — check coverage before promising a user complete data for a league. --- ## 5. IDs — bring your own, or use ours You do not have to migrate to SportFeeds IDs. Pass `id_type` and use the IDs you already have. ### Supported `id_type` values ``` sportfeeds code espn_guid espn_uid espn_slug espn sportradar sportsdataio sportsstack grid apisports nba yahoo yahoo_dfs rotowire draftkings fanduel ``` ### SportFeeds IDs Every league, team, player and post also carries a stable **8-digit numeric `sportfeeds_id`** (10000000–99999999), unique across all entity types. Every post item returns `sportfeeds_id` alongside whichever `id_type` you requested, so you can join both ways. ### `GET /ids` — the translation endpoint ```bash # All NFL teams with their Sportradar IDs curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/ids?entity=teams&league=NFL&reference_id=sportradar_id" # All NFL players with ESPN GUIDs curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/ids?entity=players&league=NFL&reference_id=espn_guid" # Reverse lookup: which SportFeeds team is this Sportradar id? curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/ids?entity=teams&league=NFL&reference_id=sportradar_id&lookup=" # Every active league and its IDs curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/ids?entity=leagues&reference_id=sportsstack_id" # Single post by id curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/ids?entity=posts&lookup=" ``` | Param | Notes | |---|---| | `entity` | **required** — `teams`, `players`, `leagues`, `posts` | | `league` | required for `teams` and `players` | | `reference_id` | the provider ID column to include in the response | | `lookup` | filter to one row; matched against `reference_id`, or `sportfeeds_id` when `reference_id` is omitted | **Recommended agent pattern:** cache the `/ids` mapping for your leagues once at startup (or nightly). Rosters change slowly; do not call `/ids` per post. --- ## 6. The engagement rating (`min_score`) Each post gets a **0–10 engagement rating** computed *relative to that author's own rolling 100-post baseline* — not against the whole firehose. A 10 from a small club account and a 10 from ESPN are both genuinely exceptional for that account. | Band | Meaning | |---|---| | 0–3 | Below the author's norm (often promos/ads) | | 4–5 | Below average | | 6 | Average for that author | | 7–8 | Highly engaged | | 9 | Rare — top of the author's year | | 10 | Unicorn (~50x the author's average) | The rating is driven ~85% by interaction ratio (retweets, likes, quotes, replies) and ~15% by views, and it is refreshed on a snapshot ladder at 1m, 5m, 15m, 30m, 60m, 6h and 12h after publication. A post's rating can therefore move upward for ~12 hours after you first see it. Practical guidance: - Feed/product surfaces: `min_score=7`. - "Best of" or push notifications: `min_score=8` or `9`. - Never use `min_score` as an absolute popularity measure across authors. --- ## 7. Response shape ```json { "pagination": { "page": 1, "limit": 20, "has_next": true, "has_prev": false }, "warnings": [], "items": [ { "id": "1750000000000000000", "sportfeeds_id": 41822317, "post_url": "https://x.com/espn/status/1750000000000000000", "text": "…", "created_at": "2026-08-19T20:00:00Z", "sport": "americanfootball", "league": "NFL", "score": 8.4, "highlight": true, "media_type": "video", "author": { "username": "espn", "name": "ESPN", "profile_image_url": "https://…", "verified": true }, "teams": [ { "sportfeeds_id": 20481933, "name": "Kansas City Chiefs", "sportradar_id": "…" } ], "players": [ { "sportfeeds_id": 63920114, "name": "Patrick Mahomes", "sportradar_id": "…" } ], "media": [ { "url": "https://pbs.twimg.com/amplify_video_thumb/…/img/….jpg", "preview_image_url": "https://pbs.twimg.com/amplify_video_thumb/…/img/….jpg", "media_key": "13_2096226426907230210", "width": 1080, "height": 1440, "duration_ms": 24000, "video_url_low": "https://video.twimg.com/amplify_video/…/320x568/….mp4", "video_url_medium": "https://video.twimg.com/amplify_video/…/720x1280/….mp4", "video_url_high": "https://video.twimg.com/amplify_video/…/2160x3840/….mp4" } ] } ] } ``` Field notes for agents: - `created_at` is the **publication** time on X, not our ingest time. Sort and de-dupe on it. - `id` is the native X post id and is globally unique — use it as your primary key. - `score` is the engagement rating (0–9, one decimal) on every post. It is both readable and filterable via `min_score`; 7+ is top performing. - **Media:** for a video, `media[].url` and `preview_image_url` are the still image (poster). The playable mp4s are `video_url_low` / `video_url_medium` / `video_url_high`. For a photo, `url` is the image itself and no `video_url_*` fields are present. `media_key` is X's stable asset id. - `teams[]`/`players[]` always include `sportfeeds_id`, plus the `{id_type}_id` column you asked for. A null provider id means we have no mapping for that entity. - News fields (`category`, `news_type`, `news_status`, `news_origin`, `news_attribution`) only appear when `include_news=true` or a news filter is present. - Always render the post's author and link back to `post_url` (see §10). --- ## 8. Geo availability (`user_location`) Some sources are only cleared for viewing in certain countries (rights restrictions). Pass the end user's country: ```bash curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/posts?leagues=EPL&media_type=video&user_location=ZA" ``` - Value is an ISO 3166-1 alpha-2 code (`US`, `ZA`, `GB`, `IN`…). Invalid codes → 400. - Sources not marked viewable in that region are excluded from results. - If you serve users in multiple countries, pass `user_location` on **every** request and key your cache by it. ### Which countries a source is cleared for (`include_geo`, Sync keys only) If you cache posts and decide regional visibility yourself, ask for the clearance list instead of filtering per request: ```bash curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/posts?leagues=EPL&include_geo=true" ``` Each item then carries a `geo` object: ```json "geo": { "allowed_countries": ["US", "GB"], "blocked_countries": [], "updated_at": "2026-09-01T12:00:00Z" } ``` - Codes are ISO 3166-1 alpha-2. Re-check `updated_at` — clearances change. - Omitted unless you ask for it, and ignored on Direct and grandfathered keys, so no existing payload changes. ### Post analysis (`include_analysis`, any key type) Ask for AI analysis alongside the posts you already fetch: ```bash curl -H "Authorization: Bearer $KEY" "https://api.sportfeeds.com/v1/posts?leagues=NFL&include_analysis=true" ``` Each analysed item then carries an `analysis` object alongside `media`: ```json "analysis": { "sentiment": { "label": "negative", "intensity": 7.5, "entities": [ { "type": "team", "name": "Cincinnati Bengals", "sentiment": "negative" }, { "type": "player", "name": "Ja'Marr Chase", "sentiment": "negative" } ] } } ``` - `label` is `positive`, `negative` or `neutral`; `intensity` is 0-10 tone intensity. - Omitted unless you ask for it, and omitted on posts not yet analysed — so no existing payload changes. --- ## 9. Errors, quotas and retries | Status | `error_code` | Meaning | Agent action | |---|---|---|---| | 400 | `INVALID_PARAMETER` | Bad/missing param value | **Terminal.** Fix the request; do not retry. | | 401 | `UNAUTHORIZED` | Missing/invalid/revoked key | **Terminal.** Surface a config error. | | 402 | `SUBSCRIPTION_REQUIRED` | No active subscription | **Terminal.** Tell the operator to fix billing. | | 410 | `ENDPOINT_DEPRECATED` | Reserved for retired endpoints | **Terminal.** Rewrite to `GET /posts`. | | 429 | `USAGE_LIMIT_REACHED` | Monthly call cap reached (hard stop, no overage billing) | Stop the loop until the next billing period. | | 429 | `SYNC_INTERVAL_NOT_ELAPSED` | Sync key polled too early | Sleep `retry_after_seconds` (also in the `Retry-After` header), then retry. Paging through a poll you already started is never blocked. | | 200 | — | Team/player/source filters that match nothing | **Not an error.** You get `items: []`. Do not treat it as a 404. | | 503 | `QUERY_TIMEOUT` | Query too broad for its time budget | Narrow it (add `since`, fewer leagues, lower `limit`) and retry once. | | 5xx | — | Transient | Retry ≤3x with exponential backoff + jitter. | Error body shape: ```json { "ok": false, "error_code": "INVALID_PARAMETER", "error_message": "Unsupported league code: PREMIER" } ``` **Never** retry a 400/401/402/410 with the same request — the answer will not change. ### Quota hygiene for agents Your plan has a monthly call cap (check `GET /account/information`). An agent loop can burn a month of calls in minutes. Required practices: 1. Poll with `since=` — never re-page history. 2. Responses are cached for 60s; polling faster than once per minute buys nothing. 3. Ask for the largest `limit` you'll actually use rather than paging repeatedly. 4. Put a hard request budget in the agent loop and fail closed when it's hit. --- ## 10. Display, playback & design practices Content originates on X and must be presented accordingly. This section also explains how to make video play reliably in production and the minimum design patterns we expect on every post surface. ### Which media field actually plays For a video post, `media[].url` and `media[].preview_image_url` are the still image. Pointing a `