API
How to use the API (no experience needed)
What is an API? It is a web address that gives you scores as plain data instead of a web page. Software such as a scorebug or graphics program can read that data on its own, so you never have to retype a score. If you only want to look at scores, you do not need the API at all: use the Scores page.
Step 1 - Try it in your browser
Copy this address into a new browser tab. The browser will show a block of text, and that text is the API's answer:
http://ajssurfacebook3.tail62af76.ts.net/api/v1/games
That is a list of games. Each item has its teams, score, period and status. The text is in a format called JSON: names in quotes, each followed by its value. You can read it like a form, for example "status": "live" means the game is live. Nothing is changed by just looking.
Step 2 - Find a game's ID
Every game has a number called its ID. Open a game on the Scores page and look at the address bar: in http://ajssurfacebook3.tail62af76.ts.net/game/5 the ID is 5. You can also find it as "id" in the list from Step 1.
Step 3 - Get one game for your scorebug
Put the ID into this address (swap 5 for your game's ID):
http://ajssurfacebook3.tail62af76.ts.net/api/v1/games/5/scorebug
This gives simple, flat fields (home score, away score, period and so on) that scorebug software understands. Add ?format= and pick the one your software wants:
?format=json- the default, used by most apps (and matches ScoreTrace)?format=csv- a spreadsheet-style line, good for tools that read CSV files?format=xml- for tools that ask for XML?format=text- plainName=valuelines
In your scorebug software, look for a setting like data source, URL or web feed, paste the address in, and set it to refresh every few seconds. The score is current every time the software asks.
http://ajssurfacebook3.tail62af76.ts.net/overlay/5 as a Browser Source in OBS or vMix. It shows a ready-made scorebug that updates by itself.Step 4 - Narrow down the list (optional)
Add filters to the end of the games address. Start with ?, and join extra filters with &:
http://ajssurfacebook3.tail62af76.ts.net/api/v1/games?status=live- only games being played right nowhttp://ajssurfacebook3.tail62af76.ts.net/api/v1/games?sport=football&date=2026-11-20- football games on one date
About dates: date= means that calendar day in the site's local timezone, so a Friday 7 PM kickoff is found under Friday. If your games are in a different timezone, add it to the address, for example &tz=America/Chicago. Admins can change the default with the timezone setting.
Step 4b - One feed for all the teams you follow
If you have an account, you do not need a separate address for every game. Follow your teams on the My teams page, then use your username as your ID (swap yourname for it):
http://ajssurfacebook3.tail62af76.ts.net/api/v1/users/yourname/scorebug
That one address returns every game for the teams you follow, one row per game: live games first, then upcoming, then finished. It accepts the same ?format= choices as Step 3 and the same filters as Step 4, for example ?status=live. Add it to vMix (or any data-driven scorebug) as a single data source. .../users/yourname/games gives the full details instead. Your number ID works in place of the username, and both are shown on the My teams page.
Step 5 - API keys: when you need one
Reading scores works without any key, but the site limits how many requests you can send each minute. If you run into that limit, ask a site admin for a read key.
Changing a score through the API needs a write key. A key is a long password for your software; the admins create them. Send it with every request as a header named X-API-Key. Keep it private: anyone who has a write key can change scores. If a key leaks, tell an admin so it can be revoked.
Step 6 - Send a score (write key only)
Browsers cannot send data just by opening an address, so use a tool like curl (included with Windows 10/11 as curl.exe, and with macOS and Linux). Change the game ID, key and numbers to yours:
curl -X POST http://ajssurfacebook3.tail62af76.ts.net/api/v1/games/5/score -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" -d '{"home_score":14,"away_score":7,"period":"Q2"}'
You can send just the parts that changed. Valid periods depend on the sport (football: Q1, Q2, HT, Q3, Q4, OT, Final). If it works you get the updated game back; if not you get a short "error" message that says what to fix.
If something does not work
- Nothing loads: check the address starts with
http://ajssurfacebook3.tail62af76.ts.netand has no extra spaces. - "game not found": the ID is wrong; look it up again (Step 2).
- "rate limit exceeded": wait a minute, send requests less often, or ask for a read key.
- 401 or "key" errors: the key is missing, mistyped, revoked, or is a read key where a write key is needed.
The tables below list every endpoint for developers.
Reference
Base URL: http://ajssurfacebook3.tail62af76.ts.net/api/v1. Reads are open (rate limited); an API key raises your limit.
Writes need a write key. Send keys as X-API-Key: YOUR_KEY or Authorization: Bearer YOUR_KEY.
Read
| Endpoint | What it returns |
|---|---|
GET /games | List games. Filters: sport, status (scheduled/live/final), date (YYYY-MM-DD, UTC), team, limit. Time window on the start time: from (inclusive) and to (exclusive), ISO timestamps; add include_live=1 to keep games that are live right now; order=desc for newest first or order=asc for strictly oldest first |
GET /games/{id} | One game |
GET /games/{id}/scorebug | Flat fields for scorebug software. ?format=json|csv|xml|text. JSON is a one-item list, like ScoreTrace's /scoretrace. Team colors: HomeColor/AwayColor (primary) and HomeColor2/AwayColor2 (secondary, empty if the school has none) |
GET /users/{username}/games | Games for every team that user follows, in one list (same shape and filters as /games). The username is the user's ID (not case-sensitive); the numeric user id also works. Unknown or disabled users give 404 |
GET /users/{username}/scorebug | The same games as flat scorebug rows, one per game, for vMix and similar. ?format=json|csv|xml|text (XML root is <scorebugs>; an empty follow list gives an empty list / header-only CSV). Same filters as /games |
GET /games/{id}/history | Scoring changes |
GET /schools, /schools/{id} | Schools: name, mascot, short, location, color, color2 (optional secondary color, empty if none), logo and the sports each has a team in (?sport=) |
GET /teams, /teams/{id} | A school's team in one sport (?sport=); includes the school fields |
GET /stream?game={id} | Server-Sent Events (event: score), pushed the moment a score changes |
Write (write key)
POST /games/{id}/score | JSON: home_score, away_score, period (Q1, Q2, HT, Q3, Q4, OT, Final...), status (scheduled/live/final) - send any subset. Status follows the period: no period = scheduled, Final = final, anything else = live. A status sent on its own is turned into the matching period. ScoreTrace keys (HomeScore, AwayScore, Period) also work. |
POST /games | {"sport","home_id","away_id","start_time","site","location"}. site is home (default), away or neutral; a neutral site needs location. Otherwise the game uses the host school's location. |
POST /schools | {"name","mascot","short","location","color","color2" (optional),"sports":["football","volleyball"]} |
POST /teams | {"school_id","sport"} adds a sport to an existing school |
POST /games/{id}/suggest | Website update form (same fields as above). Needs a signed-in user account by default. Applies instantly, or goes to the admin review queue, depending on public_updates in settings.json. Developers should use a write key with /score instead. |
Accounts (website sessions)
Visitors can create an account to keep their own followed-teams list and to update scores or submit new teams. These endpoints use the website's login cookie, not API keys:
POST /auth/register, /auth/login, /auth/logout, GET /me, GET|PUT|DELETE /me/teams/{id}, GET /games?following=1, POST /team-submissions, PUT /me/prefs (saved scoreboard filters).
Example
curl http://ajssurfacebook3.tail62af76.ts.net/api/v1/games?status=live
curl "http://ajssurfacebook3.tail62af76.ts.net/api/v1/games/1/scorebug?format=csv"
curl "http://ajssurfacebook3.tail62af76.ts.net/api/v1/users/yourname/scorebug?status=live"
curl -X POST http://ajssurfacebook3.tail62af76.ts.net/api/v1/games/1/score -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" -d '{"home_score":21,"period":"Q3"}'