{
  "openapi": "3.1.0",
  "info": {
    "title": "Project CARS UDP Telemetry API",
    "version": "1.0.0",
    "description": "Local API for decoded Project CARS UDP telemetry. The game sends binary UDP packets; this app decodes them into JSON, serves current state snapshots, exposes a server-sent events stream, and calculates a race overview leaderboard."
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "Default local development server"
    }
  ],
  "tags": [
    {
      "name": "State",
      "description": "Decoded packet state snapshots"
    },
    {
      "name": "Leaderboard",
      "description": "Server-calculated race overview"
    },
    {
      "name": "Events",
      "description": "Live telemetry stream. The current server implementation uses Server-Sent Events at /events; it does not expose a WebSocket upgrade endpoint."
    },
    {
      "name": "Ingest",
      "description": "Telemetry frame ingestion"
    },
    {
      "name": "Pages",
      "description": "Static browser pages served by the local app"
    },
    {
      "name": "Schemas",
      "description": "Reusable JSON schemas"
    }
  ],
  "x-websocket-routes": [],
  "x-streaming-routes": [
    {
      "protocol": "sse",
      "path": "/events",
      "events": ["state", "packet", "leaderboard"]
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["Pages"],
        "summary": "Open packet viewer page",
        "description": "Serves the main packet inspection UI from public/index.html.",
        "operationId": "getPacketViewerPage",
        "responses": {
          "200": {
            "description": "HTML packet viewer page",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/overview.html": {
      "get": {
        "tags": ["Pages"],
        "summary": "Open race overview page",
        "description": "Serves the leaderboard/race overview UI.",
        "operationId": "getOverviewPage",
        "responses": {
          "200": {
            "description": "HTML race overview page",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/swagger.html": {
      "get": {
        "tags": ["Pages"],
        "summary": "Open Swagger documentation page",
        "description": "Serves the browser documentation UI for this OpenAPI document.",
        "operationId": "getSwaggerPage",
        "responses": {
          "200": {
            "description": "HTML Swagger page",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/api/state": {
      "get": {
        "tags": ["State"],
        "summary": "Get latest decoded UDP packet state",
        "description": "Returns the latest merged packet by UDP packet type plus the most recent parsed packets, newest first.",
        "operationId": "getState",
        "responses": {
          "200": {
            "description": "Current decoded packet state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "/schemas/udp-packets.schema.json"
                }
              }
            }
          }
        }
      }
    },
    "/api/leaderboard": {
      "get": {
        "tags": ["Leaderboard"],
        "summary": "Get calculated leaderboard overview",
        "description": "Returns participant rows merged from UDP packets, including timing, status, nationality override, car name, lap splits, sector splits, pit state, and decoded race flag data.",
        "operationId": "getLeaderboard",
        "responses": {
          "200": {
            "description": "Current leaderboard overview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "/schemas/udp-packets.schema.json#/$defs/leaderboard"
                }
              }
            }
          }
        }
      }
    },
    "/api/ingest/shared-memory": {
      "post": {
        "tags": ["Ingest"],
        "summary": "Ingest shared-memory bridge packets",
        "description": "Receives packet-like JSON frames from scripts/shared_memory_bridge.py and merges them into the same state used by the UDP parser and leaderboard.",
        "operationId": "ingestSharedMemory",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "/schemas/udp-packets.schema.json#/$defs/sharedMemoryIngestRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Frame accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "/schemas/udp-packets.schema.json#/$defs/ingestAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Invalid frame",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "/schemas/udp-packets.schema.json#/$defs/errorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/events": {
      "get": {
        "tags": ["Events"],
        "summary": "Open live telemetry SSE stream",
        "description": "Server-Sent Events stream. This is the app's live route; there is no WebSocket upgrade route in the current server. On connection it sends a `state` event. For each parsed UDP packet it sends a `packet` event containing the packet, state and leaderboard, followed by a `leaderboard` event containing just the leaderboard.",
        "operationId": "streamEvents",
        "x-streaming-protocol": "sse",
        "x-sse-events": {
          "state": {
            "schema": {
              "$ref": "/schemas/udp-packets.schema.json#/$defs/stateEvent"
            },
            "example": {
              "latest": {
                "3": {
                  "receivedAt": "2026-05-18T06:31:12.812Z",
                  "source": "192.168.1.55:5606",
                  "base": {
                    "packetNumber": 1210,
                    "categoryPacketNumber": 309,
                    "partialPacketIndex": 0,
                    "partialPacketNumber": 1,
                    "packetType": 3,
                    "packetVersion": 1
                  },
                  "name": "Timings",
                  "size": 1064,
                  "data": {
                    "numParticipants": 2,
                    "eventTimeRemaining": 1275.442,
                    "participants": [
                      {
                        "slot": 0,
                        "racePosition": 1,
                        "active": true,
                        "currentLap": 5,
                        "currentTime": 402.733,
                        "mpParticipantIndex": 1001
                      }
                    ]
                  }
                }
              },
              "recent": [],
              "leaderboard": {
                "rows": [
                  {
                    "id": 1001,
                    "slot": 0,
                    "position": 1,
                    "status": {
                      "code": "racing",
                      "label": "Racing",
                      "tone": "good"
                    },
                    "driver": "Alex Taylor",
                    "lap": 5,
                    "currentTime": 402.733
                  }
                ],
                "note": "1 participant merged from UDP packets",
                "session": {
                  "trackName": "Bathurst - Mount Panorama",
                  "sessionType": "Race",
                  "timeLeft": 1275.442,
                  "weather": "22 C air / 31 C track / rain 0",
                  "lastUpdate": "2026-05-18T06:31:12.812Z"
                }
              }
            }
          },
          "packet": {
            "schema": {
              "$ref": "/schemas/udp-packets.schema.json#/$defs/packetEvent"
            },
            "example": {
              "packet": {
                "receivedAt": "2026-05-18T06:31:13.020Z",
                "source": "192.168.1.55:5606",
                "base": {
                  "packetNumber": 1211,
                  "categoryPacketNumber": 310,
                  "partialPacketIndex": 0,
                  "partialPacketNumber": 1,
                  "packetType": 3,
                  "packetVersion": 1
                },
                "name": "Timings",
                "size": 1064,
                "data": {
                  "numParticipants": 2,
                  "eventTimeRemaining": 1274.991,
                  "participants": [
                    {
                      "slot": 0,
                      "racePosition": 1,
                      "active": true,
                      "sector": 2,
                      "currentLap": 5,
                      "currentTime": 403.184,
                      "currentSectorTime": 32.333,
                      "mpParticipantIndex": 1001
                    }
                  ]
                }
              },
              "state": {
                "latest": {},
                "recent": []
              },
              "leaderboard": {
                "rows": [],
                "note": "Waiting for participant or timing packets",
                "session": {
                  "trackName": "-",
                  "sessionType": "-",
                  "weather": "-"
                }
              }
            }
          },
          "leaderboard": {
            "schema": {
              "$ref": "/schemas/udp-packets.schema.json#/$defs/leaderboard"
            },
            "example": {
              "rows": [
                {
                  "id": 1001,
                  "slot": 0,
                  "sortPosition": 1,
                  "position": 1,
                  "active": true,
                  "status": {
                    "code": "racing",
                    "label": "Racing",
                    "tone": "good"
                  },
                  "driver": "Alex Taylor",
                  "nationality": {
                    "code": "GBR",
                    "country": "United Kingdom",
                    "source": "udp"
                  },
                  "vehicle": "Formula A",
                  "lap": 5,
                  "sector": 2,
                  "currentTime": 403.184,
                  "lastLapTime": 83.214,
                  "fastestLapTime": 82.901
                }
              ],
              "note": "1 participant merged from UDP packets",
              "session": {
                "trackName": "Bathurst - Mount Panorama",
                "sessionType": "Race",
                "timeLeft": 1274.991,
                "weather": "22 C air / 31 C track / rain 0",
                "lastUpdate": "2026-05-18T06:31:13.020Z"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SSE stream of telemetry updates",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-Sent Events stream. Event names currently include `state`, `packet`, and `leaderboard`; payload schemas are documented in `x-sse-events`."
                },
                "examples": {
                  "state": {
                    "summary": "State event after timing and participant packets",
                    "value": "event: state\ndata: {\"latest\":{\"2\":{\"receivedAt\":\"2026-05-18T06:31:12.420Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1201,\"categoryPacketNumber\":42,\"partialPacketIndex\":1,\"partialPacketNumber\":2,\"packetType\":2,\"packetVersion\":1},\"name\":\"Participants\",\"size\":1136,\"data\":{\"participantsChangedTimestamp\":88342,\"participants\":[{\"slot\":0,\"localSlot\":0,\"partialPacketIndex\":1,\"name\":\"Alex Taylor\",\"nationality\":85,\"index\":1001},{\"slot\":1,\"localSlot\":1,\"partialPacketIndex\":1,\"name\":\"Sam Rivera\",\"nationality\":226,\"index\":1002}]}},\"3\":{\"receivedAt\":\"2026-05-18T06:31:12.812Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1210,\"categoryPacketNumber\":309,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"participantsChangedTimestamp\":88342,\"eventTimeRemaining\":1275.442,\"splitTimeAhead\":0,\"splitTimeBehind\":1.248,\"splitTime\":1.248,\"localParticipantIndex\":0,\"participants\":[{\"slot\":0,\"worldPosition\":[124,0,842],\"orientation\":[0,1024,0],\"currentLapDistance\":2840,\"racePosition\":1,\"active\":true,\"sector\":2,\"sectorRaw\":2,\"sectorExtraPrecision\":0,\"highestFlag\":0,\"pitModeSchedule\":0,\"carIndex\":45,\"raceState\":2,\"currentLap\":5,\"currentTime\":402.733,\"currentSectorTime\":31.882,\"mpParticipantIndex\":1001},{\"slot\":1,\"worldPosition\":[118,0,806],\"orientation\":[0,1008,0],\"currentLapDistance\":2790,\"racePosition\":2,\"active\":true,\"sector\":2,\"sectorRaw\":2,\"sectorExtraPrecision\":0,\"highestFlag\":2,\"pitModeSchedule\":0,\"carIndex\":47,\"raceState\":2,\"currentLap\":5,\"currentTime\":403.981,\"currentSectorTime\":33.130,\"mpParticipantIndex\":1002}]}}},\"recent\":[{\"receivedAt\":\"2026-05-18T06:31:12.812Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1210,\"categoryPacketNumber\":309,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"eventTimeRemaining\":1275.442,\"participants\":[]}}],\"leaderboard\":{\"rows\":[{\"id\":1001,\"slot\":0,\"sortPosition\":1,\"position\":1,\"active\":true,\"status\":{\"code\":\"racing\",\"label\":\"Racing\",\"tone\":\"good\"},\"driver\":\"Alex Taylor\",\"nationality\":{\"code\":\"GBR\",\"country\":\"United Kingdom\",\"source\":\"udp\"},\"vehicle\":\"Formula A\",\"vehicleShortName\":\"FORM\",\"lap\":5,\"sector\":2,\"currentTime\":402.733,\"currentSectorTime\":31.882,\"lastLapTime\":83.214,\"fastestLapTime\":82.901,\"pitModeSchedule\":0,\"highestFlag\":0,\"raceState\":2,\"raceStateCode\":2,\"invalidatedLap\":false,\"carIndex\":45},{\"id\":1002,\"slot\":1,\"sortPosition\":2,\"position\":2,\"active\":true,\"status\":{\"code\":\"blue_flag\",\"label\":\"Blue flag\",\"tone\":\"warn\"},\"driver\":\"Sam Rivera\",\"nationality\":{\"code\":\"USA\",\"country\":\"United States\",\"source\":\"udp\"},\"vehicle\":\"Formula A\",\"vehicleShortName\":\"FORM\",\"lap\":5,\"sector\":2,\"currentTime\":403.981,\"currentSectorTime\":33.13,\"lastLapTime\":84.012,\"fastestLapTime\":83.441,\"pitModeSchedule\":0,\"highestFlag\":2,\"flag\":{\"raw\":2,\"colour\":2,\"reason\":0,\"observed\":\"blue\"},\"raceState\":2,\"raceStateCode\":2,\"invalidatedLap\":false,\"carIndex\":47}],\"note\":\"2 participants merged from UDP packets\",\"session\":{\"trackName\":\"Bathurst - Mount Panorama\",\"sessionType\":\"Race\",\"timeLeft\":1275.442,\"weather\":\"22 C air / 31 C track / rain 0\",\"lastUpdate\":\"2026-05-18T06:31:12.812Z\"}}}\n\n"
                  },
                  "packet": {
                    "summary": "Packet event with state and leaderboard",
                    "value": "event: packet\ndata: {\"packet\":{\"receivedAt\":\"2026-05-18T06:31:13.020Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1211,\"categoryPacketNumber\":310,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"participantsChangedTimestamp\":88342,\"eventTimeRemaining\":1274.991,\"splitTimeAhead\":0,\"splitTimeBehind\":1.192,\"splitTime\":1.192,\"localParticipantIndex\":0,\"participants\":[{\"slot\":0,\"worldPosition\":[128,0,851],\"orientation\":[0,1026,0],\"currentLapDistance\":2875,\"racePosition\":1,\"active\":true,\"sector\":2,\"sectorRaw\":2,\"sectorExtraPrecision\":0,\"highestFlag\":0,\"pitModeSchedule\":0,\"carIndex\":45,\"raceState\":2,\"currentLap\":5,\"currentTime\":403.184,\"currentSectorTime\":32.333,\"mpParticipantIndex\":1001}] }},\"state\":{\"latest\":{\"3\":{\"receivedAt\":\"2026-05-18T06:31:13.020Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1211,\"categoryPacketNumber\":310,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"eventTimeRemaining\":1274.991,\"participants\":[]}}},\"recent\":[{\"receivedAt\":\"2026-05-18T06:31:13.020Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1211,\"categoryPacketNumber\":310,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"eventTimeRemaining\":1274.991,\"participants\":[]}}]},\"leaderboard\":{\"rows\":[{\"id\":1001,\"slot\":0,\"sortPosition\":1,\"position\":1,\"active\":true,\"status\":{\"code\":\"racing\",\"label\":\"Racing\",\"tone\":\"good\"},\"driver\":\"Alex Taylor\",\"lap\":5,\"sector\":2,\"currentTime\":403.184,\"currentSectorTime\":32.333}],\"note\":\"1 participant merged from UDP packets\",\"session\":{\"trackName\":\"Bathurst - Mount Panorama\",\"sessionType\":\"Race\",\"timeLeft\":1274.991,\"weather\":\"22 C air / 31 C track / rain 0\",\"lastUpdate\":\"2026-05-18T06:31:13.020Z\"}}}\n\n"
                  },
                  "leaderboard": {
                    "summary": "Leaderboard update event",
                    "value": "event: leaderboard\ndata: {\"rows\":[{\"id\":1001,\"slot\":0,\"sortPosition\":1,\"position\":1,\"active\":true,\"status\":{\"code\":\"racing\",\"label\":\"Racing\",\"tone\":\"good\"},\"driver\":\"Alex Taylor\",\"nationality\":{\"code\":\"GBR\",\"country\":\"United Kingdom\",\"source\":\"udp\"},\"vehicle\":\"Formula A\",\"vehicleShortName\":\"FORM\",\"lap\":5,\"sector\":2,\"currentTime\":403.184,\"currentSectorTime\":32.333,\"checkpointSplit\":{\"source\":\"checkpoint\",\"basis\":\"raceOrder\",\"checkpoint\":\"L5 S2\",\"time\":403.184,\"delta\":0},\"lastLapTime\":83.214,\"latestLapSplit\":null,\"fastestLapTime\":82.901,\"bestLapSplit\":null,\"fastestSectors\":[27.101,28.334,27.466],\"pitModeSchedule\":0,\"pit\":{\"raw\":0,\"pitMode\":0,\"pitSchedule\":0},\"highestFlag\":0,\"flag\":{\"raw\":0,\"colour\":0,\"reason\":0},\"raceState\":2,\"raceStateCode\":2,\"invalidatedLap\":false,\"carIndex\":45},{\"id\":1002,\"slot\":1,\"sortPosition\":2,\"position\":2,\"active\":true,\"status\":{\"code\":\"blue_flag\",\"label\":\"Blue flag\",\"tone\":\"warn\"},\"driver\":\"Sam Rivera\",\"nationality\":{\"code\":\"USA\",\"country\":\"United States\",\"source\":\"udp\"},\"vehicle\":\"Formula A\",\"vehicleShortName\":\"FORM\",\"lap\":5,\"sector\":2,\"currentTime\":404.376,\"currentSectorTime\":33.525,\"checkpointSplit\":{\"source\":\"checkpoint\",\"basis\":\"raceOrder\",\"checkpoint\":\"L5 S2\",\"comparedTo\":\"P1\",\"time\":404.376,\"delta\":1.192},\"lastLapTime\":84.012,\"latestLapSplit\":{\"comparedTo\":\"P1\",\"time\":84.012,\"referenceTime\":83.214,\"delta\":0.798},\"fastestLapTime\":83.441,\"bestLapSplit\":{\"comparedTo\":\"P1\",\"time\":83.441,\"referenceTime\":82.901,\"delta\":0.54},\"fastestSectors\":[27.488,28.619,27.334],\"pitModeSchedule\":0,\"pit\":{\"raw\":0,\"pitMode\":0,\"pitSchedule\":0},\"highestFlag\":2,\"flag\":{\"raw\":2,\"colour\":2,\"reason\":0,\"observed\":\"blue\"},\"raceState\":2,\"raceStateCode\":2,\"invalidatedLap\":false,\"carIndex\":47}],\"note\":\"2 participants merged from UDP packets\",\"session\":{\"trackName\":\"Bathurst - Mount Panorama\",\"sessionType\":\"Race\",\"timeLeft\":1274.991,\"weather\":\"22 C air / 31 C track / rain 0\",\"lastUpdate\":\"2026-05-18T06:31:13.020Z\"}}\n\n"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": ["Schemas"],
        "summary": "Get this OpenAPI document from the static public route",
        "operationId": "getOpenApiSpec",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/openapi.json": {
      "get": {
        "tags": ["Schemas"],
        "summary": "Get this OpenAPI document from the API alias",
        "description": "Serves the same public/openapi.json document as /openapi.json.",
        "operationId": "getOpenApiSpecApiAlias",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/schemas/udp-packets.schema.json": {
      "get": {
        "tags": ["Schemas"],
        "summary": "Get decoded UDP packet JSON Schema",
        "description": "JSON Schema used by the OpenAPI document for decoded packet state and leaderboard responses.",
        "operationId": "getUdpPacketSchema",
        "responses": {
          "200": {
            "description": "JSON Schema for decoded UDP packets",
            "content": {
              "application/schema+json": {
                "schema": {
                  "$ref": "/schemas/udp-packets.schema.json"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "/schemas/udp-packets.schema.json"
                }
              }
            }
          }
        }
      }
    }
  }
}