API & MCP

Everything Flagline shows is available to your scripts and to AI assistants: a read-only JSON API and a remote MCP server that Claude, ChatGPT, Cursor and other assistants can connect to. No sign-up needed. Please read the terms of use.

Connect your AI assistant

Point any MCP client at https://flagline.co.za/mcp (Streamable HTTP, no login). Then ask things like “How did Milnerton do at the last Rescue Sport Series?”

claude mcp add --transport http flagline https://flagline.co.za/mcp

Settings → Connectors → Add custom connector
Name: Flagline
URL:  https://flagline.co.za/mcp

{
  "mcpServers": {
    "flagline": { "url": "https://flagline.co.za/mcp" }
  }
}

Connectors (developer mode) → Create → MCP server URL: https://flagline.co.za/mcp
Custom GPT action: import https://flagline.co.za/api/v1/openapi.json

npx -y mcp-remote https://flagline.co.za/mcp

Quickstart (REST)

JSON over HTTPS, GET only. Find a slug with search, then fetch the thing itself.

curl "https://flagline.co.za/api/v1/search?q=milnerton"

curl "https://flagline.co.za/api/v1/clubs/milnerton?season=2025-26"

curl "https://flagline.co.za/api/v1/competitions?status=results&region=WC&pageSize=10"

Every response is { data, page?, meta }. meta.url is the matching Flagline page and meta.attribution is the credit line to show: “Data: Flagline (flagline.co.za), sourced from LiveHeats”. The full schema is in the OpenAPI document.

Endpoints and tools

• GET /api/v1/search · tool search
  Search athletes, clubs and competitions by name.
• GET /api/v1/athletes/{slug} · tool get_athlete
  An athlete's profile: club, career stats, form by discipline, season stats.
• GET /api/v1/athletes/{slug}/results · tool get_athlete_results
  An athlete's results, by competition, newest first.
• GET /api/v1/athletes/{slug}/head-to-head/{other} · tool get_head_to_head
  Head-to-head record between two athletes.
• GET /api/v1/clubs/{slug} · tool get_club
  A club's profile with its season summary and season-by-season trend.
• GET /api/v1/clubs/{slug}/roster · tool get_club_roster
  Athletes who raced for a club in a season.
• GET /api/v1/clubs/{slug}/medals · tool get_club_medals
  A club's medals at each competition in a season.
• GET /api/v1/competitions · tool list_competitions
  Competitions: upcoming (soonest first) and/or with results (newest first).
• GET /api/v1/competitions/{slug} · tool get_competition
  A competition with its club table (ranked by points).
• GET /api/v1/competitions/{slug}/divisions · tool list_divisions
  A competition's divisions with each winner.
• GET /api/v1/competitions/{slug}/divisions/{division}/results · tool get_division_results
  Heat-by-heat results of one division.
• GET /api/v1/pointscore · tool get_pointscore
  Season club pointscore by region and series.
• GET /api/v1/rankings · tool get_rankings
  Athlete rankings by Flagline Rating for one discipline group, age group and gender.
• GET /api/v1/records · tool get_records
  National and provincial records: most titles, most medals in a season, longest finals streak, most competitions, most heats.
• GET /api/v1/series/{slug} · tool get_series
  A series: official athlete standings per division, club series table and rounds.
• GET /api/v1/venues/{slug} · tool get_venue
  A beach: competitions held there, top clubs and athletes, field sizes and disciplines.
• GET /api/v1/disciplines/{slug} · tool get_discipline
  One discipline across SA: field sizes by season, top clubs, most golds, strongest fields and championship winners.
• GET /api/v1/seasons · tool list_seasons
  Seasons with results.
• GET /api/v1/health · status and API version.

Juniors

Junior athletes appear exactly as on the site: first name and surname initial (“Sam J.”) with isLimited: true. Search finds them by first name, never by surname, and there is no endpoint that lists every athlete.

Limits and keys

• Anonymous: 60 API requests a minute and 30 MCP requests a minute per IP, with short bursts allowed.
• Over the limit you get 429 with Retry-After; every response carries RateLimit headers.
• Lists are paginated: page and pageSize (max 50).
• Responses carry an ETag; send If-None-Match to get a cheap 304.
• Need more? Email hello@flagline.co.za for a key and send it as Authorization: Bearer fl_….

Discovery

• OpenAPI 3.1 · API catalog · MCP server card