Documentation

Mistake on this page? Email us

Update Service Public API

This is the API documentation for the Device Management deployment service, which is part of the Update service.
Version: 3
Host: https://api.us-east-1.mbedcloud.com

Endpoints

DeviceUpdateCampaigns

post /v3/update-campaigns/{campaign_id}/archive
Archive a campaign. Show more Show less

Archive a campaign.
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/archive \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
202 The campaign has been archived.
400 Unable to change the phase of the campaign.
401 Not authenticated.
404 Cannot find the campaign.
409 Cannot archive the campaign while in the current phase.
post /v3/update-campaigns
Create a campaign Show more Show less

Create an update campaign.
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns \
-H 'Authorization: <valid access token>' \
-H 'content-type: application/json;charset=UTF-8' \
-d '{
  "campaign_strategy": "one-shot",
  "description": "Campaign is for ...",
  "device_filter": "id__eq=123400000000000000000000000ae45",
  "name": "campaign",
  "root_manifest_id": "5678000000000000000000000000bd98",
}'
Request body
campaign UpdateCampaignPostRequest (required)
Body Parameter — Update campaign.
Return type
Example data
Content-Type: application/json
{
  "stopping_at" : "2017-05-22T12:37:55.576563Z",
  "description" : "This campaign updates Class XX devices to version 1.34",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "when" : "2017-05-22T12:37:55.576563Z",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "device_filter" : "id__eq=00000000000000000000000000000000",
  "autostop_success_percent" : 85.0,
  "state" : "draft",
  "id" : "00000000000000000000000000000000",
  "stopped_at" : "2017-05-22T12:37:55.576563Z",
  "autostop_reason" : "Insufficient billing credit.",
  "phase" : "draft",
  "archived_at" : "2017-05-22T12:37:55.576563Z",
  "starting_at" : "2017-05-22T12:37:55.576563Z",
  "approval_required" : false,
  "root_manifest_id" : "00000000000000000000000000000000",
  "finished" : "2017-05-22T12:37:55.576563Z",
  "campaign_strategy" : "one-shot",
  "root_manifest_url" : "http://example.com/00000000000000000000000000000000",
  "name" : "campaign",
  "started_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "active_at" : "2017-05-22T12:37:55.576563Z",
  "autostop" : false,
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
201 Update campaign created. UpdateCampaign
400 Validation error: The data used to create the campaign did not validate.
401 Not authenticated.
delete /v3/update-campaigns/{campaign_id}
Delete a campaign Show more Show less

Delete an update campaign.
Usage example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Update campaign deleted.
400 Validation error: The data used to update the campaign did not validate.
401 Not authenticated.
404 Update campaign can't be found.
409 Conflict - Cannot delete the campaign while in the current phase. ErrorResponse
get /v3/update-campaigns/{campaign_id}/statistics/{summary_status_id}/event_types
Get a list of events grouped by summary Show more Show less

Get a list of events grouped by summary.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/statistics/12345678901234567890123456789012/event_types \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
summary_status_id (required)
Path Parameter — The summary status. For example, fail.
Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "event_type" : "UPD4_FAIL_101",
    "summary_status_id" : "fail",
    "count" : 10,
    "created_at" : "2017-05-22T12:37:55.576563Z",
    "description" : "Update error, nonspecific network error",
    "summary_status" : "FAIL",
    "id" : "upd_fail_101",
    "campaign_id" : "00000000000000000000000000000000",
    "object" : "aeiou"
  } ],
  "total_count" : 1,
  "limit" : 50,
  "after" : "null",
  "has_more" : false,
  "object" : "list",
  "order" : "ASC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 OK. EventTypeList
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse
get /v3/update-campaigns/{campaign_id}/statistics/{summary_status_id}/event_types/{event_type_id}
Get an event type for a campaign Show more Show less

Get the count for a specific event type; for example, succeeded, failed, or skipped.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/statistics/12345678901234567890123456789012/event_types/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
summary_status_id (required)
Path Parameter — The summary status. For example, fail.
event_type_id (required)
Path Parameter — The event type parameter. For example, UPD4_FAIL_101.
Return type
Example data
Content-Type: application/json
{
  "event_type" : "UPD4_FAIL_101",
  "summary_status_id" : "fail",
  "count" : 10,
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "description" : "Update error, nonspecific network error",
  "summary_status" : "FAIL",
  "id" : "upd_fail_101",
  "campaign_id" : "00000000000000000000000000000000",
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 OK. EventType
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse
get /v3/update-campaigns
List all campaigns Show more Show less

Get update campaigns for devices specified by a filter.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns \
-H 'Authorization: <valid access token>'
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
minimum: 2
maximum: 1000
order (optional)
Query Parameter — The order of the records. Acceptable values: ASC, DESC. Default: ASC.
after (optional)
Query Parameter — The ID of the item after which to retrieve the next page.
include (optional)
Query Parameter — A comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL-encoded query string parameter to filter returned data

?filter={URL-encoded query string}

Filterable fields:

The below table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
created_at
description  
device_filter  
etag
finished
id  
name  
root_manifest_id  
started_at
state  
updated_at
when
 

The query string is made up of key-value pairs separated by ampersands. For example, this query: key1__eq=value1&key2__eq=value2&key3__eq=value3

would be URL-encoded as: ?filter=key1__eq%3Dvalue1%26key2__eq%3Dvalue2%26key3__eq%3Dvalue3

Filtering by campaign properties state__eq=[draft|scheduled|devicefectch|devicecopy|publishing|deploying|deployed|manifestremoved|expired]

root_manifest_id__eq=43217771234242e594ddb433816c498a

Filtering on date-time fields

Date-time fields should be specified in UTC RFC3339 format, YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds. Example: 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds. Example: 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened without milliseconds and punctuation. Example: 20161130T162512Z

Date-time filtering supports three operators:

  • equality by appending __eq to the field name
  • greater than or equal to by appending __gte to the field name
  • less than or equal to by appending __lte to the field name

{field name}[|__eq|__lte|__gte]={UTC RFC3339 date-time}

Time ranges may be specified by including both the __gte and __lte forms in the filter. For example:

created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering on multiple fields

state__eq=deployed&created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated:

name__in=fw-image1,fw-image2

Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "stopping_at" : "2017-05-22T12:37:55.576563Z",
    "description" : "This campaign updates Class XX devices to version 1.34",
    "created_at" : "2017-05-22T12:37:55.576563Z",
    "when" : "2017-05-22T12:37:55.576563Z",
    "updated_at" : "2017-05-22T12:37:55.576563Z",
    "device_filter" : "id__eq=00000000000000000000000000000000",
    "autostop_success_percent" : 85.0,
    "state" : "draft",
    "id" : "00000000000000000000000000000000",
    "stopped_at" : "2017-05-22T12:37:55.576563Z",
    "autostop_reason" : "Insufficient billing credit.",
    "phase" : "draft",
    "archived_at" : "2017-05-22T12:37:55.576563Z",
    "starting_at" : "2017-05-22T12:37:55.576563Z",
    "approval_required" : false,
    "root_manifest_id" : "00000000000000000000000000000000",
    "finished" : "2017-05-22T12:37:55.576563Z",
    "campaign_strategy" : "one-shot",
    "root_manifest_url" : "http://example.com/00000000000000000000000000000000",
    "name" : "campaign",
    "started_at" : "2017-05-22T12:37:55.576563Z",
    "etag" : "2017-05-22T12:37:58.753425Z",
    "active_at" : "2017-05-22T12:37:55.576563Z",
    "autostop" : false,
    "object" : "aeiou"
  } ],
  "total_count" : 6,
  "limit" : 0,
  "after" : "null",
  "has_more" : true,
  "object" : "aeiou",
  "order" : "ASC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful. UpdateCampaignPage
400 Validation error: The data used to update the campaign did not validate.
401 Not authenticated.
404 Unable to find content.
get /v3/update-campaigns/{campaign_id}/campaign-device-metadata
List all campaign device metadata Show more Show less

Get metadata for all devices in a campaign.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/campaign-device-metadata \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
minimum: 2
maximum: 1000
order (optional)
Query Parameter — ASC or DESC.
after (optional)
Query Parameter — The ID of the item after which to retrieve the next page.
include (optional)
Query Parameter — A comma-separated list of data fields to return. Currently supported: total_count.
Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "device_id" : "015c2fec9bba0000000000010010036f",
    "updated_at" : "2017-05-22T12:37:55.576563Z",
    "mechanism_url" : "aeiou",
    "name" : "default_object_name",
    "description" : "a description",
    "campaign" : "015bf72fccda00000000000100100280",
    "created_at" : "2017-05-22T12:37:55.576563Z",
    "etag" : "2017-05-22T12:37:58.753425Z",
    "id" : "015c3029f6f7000000000001001000c3",
    "mechanism" : "connector",
    "deployment_state" : "pending",
    "object" : "aeiou"
  } ],
  "total_count" : 1,
  "limit" : 50,
  "after" : "null",
  "has_more" : false,
  "object" : "aeiou",
  "order" : "ASC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful. CampaignDeviceMetadataPage
401 Unauthorized
get /v3/update-campaigns/{campaign_id}/campaign-device-metadata/{campaign_device_metadata_id}
Get a campaign device metadata Show more Show less

Get update campaign metadata for a specific device.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/campaign-device-metadata/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
campaign_device_metadata_id (required)
Path Parameter — The campaign device metadata ID.
Return type
Example data
Content-Type: application/json
{
  "device_id" : "015c2fec9bba0000000000010010036f",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "mechanism_url" : "aeiou",
  "name" : "default_object_name",
  "description" : "a description",
  "campaign" : "015bf72fccda00000000000100100280",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "id" : "015c3029f6f7000000000001001000c3",
  "mechanism" : "connector",
  "deployment_state" : "pending",
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful. CampaignDeviceMetadata
401 Unauthorized.
404 Not Found.
get /v3/update-campaigns/{campaign_id}/metrics
Get campaign metrics Show more Show less
Deprecation Date:
Expected End of Life:
Use the statistics endpoint instead.

Get information for a campaign based on SUCCESS, FAIL, or SKIPPED criteria for each device.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/metrics \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
Return type
Example data
Content-Type: application/json
{
  "pending_count" : 5,
  "skipped_count" : 5,
  "total_count" : 100,
  "success_count" : 90,
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "failed_count" : 0,
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful. CampaignMetrics
401 Unauthorized.
404 Unable to find campaign or the campaign hasn't started.
get /v3/update-campaigns/{campaign_id}
Get a campaign. Show more Show less

Get an update campaign.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
Return type
Example data
Content-Type: application/json
{
  "stopping_at" : "2017-05-22T12:37:55.576563Z",
  "description" : "This campaign updates Class XX devices to version 1.34",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "when" : "2017-05-22T12:37:55.576563Z",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "device_filter" : "id__eq=00000000000000000000000000000000",
  "autostop_success_percent" : 85.0,
  "state" : "draft",
  "id" : "00000000000000000000000000000000",
  "stopped_at" : "2017-05-22T12:37:55.576563Z",
  "autostop_reason" : "Insufficient billing credit.",
  "phase" : "draft",
  "archived_at" : "2017-05-22T12:37:55.576563Z",
  "starting_at" : "2017-05-22T12:37:55.576563Z",
  "approval_required" : false,
  "root_manifest_id" : "00000000000000000000000000000000",
  "finished" : "2017-05-22T12:37:55.576563Z",
  "campaign_strategy" : "one-shot",
  "root_manifest_url" : "http://example.com/00000000000000000000000000000000",
  "name" : "campaign",
  "started_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "active_at" : "2017-05-22T12:37:55.576563Z",
  "autostop" : false,
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Retrieved result successfully. UpdateCampaign
400 Validation error: The data used to update the campaign did not validate.
401 Not authenticated.
404 Unable to find campaign.
post /v3/update-campaigns/{campaign_id}/start
Start a campaign. Show more Show less

Start a campaign.
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/start \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
202 The campaign is starting.
400 Unable to change the phase of the campaign.
401 Not authenticated.
404 Cannot find the campaign.
409 Cannot start the campaign while in the current phase.
get /v3/update-campaigns/{campaign_id}/statistics
Get statistics for a campaign Show more Show less

Get a list of statistics for a campaign, including the number of devices reporting specific event codes.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/statistics \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "count" : 10,
    "created_at" : "2017-05-22T12:37:55.576563Z",
    "summary_status" : "FAIL",
    "id" : "fail",
    "campaign_id" : "00000000000000000000000000000000",
    "object" : "aeiou"
  } ],
  "total_count" : 1,
  "limit" : 50,
  "after" : "null",
  "has_more" : false,
  "object" : "aeiou",
  "order" : "ASC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 OK. EventTypeSummaryList
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse
get /v3/update-campaigns/{campaign_id}/statistics/{summary_status_id}
Get a status summary Show more Show less

Get the count of successfully updated, skipped, and failed devices.
Usage example:

curl https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/statistics/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
summary_status_id (required)
Path Parameter — The summary status. For example, fail.
Return type
Example data
Content-Type: application/json
{
  "count" : 10,
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "summary_status" : "FAIL",
  "id" : "fail",
  "campaign_id" : "00000000000000000000000000000000",
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 OK. EventTypeSummary
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse
post /v3/update-campaigns/{campaign_id}/stop
Stop a campaign. Show more Show less

Stop a campaign. Stopping is a process that requires the campaign go through several phases.
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/stop \
-H 'Authorization: <valid access token>'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
202 The campaign is stopping.
400 Unable to change the phase of the campaign.
401 Not authenticated.
404 Cannot find the campaign.
409 Cannot stop the campaign while in the current phase.
put /v3/update-campaigns/{campaign_id}
Modify a campaign Show more Show less

Modify an update campaign.
Usage example:

curl -X PUT https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>' \
d '{
  "description": "Campaign is for ...",
  "device_filter": "id__eq=123400000000000000000000000ae45",
  "name": "campaign",
  "root_manifest_id": "5678000000000000000000000000bd98",
}'
Path parameters
campaign_id (required)
Path Parameter — The campaign ID.
Request body
campaign UpdateCampaignPutRequest (required)
Body Parameter — Update campaign.
Return type
Example data
Content-Type: application/json
{
  "stopping_at" : "2017-05-22T12:37:55.576563Z",
  "description" : "This campaign updates Class XX devices to version 1.34",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "when" : "2017-05-22T12:37:55.576563Z",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "device_filter" : "id__eq=00000000000000000000000000000000",
  "autostop_success_percent" : 85.0,
  "state" : "draft",
  "id" : "00000000000000000000000000000000",
  "stopped_at" : "2017-05-22T12:37:55.576563Z",
  "autostop_reason" : "Insufficient billing credit.",
  "phase" : "draft",
  "archived_at" : "2017-05-22T12:37:55.576563Z",
  "starting_at" : "2017-05-22T12:37:55.576563Z",
  "approval_required" : false,
  "root_manifest_id" : "00000000000000000000000000000000",
  "finished" : "2017-05-22T12:37:55.576563Z",
  "campaign_strategy" : "one-shot",
  "root_manifest_url" : "http://example.com/00000000000000000000000000000000",
  "name" : "campaign",
  "started_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "active_at" : "2017-05-22T12:37:55.576563Z",
  "autostop" : false,
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Update campaign updated. UpdateCampaign
400 Validation error: The data used to update the campaign did not validate.
401 Not authenticated.
403 Fields apart from 'name', 'description' and 'state' cannot be modified when the state is not 'draft'.
404 Update campaign can't be found.

DeviceUpdateFirmwareImages

post /v3/firmware-images
Create an image Show more Show less

Create a firmware image.
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/firmware-images \
-H 'Authorization: <valid access token>' \
-H 'Content-Type: multipart/form-data' \
-F 'datafile=@myimage.bin;type=application/octet-stream'
-F 'description=bla bla' \
-F 'name=My Linux Image'
Consumes
This API call consumes the following media types via the Content-Type request header:
  • multipart/form-data
Form parameters
datafile (required)
Form Parameter — The firmware image file to upload.
description (optional)
Form Parameter — The description of the firmware image.
name (optional)
Form Parameter — The name of the firmware image.
Return type
Example data
Content-Type: application/json
{
  "datafile_checksum" : "0000000000000000000000000000000000000000000000000000000000000000",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "datafile_size" : 0,
  "name" : "aeiou",
  "description" : "a description",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "id" : "00000000000000000000000000000000",
  "datafile" : "http://example.com/00000000000000000000000000000000",
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
201 Firmware image created. The API gateway enforces the account-specific file size. FirmwareImage
400 Cannot validate the data used to create the firmware image.
401 Not authenticated.
403 Forbidden.
413 Firmware image too large.
delete /v3/firmware-images/{image_id}
Delete an image Show more Show less

Delete a firmware image.
Usage example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v3/firmware-images/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
image_id (required)
Path Parameter — The firmware image ID.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Firmware image deleted.
400 Bad Request.
401 Not authenticated.
404 Firmware image not found.
get /v3/firmware-images
List all images Show more Show less

List all firmware images.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/firmware-images \
-H 'Authorization: <valid access token>'
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
minimum: 2
maximum: 1000
order (optional)
Query Parameter — ASC or DESC.
after (optional)
Query Parameter — The ID of the item after which to retrieve the next page.
include (optional)
Query Parameter — A comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL-encoded query string parameter to filter returned data

?filter={URL-encoded query string}

Filterable fields:

The table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
created_at
datafile  
datafile_checksum  
datafile_size  
description  
etag
id  
name  
updated_at
 

The query string is made up of key-value pairs separated by ampersands. For example, this query: key1=value1&key2=value2&key3=value3

would be URL-encoded as: ?filter=key1__eq%3Dvalue1%26key2__eq%3Dvalue2%26key3__eq%3Dvalue3

Filtering by properties name__eq=myimage

Filtering on date-time fields

Date-time fields should be specified in UTC RFC3339 format, YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds. Example: 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds. Example: 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened without milliseconds and punctuation. Example: 20161130T162512Z

Date-time filtering supports three operators:

  • equality by appending __eq to the field name
  • greater than or equal to by appending __gte to the field name
  • less than or equal to by appending __lte to the field name

{field name}[|__eq|__lte|__gte]={UTC RFC3339 date-time}

Time ranges may be specified by including both the __gte and __lte forms in the filter. For example:

created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering on multiple fields

name__eq=myimage&created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated:

name__in=fw-image1,fw-image2

Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "datafile_checksum" : "0000000000000000000000000000000000000000000000000000000000000000",
    "updated_at" : "2017-05-22T12:37:55.576563Z",
    "datafile_size" : 0,
    "name" : "aeiou",
    "description" : "a description",
    "created_at" : "2017-05-22T12:37:55.576563Z",
    "etag" : "2017-05-22T12:37:58.753425Z",
    "id" : "00000000000000000000000000000000",
    "datafile" : "http://example.com/00000000000000000000000000000000",
    "object" : "aeiou"
  } ],
  "total_count" : 1,
  "limit" : 6,
  "after" : "null",
  "has_more" : true,
  "object" : "aeiou",
  "order" : "ASC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful. FirmwareImagePage
400 Bad Request.
401 Not authenticated.
404 Unable to find content.
get /v3/firmware-images/{image_id}

Retrieve a firmware image.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/firmware-images/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
image_id (required)
Path Parameter — The firmware image ID
Return type
Example data
Content-Type: application/json
{
  "datafile_checksum" : "0000000000000000000000000000000000000000000000000000000000000000",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "datafile_size" : 0,
  "name" : "aeiou",
  "description" : "a description",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "id" : "00000000000000000000000000000000",
  "datafile" : "http://example.com/00000000000000000000000000000000",
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Retrieved result successfully. FirmwareImage
400 Bad Request.
401 Not authenticated.
404 Firmware image can't be found.
post /v3/firmware-images/upload-jobs/{upload_job_id}/chunks
Append a chunk to an upload job Show more Show less

Append a chunk to an upload job. To finish a job, upload a zero-length chunk.
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/firmware-images/upload-jobs/12345678901234567890123456789012/chunks \
-H 'Authorization: <valid access token>' \
-H 'Content-MD5: Q2h1Y2sgSW51ZwDIAXR5IQ==' \
-H 'Content-Type: binary/octet-stream' \
-H 'Content-Length: 999' \
-d '{
  "IGh0dHBzOi8vYXBpLnVzLWVhc3QtMS5tYmVkY2xvdWQuY29tLy92My9maXJtd2FyZS1pbWFnZXMvdXBsb2FkLWpvYnMve3VwbG9hZF9qb2JfaWR9W5rcw=="
}'
Path parameters
upload_job_id (required)
Path Parameter — The upload job ID.
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/octet-stream
Request body
chunk binary (optional)
Body Parameter — Chunk.
Request headers
Content-MD5 (required)
Header Parameter — The base64-encoded binary digest of the body (chunk data).
format: byte
Content-Length (required)
Header Parameter
Return type
Example data
Content-Type: application/json
{
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "upload_job_id" : "00000000000000000000000000000000",
  "length" : 1234,
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "id" : 1,
  "hash" : "aeiou",
  "object" : "upload-info"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
201 Success - Chunk appended to the upload. UploadChunkInfo
400 Bad Request. ErrorResponse
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse
get /v3/firmware-images/upload-jobs/{upload_job_id}/chunks
List all metadata for uploaded chunks Show more Show less

List all metadata for uploaded chunks.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/firmware-images/upload-jobs/12345678901234567890123456789012/chunks \
-H 'Authorization: <valid access token>'
Path parameters
upload_job_id (required)
Path Parameter — The upload job ID.
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
minimum: 2
maximum: 1000
order (optional)
Query Parameter — ASC or DESC.
after (optional)
Query Parameter — The ID of the item after which to retrieve the next page.
include (optional)
Query Parameter — A comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL-encoded query string parameter to filter returned data

?filter={URL-encoded query string}

Filterable fields:

The table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
created_at
etag
id  
updated_at
hash  
length
 

The query string is made up of key-value pairs separated by ampersands. For example, this query: key1=value1&key2=value2&key3=value3

would be URL-encoded as: ?filter=key1__eq%3Dvalue1%26key2__eq%3Dvalue2%26key3__eq%3Dvalue3

Filtering by properties hash__eq=8FS70vXrq5y1VxAAssUMAg==

Filtering on date-time fields

Date-time fields should be specified in UTC RFC3339 format, YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds. Example: 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds. Example: 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened without milliseconds and punctuation. Example: 20161130T162512Z

Date-time filtering supports three operators:

  • equality by appending __eq to the field name
  • greater than or equal to by appending __gte to the field name
  • less than or equal to by appending __lte to the field name

{field name}[|__eq|__lte|__gte]={UTC RFC3339 date-time}

Time ranges may be specified by including both the __gte and __lte forms in the filter. For example:

created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering on multiple fields

status__eq=in_progress&created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated:

status__in=in_progress,success

Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "updated_at" : "2017-05-22T12:37:55.576563Z",
    "upload_job_id" : "00000000000000000000000000000000",
    "length" : 1234,
    "created_at" : "2017-05-22T12:37:55.576563Z",
    "etag" : "2017-05-22T12:37:58.753425Z",
    "id" : 1,
    "hash" : "aeiou",
    "object" : "upload-info"
  } ],
  "total_count" : 6,
  "limit" : 0,
  "after" : "null",
  "has_more" : true,
  "object" : "aeiou",
  "order" : "ASC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Ok. UploadChunkInfoPage
400 Bad Request. ErrorResponse
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse
get /v3/firmware-images/upload-jobs/{upload_job_id}/chunks/{chunk_id}
Get metadata about a chunk Show more Show less

Get metadata about a chunk.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/firmware-images/upload-jobs/12345678901234567890123456789012/chunks/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
upload_job_id (required)
Path Parameter — The upload job ID.
chunk_id (required)
Path Parameter — Chunk.
Return type
Example data
Content-Type: application/json
{
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "upload_job_id" : "00000000000000000000000000000000",
  "length" : 1234,
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "id" : 1,
  "hash" : "aeiou",
  "object" : "upload-info"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Ok. UploadChunkInfo
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse
post /v3/firmware-images/upload-jobs
Create a new upload job. Show more Show less

Create a new upload job
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/firmware-images/upload-jobs \
-H 'Authorization: <valid access token>' \
-H 'content-type: application/json;charset=UTF-8' \
-d '{
  "name": "New Linux update",
  "description": "New Linux update for my devices"
}'
Request body
Upload job Upload job (required)
Body Parameter — Upload job.
Return type
Example data
Content-Type: application/json
{
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "name" : "New Linux update",
  "description" : "New Linux update for my devices",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "firmware_image_id" : "00000000000000000000000000000000",
  "id" : "00000000000000000000000000000000",
  "complete" : false,
  "status" : "in_progress",
  "object" : "upload-job"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
201 Success - New job created. UploadJob
400 Bad Request. ErrorResponse
401 Not Authenticated. ErrorResponse
409 Conflict. ErrorResponse
delete /v3/firmware-images/upload-jobs/{upload_job_id}
Delete an upload job Show more Show less

Delete an upload job.
Usage example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v3/firmware-images/upload-jobs/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
upload_job_id (required)
Path Parameter — The upload job ID.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Job deleted - no content to show.
400 Bad Request. ErrorResponse
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse
get /v3/firmware-images/upload-jobs
Get all upload jobs Show more Show less

Get all upload jobs.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/firmware-images/upload-jobs \
-H 'Authorization: <valid access token>'
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
minimum: 2
maximum: 1000
order (optional)
Query Parameter — ASC or DESC.
after (optional)
Query Parameter — The ID of the item after which to retrieve the next page.
include (optional)
Query Parameter — A comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL-encoded query string parameter to filter returned data.

?filter={URL-encoded query string}

Filterable fields:

The table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
name  
description  
complete
id  
firmware_image_id  
status  
created_at
etag
updated_at
 

The query string is made up of key-value pairs separated by ampersands. For example, this query: key1=value1&key2=value2&key3=value3

would be URL-encoded as: ?filter=key1__eq%3Dvalue1%26key2__eq%3Dvalue2%26key3__eq%3Dvalue3

Filtering by properties name__eq=myimage

Filtering on date-time fields

Date-time fields should be specified in UTC RFC3339 format, YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds. Example: 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds. Example: 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened without milliseconds and punctuation. Example: 20161130T162512Z

Date-time filtering supports three operators:

  • equality by appending __eq to the field name
  • greater than or equal to by appending __gte to the field name
  • less than or equal to by appending __lte to the field name

{field name}[|__eq|__lte|__gte]={UTC RFC3339 date-time}

Time ranges may be specified by including both the __gte and __lte forms in the filter. For example:

created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering on multiple fields

name__eq=myimage&created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated:

name__in=fw-image1,fw-image2

Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "updated_at" : "2017-05-22T12:37:55.576563Z",
    "name" : "New Linux update",
    "description" : "New Linux update for my devices",
    "created_at" : "2017-05-22T12:37:55.576563Z",
    "etag" : "2017-05-22T12:37:58.753425Z",
    "firmware_image_id" : "00000000000000000000000000000000",
    "id" : "00000000000000000000000000000000",
    "complete" : false,
    "status" : "in_progress",
    "object" : "upload-job"
  } ],
  "total_count" : 6,
  "limit" : 0,
  "after" : "null",
  "has_more" : true,
  "object" : "aeiou",
  "order" : "ASC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Ok. UploadJobPage
400 Bad Request. ErrorResponse
401 Not Authenticated. ErrorResponse
get /v3/firmware-images/upload-jobs/{upload_job_id}
Retrieve information for an upload job Show more Show less

Get an upload job.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/firmware-images/upload-jobs/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
upload_job_id (required)
Path Parameter — The upload job ID.
Return type
Example data
Content-Type: application/json
{
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "name" : "New Linux update",
  "description" : "New Linux update for my devices",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "firmware_image_id" : "00000000000000000000000000000000",
  "id" : "00000000000000000000000000000000",
  "complete" : false,
  "status" : "in_progress",
  "object" : "upload-job"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Ok. UploadJob
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse
put /v3/firmware-images/upload-jobs/{upload_job_id}
Update an upload job Show more Show less

Update an upload job.
Usage example:

curl -X PUT https://api.us-east-1.mbedcloud.com/v3/firmware-images/upload-jobs/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>' \
-d '{
  "name": "New Linux update",
  "description": "New Linux update for my class XX devices"
}'
Path parameters
upload_job_id (required)
Path Parameter — The upload job ID.
Request body
Upload job Upload job_1 (required)
Body Parameter — Upload job.
Return type
Example data
Content-Type: application/json
{
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "name" : "New Linux update",
  "description" : "New Linux update for my devices",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "firmware_image_id" : "00000000000000000000000000000000",
  "id" : "00000000000000000000000000000000",
  "complete" : false,
  "status" : "in_progress",
  "object" : "upload-job"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Ok. UploadJob
400 Bad Request. ErrorResponse
401 Not Authenticated. ErrorResponse
404 Not Found. ErrorResponse

DeviceUpdateFirmwareManifests

post /v3/firmware-manifests/
Upload a manifest Show more Show less

Upload a firmware manifest. The API enforces a maximum manifest size of 2KB.
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/firmware-manifests \
-H 'Authorization: <valid access token>' \
-H 'Content-Type: multipart/form-data' \
-F 'datafile=@myimage.bin;type=application/octet-stream' \
-F 'description=bla bla' \
-F 'key_table=@myKeyTable.proto;type=' \
-F 'name=My Manifest'
Consumes
This API call consumes the following media types via the Content-Type request header:
  • multipart/form-data
Form parameters
datafile (required)
Form Parameter — The manifest file to create. The API gateway enforces the account-specific file size.
description (optional)
Form Parameter — The description of the firmware manifest.
key_table (optional)
Form Parameter — The key table of pre-shared keys for devices. The table is generated by the manifest tool.
name (optional)
Form Parameter — The name of the firmware manifest.
Return type
Example data
Content-Type: application/json
{
  "delivered_payload_digest" : "c520fc771c0482ad39e983d27cf725a7c724fe58c616129a34a420d1941068bc",
  "key_table" : "http://example.com/key-table",
  "precursor_payload_digest" : "54d640fcd687c9b13420b9be66a265494899002aad1b7370cfb3dbfd7fbec42f",
  "datafile_size" : 1,
  "description" : "",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "update_priority" : 0,
  "datafile" : "http://example.com/12345678901234567890123456789012",
  "parsed_raw_manifest" : "{}",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "delivered_payload_type" : "full",
  "name" : "manifest_name",
  "delivered_payload_url" : "http://example.com/abcdefghijklmnopqrstuvwxyz",
  "device_class" : "00000000-0000-0000-0000-000000000000",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "id" : "12345678901234567890123456789012",
  "device_vendor" : "00000000-0000-0000-0000-000000000000",
  "manifest_schema_version" : "1",
  "timestamp" : "2017-05-22T12:37:55.576563Z",
  "delivered_payload_size" : 6,
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
201 Created. FirmwareManifest
400 Validation error. The data used to create the firmware manifest did not validate and/or the manifest uploaded exceeded 2 KB in size.
401 Not authenticated.
403 Forbidden.
delete /v3/firmware-manifests/{manifest_id}
Delete a manifest Show more Show less

Delete a firmware manifest.
Usage example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v3/firmware-manifests/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
manifest_id (required)
Path Parameter — The firmware manifest ID.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Firmware manifest deleted.
400 Bad Request.
401 Not authenticated.
404 Firmware manifest not found.
get /v3/firmware-manifests/
List all firmware manifests. Show more Show less

List all firmware manifests.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/firmware-manifests \
-H 'Authorization: <valid access token>'
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
minimum: 2
maximum: 1000
order (optional)
Query Parameter — ASC or DESC.
after (optional)
Query Parameter — The ID of the item after which to retrieve the next page.
include (optional)
Query Parameter — A comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL-encoded query string parameter to filter returned data

?filter={URL-encoded query string}

Filterable fields:

The table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
created_at
datafile  
datafile_size  
description  
device_class  
etag
id  
name  
timestamp
updated_at
 

The query string is made up of key-value pairs separated by ampersands. For example, this query: key1__eq=value1&key2__eq=value2&key3__eq=value3

would be URL-encoded as: ?filter=key1__eq%3Dvalue1%26key2__eq%3Dvalue2%26key3__eq%3Dvalue3

Filtering by properties name__eq=mymanifest

Filtering on date-time fields

Date-time fields should be specified in UTC RFC3339 format, YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds. Example: 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds. Example: 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened without milliseconds and punctuation. Example: 20161130T162512Z

Date-time filtering supports three operators:

  • equality by appending __eq to the field name
  • greater than or equal to by appending __gte to the field name
  • less than or equal to by appending __lte to the field name

{field name}[|__eq|__lte|__gte]={UTC RFC3339 date-time}

Time ranges may be specified by including both the __gte and __lte forms in the filter. For example:

created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering on multiple fields

name__eq=mymanifest&created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated:

name__in=fw-manifest1,fw-manifest2

Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "delivered_payload_digest" : "c520fc771c0482ad39e983d27cf725a7c724fe58c616129a34a420d1941068bc",
    "key_table" : "http://example.com/key-table",
    "precursor_payload_digest" : "54d640fcd687c9b13420b9be66a265494899002aad1b7370cfb3dbfd7fbec42f",
    "datafile_size" : 1,
    "description" : "",
    "created_at" : "2017-05-22T12:37:55.576563Z",
    "update_priority" : 0,
    "datafile" : "http://example.com/12345678901234567890123456789012",
    "parsed_raw_manifest" : "{}",
    "updated_at" : "2017-05-22T12:37:55.576563Z",
    "delivered_payload_type" : "full",
    "name" : "manifest_name",
    "delivered_payload_url" : "http://example.com/abcdefghijklmnopqrstuvwxyz",
    "device_class" : "00000000-0000-0000-0000-000000000000",
    "etag" : "2017-05-22T12:37:58.753425Z",
    "id" : "12345678901234567890123456789012",
    "device_vendor" : "00000000-0000-0000-0000-000000000000",
    "manifest_schema_version" : "1",
    "timestamp" : "2017-05-22T12:37:55.576563Z",
    "delivered_payload_size" : 6,
    "object" : "aeiou"
  } ],
  "total_count" : 5,
  "limit" : 5,
  "after" : "null",
  "has_more" : true,
  "object" : "aeiou",
  "order" : "ASC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful. FirmwareManifestPage
400 Bad Request.
401 Not authenticated.
404 Unable to find content.
get /v3/firmware-manifests/{manifest_id}

Retrieve a firmware manifest.
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/firmware-manifests/12345678901234567890123456789012 \
-H 'Authorization: <valid access token>'
Path parameters
manifest_id (required)
Path Parameter — The firmware manifest ID.
Return type
Example data
Content-Type: application/json
{
  "delivered_payload_digest" : "c520fc771c0482ad39e983d27cf725a7c724fe58c616129a34a420d1941068bc",
  "key_table" : "http://example.com/key-table",
  "precursor_payload_digest" : "54d640fcd687c9b13420b9be66a265494899002aad1b7370cfb3dbfd7fbec42f",
  "datafile_size" : 1,
  "description" : "",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "update_priority" : 0,
  "datafile" : "http://example.com/12345678901234567890123456789012",
  "parsed_raw_manifest" : "{}",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "delivered_payload_type" : "full",
  "name" : "manifest_name",
  "delivered_payload_url" : "http://example.com/abcdefghijklmnopqrstuvwxyz",
  "device_class" : "00000000-0000-0000-0000-000000000000",
  "etag" : "2017-05-22T12:37:58.753425Z",
  "id" : "12345678901234567890123456789012",
  "device_vendor" : "00000000-0000-0000-0000-000000000000",
  "manifest_schema_version" : "1",
  "timestamp" : "2017-05-22T12:37:55.576563Z",
  "delivered_payload_size" : 6,
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Retrieved result successfully. FirmwareManifest
400 Bad request.
401 Not authenticated.
404 Firmware manifest can't be found.

Models

CampaignDeviceMetadata

name (optional)
String

maxLength: 128

The record name.

mechanism_url (optional)
String

The Device Management Connect URL.

mechanism (optional)
String

How the firmware is delivered (connector or direct).

id (optional)
String

The metadata record ID.

device_id (optional)
String

The device ID.

description (optional)
String

maxLength: 2000

Description.

deployment_state (optional)
String

The state of the update campaign on the device.

Enum:
pending
updated_connector_channel
failed_connector_channel_update
deployed
manifestremoved
deregistered
campaign (optional)
String

The device's campaign ID.

updated_at (optional)
Date ($date-time)

The time the entity was updated.

etag (optional)
String

API resource entity version.

created_at (optional)
Date ($date-time)

The time the entity was created.

object (optional)
String

The entity name: always 'update-campaign-device-metadata'.

CampaignDeviceMetadataPage

object (optional)
String

The entity name: always 'list'.

order (optional)
String

The order of the records to return. Acceptable values: ASC, DESC. Default: ASC.

Enum:
ASC
DESC
limit (optional)
Integer

How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.

after (optional)
String

The entity ID to fetch after the given one.

has_more (optional)
Boolean

A flag indicating whether there are more results.

data (optional)
total_count (optional)
Integer

The total number or records, if requested. It may be returned also for small lists.

CampaignMetrics

object (optional)
String

Entity name: always 'update-campaign-metrics'.

created_at (optional)
Date ($date-time)

The time the metrics were created.

success_count (optional)
Integer ($int32)

Running total of successfully updated devices.

failed_count (optional)
Integer ($int32)

Running total of devices that could not be updated.

pending_count (optional)
Integer ($int32)

Running total of devices that have yet to receive an update or are applying an update.

skipped_count (optional)
Integer ($int32)

Running total of devices that were skipped.

total_count (optional)
Integer ($int32)

Number of devices in the campaign.

ErrorResponse

object (optional)
String

Entity name: always 'error'.

code (optional)
Integer ($int32)

Response code.

type (optional)
message (optional)
fields (optional)
request_id (optional)

ErrorResponse_fields

name (optional)
message (optional)

EventType

object (optional)
String

Entity name: always 'event-type'.

created_at (optional)
Date ($date-time)

event_type (optional)
description (optional)
summary_status (optional)
id (optional)
count (optional)
summary_status_id (optional)
campaign_id (optional)
String

ID of the associated campaign.

EventTypeList

object (optional)
String

The entity name: always 'list'.

order (optional)
String

The order of the records to return. Acceptable values: ASC, DESC. Default: ASC.

Enum:
ASC
DESC
limit (optional)
Integer

The number of results to return, (range: 2-1000), or equals to total_count.

after (optional)
String

The entity ID to fetch after the given one.

has_more (optional)
Boolean

A flag indicating whether there are more results.

total_count (optional)
Integer

The total number or records, if requested. It may be returned also for small lists.

data (optional)

EventTypeSummary

object (optional)
String

Entity name: always 'summary_status'.

summary_status (optional)
String

The event type description.

Enum:
FAIL
SUCCESS
INFO
SKIPPED
id (optional)
String

ID of the event type description.

Enum:
fail
success
info
skipped
count (optional)
created_at (optional)
Date ($date-time)

campaign_id (optional)
String

ID of the associated campaign.

EventTypeSummaryList

object (optional)
String

The entity name: always 'list'.

order (optional)
String

The order of the records to return. Acceptable values: ASC, DESC. Default: ASC.

Enum:
ASC
DESC
limit (optional)
Integer

The number of results to return, (range: 2-1000), or equals to total_count.

after (optional)
String

The entity ID to fetch after the given one.

has_more (optional)
Boolean

A flag indicating whether there are more results.

total_count (optional)
Integer

The total number or records, if requested. It may be returned also for small lists.

data (optional)

FirmwareImage

name (optional)
String

maxLength: 128

The firmware image name.

id (optional)
String

The firmware image ID.

description (optional)
String

maxLength: 2000

The description of the object.

datafile_size (optional)
Long ($int64)

The size of the datafile in bytes.

datafile_checksum (optional)
String

The checksum (sha256) generated for the datafile.

datafile (optional)
String

The firmware image file URL

object (optional)
String

Entity name: always 'firmware-image'.

updated_at (optional)
Date ($date-time)

The time the entity was updated.

etag (optional)
String

API resource entity version.

created_at (optional)
Date ($date-time)

The time the entity was created.

FirmwareImageEqNeqFilter

created_at (optional)
Date ($date-time)

datafile (optional)
datafile_checksum (optional)
datafile_size (optional)
description (optional)
etag (optional)
Date ($date-time)

id (optional)
name (optional)
updated_at (optional)
Date ($date-time)

FirmwareImageGteLteFilter

created_at (optional)
Date ($date-time)

etag (optional)
Date ($date-time)

updated_at (optional)
Date ($date-time)

FirmwareImageInNinFilter

created_at (optional)
Date ($date-time)

datafile (optional)
datafile_checksum (optional)
datafile_size (optional)
description (optional)
etag (optional)
Date ($date-time)

id (optional)
name (optional)
updated_at (optional)
Date ($date-time)

FirmwareImagePage

object (optional)
String

Entity name: always 'list'.

after (optional)
data (optional)
has_more (optional)
limit (optional)
Integer ($int32)

order (optional)
String

The order of the records based on creation time, ASC or DESC; by default ASC.

Enum:
ASC
DESC
total_count (optional)
Integer ($int32)

FirmwareManifest

parsed_raw_manifest (optional)
Object

Raw manifest in JSON format, parsed from ASN.1 DER encoding. Fields may change. Backwards compatibility is not guaranteed. Recommended for debugging only.

timestamp (optional)
Date ($date-time)

The firmware manifest version as a timestamp.

name (optional)
String

maxLength: 128

The name of the manifest.

id (optional)
String

The firmware manifest ID.

key_table (optional)
String ($uri)

The key table of pre-shared keys for devices.

update_priority (optional)
Long ($int64)

Update priority, passed to the application callback when an update is performed. Allows the application to make application-specific decisions.

device_vendor (optional)
UUID ($uuid)

The device vendor ID.

device_class (optional)
UUID ($uuid)

The device class ID.

description (optional)
String

maxLength: 2000

The description of the firmware manifest.

precursor_payload_digest (optional)
String

Digest (SHA256, hex-encoded) of the currently installed payload.

delivered_payload_type (optional)
String

Type of the payload to deliver to the device (full or delta image).

Enum:
full
delta
delivered_payload_digest (optional)
String ($hex)

Digest (SHA256, hex-encoded) of the payload to deliver to the device.

delivered_payload_size (optional)
Long ($int64)

The size in bytes of the payload to deliver to the device.

delivered_payload_url (optional)
String ($uri)

The URL of the payload to deliver to the device.

datafile_size (optional)
Long ($int64)

The size of the firmware manifest in bytes.

datafile (optional)
String ($uri)

The URL of the ASN.1 DER-encoded firmware manifest binary.

manifest_schema_version (optional)
String

Version of the manifest schema (1 or 3).

Enum:
1
3
object (optional)
String

Entity name: always 'firmware-manifest'.

created_at (optional)
Date ($date-time)

The time the entity was created.

etag (optional)
String

API resource entity version.

updated_at (optional)
Date ($date-time)

The time the entity was updated.

FirmwareManifestEqNeqFilter

created_at (optional)
Date ($date-time)

datafile (optional)
datafile_size (optional)
description (optional)
device_class (optional)
etag (optional)
Date ($date-time)

id (optional)
name (optional)
timestamp (optional)
Date ($date-time)

updated_at (optional)
Date ($date-time)

FirmwareManifestGteLteFilter

created_at (optional)
Date ($date-time)

etag (optional)
Date ($date-time)

timestamp (optional)
Date ($date-time)

updated_at (optional)
Date ($date-time)

FirmwareManifestInNinFilter

created_at (optional)
Date ($date-time)

datafile (optional)
datafile_size (optional)
description (optional)
device_class (optional)
etag (optional)
Date ($date-time)

id (optional)
name (optional)
timestamp (optional)
Date ($date-time)

updated_at (optional)
Date ($date-time)

FirmwareManifestPage

object (optional)
String

Entity name: always 'list'.

after (optional)
data (optional)
has_more (optional)
limit (optional)
Integer ($int32)

order (optional)
String

The order of the records to return. Acceptable values: ASC, DESC. Default: ASC.

Enum:
ASC
DESC
total_count (optional)
Integer ($int32)

UpdateCampaign

when (optional)
Date ($date-time)

The scheduled start time for the campaign. The campaign will start within 1 minute when then start time has elapsed.

state (optional)
String

The state of the campaign.

Enum:
draft
scheduled
allocatingquota
allocatedquota
quotaallocationfailed
checkingmanifest
checkedmanifest
devicefetch
devicecopy
devicecheck
publishing
deploying
deployed
manifestremoved
expired
stopping
autostopped
userstopped
conflict
phase (optional)
String

The phase of the campaign.

Enum:
draft
awaiting_approval
timed
starting
active
stopping
stopped
deleted
archived
stopped_at (optional)
Date ($date-time)

The time the campaign was stopped.

stopping_at (optional)
Date ($date-time)

The time the campaign will be stopped.

started_at (optional)
Date ($date-time)

The time the campaign was started.

starting_at (optional)
Date ($date-time)

The time the campaign will be started.

root_manifest_url (optional)
String

The URL for the manifest that will be sent to the device as part of the campaign.

root_manifest_id (optional)
String

The ID of the manifest that will be sent to the device as part of the campaign.

name (optional)
String

maxLength: 128

The campaign name.

id (optional)
String

The campaign ID.

finished (optional)
Date ($date-time)

The time the campaign finished.

device_filter (optional)
String

The filter for the devices the campaign is targeting at.

description (optional)
String

maxLength: 2000

An optional description of the campaign.

autostop_reason (optional)
String

Text description of why a campaign failed to start or why a campaign stopped.

autostop_success_percent (optional)
Double ($double)

Percent of successful device updates to auto stop the campaign.

autostop (optional)
Boolean

Flag indicating whether the campaign should be auto-stopped on reaching a threshold.

archived_at (optional)
Date ($date-time)

The time the campaign was archived.

approval_required (optional)
Boolean

Flag indicating whether approval is needed to start the campaign.

active_at (optional)
Date ($date-time)

The time the campaign entered the active state.

campaign_strategy (optional)
String

How the campaign adds devices. A one-shot campaign does not add new devices after it has started. A continuous campaign means that devices may be added to the campaign after it has started. The default is one-shot.

Enum:
one-shot
continuous
created_at (optional)
Date ($date-time)

The time the entity was created.

etag (optional)
String

API resource entity version.

updated_at (optional)
Date ($date-time)

The time the entity was updated.

object (optional)
String

Entity name: always 'update-campaign'.

UpdateCampaignEqNeqFilter

created_at (optional)
Date ($date-time)

description (optional)
device_filter (optional)
etag (optional)
Date ($date-time)

finished (optional)
Date ($date-time)

id (optional)
name (optional)
root_manifest_id (optional)
started_at (optional)
Date ($date-time)

state (optional)
when (optional)
Date ($date-time)

updated_at (optional)
Date ($date-time)

UpdateCampaignGteLteFilter

created_at (optional)
Date ($date-time)

etag (optional)
Date ($date-time)

finished (optional)
Date ($date-time)

started_at (optional)
Date ($date-time)

when (optional)
Date ($date-time)

updated_at (optional)
Date ($date-time)

UpdateCampaignInNinFilter

created_at (optional)
Date ($date-time)

description (optional)
device_filter (optional)
etag (optional)
Date ($date-time)

finished (optional)
Date ($date-time)

id (optional)
name (optional)
root_manifest_id (optional)
started_at (optional)
Date ($date-time)

state (optional)
when (optional)
Date ($date-time)

updated_at (optional)
Date ($date-time)

UpdateCampaignPage

object (optional)
String

Entity name: always 'list'.

after (optional)
data (optional)
has_more (optional)
limit (optional)
order (optional)
String

The order of the records to return. Acceptable values: ASC, DESC. Default: ASC.

Enum:
ASC
DESC
total_count (optional)

UpdateCampaignPostRequest

autostop_success_percent (optional)
autostop (optional)
approval_required (optional)
root_manifest_id (optional)
String

maxLength: 32

minLength: 32

name (optional)
String

maxLength: 128

The name for this campaign.

device_filter
String

The filter for the devices the campaign is targeted at.

description (optional)
String

maxLength: 2000

An optional description of the campaign.

campaign_strategy (optional)
String

How the campaign adds devices. A one-shot campaign does not add new devices after it has started. A continuous campaign means that devices may be added to the campaign after it has started. The default is one-shot.

Enum:
one-shot
continuous

UpdateCampaignPutRequest

description (optional)
String

maxLength: 2000

An optional description of the campaign.

device_filter (optional)
String

The filter for the devices the campaign is targeting at.

name (optional)
String

maxLength: 128

The campaign's name.

root_manifest_id (optional)
String

maxLength: 32

approval_required (optional)
autostop (optional)
autostop_success_percent (optional)

Upload job

name (optional)
String

maxLength: 128

Human-readable name.

description (optional)
String

maxLength: 2000

Human-readable description.

Upload job_1

description (optional)
String

maxLength: 2000

Human-readable description.

name (optional)
String

maxLength: 128

Human-readable name.

UploadChunkInfo

updated_at (optional)
Date ($date-time)

The time the entity was updated.

etag (optional)
String

API resource entity version.

created_at (optional)
Date ($date-time)

The time the entity was created.

object (optional)
String

Entity name: always 'upload-info'.

upload_job_id (optional)
String

The upload job ID.

length (optional)
Integer

The length of the chunk.

hash (optional)
String

The hash of the chunk. The default hash is MD5. If no Content-MD5 header is supplied as part of uploading the chunk then this will be empty.

id (optional)
Integer

The chunk number.

UploadChunkInfoPage

object (optional)
String

Entity name: always 'list'.

after (optional)
data (optional)
has_more (optional)
limit (optional)
Integer ($int32)

order (optional)
String

The order of the records to return. Acceptable values: ASC, DESC. Default: ASC.

Enum:
ASC
DESC
total_count (optional)
Integer ($int32)

UploadJob

status (optional)
String

Status of the upload job.

firmware_image_id (optional)
String

ID of the firmware image - empty until the upload job is complete.

id (optional)
String

The upload job ID.

complete (optional)
Boolean

A flag that indicates job completion.

description (optional)
String

maxLength: 2000

Human-readable description.

name (optional)
String

maxLength: 128

Human-readable name.

created_at (optional)
Date ($date-time)

The time the entity was created.

etag (optional)
String

API resource entity version.

updated_at (optional)
Date ($date-time)

The time the entity was updated.

object (optional)
String

Entity name: always 'upload-job'.

UploadJobPage

object (optional)
String

Entity name: always 'list'.

after (optional)
data (optional)
has_more (optional)
limit (optional)
Integer ($int32)

order (optional)
String

The order of the records to return. Acceptable values: ASC, DESC. Default: ASC.

Enum:
ASC
DESC
total_count (optional)
Integer ($int32)