Skip to main content

Assets API

Authentication: every request needs an IdToken — see Authentication. Error shapes: Errors.

Endpoint: POST https://api.xemelgo.com/graphql

Queries​

assetRoute​

Returns the location route history for an asset over a time window.

query AssetRoute($input: AssetRouteInput) {
assetRoute(input: $input) {
nextToken
route {
customProperties
duration
endDate
startDate
state
location {
id
name
}
}
}
}
Example variables
{
"input": {
"endDate": 1719792000000,
"id": "assetroute-001",
"nextToken": "eyJpZCI6IjEwMjQifQ==",
"startDate": 1719792000000
}
}
Example response
{
"data": {
"assetRoute": {
"nextToken": "eyJpZCI6IjEwMjQifQ==",
"route": [
{
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"duration": 1719792000000,
"endDate": 1719792000000,
"startDate": 1719792000000,
"state": "ACTIVE",
"location": {
"id": "location-001",
"name": "Forklift 7"
}
}
]
}
}
}

Arguments​

input · AssetRouteInput

AssetRouteInput​

Input for the assetRoute query, identifying the asset and time window.

FieldTypeDescription
endDateAWSTimestampEpoch-millisecond end timestamp for the route window.
idString!Unique identifier of the asset whose route is requested.
nextTokenStringPagination token to retrieve the next page of results.
startDateAWSTimestampEpoch-millisecond start timestamp for the route window.

Returns​

AssetRoutePayload

AssetRoute​

A single segment of an asset's location route.

FieldTypeDescription
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
durationAWSTimestampTime spent at this location, in milliseconds.
endDateAWSTimestampEpoch-millisecond timestamp of last detection at this location.
locationLocationV2Location for this route segment.
startDateAWSTimestampEpoch-millisecond timestamp of first detection at this location.
stateStringState of the asset at this location (e.g. onhand, removed).
AssetRoutePayload​

Result of the assetRoute query.

FieldTypeDescription
nextTokenStringPagination token to retrieve the next page of results.
route[AssetRoute!]Ordered route segments for the asset.

assets​

Lists assets matching the given filter.

query Assets($input: AssetsInput) {
assets(input: $input) {
nextToken
assets {
comments
containerId
creationDate
customProperties
description
dueDate
id
images
lastDetectionDate
lastUpdatedDate
name
quantity
requestStatus
state
transferOrderId
transferStatus
uuid
lastDetectedAtLocation {
id
name
}
location {
id
name
}
owner {
id
}
trackers {
serial
}
type {
id
name
number
}
}
}
}
Example variables
{
"input": {
"filter": "name:\"Forklift*\"",
"nextToken": "eyJpZCI6IjEwMjQifQ=="
}
}
Example response
{
"data": {
"assets": {
"nextToken": "eyJpZCI6IjEwMjQifQ==",
"assets": [
{
"comments": "Inspected and approved",
"containerId": "container-001",
"creationDate": 1719792000000,
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"dueDate": 1719792000000,
"id": "asset-001",
"images": [
"https://cdn.example.com/asset-1024.png"
],
"lastDetectionDate": 1719792000000,
"lastUpdatedDate": 1719792000000,
"name": "Forklift 7",
"quantity": 1,
"requestStatus": "AVAILABLE",
"state": "ACTIVE",
"transferOrderId": "transferorder-001",
"transferStatus": "example",
"uuid": "uu-001",
"lastDetectedAtLocation": {
"id": "location-001",
"name": "Forklift 7"
},
"location": {
"id": "location-001",
"name": "Forklift 7"
},
"owner": {
"id": "assetowner-001"
},
"trackers": [
{
"serial": "E28011700000020ABC12345"
}
],
"type": {
"id": "assettype-001",
"name": "Forklift 7",
"number": "AST-1024"
}
}
]
}
}
}

Arguments​

input · AssetsInput

AssetsInput​

Input for the assets query, supporting filtering and pagination.

FieldTypeDescription
filterStringFilter expression for asset properties.
nextTokenStringPagination token to retrieve the next page of results.

Returns​

AssetsPayload

AssetsPayload​

Result of the assets query.

FieldTypeDescription
assets[Asset!]!Matching assets for this page.
nextTokenStringPagination token to retrieve the next page of results.

assetTypes​

Lists asset types matching the given filter.

query AssetTypes($input: AssetTypesInput) {
assetTypes(input: $input) {
nextToken
assetTypes {
creationDate
customProperties
description
id
images
lastUpdatedDate
name
number
quantity
unit
uuid
categories {
id
name
}
customerAssetTypes {
customerAssetTypeId
customerId
}
}
}
}
Example variables
{
"input": {
"filter": "name:\"Forklift*\"",
"nextToken": "eyJpZCI6IjEwMjQifQ=="
}
}
Example response
{
"data": {
"assetTypes": {
"nextToken": "eyJpZCI6IjEwMjQifQ==",
"assetTypes": [
{
"creationDate": 1719792000000,
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"id": "assettype-001",
"images": [
"https://cdn.example.com/asset-1024.png"
],
"lastUpdatedDate": 1719792000000,
"name": "Forklift 7",
"number": "AST-1024",
"quantity": 10,
"unit": "EA",
"uuid": "uu-001",
"categories": [
{
"id": "assettypecategory-001",
"name": "Forklift 7"
}
],
"customerAssetTypes": [
{
"customerAssetTypeId": "customerassettype-001",
"customerId": "customer-001"
}
]
}
]
}
}
}

Arguments​

input · AssetTypesInput

AssetTypesInput​

Input for the assetTypes query, supporting filtering and pagination.

FieldTypeDescription
filterStringFilter expression for asset type properties.
nextTokenStringPagination token to retrieve the next page of results.

Returns​

QueryAssetTypesPayload

QueryAssetTypesPayload​

Result of the assetTypes query.

FieldTypeDescription
assetTypes[AssetType!]!Matching asset types for this page.
nextTokenStringPagination token to retrieve the next page of results.

Mutations​

createAssets​

Creates one or more assets. If creation succeeds but complete asset details are unavailable, the response includes the created assets' id and uuid, along with an error. Do not retry creation for those assets.

mutation CreateAssets($input: CreateAssetsInput!) {
createAssets(input: $input) {
assets {
comments
containerId
creationDate
customProperties
description
dueDate
id
images
lastDetectionDate
lastUpdatedDate
name
quantity
requestStatus
state
transferOrderId
transferStatus
uuid
lastDetectedAtLocation {
id
name
}
location {
id
name
}
owner {
id
}
trackers {
serial
}
type {
id
name
number
}
}
}
}
Example variables
{
"input": {
"assets": [
{
"comments": "Inspected and approved",
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"customerAssetTypeId": "customerassettype-001",
"description": "Electric counterbalance forklift",
"dueDate": 1719792000000,
"id": "createasset-001",
"images": [
"https://cdn.example.com/asset-1024.png"
],
"locationId": "location-001",
"name": "Forklift 7",
"trackers": [
{
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"encodingFormat": "example",
"reuseTrackerSerial": false,
"serial": "E28011700000020ABC12345"
}
],
"typeId": "type-001"
}
]
}
}
Example response
{
"data": {
"createAssets": {
"assets": [
{
"comments": "Inspected and approved",
"containerId": "container-001",
"creationDate": 1719792000000,
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"dueDate": 1719792000000,
"id": "asset-001",
"images": [
"https://cdn.example.com/asset-1024.png"
],
"lastDetectionDate": 1719792000000,
"lastUpdatedDate": 1719792000000,
"name": "Forklift 7",
"quantity": 1,
"requestStatus": "AVAILABLE",
"state": "ACTIVE",
"transferOrderId": "transferorder-001",
"transferStatus": "example",
"uuid": "uu-001",
"lastDetectedAtLocation": {
"id": "location-001",
"name": "Forklift 7"
},
"location": {
"id": "location-001",
"name": "Forklift 7"
},
"owner": {
"id": "assetowner-001"
},
"trackers": [
{
"serial": "E28011700000020ABC12345"
}
],
"type": {
"id": "assettype-001",
"name": "Forklift 7",
"number": "AST-1024"
}
}
]
}
}
}

Arguments​

input · CreateAssetsInput!

CreateAssetInput​

Definition of a single asset to create.

FieldTypeDescription
commentsStringAny comments or remarks for the asset.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
customerAssetTypeIdStringOptional asset type identifier used by your customer.
descriptionStringFree-text description of the asset.
dueDateAWSTimestampEpoch-millisecond timestamp when the asset is due for maintenance or calibration.
idString!Serial or unique identifier for the asset.
images[String]Public image URLs for the asset.
locationIdStringIdentifier of the location of the asset.
nameStringDisplay name of the asset.
trackers[TrackerInput!]Trackers to attach to the asset.
typeIdString!Identifier of the asset type this asset is associated with.
CreateAssetsInput​

Input for the createAssets mutation, carrying the assets to create.

FieldTypeDescription
assets[CreateAssetInput!]!Assets to create.

Returns​

CreateAssetsPayload

CreateAssetsPayload​

Result of the createAssets mutation.

FieldTypeDescription
assets[Asset!]The created assets.

createAssetTypes​

Creates one or more asset types and returns their identifiers.

mutation CreateAssetTypes($input: CreateAssetTypesInput!) {
createAssetTypes(input: $input) {
assetTypeIds
}
}
Example variables
{
"input": {
"assetTypes": [
{
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"customerAssetTypes": [
{
"customerAssetTypeId": "customerassettype-001",
"customerId": "customer-001"
}
],
"description": "Electric counterbalance forklift",
"id": "createassettype-001",
"images": [
"https://cdn.example.com/asset-1024.png"
],
"name": "Forklift 7",
"number": "AST-1024",
"quantity": 10,
"unit": "EA"
}
]
}
}
Example response
{
"data": {
"createAssetTypes": {
"assetTypeIds": [
"example"
]
}
}
}

Arguments​

input · CreateAssetTypesInput!

CreateAssetTypeInput​

Definition of a single asset type to create.

FieldTypeDescription
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
customerAssetTypes[CustomerAssetTypeInput!]Customer-specific asset type identifiers mapped to this asset type.
descriptionStringFree-text description of the asset type.
idString!Unique identifier of the asset type, usually the asset type number or SKU.
images[String!]Public image URLs for the asset type.
nameStringDisplay name of the asset type.
numberStringAsset type number.
quantityIntExpected quantity of the asset type.
unitStringUnit of measure of the asset type.
CreateAssetTypesInput​

Input for the createAssetTypes mutation, carrying the asset types to create.

FieldTypeDescription
assetTypes[CreateAssetTypeInput!]Asset types to create.
CustomerAssetTypeInput​

Mapping of a customer to one of its asset type identifiers.

FieldTypeDescription
customerAssetTypeIdString!Customer-specific asset type identifier.
customerIdString!Unique identifier of the customer.

Returns​

CreateAssetTypesPayload

CreateAssetTypesPayload​

Result of the createAssetTypes mutation.

FieldTypeDescription
assetTypeIds[String]Identifiers of the created asset types.

deleteAssets​

Deletes one or more assets and returns their identifiers.

mutation DeleteAssets($input: DeleteAssetsInput!) {
deleteAssets(input: $input) {
assetIds
}
}
Example variables
{
"input": {
"assetIds": [
"example"
]
}
}
Example response
{
"data": {
"deleteAssets": {
"assetIds": [
"example"
]
}
}
}

Arguments​

input · DeleteAssetsInput!

DeleteAssetsInput​

Input for the deleteAssets mutation, listing the assets to delete.

FieldTypeDescription
assetIds[String!]!Identifiers of the assets to delete.

Returns​

DeleteAssetsPayload

DeleteAssetsPayload​

Result of the deleteAssets mutation.

FieldTypeDescription
assetIds[String!]!Identifiers of the deleted assets.

updateAssets​

Updates one or more assets and returns the updated assets.

mutation UpdateAssets($input: UpdateAssetsInput!) {
updateAssets(input: $input) {
assets {
comments
containerId
creationDate
customProperties
description
dueDate
id
images
lastDetectionDate
lastUpdatedDate
name
quantity
requestStatus
state
transferOrderId
transferStatus
uuid
lastDetectedAtLocation {
id
name
}
location {
id
name
}
owner {
id
}
trackers {
serial
}
type {
id
name
number
}
}
}
}
Example variables
{
"input": {
"assets": [
{
"id": "updatedasset-001",
"updates": {
"addTrackers": [
{
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"encodingFormat": "example",
"reuseTrackerSerial": false,
"serial": "E28011700000020ABC12345"
}
],
"comments": "Inspected and approved",
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"dueDate": 1719792000000,
"id": "asset-001",
"images": [
"https://cdn.example.com/asset-1024.png"
],
"locationId": "location-001",
"name": "Forklift 7",
"removeTrackerSerials": [
"E28011700000020ABC12345"
],
"state": "ACTIVE",
"typeId": "type-001"
}
}
]
}
}
Example response
{
"data": {
"updateAssets": {
"assets": [
{
"comments": "Inspected and approved",
"containerId": "container-001",
"creationDate": 1719792000000,
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"dueDate": 1719792000000,
"id": "asset-001",
"images": [
"https://cdn.example.com/asset-1024.png"
],
"lastDetectionDate": 1719792000000,
"lastUpdatedDate": 1719792000000,
"name": "Forklift 7",
"quantity": 1,
"requestStatus": "AVAILABLE",
"state": "ACTIVE",
"transferOrderId": "transferorder-001",
"transferStatus": "example",
"uuid": "uu-001",
"lastDetectedAtLocation": {
"id": "location-001",
"name": "Forklift 7"
},
"location": {
"id": "location-001",
"name": "Forklift 7"
},
"owner": {
"id": "assetowner-001"
},
"trackers": [
{
"serial": "E28011700000020ABC12345"
}
],
"type": {
"id": "assettype-001",
"name": "Forklift 7",
"number": "AST-1024"
}
}
]
}
}
}

Arguments​

input · UpdateAssetsInput!

AssetUpdates​

Updates to apply to a single asset.

FieldTypeDescription
addTrackers[TrackerInput!]Trackers to attach to the asset.
commentsStringAny comments or remarks for the asset.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
descriptionStringFree-text description of the asset.
dueDateAWSTimestampEpoch-millisecond timestamp when the asset is due for maintenance or calibration.
idStringUnique identifier of the asset to update.
images[String]Public image URLs for the asset.
locationIdStringIdentifier of the location to move the asset to.
nameStringDisplay name of the asset.
removeTrackerSerials[String!]Tracker serials to detach from the asset.
stateStringCurrent state of the asset at its location (e.g. onhand, removed).
typeIdStringIdentifier of the asset type this asset is associated with.
UpdateAssetsInput​

Input for the updateAssets mutation, carrying the asset updates to apply.

FieldTypeDescription
assets[UpdatedAsset!]!Assets to update.
UpdatedAsset​

A single asset update entry, pairing an asset id with its updates.

FieldTypeDescription
idString!Unique identifier of the asset to update.
updatesAssetUpdatesUpdates to apply to the asset.

Returns​

UpdateAssetsPayload

UpdateAssetsPayload​

Result of the updateAssets mutation.

FieldTypeDescription
assets[Asset!]The updated assets.

updateAssetTypes​

Updates one or more asset types and returns their identifiers.

mutation UpdateAssetTypes($input: UpdateAssetTypesInput!) {
updateAssetTypes(input: $input) {
assetTypeIds
}
}
Example variables
{
"input": {
"assetTypes": [
{
"id": "updateassettype-001",
"updates": {
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"id": "assettype-001",
"images": [
"https://cdn.example.com/asset-1024.png"
],
"name": "Forklift 7",
"number": "AST-1024",
"quantity": 10,
"unit": "EA"
}
}
]
}
}
Example response
{
"data": {
"updateAssetTypes": {
"assetTypeIds": [
"example"
]
}
}
}

Arguments​

input · UpdateAssetTypesInput!

AssetTypeUpdates​

Asset type updates.

FieldTypeDescription
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
descriptionStringFree-text description of the asset type.
idString!Unique identifier of the asset type to update.
images[String!]Public image URLs for the asset type.
nameStringDisplay name of the asset type.
numberStringAsset type number.
quantityIntExpected quantity of the asset type.
unitStringUnit of measure of the asset type.
UpdateAssetTypeInput​

Updates to apply to a single asset type.

FieldTypeDescription
idString!Unique identifier of the asset type to update.
updatesAssetTypeUpdatesUpdates to apply to the asset type.
UpdateAssetTypesInput​

Input for the updateAssetTypes mutation, carrying the asset type updates to apply.

FieldTypeDescription
assetTypes[UpdateAssetTypeInput!]Asset types to update.

Returns​

UpdateAssetTypesPayload

UpdateAssetTypesPayload​

Result of the updateAssetTypes mutation.

FieldTypeDescription
assetTypeIds[String]Identifiers of the updated asset types.

Shared types​

Entity types used across multiple operations on this page. Type names throughout link here.

Asset​

A tracked asset.

FieldTypeDescription
commentsStringAny comments or remarks for the asset.
containerIdStringIdentifier of the container holding this asset, if any.
creationDateAWSTimestampEpoch-millisecond timestamp when the asset was created.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
descriptionStringFree-text description of the asset.
dueDateAWSTimestampEpoch-millisecond timestamp when the asset is due for maintenance or calibration.
idStringUnique identifier of the asset, usually the asset number.
images[String]Public image URLs for the asset.
lastDetectedAtLocationLocationV2Location where the asset was last detected.
lastDetectionDateAWSTimestampEpoch-millisecond timestamp when the asset was last detected.
lastUpdatedDateAWSTimestampEpoch-millisecond timestamp when the asset was last updated.
locationLocationV2Location where the asset is currently tracked.
nameStringDisplay name of the asset.
ownerAssetOwnerCurrent owner of the asset, set via an Owner Change asset request.
quantityFloatQuantity represented by this asset record.
requestStatusRequestStatusCurrent asset request status of the asset.
stateStringCurrent state of the asset at its location (e.g. onhand, removed).
trackers[Tracker]Trackers currently attached to this asset.
transferOrderIdStringIdentifier of the transfer order this asset belongs to, if any.
transferStatusStringCurrent transfer status of the asset, if part of a transfer order.
typeAssetTypeAsset type of the asset.
uuidStringGlobally unique identifier of the asset.

AssetOwner​

The current owner of a tracked asset, set via an Owner Change asset request.

FieldTypeDescription
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
firstNameStringFirst name.
idString!Unique identifier of the owner.
lastNameStringLast name.
uuidID!Globally unique identifier of the owner.

AssetType​

A type (template) describing a class of assets.

FieldTypeDescription
categories[AssetTypeCategory]Categories this asset type belongs to.
creationDateAWSTimestampEpoch-millisecond timestamp when the asset type was created.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
customerAssetTypes[CustomerAssetType!]Per-customer asset types mapped to this asset type.
descriptionStringFree-text description of the asset type.
idStringUnique identifier of the asset type, usually the asset type number or SKU.
images[String!]Public image URLs for the asset type.
lastUpdatedDateAWSTimestampEpoch-millisecond timestamp when the asset type was last updated.
nameStringDisplay name of the asset type.
numberStringAsset type number.
quantityIntExpected quantity of the asset type.
unitStringUnit of measure of the asset type.
uuidStringGlobally unique identifier of the asset type.

AssetTypeCategory​

A category grouping asset types, resolved through the asset's type.

FieldTypeDescription
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
descriptionStringFree-text description of the category.
idID!Unique identifier of the category.
nameStringDisplay name of the category.
parentAssetTypeCategoryParent category, if the category is not a root category.
uuidStringGlobally unique identifier of the category.

CustomerAssetType​

A customer-specific asset type mapped to an asset type.

FieldTypeDescription
customerAssetTypeIdString!The customer's asset type for this asset type.
customerIdString!Unique identifier of the customer.

LocationV2​

A location in the tenant's location hierarchy.

FieldTypeDescription
categoryIdStringIdentifier of the location category this location is classified under.
childLocationIds[String!]Identifiers of locations nested directly beneath this one.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
customerIdStringIdentifier of the customer this location belongs to, if any.
descriptionStringFree-text description of the location.
idStringUnique identifier of the location.
nameStringDisplay name of the location.
parentLocationIdStringIdentifier of the parent location in the hierarchy, if any.
roleIdStringIdentifier of the location role describing how this location is used.

RequestStatus​

The current status of a tracked asset as driven by the asset-request lifecycle.

ValueDescription
AVAILABLENot currently held against any active request.
CHECKED_OUTChecked out and not yet returned.
ON_HOLDReserved against a pending or approved CheckOut or Loan request.
ON_LOANLoaned out and not yet returned.
RETIREDRetired via a Scrap request.

Tracker​

An identifier tracker (e.g. RFID tag or barcode) attached to a tracked item.

FieldTypeDescription
attachDateAWSTimestampEpoch-millisecond timestamp when the tracker was attached to the item.
customPropertiesAWSJSONTenant-specific sensor profile custom properties.
encodingFormatStringRFID tag encoding format for this tracker.
serialStringEPC or tracker serial identifying this tracker.

TrackerInput​

Input for specifying a tracker to attach when creating or updating an item. Replaces the per-field trackerSerial / reuseTrackerSerial pattern.

FieldTypeDescription
customPropertiesAWSJSONTracker-level custom properties as a JSON object.
encodingFormatStringRFID tag encoding format for this tracker.
reuseTrackerSerialBooleanWhether to reuse a tracker serial already attached to another item.
serialString!EPC or tracker serial to attach.