Inventory API V2 Migration Guide

This guide describes the changes introduced in the V2 Inventory API compared to V1, and provides a migration path for developers transitioning their integrations.

The V2 API is now stable under the v2 path. The V1 API (v1-earlyaccess) remains available during the transition period but is deprecated. Endpoints that were previously available under v2-earlyaccess remain callable through that prefix, but integrations should be migrated to use v2.

Why V2

The V1 Inventory API reached its limits in several areas. Assets without a MAC address could not be created, which prevented onboarding of brownfield equipment that uses proprietary or domain-specific identifiers. Relationships between assets -- such as parent-child hierarchies, gateway associations, and software component assignments -- were modeled as static inline properties, making them difficult to extend or query independently. Software components installed on or running on an asset had no first-class representation and could not be tracked through relations. In addition, returning all assets in a single unbounded GET response caused performance degradation for tenants with large inventories.

The V2 API addresses these limitations by introducing custom identifiers, a flexible relations model for asset-to-asset and asset-to-software-component linkage, and mandatory pagination with asynchronous write operations to improve throughput and reliability at scale.

Overview of changes

The V2 Inventory API introduces the following key changes:

• Asynchronous operations -- write operations (POST, PATCH, DELETE) return 202 Accepted with a status ID instead of completing synchronously.
• Mandatory pagination -- the GET assets endpoint enforces pagination with a default limit of 50 and a maximum of 100 assets per request.
• Schema enforcement -- the asset schema is now enforced on all write operations. In V1, the schema was only a recommendation.
• Dedicated PATCH endpoints -- the generic PATCH endpoint is replaced by property-specific endpoints with validated request schemas.
• Relations model -- data previously returned as inline properties (such as gateway linkage or parent-child relationships) is now modeled as relations and retrieved through separate endpoints.

Breaking changes

Asynchronous write operations

All write operations now return HTTP 202 Accepted with a status ID in the response body. Poll the status endpoint to determine whether the operation completed successfully.

Operation	V1 behavior	V2 behavior
Create asset (POST)	Synchronous, returns the created asset	Returns 202 with a status ID
Delete asset (DELETE)	Synchronous, returns 204	Returns 202 with a status ID
Update asset (PATCH)	Synchronous, returns the updated asset	Returns 202 with a status ID

To check the result of an asynchronous operation, call the status endpoint with the returned status ID. The response includes a state (queued, finished, or failed) and a detail.result field with the outcome.

Mandatory pagination on GET assets

The GET assets endpoint no longer returns all assets in a single response.

Parameter	Default	Maximum
limit	50	100
offset	0	--

The response meta object contains totalElements, elements, and offset to support client-side pagination logic.

Generic PATCH endpoint removed

The generic PATCH endpoint that accepted arbitrary JSON merge patches is no longer available. Use the dedicated endpoints for each property:

Property	V2 endpoint
Management state	PATCH /assets/{id}/management-state
Reachability state	PATCH /assets/{id}/reachability-state
Trust state	PATCH /assets/{id}/trust-state
Firmware version	PATCH /assets/{id}/firmware-version
Gateway version	PATCH /gateways/{id}/version
Access group	PATCH /assets/{id}/access-group
Responsible	PATCH /assets/{id}/responsible
Custom property values	PATCH /asset-property-values

Each endpoint validates the request body against a dedicated schema.

Identifiers removed from GET response

Asset identifiers (MAC identifiers, software identifiers, and other identifier types) are no longer included in the GET assets response by default. Retrieve them separately:

GET /assets/{id}/identifiers

Identifiers are used internally for asset deduplication and are typically not needed by consuming applications.

Response model changes

The asset response model has changed. The following table maps V1 properties to their V2 equivalents:

V1 property	V2 equivalent	Notes
@type	Removed	Use functional_object_type instead
@context	Removed	Use functional_object_schema_url instead
--	functional_object_type	New field. Values: asset, device, gateway, software_artifact
--	functional_object_schema_url	New field. Points to the JSON schema for this asset
zone	access_group	Renamed. Semantically equivalent
product_instance_identifier	product_instance_information	Renamed. Content structure unchanged (serial number, manufacturer, product ID)
trust_established_state	trust_state	Renamed
custom_ui_properties	custom_properties	Renamed
instance_annotations	instance_annotations	Unchanged (key-value pairs)
mounting_location (top-level)	location (array with typed entries)	Restructured. Supports mounting location, geo location, and postal address
JSON-LD metadata fields	Removed	Replaced by functional_object_schema_url
Inline gateway reference	Relation	Retrieve through the relations endpoint
Inline identifiers	Separate endpoint	GET /assets/{id}/identifiers

Relations replace inline properties

Data that was previously embedded in the asset response is now modeled as relations. Relations use a triple structure: subject -> predicate -> object.

Retrieve relations through the GET /relations endpoint with appropriate filters.

Currently supported system-managed predicates:

• found_by_gateway -- links an asset to the gateway that discovered it
• found_by_asset_link -- links an asset to the asset link that discovered it
• is_installed_on -- links a software component or asset link to its host
• is_running_on -- links a running asset link instance to its host

Note: Retrieving gateway information for an asset now requires two API calls (get the asset, then query its relations) instead of reading an inline property.

New features

Case-insensitive filtering

The GET assets endpoint supports a case-insensitive filter option. When using the case-insensitive filter, string comparisons ignore character casing. For example, filtering for manufacturer "siemens" matches "Siemens", "SIEMENS", and "siemens".

Custom identifiers

Assets can now be created without a MAC address by providing custom identifiers. This enables scenarios such as:

• Importing brownfield plant data with proprietary identifier schemes (DDX import)
• Onboarding assets that use domain-specific identifiers instead of standard network identifiers

Custom relations

In addition to system-managed relations, custom relations can be created to model domain-specific relationships between assets. Use cases include:

• Assigning assets to a plant topology or context hierarchy
• Modeling maintenance cycles or organizational groupings
• Creating any customer-defined relationship type

Asset link modeling through relations

Asset links installed on gateways are now represented through relations. This provides visibility into:

• Which asset links are installed on a gateway
• Which asset links are currently running
• The relationship between asset links and the assets they discover

Bulk operation endpoints

Several V2 endpoints accept arrays of items in a single request, reducing the number of API calls needed for large-scale updates. The following endpoints support bulk operations:

• PATCH /asset-responsible
• PATCH /asset-property-values
• DELETE /asset-property-values
• PATCH /management-states
• PATCH /asset-access-groups
• DELETE /assets

The DELETE /relations/query-results endpoint provides an alternative bulk deletion approach: instead of listing individual IDs, the delete scope is described by a filter query, which removes the need to paginate through large result sets first.

Standardized operation and mode names

Asset operation names and operating modes follow a standardized naming convention defined in the asset schema. This ensures consistency across different discovery sources.

Extended product instance information

The product_instance_information object can now include additional fields defined in the schema:

• product_link
• product_version
• product_name
• product_family

These fields are optional and depend on the data provided by the discovery source.

Known limitations

• Sorting on array properties -- sorting is not supported for properties that contain arrays. This limitation also existed in V1.
• Dedicated PATCH endpoints in progress -- additional PATCH endpoints may be added based on integration partner feedback. Contact the IAH team if you need a PATCH endpoint for a property not listed above.
• No network zone information -- the zone property has been renamed to access_group and does not represent network segmentation or subnet information. Network-level information is limited to MAC address and IP address.

Migration checklist

Use this checklist when migrating an integration from V1 to V2:

• [ ] Update base path -- change API calls from /inventory/v1-earlyaccess/ to /inventory/v2/.
• [ ] Handle asynchronous responses -- update POST, PATCH, and DELETE handlers to expect 202 Accepted and implement status polling.
• [ ] Implement pagination -- add pagination logic (limit/offset) to GET assets calls. Do not assume all assets are returned in a single response.
• [ ] Replace generic PATCH calls -- map each property update to its dedicated PATCH endpoint.
• [ ] Update response parsing -- adapt to the new response model:
• [ ] Remove parsing of @type and @context.
• [ ] Use functional_object_type and functional_object_schema_url.
• [ ] Rename zone references to access_group.
• [ ] Rename product_instance_identifier to product_instance_information.
• [ ] Rename custom_ui_properties to custom_properties.
• [ ] Adapt location parsing to handle the new array structure with typed entries.
• [ ] Retrieve identifiers separately -- if your integration uses asset identifiers, add a call to GET /assets/{id}/identifiers.
• [ ] Retrieve relations separately -- if your integration uses gateway or parent-child information, query the GET /relations endpoint.
• [ ] Test with pre-production tenant -- validate the migration against a pre-production environment before switching production integrations.

Any questions left?

Ask the community