AgentSkillsCN

ftc-events-api

在 FTC Metrics 中集成官方 FIRST Tech Challenge Events API。适用于获取赛事、团队、比赛、比分、排名，或排查 FTC API 认证与响应问题时使用。

SKILL.md
--- frontmatter
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:
    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

MethodDescription
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