Shipments

OTA firmware update shipment management

Get shipments

get

Retrieve all OTA shipments in the organization.

Required permissions, when user-scoped authentication is used: OTA_VIEW.

Authorizations
AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Query parameters
orgIdinteger · int32Optional

Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used.

Responses
200

List of shipments

application/json
idinteger · int64Optional

Shipment unique identifier

Example: 1
productIdinteger · int32Optional

Template (product) ID for this shipment

Example: 10
productNamestringOptional

Template (product) name

Example: Smart Sensor
shipmentTimestring · enumOptional

Time window for the OTA update delivery

Example: ANYPossible values:
titlestringOptional

Shipment title

Example: Firmware v2.0 rollout
pathToFirmwarestringOptional

Path to the firmware file on the server

Example: /uploads/firmware/v2.0.bin
firmwareOriginalFileNamestringOptional

Original firmware file name

Example: firmware_v2.0.bin
hoststringOptional

Optional. Custom host domain name used for firmware download URL. If not set, the server's default host is used.

Example: myhost.com
startedByUserIdinteger · int64Optional

ID of the user who started the shipment

Example: 42
startedAtinteger · int64Optional

Timestamp (ms) when the shipment was started

Example: 1700000000000
finishedAtinteger · int64Optional

Timestamp (ms) when the shipment finished (0 if still running)

Example: 0
deviceIdsinteger · int32[]Optional

List of device IDs targeted by this shipment

Example: [1,2,3]
attemptsLimitinteger · int32Optional

Maximum number of OTA delivery attempts per device

Example: 3
attemptResetPeriodMsinteger · int64Optional

Period (ms) after which the attempt counter resets

Example: 86400000
isSecurebooleanOptional

Whether the firmware transfer uses a secure channel

Example: true
skipFwTypeCheckbooleanOptional

Whether to skip firmware type compatibility check

Example: false
isCriticalbooleanOptional

Whether this is a critical update

Example: false
sendPushbooleanOptional

Whether push notifications were sent for this shipment

Example: false
statusstring · enumOptional

Current shipment status

Example: RUNPossible values:
compareFieldstring · enumOptional

Condition used to determine whether the shipment should apply to a device

Example: NO_CONDITIONPossible values:
get
/api/v1/organization/shipments

Get shipment

get

Retrieve a single shipment by ID.

Required permissions, when user-scoped authentication is used: OTA_VIEW.

Authorizations
AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Query parameters
shipmentIdinteger · int64Required

Shipment ID

orgIdinteger · int32Optional

Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used.

Responses
200

Shipment details

application/json
idinteger · int64Optional

Shipment unique identifier

Example: 1
productIdinteger · int32Optional

Template (product) ID for this shipment

Example: 10
productNamestringOptional

Template (product) name

Example: Smart Sensor
shipmentTimestring · enumOptional

Time window for the OTA update delivery

Example: ANYPossible values:
titlestringOptional

Shipment title

Example: Firmware v2.0 rollout
pathToFirmwarestringOptional

Path to the firmware file on the server

Example: /uploads/firmware/v2.0.bin
firmwareOriginalFileNamestringOptional

Original firmware file name

Example: firmware_v2.0.bin
hoststringOptional

Optional. Custom host domain name used for firmware download URL. If not set, the server's default host is used.

Example: myhost.com
startedByUserIdinteger · int64Optional

ID of the user who started the shipment

Example: 42
startedAtinteger · int64Optional

Timestamp (ms) when the shipment was started

Example: 1700000000000
finishedAtinteger · int64Optional

Timestamp (ms) when the shipment finished (0 if still running)

Example: 0
deviceIdsinteger · int32[]Optional

List of device IDs targeted by this shipment

Example: [1,2,3]
attemptsLimitinteger · int32Optional

Maximum number of OTA delivery attempts per device

Example: 3
attemptResetPeriodMsinteger · int64Optional

Period (ms) after which the attempt counter resets

Example: 86400000
isSecurebooleanOptional

Whether the firmware transfer uses a secure channel

Example: true
skipFwTypeCheckbooleanOptional

Whether to skip firmware type compatibility check

Example: false
isCriticalbooleanOptional

Whether this is a critical update

Example: false
sendPushbooleanOptional

Whether push notifications were sent for this shipment

Example: false
statusstring · enumOptional

Current shipment status

Example: RUNPossible values:
compareFieldstring · enumOptional

Condition used to determine whether the shipment should apply to a device

Example: NO_CONDITIONPossible values:
get
/api/v1/organization/shipment

Delete shipment

delete

Delete a finished or cancelled shipment by ID. Only shipments with status FINISH or CANCEL can be deleted.

Required permissions, when user-scoped authentication is used: OTA_CANCEL.

Authorizations
AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Query parameters
shipmentIdinteger · int64Required

Shipment ID

orgIdinteger · int32Optional

Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used.

Responses
delete
/api/v1/organization/shipment

No content

Create shipment

post

Create a new OTA firmware update shipment.

Required permissions, when user-scoped authentication is used: OTA_START.

Note: sendPush is not supported via the Platform API and is always set to false.

Authorizations
AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Body
orgIdinteger · int32Optional

Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used.

Example: 101
productIdinteger · int32Optional

Template (product) ID for this shipment

Example: 10
shipmentTimestring · enumOptional

Time window for the OTA update delivery

Example: ANYPossible values:
titlestringRequired

Shipment title

Example: Firmware v2.0 rollout
pathToFirmwarestringRequired

Path to the firmware file on the server

Example: /uploads/firmware/v2.0.bin
firmwareOriginalFileNamestringRequired

Original firmware file name

Example: firmware_v2.0.bin
hoststringOptional

Optional. Custom host domain name for firmware download URL. If not provided, the server's default host will be used. Should be a domain name (e.g., 'myhost.com'). URL scheme prefixes (http://, https://) and trailing slashes are automatically stripped.

Example: myhost.com
deviceIdsinteger · int32[]Optional

List of device IDs to target

Example: [1,2,3]
attemptsLimitinteger · int32Optional

Maximum number of OTA delivery attempts per device

Example: 3
attemptResetPeriodMsinteger · int64Optional

Period (ms) after which the attempt counter resets

Example: 86400000
isSecurebooleanOptional

Whether the firmware transfer uses a secure channel

Example: true
skipFwTypeCheckbooleanOptional

Whether to skip firmware type compatibility check

Example: false
isCriticalbooleanOptional

Whether this is a critical update

Example: false
compareFieldstring · enumOptional

Condition used to determine whether the shipment should apply to a device

Example: NO_CONDITIONPossible values:
Responses
post
/api/v1/organization/shipment/create

Stop shipment

put

Stop (cancel) a running or paused shipment. Only shipments with status RUN or PAUSE can be stopped.

Required permissions, when user-scoped authentication is used: OTA_CANCEL.

Authorizations
AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Query parameters
shipmentIdinteger · int64Required

Shipment ID

orgIdinteger · int32Optional

Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used.

Responses
200

Shipment stopped successfully

application/json
idinteger · int64Optional

Shipment unique identifier

Example: 1
productIdinteger · int32Optional

Template (product) ID for this shipment

Example: 10
productNamestringOptional

Template (product) name

Example: Smart Sensor
shipmentTimestring · enumOptional

Time window for the OTA update delivery

Example: ANYPossible values:
titlestringOptional

Shipment title

Example: Firmware v2.0 rollout
pathToFirmwarestringOptional

Path to the firmware file on the server

Example: /uploads/firmware/v2.0.bin
firmwareOriginalFileNamestringOptional

Original firmware file name

Example: firmware_v2.0.bin
hoststringOptional

Optional. Custom host domain name used for firmware download URL. If not set, the server's default host is used.

Example: myhost.com
startedByUserIdinteger · int64Optional

ID of the user who started the shipment

Example: 42
startedAtinteger · int64Optional

Timestamp (ms) when the shipment was started

Example: 1700000000000
finishedAtinteger · int64Optional

Timestamp (ms) when the shipment finished (0 if still running)

Example: 0
deviceIdsinteger · int32[]Optional

List of device IDs targeted by this shipment

Example: [1,2,3]
attemptsLimitinteger · int32Optional

Maximum number of OTA delivery attempts per device

Example: 3
attemptResetPeriodMsinteger · int64Optional

Period (ms) after which the attempt counter resets

Example: 86400000
isSecurebooleanOptional

Whether the firmware transfer uses a secure channel

Example: true
skipFwTypeCheckbooleanOptional

Whether to skip firmware type compatibility check

Example: false
isCriticalbooleanOptional

Whether this is a critical update

Example: false
sendPushbooleanOptional

Whether push notifications were sent for this shipment

Example: false
statusstring · enumOptional

Current shipment status

Example: RUNPossible values:
compareFieldstring · enumOptional

Condition used to determine whether the shipment should apply to a device

Example: NO_CONDITIONPossible values:
put
/api/v1/organization/shipment/stop

Last updated

Was this helpful?