Ctrlk
GitHubBlynk WebsiteLogin to Blynk.Console
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Server path to the firmware binary, as returned by the firmware upload endpoint (POST /api/upload with type=FIRMWARE).

Example: /static/fw_abc123def456.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 /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": "/static/fw_abc123def456.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

Server path to the firmware binary, as returned by the firmware upload endpoint (POST /api/upload with type=FIRMWARE).

Example: /static/fw_abc123def456.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
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": "/static/fw_abc123def456.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

No content
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.

Upload the firmware first. A shipment does not accept a raw file — it references a firmware binary that has already been uploaded to the server. Before calling this endpoint you must upload the firmware via POST /api/upload with type=FIRMWARE. That upload returns a JSON object with two values you feed straight into this request:

  • path → use as pathToFirmware

  • firmwareInfo → use as firmwareInfo

You still supply firmwareOriginalFileName yourself (typically the name of the file you uploaded).

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

Server path to the firmware binary. This is the path value returned by the firmware upload endpoint (POST /api/upload with type=FIRMWARE) — upload the file there first, then pass the returned path here.

Example: /static/fw_abc123def456.bin
firmwareOriginalFileNamestringRequired

Original firmware file name, as it should be shown to the user (usually the name of the file you uploaded).

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
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

Server path to the firmware binary, as returned by the firmware upload endpoint (POST /api/upload with type=FIRMWARE).

Example: /static/fw_abc123def456.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:
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: 579

{
  "orgId": 101,
  "productId": 10,
  "shipmentTime": "ANY",
  "title": "Firmware v2.0 rollout",
  "pathToFirmware": "/static/fw_abc123def456.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": "/static/fw_abc123def456.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

Server path to the firmware binary, as returned by the firmware upload endpoint (POST /api/upload with type=FIRMWARE).

Example: /static/fw_abc123def456.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
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": "/static/fw_abc123def456.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

Was this helpful?