API Reference

The RaceHooks API is a REST API returning JSON. All requests are authenticated via Bearer token and versioned under /v1. The API is sport-agnostic at the infrastructure level — feeds, webhooks, and simulate endpoints will serve all supported sports as the platform expands beyond F1.

curl -X POST https://api.racehooks.io/v1/oauth \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":     "your_client_id",
    "client_secret": "your_client_secret"
  }'

# Response
{
  "token":     "eyJhbGc...",
  "expiresAt": "2026-06-07T12:00:00Z"
}

# All subsequent requests:
curl https://api.racehooks.io/v1/webhooks \
  -H "Authorization: Bearer eyJhbGc..."

curl -X POST https://api.racehooks.io/v1/webhooks \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.com/f1",
    "feedId": "timingdata",
    "filters": {
      "driverNumbers": ["1", "4", "16"]
    }
  }'

# Response
{
  "data": {
    "webhooks": [
      {
        "webhookId": "wh_7a3b9c2d",
        "webhookUrl": "https://your-app.com/f1",
        "feedId": "timingdata",
        "active": true,
        "createdAt": "2026-06-01T12:00:00Z"
      }
    ]
  }
}

# GET /v1/webhooks/:id/logs?limit=50
{
  "data": {
    "logs": [
      {
        "logId": "log_a1b2c3",
        "webhookId": "wh_7a3b9c2d",
        "statusCode": 200,
        "latencyMs": 142,
        "createdAt": "2026-06-01T14:22:31Z",
        "responseBody": "ok"
      }
    ]
  }
}

# GET /v1/feeds
{
  "data": {
    "feeds": [
      {
        "feedId": "timingdata",
        "name": "Timing Data",
        "tier": "live",
        "cadence": "per_lap",
        "description": "Per-driver lap times, sector times, gaps, and position data."
      },
      {
        "feedId": "racecontrolmessages",
        "name": "Race Control Messages",
        "tier": "live",
        "cadence": "per_event",
        "description": "Official race control messages: safety car, flags, penalties, and steward decisions."
      }
    ]
  }
}

# Start a simulation
curl -X POST https://api.racehooks.io/v1/simulate \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "2024-british-r1",
    "speed": "10x"
  }'

# Poll for status
curl https://api.racehooks.io/v1/simulate/sim_9f2c \
  -H "Authorization: Bearer ${TOKEN}"

# Response when complete
{
  "data": {
    "simulationId": "sim_9f2c",
    "status": "completed",
    "eventsDispatched": 48201,
    "deliveriesSent": 48201,
    "successRate": 0.998,
    "completedAt": "2026-06-01T14:35:00Z"
  }
}

# GET /v1/events
{
  "data": {
    "events": [
      {
        "eventId": "2026-british",
        "name": "British Grand Prix",
        "circuitName": "Silverstone",
        "round": 12,
        "sessions": [
          {
            "sessionId": "2026-british-q",
            "type": "Qualifying",
            "startDate": "2026-07-05T14:00:00Z",
            "status": "upcoming"
          },
          {
            "sessionId": "2026-british-r1",
            "type": "Race",
            "startDate": "2026-07-06T14:00:00Z",
            "status": "upcoming"
          }
        ]
      }
    ]
  }
}