Agent skill

ftc-events-api

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.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/ftc-events-api

Metadata

Additional technical details for this skill

author
ftcmetrics
version
1.0.0
category
api

SKILL.md

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:
    bash
    FTC_API_USERNAME=your_username
    FTC_API_TOKEN=your_token
    

Basic Usage

typescript
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

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

FTCMatchScore

typescript
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:

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

Common Patterns

Fetch Event with All Data

typescript
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

typescript
// 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:

typescript
const CURRENT_SEASON = 2025;

References

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results