> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chrono.racing/llms.txt
> Use this file to discover all available pages before exploring further.
# Events: structuring your sim racing competition
> Learn how events group a simulator, cars, track layouts, and rigs into a timed competition session, and how modes and slugs control their behavior.
An **event** is the central organizing unit in PitPath Chrono. It ties together everything needed to run a timed competition session: the simulator being used, the cars that are allowed, the track layouts being driven, the rigs that will submit data, and the time window during which it runs. Every lap recorded in Chrono belongs to exactly one event.
## Event fields
| Field | Type | Notes |
| - | - | - |
| `id` | UUID | Immutable identifier |
| `name` | string | Display name (max 120 chars) |
| `slug` | string | URL-safe identifier (max 25 chars) |
| `description` | string | Free-text description |
| `mode` | enum | Competition format — see [Modes](#modes) below |
| `startsAt` | ISO 8601 or `null` | When the event opens for lap submissions |
| `endsAt` | ISO 8601 or `null` | When the event closes |
| `simulatorId` | UUID | The simulator this event runs on |
| `simulatorDisplayName` | string | Denormalized for convenience |
| `carIds` | UUID\[] | Allowed cars for this event |
| `trackLayoutIds` | UUID\[] | Track layouts included in this event |
| `rigIds` | UUID\[] | Rigs authorized to submit laps |
| `brandIds` | UUID\[] | Brands associated with this event |
| `i18nJson` | object or `null` | Localization overrides |
| `settingsJson` | object or `null` | Event-specific configuration |
| `enabled` | boolean | |
| `createdAt` | ISO 8601 | |
| `updatedAt` | ISO 8601 | |
```json title="GET /api/v1/events/{id} — example response" theme={null}
{
"id": "e1000000-0000-0000-0000-000000000001",
"name": "ACME Autumn Championship — Round 3",
"slug": "acme-autumn-r3",
"description": "Third round of the ACME autumn series at Spa.",
"mode": "MULTIPLAYER_RACE",
"startsAt": "2024-11-10T18:00:00Z",
"endsAt": "2024-11-10T22:00:00Z",
"simulatorId": "s1000000-0000-0000-0000-000000000001",
"simulatorDisplayName": "Assetto Corsa Competizione",
"carIds": [
"c1000000-0000-0000-0000-000000000001",
"c1000000-0000-0000-0000-000000000002"
],
"trackLayoutIds": [
"t1000000-0000-0000-0000-000000000001"
],
"rigIds": [
"b2c3d4e5-0000-0000-0000-000000000002"
],
"brandIds": [
"d1000000-0000-0000-0000-000000000001"
],
"i18nJson": null,
"settingsJson": { "maxLapsPerParticipant": 30 },
"enabled": true,
"createdAt": "2024-10-01T09:00:00Z",
"updatedAt": "2024-10-15T11:30:00Z"
}
```
The `slug` field is designed for human-friendly URLs. Instead of building a leaderboard link from the UUID, you can use the slug — for example `/events/acme-autumn-r3/results` — making your URLs bookmarkable and shareable. Slugs are unique within a license and limited to 25 characters.
***
## Modes
The `mode` field describes the competition format. Chrono uses it to determine how laps are classified and which rules apply to the results.
Single-driver time attack. Each participant drives alone and the best clean lap counts. No opponents on track.
Open session for testing and setup. Laps are recorded but are not usually included in ranked results.
The participant races against AI opponents generated by the simulator. Useful for solo competitions or structured challenges.
Full online race where all participants share the same session. Results are ranked by finishing position and lap data.
***
## Track layouts
A **track** is a real-world or fictional circuit (for example, Circuit de Spa-Francorchamps). A **track layout** is a specific configuration of that track — the same physical venue can have multiple layouts such as a full circuit, a shorter national layout, or a rallycross infield. Each layout has its own length, corner count, and `TrackType`.
Track layout types (`TrackType`):
| Value | Description |
| - | - |
| `PERMANENT_ROAD` | A purpose-built permanent road circuit |
| `PERMANENT_DIRT` | A permanent off-road or gravel circuit |
| `PERMANENT_OVAL` | A permanent banked oval |
| `TEMPORARY_ROAD` | A temporary road layout (e.g. converted parking lot) |
| `TEMPORARY_DIRT` | A temporary dirt layout |
| `TEMPORARY_OVAL` | A temporary oval layout |
| `STREET_CIRCUIT_ROAD` | A closed public-road street circuit (paved) |
| `STREET_CIRCUIT_DIRT` | A closed public-road street circuit (unpaved) |
| `RALLY` | A point-to-point or stage rally layout |
An event's `trackLayoutIds` array lists the layouts active for that event. When multiple layouts are listed, each lap record specifies which layout it was driven on.
Track layout IDs, not track IDs, are what you reference when creating laps and filtering results. A lap is always tied to the specific layout, not the parent track, so that length and corner data are unambiguous.
***
## Simulators and cars
Each event is linked to exactly one **simulator** (for example, Assetto Corsa Competizione, iRacing, or rFactor 2) via `simulatorId`. The simulator determines which cars are available in its catalog.
Cars are listed in `carIds`. A car carries a `modelName`, a brand (`CarBrand`), and a class (`CarClass`). You can use `carIds` to filter results down to a specific class or marque when building leaderboards. There is no restriction on mixing classes within a single event — that is a policy decision left to your application.