### Generate Getting Started Data with Management API Example

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/README.md

Executes an example management simulator to generate initial data for Hawkbit. Replace '#version#' with the actual version number.

```bash
java -jar ./hawkbit-example-mgmt-simulator/target/hawkbit-example-mgmt-simulator-#version#-exec.jar
```

--------------------------------

### Example DMF Download and Install Message

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/DMF API

An example of a complete message, including headers and payload, for initiating a download and install task. This demonstrates the expected values for a typical request.

```json
{
"actionId":137,
"targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY",
"softwareModules":[
    {
    "moduleId":7,
    "moduleType":"firmware",
    "moduleVersion":"7.7.7",
    "artifacts":[
        {
        "filename":"artifact.zip",
        "urls":{
            "HTTP":"http://download-from-url.com",
            "HTTPS":"https://download-from-url.com"
            },
        "hashes":{
            "md5":"md5hash",
            "sha1":"sha1hash"
            },
        "size":512
        }],
    "metadata":[
        {
            "key":"installationType",
            "value":"5784K#"
        }
    ]
    }]
}
```

--------------------------------

### Start Rollout Request

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

This is an example of a POST request to start a created rollout. The rolloutId path parameter must be specified.

```http
POST /rest/v1/rollouts/{rolloutId}/start HTTP/1.1
Host: localhost:59874
Accept: application/json
```

--------------------------------

### Response Sample for Bad Request (Installed Base)

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/ddi.html

Example JSON response for a 400 Bad Request error when updating installed base information.

```json
{
  "exceptionClass": "string",
  "errorCode": "string",
  "message": "string",
  "parameters": [
    "string"
  ]
}
```

--------------------------------

### Start Rollout

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

Handles the POST request of starting a created rollout. Requires HANDLE_ROLLOUT permission.

```APIDOC
## POST /rest/v1/rollouts/{rolloutId}/start

### Description
Starts a previously created rollout.

### Method
POST

### Endpoint
/rest/v1/rollouts/{rolloutId}/start

### Parameters
#### Path Parameters
- **rolloutId** (integer) - Required - The ID of the rollout to start.

### Response
#### Success Response (200)
- **(object)** - Successfully started the rollout.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Start a Rollout

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

Handles the POST request of starting a created rollout. This operation requires the HANDLE_ROLLOUT permission.

```APIDOC
## POST /rest/v1/rollouts/{rolloutId}/start

### Description
Starts a created rollout.

### Method
POST

### Endpoint
/rest/v1/rollouts/{rolloutId}/start

### Parameters
#### Path Parameters
- **rolloutId** (integer <int64>) - Required - The ID of the rollout to start.

### Responses
#### Success Response (200)
- **Success** - Successfully started.

#### Error Responses
- **400** - Bad Request - e.g. invalid parameters
- **401** - The request requires user authentication.
- **403** - Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.
- **405** - The http request method is not allowed on the resource.
- **406** - In case accept header is specified and not application/json.
- **429** - Too many requests. The server will refuse further attempts and the client has to wait another second.
```

--------------------------------

### Retrieve All Targets

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docs/rest-api/mgmt.html

This example demonstrates a GET request to retrieve all targets. It supports query parameters for pagination (offset, limit), sorting, and filtering using FIQL.

```http
GET /rest/v1/targets?offset=0&limit=50&sort=string&q=string HTTP/1.1
Host: localhost:53002
Accept: application/json
```

--------------------------------

### Get Previously Installed Action

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docs/rest-api/ddi.html

Retrieves information about a previously completed installation action for a given controller. Can optionally include historical messages. The response format is similar to the deploymentBase operation.

```http
GET /{{tenant}}/controller/v1/{{controllerId}}/installedBase/{{actionId}}
```

--------------------------------

### RSQL Combining Conditions Examples

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-mcp/hawkbit-mcp-starter/src/main/resources/prompts/rsql-help.md

Examples demonstrating how to combine RSQL conditions using AND (;) and OR (,).

```text
status==RUNNING;name==Device*
```

```text
status==ERROR,status==CANCELED
```

--------------------------------

### RSQL Comparison Operators Examples

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-mcp/hawkbit-mcp-starter/src/main/resources/hawkbit-entity-definitions.md

Examples demonstrating RSQL comparison operators for filtering entities.

```text
name==MyTarget
```

```text
status!=ERROR
```

```text
createdAt=lt=1609459200000
```

```text
weight=le=500
```

```text
lastTargetQuery=gt=1609459200000
```

```text
id=ge=100
```

```text
status=in=(RUNNING,FINISHED)
```

```text
updateStatus=out=(ERROR,UNKNOWN)
```

--------------------------------

### Get Previously Installed Action

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docs/rest-api/ddi.html

Retrieves information about a previously installed action. This can be used to re-download artifacts of a finished action, for example, for re-installation.

```APIDOC
## GET /controller/v1/{tenant}/controller/{controllerId}/installedBase/{actionId}

### Description
Retrieves information about a previously installed action. This can be used to re-download artifacts of a finished action, for example, for re-installation.

### Method
GET

### Endpoint
/controller/v1/{tenant}/controller/{controllerId}/installedBase/{actionId}

### Parameters
#### Path Parameters
- **tenant** (string) - Required - The tenant identifier.
- **controllerId** (string) - Required - The ID of the controller.
- **actionId** (integer <int64>) - Required - The ID of the action.

#### Query Parameters
- **actionHistory** (integer <int32>) - Optional - Default: 0. Specifies the history of actions to retrieve.

### Responses
#### Success Response (200)
The response body includes the detailed operation for the already finished action in the same format as for the deploymentBase operation. The (optional) query for the last 10 messages, previously provided by the device, are included.

#### Error Responses
- **400** Bad Request - e.g. invalid parameters
- **401** The request requires user authentication.
- **403** Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.
- **405** The http request method is not allowed on the resource.
- **406** In case accept header is specified and not application/json.
- **429** Too many requests. The server will refuse further attempts and the client has to wait another second.
```

--------------------------------

### Example MULTI_ACTION Header and Payload

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/DMF API

This example demonstrates a MULTI_ACTION message with two actions: DOWNLOAD_AND_INSTALL and DOWNLOAD. It includes specific values for action IDs, security tokens, module details, and artifact information, showcasing a practical use case.

```json
[{
"topic": "DOWNLOAD_AND_INSTALL",
"weight": 600,
"action": {
  "actionId":137,
  "targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY",
  "softwareModules":[
      {
      "moduleId":7,
      "moduleType":"firmware",
      "moduleVersion":"7.7.7",
      "artifacts":[
          {
          "filename":"artifact.zip",
          "urls":{
              "HTTP":"http://download-from-url.com",
              "HTTPS":"https://download-from-url.com"
              },
          "hashes":{
              "md5":"md5hash",
              "sha1":"sha1hash"
              },
          "size":512
          }],
      "metadata":[
          {
              "key":"installationType",
              "value":"5784K#"
          }
      ]
      }]
  }
},
{
"topic": "DOWNLOAD",
"weight": 500,
"action": {
  "actionId":138,
  "targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY",
  "softwareModules":[
      {
      "moduleId":4,
      "moduleType":"firmware",
      "moduleVersion":"7.7.9",
      "artifacts":[
          {
          "filename":"artifact.zip",
          "urls":{
              "HTTP":"http://download-from-url.com",
              "HTTPS":"https://download-from-url.com"
              },
          "hashes":{
              "md5":"md5hash",
              "sha1":"sha1hash"
              },
          "size":512
          }],
      "metadata":[
          {
              "key":"installationType",
              "value":"5784K#"
          }
      ]
      }]
  }
}]
```

--------------------------------

### Get Installed Base

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/ddi/index.html

Retrieves the installed base for a controller.

```APIDOC
## GET /tenant/controller/v1/{controllerid}/installedbas

### Description
Retrieves the installed base for a controller.

### Method
GET

### Endpoint
/tenant/controller/v1/{controllerid}/installedbas

### Parameters
#### Path Parameters
- **controllerid** (string) - Required - The ID of the controller.
```

--------------------------------

### Get Installed Base Action

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/ddi/index.html

Retrieves details of an installed base action.

```APIDOC
## GET /tenant/controller/v1/{controllerid}/installedbase/{actionid}

### Description
Retrieves details of an installed base action.

### Method
GET

### Endpoint
/tenant/controller/v1/{controllerid}/installedbase/{actionid}

### Parameters
#### Path Parameters
- **controllerid** (string) - Required - The ID of the controller.
- **actionid** (string) - Required - The ID of the installed base action.
```

--------------------------------

### Get Installed Distributions

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docs/rest-api/mgmt.html

Retrieves the list of installed distributions for a specified target ID.

```APIDOC
## GET /rest/v1/targets/{targetId}/installedDS

### Description
Retrieves the list of installed distributions for a specified target ID.

### Method
GET

### Endpoint
/rest/v1/targets/{targetId}/installedDS

### Parameters
#### Path Parameters
- **targetId** (string) - Required - The unique identifier of the target.

### Response
#### Success Response (200)
- **installedDistributions** (array) - A list of installed distributions.
  - **name** (string) - The name of the distribution.
  - **version** (string) - The version of the distribution.
  - **type** (string) - The type of the distribution.

#### Response Example
{
  "installedDistributions": [
    {
      "name": "example-dist",
      "version": "1.0.0",
      "type": "os"
    }
  ]
}
```

--------------------------------

### Soft/Forced Switch Example (DDI)

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/Separation-of-Download-and-Install

Shows a DDI deployment configuration where download is 'attempt' and update is 'forced', highlighting a potential API design consideration.

```json
{
  "deployment" : {
    "download" : "attempt",
    "update" : "forced",

```

--------------------------------

### Run HawkBit Management Server with Main Class

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-mgmt/hawkbit-mgmt-server/README.md

Alternatively, run the hawkBit Management Server using its main class.

```bash
run org.eclipse.hawkbit.app.mgmt.MgmtServerStart
```

--------------------------------

### Get Installed Devices for Target

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

Retrieves a list of devices installed on a specific target.

```APIDOC
## GET /rest/v1/targets/{targetid}/installedd

### Description
Retrieves a list of devices installed on a specific target.

### Method
GET

### Endpoint
/rest/v1/targets/{targetid}/installedd
```

--------------------------------

### Request Payload for Installed Base

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/ddi.html

Example JSON payload for updating the installed base information for a controller.

```json
{
  "name": "linux",
  "version": "1.2.3"
}
```

--------------------------------

### Paging and Sorting Examples

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docs/query-parameters.md

Demonstrates how to combine sorting with pagination parameters 'offset' and 'limit'. Note that 'limit' is capped at a maximum value.

```HTTP
/targets?sort=name:ASC
```

```HTTP
/targets?sort=name:ASC&limit=10
```

```HTTP
/targets?sort=name:ASC&offset=10
```

```HTTP
/targets?sort=name:ASC&offset=20&limit=10
```

```HTTP
/targets?sort=name:ASC&offset=100&limit=600
```

--------------------------------

### Start Hawkbit Device Simulator with Gateway Token Authentication

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/README.md

Starts the demo Device Simulator. Ensure gateway token authentication is enabled on the update server and configure the DDI URL, controller ID, and gateway token accordingly.

```bash
export hawkbit_server_ddiurl=http://localhost:8080
export demo_controller_id=demo
export hawkbit_tenant_gatewaytoken=gw_token

java -jar ./hawkbit-sdk/hawkbit-sdk-demo/target/hawkbit-sdk-demo-0-SNAPSHOT.jar
```

--------------------------------

### Start Hawkbit UI

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/README.md

Launches the Hawkbit user interface. Access it at http://localhost:8088 and log in with the default user admin:admin.

```bash
java -jar ./hawkbit-ui/target/hawkbit-ui.jar
```

--------------------------------

### Get Installed Distribution Set

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

Retrieves the installed distribution set for a specific target. This operation requires READ_TARGET permission.

```APIDOC
## GET /rest/v1/targets/{targetId}/distribution-set

### Description
Handles the GET request of retrieving the installed distribution set of an specific target.

### Method
GET

### Endpoint
/rest/v1/targets/{targetId}/distribution-set

### Parameters
#### Path Parameters
- **targetId** (string) - Required - The ID of the target.

### Responses
#### Success Response (200)
- **MgmtDistributionSet** - The installed distribution set of the target.

#### Error Responses
- **400** - Bad Request - e.g. invalid parameters
- **401** - Unauthorized - The request requires user authentication.
- **403** - Forbidden - Insufficient permissions.
- **404** - Not Found - Target not found.
- **405** - Method Not Allowed - The http request method is not allowed on the resource.
- **406** - Not Acceptable - In case accept header is specified and not application/json.
- **429** - Too Many Requests - The server will refuse further attempts and the client has to wait another second.
```

--------------------------------

### Return installed targets to a specific distribution set

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

Handles the GET request for retrieving installed targets of a single distribution set. This endpoint lists the targets that have a specific distribution set installed on them.

```APIDOC
## GET /rest/v1/distributionsets/{distributionSetId}/installedTargets

### Description
Retrieves a list of installed targets for a specific distribution set.

### Method
GET

### Endpoint
/rest/v1/distributionsets/{distributionSetId}/installedTargets

### Parameters
#### Path Parameters
- **distributionSetId** (integer <int64>) - Required - The ID of the distribution set.

#### Query Parameters
- **offset** (string) - Optional - The paging offset (default is 0).
- **limit** (string) - Optional - The maximum number of entries in a page (default is 50).
- **sort** (string) - Optional - The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.
- **q** (string) - Optional - Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for available fields.

### Response
#### Success Response (200)
(Response schema not explicitly defined in source, but implies a list of installed targets.)

### Response Example
(Response example not explicitly defined in source.)
```

--------------------------------

### Run HawkBit DDI Server with Main Class

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-ddi/hawkbit-ddi-server/README.md

Start the HawkBit DDI Server by directly executing its main class.

```bash
run org.eclipse.hawkbit.app.ddi.DdiStart
```

--------------------------------

### DDI Deployment Base Resource Example

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/Separation-of-Download-and-Install

Illustrates how the ETag changes in the deploymentBase resource URI to signal updates to the device.

```text
https://HOST/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/1?c=-2130877640 switches to https://HOST/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/1?c=-2130877641
```

--------------------------------

### RSQL Wildcards Examples

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-mcp/hawkbit-mcp-starter/src/main/resources/prompts/rsql-help.md

Examples of using RSQL wildcards (*) for pattern matching in queries. Supports matching strings that start with, end with, or contain a specific pattern.

```text
name==Device*
```

```text
name==*Controller
```

```text
name==*test*
```

--------------------------------

### Software Module with Artifacts

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/ddi.html

Example response showing a software module with its version, name, and associated artifacts. Each artifact includes filename, hashes (md5, sha1, sha256), size, and download links.

```json
{
  "part": "os",
  "version": "1.0.79",
  "name": "one Firmware",
  "artifacts": [
    {
      "filename": "binary.tgz",
      "hashes": {
        "sha1": "574cd34be20f75d101ed23518339cc38c5157bdb",
        "md5": "a0637c1ccb9fd53e2ba6f45712516989",
        "sha256": "498014801aab66be1d7fbea56b1aa5959651b6fd710308e196a8c414029e7291"
      },
      "size": 13,
      "_links": {
        "download": {
          "href": "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/binary.tgz"
        },
        "download-http": {
          "href": "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/binary.tgz"
        },
        "md5sum-http": {
          "href": "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/binary.tgz.MD5SUM"
        },
        "md5sum": {
          "href": "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/binary.tgz.MD5SUM"
        }
      }
    },
    {
      "filename": "file.signature",
      "hashes": {
        "sha1": "574cd34be20f75d101ed23518339cc38c5157bdb",
        "md5": "a0637c1ccb9fd53e2ba6f45712516989",
        "sha256": "498014801aab66be1d7fbea56b1aa5959651b6fd710308e196a8c414029e7291"
      },
      "size": 13,
      "_links": {
        "download": {
          "href": "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/file.signature.MD5SUM"
        },
        "download-http": {
          "href": "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/file.signature.MD5SUM"
        },
        "md5sum-http": {
          "href": "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/file.signature.MD5SUM"
        },
        "md5sum": {
          "href": "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/file.signature.MD5SUM"
        }
      }
    }
  ]
}
```

--------------------------------

### Previously Installed Action

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/ddi/index.html

Resource to receive information of the previous installation. Can be used to re-retrieve artifacts of the already finished action, for example in case a re-installation is necessary.

```APIDOC
## GET /{tenant}/controller/v1/{controllerId}/installedBase/{actionId}

### Description
Resource to receive information of the previous installation. Can be used to re-retrieve artifacts of the already finished action, for example in case a re-installation is necessary. The response will be of the same format as the deploymentBase operation, providing the previous action that has been finished successfully. As the action is already finished, no further feedback is expected.

Keep in mind that the provided download links for the artifacts are generated dynamically by the update server. Host, port and path are not guaranteed to be similar to the provided examples below but will be defined at runtime.

### Method
GET

### Endpoint
/{tenant}/controller/v1/{controllerId}/installedBase/{actionId}

### Parameters
#### Path Parameters
- **tenant** (string) - Required - The tenant identifier.
- **controllerId** (string) - Required - The controller identifier.
- **actionId** (integer) - Required - The identifier of the action.

#### Query Parameters
- **actionHistory** (integer) - Optional - Defaults to 0. Specifies the amount of action history to retrieve.

### Response
#### Success Response (200)
- **DdiDeploymentBase** (object) - The response body includes the detailed operation for the already finished action in the same format as for the deploymentBase operation. In this case the (optional) query for the last 10 messages, previously provided by the device, are included.

#### Error Responses
- **400** - Bad Request - e.g. invalid parameters.
- **401** - Unauthorized - The request requires user authentication.
- **403** - Forbidden - Insufficient permissions or data volume restriction applies.
- **404** - Not Found - Target or Module not found.
- **405** - Method Not Allowed - The http request method is not allowed on the resource.
- **406** - Not Acceptable - In case accept header is specified and not application/json.
- **429** - Too Many Requests - The server will refuse further attempts and the client has to wait another second.
```

--------------------------------

### Return Installed Distribution Set of a Specific Target

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt.html

Handles the GET request of retrieving the installed distribution set of an specific target. Required Permission: READ_TARGET.

```APIDOC
## GET /rest/v1/targets/{targetId}/installedDistributionSet

### Description
Handles the GET request of retrieving the installed distribution set of an specific target. Required Permission: READ_TARGET.

### Method
GET

### Endpoint
/rest/v1/targets/{targetId}/installedDistributionSet

### Parameters
#### Path Parameters
- **targetId** (string) - Required - The ID of the target.

### Responses
#### Success Response (200)
- **Response Body**: Details of the installed distribution set for the target.

#### Error Responses
(Error responses are not explicitly detailed in the source for this operation, but standard HTTP error codes may apply.)
```

--------------------------------

### Run HawkBit DMF Server with DmfStart Class

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-dmf/hawkbit-dmf-server/README.md

Alternative method to run the HawkBit DMF Server using the DmfStart class.

```bash
run org.eclipse.hawkbit.app.dmf.DmfStart
```

--------------------------------

### Get Installed Data for a Target

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

Retrieves the installed data for a specific target identified by its ID. This endpoint is useful for understanding the software and configuration deployed on a target device.

```APIDOC
## GET /rest/v1/targets/{targetId}/installedDS

### Description
Retrieves the installed data for a specific target.

### Method
GET

### Endpoint
/rest/v1/targets/{targetId}/installedDS

### Parameters
#### Path Parameters
- **targetId** (string) - Required - The unique identifier of the target.

### Response
#### Success Response (200)
- **installedData** (object) - Description of the installed data (details not provided in source).

#### Response Example
{
  "example": "{\"installedData\": {}}"
}

### Error Handling
- **400**: Bad Request - e.g. invalid parameters
- **401**: The request requires user authentication.
- **403**: Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.
- **404**: Target not found.
- **405**: The http request method is not allowed on the resource.
- **406**: In case accept header is specified and not application/json.
- **429**: Too many requests. The server will refuse further attempts and the client has to wait another second.
```

--------------------------------

### GET /rest/v1/targets/{targetid}/installed

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docs/rest-api/mgmt.html

Retrieves information about installed software on a specific target.

```APIDOC
## GET /rest/v1/targets/{targetid}/installed

### Description
Retrieves information about installed software on a specific target.

### Method
GET

### Endpoint
/rest/v1/targets/{targetid}/installed

### Parameters
#### Path Parameters
- **targetid** (string) - Required - The ID of the target.
```

--------------------------------

### Example Rollout Response (200 OK)

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

This JSON object represents a successful response when retrieving Rollout details. It includes metadata, target information, and links to related actions.

```json
{
  "createdBy": "bumlux",
  "createdAt": 1682408568812,
  "lastModifiedBy": "bumlux",
  "lastModifiedAt": 1682408568812,
  "name": "exampleRollout",
  "description": "Rollout for all named targets",
  "targetFilterQuery": "id==targets-*",
  "distributionSetId": 6,
  "status": "creating",
  "totalTargets": 20,
  "totalTargetsPerStatus": {
    "running": 0,
    "notstarted": 20,
    "scheduled": 0,
    "cancelled": 0,
    "finished": 0,
    "error": 0
  },
  "totalGroups": 5,
  "startAt": 1682408570791,
  "forcetime": 1682408571791,
  "deleted": false,
  "type": "forced",
  "_links": {
    "start": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/start"
    },
    "pause": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/pause"
    },
    "resume": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/resume"
    },
    "triggerNextGroup": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/triggerNextGroup"
    },
    "approve": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/approve"
    },
    "deny": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/deny"
    },
    "groups": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/deploygroups?offset=0&limit=50"
    },
    "distributionset": {
      "href": "https://management-api.host.com/rest/v1/distributionsets/6",
      "name": "bd3a71cb-6c8f-445c-adbb-e221414dcd96:1.0"
    },
    "self": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6"
    }
  },
  "id": 6
}
```

--------------------------------

### Device Provisioning Workflow Diagram

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docs/device-provisioning.md

Visualizes the step-by-step process for provisioning and registering devices using the Management API and DDI API. It covers phases from initial device creation to attribute updates.

```mermaid
%%{init: {'theme':'base', 'themeVariables': {
      'primaryColor':'#027ABE',
      'primaryTextColor':'#FFF',
      'primaryBorderColor':'#015585',
      'lineColor':'#43464A',
      'secondaryColor':'#9ABFDB',
      'tertiaryColor':'#027ABE',
      'noteBkgColor':'#F0EEEA',
      'noteTextColor':'#43464A',
      'noteBorderColor':'#015585',
      'actorBorder':'#015585',
      'actorBkg':'#027ABE',
      'actorTextColor':'#FFF',
      'actorLineColor':'#43464A',
      'signalColor':'#43464A',
      'signalTextColor':'#43464A',
      'labelBoxBkgColor':'#9ABFDB',
      'labelBoxBorderColor':'#015585',
      'labelTextColor':'#015585',
      'loopTextColor':'#43464A',
      'activationBorderColor':'#015585',
      'activationBkgColor':'#F0EEEA',
      'sequenceNumberColor':'#FFF'
    }}}%%

sequenceDiagram
    participant Admin as Admin/Backend System
    participant MgmtAPI as Management API<br/>(REST)
    participant Server as hawkBit Server
    participant DDIAPI as DDI API<br/>(REST)
    participant Device as Device

    Note over Admin,Device: Phase 1: Provisioning (Before Device Deployment)

    Admin->>MgmtAPI: POST /rest/v1/targets
    Note right of Admin: Create device with:<br/>- controllerId<br/>- name, description<br/>- securityToken (optional)<br/>- requestAttributes
    activate MgmtAPI
    MgmtAPI->>Server: Create Target Entity
    activate Server
    Server->>Server: Generate securityToken<br/>(if not provided)
    Server->>Server: Set updateStatus:
"registered"
    Server-->>MgmtAPI: 201 Created
    deactivate Server
    MgmtAPI-->>Admin: Target created with<br/>securityToken
    deactivate MgmtAPI

    Note over Admin,Device: Phase 2: Device Registration (First Connection)

    Device->>DDIAPI: GET /{tenant}/controller/v1/{controllerId}
    Note right of DDIAPI: Authorization:<br/>TargetToken {securityToken}
    activate DDIAPI
    DDIAPI->>Server: Authenticate & Retrieve Target
    activate Server
    Server->>Server: Validate securityToken<br/>Update lastControllerRequestAt
    Server-->>DDIAPI: Target Configuration
    deactivate Server
    DDIAPI-->>Device: 200 OK<br/>Polling interval + links
    deactivate DDIAPI
    Note left of Device: config.polling.sleep<br/>_links.configData

    Note over Admin,Device: Phase 3: Add Device Attributes (Optional)

    Device->>DDIAPI: PUT /{tenant}/controller/v1/{controllerId}/configData
    Note right of DDIAPI: Send attributes:<br/>- hwRevision<br/>- VIN<br/>- OS version
mode: "merge"
    activate DDIAPI
    DDIAPI->>Server: Update Target Attributes
    activate Server
    Server->>Server: Merge/Replace/Remove<br/>attributes
    Server-->>DDIAPI: 200 OK
    deactivate Server
    DDIAPI-->>Device: Configuration updated
    deactivate DDIAPI
```

--------------------------------

### Get Installed Targets for Distribution Set

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

Retrieves a list of targets that have a specific distribution set installed. This endpoint is useful for identifying which devices or systems have a particular distribution set deployed.

```APIDOC
## GET /rest/v1/distributionsets/{distributionSetId}/installedTargets

### Description
Handles the GET request for retrieving installed targets of a single distribution set. Required permissions: READ_REPOSITORY and READ_TARGET.

### Method
GET

### Endpoint
/rest/v1/distributionsets/{distributionSetId}/installedTargets

### Parameters
#### Path Parameters
- **distributionSetId** (integer) - Required - The ID of the distribution set.

#### Query Parameters
- **offset** (string) - Optional - The paging offset (default is 0).

### Response
#### Success Response (200)
- **InstalledTargetList** - A list of installed targets.

#### Response Example
{
  "example": "{\"total\": 15, \"data\": [{\"id\": \"target1\", \"name\": \"Device Alpha\"}, {\"id\": \"target2\", \"name\": \"Device Beta\"}]}"
}
```

--------------------------------

### Example Rollout Response (200 OK)

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

This JSON object represents a successful response when retrieving rollout details. It includes metadata, target information, status, and links to related actions and resources.

```json
{
  "createdBy": "bumlux",
  "createdAt": 1682408568812,
  "lastModifiedBy": "bumlux",
  "lastModifiedAt": 1682408568812,
  "name": "exampleRollout",
  "description": "Rollout for all named targets",
  "targetFilterQuery": "id==targets-*",
  "distributionSetId": 6,
  "status": "creating",
  "totalTargets": 20,
  "totalTargetsPerStatus": {
    "running": 0,
    "notstarted": 20,
    "scheduled": 0,
    "cancelled": 0,
    "finished": 0,
    "error": 0
  },
  "totalGroups": 5,
  "startAt": 1682408570791,
  "forcetime": 1682408571791,
  "deleted": false,
  "type": "forced",
  "_links": {
    "start": {
      "href": "[https://management-api.host.com/rest/v1/rollouts/6/start](https://management-api.host.com/rest/v1/rollouts/6/start)"
    },
    "pause": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/pause"
    },
    "resume": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/resume"
    },
    "triggerNextGroup": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/triggerNextGroup"
    },
    "approve": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/approve"
    },
    "deny": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/deny"
    },
    "groups": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6/deploygroups?offset=0&limit=50"
    },
    "distributionset": {
      "href": "https://management-api.host.com/rest/v1/distributionsets/6",
      "name": "bd3a71cb-6c8f-445c-adbb-e221414dcd96:1.0"
    },
    "self": {
      "href": "https://management-api.host.com/rest/v1/rollouts/6"
    }
  },
  "id": 6
}
```

--------------------------------

### Build hawkbit-ddi-resource

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-ddi/hawkbit-ddi-resource/README.md

Navigate to the hawkbit-ddi-resource directory and execute the Maven clean install command to build the module.

```bash
$ cd hawkbit/hawkbit-ddi-resource
$ mvn clean install
```

--------------------------------

### Get Previously Installed Action

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/ddi.html

Retrieves information about a previously installed action, including details of the finished deployment and optionally the last 10 messages from the device. Useful for re-installation or auditing.

```APIDOC
## GET /controller/v1/{tenant}/{controllerId}/installedBase/{actionId}

### Description
Retrieves information about a previously installed action. Can be used to re-retrieve artifacts of the already finished action, for example in case a re-installation is necessary. The response will be of the same format as the deploymentBase operation, providing the previous action that has been finished successfully. As the action is already finished, no further feedback is expected.

### Method
GET

### Endpoint
/controller/v1/{tenant}/{controllerId}/installedBase/{actionId}

#### Path Parameters
- **tenant** (string) - Required - The tenant identifier.
- **controllerId** (string) - Required - The ID of the controller.
- **actionId** (integer <int64>) - Required - The ID of the action.

#### Query Parameters
- **actionHistory** (integer <int32>) - Optional - Default: 0. Specifies the number of historical messages to retrieve.

### Responses
#### Success Response (200)
The response body includes the detailed operation for the already finished action in the same format as for the deploymentBase operation. In this case the (optional) query for the last 10 messages, previously provided by the device, are included.

#### Error Responses
- **400** Bad Request - e.g. invalid parameters
- **401** Unauthorized - The request requires user authentication.
- **403** Forbidden - Insufficient permissions or data volume restriction applies.
- **405** Method Not Allowed - The http request method is not allowed on the resource.
- **406** Not Acceptable - In case accept header is specified and not application/json.
- **429** Too Many Requests - The server will refuse further attempts and the client has to wait another second.
```

--------------------------------

### Get Target Metadata Response Sample

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt.html

Example of a successful response when retrieving target metadata.

```json
{ 
  "key": "someKnownKey", 
  "value": "someKnownKeyValue" 
}
```

--------------------------------

### Response Sample for Batch Update

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

Example response after a successful batch update of tenant configuration. It typically returns an array of configuration objects, each with its value, global status, and links.

```json
[
  {
    "value": "",
    "global": true,
    "_links": {
      "self": {
        "href": "https://management-api.host.com/rest/v1/system/configs/authentication.gatewaytoken.key"
      }
    }
  }
]
```

--------------------------------

### Get Target Type Response Sample

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/rest-api/mgmt/index.html

Example of a successful JSON response when retrieving a target type by its ID.

```json
{
  "createdBy": "bumlux",
  "createdAt": 1682408564546,
  "lastModifiedBy": "bumlux",
  "lastModifiedAt": 1682408564546,
  "name": "TargetType",
  "description": "TargetType description",
  "colour": "#000000",
  "_links": {
    "self": {
      "href": "https://management-api.host.com/rest/v1/targettypes/8"
    },
    "compatibledistributionsettypes": {
      "href": "https://management-api.host.com/rest/v1/targettypes/8/compatibledistributionsettypes"
    }
  },
  "id": 8
}
```

--------------------------------

### Example MULTI_ACTION Payload

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docs/device-management-federation-api.md

An example of a MULTI_ACTION message payload demonstrating how to specify two distinct actions: DOWNLOAD_AND_INSTALL with a weight of 600 and DOWNLOAD with a weight of 500. This illustrates the structure for multiple prioritized operations.

```json
[{
"topic": "DOWNLOAD_AND_INSTALL",
"weight": 600,
"action": {
  "actionId":137,
  "targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY",
  "softwareModules":[
      {
      "moduleId":7,
      "moduleType":"firmware",
      "moduleVersion":"7.7.7",
      "artifacts":[
          {
          "filename":"artifact.zip",
          "urls":{
              "HTTP":"http://download-from-url.com",
              "HTTPS":"https://download-from-url.com"
              },
          "hashes":{
              "md5":"md5hash",
              "sha1":"sha1hash"
              },
          "size":512
          }],
      "metadata":[
          {
              "key":"installationType",
              "value":"5784K#"
          }
      ]
      }
  ]
}
},
{
"topic": "DOWNLOAD",
"weight": 500,
"action": {
  "actionId":138,
  "targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY",
  "softwareModules":[
      {
      "moduleId":4,
      "moduleType":"firmware",
      "moduleVersion":"7.7.9",
      "artifacts":[
          {
          "filename":"artifact.zip",
          "urls":{
              "HTTP":"http://download-from-url.com",
              "HTTPS":"https://download-from-url.com"
              },
          "hashes":{
              "md5":"md5hash",
              "sha1":"sha1hash"
              },
          "size":512
          }],
      "metadata":[
          {
              "key":"installationType",
              "value":"5784K#"
          }
      ]
      }
  ]
}
}]
```

--------------------------------

### Initial Deployment Configuration (DDI)

Source: https://github.com/eclipse-hawkbit/hawkbit/wiki/Separation-of-Download-and-Install

Defines the initial state of a deployment action, specifying separate download and update behaviors.

```json
{
  "deployment" : {
    "download" : "forced",
    "update" : "skip",

```

--------------------------------

### Start hawkBit Update Server (Monolith) as a Single Docker Container

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docker/README.md

This command starts the hawkBit Update Server in monolith mode as a single Docker container. It maps port 8080 from the container to the host. Assumes Docker is installed.

```bash
$ docker run -d -p 8080:8080 hawkbit/hawkbit-update-server:latest
```

--------------------------------

### DOWNLOAD_AND_INSTALL or DOWNLOAD Message

Source: https://github.com/eclipse-hawkbit/hawkbit/blob/master/docs/device-management-federation-api.md

This section describes the message structure for initiating a download or an update on a registered device. The topic can be either DOWNLOAD_AND_INSTALL or DOWNLOAD, depending on whether a maintenance window is active.

```APIDOC
## DOWNLOAD_AND_INSTALL or DOWNLOAD

### Description
Message sent by hawkBit to initialize an update or download task. Note: in case of a maintenance window configured but not yet active the message will have the topic _DOWNLOAD_ instead of _DOWNLOAD_AND_INSTALL_.

### Headers

| Header  | Description                                    | Type                                              | Mandatory |
|---------|------------------------------------------------|---------------------------------------------------|-----------|
| type    | Type of the message                            | Fixed string "EVENT"                              | true      |
| thingId | The ID of the registered provisioning target   | String                                            | true      |
| topic   | Topic name identifying the event               | Fixed string "DOWNLOAD_AND_INSTALL" or "DOWNLOAD" | true      |
| tenant  | The tenant this provisioning target belongs to | String                                            | false     |

### Message Properties

| Message Properties | Description                     | Type   | Mandatory |
|--------------------|---------------------------------|--------|-----------|
| content_type       | The content type of the payload | String | true      |

### Payload Template
```json
{
"actionId": long,
"targetSecurityToken": "String",
"softwareModules":[
    {
    "moduleId": long,
    "moduleType":"String",
    "moduleVersion":"String",
    "artifacts":[
        {
        "filename":"String",
        "urls":{
            "HTTP":"String",
            "HTTPS":"String"
            },
        "hashes":{
            "md5":"String",
            "sha1":"String"
            },
        "size":long
        }],
    "metadata":[
        {
            "key":"String",
            "value":"String"
        }
    ]
    }]
}
```

### Example

**Header:**
```
type=EVENT
tenant=default
thingId=abc
topic=DOWNLOAD_AND_INSTALL
```

**MessageProperties:**
```
content_type=application/json
```

**Payload:**
```json
{
"actionId":137,
"targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY",
"softwareModules":[
    {
    "moduleId":7,
    "moduleType":"firmware",
    "moduleVersion":"7.7.7",
    "artifacts":[
        {
        "filename":"artifact.zip",
        "urls":{
            "HTTP":"http://download-from-url.com",
            "HTTPS":"https://download-from-url.com"
            },
        "hashes":{
            "md5":"md5hash",
            "sha1":"sha1hash"
            },
        "size":512
        }],
    "metadata":[
        {
            "key":"installationType",
            "value":"5784K#"
        }
    ]
    }]
}
```
```