You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 1.2.

Deployments

Overview

An API for deployments and artifacts management. Intended for use by the web GUI.

Version information

Version : 1

URI scheme

Host : docker.mender.io
BasePath : /api/management/v1/deployments
Schemes : HTTPS

Paths


Upload mender artifact

POST /artifacts

Description

Upload medner artifact. Multipart request with meta and artifact.

Supports artifact (versions v1, v2)[https://docs.mender.io/development/architecture/mender-artifacts#versions].

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
FormData artifact
required
Artifact. It has to be the last part of request. file
FormData description
optional
string
FormData size
required
Size of the artifact file in bytes. integer(long)

Responses

HTTP Code Description Schema
201 Artifact uploaded.
Headers :
Location (string) : URL of the newly uploaded artifact.
No Content
400 Invalid Request. Error
500 Internal Server Error. Error

Consumes

  • multipart/form-data

Produces

  • application/json

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

List known artifacts

GET /artifacts

Description

Returns a collection of all artifacts.

Responses

HTTP Code Description Schema
200 OK < Artifact > array
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "application/json" : [ {
    "name" : "Application 1.0.0",
    "description" : "Johns Monday test build",
    "device_types_compatible" : [ "Beagle Bone" ],
    "id" : "0c13a0e6-6b63-475d-8260-ee42a590e8ff",
    "signed" : false,
    "modified" : "2016-03-11T13:03:17.063493443Z",
    "info" : {
      "type_info" : {
        "type" : "rootfs"
      }
    },
    "files" : [ {
      "name" : "rootfs-image-1",
      "checksum" : "cc436f982bc60a8255fe1926a450db5f195a19ad",
      "size" : 123,
      "date" : "2016-03-11T13:03:17.063+0000"
    } ],
    "metadata" : { }
  } ]
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Get the details of a selected artifact

GET /artifacts/{id}

Description

Returns the details of a selected artifact.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Artifact identifier. string

Responses

HTTP Code Description Schema
200 Successful response. Artifact
400 Invalid Request. Error
404 Not Found. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "name" : "Application 1.0.0",
    "description" : "Johns Monday test build",
    "device_types_compatible" : [ "Beagle Bone" ],
    "id" : "0c13a0e6-6b63-475d-8260-ee42a590e8ff",
    "signed" : false,
    "modified" : "2016-03-11T13:03:17.063493443Z",
    "info" : {
      "type_info" : {
        "type" : "rootfs"
      }
    },
    "files" : [ {
      "name" : "rootfs-image-1",
      "checksum" : "cc436f982bc60a8255fe1926a450db5f195a19ad",
      "size" : 123,
      "date" : "2016-03-11T13:03:17.063+0000"
    } ],
    "metadata" : { }
  }
}
Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Update description of a selected artifact

PUT /artifacts/{id}

Description

Edit description. Artifact is not allowed to be edited if it was used in any deployment.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Artifact identifier. string
Body artifact
optional
ArtifactUpdate

Responses

HTTP Code Description Schema
204 The artifact metadata updated successfully. No Content
400 Invalid Request. Error
404 Not Found. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP request

Request body
json :
{
  "description" : "Some description"
}

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Delete the artifact

DELETE /artifacts/{id}

Description

Deletes the artifact from file and artifacts storage. Artifacts used by deployments in progress can not be deleted until deployment finishes.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Artifact identifier. string

Responses

HTTP Code Description Schema
204 The artifact deleted successfully. No Content
404 Not Found. Error
409 Artifact used by active deployment. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 409
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Get the download link of a selected artifact

GET /artifacts/{id}/download

Description

Generates signed URL for downloading artifact file. URI can be used only with GET HTTP method. Link supports such HTTP headers: 'Range', 'If-Modified-Since', 'If-Unmodified-Since' It is valid for specified period of time.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Artifact identifier. string
Query expire
optional
Link validity length in minutes. Min 1 minute, max 10080 (1 week). integer "60"

Responses

HTTP Code Description Schema
200 Successful response. ArtifactLink
400 Invalid Request. Error
404 Not Found. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "uri" : "http://mender.io/artifact.tar.gz.mender",
    "expire" : "2016-10-29T10:45:34.000+0000"
  }
}
Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Create a deployment

POST /deployments

Description

Deploy software to specified devices. Artifact is auto assigned to the device from all available artifacts based on artifact name and device type. Devices for which there are no compatible artifacts to be installed are considered finished successfully as well as receive status of noartifact. If there is no artifacts for the deployment, deployment will not be created and the 422 Unprocessable Entity status code will be returned.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Body deployment
required
New deployment that needs to be created. NewDeployment

Responses

HTTP Code Description Schema
201 New deployment created.
Headers :
Location (string) : URL of the newly created deployment.
No Content
400 Invalid Request. Error
422 Unprocessable Entity. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP request

Request body
json :
{
  "application/json" : [ {
    "name" : "production",
    "artifact_name" : "Application 0.0.1",
    "devices" : [ "00a0c91e6-7dec-11d0-a765-f81d4faebf6" ]
  } ]
}

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 422
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Find all deployments

GET /deployments

Description

Returns a filtered collection of deployments in the system, including active and historical. If both 'status' and 'query' are not specified, all devices are listed.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Query page
optional
Results page number number(integer) "1"
Query per_page
optional
Number of results per page number(integer) "20"
Query search
optional
Deployment name or description filter. string
Query status
optional
Deployment status filter. enum (inprogress, finished, pending)

Responses

HTTP Code Description Schema
200 Successful response.
Headers :
Link (string) : Standard header, we support 'first', 'next', and 'prev'.
< Deployment > array
400 Invalid Request. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "application/json" : [ {
    "created" : "2016-02-11T13:03:17.063+0000",
    "status" : "finished",
    "name" : "production",
    "artifact_name" : "Application 0.0.1",
    "id" : "00a0c91e6-7dec-11d0-a765-f81d4faebf6",
    "finished" : "2016-03-11T13:03:17.063+0000"
  } ]
}
Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Remove device from all deployments

DELETE /deployments/devices/{id}

Description

Set 'decommissioned' status to all pending device deployments for a given device

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
System wide device identifier string

Responses

HTTP Code Description Schema
204 Device was removed No Content
500 Internal server error. Error

Example HTTP response

Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

List devices of a deployment

GET /deployments/{deployment_id}/devices

Description

Returns a collection of a selected deployment's status for each assigned device.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path deployment_id
required
Deployment identifier. string

Responses

HTTP Code Description Schema
200 OK < Device > array
404 Not Found. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "application/json" : [ {
    "id" : "00a0c91e6-7dec-11d0-a765-f81d4faebf6",
    "finished" : "2016-03-11T13:03:17.063+0000",
    "status" : "pending",
    "created" : "2016-02-11T13:03:17.063+0000",
    "device_type" : "Raspberry Pi 3"
  } ]
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Get the log of a selected device's deployment

GET /deployments/{deployment_id}/devices/{device_id}/log

Description

Returns the log of a selected device, collected during a particular deployment.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path deployment_id
required
Deployment identifier. string
Path device_id
required
Device identifier. string

Responses

HTTP Code Description Schema
200 Successful response. No Content
404 Not Found. Error
500 Internal Server Error. Error

Produces

  • text/plain

Example HTTP response

Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Get the statistics of a selected deployment

GET /deployments/{deployment_id}/statistics

Description

Returns the statistics of a selected deployment statuses.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path deployment_id
required
Deployment identifier string

Responses

HTTP Code Description Schema
200 OK DeploymentStatistics
404 Not Found. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "success" : 3,
    "pending" : 1,
    "failure" : 0,
    "downloading" : 1,
    "installing" : 2,
    "rebooting" : 3,
    "noartifact" : 0,
    "already-installed" : 0,
    "aborted" : 0
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Abort the deployment

PUT /deployments/{deployment_id}/status

Description

Aborts the deployment that is pending or in progress. For devices included in this deployment it means that:

  • Devices that have completed the deployment (i.e. reported final status) are not affected by the abort, and their original status is kept in the deployment report.
  • Devices that do not yet know about the deployment at time of abort will not start the deployment.
  • Devices that are in the middle of the deployment at time of abort will finish its deployment normally, but they will not be able to change its deployment status so they will perform rollback.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path deployment_id
required
Deployment identifier. string
Body Status
required
Deployment status. Status

Status

Name Description Schema
status
required
enum (aborted)

Responses

HTTP Code Description Schema
204 Status updated successfully. No Content
400 Invalid Request. Error
404 Not Found. Error
422 Unprocessable Entity. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 422
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Get the details of a selected deployment

GET /deployments/{id}

Description

Returns the details of a particular deployment.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Deployment identifier. string

Responses

HTTP Code Description Schema
200 Successful response. Deployment
404 Not Found. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "created" : "2016-02-11T13:03:17.063+0000",
    "name" : "production",
    "artifact_name" : "Application 0.0.1",
    "id" : "00a0c91e6-7dec-11d0-a765-f81d4faebf6",
    "finished" : "2016-03-11T13:03:17.063+0000"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Get storage limit and current storage usage

GET /limits/storage

Description

Get storage limit and current storage usage for currently logged in user. If the limit value is 0 it means there is no limit for storage for logged in user.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])

Responses

HTTP Code Description Schema
200 Successful response. StorageLimit
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "limit" : 1073741824,
    "usage" : 536870912
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Definitions

Artifact

Detailed artifact.

Name Description Schema
description
required
string
device_types_compatible
required
< string > array
id
required
string
info
optional
ArtifactInfo
modified
required
Represents creation / last edition of any of the artifact properties. string(date-time)
name
required
string
signed
optional
Idicates if artifact is signed or not. boolean
updates
optional
< Update > array

ArtifactInfo

Information about artifact format and version.

Name Description Schema
format
optional
string
version
optional
integer

ArtifactLink

URL for artifact file download.

Name Description Schema
expire
required
string(date-time)
uri
required
string

ArtifactTypeInfo

Information about update type.

Name Description Schema
type
optional
string

ArtifactUpdate

Artifact information update.

Name Description Schema
description
optional
string

Deployment

Name Description Schema
artifact_name
required
string
artifacts
optional
< string > array
created
required
string(date-time)
finished
optional
string(date-time)
id
required
string
name
required
string
status
required
enum (inprogress, pending, finished)

DeploymentStatistics

Name Description Schema
aborted
required
Number of deployments aborted by user. integer
already-installed
required
Number of devices unaffected by upgrade, since they are already running the specified software version. integer
downloading
required
Number of deployments being downloaded. integer
failure
required
Number of failed deployments. integer
installing
required
Number of deployments devices being installed. integer
noartifact
required
Do not have appropriate artifact for device type. integer
pending
required
Number of pending deployments. integer
rebooting
required
Number of deployments devices are rebooting into. integer
success
required
Number of successful deployments. integer

Device

Name Description Schema
created
optional
string(date-time)
device_type
optional
string
finished
optional
string(date-time)
id
required
Device identifier. string
log
required
Availability of the device's deployment log. boolean
status
required
enum (inprogress, pending, success, failure, noartifact, aborted)

Error

Error descriptor.

Name Description Schema
error
optional
Description of the error. string
request_id
optional
Request ID (same as in X-MEN-RequestID header). string

NewDeployment

Name Description Schema
artifact_name
required
string
devices
required
< string > array
name
required
string

StorageLimit

Tenant account storage limit and storage usage.

Name Description Schema
limit
required
Storage limit in bytes. If set to 0 - there is no limit for storage. integer
usage
required
Current storage usage in bytes. integer

Update

Single updated to be applied.

Name Description Schema
files
optional
< UpdateFile > array
meta_data
optional
meta_data is an object of unknown structure as this is dependent of update type (also custom defined by user) object
type_info
optional
ArtifactTypeInfo

UpdateFile

Information about particular update file.

Name Description Schema
checksum
optional
string
date
optional
string(date-time)
name
optional
string
size
optional
integer