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:

400

Bad request

application/json

403

Forbidden

404

Organization not found or access denied

application/json

429

Too many requests

500

Internal server error

application/json

get

/api/v1/organization/shipments

GET /api/v1/organization/shipments HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": 1,
    "productId": 10,
    "productName": "Smart Sensor",
    "shipmentTime": "ANY",
    "title": "Firmware v2.0 rollout",
    "pathToFirmware": "/uploads/firmware/v2.0.bin",
    "firmwareOriginalFileName": "firmware_v2.0.bin",
    "host": "myhost.com",
    "startedByUserId": 42,
    "startedAt": 1700000000000,
    "finishedAt": 0,
    "deviceIds": [
      1,
      2,
      3
    ],
    "firmwareInfo": {
      "version": "2.0.0",
      "blynkVersion": "1.3.0",
      "fwType": "Smart Sensor",
      "boardType": "ESP32",
      "buildDate": "Apr 10 2026",
      "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
      "sha256Hash": "text",
      "type": "MCU",
      "fileSize": 1048576
    },
    "attemptsLimit": 3,
    "attemptResetPeriodMs": 86400000,
    "isSecure": true,
    "skipFwTypeCheck": false,
    "isCritical": false,
    "sendPush": false,
    "status": "RUN",
    "compareField": "NO_CONDITION",
    "shipmentProgress": {
      "started": 10,
      "requestSent": 8,
      "firmwareRequested": 7,
      "firmwareUploaded": 6,
      "firmwareUploadedToMobile": 0,
      "success": 5,
      "uploadFailure": 1,
      "firmwareTypeMismatch": 0,
      "downloadLimitReached": 0,
      "rollback": 0,
      "firmwareVersionMismatch": 0,
      "updatedAt": 1700000000000
    }
  }
]

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:

400

Bad request

application/json

403

Forbidden

404

Shipment not found or access denied

429

Too many requests

500

Internal server error

application/json

get

/api/v1/organization/shipment

GET /api/v1/organization/shipment?shipmentId=1 HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "productId": 10,
  "productName": "Smart Sensor",
  "shipmentTime": "ANY",
  "title": "Firmware v2.0 rollout",
  "pathToFirmware": "/uploads/firmware/v2.0.bin",
  "firmwareOriginalFileName": "firmware_v2.0.bin",
  "host": "myhost.com",
  "startedByUserId": 42,
  "startedAt": 1700000000000,
  "finishedAt": 0,
  "deviceIds": [
    1,
    2,
    3
  ],
  "firmwareInfo": {
    "version": "2.0.0",
    "blynkVersion": "1.3.0",
    "fwType": "Smart Sensor",
    "boardType": "ESP32",
    "buildDate": "Apr 10 2026",
    "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
    "sha256Hash": "text",
    "type": "MCU",
    "fileSize": 1048576
  },
  "attemptsLimit": 3,
  "attemptResetPeriodMs": 86400000,
  "isSecure": true,
  "skipFwTypeCheck": false,
  "isCritical": false,
  "sendPush": false,
  "status": "RUN",
  "compareField": "NO_CONDITION",
  "shipmentProgress": {
    "started": 10,
    "requestSent": 8,
    "firmwareRequested": 7,
    "firmwareUploaded": 6,
    "firmwareUploadedToMobile": 0,
    "success": 5,
    "uploadFailure": 1,
    "firmwareTypeMismatch": 0,
    "downloadLimitReached": 0,
    "rollback": 0,
    "firmwareVersionMismatch": 0,
    "updatedAt": 1700000000000
  }
}

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

204

Shipment deleted successfully

400

Bad request

application/json

403

Forbidden

404

Shipment not found or access denied

429

Too many requests

500

Internal server error

application/json

delete

/api/v1/organization/shipment

DELETE /api/v1/organization/shipment?shipmentId=1 HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

201

Shipment created successfully

application/json

400

Bad request

application/json

403

Forbidden

404

Organization or product not found

application/json

429

Too many requests

500

Internal server error

application/json

post

/api/v1/organization/shipment/create

POST /api/v1/organization/shipment/create HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 578

{
  "orgId": 101,
  "productId": 10,
  "shipmentTime": "ANY",
  "title": "Firmware v2.0 rollout",
  "pathToFirmware": "/uploads/firmware/v2.0.bin",
  "firmwareOriginalFileName": "firmware_v2.0.bin",
  "host": "myhost.com",
  "deviceIds": [
    1,
    2,
    3
  ],
  "firmwareInfo": {
    "version": "2.0.0",
    "blynkVersion": "1.3.0",
    "fwType": "Smart Sensor",
    "boardType": "ESP32",
    "buildDate": "Apr 10 2026",
    "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
    "sha256Hash": "text",
    "type": "MCU",
    "fileSize": 1048576
  },
  "attemptsLimit": 3,
  "attemptResetPeriodMs": 86400000,
  "isSecure": true,
  "skipFwTypeCheck": false,
  "isCritical": false,
  "compareField": "NO_CONDITION"
}

{
  "id": 1,
  "productId": 10,
  "productName": "Smart Sensor",
  "shipmentTime": "ANY",
  "title": "Firmware v2.0 rollout",
  "pathToFirmware": "/uploads/firmware/v2.0.bin",
  "firmwareOriginalFileName": "firmware_v2.0.bin",
  "host": "myhost.com",
  "startedByUserId": 42,
  "startedAt": 1700000000000,
  "finishedAt": 0,
  "deviceIds": [
    1,
    2,
    3
  ],
  "firmwareInfo": {
    "version": "2.0.0",
    "blynkVersion": "1.3.0",
    "fwType": "Smart Sensor",
    "boardType": "ESP32",
    "buildDate": "Apr 10 2026",
    "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
    "sha256Hash": "text",
    "type": "MCU",
    "fileSize": 1048576
  },
  "attemptsLimit": 3,
  "attemptResetPeriodMs": 86400000,
  "isSecure": true,
  "skipFwTypeCheck": false,
  "isCritical": false,
  "sendPush": false,
  "status": "RUN",
  "compareField": "NO_CONDITION",
  "shipmentProgress": {
    "started": 10,
    "requestSent": 8,
    "firmwareRequested": 7,
    "firmwareUploaded": 6,
    "firmwareUploadedToMobile": 0,
    "success": 5,
    "uploadFailure": 1,
    "firmwareTypeMismatch": 0,
    "downloadLimitReached": 0,
    "rollback": 0,
    "firmwareVersionMismatch": 0,
    "updatedAt": 1700000000000
  }
}

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:

400

Bad request

application/json

403

Forbidden

404

Shipment not found or access denied

429

Too many requests

500

Internal server error

application/json

put

/api/v1/organization/shipment/stop

PUT /api/v1/organization/shipment/stop?shipmentId=1 HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "productId": 10,
  "productName": "Smart Sensor",
  "shipmentTime": "ANY",
  "title": "Firmware v2.0 rollout",
  "pathToFirmware": "/uploads/firmware/v2.0.bin",
  "firmwareOriginalFileName": "firmware_v2.0.bin",
  "host": "myhost.com",
  "startedByUserId": 42,
  "startedAt": 1700000000000,
  "finishedAt": 0,
  "deviceIds": [
    1,
    2,
    3
  ],
  "firmwareInfo": {
    "version": "2.0.0",
    "blynkVersion": "1.3.0",
    "fwType": "Smart Sensor",
    "boardType": "ESP32",
    "buildDate": "Apr 10 2026",
    "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
    "sha256Hash": "text",
    "type": "MCU",
    "fileSize": 1048576
  },
  "attemptsLimit": 3,
  "attemptResetPeriodMs": 86400000,
  "isSecure": true,
  "skipFwTypeCheck": false,
  "isCritical": false,
  "sendPush": false,
  "status": "RUN",
  "compareField": "NO_CONDITION",
  "shipmentProgress": {
    "started": 10,
    "requestSent": 8,
    "firmwareRequested": 7,
    "firmwareUploaded": 6,
    "firmwareUploadedToMobile": 0,
    "success": 5,
    "uploadFailure": 1,
    "firmwareTypeMismatch": 0,
    "downloadLimitReached": 0,
    "rollback": 0,
    "firmwareVersionMismatch": 0,
    "updatedAt": 1700000000000
  }
}

PreviousWebhooks NextUploads

Last updated 12 days ago

Was this helpful?