Working with assets
Create and manage assets — vehicles, equipment, and other tracked objects.
Navixy Repository API is a work in progress. This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.
Assets in Navixy Repository API represent the physical or logical objects your organization tracks and manages. The most common example is a vehicle, but assets can be anything you need to monitor: construction equipment, forklifts, generators, shipping containers, leased machinery, or fixed infrastructure. If your organization has a reason to record it, assign attributes to it, or link a GPS device to it, it's a good candidate for an asset.
Each asset is defined by the asset type, which acts as a template: it classifies the asset and determines which custom fields are available for it. For example, a "Delivery Truck" type might have fields for license plate, fuel capacity, and assigned driver, while a "Generator" type might have fields for power output, last service date, and installation site.
To organize assets into named collections, such as grouping vehicles by depot or equipment by project, see Organizing assets into groups.
Before you start
You need your organization's ID for all asset operations. Use the me query to retrieve it:
query GetMyOrganization {
me {
... on User {
memberships {
nodes {
organization {
id
title
}
}
}
}
}
}The ... on User inline fragment is required because me returns the Actor interface, which can resolve to either a User or an Integration. The memberships field only exists on User, so the fragment ensures the query is valid for both actor types. If you authenticate as an Integration, the memberships block is omitted from the response.
You'll receive a response:
Use the id of the organization you want to work with for all subsequent geo object operations.
Check available asset types
Before creating an asset, request the available asset types for your organization:
You'll get an array of types, if any exist:
If you need a type that doesn't exist yet, you can create it as described in the scenario below.
If you're working with an existing type and need to know which custom fields it has, query customFieldDefinitions on the type:
Response:
The code values here are exactly what you use as keys in customFields.set when creating or updating assets of this type. For type-specific parameters like maximum string length or the list of valid options, see Implementing custom fields.
Understanding assets
Asset types
An asset type classifies assets and defines which custom fields they have. It is a catalog item: it has a code (a stable machine-readable identifier), a title (the display name), and meta properties for UI customization. The customFieldDefinitions field lists all custom fields available on assets of that type.
Before creating a type, remember that code is immutable after creation. Choose it carefully, since it's what integrations and filters will use to reference the type.
Before deleting an asset type, check meta.canBeDeleted. The API rejects deletion if the type still has dependent assets or is system-managed. Query meta { canBeDeleted } on the type to verify before calling assetTypeDelete.
Types can originate from three places: predefined by the platform (SYSTEM), created by your organization (ORGANIZATION), or inherited from a parent organization in the dealer hierarchy (PARENT_ORGANIZATION). The origin is exposed as meta.origin on the type. You can only create, update, and delete types with ORGANIZATION origin — system and inherited types are read-only. The organization field on an asset type is null for SYSTEM-origin types, since they're not owned by any single organization.
For the full field reference, see AssetType.
Asset fields
An asset has a title, belongs to an organization, and is classified by an asset type. Its dynamic attributes are listed in customFields, and it uses the device field as a shortcut to the linked GPS device. Assets also have a groups connection field that returns the asset groups they belong to, with optional filtering, ordering, and pagination arguments.
For the full field reference, see Asset object.
Custom fields
Assets store their domain-specific attributes in the customFields field. When creating or updating an asset, you pass custom field changes using CustomFieldsPatchInput, which has two sub-fields:
customFields is always a patch operation: fields you don't mention are left unchanged. To update one field without touching others, include only that field in set. To remove a value entirely, list its code in unset.
See Implementing custom fields for details on defining field definitions and the supported field types.
The device field
The device field on an asset is a first-class alias for a system-level custom field that stores a reference to a GPS device. The underlying custom field key is device, and its value is the device's ID as a plain string. The device field resolves that ID into a full Device object, so you can query device details directly from the asset without a separate lookup.
To link a device when creating or updating an asset, pass the device ID under set in customFields:
To unlink a device without touching other fields:
Example scenario: Registering a logistics fleet
TransLog GmbH is setting up their asset registry. They need to track both their delivery trucks (with GPS devices) and warehouse forklifts (without GPS devices). This scenario walks through creating an asset type, registering assets, and maintaining the registry over time.
Create an asset type
Start by creating a "Delivery Truck" asset type for your organization. Be careful when choosing the code — it's immutable after creation and will be used to reference this type in integrations and filters.
Run this mutation:
Response:
Save the id and version — you'll need the id to create assets of this type, and version if you later need to update or delete the type.
The order field controls how types appear in UI lists. Lower numbers appear first. If display order doesn't matter for your use case, you can omit it — it defaults to 0.
Verify the asset
Query the asset to confirm it was created correctly:
Response:
device is null because no GPS unit has been assigned yet. customFields returns a raw JSON object keyed by field code — the same keys you use in set and unset.
To keep the response lean, you can request only specific custom field codes:
Assign a device
A GPS unit has been installed in the truck. Assign it using assetUpdate with the device ID in customFields.set. The operation is identical whether you're making an initial assignment or replacing an existing one.
Run this mutation:
Response:
Note that version increments to 2 after a successful update. Use this new version for any further mutations.
To unassign the device (e.g., if the unit is removed for maintenance), use unset:
After unlinking, device returns null.
Delete the asset
Asset deletion is permanent. Unlike some other entity types in the API, assets don't support soft delete and cannot be restored after deletion. Make sure you no longer need the record before proceeding.
When the truck is decommissioned and you no longer need its record, run the assetDelete mutation:
Response:
The version field ensures you don't accidentally delete an asset that someone else has modified since you last fetched it.
Listing assets
To list all assets for an organization, run the following query:
Filtering
Use AssetFilter to narrow results by type, linked GPS device, title, or custom field values. Conditions across different fields are combined with AND, while multiple values within a single field are combined with OR. For the full filter field reference and custom field filter operators, see Filtering and sorting.
To find all assets linked to a specific GPS device, run this query:
To filter assets by a custom field value, pass conditions to customFields in the filter. Each condition specifies a field code, a comparison operator, and a value. The following query finds all delivery trucks with a specific license plate:
Multiple conditions in the customFields array are combined with AND.
Ordering
Assets can be ordered by title (the default) or by any custom field using customFieldCode:
field (an AssetOrderField enum) and customFieldCode are mutually exclusive — use one or the other. Valid values for field are defined in the AssetOrderField enum.
For details on pagination, see Pagination.
Handling version conflicts
If another client updates an asset between when you fetched it and when you submit your mutation, the API returns a conflict error:
To resolve this, query the asset to get its current version and state, merge your intended changes, and retry the mutation with the updated version.
For a full explanation of how versioning works, see Optimistic locking.
See also
Asset types and operations: Complete reference for all asset operations and types
Organizing assets into groups: Collect assets into named groups by depot, project, or any other dimension
Implementing custom fields: Define the properties available to each asset type
Last updated
Was this helpful?