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.
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
| Function | Endpoint |
|---|---|
| Get commands by restrictions | GET /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 profiles | GET /v2/command-profiles |
| Get command profile | GET /v2/command-profiles/{id} |
| List command profile commands | GET /v2/command-profiles/{id}/commands |
| Execute remote command | POST /v2/execution |
| Get latest command status | GET /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:
| Status | Case | Response message |
|---|---|---|
| 403 | The account cannot see the asset. | Starts with User account not authorized. Does not have visibility to view asset(s) |
| 403 | The account is not allowed to send this command to this asset. | The account is not allowed to send this command |
| 400 | The asset is not configured for this command. | The asset is not configured for this command |
| 400 | A parameter value is outside the allowed range. | A parameter is outside the allowed range |
| 400 | A 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:
| Group | Status values |
|---|---|
| Queued | QUEUED, PENDING, COMMAND_RECEIVED |
| Delivered | SENT_TO_DEVICE, RECEIVED_BY_DEVICE |
| Executed | SUCCESS |
| Failed | QUEUED_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
assetIdandserialNumber,assetIdis used andserialNumberis 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}/parametersfor M7 andGET /v2/{commandId}/parametersfor TU700.