📖 OpenLiveTiming API Documentation

Overview

OpenLiveTiming provides a REST API and SignalR hub for streaming live motorsport timing data. You can push race data from your own timing application and have it displayed in real-time on your dedicated live timing page.

The platform is organized around a simple hierarchy:

Account (your organization)
  └─ Instance (a live timing feed, e.g. "adac-mx-masters")
       └─ API Key (grants push access to specific instances)

Authentication

The API supports two authentication methods for pushing data:

API Key (recommended for workers)

Use the X-Api-Key header with a key created from your account dashboard.

X-Api-Key: rm_a1b2c3d4e5f6...
JWT Bearer Token (for user-facing operations)

Obtain a token via POST /api/auth/login:

POST /api/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

// Response:
{
  "token": "eyJhbGciOi...",
  "email": "you@example.com",
  "displayName": "Your Name"
}

// Use in subsequent requests:
Authorization: Bearer eyJhbGciOi...

Quick Start

Step by step, with your own pages and keys when you are signed in: push your timing data with the API.

  1. Create your live timing at /create (or via the API).
  2. Create an API key from your account dashboard, scoped to your instance.
  3. Push a full state to initialize your timing page (see below).
  4. Push incremental events as the race progresses.
  5. View live at olt.live/lt/your-slug, or embed it on your website.

Pushing Race Data

Full State (complete snapshot)

Push a complete race state. This is the primary way to update your timing page. New viewers and reconnecting clients will receive this state immediately. The snapshot goes in a state object; a new groupName or runName starts a new session and archives the previous one as results.

POST /api/instances/{slug}/race/fullstate
X-Api-Key: your-api-key
Content-Type: application/json

{
  "state": {
    "session": {
      "trackName": "Circuit de Spa",
      "eventName": "Club Championship",
      "groupName": "Race 1",
      "runName": "Final",
      "runType": "Race",
      "flag": "Green",
      "timeToGo": "00:25:00",
      "laps": 5,
      "totalLaps": 20,
      "sectorCount": 3
    },
    "drivers": {
      "1": {
        "number": "1",
        "fullName": "Max Speed",
        "className": "Pro",
        "position": 1,
        "laps": 5,
        "lastTime": "1:45.123",
        "bestTime": "1:44.567",
        "sectorTimes": ["32.100", "38.200", "34.823"],
        "gap": "",
        "interval": ""
      },
      "44": {
        "number": "44",
        "fullName": "Lewis Quick",
        "className": "Pro",
        "position": 2,
        "laps": 5,
        "lastTime": "1:45.456",
        "bestTime": "1:44.890",
        "gap": "+0.323",
        "interval": "+0.323"
      }
    }
  }
}
  • Times: "1:44.567", "00:01:44.567" or a number of seconds (104.567).
  • Flags (flag): None, Green, Yellow, Red, Blue, White, Black, Checkered, SafetyCar, VirtualSafetyCar (the name or its number).
  • Run types (runType): Practice, Qualifying, Race, … (the name or its number).
  • Timestamp: optional ("timestamp" next to state, UTC); the time of arrival otherwise.
  • A session under the Checkered flag is archived 120 seconds after its last update.
Update Cache Only (no broadcast)

Use PUT instead of POST to update the cached state without broadcasting to connected viewers. Useful for high-frequency updates.

PUT /api/instances/{slug}/race/fullstate
X-Api-Key: your-api-key
Content-Type: application/json

{ "state": { ...same body... } }
Push Individual Events

Send individual race events for real-time updates (lap and best lap highlights, flag changes, the lap history of the results):

POST /api/instances/{slug}/race/event
X-Api-Key: your-api-key
Content-Type: application/json

{
  "$type": "LapCompleted",
  "driverNumber": "44",
  "driverName": "Lewis Quick",
  "lapNumber": 6,
  "lapTime": "1:44.567",
  "isPersonalBest": true,
  "isOverallBest": false,
  "position": 2
}
Push Batch Events
POST /api/instances/{slug}/race/events
X-Api-Key: your-api-key
Content-Type: application/json

[
  { "$type": "SectorCompleted", "driverNumber": "1", "driverName": "Max Speed", "sectorIndex": 0, "sectorTime": "31.900", "isPersonalBest": true, "isOverallBest": true },
  { "$type": "FlagChange", "oldFlag": "Green", "newFlag": "Yellow" }
]

Race Event Types

Events use a $type discriminator for polymorphic JSON serialization:

TypeDescription
SectorCompletedA driver completed a timing sector
LapCompletedA driver completed a lap
PositionChangeDriver classification position changed
BestLapNew session overall best lap time
BestSectorNew session overall best sector time
FlagChangeTrack flag status changed (Green, Yellow, Red, etc.)
SessionInfoUpdateSession metadata updated
FullStateComplete state snapshot
AnnouncementRace control announcement

Reading Live Data & Results

The read endpoints need no API key for a public page; a private page answers to its signed-in members only, a password-protected one after the password is accepted (403 otherwise).

EndpointDescription
GET /api/instances/{slug}/race/fullstateCurrent state of the session (404 before any data)
GET /api/instances/{slug}/race/events?since=Buffered events since a UTC timestamp (the last hour at most)
GET /api/instances/{slug}/race/history?limit=20Archived sessions, newest first (100 at most)
GET /api/instances/{slug}/race/history/{id}Final state of an archived session
GET /api/instances/{slug}/race/history/{id}/laps[/{number}]Lap and sector breakdown of an archived session (all drivers, or one)

Every archived session of a public page also has a results page for people: https://openlivetiming.com/lt/your-slug/results.

Real-Time via SignalR

For consuming live data in real-time, connect to the SignalR hub:

// JavaScript example
const connection = new signalR.HubConnectionBuilder()
    .withUrl("/racehub?instance=your-slug")
    .build();

// Request the current state
await connection.start();
await connection.invoke("RequestFullState");

// Listen for events
connection.on("ReceiveFullState", (state) => {
    console.log("Full state:", state);
});

connection.on("ReceiveRaceEvent", (event) => {
    console.log("Event:", event);
});

connection.on("ReceiveBatchEvents", (events) => {
    console.log("Batch:", events);
});
Hub Methods
MethodDirectionDescription
RequestFullState()Client → ServerRequest cached full state
ReceiveFullStateServer → ClientComplete race snapshot
ReceiveRaceEventServer → ClientSingle race event
ReceiveBatchEventsServer → ClientBatch of race events

Public Directory

The public live timing pages (those of /live, plus the collaborative sessions of the LapViz apps not marked private), for apps. Anonymous, 60 requests per minute per IP.

GET https://openlivetiming.com/api/directory?status=live&circuits=zolder,genk&limit=50
ParameterDescription
statuslive (data in the last 10 minutes), upcoming (scheduled session in the next 60 days) or recent (data in the last 30 days), several separated by commas; all when omitted
circuitsLapViz circuit codes separated by commas, case-insensitive (e.g. zolder); only the pages of these circuits
limitMaximum number of entries: 50 by default, 200 at most
includeDemosfalse to exclude the demo pages (isDemo: true); included by default

Live pages come first (most recent activity first), then upcoming (soonest first), then recent; within each status, the real pages come before the demo pages. Track, session, flag and viewers are only given for the live pages.

{
  "generatedAtUtc": "2026-10-19T12:00:00Z",
  "entries": [ {
    "slug": "spa-endurance", "title": "Spa 24h club race", "status": "live",
    "circuitCode": "spakarting", "trackName": "Spa-Francorchamps", "sessionName": "Race 1",
    "flag": "green", "viewerCount": 12, "lastActivityUtc": "2026-10-19T11:59:00Z", "startsAtUtc": null,
    "url": "https://olt.live/lt/spa-endurance",
    "eventName": "Club endurance", "accountName": "Karting Club", "isCollaborative": false, "isDemo": false
  } ]
}

Add ?app=1 to a page shown in a native app's WebView: no site header, footer, push notification or screen wake lock, links to other sites open in the same window.

OpenAPI Specification

The complete OpenAPI specification, with every request and response schema, is served at /openapi/v1.json; in production it is restricted to the platform administrators. The sections above cover the endpoints open to integrations.

Questions? Reach out at info@openlivetiming.com

An unhandled error has occurred. Reload 🗙