Get a key. Push a game. Pull a slate.

Getting started

1. Pick a plan on Pricing. Free is enough for a 6-team proof.
2. Create a league and download the CSV templates — or POST JSON.
3. Create an API key. Prefix usf_live_ is production; usf_test_ never writes public feeds.
4. Confirm with GET /v1/sports.

Authentication

Public JSON feeds require an API key created in the league office. Send Authorization: Bearer usf_live_… or X-Api-Key. Do not put keys in query strings. Revoked keys 401 immediately. Dashboard session tokens are separate (login JWT).

GET /api/v1/feeds/leagues/{league_id}/standings HTTP/1.1
Host: sports-feed.totalaisports.com
Authorization: Bearer usf_live_…
Accept: application/json

League ingest

Leagues push to POST /v1/ingest. The body is a list of games (and optional box lines). Idempotent on game_id. A second POST with the same id replaces scores, it does not duplicate the game.

{
  "league_id": "lg_prairie",
  "sport": "softball",
  "games": [
    {
      "game_id": "g-104",
      "home": "Northside",
      "away": "Prairie",
      "home_score": 4,
      "away_score": 2,
      "status": "final",
      "period": 7
    }
  ]
}

CSV equivalent: see For Leagues. Rejected rows return errors[] with line number and reason. We never coerce a blank score to zero.

Read feeds

Canonical prefix /api/v1/feeds. Every response is { object, league, data, meta }. See the developer portal for full examples.

GET /api/v1/feeds/leagues/{league_id}/teams
GET /api/v1/feeds/leagues/{league_id}/standings
GET /api/v1/feeds/leagues/{league_id}/schedule?status=live
GET /api/v1/feeds/games/{game_id}/boxscore
GET /api/v1/leagues/{league_id}/schedule
GET /api/v1/games/{game_id}/boxscore

Schedule accepts status, from, and to (YYYY-MM-DD). Boxscore includes period lines, clock, and sport stats.

Webhooks

Pro and Enterprise. Subscribe a URL. Events: game.score_changed, game.final, player.injury. Each payload is signed: header X-USF-Signature is HMAC-SHA256 of the raw body. We retry for 24 hours on non-2xx.

Errors & limits

• 401 — missing or rotated key
• 403 — league not on this account
• 422 — ingest row failed validation
• 429 — rate limit; honor Retry-After

Monthly call caps are on Pricing. Burst rps is per plan. Enterprise quotes a dedicated cluster when 1M/month is not enough.

Need a human?

hello@usfp.numadns.com — League plan and above get priority. Sibling product: Total AI Sports for the commissioner office.