# Shipments
OTA firmware update shipment management
## Get shipments
> Retrieve all OTA shipments in the organization.\
> \
> Required permissions, when user-scoped authentication is used: \`OTA\_VIEW\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"OTA firmware update shipment management"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"Shipment":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Shipment unique identifier"},"productId":{"type":"integer","format":"int32","description":"Template (product) ID for this shipment"},"productName":{"type":"string","description":"Template (product) name"},"shipmentTime":{"type":"string","enum":["ANY","NIGHT","MORNING","AFTERNOON","EVENING"],"description":"Time window for the OTA update delivery"},"title":{"type":"string","description":"Shipment title"},"pathToFirmware":{"type":"string","description":"Path to the firmware file on the server"},"firmwareOriginalFileName":{"type":"string","description":"Original firmware file name"},"host":{"type":"string","description":"Optional. Custom host domain name used for firmware download URL. If not set, the server's default host is used."},"startedByUserId":{"type":"integer","format":"int64","description":"ID of the user who started the shipment"},"startedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) when the shipment was started"},"finishedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) when the shipment finished (0 if still running)"},"deviceIds":{"type":"array","items":{"type":"integer","format":"int32"},"description":"List of device IDs targeted by this shipment"},"firmwareInfo":{"$ref":"#/components/schemas/FirmwareInfo"},"attemptsLimit":{"type":"integer","format":"int32","description":"Maximum number of OTA delivery attempts per device"},"attemptResetPeriodMs":{"type":"integer","format":"int64","description":"Period (ms) after which the attempt counter resets"},"isSecure":{"type":"boolean","description":"Whether the firmware transfer uses a secure channel"},"skipFwTypeCheck":{"type":"boolean","description":"Whether to skip firmware type compatibility check"},"isCritical":{"type":"boolean","description":"Whether this is a critical update"},"sendPush":{"type":"boolean","description":"Whether push notifications were sent for this shipment"},"status":{"type":"string","enum":["RUN","PAUSE","FINISH","CANCEL"],"description":"Current shipment status"},"compareField":{"type":"string","enum":["NO_CONDITION","BUILD_DATE_DIFFERS","EARLIER_BUILD_DATE","LATEST_FIRMWARE_VERSION","LATEST_BLYNK_VERSION"],"description":"Condition used to determine whether the shipment should apply to a device"},"shipmentProgress":{"$ref":"#/components/schemas/ShipmentProgress"}}},"FirmwareInfo":{"type":"object","properties":{"version":{"type":"string","description":"Firmware version"},"blynkVersion":{"type":"string","description":"Blynk firmware version"},"fwType":{"type":"string","description":"Firmware type (product name)"},"boardType":{"type":"string","description":"Board type"},"buildDate":{"type":"string","description":"Firmware build date"},"md5Hash":{"type":"string","description":"MD5 hash of the firmware file"},"sha256Hash":{"type":"string","description":"SHA-256 hash of the firmware file"},"type":{"type":"string","enum":["NCP","MCU"],"description":"Firmware type"},"fileSize":{"type":"integer","format":"int32","description":"Firmware file size in bytes"}}},"ShipmentProgress":{"type":"object","properties":{"started":{"type":"integer","format":"int32","description":"Number of devices that started the OTA update"},"requestSent":{"type":"integer","format":"int32","description":"Number of devices that received the update request"},"firmwareRequested":{"type":"integer","format":"int32","description":"Number of devices that requested the firmware"},"firmwareUploaded":{"type":"integer","format":"int32","description":"Number of devices that completed firmware upload"},"firmwareUploadedToMobile":{"type":"integer","format":"int32","description":"Number of devices that uploaded firmware via mobile"},"success":{"type":"integer","format":"int32","description":"Number of devices that successfully updated"},"uploadFailure":{"type":"integer","format":"int32","description":"Number of devices that failed to upload firmware"},"firmwareTypeMismatch":{"type":"integer","format":"int32","description":"Number of devices with firmware type mismatch"},"downloadLimitReached":{"type":"integer","format":"int32","description":"Number of devices that reached the download limit"},"rollback":{"type":"integer","format":"int32","description":"Number of devices that rolled back"},"firmwareVersionMismatch":{"type":"integer","format":"int32","description":"Number of devices with firmware version mismatch"},"updatedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) of the last progress update"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/shipments":{"get":{"tags":["Shipments"],"summary":"Get shipments","description":"Retrieve all OTA shipments in the organization.\n\nRequired permissions, when user-scoped authentication is used: `OTA_VIEW`.\n","operationId":"getShipments","parameters":[{"name":"orgId","in":"query","schema":{"type":"integer","format":"int32"},"description":"Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used."}],"responses":{"200":{"description":"List of shipments","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Organization not found or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Get shipment
> Retrieve a single shipment by ID.\
> \
> Required permissions, when user-scoped authentication is used: \`OTA\_VIEW\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"OTA firmware update shipment management"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"Shipment":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Shipment unique identifier"},"productId":{"type":"integer","format":"int32","description":"Template (product) ID for this shipment"},"productName":{"type":"string","description":"Template (product) name"},"shipmentTime":{"type":"string","enum":["ANY","NIGHT","MORNING","AFTERNOON","EVENING"],"description":"Time window for the OTA update delivery"},"title":{"type":"string","description":"Shipment title"},"pathToFirmware":{"type":"string","description":"Path to the firmware file on the server"},"firmwareOriginalFileName":{"type":"string","description":"Original firmware file name"},"host":{"type":"string","description":"Optional. Custom host domain name used for firmware download URL. If not set, the server's default host is used."},"startedByUserId":{"type":"integer","format":"int64","description":"ID of the user who started the shipment"},"startedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) when the shipment was started"},"finishedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) when the shipment finished (0 if still running)"},"deviceIds":{"type":"array","items":{"type":"integer","format":"int32"},"description":"List of device IDs targeted by this shipment"},"firmwareInfo":{"$ref":"#/components/schemas/FirmwareInfo"},"attemptsLimit":{"type":"integer","format":"int32","description":"Maximum number of OTA delivery attempts per device"},"attemptResetPeriodMs":{"type":"integer","format":"int64","description":"Period (ms) after which the attempt counter resets"},"isSecure":{"type":"boolean","description":"Whether the firmware transfer uses a secure channel"},"skipFwTypeCheck":{"type":"boolean","description":"Whether to skip firmware type compatibility check"},"isCritical":{"type":"boolean","description":"Whether this is a critical update"},"sendPush":{"type":"boolean","description":"Whether push notifications were sent for this shipment"},"status":{"type":"string","enum":["RUN","PAUSE","FINISH","CANCEL"],"description":"Current shipment status"},"compareField":{"type":"string","enum":["NO_CONDITION","BUILD_DATE_DIFFERS","EARLIER_BUILD_DATE","LATEST_FIRMWARE_VERSION","LATEST_BLYNK_VERSION"],"description":"Condition used to determine whether the shipment should apply to a device"},"shipmentProgress":{"$ref":"#/components/schemas/ShipmentProgress"}}},"FirmwareInfo":{"type":"object","properties":{"version":{"type":"string","description":"Firmware version"},"blynkVersion":{"type":"string","description":"Blynk firmware version"},"fwType":{"type":"string","description":"Firmware type (product name)"},"boardType":{"type":"string","description":"Board type"},"buildDate":{"type":"string","description":"Firmware build date"},"md5Hash":{"type":"string","description":"MD5 hash of the firmware file"},"sha256Hash":{"type":"string","description":"SHA-256 hash of the firmware file"},"type":{"type":"string","enum":["NCP","MCU"],"description":"Firmware type"},"fileSize":{"type":"integer","format":"int32","description":"Firmware file size in bytes"}}},"ShipmentProgress":{"type":"object","properties":{"started":{"type":"integer","format":"int32","description":"Number of devices that started the OTA update"},"requestSent":{"type":"integer","format":"int32","description":"Number of devices that received the update request"},"firmwareRequested":{"type":"integer","format":"int32","description":"Number of devices that requested the firmware"},"firmwareUploaded":{"type":"integer","format":"int32","description":"Number of devices that completed firmware upload"},"firmwareUploadedToMobile":{"type":"integer","format":"int32","description":"Number of devices that uploaded firmware via mobile"},"success":{"type":"integer","format":"int32","description":"Number of devices that successfully updated"},"uploadFailure":{"type":"integer","format":"int32","description":"Number of devices that failed to upload firmware"},"firmwareTypeMismatch":{"type":"integer","format":"int32","description":"Number of devices with firmware type mismatch"},"downloadLimitReached":{"type":"integer","format":"int32","description":"Number of devices that reached the download limit"},"rollback":{"type":"integer","format":"int32","description":"Number of devices that rolled back"},"firmwareVersionMismatch":{"type":"integer","format":"int32","description":"Number of devices with firmware version mismatch"},"updatedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) of the last progress update"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/shipment":{"get":{"tags":["Shipments"],"summary":"Get shipment","description":"Retrieve a single shipment by ID.\n\nRequired permissions, when user-scoped authentication is used: `OTA_VIEW`.\n","operationId":"getShipment","parameters":[{"name":"shipmentId","in":"query","required":true,"schema":{"type":"integer","format":"int64"},"description":"Shipment ID"},{"name":"orgId","in":"query","schema":{"type":"integer","format":"int32"},"description":"Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used."}],"responses":{"200":{"description":"Shipment details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Shipment not found or access denied"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Delete shipment
> 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\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"OTA firmware update shipment management"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/shipment":{"delete":{"tags":["Shipments"],"summary":"Delete shipment","description":"Delete a finished or cancelled shipment by ID. Only shipments with status `FINISH` or `CANCEL` can be deleted.\n\nRequired permissions, when user-scoped authentication is used: `OTA_CANCEL`.\n","operationId":"deleteShipment","parameters":[{"name":"shipmentId","in":"query","required":true,"schema":{"type":"integer","format":"int64"},"description":"Shipment ID"},{"name":"orgId","in":"query","schema":{"type":"integer","format":"int32"},"description":"Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used."}],"responses":{"204":{"description":"Shipment deleted successfully"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Shipment not found or access denied"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Create shipment
> 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\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"OTA firmware update shipment management"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"FirmwareInfo":{"type":"object","properties":{"version":{"type":"string","description":"Firmware version"},"blynkVersion":{"type":"string","description":"Blynk firmware version"},"fwType":{"type":"string","description":"Firmware type (product name)"},"boardType":{"type":"string","description":"Board type"},"buildDate":{"type":"string","description":"Firmware build date"},"md5Hash":{"type":"string","description":"MD5 hash of the firmware file"},"sha256Hash":{"type":"string","description":"SHA-256 hash of the firmware file"},"type":{"type":"string","enum":["NCP","MCU"],"description":"Firmware type"},"fileSize":{"type":"integer","format":"int32","description":"Firmware file size in bytes"}}},"Shipment":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Shipment unique identifier"},"productId":{"type":"integer","format":"int32","description":"Template (product) ID for this shipment"},"productName":{"type":"string","description":"Template (product) name"},"shipmentTime":{"type":"string","enum":["ANY","NIGHT","MORNING","AFTERNOON","EVENING"],"description":"Time window for the OTA update delivery"},"title":{"type":"string","description":"Shipment title"},"pathToFirmware":{"type":"string","description":"Path to the firmware file on the server"},"firmwareOriginalFileName":{"type":"string","description":"Original firmware file name"},"host":{"type":"string","description":"Optional. Custom host domain name used for firmware download URL. If not set, the server's default host is used."},"startedByUserId":{"type":"integer","format":"int64","description":"ID of the user who started the shipment"},"startedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) when the shipment was started"},"finishedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) when the shipment finished (0 if still running)"},"deviceIds":{"type":"array","items":{"type":"integer","format":"int32"},"description":"List of device IDs targeted by this shipment"},"firmwareInfo":{"$ref":"#/components/schemas/FirmwareInfo"},"attemptsLimit":{"type":"integer","format":"int32","description":"Maximum number of OTA delivery attempts per device"},"attemptResetPeriodMs":{"type":"integer","format":"int64","description":"Period (ms) after which the attempt counter resets"},"isSecure":{"type":"boolean","description":"Whether the firmware transfer uses a secure channel"},"skipFwTypeCheck":{"type":"boolean","description":"Whether to skip firmware type compatibility check"},"isCritical":{"type":"boolean","description":"Whether this is a critical update"},"sendPush":{"type":"boolean","description":"Whether push notifications were sent for this shipment"},"status":{"type":"string","enum":["RUN","PAUSE","FINISH","CANCEL"],"description":"Current shipment status"},"compareField":{"type":"string","enum":["NO_CONDITION","BUILD_DATE_DIFFERS","EARLIER_BUILD_DATE","LATEST_FIRMWARE_VERSION","LATEST_BLYNK_VERSION"],"description":"Condition used to determine whether the shipment should apply to a device"},"shipmentProgress":{"$ref":"#/components/schemas/ShipmentProgress"}}},"ShipmentProgress":{"type":"object","properties":{"started":{"type":"integer","format":"int32","description":"Number of devices that started the OTA update"},"requestSent":{"type":"integer","format":"int32","description":"Number of devices that received the update request"},"firmwareRequested":{"type":"integer","format":"int32","description":"Number of devices that requested the firmware"},"firmwareUploaded":{"type":"integer","format":"int32","description":"Number of devices that completed firmware upload"},"firmwareUploadedToMobile":{"type":"integer","format":"int32","description":"Number of devices that uploaded firmware via mobile"},"success":{"type":"integer","format":"int32","description":"Number of devices that successfully updated"},"uploadFailure":{"type":"integer","format":"int32","description":"Number of devices that failed to upload firmware"},"firmwareTypeMismatch":{"type":"integer","format":"int32","description":"Number of devices with firmware type mismatch"},"downloadLimitReached":{"type":"integer","format":"int32","description":"Number of devices that reached the download limit"},"rollback":{"type":"integer","format":"int32","description":"Number of devices that rolled back"},"firmwareVersionMismatch":{"type":"integer","format":"int32","description":"Number of devices with firmware version mismatch"},"updatedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) of the last progress update"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/shipment/create":{"post":{"tags":["Shipments"],"summary":"Create shipment","description":"Create a new OTA firmware update shipment.\n\nRequired permissions, when user-scoped authentication is used: `OTA_START`.\n\nNote: `sendPush` is not supported via the Platform API and is always set to `false`.\n","operationId":"createShipment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"integer","format":"int32","description":"Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used."},"productId":{"type":"integer","format":"int32","description":"Template (product) ID for this shipment"},"shipmentTime":{"type":"string","enum":["ANY","NIGHT","MORNING","AFTERNOON","EVENING"],"description":"Time window for the OTA update delivery"},"title":{"type":"string","description":"Shipment title"},"pathToFirmware":{"type":"string","description":"Path to the firmware file on the server"},"firmwareOriginalFileName":{"type":"string","description":"Original firmware file name"},"host":{"type":"string","description":"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."},"deviceIds":{"type":"array","items":{"type":"integer","format":"int32"},"description":"List of device IDs to target"},"firmwareInfo":{"$ref":"#/components/schemas/FirmwareInfo"},"attemptsLimit":{"type":"integer","format":"int32","description":"Maximum number of OTA delivery attempts per device"},"attemptResetPeriodMs":{"type":"integer","format":"int64","description":"Period (ms) after which the attempt counter resets"},"isSecure":{"type":"boolean","description":"Whether the firmware transfer uses a secure channel"},"skipFwTypeCheck":{"type":"boolean","description":"Whether to skip firmware type compatibility check"},"isCritical":{"type":"boolean","description":"Whether this is a critical update"},"compareField":{"type":"string","enum":["NO_CONDITION","BUILD_DATE_DIFFERS","EARLIER_BUILD_DATE","LATEST_FIRMWARE_VERSION","LATEST_BLYNK_VERSION"],"description":"Condition used to determine whether the shipment should apply to a device"}},"required":["title","pathToFirmware","firmwareOriginalFileName","firmwareInfo"]}}}},"responses":{"201":{"description":"Shipment created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Organization or product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Stop shipment
> 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\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"OTA firmware update shipment management"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"Shipment":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Shipment unique identifier"},"productId":{"type":"integer","format":"int32","description":"Template (product) ID for this shipment"},"productName":{"type":"string","description":"Template (product) name"},"shipmentTime":{"type":"string","enum":["ANY","NIGHT","MORNING","AFTERNOON","EVENING"],"description":"Time window for the OTA update delivery"},"title":{"type":"string","description":"Shipment title"},"pathToFirmware":{"type":"string","description":"Path to the firmware file on the server"},"firmwareOriginalFileName":{"type":"string","description":"Original firmware file name"},"host":{"type":"string","description":"Optional. Custom host domain name used for firmware download URL. If not set, the server's default host is used."},"startedByUserId":{"type":"integer","format":"int64","description":"ID of the user who started the shipment"},"startedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) when the shipment was started"},"finishedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) when the shipment finished (0 if still running)"},"deviceIds":{"type":"array","items":{"type":"integer","format":"int32"},"description":"List of device IDs targeted by this shipment"},"firmwareInfo":{"$ref":"#/components/schemas/FirmwareInfo"},"attemptsLimit":{"type":"integer","format":"int32","description":"Maximum number of OTA delivery attempts per device"},"attemptResetPeriodMs":{"type":"integer","format":"int64","description":"Period (ms) after which the attempt counter resets"},"isSecure":{"type":"boolean","description":"Whether the firmware transfer uses a secure channel"},"skipFwTypeCheck":{"type":"boolean","description":"Whether to skip firmware type compatibility check"},"isCritical":{"type":"boolean","description":"Whether this is a critical update"},"sendPush":{"type":"boolean","description":"Whether push notifications were sent for this shipment"},"status":{"type":"string","enum":["RUN","PAUSE","FINISH","CANCEL"],"description":"Current shipment status"},"compareField":{"type":"string","enum":["NO_CONDITION","BUILD_DATE_DIFFERS","EARLIER_BUILD_DATE","LATEST_FIRMWARE_VERSION","LATEST_BLYNK_VERSION"],"description":"Condition used to determine whether the shipment should apply to a device"},"shipmentProgress":{"$ref":"#/components/schemas/ShipmentProgress"}}},"FirmwareInfo":{"type":"object","properties":{"version":{"type":"string","description":"Firmware version"},"blynkVersion":{"type":"string","description":"Blynk firmware version"},"fwType":{"type":"string","description":"Firmware type (product name)"},"boardType":{"type":"string","description":"Board type"},"buildDate":{"type":"string","description":"Firmware build date"},"md5Hash":{"type":"string","description":"MD5 hash of the firmware file"},"sha256Hash":{"type":"string","description":"SHA-256 hash of the firmware file"},"type":{"type":"string","enum":["NCP","MCU"],"description":"Firmware type"},"fileSize":{"type":"integer","format":"int32","description":"Firmware file size in bytes"}}},"ShipmentProgress":{"type":"object","properties":{"started":{"type":"integer","format":"int32","description":"Number of devices that started the OTA update"},"requestSent":{"type":"integer","format":"int32","description":"Number of devices that received the update request"},"firmwareRequested":{"type":"integer","format":"int32","description":"Number of devices that requested the firmware"},"firmwareUploaded":{"type":"integer","format":"int32","description":"Number of devices that completed firmware upload"},"firmwareUploadedToMobile":{"type":"integer","format":"int32","description":"Number of devices that uploaded firmware via mobile"},"success":{"type":"integer","format":"int32","description":"Number of devices that successfully updated"},"uploadFailure":{"type":"integer","format":"int32","description":"Number of devices that failed to upload firmware"},"firmwareTypeMismatch":{"type":"integer","format":"int32","description":"Number of devices with firmware type mismatch"},"downloadLimitReached":{"type":"integer","format":"int32","description":"Number of devices that reached the download limit"},"rollback":{"type":"integer","format":"int32","description":"Number of devices that rolled back"},"firmwareVersionMismatch":{"type":"integer","format":"int32","description":"Number of devices with firmware version mismatch"},"updatedAt":{"type":"integer","format":"int64","description":"Timestamp (ms) of the last progress update"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/shipment/stop":{"put":{"tags":["Shipments"],"summary":"Stop shipment","description":"Stop (cancel) a running or paused shipment. Only shipments with status `RUN` or `PAUSE` can be stopped.\n\nRequired permissions, when user-scoped authentication is used: `OTA_CANCEL`.\n","operationId":"stopShipment","parameters":[{"name":"shipmentId","in":"query","required":true,"schema":{"type":"integer","format":"int64"},"description":"Shipment ID"},{"name":"orgId","in":"query","schema":{"type":"integer","format":"int32"},"description":"Organization ID (optional). If not provided, the organization, that is associated with the authentication token, will be used."}],"responses":{"200":{"description":"Shipment stopped successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Shipment not found or access denied"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.blynk.io/en/blynk.cloud/platform-https-api/shipments.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.