ftc-events-api

name	ftc-events-api
description	Integrate with the official FIRST Tech Challenge Events API in FTC Metrics. Use when fetching events, teams, matches, scores, rankings, or troubleshooting FTC API authentication and responses.
license	MIT
compatibility	["Claude Code"]
metadata	{"author":"ftcmetrics","version":"1.0.0","category":"api"}

FTC Events API Integration

The FTC Events API provides official data for FIRST Tech Challenge competitions. FTC Metrics uses this to fetch events, teams, match schedules, scores, and rankings.

Quick Start

Prerequisites

1. Register for API credentials at https://ftc-events.firstinspires.org/services/API
2. Add credentials to .env:

   FTC_API_USERNAME=your_username
   FTC_API_TOKEN=your_token
   

Basic Usage

import { getFTCApi } from "@ftcmetrics/api/lib/ftc-api";

const api = getFTCApi();

// Get all events for current season
const { events } = await api.getEvents();

// Get teams at an event
const { teams } = await api.getEventTeams("USNCCRR");

// Get match scores
const { matchScores } = await api.getScores("USNCCRR", "qual");

API Reference

Method	Description
getEvents()	List all events for current season
getEvent(code)	Get specific event details
getEventTeams(code)	Get teams registered at event
getTeam(number)	Get team info by number
getSchedule(code, level)	Get match schedule
getMatches(code, level)	Get match results
getScores(code, level)	Get detailed match scores
getRankings(code)	Get team rankings at event
getTeamEvents(number)	Get events a team is registered for

Tournament Levels

• "qual" - Qualification matches (default)
• "playoff" - Elimination matches

Response Types

FTCEvent

interface FTCEvent {
  eventCode: string;
  name: string;
  venue: string;
  city: string;
  stateProv: string;
  country: string;
  dateStart: string;
  dateEnd: string;
  type: string;
  timezone: string;
}

FTCMatchScore

interface FTCMatchScore {
  matchLevel: string;
  matchNumber: number;
  alliances: {
    alliance: "Red" | "Blue";
    totalPoints: number;
    autoPoints: number;
    dcPoints: number;
    endgamePoints: number;
    penaltyPointsCommitted: number;
    team1: number;
    team2: number;
  }[];
}

Authentication

The API uses HTTP Basic Auth with base64-encoded credentials:

private getAuthHeader(): string {
  const credentials = Buffer.from(`${username}:${token}`).toString("base64");
  return `Basic ${credentials}`;
}

Common Patterns

Fetch Event with All Data

async function getFullEventData(eventCode: string) {
  const api = getFTCApi();

  const [eventData, teams, schedule, scores, rankings] = await Promise.all([
    api.getEvent(eventCode),
    api.getEventTeams(eventCode),
    api.getSchedule(eventCode, "qual"),
    api.getScores(eventCode, "qual"),
    api.getRankings(eventCode),
  ]);

  return { eventData, teams, schedule, scores, rankings };
}

Handle Missing Scores

// Matches may not have scores yet (scheduled but not played)
const { matchScores } = await api.getScores(eventCode, "qual");

const completedMatches = matchScores.filter(
  (match) => match.alliances[0].totalPoints > 0
);

Anti-Patterns

• ❌ Hardcoding credentials in source code
• ❌ Not handling API errors (always check response.ok)
• ❌ Fetching all events when you only need one (use eventCode filter)
• ❌ Ignoring rate limits (add delays between bulk requests)

Common Errors

"FTC API credentials not configured"

Ensure FTC_API_USERNAME and FTC_API_TOKEN are set in your .env file.

401 Unauthorized

Credentials are invalid. Verify at https://ftc-events.firstinspires.org/services/API

404 Not Found

Event code doesn't exist or season is wrong. Current season is 2025 (DECODE).

Current Season

The API client is configured for the 2025 DECODE season:

const CURRENT_SEASON = 2025;

References

• FTC Events API Documentation
• Register for API Access
• API Implementation