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

# Cars API — vehicle catalog and classes

> Browse and manage the full vehicle catalog, manufacturer brands, and performance classes. Every car belongs to a brand and a class.

The Cars API lets you query and manage the vehicle catalog used across PitPath Chrono events. Each car belongs to a **car brand** (the manufacturer) and a **car class** (the performance category). You must create a brand and a class before creating a car that references them. GET endpoints are public. Creating or updating records requires a CRUD+ role.

## Car object

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

<ResponseField name="brandId" type="string (UUID)" required>
  UUID of the car brand (manufacturer).
</ResponseField>

<ResponseField name="brandDisplayName" type="string" required>
  Display name of the manufacturer.
</ResponseField>

<ResponseField name="modelName" type="string" required>
  Model name of the car (1–120 characters).
</ResponseField>

<ResponseField name="carClassId" type="string (UUID)" required>
  UUID of the car class.
</ResponseField>

<ResponseField name="carClassDisplayName" type="string" required>
  Display name of the car class.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Whether the car appears in public listings.
</ResponseField>

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

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

***

## List cars

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

Returns all enabled cars as an unordered list.

```
GET /api/v1/cars
```

**Example request**

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

**Example response**

```json 200 theme={null}
[
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "brandId": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "brandDisplayName": "Porsche",
    "modelName": "911 GT3 Cup",
    "carClassId": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "carClassDisplayName": "GT3",
    "enabled": true,
    "createdAt": "2024-02-10T09:00:00Z",
    "updatedAt": "2024-05-20T14:15:00Z"
  }
]
```

***

## List cars (paged)

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

Returns enabled cars in a paginated response. Default page size is 20, sorted by `modelName`.

```
GET /api/v1/cars/paged
```

**Query parameters**

<ParamField query="page" type="number" default="0">
  Zero-based page index.
</ParamField>

<ParamField query="size" type="number" default="20">
  Number of items per page.
</ParamField>

<ParamField query="sort" type="string" default="modelName">
  Field and direction, e.g. `modelName,asc`.
</ParamField>

**Example request**

```bash cURL theme={null}
curl "https://chrono.pitpath.de/api/v1/cars/paged?page=0&size=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Get a car

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

Returns a single car by its UUID.

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

**Path parameters**

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

**Example request**

```bash cURL theme={null}
curl https://chrono.pitpath.de/api/v1/cars/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Create a car

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

Creates a new car. You must supply a valid `brandId` and `carClassId` that already exist in the system.

```
POST /api/v1/cars
```

**Request body**

<ParamField body="brandId" type="string (UUID)" required>
  UUID of the manufacturer brand.
</ParamField>

<ParamField body="modelName" type="string" required>
  Car model name (1–120 characters).
</ParamField>

<ParamField body="carClassId" type="string (UUID)" required>
  UUID of the performance class.
</ParamField>

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

**Example request**

```bash cURL theme={null}
curl -X POST https://chrono.pitpath.de/api/v1/cars \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "modelName": "911 GT3 Cup",
    "carClassId": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "enabled": true
  }'
```

***

## Update a car

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

Partially updates an existing car. Only the fields you include are changed.

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

**Path parameters**

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

**Request body**

<ParamField body="brandId" type="string (UUID)">
  UUID of the new manufacturer brand.
</ParamField>

<ParamField body="modelName" type="string">
  New model name (1–120 characters).
</ParamField>

<ParamField body="carClassId" type="string (UUID)">
  UUID of the new performance class.
</ParamField>

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

**Example request**

```bash cURL theme={null}
curl -X PATCH https://chrono.pitpath.de/api/v1/cars/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

***

## Car brand object

A car brand represents a vehicle manufacturer such as Porsche, Ferrari, or BMW.

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

<ResponseField name="displayName" type="string" required>
  Manufacturer 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 manufacturer logo asset (max 255 characters).
</ResponseField>

<ResponseField name="svg" type="boolean">
  Whether the logo is an SVG file.
</ResponseField>

<ResponseField name="country" type="string" required>
  ISO 3166-1 alpha-3 country code of the manufacturer's home country.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Whether the brand appears in public listings.
</ResponseField>

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

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

***

## List car brands

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

```
GET /api/v1/car-brands
```

**Example request**

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

***

## List car brands (paged)

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

```
GET /api/v1/car-brands/paged
```

***

## Get a car brand

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

```
GET /api/v1/car-brands/{carBrandId}
```

<ParamField path="carBrandId" type="string (UUID)" required>
  The UUID of the car brand.
</ParamField>

***

## Create a car brand

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

```
POST /api/v1/car-brands
```

**Request body**

<ParamField body="displayName" type="string" required>
  Manufacturer 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 logo asset (max 255 characters).
</ParamField>

<ParamField body="svg" type="boolean">
  Whether the logo is an SVG file.
</ParamField>

<ParamField body="country" type="string" required>
  ISO 3166-1 alpha-3 country code (exactly 3 characters, e.g. `"DEU"`).
</ParamField>

<ParamField body="enabled" type="boolean">
  Defaults to `true`.
</ParamField>

**Example request**

```bash cURL theme={null}
curl -X POST https://chrono.pitpath.de/api/v1/car-brands \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Porsche",
    "slug": "porsche",
    "logo": "BRAND/porsche.svg",
    "svg": true,
    "country": "DEU",
    "enabled": true
  }'
```

***

## Update a car brand

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

```
PATCH /api/v1/car-brands/{carBrandId}
```

<ParamField path="carBrandId" type="string (UUID)" required>
  The UUID of the car brand to update.
</ParamField>

**Request body** — all fields are optional.

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

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

<ParamField body="logo" type="string">
  New CDN key for the logo (max 255 characters).
</ParamField>

<ParamField body="svg" type="boolean">
  Whether the new logo is an SVG file.
</ParamField>

<ParamField body="country" type="string">
  New ISO 3166-1 alpha-3 country code (exactly 3 characters).
</ParamField>

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

***

## Car class object

A car class groups vehicles by performance category, for example GT3, GT4, or Prototype.

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

<ResponseField name="displayName" type="string" required>
  Full class name (2–120 characters).
</ResponseField>

<ResponseField name="shortName" type="string" required>
  Abbreviated class name (2–20 characters).
</ResponseField>

<ResponseField name="logo" type="string" required>
  CDN key for the class logo (max 255 characters).
</ResponseField>

<ResponseField name="svg" type="boolean">
  Whether the logo is an SVG file.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Whether the class appears in public listings.
</ResponseField>

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

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

***

## List car classes

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

```
GET /api/v1/car-classes
```

**Example request**

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

***

## List car classes (paged)

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

```
GET /api/v1/car-classes/paged
```

***

## Get a car class

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

```
GET /api/v1/car-classes/{carClassId}
```

<ParamField path="carClassId" type="string (UUID)" required>
  The UUID of the car class.
</ParamField>

***

## Create a car class

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

```
POST /api/v1/car-classes
```

**Request body**

<ParamField body="displayName" type="string" required>
  Full class name (2–120 characters).
</ParamField>

<ParamField body="shortName" type="string" required>
  Abbreviated name (2–20 characters).
</ParamField>

<ParamField body="logo" type="string" required>
  CDN key for the class logo (max 255 characters).
</ParamField>

<ParamField body="svg" type="boolean">
  Whether the logo is an SVG file.
</ParamField>

<ParamField body="enabled" type="boolean">
  Defaults to `true`.
</ParamField>

**Example request**

```bash cURL theme={null}
curl -X POST https://chrono.pitpath.de/api/v1/car-classes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "GT3",
    "shortName": "GT3",
    "logo": "CLASS/gt3.svg",
    "svg": true,
    "enabled": true
  }'
```

***

## Update a car class

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

```
PATCH /api/v1/car-classes/{carClassId}
```

<ParamField path="carClassId" type="string (UUID)" required>
  The UUID of the car class to update.
</ParamField>

**Request body** — all fields are optional.

<ParamField body="displayName" type="string">
  New full class name (2–120 characters).
</ParamField>

<ParamField body="shortName" type="string">
  New abbreviated name (2–20 characters).
</ParamField>

<ParamField body="logo" type="string">
  New CDN key for the logo (max 255 characters).
</ParamField>

<ParamField body="svg" type="boolean">
  Whether the new logo is an SVG file.
</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/car-classes/e5f6a7b8-c9d0-1234-efab-345678901234 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shortName": "GT3-Cup"}'
```