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

All private routes require Authorization: Bearer <key>. Do not put keys in query strings. Rotate from the account desk; old keys 401 immediately.

GET /v1/sports HTTP/1.1
Host: usfp.numadns.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

List endpoints accept sport, date or period, and league_id.

GET /v1/nfl/games?date=2026-09-10
GET /v1/nba/standings?league_id=lg_prairie
GET /v1/mlb/games/g-104
GET /v1/nhl/games?format=csv

Object shapes stay stable per sport family. Football uses box, diamond sports use linescore, soccer uses events. Catalog: Sports.

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.