Skip to main content

Remote Commands API (Beta)

The Remote Commands API lets you send remote commands to the telematics device on an asset, so you can read and write parameters on the machine. You can find the commands an asset allows, inspect their parameters, read command profile configuration, execute a command, and follow its status.

The API supports single command execution over CAN and MODBUS. Every call follows the rights your account already has in Trackunit Manager: you only see assets, commands, and profiles your account can see, and a send is refused before anything reaches the machine when your account may not make it.

Beta

The Remote Commands API is in beta. Endpoints and models may change before general availability.

Concepts​

  • Command restriction limits where a command can run. Restrictions are asset based: they say which assets can run the command.
  • Command parameter is an input a command needs. A parameter can have a value range (minimum, maximum, step) or a list of allowed values.
  • Command profile groups the commands an account owns. Profiles are read-only in this API.
  • Command execution is a single run of a command against a machine. Each execution has an id you can track.
  • Command status is the state of an execution, for example queued, sent to device, success, or failed.
  • Command precondition must be true before a command runs on the machine, for example the machine must be powered on. If a precondition fails, the command is not executed.

Authentication​

The API uses an OAuth 2.0 bearer token. See Access Token for how to create API credentials in Trackunit Manager and obtain a token, then send it on every request:

--header 'Authorization: Bearer ACCESS_TOKEN'

A missing or invalid token returns 401. Tokens expire, so refresh before the expiry and retry on 401.

Endpoints​

FunctionEndpoint
Get commands by restrictionsGET /v2/restrictions
Get parameters by command id (TU700)GET /v2/{commandId}/parameters
Get command parameters by name (M7)GET /v2/name/{commandName}/parameters
List command profilesGET /v2/command-profiles
Get command profileGET /v2/command-profiles/{id}
List command profile commandsGET /v2/command-profiles/{id}/commands
Execute remote commandPOST /v2/execution
Get latest command statusGET /v2/statuses/latest

Worked examples​

The examples walk through a typical flow: find the commands allowed on an asset, inspect a command's parameters, read profile configuration, execute, and check the latest status. All requests go to https://iris.trackunit.com/api/commands. Responses are abbreviated.

List the commands allowed on an asset​

Pass either assetId or serialNumber. commandName, page, size and sort are optional.

curl --location --request GET 'https://iris.trackunit.com/api/commands/v2/restrictions?assetId=ASSET_ID&page=0&size=20' \
--header 'Authorization: Bearer ACCESS_TOKEN'
{
"content": [
{
"id": "COMMAND_ID",
"name": "Set idle timer",
"description": "Sets the engine idle shutdown timer",
"protocolType": "CAN",
"queueable": true,
"isImmediate": false,
"parameters": { "href": "...", "totalElements": 1 }
}
],
"number": 0,
"size": 20,
"numberOfElements": 1,
"totalElements": 1,
"totalPages": 1
}

An asset your account cannot see returns an empty page, exactly like an asset with no commands.

Inspect a command's parameters​

Use the id from the restrictions response. For M7 (Onei3) commands, use GET /v2/name/{commandName}/parameters instead.

curl --location --request GET 'https://iris.trackunit.com/api/commands/v2/COMMAND_ID/parameters' \
--header 'Authorization: Bearer ACCESS_TOKEN'
{
"parameters": [
{
"id": "PARAMETER_ID",
"name": "Idle timer (minutes)",
"valueType": "INTEGER",
"required": true,
"overwritable": true,
"valueRange": { "min": 1, "max": 60, "step": 1 }
}
]
}

A write value must fall inside valueRange, or match one of allowedValues when the parameter has them. A value exactly at the minimum or maximum is inside the range.

Read command profile configuration​

List the profiles you may view, then list the commands a profile owns.

curl --location --request GET 'https://iris.trackunit.com/api/commands/v2/command-profiles?page=0&size=20&sort=name' \
--header 'Authorization: Bearer ACCESS_TOKEN'
{
"content": [
{
"id": "PROFILE_ID",
"name": "Excavator defaults",
"description": null,
"state": "RELEASED",
"ownerAccountId": "ACCOUNT_ID",
"commandCount": 3
}
],
"number": 0,
"size": 20,
"numberOfElements": 1,
"totalElements": 1,
"totalPages": 1
}
curl --location --request GET 'https://iris.trackunit.com/api/commands/v2/command-profiles/PROFILE_ID/commands?page=0&size=20' \
--header 'Authorization: Bearer ACCESS_TOKEN'
{
"content": [
{
"id": "COMMAND_ID",
"name": "Set idle timer",
"description": "Sets the engine idle shutdown timer",
"protocolType": "CAN",
"parameterDefinitions": [
{
"id": "PARAMETER_ID",
"name": "Idle timer (minutes)",
"valueType": "INTEGER",
"required": true,
"overwritable": true,
"valueRange": { "min": 1, "max": 60, "step": 1 }
}
]
}
],
"number": 0,
"size": 20,
"numberOfElements": 1,
"totalElements": 1,
"totalPages": 1
}

Seeing a profile does not mean you may execute its commands. A profile that does not exist and one you may not view both return 404.

Execute a command​

Send exactly one of assetId or serialNumber. commandId is required. For a WRITE, also send parameterId and value.

curl --location --request POST 'https://iris.trackunit.com/api/commands/v2/execution' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"commandId": "COMMAND_ID",
"assetId": "ASSET_ID",
"operationType": "WRITE",
"parameterId": "PARAMETER_ID",
"value": "30"
}'

On success you receive 201 with the execution id and its initial status. A queueable WRITE to a TU700 device can start as QUEUED, waiting until the machine is ready. Other sends start as COMMAND_RECEIVED.

{
"commandExecutionIds": ["EXECUTION_ID"],
"statuses": ["QUEUED"]
}

A send your account may not make is refused before anything is queued, and no execution id is returned. The response says which case it was:

StatusCaseResponse message
403The account cannot see the asset.Starts with User account not authorized. Does not have visibility to view asset(s)
403The account is not allowed to send this command to this asset.The account is not allowed to send this command
400The asset is not configured for this command.The asset is not configured for this command
400A parameter value is outside the allowed range.A parameter is outside the allowed range
400A parameter value is not one of its allowedValues.Value VALUE is not allowed for parameter NAME

Get the latest status​

Use the execution id from the execute response.

curl --location --request GET 'https://iris.trackunit.com/api/commands/v2/statuses/latest?executionId=EXECUTION_ID' \
--header 'Authorization: Bearer ACCESS_TOKEN'
{
"id": "STATUS_ID",
"commandExecutionId": "EXECUTION_ID",
"commandStatusType": "QUEUED",
"operationType": "WRITE",
"timeStamp": "2026-10-28T14:00:00Z"
}

An execution id that is unknown, or that belongs to an asset you cannot see, returns 404 with the message Command execution not found.

Status groups​

Every commandStatusType value falls into one group:

GroupStatus values
QueuedQUEUED, PENDING, COMMAND_RECEIVED
DeliveredSENT_TO_DEVICE, RECEIVED_BY_DEVICE
ExecutedSUCCESS
FailedQUEUED_CANCELLED, SENDING_TO_DEVICE_FAILED, RECEIVED_BY_DEVICE_WITH_ERROR, CANCELLED_ON_GATEWAY, EXPIRED_ON_GATEWAY, EXPIRED_ON_DEVICE, PRECONDITION_FAILED_ON_DEVICE, SEND_FROM_DEVICE_TO_MACHINE_FAILED, DEVICE_QUEUE_FULL, MACHINE_RESPONSE_TIMEOUT, COMMAND_DROPPED_BY_DEVICE, MACHINE_OPERATION_FAILED, INVALID_MEMORY_ACCESS_DATA, MACHINE_BUSY, MACHINE_INVALID_KEY, COMMAND_GROUP_OPERATION_ERROR, EXCEPTION, INVALID_RESPONSE, INTERNAL_ERROR

SUCCESS and the failed values are final. Queued and delivered values mean the command is still in progress, so poll the latest status rather than executing again.

Constraints​

  • The API reads configuration and sends commands. It cannot create or change a profile, a command, or which assets a command applies to.
  • When a request has both assetId and serialNumber, assetId is used and serialNumber is ignored. Send only one.
  • A 404 on execute, or a message starting with No Telematics Device representation found, means the asset is unknown or has no linked telematics device.
  • M7 and TU700 command parameters are read through different endpoints. Use GET /v2/name/{commandName}/parameters for M7 and GET /v2/{commandId}/parameters for TU700.