Rigs API — timing hardware registration

A rig represents a physical timing station that records lap data during a racing event. Rigs self-register using a hardware identifier and a signed license file obtained from POST /api/v1/licenses/{licenseId}/file. On successful registration, the server returns a bootstrapped API key for the rig to use in subsequent requests. All GET endpoints require authentication. Only PATCH requires a higher CRUD-level role; POST is open to any authenticated caller.

GET /api/v1/rigs

Return all enabled rigs. Required role: Any authenticated user

curl --request GET \
  --url https://api.pitpath.de/api/v1/rigs \
  --header 'X-API-Key: ppk_your_api_key_here'

The response is an array of rig objects.

string (UUID)

required

Unique identifier for the rig.

string

required

Display name of the rig.

string

Optional description of the rig’s location or purpose.

string

required

Unique hardware identifier supplied by the device.

string (UUID)

required

UUID of the license this rig is registered under.

string

required

Human-readable name of the associated license.

boolean

required

Whether this rig is available for assignment to events.

string (ISO 8601)

required

Timestamp when the rig was registered.

string (ISO 8601)

required

Timestamp of the most recent update.

[
  {
    "id": "r1i2g3h4-i5j6-7890-abcd-ef1234567890",
    "name": "Rig A",
    "description": "Pit lane timing station",
    "hardwareId": "PP-RIG-0042",
    "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "licenseDisplayName": "Acme Racing Team",
    "enabled": true,
    "createdAt": "2026-05-10T09:00:00Z",
    "updatedAt": "2026-05-10T09:00:00Z"
  }
]

GET /api/v1/rigs/paged

Return a paginated list of enabled rigs, sorted by name ascending by default. Required role: Any authenticated user

number

default:"0"

Zero-based page number.

number

default:"20"

Number of rigs per page.

string

default:"name"

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

curl --request GET \
  --url 'https://api.pitpath.de/api/v1/rigs/paged?page=0&size=20&sort=name,asc' \
  --header 'X-API-Key: ppk_your_api_key_here'

Returns a page envelope with content, totalElements, totalPages, number, and size.

{
  "content": [
    {
      "id": "r1i2g3h4-i5j6-7890-abcd-ef1234567890",
      "name": "Rig A",
      "description": "Pit lane timing station",
      "hardwareId": "PP-RIG-0042",
      "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "licenseDisplayName": "Acme Racing Team",
      "enabled": true,
      "createdAt": "2026-05-10T09:00:00Z",
      "updatedAt": "2026-05-10T09:00:00Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

GET /api/v1/rigs/

Return a single rig by UUID. Required role: Any authenticated user

string (UUID)

required

UUID of the rig to retrieve.

curl --request GET \
  --url https://api.pitpath.de/api/v1/rigs/r1i2g3h4-i5j6-7890-abcd-ef1234567890 \
  --header 'X-API-Key: ppk_your_api_key_here'

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

{
  "id": "r1i2g3h4-i5j6-7890-abcd-ef1234567890",
  "name": "Rig A",
  "description": "Pit lane timing station",
  "hardwareId": "PP-RIG-0042",
  "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "licenseDisplayName": "Acme Racing Team",
  "enabled": true,
  "createdAt": "2026-05-10T09:00:00Z",
  "updatedAt": "2026-05-10T09:00:00Z"
}

GET /api/v1/rigs/hardwareId/

Look up a rig by its hardware identifier. This is the primary lookup used by timing devices to find their own registration record. Required role: Any authenticated user

string

required

The hardware identifier string as reported by the device.

curl --request GET \
  --url https://api.pitpath.de/api/v1/rigs/hardwareId/PP-RIG-0042 \
  --header 'X-API-Key: ppk_your_api_key_here'

Returns a single rig object with the same shape as GET /api/v1/rigs/{rigId}.

{
  "id": "r1i2g3h4-i5j6-7890-abcd-ef1234567890",
  "name": "Rig A",
  "description": "Pit lane timing station",
  "hardwareId": "PP-RIG-0042",
  "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "licenseDisplayName": "Acme Racing Team",
  "enabled": true,
  "createdAt": "2026-05-10T09:00:00Z",
  "updatedAt": "2026-05-10T09:00:00Z"
}

POST /api/v1/rigs

Register a new timing rig. The rig identifies itself with a hardware ID and proves ownership by submitting a signed license file issued via POST /api/v1/licenses/{licenseId}/file. On success, the server registers the rig and returns a fresh API key for the device to use. Required role: Any authenticated user

string

required

Unique identifier reported by the hardware device. Maximum 255 characters.

object

required

Signed license token obtained from POST /api/v1/licenses/{licenseId}/file.

Show licenseFile properties

string (UUID)

required

UUID of the license the file was issued for.

string

required

License key embedded in the signed file.

string (ISO 8601)

required

Timestamp when the file was issued.

string

required

Cryptographic signature verifying file authenticity.

curl --request POST \
  --url https://api.pitpath.de/api/v1/rigs \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ppk_your_api_key_here' \
  --data '{
    "hardwareId": "PP-RIG-0042",
    "licenseFile": {
      "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "licenseKey": "lic_a1b2c3d4e5f6",
      "issuedAt": "2026-05-19T10:05:00Z",
      "signature": "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }
  }'

object

required

The registered rig record.

Show rig properties

string (UUID)

required

Unique identifier for the rig.

string

required

Display name assigned to the rig.

string

Optional description.

string

required

Hardware identifier as submitted.

string (UUID)

required

UUID of the owning license.

string

required

Human-readable license name.

boolean

required

Whether the rig is active.

string (ISO 8601)

required

Registration timestamp.

string (ISO 8601)

required

Last-updated timestamp.

object

required

A bootstrapped API key for the rig to use in subsequent requests. The full token is only present in this response.

Show apiKey properties

object

required

API key metadata with the same shape as GET /api/v1/api-keys items.

string

required

Full API key token. Store this securely — it cannot be retrieved again.

{
  "rig": {
    "id": "r1i2g3h4-i5j6-7890-abcd-ef1234567890",
    "name": "Rig A",
    "description": null,
    "hardwareId": "PP-RIG-0042",
    "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "licenseDisplayName": "Acme Racing Team",
    "enabled": true,
    "createdAt": "2026-05-19T10:10:00Z",
    "updatedAt": "2026-05-19T10:10:00Z"
  },
  "apiKey": {
    "apiKey": {
      "id": "k1e2y3i4-d5f6-7890-abcd-ef1234567890",
      "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "rig-PP-RIG-0042",
      "keyPrefix": "ppk_r1i2",
      "role": "CRUD",
      "enabled": true,
      "lastUsedAt": null,
      "createdAt": "2026-05-19T10:10:00Z",
      "updatedAt": "2026-05-19T10:10:00Z"
    },
    "token": "ppk_r1i2g3h4i5j6k7l8m9n0o1p2q3r4s5t6u7v8w9x0"
  }
}

PATCH /api/v1/rigs/

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

string (UUID)

required

UUID of the rig to update.

string

New display name. Must be 2–120 characters.

string

Updated description. Maximum 255 characters.

string

Updated hardware identifier. Maximum 255 characters.

string (UUID)

Reassign the rig to a different license.

boolean

Enable or disable the rig.

curl --request PATCH \
  --url https://api.pitpath.de/api/v1/rigs/r1i2g3h4-i5j6-7890-abcd-ef1234567890 \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ppk_your_api_key_here' \
  --data '{
    "name": "Rig A — Pit Lane",
    "description": "Timing station at pit lane entry"
  }'

Returns 200 OK with the updated rig object.

{
  "id": "r1i2g3h4-i5j6-7890-abcd-ef1234567890",
  "name": "Rig A — Pit Lane",
  "description": "Timing station at pit lane entry",
  "hardwareId": "PP-RIG-0042",
  "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "licenseDisplayName": "Acme Racing Team",
  "enabled": true,
  "createdAt": "2026-05-10T09:00:00Z",
  "updatedAt": "2026-05-19T11:00:00Z"
}

Overview

Endpoints

Rigs API — timing hardware registration

GET /api/v1/rigs

GET /api/v1/rigs/paged

GET /api/v1/rigs/

GET /api/v1/rigs/hardwareId/

POST /api/v1/rigs

PATCH /api/v1/rigs/

​GET /api/v1/rigs

​GET /api/v1/rigs/paged

​GET /api/v1/rigs/

​GET /api/v1/rigs/hardwareId/

​POST /api/v1/rigs

​PATCH /api/v1/rigs/

GET /api/v1/rigs

GET /api/v1/rigs/paged

GET /api/v1/rigs/

GET /api/v1/rigs/hardwareId/

POST /api/v1/rigs

PATCH /api/v1/rigs/