API reference

24 endpointsJSON

Overview

Base URL
https://secrets.team31000.org
Format
JSON over HTTPS. All routes are GET except /api/predict.
Authentication
None
Rate limit
None published. Cache responses and keep request volume modest.
Browser access
Other origins are blocked by CORS. Call the API from a server or script.
Seasons
season is a start year: 2025 is 2025–26. Omit it for the current season (2026–27 BIOBUZZ), which has little data so far. Examples use 2025.
Errors
Failures return { "error": "message" } with status 400, 404, 500, or 503. Data that is not published yet returns 200 with available: false.
FIRST data terms.Event data comes from FIRST’s FTC Events API, which allows non-commercial use only. Read their terms before building on this data.
Stable fields only.Examples are trimmed. Responses include other fields, such as legacy metrics, that are not supported and may change or disappear. Routes that refresh or sync data are not public and are not listed.

Seasons and summary

Season catalog, a snapshot of the current state of the data, and metric distributions.

GET/api/seasons

The season catalog and the current default season. Each season says whether its score schema and advancement rules are verified; OPR and score breakdowns are unavailable until the score schema is.

No parameters.

Example request
curl "https://secrets.team31000.org/api/seasons"
Example response
JSON, trimmed
{
  "current_season": 2026,
  "seasons": {
    "2025": {
      "id": 2025,
      "label": "2025–2026",
      "game_name": "DECODE",
      "score_schema_verified": true,
      "official_manual_url": "https://ftc-resources.firstinspires.org/ftc/archive/2026/game/manual"
    },
    "2026": {
      "id": 2026,
      "label": "2026–2027",
      "game_name": "BIOBUZZ",
      "score_schema_verified": false,
      "advancement_rules_verified": false,
      "start_date": "2026-09-12"
    }
  }
}

GET/api/summary

Season snapshot: matches played, the highest-scoring match, top teams by Elo, the number of Worlds-qualified teams, and recent activity. Cached for five minutes. The availability objects say which parts could be computed.

Parameters for GET /api/summary
ParameterTypeDescription
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/summary?season=2025"
Example response
JSON, trimmed
{
  "season": 2025,
  "matches_played": 45375,
  "teams_qualified": 146,
  "leaderboard_metric": "overall_elo",
  "top_teams": [
    {
      "team_number": 30030,
      "overall_elo": 3110.38,
      "opr": 211.24,
      "wins": 78,
      "losses": 10,
      "ties": 0,
      "matches_played": 88,
      "teams": {
        "name": "Exodus",
        "region": "TX"
      }
    }
  ],
  "season_high_score_match": {
    "event_code": "FPECAR",
    "event_name": "Carolinas Premier Event",
    "match_id": 49,
    "top_score": 714,
    "red_teams": [
      17421,
      25550
    ],
    "blue_teams": [
      23396,
      20003
    ]
  },
  "activity": {
    "latest_events": [],
    "recent_results": [],
    "recent_upsets": [],
    "trending_teams": [],
    "availability": {
      "latest_events": true,
      "recent_results": true,
      "recent_upsets": true,
      "trending_teams": true
    }
  },
  "availability": {
    "matches_played": true,
    "top_teams": true,
    "teams_qualified": true,
    "season_high_score_match": true
  }
}

GET/api/stats/distribution

Quantiles and histogram bins for one metric across a season, optionally with one team’s value and percentile. OPR, consistency, and the legacy momentum metric return 400 for seasons whose score schema is not verified.

Parameters for GET /api/stats/distribution
ParameterTypeDescription
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
metricstringstringoverall_elo, matches_played, consistency_index, or opr. The legacy momentum metric is also accepted. Default: overall_elo.
eventstringstringEvent code. Required when metric is opr, because OPR is specific to an event.
teamintegerintegerTeam number to include as selected_team, with its value and percentile.
binsintegerintegerHistogram bin count, from 1 to 40. Default: 24.
Example request
curl "https://secrets.team31000.org/api/stats/distribution?season=2025&metric=overall_elo&team=31000&bins=6"
Example response
JSON, trimmed
{
  "season": 2025,
  "metric": "overall_elo",
  "label": "Elo",
  "count": 8364,
  "stats": {
    "minimum": 856.08,
    "p25": 1343.97,
    "median": 1424.1,
    "p75": 1522.3,
    "p90": 1711.93,
    "p95": 1891.99,
    "p99": 2240.96,
    "maximum": 3110.38
  },
  "histogram": [
    {
      "start": 856.08,
      "end": 1231.8,
      "count": 524,
      "contains_selected_team": false
    }
  ],
  "selected_team": {
    "team_number": 31000,
    "name": "VANTA",
    "value": 1657.43,
    "percentile": 87.2
  },
  "last_updated": "2026-09-24T02:36:02.468863+00:00"
}

Leaderboard

Season rankings with server-side filtering, sorting, and paging.

GET/api/leaderboard

One page of team ratings for a season. Rows include identity, Elo, OPR where available, record, and Worlds status. Pass fields=compact to load a whole season in one request.

Parameters for GET /api/leaderboard
ParameterTypeDescription
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
limitintegerintegerRows per page, from 1 to 20000. Default: 100.
offsetintegerintegerRows to skip, for paging. has_more in the response says whether another page exists. Default: 0.
order_bystringstringSort column: overall_elo, opr, best_event_opr, consistency_index, matches_played, wins, losses, ties, region, or last_updated. Score-derived columns fall back to overall_elo for seasons without a verified score schema. Default: overall_elo.
order_dirstringstringasc or desc. ascending=true is also accepted. Default: desc.
min_matchesintegerintegerOnly teams with at least this many matches. Default: 0.
regionstringstringRegion filter: a state or region code or name, such as FL, USFL, or Florida.
countrystringstringCountry name, such as USA or Canada.
searchstringstringA team number matches exactly. Other text matches team name, region, state, or country.
rookie_yearintegerintegerOnly teams whose rookie year matches.
eventstringstringOnly teams that played at this event code.
worlds_qualified_onlybooleanbooleantrue to return only teams qualified for the FIRST Championship.
rank_periodstringstringAdds elo_rank and rank_change to each row: previous_event, previous, 7d, 30d, or season. rank_movement in the response says whether a comparison exists.
fieldsstringstringcompact returns a reduced row (see the note below). Any other value returns full rows.
Example request
curl "https://secrets.team31000.org/api/leaderboard?season=2025&limit=2&worlds_qualified_only=true"
Example response
JSON, trimmed
{
  "season": 2025,
  "offset": 0,
  "limit": 2,
  "has_more": true,
  "entries": [
    {
      "team_number": 3565,
      "season": 2025,
      "overall_elo": 2805.66,
      "opr": 223.52,
      "best_event_opr": 231.4,
      "wins": 62,
      "losses": 12,
      "ties": 0,
      "matches_played": 74,
      "region": "MA",
      "last_event_code": "USCHSLAOS",
      "last_event_rank": 4,
      "worlds_qualified": true,
      "worlds_region_id": "massachusetts",
      "worlds_advancement_rank": 1,
      "teams": {
        "name": "Ghost Robotics",
        "region": "MA",
        "state": "MA"
      }
    }
  ],
  "rank_movement": {
    "available": false,
    "period": null
  }
}

fields=compact keeps team_number, season, region, overall_elo, opr, best_event_opr, highest_np_score, wins, losses, ties, matches_played, consistency_index, strength_of_schedule, the RP rate, probability, and count fields, worlds_advancement_rank, last_event_code, last_event_rank, and last_calculated. teams is reduced to name, region, state, and country, and per_event_metrics to { elo, opr, elo_delta } per event. The response also carries "fields": "compact".

Teams

Search, profiles, and per-team history. Team routes take team_number in the path.

GET/api/team/{team_number}

A team’s profile and season metrics: Elo, OPR, record, global and regional rank with percentiles, and per-event ratings. Returns 404 for an unknown team and metrics: null when the team has no rated matches that season.

Parameters for GET /api/team/{team_number}
ParameterTypeDescription
team_numberpathintegerintegerFTC team number.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/team/31000?season=2025"
Example response
JSON, trimmed
{
  "season": 2025,
  "team_number": 31000,
  "team": {
    "team_number": 31000,
    "name": "VANTA",
    "city": "Orlando",
    "state": "FL",
    "region": "FL",
    "country": "USA",
    "rookie_year": 2025,
    "school_name": "Family/Community",
    "website": "https://www.team31000.org"
  },
  "metrics": {
    "overall_elo": 1657.43,
    "opr": 83.09,
    "best_event_opr": 95,
    "highest_np_score": 326,
    "matches_played": 45,
    "wins": 23,
    "losses": 22,
    "ties": 0,
    "record": {
      "wins": 23,
      "losses": 22,
      "ties": 0
    },
    "global_rank": 1068,
    "global_percentile": 87.2,
    "regional_rank": 40,
    "regional_percentile": 83.5,
    "last_event_code": "FTCCMP1LOVE",
    "last_event_rank": 7,
    "per_event_metrics": {
      "USFLORM1": {
        "elo": 1514.3,
        "opr": 25
      }
    }
  },
  "_meta": {
    "metrics_available": true
  }
}

GET/api/team/{team_number}/events

Events the team played, in date order, each with its record, scoring averages, and every match. team_names maps team numbers seen in those matches to names.

Parameters for GET /api/team/{team_number}/events
ParameterTypeDescription
team_numberpathintegerintegerFTC team number.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/team/31000/events?season=2025"
Example response
JSON, trimmed
{
  "events": [
    {
      "event_code": "FTCCMP1LOVE",
      "event_name": "FIRST World Championship - Lovelace Division",
      "start_date": "2026-04-29",
      "end_date": "2026-05-02",
      "wins": 3,
      "losses": 7,
      "ties": 0,
      "played_count": 10,
      "unplayed_count": 0,
      "avg_scored": 192.1,
      "avg_allowed": 219.6,
      "matches": [
        "…"
      ]
    }
  ],
  "team_names": {
    "15083": "Overclock"
  }
}

GET/api/team/{team_number}/matches

The team’s match history grouped by event, from the team’s point of view: alliance scores, result (W, L, or T), ranking points earned, penalties, and the raw score breakdown.

Parameters for GET /api/team/{team_number}/matches
ParameterTypeDescription
team_numberpathintegerintegerFTC team number.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/team/31000/matches?season=2025"
Example response
JSON, trimmed
{
  "team_number": 31000,
  "season": 2025,
  "events": [
    {
      "event_code": "USFLORM1",
      "event_name": "Orlando Robotics League Meet 1",
      "event_start": "2025-11-15",
      "event_end": "2025-11-15",
      "summary": {
        "matches_played": 5,
        "record": {
          "wins": 1,
          "losses": 4,
          "ties": 0
        },
        "avg_scored": 49.8,
        "avg_allowed": 78
      },
      "matches": [
        {
          "match_id": 8,
          "match_label": "Quals 8",
          "tournament_level": "Quals",
          "red_teams": [
            15065,
            26290
          ],
          "blue_teams": [
            31000,
            31997
          ],
          "red_score": 57,
          "blue_score": 54,
          "result": "L",
          "rp": {
            "goal": false,
            "movement": false,
            "pattern": true
          },
          "rp_total": 1
        }
      ]
    }
  ]
}

GET/api/team/{team_number}/stats_over_time

One row per match with the team’s scoring components and its Elo and OPR at that point. Scoring field names follow the season’s game. For a season whose score schema is not verified, data is empty, score_metrics_available is false, and score_metrics_message says why.

Parameters for GET /api/team/{team_number}/stats_over_time
ParameterTypeDescription
team_numberpathintegerintegerFTC team number.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/team/31000/stats_over_time?season=2025"
Example response
JSON, trimmed
{
  "team_number": 31000,
  "season": 2025,
  "score_metrics_available": true,
  "score_schema_verified": true,
  "score_metrics_message": null,
  "data": [
    {
      "event_code": "USFLORM1",
      "match_id": 8,
      "played_at": "2025-11-15T16:26:51.881+00:00",
      "elo": 1514.3,
      "opr": 24.98,
      "total_points": 54,
      "total_np": 39,
      "auto_points": 0,
      "teleop_points": 39,
      "penalty_points": 5
    }
  ]
}

GET/api/team/{team_number}/event_metrics_over_time

One row per event, in order, with the team’s Elo and OPR at that event. cumulative_elo can repeat the season-end rating in stored data, so use elo to chart progression.

Parameters for GET /api/team/{team_number}/event_metrics_over_time
ParameterTypeDescription
team_numberpathintegerintegerFTC team number.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/team/31000/event_metrics_over_time?season=2025"
Example response
JSON, trimmed
{
  "team_number": 31000,
  "events": [
    {
      "event_code": "USFLORM1",
      "event_index": 1,
      "first_match_time": "2025-11-15T16:26:51.881+00:00",
      "match_count": 5,
      "elo": 1514.3,
      "opr": 25,
      "cumulative_opr": 25
    }
  ]
}

GET/api/team/{team_number}/awards

Awards the team won in a season. Loaded separately from the profile so a slow awards lookup does not block it. availability says whether the awards source answered.

Parameters for GET /api/team/{team_number}/awards
ParameterTypeDescription
team_numberpathintegerintegerFTC team number.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/team/31000/awards?season=2025"
Example response
JSON, trimmed
{
  "team_number": 31000,
  "season": 2025,
  "availability": "available",
  "awards": [
    {
      "event_code": "USFLORLT",
      "event_name": "USFLORLT",
      "name": "Inspire Award Winner",
      "original_name": "Inspire Award",
      "series": 1,
      "team_number": 31000
    }
  ]
}

GET/api/team/{team_number}/suggested

Top teams from the event the team most recently played, for “teams to look at next”.

Parameters for GET /api/team/{team_number}/suggested
ParameterTypeDescription
team_numberpathintegerintegerFTC team number.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/team/31000/suggested?season=2025"
Example response
JSON, trimmed
{
  "source_event": "FTCCMP1LOVE",
  "suggested_teams": [
    {
      "team_number": 30030,
      "team_name": "Exodus",
      "event_code": "FTCCMP1LOVE",
      "event_rank": 1,
      "overall_elo": 3110.38,
      "opr": 211.24,
      "wins": 9,
      "losses": 1,
      "ties": 0,
      "global_rank": 1
    }
  ]
}

Events

The event catalog and per-event routes. Event routes take event_code in the path.

GET/api/events

Search and filter a season’s events, with paging. Each event carries its location, dates, status, and match count.

Parameters for GET /api/events
ParameterTypeDescription
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
search_textstringstringCase-insensitive match on event name or code. worlds and championship also match FIRST Championship events.
regionstringstringRegion code or name (USMA, MA), or a group: USA, NORTH_AMERICA, SOUTH_AMERICA, EUROPE, ASIA, OCEANIA, INTERNATIONAL.
statestringstringState or province code or name.
typestringstringEvent type contains this text, such as Championship or League Meet.
statusstringstringcompleted, upcoming (or scheduled), or live.
start_datestringstringOnly events ending on or after this date, YYYY-MM-DD.
end_datestringstringOnly events starting on or before this date, YYYY-MM-DD.
limitintegerintegerEvents per page, from 1 to 500. Default: 100.
offsetintegerintegerEvents to skip. Default: 0.
order_bystringstringstart_date, end_date, name, type, region, or event_code. Default: start_date.
order_dirstringstringasc or desc. Default: desc.
Example request
curl "https://secrets.team31000.org/api/events?season=2025&search_text=Massachusetts&limit=2"
Example response
JSON, trimmed
{
  "count": 2,
  "total": 2,
  "offset": 0,
  "limit": 2,
  "catalog_updated_at": "2026-10-14T20:47:00.561217+00:00",
  "events": [
    {
      "code": "USMACMP",
      "name": "Massachusetts Championship",
      "type": "Championship",
      "status": "completed",
      "start": "2026-03-15T00:00:00",
      "end": "2026-03-15T00:00:00",
      "city": "Boston",
      "state": "MA",
      "country": "USA",
      "venue": "Wentworth Institute of Technology",
      "regionCode": "USMA",
      "total_matches": 55
    }
  ]
}

GET/api/events/{event_code}

Event details, status, summary statistics, and an event difficulty rating once the event has completed. Returns 404 if the code is not in the season.

Parameters for GET /api/events/{event_code}
ParameterTypeDescription
event_codepathstringstringEvent code, such as USMACMP.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/events/USMACMP?season=2025"
Example response
JSON, trimmed
{
  "event": {
    "code": "USMACMP",
    "name": "Massachusetts Championship",
    "event_type": "Championship",
    "start_date": "2026-03-15",
    "end_date": "2026-03-15",
    "city": "Boston",
    "state": "MA",
    "country": "USA",
    "total_matches": 55
  },
  "status": "completed",
  "is_live": false,
  "last_updated_at": "2026-09-23T09:20:48.512467+00:00",
  "hero_stats": {
    "averages": {
      "avg_elo": 1741,
      "avg_np_score": 175,
      "total_matches": 55,
      "total_teams": 36
    },
    "top_team": {
      "team_number": 3565,
      "team_name": "Ghost Robotics",
      "value": 2733.41
    }
  },
  "difficulty": {
    "actual": {
      "label": "Elite",
      "score": 10,
      "top_8_avg": 1803.3,
      "type": "actual"
    }
  }
}

GET/api/events/{event_code}/matches

Every match at the event, with alliances, scores, and the score breakdown. Played matches come from storage and scheduled matches from FIRST. Win probabilities and upset flags are included when computed.

Parameters for GET /api/events/{event_code}/matches
ParameterTypeDescription
event_codepathstringstringEvent code, such as USMACMP.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
sort_bystringstringmatch_num or np_score (combined non-penalty score, highest first). Default: match_num.
Example request
curl "https://secrets.team31000.org/api/events/USMACMP/matches?season=2025"
Example response
JSON, trimmed
{
  "count": 55,
  "matches": [
    {
      "event_code": "USMACMP",
      "match_id": 22001,
      "match_num": 1,
      "tournament_level": "DoubleElim",
      "series": 2,
      "red1_team": 26112,
      "red2_team": 31865,
      "blue1_team": 26181,
      "blue2_team": 27050,
      "red_score_np": 341,
      "blue_score_np": 122,
      "played_at": "2026-03-15T21:29:15.372+00:00",
      "score_breakdown": {
        "red": "…",
        "blue": "…"
      }
    }
  ]
}

GET/api/events/{event_code}/rankings

Official event rankings from FIRST joined with this site’s ratings: season Elo, event Elo, and OPR. Returns an empty list with a message when FIRST has not published rankings.

Parameters for GET /api/events/{event_code}/rankings
ParameterTypeDescription
event_codepathstringstringEvent code, such as USMACMP.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
sort_bystringstringofficial (default; also rs), tbp, np_avg, np_max, opr, event_opr, event_elo, or overall_elo. Anything else sorts by official rank. Default: official.
Example request
curl "https://secrets.team31000.org/api/events/USMACMP/rankings?season=2025"
Example response
JSON, trimmed
{
  "count": 36,
  "rankings": [
    {
      "rank": 1,
      "team_number": 3565,
      "team_name": "Ghost Robotics",
      "record": "4-1-0",
      "wins": 4,
      "losses": 1,
      "ties": 0,
      "matches_played": 5,
      "overall_elo": 2805.7,
      "event_elo": 2083.7,
      "opr": 178.48,
      "event_opr": 191.99,
      "dqs": 0
    }
  ]
}

GET/api/events/{event_code}/teams

Teams registered at the event with their location.

Parameters for GET /api/events/{event_code}/teams
ParameterTypeDescription
event_codepathstringstringEvent code, such as USMACMP.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/events/USMACMP/teams?season=2025"
Example response
JSON, trimmed
{
  "count": 36,
  "teams": [
    {
      "team_number": 3565,
      "name": "Ghost Robotics",
      "city": "Westford",
      "state": "MA",
      "region": "MA",
      "country": "USA"
    }
  ]
}

GET/api/events/{event_code}/awards

Awards at the event, each with the advancement points it is worth, grouped into robot performance, judged, and other. The list is empty until FIRST publishes awards.

Parameters for GET /api/events/{event_code}/awards
ParameterTypeDescription
event_codepathstringstringEvent code, such as USMACMP.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/events/USFLCMP/awards?season=2025"
Example response
JSON, trimmed
{
  "summary": {
    "total_awards": 2,
    "robot_awards": 1,
    "judged_awards": 1,
    "other_awards": 0
  },
  "awards": [
    {
      "team_number": 31000,
      "team_name": "VANTA",
      "type": "Inspire",
      "placement": 3,
      "points": 15,
      "category": "Judged Awards"
    }
  ],
  "categories": {
    "robot_performance": [
      "…"
    ],
    "judged_awards": [
      "…"
    ],
    "other": []
  }
}

GET/api/events/{event_code}/advancement

Advancement point breakdown for each team at the event: qualification, alliance selection, playoffs, and awards, with tiebreak statistics. advancement_slots is a rough estimate (a quarter of the field), not the official allocation. Seasons without verified advancement rules return available: false. Can return 500 or 404 when rankings are missing from FIRST.

Parameters for GET /api/events/{event_code}/advancement
ParameterTypeDescription
event_codepathstringstringEvent code, such as USMACMP.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/events/USMACMP/advancement?season=2025"
Example response
JSON, trimmed
{
  "is_advancement_event": true,
  "event_name": "Massachusetts Championship",
  "total_teams": 36,
  "advancement_slots": 9,
  "teams": [
    {
      "team_number": 3565,
      "team_name": "Ghost Robotics",
      "qualification_rank": 1,
      "advancement_rank": 1,
      "qualified": true,
      "advancement": {
        "qualification_points": 16,
        "alliance_selection_points": 20,
        "playoff_points": 40,
        "award_points": 0,
        "total_points": 76
      },
      "stats": {
        "avg_match_points": 178.5,
        "avg_auto_points": 42,
        "highest_match_score": 379,
        "second_highest_match_score": 320
      },
      "reasoning": "…"
    }
  ]
}

Matches and predictions

A single match, and win probability for any alliance pairing.

GET/api/match/{season}/{event_code}/{match_id}

One match in full: alliances, scores, winner, ranking points, penalties, and the score breakdown. Add team_number to get the same match from that team’s point of view. Returns 404 if the match is not found.

Parameters for GET /api/match/{season}/{event_code}/{match_id}
ParameterTypeDescription
seasonpathintegerintegerSeason start year.
event_codepathstringstringEvent code, such as USMACMP.
match_idpathintegerintegerMatch ID within the event, as returned by the matches routes.
team_numberintegerintegerTeam whose point of view to use; adds team_alliance, result, and opponent_score.
Example request
curl "https://secrets.team31000.org/api/match/2025/USMACMP/22001"
Example response
JSON, trimmed
{
  "match": {
    "event_code": "USMACMP",
    "match_id": 22001,
    "match_label": "DoubleElim 1",
    "tournament_level": "DoubleElim",
    "red_teams": [
      26112,
      31865
    ],
    "blue_teams": [
      26181,
      27050
    ],
    "red_score": 351,
    "blue_score": 142,
    "red_score_np": 341,
    "blue_score_np": 122,
    "winner": "RED",
    "played_at": "2026-03-15T21:29:15.372+00:00",
    "score_breakdown": {
      "red": "…",
      "blue": "…"
    }
  },
  "analytics": {
    "total_points": 493,
    "actual_margin": 209
  },
  "prediction": null
}

POST/api/predict

Estimated win probability for a 2v2 match from season Elo. This is an estimate: score forecasts are unavailable and the model has not been validated against historical results. Teams without a rating start at 1500, and rating_coverage says how many of the four had one. Returns 400 for invalid or duplicate team numbers.

Parameters for POST /api/predict
ParameterTypeDescription
red1_teamrequiredbodyintegerintegerRed alliance team, 1 to 99999.
red2_teamrequiredbodyintegerintegerRed alliance team, different from the others.
blue1_teamrequiredbodyintegerintegerBlue alliance team, different from the others.
blue2_teamrequiredbodyintegerintegerBlue alliance team, different from the others.
seasonbodyintegerintegerSeason whose ratings to use. Default: current season.
Example request
curl -X POST "https://secrets.team31000.org/api/predict" \
  -H "Content-Type: application/json" \
  -d '{"red1_team":3565,"red2_team":31000,"blue1_team":30030,"blue2_team":15083,"season":2025}'
Example response
JSON, trimmed
{
  "season": 2025,
  "input": {
    "red1_team": 3565,
    "red2_team": 31000,
    "blue1_team": 30030,
    "blue2_team": 15083,
    "season": 2025
  },
  "prediction": {
    "red_alliance_win_probability": 0.0219,
    "blue_alliance_win_probability": 0.9781,
    "red_alliance_elo": 2231.55,
    "blue_alliance_elo": 2891.8,
    "predicted_winner": "Blue",
    "prediction_method": "2v2 Elo, equal alliance means, v1",
    "calibration_status": "not validated",
    "score_forecast_available": false,
    "score_forecast_reason": "A validated current-season score model is not available.",
    "rating_coverage": {
      "available": 4,
      "total": 4,
      "starting_rating": 1500,
      "baseline_team_numbers": []
    },
    "red1_details": "…"
  }
}

The prediction object also includes a details object for each of the four teams (red1_details through blue2_details) with their season metrics.

Worlds advancement

Regional championship allocations and teams qualified for the FIRST Championship. For a season whose allocations are not verified, these return available: false with status 200 and no data.

GET/api/advancement/regions

Every regional championship with its slot allocation, date, and status. A region counts as complete once its championship date has passed, and filled_slots then equals worlds_reserved; it does not mean team names have been published.

Parameters for GET /api/advancement/regions
ParameterTypeDescription
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
statusstringstringcomplete, pending, pending_finalization, or all. Default: all.
countrystringstringOnly regions in this country, such as USA or Canada.
Example request
curl "https://secrets.team31000.org/api/advancement/regions?season=2025"
Example response
JSON, trimmed
{
  "summary": {
    "total_regions": 93,
    "completed_regions": 88,
    "pending_regions": 5,
    "total_worlds_slots": 332,
    "total_advancement_slots": 953,
    "total_teams_advanced": 318
  },
  "regions": [
    {
      "region_id": "newfoundland",
      "name": "Newfoundland and Labrador",
      "full_name": "Newfoundland and Labrador Championship",
      "country": "Canada",
      "event_date": "2025-12-06",
      "event_date_end": null,
      "status": "complete",
      "total_slots": 4,
      "worlds_reserved": 1,
      "filled_slots": 1
    }
  ]
}

GET/api/advancement/regions/{region_id}

One region: its allocation, the championship events matched to it, and advancement points for each team when FIRST has marked an event finished. Looks up FIRST data live, so it is slower than the list and teams may be empty. Returns 404 for an unknown region.

Parameters for GET /api/advancement/regions/{region_id}
ParameterTypeDescription
region_idpathstringstringRegion ID from the regions list, such as michigan.
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
Example request
curl "https://secrets.team31000.org/api/advancement/regions/michigan?season=2025"
Example response
JSON, trimmed
{
  "region_id": "michigan",
  "name": "Michigan - FiM",
  "full_name": "Michigan State Championship",
  "country": "USA",
  "status": "complete",
  "event_date": "2025-12-11",
  "total_slots": 46,
  "worlds_reserved": 18,
  "matching_events": [
    {
      "code": "USMICMP",
      "name": "Michigan State Championship-SE",
      "finished": false
    }
  ],
  "teams": [],
  "teams_count": 0,
  "qualified_count": 0
}

GET/api/advancement/teams

Teams qualified for the FIRST Championship, highest advancement points first. This is the list stored in the database, which can lag behind regions marked complete.

Parameters for GET /api/advancement/teams
ParameterTypeDescription
seasonintegerintegerSeason start year, such as 2025 for 2025–26. Default: current season.
limitintegerintegerMaximum teams returned. Default: 500.
searchstringstringMatch team number, team name, or region name.
Example request
curl "https://secrets.team31000.org/api/advancement/teams?season=2025&limit=2"
Example response
JSON, trimmed
{
  "count": 2,
  "total_qualified": 146,
  "teams": [
    {
      "team_number": 11511,
      "team_name": "Referees",
      "region_id": "new_zealand",
      "region_name": "New Zealand",
      "event_code": "FTCCMP1FRAN",
      "advancement_rank": 1,
      "advancement": {
        "total_points": 96
      }
    }
  ]
}