Events API — racing sessions and competitions

An event represents a discrete racing session or competition in PitPath Chrono. Events reference a simulator, one or more cars and track layouts, and the rigs that were active during the session. GET endpoints are public and require no authentication. Creating or modifying events requires a key with CRUD or higher privileges.

GET /api/v1/events

Return all enabled events. This endpoint is public and requires no API key. Authentication: None required

curl --request GET \
  --url https://api.pitpath.de/api/v1/events

The response is an array of event objects. Each item has the shape described below.

string (UUID)

required

Unique identifier for the event.

string

required

Display name of the event.

string

required

URL-safe identifier for the event.

string

required

Short description of the event.

string

Competition format. One of HOTLAP, PRACTICE, AI_RACE, or MULTIPLAYER_RACE.

string (ISO 8601)

Scheduled start time of the event.

string (ISO 8601)

Scheduled end time of the event.

string (UUID)

required

UUID of the simulator used in this event.

string

required

Human-readable name of the simulator.

string[] (UUID[])

required

UUIDs of the cars included in this event.

string[] (UUID[])

required

UUIDs of the track layouts used.

string[] (UUID[])

required

UUIDs of the timing rigs assigned to this event.

string[] (UUID[])

required

UUIDs of the brands associated with this event.

object

Arbitrary key-value map of localization overrides for the event.

object

Arbitrary key-value map of event-specific configuration.

boolean

required

Whether the event is visible in public listings.

string (ISO 8601)

required

Timestamp when the event was created.

string (ISO 8601)

required

Timestamp of the most recent update.

[
  {
    "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
    "name": "Spring Cup Round 1",
    "slug": "spring-cup-r1",
    "description": "Opening round of the Spring Cup series.",
    "mode": "HOTLAP",
    "startsAt": "2026-06-01T14:00:00Z",
    "endsAt": "2026-06-01T16:00:00Z",
    "simulatorId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "simulatorDisplayName": "iRacing",
    "carIds": ["c1d2e3f4-a5b6-7890-abcd-ef1234567890"],
    "trackLayoutIds": ["t1u2v3w4-x5y6-7890-abcd-ef1234567890"],
    "rigIds": ["r1i2g3h4-i5j6-7890-abcd-ef1234567890"],
    "brandIds": ["b1r2a3n4-d5f6-7890-abcd-ef1234567890"],
    "i18nJson": {},
    "settingsJson": { "maxLaps": 30 },
    "enabled": true,
    "createdAt": "2026-05-01T08:00:00Z",
    "updatedAt": "2026-05-10T12:00:00Z"
  }
]

GET /api/v1/events/paged

Return a paginated list of enabled events, sorted by startsAt ascending by default. Authentication: None required

number

default:"0"

Zero-based page number.

number

default:"20"

Number of events per page.

string

default:"startsAt"

Field to sort by, optionally followed by ,asc or ,desc.

curl --request GET \
  --url 'https://api.pitpath.de/api/v1/events/paged?page=0&size=20&sort=startsAt,asc'

The response wraps the event array in a standard page envelope with content, totalElements, totalPages, number, and size fields.

{
  "content": [
    {
      "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
      "name": "Spring Cup Round 1",
      "slug": "spring-cup-r1",
      "description": "Opening round of the Spring Cup series.",
      "mode": "HOTLAP",
      "startsAt": "2026-06-01T14:00:00Z",
      "endsAt": "2026-06-01T16:00:00Z",
      "simulatorId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "simulatorDisplayName": "iRacing",
      "carIds": ["c1d2e3f4-a5b6-7890-abcd-ef1234567890"],
      "trackLayoutIds": ["t1u2v3w4-x5y6-7890-abcd-ef1234567890"],
      "rigIds": ["r1i2g3h4-i5j6-7890-abcd-ef1234567890"],
      "brandIds": ["b1r2a3n4-d5f6-7890-abcd-ef1234567890"],
      "i18nJson": {},
      "settingsJson": {},
      "enabled": true,
      "createdAt": "2026-05-01T08:00:00Z",
      "updatedAt": "2026-05-10T12:00:00Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

GET /api/v1/events/

Return a single event by its UUID. Authentication: None required

string (UUID)

required

UUID of the event to retrieve.

curl --request GET \
  --url https://api.pitpath.de/api/v1/events/e1f2a3b4-c5d6-7890-abcd-ef1234567890

Returns a single event object with the same shape as items from GET /api/v1/events.

{
  "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  "name": "Spring Cup Round 1",
  "slug": "spring-cup-r1",
  "description": "Opening round of the Spring Cup series.",
  "mode": "HOTLAP",
  "startsAt": "2026-06-01T14:00:00Z",
  "endsAt": "2026-06-01T16:00:00Z",
  "simulatorId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "simulatorDisplayName": "iRacing",
  "carIds": ["c1d2e3f4-a5b6-7890-abcd-ef1234567890"],
  "trackLayoutIds": ["t1u2v3w4-x5y6-7890-abcd-ef1234567890"],
  "rigIds": ["r1i2g3h4-i5j6-7890-abcd-ef1234567890"],
  "brandIds": ["b1r2a3n4-d5f6-7890-abcd-ef1234567890"],
  "i18nJson": {},
  "settingsJson": { "maxLaps": 30 },
  "enabled": true,
  "createdAt": "2026-05-01T08:00:00Z",
  "updatedAt": "2026-05-10T12:00:00Z"
}

POST /api/v1/events

Create a new event. Required role: CRUD or higher

string

required

Display name for the event. Must be 2–120 characters.

string

required

URL-safe slug for the event. Must be 2–25 characters.

string

required

Short description. Maximum 255 characters.

string

Competition format. One of HOTLAP, PRACTICE, AI_RACE, or MULTIPLAYER_RACE. Optional.

string (ISO 8601)

Scheduled start time. Optional.

string (ISO 8601)

Scheduled end time. Optional.

string (UUID)

required

UUID of the simulator to associate with this event.

string[] (UUID[])

required

One or more car UUIDs. Must not be null; each element must be a valid UUID.

string[] (UUID[])

required

One or more track layout UUIDs.

string[] (UUID[])

required

One or more rig UUIDs active during this event.

string[] (UUID[])

required

One or more brand UUIDs to associate.

object

Optional map of localization overrides.

object

Optional map of event configuration values.

boolean

Whether to make the event visible in public listings immediately. Defaults to false if omitted.

curl --request POST \
  --url https://api.pitpath.de/api/v1/events \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ppk_your_api_key_here' \
  --data '{
    "name": "Spring Cup Round 1",
    "slug": "spring-cup-r1",
    "description": "Opening round of the Spring Cup series.",
    "mode": "HOTLAP",
    "startsAt": "2026-06-01T14:00:00Z",
    "endsAt": "2026-06-01T16:00:00Z",
    "simulatorId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "carIds": ["c1d2e3f4-a5b6-7890-abcd-ef1234567890"],
    "trackLayoutIds": ["t1u2v3w4-x5y6-7890-abcd-ef1234567890"],
    "rigIds": ["r1i2g3h4-i5j6-7890-abcd-ef1234567890"],
    "brandIds": ["b1r2a3n4-d5f6-7890-abcd-ef1234567890"],
    "settingsJson": { "maxLaps": 30 },
    "enabled": true
  }'

Returns 201 Created with the full event object.

{
  "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  "name": "Spring Cup Round 1",
  "slug": "spring-cup-r1",
  "description": "Opening round of the Spring Cup series.",
  "mode": "HOTLAP",
  "startsAt": "2026-06-01T14:00:00Z",
  "endsAt": "2026-06-01T16:00:00Z",
  "simulatorId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "simulatorDisplayName": "iRacing",
  "carIds": ["c1d2e3f4-a5b6-7890-abcd-ef1234567890"],
  "trackLayoutIds": ["t1u2v3w4-x5y6-7890-abcd-ef1234567890"],
  "rigIds": ["r1i2g3h4-i5j6-7890-abcd-ef1234567890"],
  "brandIds": ["b1r2a3n4-d5f6-7890-abcd-ef1234567890"],
  "i18nJson": {},
  "settingsJson": { "maxLaps": 30 },
  "enabled": true,
  "createdAt": "2026-05-19T10:00:00Z",
  "updatedAt": "2026-05-19T10:00:00Z"
}

PATCH /api/v1/events/

Update an existing event. All fields are optional — only the fields you provide are changed. Required role: CRUD or higher

string (UUID)

required

UUID of the event to update.

string

New display name. Must be 2–120 characters.

string

New URL-safe slug. Must be 2–25 characters.

string

New description. Maximum 255 characters.

string

Updated competition format. One of HOTLAP, PRACTICE, AI_RACE, or MULTIPLAYER_RACE.

string (ISO 8601)

Updated start time.

string (ISO 8601)

Updated end time.

string (UUID)

Replacement simulator UUID.

string[] (UUID[])

Replacement set of car UUIDs. Replaces the entire existing list.

string[] (UUID[])

Replacement set of track layout UUIDs.

string[] (UUID[])

Replacement set of rig UUIDs.

string[] (UUID[])

Replacement set of brand UUIDs.

object

Replacement localization map.

object

Replacement settings map.

boolean

Set the event’s visibility in public listings.

curl --request PATCH \
  --url https://api.pitpath.de/api/v1/events/e1f2a3b4-c5d6-7890-abcd-ef1234567890 \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ppk_your_api_key_here' \
  --data '{
    "enabled": false
  }'

Returns 200 OK with the updated event object.

{
  "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  "name": "Spring Cup Round 1",
  "slug": "spring-cup-r1",
  "description": "Opening round of the Spring Cup series.",
  "mode": "HOTLAP",
  "startsAt": "2026-06-01T14:00:00Z",
  "endsAt": "2026-06-01T16:00:00Z",
  "simulatorId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "simulatorDisplayName": "iRacing",
  "carIds": ["c1d2e3f4-a5b6-7890-abcd-ef1234567890"],
  "trackLayoutIds": ["t1u2v3w4-x5y6-7890-abcd-ef1234567890"],
  "rigIds": ["r1i2g3h4-i5j6-7890-abcd-ef1234567890"],
  "brandIds": ["b1r2a3n4-d5f6-7890-abcd-ef1234567890"],
  "i18nJson": {},
  "settingsJson": { "maxLaps": 30 },
  "enabled": false,
  "createdAt": "2026-05-19T10:00:00Z",
  "updatedAt": "2026-05-19T11:30:00Z"
}

Overview

Endpoints

Events API — racing sessions and competitions

GET /api/v1/events

GET /api/v1/events/paged

GET /api/v1/events/

POST /api/v1/events

PATCH /api/v1/events/

​GET /api/v1/events

​GET /api/v1/events/paged

​GET /api/v1/events/

​POST /api/v1/events

​PATCH /api/v1/events/

GET /api/v1/events

GET /api/v1/events/paged

GET /api/v1/events/

POST /api/v1/events

PATCH /api/v1/events/