Vehicles

Every vehicle on your server — the paginated list, a single vehicle by its entity id, its inventory, and a breakdown of how many of each type exist.

Identifying a vehicle

The detail and inventory endpoints take a numeric {id} path segment — the vehicle's entity id. It must be a positive integer with no leading zeros (pattern ^[1-9]\d*$); values such as 0 and 007 are rejected with 400 validation_error.

GET /v1/vehicles
GET /v1/vehicles/9
GET /v1/vehicles/9/inventory
GET /v1/vehicles/types

Authorization

Scope	Grants
`vehicles:read`	Every vehicle endpoint — list, detail, inventory, type counts.

Each vehicle owner carries a discord_id (null when that owner isn't linked to Discord). A key missing the scope gets 403 insufficient_scope.

`GET /v1/vehicles`

The vehicle list, paginated. Optional filters:

Query	Meaning
`owner_steam_id`	Vehicles owned by this Steam64 (digits only).
`owner_discord_id`	Vehicles owned by the player linked to this Discord id (digits only). Resolves at request time; an unlinked id matches nothing (empty page, never a `404`).
`owner_name`	Exact owner character-name match (no substring operator).
`alias`	Exact vehicle alias match.
`is_locked`	`true` or `false`.
`is_functional`	`true` or `false`.
`search`	Free-text search. Cannot be combined with any structured filter above (`400 validation_error`).
`limit`	Page size, 10–100 (default 50).
`cursor`	Opaque cursor from a previous response's `next_cursor`.

Supplying both owner_steam_id and owner_discord_id is a 400 validation_error.

{
  "data": [
    {
      "entity_id": "9", "class_name": "BPC_Kinglet_Duster", "display_name": "Kinglet Duster",
      "owner": { "profile_id": 7, "name": "Bob", "steam_id": "76561198000000000", "discord_id": "123456789012345678" },
      "health": 950.5, "max_health": 1000,
      "position": { "x": 1, "y": 2, "z": 3 },
      "is_locked": true, "lock_type": "DialLock_Item", "lock_hp": 0.85,
      "is_functional": true, "last_access_time": "2023-11-14T22:13:20.000Z", "item_count": 12
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 1
}

Field notes

owner is the nested identity object { profile_id, name, steam_id, discord_id }. health, max_health, lock_hp, and every position axis are fractional numbers. last_access_time is ISO-8601 (or null). item_count is null when the mod didn't report it.

`GET /v1/vehicles/{id}`

A single vehicle by its entity id. Returns the same object as one list row. 404 not_found when no vehicle carries that entity id.

`GET /v1/vehicles/{id}/inventory`

The vehicle's full, nested inventory. Each item may carry contents (recursively). A subtree the mod stopped expanding at its depth cap is flagged contents_truncated: true.

{
  "items": [
    {
      "id": 1, "class": "Backpack", "name": "Backpack", "icon": "…",
      "health": 100, "max_health": 100, "weight": 2, "is_container": true, "is_weapon": false,
      "contents_truncated": false,
      "contents": [ { "id": 3, "class": "Pouch", "name": "Pouch", "icon": "…", "contents": [], "contents_truncated": true, "health": 1, "max_health": 1, "weight": 0.1, "is_container": true, "is_weapon": false } ]
    }
  ],
  "total": 1
}

`GET /v1/vehicles/types`

A read-only aggregation of how many vehicles of each display name exist. This is a summary, not a filter source — the numbers are keyed by human-readable names, not the raw class_name you'd pass to a filter.

{ "types": { "Kinglet Duster": 3, "Wolfswagen": 1 } }

Caching

Every vehicle read sends an ETag and Cache-Control: private with a short max-age (10–15 s); send the ETag back as If-None-Match to get a 304 Not Modified.

Errors

Standard error envelope. The ones you're most likely to hit:

Code	Status	When
`insufficient_scope`	403	The key lacks `vehicles:read`.
`not_found`	404	No vehicle matches the `{id}`.
`validation_error`	400	An `{id}` that isn't a positive integer without leading zeros (`^[1-9]\d*$`), `?search=` combined with a structured filter, both owner ids together, or a non-digit `owner_steam_id`/`owner_discord_id`.
`server_unavailable`	503	The game server is offline or unreachable.
`gateway_timeout`	504	The server did not respond in time.

Vehicles

On this page