Developer Documentation

Racey Public API v1

Build integrations, overlays, bots, and analytics tools with programmatic access to Racey league data. REST API v1 is currently read-only and secured by API key authentication.

Get Your API Key

API Key Auth

Authenticate with Bearer tokens. Create and manage keys from your settings.

Rate Limits

200 read requests/min per API key.

Scoped Access

Restrict keys by scope and optionally limit to specific leagues. An unrestricted key (no league filter) may read any league the key owner can access; a league-restricted key may only read the specific leagues listed on the key and returns 403 LEAGUE_ACCESS_DENIED for any other league.

Authentication

All API requests must include your API key in the Authorization header as a Bearer token.

Getting an API Key

Sign in to your Racey account
Go to Settings → API Keys
Click “Create API Key” and give it a name
Copy the key immediately — it will only be shown once

Using Your Key

HTTP Header

Authorization: Bearer rk_live_example_redacted

Base URL & Response Format

Base URL

https://racey.gg/api/v1

All responses follow a consistent envelope format:

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

Paginated endpoints return an additional wrapper:

Paginated Response

{
  "success": true,
  "data": {
    "data": [ ... ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Rate Limits

Tier	Limit	Window
Read (GET)	200 requests	per minute

When rate limited, the API returns HTTP 429. Wait until the reset window before retrying.

Endpoints Reference

GET

/api/v1/leagues

List leagues accessible to the authenticated user. Supports search and filtering.

Parameters

Name	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)
search	string	Search by league name
status	string	Filter by status (draft, active, paused, archived)

Example Response

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "clx1abc...",
        "name": "Sunday Road Racing",
        "slug": "sunday-road-racing",
        "discipline": "road",
        "region": "na",
        "status": "active",
        "seasonCount": 3,
        "staffCount": 5
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

GET

/api/v1/leagues/:leagueId

Get detailed information about a specific league including its current season.

Example Response

{
  "success": true,
  "data": {
    "id": "clx1abc...",
    "name": "Sunday Road Racing",
    "slug": "sunday-road-racing",
    "description": "Weekly road racing league",
    "discipline": "road",
    "region": "na",
    "status": "active",
    "currentSeason": {
      "id": "clx2def...",
      "name": "Season 3",
      "status": "active"
    },
    "seasonCount": 3,
    "staffCount": 5
  }
}

GET

/api/v1/seasons/:seasonId

Get season details with the full rounds schedule.

Example Response

{
  "success": true,
  "data": {
    "id": "clx2def...",
    "name": "Season 3",
    "status": "active",
    "league": { "id": "clx1abc...", "name": "Sunday Road Racing" },
    "rounds": [
      {
        "id": "clx3ghi...",
        "roundNumber": 1,
        "name": "Daytona Road Course",
        "trackName": "Daytona International Speedway",
        "status": "completed"
      }
    ],
    "registrationCount": 24,
    "standingsCount": 24
  }
}

GET

/api/v1/standings/:seasonId

Full championship standings for a season.

Parameters

Name	Type	Description
carClassId	string	Filter by car class (optional)

Example Response

{
  "success": true,
  "data": {
    "season": { "id": "clx2def...", "name": "Season 3", "status": "active" },
    "standings": [
      {
        "position": 1,
        "userId": "clx4jkl...",
        "driverName": "Casey Brooks",
        "totalPoints": 245,
        "wins": 3,
        "podiums": 7,
        "dnfs": 0
      }
    ]
  }
}

GET

/api/v1/results/:roundId

Race results for all sessions in a round, including points breakdown.

Example Response

{
  "success": true,
  "data": {
    "round": {
      "id": "clx3ghi...",
      "roundNumber": 1,
      "name": "Daytona Road Course",
      "status": "completed"
    },
    "sessions": [
      {
        "sessionId": "clx5mno...",
        "type": "race",
        "results": [
          {
            "position": 1,
            "driverName": "Casey Brooks",
            "startPosition": 3,
            "lapsCompleted": 45,
            "finishStatus": "running",
            "gap": null,
            "points": {
              "position": 25,
              "bonus": { "fastestLap": 1 },
              "penalty": 0,
              "total": 26
            }
          }
        ]
      }
    ]
  }
}

GET

/api/v1/drivers/:userId

Driver profile with career statistics across all seasons.

Example Response

{
  "success": true,
  "data": {
    "id": "clx4jkl...",
    "displayName": "Casey Brooks",
    "avatar": null,
    "preferredNumber": 42,
    "careerStats": {
      "seasonsRaced": 5,
      "totalWins": 12,
      "totalPodiums": 28,
      "championships": 2,
      "totalPoints": 1250.5
    },
    "simProfiles": [
      { "platform": "iracing", "iRating": 3200, "safetyRating": 4.5 }
    ]
  }
}

Code Examples

curl

Fetch league standings

curl -H "Authorization: Bearer rk_live_YOUR_KEY_HERE" \
  "https://your-domain.com/api/v1/standings/SEASON_ID"

JavaScript / TypeScript

fetch example

const API_KEY = 'rk_live_YOUR_KEY_HERE';
const BASE_URL = 'https://your-domain.com/api/v1';

async function getStandings(seasonId: string) {
  const res = await fetch(`${BASE_URL}/standings/${seasonId}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
  });

  if (!res.ok) {
    throw new Error(`API error: ${res.status}`);
  }

  const json = await res.json();
  if (!json.success) {
    throw new Error(json.error);
  }

  return json.data;
}

// Usage
const data = await getStandings('clx2def...');
console.log(data.standings);

Python

requests example

import requests

API_KEY = "rk_live_YOUR_KEY_HERE"
BASE_URL = "https://your-domain.com/api/v1"

def get_standings(season_id: str):
    response = requests.get(
        f"{BASE_URL}/standings/{season_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    response.raise_for_status()
    data = response.json()
    if not data["success"]:
        raise Exception(data["error"])
    return data["data"]

# Usage
standings = get_standings("clx2def...")
for entry in standings["standings"]:
    print(f"{entry['position']}. {entry['driverName']} - {entry['totalPoints']} pts")

Error Codes

HTTP Status	Code	Description
401	UNAUTHORIZED	Missing or malformed Authorization header
401	INVALID_API_KEY	Invalid, expired, or revoked API key
403	INSUFFICIENT_SCOPE	API key lacks the required scope for this endpoint
403	LEAGUE_ACCESS_DENIED	API key restricted to specific leagues that don't include the requested league
404	NOT_FOUND	Requested resource does not exist
429	RATE_LIMITED	Too many requests; wait for the rate limit window to reset
500	INTERNAL_ERROR	Unexpected server error

Webhooks
Coming Soon

Webhooks let you receive real-time HTTP notifications when events happen in your leagues — results published, protests filed, standings updated, and more. Once shipped, you will configure webhook endpoints in your league settings.

Planned Webhook Events

Event	Description
result.published	Race results have been published for a round
standings.updated	Championship standings recalculated after a result or correction
protest.filed	A driver has filed a protest for a round
protest.decided	Stewards have issued a verdict on a protest
appeal.filed	A driver has appealed a stewarding decision
appeal.decided	An appeal panel has issued its final verdict
registration.approved	A driver registration request has been approved
round.scheduled	A new round has been added to a season schedule

Payload Shape

Each webhook delivery is an HTTP POST with a JSON body in this format:

Webhook payload

{
  "event": "result.published",
  "leagueId": "clx1abc...",
  "roundId": "clx2def...",
  "timestamp": "2026-04-10T14:30:00Z",
  "data": { ... }  // event-specific payload
}

Deliveries will include an X-Racey-Signature header (HMAC-SHA256 of the raw body using your webhook secret) so you can verify authenticity.

Ready to Build?

Create an API key and start building integrations in minutes.

Create API Key Browse Leagues

Racey Public API v1

Authentication

Getting an API Key

Using Your Key

Base URL & Response Format

Rate Limits

Endpoints Reference

Parameters

Example Response

Example Response

Example Response

Parameters

Example Response

Example Response

Example Response

Code Examples

curl

JavaScript / TypeScript

Python

Error Codes

Webhooks Coming Soon

Planned Webhook Events

Payload Shape

Ready to Build?

Webhooks
Coming Soon