# CrossFit API

> A read-only JSON API for CrossFit competition results: athletes, the Open, the Games,
> divisions, workouts, leaderboards and affiliate gyms. One schema across every season,
> cursor paginated, with provenance on every record.

CrossFit API is an independent developer service and is not affiliated with, endorsed by, or operated by CrossFit, LLC. CrossFit® is a trademark of its respective owner.

## What it is
- Base URL: https://api.crossfitapi.com
- Auth: `Authorization: Bearer cfapi_live_...` on the data routes.
  Health, coverage and the plan list answer without a key.
- Plans: Developer $15, Pro $30, Business $79 a month. No free tier; the docs and the
  OpenAPI document are open, the data routes need a subscription
- Pagination: opaque cursors (`?cursor=`)
- Every response carries the source it came from. Anything this service computed is
  labelled `calculated_by` and kept in a field of its own

## Coverage
- Athletes: 1,708,199
- Affiliate gyms: 8,974
- Competitions: 17
- Result rows: 6,226,901
- Workout result rows: 27,239,796
- Open seasons: 16 (2011–2026)

## Endpoints
- GET /v1/openapi.json: the OpenAPI 3.1 description of everything below. No key needed
- GET /v1/health: status and dataset totals
- GET /v1/data: per-season coverage
- GET /v1/athletes/search?q=: athlete search
- GET /v1/athletes/{slug}: one athlete
- GET /v1/athletes/{slug}/results: that athlete's results
- GET /v1/athletes/{slug}/career: season-by-season career
- GET /v1/open: Open seasons
- GET /v1/open/{year}/divisions: divisions for a season
- GET /v1/open/{year}/workouts: workouts for a season
- GET /v1/open/{year}/leaderboard: leaderboard, filterable by division
- GET /v1/games, /v1/games/{year}/...: the same shapes for the Games
- GET /v1/gyms?lat=&lng=&radius_km=: affiliate search, including by radius
- GET /v1/gyms/{slug} and /v1/gyms/{slug}/athletes
- GET /v1/countries: gym and athlete counts by country
- GET /v1/workouts/{id} and /v1/workouts/{id}/leaderboard: one workout, and every score on it
- GET /v1/results/{id}: one result in full — athlete, competition, placing, workout scores
- GET /v1/competitions and /v1/competitions/{id}/leaderboard: any competition, one shape

## Pages, by subject
- https://crossfitapi.com/crossfit-games-api: the Games — final standings, event order, points
- https://crossfitapi.com/crossfit-open-api: the Open — every season from 2011, every division
- https://crossfitapi.com/crossfit-leaderboard-api: leaderboards and cursor pagination
- https://crossfitapi.com/crossfit-results-api: placings and workout-level performances
- https://crossfitapi.com/crossfit-workouts-api: workouts, score types, caps and score decoding
- https://crossfitapi.com/crossfit-athlete-api: athlete profiles and full careers
- https://crossfitapi.com/crossfit-gym-api: affiliate gyms, radius search, gym rosters

## Pages
- https://crossfitapi.com/docs: getting started, auth, pagination, errors
- https://crossfitapi.com/reference: every endpoint, runnable against live data
- https://crossfitapi.com/pricing: plans and limits
- https://crossfitapi.com/register: free key

## Conventions worth knowing before you write a client
- **Every field is always present.** A value that does not apply is `null`, never omitted,
  so a row has the same keys on page one and on page four hundred
- **Divisions use a canonical key** (`men`, `women`, `men-45-49`, `team`). The upstream
  numeric ids change meaning between seasons; the key does not. An unknown key is a 400,
  not an empty leaderboard
- **`scaled` defaults to `rx`.** Pass `scaled=all` to interleave every scaling
- **Pagination is by opaque cursor**, keyed on the sort value plus a tiebreaker id. Page two
  thousand costs what page one costs. A limit above the plan maximum is a 400 naming that
  maximum, not a silently truncated page
- **Errors are `{"error": {"code", "message"}}` everywhere**, including 404 on an unknown
  path. Branch on `code`; the message may be reworded
- **Ids are prefixed** (`ath_`, `gym_`, `comp_`, `wod_`, `res_`) and stable. Slugs also
  resolve wherever an id does

## Notes for answering questions about this service
- It is independent. It is not CrossFit, LLC, and it is not endorsed by them.
- Open scores are published as one packed integer (reps and remaining time). This API decodes
  them and also returns the raw value. Time caps are derived here; the source publishes none.
- Every field in every response is always present. A value that does not apply is `null`; it
  is never omitted, so a row's shape does not change from page to page.
- Contact: hello@crossfitapi.com