Skip to main content

Vehicle definitions and attributes

Vehicles keep one native identity across dispatching, device associations and custom attributes. A Vehicle definition describes a kind of vehicle, such as a bicycle or patrol car. Each vehicle belongs to exactly one explicitly created definition. New workspaces have no default Vehicle type; create a definition first, or use one installed by an enabled integration. All business fields—including name, license plate, VIN and capacity—are definition attributes inside data, just like Object record values. The definition controls which fields exist and which are required. Its display template provides the label; without a template, a nonblank text data.name is used. If there is no usable name, or an explicit template renders empty, the label falls back to the current natural_id.

Vehicle definitions use the same attribute contract as Object definitions. Supported types are text, license_plate, vin, number, boolean, date, date_time, select (single or multiple), state, capacity, measure, currency, rating, email, phone, tags, required_skills, provided_skills, relationship, location, raw_json, rich_text, full_name and links. Capacity and measure fields validate their referenced units. Phone values are normalized on write; license plates and VINs retain their free text.

Display configuration is editable and attributes can be added to existing tenant-owned definitions. Attributes support incremental editing/deletion and atomic full definition replacement. Scoped REST queries support column-backed attribute filters and sorts; metadata publishes is_sortable and filter_operators. GraphQL custom fields remain follow-up work. Every Vehicle also inherits one read-only intrinsic location; ordinary named location attributes support fixed and tracked values. Record responses omit data.location when there is no current location.

Every definition has an optional, editable natural-ID prefix and an independent counter. Omitting the prefix on creation or replacement produces numeric-only IDs; records expose the ID as a top-level string. Managed definitions permit metadata PATCH changes to the prefix, icon, color and map marker fields. BW dispatch reads, including Vehicles embedded in Tours, expose the same canonical string.

Create a definition​

POST /api/v2/definitions/vehicles requires schemas:write. System owners and admins receive this grant by default. Reading definitions accepts vehicles:read or schemas:write.

schemas:write also governs Object definitions and measure-unit definitions. It grants no Vehicle or Object record access. System- and plugin-managed definitions remain locked for schema editors.

{
"slug": "bicycle",
"natural_id_key": "BIKE",
"name": {"en": {"singular": "Bicycle", "plural": "Bicycles"}},
"attributes": [
{"slug": "battery_wh", "type": "number", "config": {"minimum": 0, "default": 625}},
{"slug": "frame_number", "type": "text", "config": {"is_unique": true}},
{"slug": "electric", "type": "boolean", "config": {"default": true}}
]
}

The response is 201 with the created definition and its absolute Location. List definitions at GET /api/v2/definitions/vehicles?page=0&size=20, or read one at GET /api/v2/definitions/vehicles/{definition_ref}. A reference is a UUID or slug. Slugs are unique across all definitions in a workspace: Object, Vehicle and Task definitions cannot share a slug. Definition lists order by slug, then UUID, matching custom Object and Task definitions. There is no additional core or standard Vehicle definition. An upgrade may preserve an existing legacy fleet as a tenant-owned definition. Responses use the canonical definition representation, with resource_type: "vehicle" and effective inherited/system attributes. Internal family ancestry is not exposed. Installed plugins own their protected Vehicle definitions; create their records through the same definition-scoped API.

Definitions currently allow up to 20 custom attributes. Slugs start with a lowercase letter and contain lowercase letters, digits or underscores. Definition slugs have at most 63 characters; attribute slugs have at most 200. The exact words self and this are reserved for both. The plugin_ prefix is reserved for plugin-managed definitions, even before plugin activation; all is reserved for family-wide Vehicle routes. Both are allowed on attributes, and so_ is no longer reserved. Custom fields cannot shadow platform or native fields. Defaults apply only when creating a vehicle and only when the value is omitted. Single-value text- and number-backed attributes can require uniqueness within the selected definition. Multi-select values and booleans cannot require uniqueness.

Select options (options) and colored states (states) sit alongside config. Send their value codes or UUIDs in record data; reads return canonical UUIDs. Multi-select data and defaults are arrays. Omit attribute, option and state IDs when creating a Vehicle definition; the server assigns them. Defaults apply on create when a field is omitted. Explicit null clears an optional field and suppresses its default; required fields cannot be cleared. Invalid values leave the whole write unchanged, including the vehicle's version.

Configure definition presentation​

Vehicle definitions accept the same icon, color and map_marker_fields metadata as Object and Task definitions. Marker fields are ordered slugs of supported effective attributes; [] or PATCH null clears the selection. Attribute rename/removal updates the selection in the same transaction. An icon is a catalog key of up to 64 lowercase letters, digits and single hyphens, such as truck. Colors are gray, red, orange, amber, green, teal, blue, indigo, violet or pink. An omitted or null color has a transparent background in the web app; an unset icon uses the standard Vehicle navigation icon. Definition icons appear in the sidebar, rather than page headers.

Set either field on creation or full replacement, or PATCH it independently:

{"icon":"truck","color":null,"lock_version":0}

PATCH omission preserves each value; explicit null clears it. Full replacement omission clears both fields. Reads omit unset values. Invalid keys, colors or JSON types return field-level 422. System/plugin definitions permit these presentation changes while their schema stays locked.

Add an attribute​

POST /api/v2/definitions/vehicles/{definition_ref}/attributes requires schemas:write. It accepts the same AttributeWrite payload as incremental Object authoring:

{
"slug": "range_km",
"type": "number",
"name": {"en": "Range (km)"},
"config": {"is_integer": true, "minimum": 0, "default": 80},
"lock_version": 0
}

All supported attribute types can be added, including relationships, named locations, tags and skills. The response is 201 with the complete updated definition and an absolute Location pointing to that definition. Attribute and choice IDs are assigned by the server; omit them on creation. The optional lock_version belongs to the definition, not a Vehicle record. Stale versions or a concurrent schema change return 409. Duplicate or reserved slugs, invalid configuration and exceeding the 20-attribute limit return 422. Attempts to edit managed definitions return 409 definitions/schema-locked.

Existing Vehicle records, their values and their versions are preserved. Adding a default does not backfill existing records: it applies when creating future Vehicles. Adding a required field makes it mandatory for subsequent record writes, so integrations must supply it when editing an older record that has no value yet. Schema metadata, column/index creation and relationship provisioning commit together; a rejected operation leaves the definition unchanged. An added relationship uses the same native Vehicle identity as existing links and can provision a read-only reverse field on its target. Inherited fields, including the intrinsic location, remain owned by their source.

This operation also exists under /frontend/v2, and as the MCP tool vehicle_attributes_add.

Attribute order​

The attributes array of a Vehicle definition is returned in display order. The same order drives record forms and the columns of the generated default list view. Until an order is saved, id, the native definition_id and natural_id and the inherited attributes such as location come first, followed by the definition's own attributes, and created_at, updated_at and lock_version come last.

updateVehicleAttributeOrder replaces the complete order, including the system attributes, the native fields and the inherited attributes. List every slug of the definition's attributes exactly once:

PUT /api/v2/definitions/vehicles/bicycle/attribute-order
Content-Type: application/json

{"attribute_slugs":["battery_wh","id","definition_id","natural_id","location","created_at","updated_at","lock_version"],"lock_version":0}

A missing, unknown or repeated slug returns 422 with one error per problem under #/attribute_slugs. Only the order changes; attribute values and records are untouched. Attributes added later, including reverse relationships and inherited attributes that appear after the order was saved, are appended at the end. A full replacement keeps the saved slots of the authored attributes and fills them in the submitted order. Managed definitions reject the request with 409 definitions/schema-locked.

This operation also exists as the MCP tool vehicle_definitions_update_attribute_order.

Configure record labels​

Set display_template when creating a definition, or update it with PATCH /api/v2/definitions/vehicles/{definition_ref} and the schemas:write grant:

{"display_template":"Bike {{frame_number}}","lock_version":0}

The template uses {{slug}} placeholders. It can read a column-backed custom attribute, such as text, VIN, license plate, number or state, and native fields: id, natural_id, definition_id, created_at, updated_at and lock_version. Business fields such as name or license_plate are available only when the selected definition declares those attributes. Other attribute types—relationships, locations, tags and skills—are not supported in Vehicle templates yet; referencing them returns 422. Supporting a type in record data does not imply it is available in a display template.

Reads and relationship references return the same computed display_name. A record edit is reflected immediately; changing the template changes labels without rewriting vehicle records. Templates have a maximum of 2,000 characters. Blank strings and unknown placeholders return 422. If no template is configured, labels use a nonblank text data.name, trimmed of surrounding whitespace, then fall back to the current natural_id. An explicit template always takes precedence; if it renders empty, the label uses natural_id.

PATCH accepts application/merge-patch+json and application/json. Omission preserves the template; {"display_template":null} clears it. The response contains the complete definition; an unset display_template is omitted. Optional lock_version protects against concurrent edits (409 when stale). An identical template or empty patch does not increment the version. System and plugin-managed definitions remain locked (409 definitions/schema-locked); record values remain editable through their record API. The same endpoint also edits names and slug, as described below.

Edit definitions and attributes​

All schema writes require schemas:write. System/plugin definitions and inherited or generated attributes stay locked. In particular, the built-in Vehicle location cannot be renamed or deleted.

OperationEndpointSuccess
Edit metadataPATCH /api/v2/definitions/vehicles/{definition_ref}200, complete definition
Edit an attributePATCH /api/v2/definitions/vehicles/{definition_ref}/attributes/{attribute_ref}200, complete definition
Delete an attributeDELETE /api/v2/definitions/vehicles/{definition_ref}/attributes/{attribute_ref}200, complete definition
Delete an empty definitionDELETE /api/v2/definitions/vehicles/{definition_ref}204, no body

Definition and attribute references accept UUIDs or slugs. Renames preserve their UUIDs, choice identities, existing values and relationships. The old slug stops resolving; UUID references remain valid. Slugs share the Object/Vehicle namespace, so a rename cannot take another definition's slug.

Metadata patches merge names by language and noun form. For example, {"name":{"en":{"singular":"Cycle"}},"slug":"cycles","lock_version":2} preserves the English plural and other languages. A null noun form or language removes it; at least one localized name must remain. Root name: null is rejected. An empty map preserves names.

Attribute patches merge type-specific configuration. For example:

{"slug":"range","description":null,"config":{"minimum":0,"default":null},"lock_version":3}

This renames the field, clears its description and default, and preserves other configuration. Unknown or inapplicable configuration returns 422. Type, uniqueness, relationship target and cardinality are immutable. A shape change requires a new attribute and an explicit value migration. options and states replace their complete arrays: retain IDs when editing existing choices and omit IDs for new choices. Removing a choice still used by a Vehicle returns 409. A default must also reference a retained choice, or be cleared in the same patch. Defaults/requiredness changes apply to subsequent record writes, without backfilling existing values.

A custom attribute rename updates its display-template placeholders and generated reverse relationship metadata. Named-location changes affect only Vehicles using that definition and update incoming tracking references. Deleting a location leaves incoming trackers without a resolved position; it does not clear the native Vehicle position.

Deleting an attribute removes its values, relationship edges/generated reverse fields, or its tags or skill associations in the same transaction. A display template referencing it must be edited first (422); workflow dependencies prevent deletion (409). Definition deletion never deletes Vehicles: remove the records and incoming schema dependencies first (409). The current record API does not yet offer Vehicle deletion, so this operation is presently useful for unused definitions. Managed schema edits/deletions return 409 definitions/schema-locked; editing an inherited or generated field on an otherwise editable definition returns 422. All these operations also exist under /frontend/v2 and through the corresponding vehicle_* MCP tools.

Work with vehicles​

OperationEndpointGrant
CreatePOST /api/v2/vehicles/{definition_ref}/recordsvehicles:create
List one definitionGET /api/v2/vehicles/{definition_ref}/recordsvehicles:read
ReadGET /api/v2/vehicles/{definition_ref}/records/{vehicle_id}vehicles:read
Read by unique attributeGET /api/v2/vehicles/{definition_ref}/records/by/{attribute_ref}?attribute_value=…vehicles:read
UpdatePATCH /api/v2/vehicles/{definition_ref}/records/{vehicle_id}vehicles:update
List across definitionsGET /api/v2/vehicles/recordsvehicles:read

Create a bicycle:

{"data":{"battery_wh":750,"frame_number":"FRAME-7"}}

The 201 response contains native fields (id, definition_id, natural_id, display_name, timestamps and lock_version) plus a data object keyed by custom attribute slug. The native UUID and sequence number remain stable. Absent optional values are omitted. Aggregate reads return the same shape for each vehicle.

Lists accept zero-based page, size from 1 to 100, and repeated sort=field:direction parameters. The default order is created_at:desc with an id tie-breaker. Scoped lists support sortable attributes and one to-one relationship.attribute paths. Scoped single-record reads and scoped lists also accept repeated include=<relationship_slug> parameters to expand named forward or reverse relationship pointers one level deep under record (nested relationships inside record stay compact). Aggregate lists use common fields only: id, natural_id, definition_id, created_at and updated_at. Both accept search, a literal case-insensitive substring of canonical display_name (maximum 256 characters, trimmed). Search precedes count and pagination. Unknown query parameters or unknown include relationship names return 422.

Use application/merge-patch+json for updates (application/json is also accepted):

{"lock_version":0,"data":{"battery_wh":800,"frame_number":null}}

Omitted fields retain their values. Explicit null within data clears an optional attribute; data itself cannot be null. An empty data object changes nothing. All attribute changes share one transaction and one version increment. Top-level business fields are rejected with 422. A semantic no-op does not increment the version. A stale version returns 409; invalid or duplicate values return 422 with field pointers. A vehicle addressed through the wrong definition returns 404. Definition assignment cannot be patched. BW's active-tour mutation restriction also applies to custom-only edits.

Definition deletion emits vehicle_definition.deleted. Creation emits vehicle_definition.created or vehicle.created; successful changes emit vehicle.updated or vehicle_definition.updated. Display-template updates include the previous display_template in data.previous_attributes, including null when previously unset. Attribute additions emit vehicle_definition.updated without a previous-attributes snapshot. These webhook representations contain the resource ID. Read the corresponding resource endpoint for its current state.

Look up a vehicle by a unique attribute​

A definition's unique attribute can identify a vehicle without knowing its UUID:

GET /api/v2/vehicles/bicycle/records/by/frame_number?attribute_value=FRAME-7

Both definition and attribute references accept a UUID or current slug. The response is the same complete Vehicle record as a read by UUID, including data, display_name, schema metadata and relationship previews. The lookup requires vehicles:read, is available under /frontend/v2 too, and has the MCP equivalent vehicle_records_get_by_unique_attribute. In the application, a Vehicle page addresses its record by natural ID or UUID (/app/vehicles/bicycle/BIKE-42); see Natural IDs.

Set config.is_unique: true when creating the attribute. This declares a key within that definition. Another definition may use the same value. A license_plate or vin type alone does not declare uniqueness. The lookup reads the selected attribute; it does not fall back to a legacy native field with a similar name.

Text keys match their stored value exactly, including case and surrounding spaces. This also applies to date/date-time strings used as unique keys. Numeric keys compare as decimals (7 and 7.00 match the same value). Select and state keys accept their option/state UUID or current value code. For attributes normalized on write, such as phone numbers, look up the stored canonical value.

Send attribute_value as a URL-encoded query parameter, preserving slashes, plus signs, question marks, hash signs, spaces and Unicode. Missing or blank keys return 422 at #/attribute_value. Unknown or non-unique attributes return 422 at #/attribute_ref; invalid numeric/choice keys return 422 at #/attribute_value. No matching record or definition returns 404.

Attribute UUID references continue to work after a slug rename. Clearing an optional key removes its match; it does not delete the vehicle. This follows the Object unique-attribute lookup contract.

Semantic identifiers and integer fields​

Vehicle definitions support license_plate and vin attributes in addition to text, number, and boolean. Each effective Vehicle definition may contain at most one field of each semantic identifier type, including inherited fields. The attribute slug is independent of its type. Identifier values remain editable free text; they are never automatically normalized or checked against a country-specific registration format or a VIN checksum.

Number configuration accepts is_integer: true to require whole numbers without rounding. For example, {"slug":"seats","type":"number","config":{"is_integer":true,"minimum":0}} accepts 4 and 4.0, rejects 4.5, and permits null unless is_required is also true.

Vehicle records expose business values only inside data; there is no second top-level license plate, name, capacity or active field. Business attribute slugs are available to tenant-owned definitions, and their configured validation applies consistently to creates and updates.

Tags and skills​

Declare these attributes using their reserved slugs: tags, provided_skills and required_skills. Each definition can declare at most one of each. provided_skills is the canonical name; offered_skills is not an alias. Each skill attribute holds a set, and a skill can appear in both roles. They accept arrays of IDs, exact labels, or reference objects such as {"id":"..."} and {"label":"Tail lift"}. Tags read back as {id, label, color} and skills as {id, label}. The resolved read shape can be sent back unchanged.

provided_skills describes capabilities a vehicle supplies. required_skills describes capabilities needed to work with it; the two collections are independent and may contain the same skill. Existing Vehicle skills appear as provided skills when the definition declares that attribute. The legacy Vehicle APIs continue to expose/update provided skills and preserve required skills.

For these attributes, omit to preserve the existing set, replace with the complete desired array, and use null or [] to clear an optional set. config.is_required: true requires at least one reference; this is separate from the meaning of the required_skills attribute. Defaults and uniqueness are unsupported for all three types. Reordering or duplicating references is a no-op. Unknown references return 422 at the attribute's field pointer; all changes in the same request roll back together. These attributes do not automatically configure tour eligibility or planning constraints.

Full definition replacement​

PUT /api/v2/definitions/vehicles/{definition_ref} uses ReplaceVehicleDefinition, matching Object definitions under /api/v2/definitions/objects/{definition_ref}. Send complete slug, name and attributes; attributes: [] explicitly removes the authored set, while an omitted array is a 422 error. Omitted display_template restores the name/natural-ID label fallback.

Existing attribute/choice IDs preserve identity across renames. Without an ID, an existing slug (or choice value) preserves its identity; new fields and choices omit IDs. Omitted owned fields are deleted. Inherited, native and generated reverse fields must be left out and are preserved. The template is validated against the final schema. The entire replacement is transactional, including value constraints, relationships and location cleanup. Failure leaves the old definition and records intact. An optional lock_version guards against concurrent edits.

Use metadata/attribute PATCH for ordinary editing. PUT is intended for synchronizing a complete authored schema; the effective GET response also includes read-only descriptors and is not a PUT body.

Query Vehicle records​

Scoped Vehicles use the same flat filter and sort grammar as Object records. The selected definition determines the available fields:

POST /api/v2/vehicles/bicycle/records/query
Content-Type: application/json
{
"filter": {"battery_wh": {"gte": 500}},
"sort": ["battery_wh:desc"],
"page": 0,
"size": 20
}

The response is the ordinary {items, page} Vehicle collection, including each record's data. Do not prefix query fields with data or a definition slug. A path definition is mandatory scope; no filter can select records outside it.

POST /api/v2/vehicles/records/query queries all definitions using common fields only: id, definition_id, natural_id, created_at, and updated_at. For example:

{"filter":{"definition_id":{"in":["20000000-0000-4000-8000-000000000001"]}},"sort":["natural_id:asc"]}

Filtering definition_id does not enable definition-specific fields. Use the scoped URL for those. There is no top-level definition_id selector or data.<definition>.<attribute> query syntax. natural_id filters use the displayed string; sorting uses the prefix and numeric sequence.

Both query endpoints accept filter, sort, search, page and size; scoped queries also accept include (an array of relationship attribute slugs to expand one level under record). Search has the same canonical-label semantics as GET. page starts at zero; size defaults to 20 and is limited to 100. The default sort is created_at:desc with an ID tiebreaker. Ascending nulls sort last; descending nulls first. Attribute filters and sorting execute before counting and pagination.

Use the definition's filter_operators and is_sortable metadata. Supported operators depend on type: equality, comparisons, in, literal case-insensitive contains/starts_with/ends_with, is_null, and multi-select containment. Choice operands accept their value code or UUID. Dates use YYYY-MM-DD; timestamps require an explicit UTC offset. REST does not accept relative expressions such as now-6h. and/or contain arrays, not contains one filter, and sibling fields are ANDed. Filters are limited to four levels. Unknown fields, invalid operands and unsupported sort paths return field-level 422 errors, including on empty collections.

POST /api/v2/vehicles/{definition_ref}/records/{vehicle_id}/related/{attribute_ref}/query

This queries the complete linked set with filter, sort, page, and size, returning canonical records in {kind, record} wrappers. A concrete target definition exposes its flat attributes; a Vehicle-family target exposes only common Vehicle fields. Object-to-Vehicle related queries follow the same rule. User filters cannot escape the linked set.

Scoped filters can traverse relationships existentially (for example, {"assigned_to":{"label":{"eq":"Vienna"}}}). Sorts may traverse one to-one relationships once; to-many and chained paths are rejected. Target read access is required even if the result is empty. Location, tag, skill, raw JSON, rich text, full name and links attributes do not have scalar query columns; the Vehicle query surface currently supports column-backed scalar fields and catalog relationships. Rich text, full names and links still accept the contains filter on their text projection, and full names can be sorted.

These read-only operations require vehicles:read, run under a ten-second execution deadline, and return 503 (records/query-timeout) if that deadline expires. They are also exposed under /frontend/v2 and as vehicle_records_query, vehicle_records_query_all and vehicle_records_query_related MCP tools.

Native fields in definition metadata​

Vehicle definition responses and GET /api/v2/definitions/all/{definition_ref} include definition_id and natural_id in attributes, alongside the common system fields. Both are required, read-only, system-managed text fields. definition_id has no attribute UUID; it identifies the concrete Vehicle Definition; natural_id is the formatted human-readable record ID, including its configured prefix and retains its stored attribute UUID and translations. These fields are already present on Vehicle record responses and in GraphQL. They are native record fields: do not include them in custom attribute writes or the record data bag.