> ## 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.

# Simulators API — sim software catalog

> Manage the sim racing software catalog and map simulator-specific track and car identifiers to their canonical PitPath Chrono entities.

The Simulators API lets you manage the catalog of sim racing software titles supported by PitPath Chrono. Each simulator can have **layouts** that map a PitPath track layout to the simulator's internal identifier, and **cars** that do the same for vehicles. This mapping is essential when ingesting lap data from a specific simulator: the system uses these identifiers to resolve which canonical track layout or car the data belongs to. GET endpoints are public. Creating or modifying records requires a CRUD+ role.

## Simulator object

<ResponseField name="id" type="string (UUID)" required>
  Unique identifier for the simulator.
</ResponseField>

<ResponseField name="displayName" type="string" required>
  Human-readable simulator name (3–120 characters).
</ResponseField>

<ResponseField name="slug" type="string" required>
  URL-safe identifier (2–20 characters).
</ResponseField>

<ResponseField name="logo" type="string" required>
  CDN key for the simulator's square or standard logo asset.
</ResponseField>

<ResponseField name="logo_wide" type="string" required>
  CDN key for the simulator's wide-format logo asset.
</ResponseField>

<ResponseField name="svg" type="boolean">
  Whether the logo assets are SVG files.
</ResponseField>

<ResponseField name="layouts" type="object[]">
  List of simulator layout mappings embedded in the response.

  <Expandable title="SimulatorLayoutResponse properties">
    <ResponseField name="simulatorId" type="string (UUID)">
      UUID of this simulator.
    </ResponseField>

    <ResponseField name="simulatorDisplayName" type="string">
      Display name of this simulator.
    </ResponseField>

    <ResponseField name="trackLayoutId" type="string (UUID)">
      UUID of the PitPath track layout this entry maps to.
    </ResponseField>

    <ResponseField name="trackLayoutDisplayName" type="string">
      Display name of the mapped track layout.
    </ResponseField>

    <ResponseField name="simulatorIdentifier" type="string">
      The internal identifier used by the simulator to refer to this track (max 255 characters).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdAt" type="string (ISO 8601)">
  Timestamp when the simulator was created.
</ResponseField>

<ResponseField name="updatedAt" type="string (ISO 8601)">
  Timestamp of the most recent update.
</ResponseField>

***

## List simulators

<Info>Public endpoint — no authentication required.</Info>

Returns all enabled simulators, each including their full list of layout mappings.

```
GET /api/v1/simulators
```

**Example request**

```bash cURL theme={null}
curl https://chrono.pitpath.de/api/v1/simulators \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json 200 theme={null}
[
  {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "displayName": "Assetto Corsa Competizione",
    "slug": "acc",
    "logo": "LOGO/acc.png",
    "logo_wide": "LOGO/acc-wide.png",
    "svg": false,
    "layouts": [
      {
        "simulatorId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "simulatorDisplayName": "Assetto Corsa Competizione",
        "trackLayoutId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "trackLayoutDisplayName": "Grand Prix Circuit",
        "simulatorIdentifier": "nurburgring_gp"
      }
    ],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-06-01T12:00:00Z"
  }
]
```

***

## Get a simulator

<Info>Public endpoint — no authentication required.</Info>

Returns a single simulator by its UUID, including all layout mappings.

```
GET /api/v1/simulators/{simulatorId}
```

**Path parameters**

<ParamField path="simulatorId" type="string (UUID)" required>
  The UUID of the simulator to retrieve.
</ParamField>

**Example request**

```bash cURL theme={null}
curl https://chrono.pitpath.de/api/v1/simulators/f1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Create a simulator

<Warning>Requires CRUD+ role.</Warning>

Registers a new simulator in the catalog. Returns `201 Created` with a `Location` header.

```
POST /api/v1/simulators
```

**Request body**

<ParamField body="displayName" type="string" required>
  Simulator name (3–120 characters).
</ParamField>

<ParamField body="slug" type="string" required>
  URL-safe identifier (2–20 characters).
</ParamField>

<ParamField body="logo" type="string" required>
  CDN key for the standard logo asset.
</ParamField>

<ParamField body="logoWide" type="string" required>
  CDN key for the wide-format logo asset.
</ParamField>

<ParamField body="svg" type="boolean">
  Whether the logo assets are SVG files. Defaults to `false`.
</ParamField>

<ParamField body="enabled" type="boolean">
  Whether the simulator appears in public listings. Defaults to `true`.
</ParamField>

**Example request**

```bash cURL theme={null}
curl -X POST https://chrono.pitpath.de/api/v1/simulators \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Assetto Corsa Competizione",
    "slug": "acc",
    "logo": "LOGO/acc.png",
    "logoWide": "LOGO/acc-wide.png",
    "svg": false,
    "enabled": true
  }'
```

***

## Update a simulator

<Warning>Requires CRUD+ role.</Warning>

Updates an existing simulator. All fields are required in the update body because the underlying service replaces the full set of mutable fields.

```
PATCH /api/v1/simulators/{simulatorId}
```

**Path parameters**

<ParamField path="simulatorId" type="string (UUID)" required>
  The UUID of the simulator to update.
</ParamField>

**Request body**

<ParamField body="displayName" type="string" required>
  New simulator name (3–120 characters).
</ParamField>

<ParamField body="slug" type="string" required>
  New URL-safe identifier (3–20 characters).
</ParamField>

<ParamField body="logo" type="string" required>
  New CDN key for the standard logo.
</ParamField>

<ParamField body="logoWide" type="string" required>
  New CDN key for the wide-format logo.
</ParamField>

<ParamField body="svg" type="boolean">
  Whether the new logo assets are SVG files.
</ParamField>

<ParamField body="enabled" type="boolean">
  Set to `false` to hide from public listings.
</ParamField>

**Example request**

```bash cURL theme={null}
curl -X PATCH https://chrono.pitpath.de/api/v1/simulators/f1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Assetto Corsa Competizione",
    "slug": "acc",
    "logo": "LOGO/acc-v2.png",
    "logoWide": "LOGO/acc-wide-v2.png",
    "enabled": true
  }'
```

***

## Simulator layout mappings

A simulator layout maps a PitPath track layout to the string identifier the simulator uses for that track internally. The `simulatorIdentifier` is what the sim reports in its telemetry or data export — for example `"nurburgring_gp"` in Assetto Corsa Competizione.

### List layouts for a simulator

<Info>Public endpoint — no authentication required.</Info>

```
GET /api/v1/simulators/{simulatorId}/layouts
```

<ParamField path="simulatorId" type="string (UUID)" required>
  The UUID of the simulator.
</ParamField>

**Example request**

```bash cURL theme={null}
curl https://chrono.pitpath.de/api/v1/simulators/f1a2b3c4-d5e6-7890-abcd-ef1234567890/layouts \
  -H "X-API-Key: YOUR_API_KEY"
```

***

### Get a simulator layout

<Info>Public endpoint — no authentication required.</Info>

```
GET /api/v1/simulators/{simulatorId}/layouts/{trackLayoutId}
```

<ParamField path="simulatorId" type="string (UUID)" required>
  The UUID of the simulator.
</ParamField>

<ParamField path="trackLayoutId" type="string (UUID)" required>
  The UUID of the PitPath track layout.
</ParamField>

***

### Create a simulator layout

<Warning>Requires CRUD+ role.</Warning>

Links a PitPath track layout to a simulator using the simulator's own internal identifier.

```
POST /api/v1/simulators/{simulatorId}/layouts
```

<ParamField path="simulatorId" type="string (UUID)" required>
  The UUID of the simulator.
</ParamField>

**Request body**

<ParamField body="trackLayoutId" type="string (UUID)" required>
  UUID of the PitPath track layout to link.
</ParamField>

<ParamField body="simulatorIdentifier" type="string" required>
  The internal string the simulator uses for this track (max 255 characters).
</ParamField>

**Example request**

```bash cURL theme={null}
curl -X POST https://chrono.pitpath.de/api/v1/simulators/f1a2b3c4-d5e6-7890-abcd-ef1234567890/layouts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackLayoutId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "simulatorIdentifier": "nurburgring_gp"
  }'
```

***

### Update a simulator layout

<Warning>Requires CRUD+ role.</Warning>

Updates the simulator's internal identifier for an existing layout mapping.

```
PATCH /api/v1/simulators/{simulatorId}/layouts/{trackLayoutId}
```

<ParamField path="simulatorId" type="string (UUID)" required>
  The UUID of the simulator.
</ParamField>

<ParamField path="trackLayoutId" type="string (UUID)" required>
  The UUID of the PitPath track layout.
</ParamField>

**Request body**

<ParamField body="simulatorIdentifier" type="string" required>
  The updated internal identifier (max 255 characters).
</ParamField>

**Example request**

```bash cURL theme={null}
curl -X PATCH https://chrono.pitpath.de/api/v1/simulators/f1a2b3c4-d5e6-7890-abcd-ef1234567890/layouts/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"simulatorIdentifier": "nurburgring_gp_2024"}'
```

***

### Delete a simulator layout

<Warning>Requires CRUD+ role with delete permission.</Warning>

Removes the link between a simulator and a track layout. Returns `204 No Content`.

```
DELETE /api/v1/simulators/{simulatorId}/layouts/{trackLayoutId}
```

<ParamField path="simulatorId" type="string (UUID)" required>
  The UUID of the simulator.
</ParamField>

<ParamField path="trackLayoutId" type="string (UUID)" required>
  The UUID of the PitPath track layout to unlink.
</ParamField>

**Example request**

```bash cURL theme={null}
curl -X DELETE https://chrono.pitpath.de/api/v1/simulators/f1a2b3c4-d5e6-7890-abcd-ef1234567890/layouts/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Simulator car mappings

In addition to track layouts, you can map PitPath cars to simulator-specific identifiers using the `/cars` sub-resource. This follows the same pattern as layout mappings.

### List cars for a simulator

<Info>Public endpoint — no authentication required.</Info>

```
GET /api/v1/simulators/{simulatorId}/cars
```

***

### Get a simulator car

<Info>Public endpoint — no authentication required.</Info>

```
GET /api/v1/simulators/{simulatorId}/cars/{carId}
```

The response includes `simulatorId`, `simulatorDisplayName`, `carId`, `carDisplayName`, `carBrandId`, `carBrandDisplayName`, `carClassId`, `carClassDisplayName`, `simulatorIdentifier`, and `contentId`.

***

### Create a simulator car

<Warning>Requires CRUD+ role.</Warning>

```
POST /api/v1/simulators/{simulatorId}/cars
```

**Request body**

<ParamField body="carId" type="string (UUID)" required>
  UUID of the PitPath car to link.
</ParamField>

<ParamField body="simulatorIdentifier" type="string" required>
  The internal string the simulator uses for this car.
</ParamField>

***

### Update a simulator car

<Warning>Requires CRUD+ role.</Warning>

```
PATCH /api/v1/simulators/{simulatorId}/cars/{carId}
```

**Request body**

<ParamField body="simulatorIdentifier" type="string" required>
  Updated internal identifier.
</ParamField>

***

### Delete a simulator car

<Warning>Requires CRUD+ role with delete permission.</Warning>

Removes the car mapping. Returns `204 No Content`.

```
DELETE /api/v1/simulators/{simulatorId}/cars/{carId}
```