openapi: 3.0.1
info:
  contact:
    email: support@mender.io
    name: support@mender.io
    url: https://hosted.mender.io
  description: |
    Combined API specification for the features of the different Mender backend services, suitable for code generation applications
  title: Mender API
  version: '1'
servers:
  - url: https://hosted.mender.io
tags:
  - name: Mender_API_Mender API
    x-displayName: Mender API
  - name: Audit_Logs_Internal API
    x-displayName: Internal API
  - name: Audit_Logs_Auditlogs Internal
    x-displayName: Auditlogs Internal
  - name: Audit_Logs_Management API
    x-displayName: Management API
  - name: Audit_Logs_Auditlogs Management
    x-displayName: Auditlogs Management
  - name: Deployments_Device API
    x-displayName: Device API
  - name: Deployments_v2_Device API
    x-displayName: Device API
  - name: Deployments_Internal_API_Internal API
    x-displayName: Internal API
  - name: Deployments_Management API
    x-displayName: Management API
  - name: Deployments_v2_Management API
    x-displayName: Management API
  - name: Device_Authentication_Device API
    x-displayName: Device API
  - name: Device_Authentication_Internal API
    x-displayName: Internal API
  - name: Device_Authentication_Management API
    x-displayName: Management API
  - name: Device_configure_Device API
    x-displayName: Device API
  - name: Device_configure_Internal API
    x-displayName: Internal API
  - name: Device_configure_Management API
    x-displayName: Management API
  - name: Device_connect_Device API
    x-displayName: Device API
  - name: Device_connect_Internal API
    x-displayName: Internal API
  - name: Device_connect_Management API
    x-displayName: Management API
  - name: Device_monitor_Devices API
    x-displayName: Devices API
  - name: Device_monitor_Internal API
    x-displayName: Internal API
  - name: Device_monitor_Management API
    x-displayName: Management API
  - name: Device_inventory_Device API
    x-displayName: Device API
  - name: Device_inventory_Internal API
    x-displayName: Internal API
  - name: Device_inventory_filters_and_search_Internal API
    x-displayName: Internal API
  - name: Device_inventory_Management API
    x-displayName: Management API
  - name: Device_inventory_filters_and_search_Management API
    x-displayName: Management API
  - name: IoT_Manager_Internal API
    x-displayName: Internal API
  - name: IoT_Manager_Management API
    x-displayName: Management API
  - name: Tenants_APIs_Internal API
    x-displayName: Internal API
  - name: Tenants_APIs_Tenantadm Internal
    x-displayName: Tenantadm Internal
  - name: Tenants_APIs_Management API
    x-displayName: Management API
  - name: Tenants_APIs_Tenantadm Management
    x-displayName: Tenantadm Management
  - name: Tenants_APIs_v2_Management API
    x-displayName: Management API
  - name: Tenants_APIs_v2_Tenantadm Management v2
    x-displayName: Tenantadm Management v2
  - name: User_administration_and_authentication_Internal API
    x-displayName: Internal API
  - name: User_Administration_Management API
    x-displayName: Management API
  - name: User_Administration_v2_Management API
    x-displayName: Management API
  - name: Workflows_other
    x-displayName: other
paths:
  /api/internal/v1/auditlogs/alive:
    get:
      tags:
        - Audit_Logs_Auditlogs Internal
      summary: Get liveliness status of service
      operationId: Ping
      responses:
        '204':
          description: Successful response.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/auditlogs/health:
    get:
      tags:
        - Audit_Logs_Auditlogs Internal
      summary: Get status of service
      operationId: Auditlogs Internal Check Health
      responses:
        '204':
          description: Successful response.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/internal/v1/auditlogs/tenants/{tenant_id}:
    delete:
      tags:
        - Audit_Logs_Auditlogs Internal
      summary: Delete all the logs for given tenant.
      operationId: Delete Audit Logs
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: All the tenant logs have been successfully deleted.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/auditlogs/tenants/{tenant_id}/logs:
    get:
      tags:
        - Audit_Logs_Auditlogs Internal
      summary: Returns a list of audit log objects.
      operationId: Get Audit Logs (internal)
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: Starting page.
          schema:
            type: number
            format: integer
            default: 1
        - name: per_page
          in: query
          description: Number of results per page.
          schema:
            type: number
            format: integer
            default: 10
        - name: created_before
          in: query
          description: List only log entries created before and equal to Unix timestamp (UTC)
          schema:
            type: number
            format: integer
        - name: created_after
          in: query
          description: List only log entries created after and equal to Unix timestamp (UTC)
          schema:
            type: number
            format: integer
        - name: actor_id
          in: query
          description: If present, limits the results only to logs where actor has given id.
          schema:
            type: string
        - name: actor_type
          in: query
          description: If present, limits the results only to logs where actor is of a given type.
          schema:
            type: string
            enum:
              - user
              - device
        - name: actor_email
          in: query
          description: If present, limits the results only to logs where actors has given email address.
          schema:
            type: string
        - name: object_id
          in: query
          description: If present, limits the results only to logs where object has given id.
          schema:
            type: string
        - name: object_type
          in: query
          description: If present, limits the results only to logs where object is of a given type.
          schema:
            type: string
            enum:
              - user
              - deployment
              - artifact
              - device
        - name: object_deployment_name
          in: query
          description: If present, limits the results only to logs where object is a deployment with a given name.
          schema:
            type: string
        - name: sort
          in: query
          description: |
            Supports sorting the log list by creation date.
            By default logs are sorted by creation date in descending order (newest first).
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of devices matched query.
              schema:
                type: string
            Link:
              description: |
                Standard header used for page navigation, page relations: 'first', 'next' and 'prev'.
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfLogs
                type: array
                description: A list of audit logs is returned.
                items:
                  $ref: '#/components/schemas/AuditLog'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - Audit_Logs_Auditlogs Internal
      summary: Log event.
      operationId: Save Audit Log
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditLog'
        required: true
      responses:
        '201':
          description: Event has been successfully logged.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/auditlogs/logs:
    get:
      tags:
        - Audit_Logs_Auditlogs Management
      summary: Returns a paged list of audit log objects.
      operationId: Get Audit Logs
      parameters:
        - name: page
          in: query
          description: Starting page.
          schema:
            type: number
            format: integer
            default: 1
        - name: per_page
          in: query
          description: Number of results per page.
          schema:
            type: number
            format: integer
            default: 10
        - name: created_before
          in: query
          description: List only log entries created before and equal to Unix timestamp (UTC)
          schema:
            type: number
            format: integer
        - name: created_after
          in: query
          description: List only log entries created after and equal to Unix timestamp (UTC)
          schema:
            type: number
            format: integer
        - name: actor_id
          in: query
          description: If present, limits the results only to logs where the actor has a given id.
          schema:
            type: string
        - name: actor_type
          in: query
          description: If present, limits the results only to logs where the actor is of a given type.
          schema:
            type: string
            enum:
              - user
              - device
        - name: actor_email
          in: query
          description: If present, limits the results only to logs where the actor has a given email address.
          schema:
            type: string
        - name: object_id
          in: query
          description: If present, limits the results only to logs where the object has a given id.
          schema:
            type: string
        - name: object_type
          in: query
          description: If present, limits the results only to logs where the object is of a given type.
          schema:
            type: string
            enum:
              - tenant
              - user
              - deployment
              - artifact
              - device
        - name: object_deployment_name
          in: query
          description: If present, limits the results only to logs where the object is a deployment and has a given name.
          schema:
            type: string
        - name: sort
          in: query
          description: |
            Supports sorting the log list by creation date.
            By default logs are sorted by creation date in descending order (newest first).
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of devices matched query.
              schema:
                type: string
            Link:
              description: |
                Standard header used for page navigation, page relations: 'first', 'next' and 'prev'.
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfLogs
                type: array
                description: A list of audit logs is returned.
                items:
                  $ref: '#/components/schemas/AuditLog'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          description: |
            The user has sent too many requests in a given amount of time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v1/auditlogs/logs/export:
    get:
      tags:
        - Audit_Logs_Auditlogs Management
      summary: Returns a paged list of audit log objects in text/csv format.
      operationId: Export Audit Logs
      parameters:
        - name: limit
          in: query
          description: Limit number of logs returned
          schema:
            type: number
            format: integer
        - name: created_before
          in: query
          description: List only log entries created before and equal to Unix timestamp (UTC)
          schema:
            type: number
            format: integer
        - name: created_after
          in: query
          description: List only log entries created after and equal to Unix timestamp (UTC)
          schema:
            type: number
            format: integer
        - name: actor_id
          in: query
          description: If present, limits the results only to logs where the actor has a given id.
          schema:
            type: string
        - name: actor_type
          in: query
          description: If present, limits the results only to logs where the actor is of a given type.
          schema:
            type: string
            enum:
              - user
              - device
        - name: actor_email
          in: query
          description: If present, limits the results only to logs where the actors has a given email address.
          schema:
            type: string
        - name: object_id
          in: query
          description: If present, limits the results only to logs where the object has a given id.
          schema:
            type: string
        - name: object_type
          in: query
          description: If present, limits the results only to logs where the object is of a given type.
          schema:
            type: string
            enum:
              - user
              - deployment
              - artifact
              - device
        - name: object_deployment_name
          in: query
          description: If present, limits the results only to logs where the object is a deployment and has a given name.
          schema:
            type: string
        - name: sort
          in: query
          description: |
            Supports sorting the log list by creation date.
            By default logs are sorted by creation date in descending order (newest first).
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: format_separator
          in: query
          description: |
            Format string used to separate nested fields in the exported csv header
          schema:
            type: string
            default: .
        - name: ignore
          in: query
          description: |
            Header fields to ignore in the exported document (e.g. ignore=actor.id)
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful response.

            Document follows in response body (chunked encoding).
          content:
            text/csv:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          description: |
            The user has sent too many requests in a given amount of time.
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/devices/v1/deployments/artifacts:
    get:
      description: |
        Returns a collection of up to 100 artifacts matching the provided release name and device type.
      operationId: Device List Artifacts
      parameters:
        - description: name of the release
          in: query
          name: release_name
          required: true
          schema:
            type: string
        - description: Device type of device
          in: query
          name: device_type
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                  name: Application 1.0.0
                  description: Johns Monday test build
                  device_types_compatible:
                    - Beagle Bone
                  info:
                    format: mender
                    version: 3
                  updates:
                    - type_info:
                        type: rootfs-image
                      files:
                        - name: rootfs-image-1
                          checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                          size: 123
                          date: 2016-03-11T13:03:17.063+0000
                      meta_data: []
                  artifact_provides:
                    artifact_name: test
                    rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                    rootfs-image.version: test
                  artifact_depends:
                    device_type:
                      - test
                  clears_artifact_provides:
                    - rootfs-image.*
                  size: 36891648
                  modified: '2016-03-11T13:03:17.063493443Z'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Artifact'
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
      summary: List artifacts filtering by release name and device type
      tags:
        - Deployments_Device API
  /api/devices/v1/deployments/artifacts/{id}:
    get:
      description: |
        Returns the details of a selected artifact.
      operationId: Device Show Artifact
      parameters:
        - description: Artifact identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                name: Application 1.0.0
                description: Johns Monday test build
                device_types_compatible:
                  - Beagle Bone
                info:
                  format: mender
                  version: 3
                updates:
                  - type_info:
                      type: rootfs-image
                    files:
                      - name: rootfs-image-1
                        checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                        size: 123
                        date: 2016-03-11T13:03:17.063+0000
                    meta_data: []
                artifact_provides:
                  artifact_name: test
                  rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                  rootfs-image.version: test
                artifact_depends:
                  device_type:
                    - test
                clears_artifact_provides:
                  - rootfs-image.*
                size: 36891648
                modified: '2016-03-11T13:03:17.063493443Z'
              schema:
                $ref: '#/components/schemas/Artifact'
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
      summary: Get the details of a selected artifact
      tags:
        - Deployments_Device API
  /api/devices/v1/deployments/artifacts/{id}/download:
    get:
      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.
      operationId: Devices Download Artifact
      parameters:
        - description: Artifact identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactLink'
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
      summary: Get the download link of a selected artifact
      tags:
        - Deployments_Device API
  /api/devices/v1/deployments/device/deployments/next:
    get:
      description: |
        On success, either an empty response or a DeploymentInstructions object
        is returned depending on whether there are any pending updates.
      operationId: Device Check Update
      parameters:
        - description: currently installed artifact
          in: query
          name: artifact_name
          required: true
          schema:
            type: string
        - description: Device type of device
          in: query
          name: device_type
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                id: w81s4fae-7dec-11d0-a765-00a0c91e6bf6
                artifact:
                  artifact_name: my-app-0.1
                  source:
                    uri: https://aws.myupdatebucket.com/image123
                    expire: '2016-03-11T13:03:17.063493443Z'
                  device_types_compatible:
                    - rspi
                    - rspi2
                    - rspi0
              schema:
                $ref: '#/components/schemas/DeploymentInstructions'
          description: Successful response.
        '204':
          content: {}
          description: No updates for device.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
      summary: Get next update
      tags:
        - Deployments_Device API
    post:
      description: |
        Returns the next update to be installed on the device.
        Next update will be chosen based on parameters provided in the request
        body. Request body should contain artifact_provides object.
      operationId: Check Update Depends
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckUpdateDependsRequest'
        description: |
          Key-value map of strings which describes the artifact(s) installed on the device and the
          device itself. It is used to determine the next deployment. The keys device_type and
          artifact_name are mandatory, additional free-form key-value pairs can be specified.
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                id: w81s4fae-7dec-11d0-a765-00a0c91e6bf6
                artifact:
                  artifact_name: my-app-0.1
                  source:
                    uri: https://aws.my.update.bucket.com/image_123
                    expire: '2016-03-11T13:03:17.063493443Z'
                  device_types_compatible:
                    - rspi
                    - rspi2
                    - rspi0
              schema:
                $ref: '#/components/schemas/DeploymentInstructions'
          description: Successful response.
        '204':
          content: {}
          description: No updates for device.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
      summary: Get a next update satisfying dependencies
      tags:
        - Deployments_Device API
  /api/devices/v1/deployments/device/deployments/{id}/status:
    put:
      description: |
        Updates the status of a deployment on a particular device. Final status
        of the deployment is required to be set to indicate the success or failure
        of the installation process. The status can not be changed when deployment
        status is set to aborted. Reporting of intermediate steps such as
        installing, downloading, rebooting is optional.
      operationId: Update Deployment Status
      parameters:
        - description: Deployment identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentStatus'
        description: Deployment status.
        required: true
      responses:
        '204':
          content: {}
          description: Status updated successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          content: {}
          description: Status already set to aborted.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
      summary: Update the device deployment status
      tags:
        - Deployments_Device API
  /api/devices/v1/deployments/device/deployments/{id}/log:
    put:
      description: |
        Set the log of a selected deployment. Messages are split by line in the payload.
      operationId: Report Deployment Log
      parameters:
        - description: Deployment identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentLog'
        description: Deployment log
        required: true
      responses:
        '204':
          content: {}
          description: The deployment log uploaded successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
      summary: Upload the device deployment log
      tags:
        - Deployments_Device API
  /api/devices/v1/deployments/download/configuration/{deployment_id}/{device_type}/{device_id}:
    get:
      operationId: Fetch Configuration
      parameters:
        - description: Deployment UUID
          in: path
          name: deployment_id
          required: true
          schema:
            type: string
        - description: Device type of the calling device
          in: path
          name: device_type
          required: true
          schema:
            type: string
        - description: Device UUID
          in: path
          name: device_id
          required: true
          schema:
            type: string
        - description: Time of link expire
          in: query
          name: x-men-expire
          required: true
          schema:
            format: date-time
            type: string
        - description: Signature of the URL link
          in: query
          name: x-men-signature
          required: true
          schema:
            type: string
        - description: Device tenant ID
          in: query
          name: tenant_id
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Artifact file
                format: binary
                type: string
          description: Successful response
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          content: {}
          description: The download link has expired or the signature is invalid.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security: []
      summary: |
        Internally generated download link for deploying device configurations.
        All parameters are generated internally when fetching a configuration deployment.
      tags:
        - Deployments_Device API
  /api/devices/v2/deployments/device/deployments/next:
    post:
      description: |
        Returns the next update to be installed on the device.
        Next update will be chosen based on parameters provided in the request
        body.
      operationId: Check Update
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckUpdateRequest'
        description: |
          Request which describes the artifact(s) installed on the devices and the suppported features. The device_provides attribute contains a key-value map of strings which describes the artifact(s) installed on the device and the device itself. It is used to determine the next deployment. The keys device_type and artifact_name are mandatory, additional free-form key-value pairs can be specified.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentInstructionsV2'
          description: Successful response.
        '204':
          content: {}
          description: No updates for device.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
      summary: Get a next update satisfying dependencies
      tags:
        - Deployments_v2_Device API
  /api/devices/v2/deployments/device/deployments/{id}/update_control_map:
    get:
      description: |
        Returns the update control map assigned to given, active deployment.
      operationId: Get Update Control Map
      parameters:
        - description: Deployment identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateControlMap'
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: |
            Device deployment with given ID does not exist
            or has been finished.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
      summary: Get the update control map object
      tags:
        - Deployments_v2_Device API
  /api/internal/v1/deployments/health:
    get:
      operationId: Deployments Internal Check Health
      responses:
        '204':
          content: {}
          description: |
            Service is healthy and all dependencies are up and running.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          content:
            application/json:
              example:
                error: 'error reaching MongoDB: context deadline exceeded'
                request_id: ffd712be-d697-4cb7-814b-88ff1e2eb5f6
              schema:
                $ref: '#/components/schemas/Error'
          description: |
            Service unhealthy / not ready to accept traffic. At least one dependency is not running.
      summary: Check the health of the service
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/alive:
    get:
      operationId: Deployments Internal Check Liveliness
      responses:
        '204':
          content: {}
          description: Service is up and running.
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: |
        Trivial endpoint that unconditionally returns an empty 204 response whenever the API handler is running correctly.
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/config/binary_delta:
    get:
      description: |
        Returns an array of objects containing the tenant ID and a boolean flag which represents whether the binary delta generation is enabled or not for the given tenant.
      operationId: Get Binary Delta Configurations
      responses:
        '200':
          content:
            application/json:
              example:
                - tenant_id: 58be8208dd77460001fe0d78
                  enabled: true
                - tenant_id: 58be8208dd77460001fe0d79
                  enabled: false
              schema:
                items:
                  $ref: '#/components/schemas/Get_Binary_Delta_Configurations_200_response_inner'
                type: array
          description: Successful response with binary delta configurations.
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Retrieve binary delta generation configurations for all tenants
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{id}/storage/settings:
    get:
      description: |
        Returns an object with per tenant storage layer specific settings.
      operationId: Get Storage Settings
      parameters:
        - description: Tenant ID
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageSettings'
          description: Successful response with all available settings.
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get storage setting for a given tenant
      tags:
        - Deployments_Internal_API_Internal API
    put:
      description: Set the storage layer settings for a given tenant.
      operationId: Set Storage Settings
      parameters:
        - description: Tenant ID
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorageSettings'
        description: |-
          Settings to set.
          If set to null or an empty object, the tenant will use the default settings.
        required: false
      responses:
        '204':
          content: {}
          description: Settings updated.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Set storage settings for a given tenant
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{id}/limits/{name}:
    parameters:
      - description: Tenant ID
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Name
        in: path
        name: name
        required: true
        schema:
          type: string
          enum:
            - storage
            - max_artifact_size_micro_device_tier
    get:
      description: |
        Get limit by name for a given tenant.
        If the limit value is -1 it means the limit is unlimited.
      operationId: Deployments Internal Get Tenant Limit
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantLimit'
          description: Successful response.
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get limit for the given tenant
      tags:
        - Deployments_Internal_API_Internal API
    put:
      description: |
        Set limit for given tenant.
        If the limit value is -1 it means the limit is unlimited.
      operationId: Set Tenant Limit
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantLimitValue'
        required: true
      responses:
        '204':
          content: {}
          description: Limit information updated.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Set limit for given tenant
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants:
    post:
      description: |
        Sets up all tenant-related infrastructure, e.g. a migrated tenant's database.
      operationId: Deployments Internal Create Tenant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantNew'
        description: New tenant descriptor.
        required: true
      responses:
        '201':
          content: {}
          description: Tenant was successfully provisioned.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Provision a new tenant
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{id}/deployments:
    get:
      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.
      operationId: Get Deployments
      parameters:
        - description: Tenant ID
          in: path
          name: id
          required: true
          schema:
            type: string
        - description: Deployment status filter.
          in: query
          name: status
          schema:
            enum:
              - inprogress
              - finished
              - pending
            type: string
        - description: Deployment name or description filter.
          in: query
          name: search
          schema:
            type: string
        - description: Results page number
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: List only deployments created before and equal to Unix timestamp (UTC)
          in: query
          name: created_before
          schema:
            type: integer
        - description: List only deployments created after and equal to Unix timestamp (UTC)
          in: query
          name: created_after
          schema:
            type: integer
        - description: |
            Supports sorting the deployments list by creation date.
          in: query
          name: sort
          schema:
            enum:
              - asc
              - desc
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                - created: '2016-02-11 13:03:17.063493+00:00'
                  status: finished
                  name: production
                  artifact_name: Application 0.0.1
                  id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
                  finished: '2016-03-11 13:03:17.063493+00:00'
                  device_count: 10
              schema:
                items:
                  $ref: '#/components/schemas/DeploymentV1Internal'
                type: array
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of deployments matching query.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/InvalidRequestError'
      summary: Get all deployments for specific tenant
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{tenant_id}/deployments/{id}/groups:
    get:
      description: |
        Returns the device groups of a particular deployment.
        Getting empty groups means the deployment are sent to all devices.
      operationId: Get Deployment Groups
      parameters:
        - description: Tenant ID
          in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - description: Deployment identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceGroups'
          description: Successful response.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the details of a selected deployment
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{id}:
    delete:
      description: |
        Deletes all the tenant data.
      operationId: Delete tenant
      parameters:
        - description: Tenant ID
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          content: {}
          description: Successful removal.
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Delete all the tenant data
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{tenant_id}/deployments/devices:
    get:
      description: |
        Return the Deployments history entries for the specified IDs
      operationId: List Device Deployments entries
      parameters:
        - description: Tenant ID
          in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - description: Deployment Device ID filter. Can be repeated to query a set of entries.
          explode: true
          in: query
          name: id
          schema:
            items:
              type: string
            type: array
          style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeviceDeployment'
                type: array
          description: OK
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Return the Deployments history entries for the specified IDs
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{tenant_id}/deployments/devices/{id}:
    delete:
      description: Set 'decommissioned' status to all pending device deployments for a given device
      operationId: Remove Device from Deployments
      parameters:
        - description: Tenant ID
          in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - description: System wide device identifier
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          content: {}
          description: Device was removed
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Remove device from all deployments
      tags:
        - Deployments_Internal_API_Internal API
    get:
      description: |
        Return the Deployments history for the specified Device, listing all its Deployments.
      operationId: Deployments Internal List Deployments for a Device
      parameters:
        - description: Tenant ID
          in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - description: System wide device identifier
          in: path
          name: id
          required: true
          schema:
            type: string
        - description: Filter deployments by status for the given device.
          in: query
          name: status
          schema:
            enum:
              - failure
              - aborted
              - pause_before_installing
              - pause_before_committing
              - pause_before_rebooting
              - downloading
              - installing
              - rebooting
              - pending
              - success
              - noartifact
              - artifact_too_big
              - already-installed
              - decommissioned
              - pause
              - active
              - finished
            type: string
        - description: Starting page.
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Maximum number of results per page.
          in: query
          name: per_page
          schema:
            default: 20
            maximum: 20
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeviceDeployment'
                type: array
          description: OK
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Return the Deployments history for a Device
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{id}/artifacts:
    post:
      description: |
        Upload mender artifact to a specific tenant. Multipart request with meta and artifact.
        Supports artifact [versions v1, v2, v3](https://docs.mender.io/overview/artifact#versions).
      operationId: Deployments Internal Upload artifact
      parameters:
        - description: Tenant ID, or "default" if running in non-multitenant setup
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Upload_artifact_request'
        required: true
      responses:
        '201':
          content: {}
          description: Artifact uploaded.
          headers:
            Location:
              description: URL of the newly uploaded artifact.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Upload mender artifact
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{tenant_id}/configuration/deployments/{deployment_id}/devices/{device_id}:
    post:
      description: |
        Deploy configuration to a specified device.
        The artifact will be auto-generated based on the configuration object
        provided with the deployment constructor.
      operationId: Deployments Internal Create Deployment
      parameters:
        - description: Tenant identifier.
          in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - description: Device identifier.
          in: path
          name: device_id
          required: true
          schema:
            type: string
        - description: Deployment identifier.
          in: path
          name: deployment_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigurationDeploymentRequest'
        description: New deployment that needs to be created.
        required: true
      responses:
        '201':
          content: {}
          description: New configuration deployment created.
          headers:
            Location:
              description: URL of the newly created deployment.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Create a configuration deployment
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{tenant_id}/config:
    get:
      operationId: Get Tenant Configuration
      parameters:
        - description: Tenant identifier.
          in: path
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationTenant'
          description: Successful response.
          headers:
            ETag:
              description: |
                Contains the configuration object's current ETag.
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get Tenant specific configuration
      tags:
        - Deployments_Internal_API_Internal API
    put:
      operationId: Update Tenant Configuration
      parameters:
        - description: Tenant identifier.
          in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - description: Contains the config' current ETag, and performs the update only if it matches the one stored in the database.
          in: header
          name: If-Match
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigurationTenant'
        description: Configuration update.
        required: true
      responses:
        '204':
          content: {}
          description: Configuration updated.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '412':
          content: {}
          description: Document with a matching ETag does not exist.
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Set tenant configuration
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{tenant_id}/delta/{job_id}/status:
    put:
      description: |
        Generate delta worker uses this endpoint to report back generate delta job status.
      operationId: Update Delta Job Status
      parameters:
        - description: Tenant identifier.
          in: path
          name: tenant_id
          required: true
          schema:
            type: string
        - description: Job identifier.
          in: path
          name: job_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateDeltaJobStatus'
        description: New job status.
        required: true
      responses:
        '204':
          content: {}
          description: Status updated sucessfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update status of generate delta job
      tags:
        - Deployments_Internal_API_Internal API
  /api/internal/v1/deployments/tenants/{tenant_id}/devices/deployments/last:
    post:
      description: |
        Return the status of the last unsucessful device deployment.
      operationId: Get last device deployment status
      parameters:
        - description: Tenant identifier.
          in: path
          name: tenant_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LastDeviceDeploymentReq'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastDeviceDeploymentsStatuses'
          description: List of device deployment statuses returned.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get status of the last device devployment
      tags:
        - Deployments_Internal_API_Internal API
  /api/management/v1/deployments/deployments:
    get:
      deprecated: true
      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.

        DEPRECATED: _since Mon Oct 21 2024_ we deprecated the endpoint due to an issue with the "search" query
          behavior. Please use the v2 /deployments/deployments endpoint instead.
          In the new endpoint, we replaced search parameter with the "id" and "name" parameters.
      operationId: Deployments V1 List Deployments
      parameters:
        - description: Deployment status filter.
          in: query
          name: status
          schema:
            enum:
              - inprogress
              - finished
              - pending
              - scheduled
            type: string
        - description: |
            Deployment type filter.
          in: query
          name: type
          schema:
            enum:
              - software
              - configuration
            type: string
        - description: Deployment name or description filter.
          in: query
          name: search
          schema:
            type: string
        - description: Results page number
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Maximum number of results per page.
          in: query
          name: per_page
          schema:
            default: 20
            maximum: 500
            type: integer
        - description: List only deployments created before and equal to Unix timestamp (UTC)
          in: query
          name: created_before
          schema:
            type: integer
        - description: List only deployments created after and equal to Unix timestamp (UTC)
          in: query
          name: created_after
          schema:
            type: integer
        - description: |
            Supports sorting the deployments list by creation date.
          in: query
          name: sort
          schema:
            enum:
              - asc
              - desc
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                - created: '2016-02-11T13:03:17.063493443Z'
                  status: finished
                  name: production
                  artifact_name: Application 0.0.1
                  id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
                  finished: '2016-03-11T13:03:17.063493443Z'
                  device_count: 10
                  retries: 0
              schema:
                items:
                  $ref: '#/components/schemas/DeploymentV1'
                type: array
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of deployments matching query.
              schema:
                type: integer
            Link:
              description: Standard header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Find all deployments
      tags:
        - Deployments_Management API
    post:
      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.
      operationId: Deployments Create Deployment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewDeployment'
        description: New deployment that needs to be created.
        required: true
      responses:
        '201':
          content: {}
          description: New deployment created.
          headers:
            Location:
              description: URL of the newly created deployment.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: An active deployment with the same parameters already exists.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unprocessable Entity.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Create a deployment
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/statistics/list:
    post:
      operationId: Deployment Status Statistics List
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentIdentifier'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                  stats:
                    success: 3
                    pending: 1
                    failure: 0
                    downloading: 1
                    installing: 2
                    rebooting: 3
                    noartifact: 0
                    artifact_too_big: 0
                    already-installed: 0
                    aborted: 0
                    pause_before_installing: 1
                    pause_before_rebooting: 1
                    pause_before_committing: 1
                - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                  stats:
                    success: 3
                    pending: 1
                    failure: 0
                    downloading: 1
                    installing: 2
                    rebooting: 3
                    noartifact: 0
                    artifact_too_big: 0
                    already-installed: 0
                    aborted: 0
                    pause_before_installing: 1
                    pause_before_rebooting: 1
                    pause_before_committing: 1
              schema:
                items:
                  $ref: '#/components/schemas/DeploymentStatusStatisticsList200ResponseInner'
                type: array
          description: OK
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        Get status count for all devices in the listed deployments (plural).
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/group/{name}:
    post:
      description: |
        Deploy software to devices belonging to the specified group.

        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.
      operationId: Create Deployment for a Group of Devices
      parameters:
        - description: Device group name.
          in: path
          name: name
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewDeploymentForGroup'
        description: New deployment that needs to be created.
        required: true
      responses:
        '201':
          content: {}
          description: New deployment created.
          headers:
            Location:
              description: URL of the newly created deployment.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: An active deployment with the same parameters already exists.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unprocessable Entity.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Create a deployment for a group of devices
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/{id}:
    get:
      description: |
        Returns the details of a particular deployment.
      operationId: Show Deployment
      parameters:
        - description: Deployment identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentV1'
          description: Successful response.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Get the details of a selected deployment
      tags:
        - Deployments_Management API
    patch:
      description: |
        Updates the deployment's update control map.
        It is possible to update the deployment's update control map
        only if the map exists.
        In case the control map does not exist,
        409 Conflict error will be returned.
      operationId: Patch Deployment Control Map
      parameters:
        - description: Deployment identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchDeploymentControlMapRequest'
        description: Update control map to set.
        required: true
      responses:
        '204':
          content: {}
          description: Control map updated.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: An active deployment with the same parameters already exists.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Update the deployment's update control map
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/{deployment_id}/status:
    put:
      description: |
        Abort an ongoing deployment. 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.
      operationId: Abort Deployment
      parameters:
        - description: Deployment identifier.
          in: path
          name: deployment_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AbortDeploymentRequest'
        description: Deployment status.
        required: true
      responses:
        '204':
          content: {}
          description: Status updated successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unprocessable Entity.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Abort the deployment
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/{deployment_id}/statistics:
    get:
      operationId: Deployment Status Statistics
      parameters:
        - description: Deployment identifier
          in: path
          name: deployment_id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                success: 3
                pending: 1
                failure: 0
                downloading: 1
                installing: 2
                rebooting: 3
                noartifact: 0
                artifact_too_big: 0
                already-installed: 0
                aborted: 0
                pause_before_installing: 1
                pause_before_rebooting: 1
                pause_before_committing: 1
              schema:
                $ref: '#/components/schemas/Statistics'
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        Get status count for all devices in a deployment.
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/{deployment_id}/devices:
    get:
      deprecated: true
      operationId: List All Devices in Deployment
      parameters:
        - description: Deployment identifier.
          in: path
          name: deployment_id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeviceWithImage'
                type: array
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        DEPRECATED: _since Wed May 19 2021_ this end-point is deprecated because it doesn't support
        pagination and will be removed in the future, please use the
        /deployments/{deployment_id}/devices/list end-point instead.
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/{deployment_id}/devices/list:
    get:
      operationId: List Devices in Deployment
      parameters:
        - description: Deployment identifier.
          in: path
          name: deployment_id
          required: true
          schema:
            type: string
        - description: Filter devices by status within deployment.
          in: query
          name: status
          schema:
            enum:
              - failure
              - aborted
              - pause_before_installing
              - pause_before_committing
              - pause_before_rebooting
              - downloading
              - installing
              - rebooting
              - pending
              - success
              - noartifact
              - artifact_too_big
              - already-installed
              - decommissioned
              - pause
              - active
              - finished
            type: string
        - description: Starting page.
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Maximum number of results per page.
          in: query
          name: per_page
          schema:
            default: 20
            maximum: 500
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeviceWithImage'
                type: array
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        Get the list of devices and their respective status for the deployment
        with the given ID. The response includes devices as they get assigned
        to the deployment when checking for updates. Therefore, this endpoint
        will list all the devices only once each asks for updates and evaluates
        this deployment.
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/{id}/device_list:
    get:
      operationId: List Device IDs in Deployment
      parameters:
        - description: Deployment identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                - 00a0c91e6-7dec-11d0-a765-f81d4faebf6
                - 00a0c91e6-7dec-11d0-a765-f81d4faebf8
                - 00a0c91e6-7dec-11d0-a765-f81d4faebf7
              schema:
                description: List of device IDs
                items:
                  type: string
                type: array
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Get the list of device IDs being part of the deployment.
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/{deployment_id}/devices/{device_id}/log:
    get:
      description: |
        The response body for this endpoint include the device's deployment logs
        in text/plain format.
      operationId: Get Deployment Log for Device
      parameters:
        - description: Deployment identifier.
          in: path
          name: deployment_id
          required: true
          schema:
            type: string
        - description: Device identifier.
          in: path
          name: device_id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            text/plain:
              schema:
                type: string
          description: Successful response, including the logs in text/plain format.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Get the log of a selected device's deployment
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/{deployment_id}/devices/{device_id}/delta/status:
    get:
      description: |
        The response body for this endpoint include a detailed information on the delta
        generation job.
      operationId: Get Delta Generation Status
      parameters:
        - description: Deployment identifier.
          in: path
          name: deployment_id
          required: true
          schema:
            type: string
        - description: Device identifier.
          in: path
          name: device_id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
          description: Successful response, including the status in application/json format.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Get the detailed status of server side delta generation
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/devices/{id}:
    delete:
      description: |
        Abort all the active and pending Deployments for the specified Device.

        Please note that deployments for the Device not targeting it when issuing this API call won't be aborted. If the deployment applies to the Device in the future, for example, because of inventory updates, the Device will still process the deployment.
      operationId: Abort Deployments for a Device
      parameters:
        - description: System wide device identifier
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          content: {}
          description: Operation completed successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Abort all the active and pending Deployments for a Device
      tags:
        - Deployments_Management API
    get:
      description: |
        Return the Deployments history for the specified Device, listing all its Deployments.
      operationId: Deployments List Deployments for a Device
      parameters:
        - description: System wide device identifier
          in: path
          name: id
          required: true
          schema:
            type: string
        - description: Filter deployments by status for the given device.
          in: query
          name: status
          schema:
            enum:
              - failure
              - aborted
              - pause_before_installing
              - pause_before_committing
              - pause_before_rebooting
              - downloading
              - installing
              - rebooting
              - pending
              - success
              - noartifact
              - artifact_too_big
              - already-installed
              - decommissioned
              - pause
              - active
              - finished
            type: string
        - description: Starting page.
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Maximum number of results per page.
          in: query
          name: per_page
          schema:
            default: 20
            maximum: 20
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeviceDeploymentV1'
                type: array
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Return the Deployments history for a Device
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/devices/{id}/history:
    delete:
      description: |
        Mark as logically deleted the completed Device Deployments records for the given device.
        This effectively resets the Device Deployments history and makes the
        device eligible (again) for all the active deployments.
      operationId: Reset Device Deployments history
      parameters:
        - description: System wide device identifier
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          content: {}
          description: Operation completed successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Reset the Device Deployments history
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/releases:
    get:
      deprecated: true
      description: |
        Returns a collection of releases, allows filtering by release name.

        DEPRECATED: _since Wed May 19 2021_ this end-point is deprecated because it doesn't support
        pagination and will be removed in the future, please use the
        /deployments/releases/list end-point instead.
      operationId: List Releases
      parameters:
        - description: Release name filter.
          in: query
          name: name
          schema:
            type: string
        - description: Release description filter.
          in: query
          name: description
          schema:
            type: string
        - description: Release device type filter.
          in: query
          name: device_type
          schema:
            type: string
        - description: Update type filter.
          in: query
          name: update_type
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                - name: my-app-v1.0.1
                  artifacts:
                    - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                      name: Application 1.0.0
                      description: Johns Monday test build
                      device_types_compatible:
                        - Beagle Bone
                      info:
                        format: mender
                        version: 3
                      updates:
                        - type_info:
                            type: rootfs-image
                          files:
                            - name: rootfs-image-1
                              checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                              size: 123
                              date: 2016-03-11T13:03:17.063+0000
                          metadata: {}
                          meta_data: []
                      artifact_provides:
                        artifact_name: test
                        rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                        rootfs-image.version: test
                      artifact_depends:
                        device_type:
                          - test
                      clears_artifact_provides:
                        - rootfs-image.*
                      size: 36891648
                      modified: '2016-03-11T13:03:17.063493443Z'
                    - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                      name: Application 1.0.0
                      description: Johns Monday test build
                      device_types_compatible:
                        - Raspberry Pi
                      info:
                        format: mender
                        version: 3
                      updates:
                        - type_info:
                            type: rootfs-image
                          files:
                            - name: rootfs-image-1
                              checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                              size: 123
                              date: 2016-03-11T13:03:17.063+0000
                          metadata: {}
                          meta_data: []
                      artifact_provides:
                        artifact_name: test
                        rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                        rootfs-image.version: test
                      artifact_depends:
                        device_type:
                          - test
                      clears_artifact_provides:
                        - rootfs-image.*
                      size: 36891648
                      modified: '2016-03-11T13:03:17.063493443Z'
                - name: my-app-v2.0.0
                  artifacts:
                    - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                      name: Application 2.0.0
                      description: Johns Monday test build
                      device_types_compatible:
                        - Beagle Bone
                      info:
                        format: mender
                        version: 3
                      updates:
                        - type_info:
                            type: rootfs-image
                          files:
                            - name: rootfs-image-1
                              checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                              size: 123
                              date: 2016-03-11T13:03:17.063+0000
                          metadata: {}
                          meta_data: []
                      artifact_provides:
                        artifact_name: test
                        rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                        rootfs-image.version: test
                      artifact_depends:
                        device_type:
                          - test
                      clears_artifact_provides:
                        - rootfs-image.*
                      size: 36891648
                      modified: '2016-03-11T13:03:17.063493443Z'
              schema:
                $ref: '#/components/schemas/ReleasesV1'
          description: Successful response.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        List releases
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/deployments/releases/list:
    get:
      deprecated: true
      description: |
        Returns a collection of releases, allows filtering by release name and sorting
        by name or last modification date.

        DEPRECATED: _since Sep 24 2023_ due to a mismatch in the capitalization of the fields of the response
        body and lack of support for advanced filters and sorting, we have deprecated this
        endpoint. Please use the v2 /deployments/releases end-point instead.
      operationId: Deployments V1 List Releases with pagination
      parameters:
        - description: Release name filter.
          in: query
          name: name
          schema:
            type: string
        - description: Release description filter.
          in: query
          name: description
          schema:
            type: string
        - description: Release device type filter.
          in: query
          name: device_type
          schema:
            type: string
        - description: Update type filter.
          in: query
          name: update_type
          schema:
            type: string
        - description: Starting page.
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Maximum number of results per page.
          in: query
          name: per_page
          schema:
            default: 20
            maximum: 500
            type: integer
        - description: |
            Sort the release list by the specified field and direction.
          in: query
          name: sort
          schema:
            default: name:asc
            enum:
              - artifacts_count:asc
              - artifacts_count:desc
              - modified:asc
              - modified:desc
              - name:asc
              - name:desc
              - tags:asc
              - tags:desc
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                - name: my-app-v1.0.1
                  artifacts:
                    - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                      name: Application 1.0.0
                      description: Johns Monday test build
                      device_types_compatible:
                        - Beagle Bone
                      info:
                        format: mender
                        version: 3
                      updates:
                        - type_info:
                            type: rootfs-image
                          files:
                            - name: rootfs-image-1
                              checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                              size: 123
                              date: 2016-03-11T13:03:17.063+0000
                          metadata: {}
                          meta_data: []
                      artifact_provides:
                        artifact_name: test
                        rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                        rootfs-image.version: test
                      artifact_depends:
                        device_type:
                          - test
                      clears_artifact_provides:
                        - rootfs-image.*
                      size: 36891648
                      modified: '2016-03-11T13:03:17.063493443Z'
                    - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                      name: Application 1.0.0
                      description: Johns Monday test build
                      device_types_compatible:
                        - Raspberry Pi
                      info:
                        format: mender
                        version: 3
                      updates:
                        - type_info:
                            type: rootfs-image
                          files:
                            - name: rootfs-image-1
                              checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                              size: 123
                              date: 2016-03-11T13:03:17.063+0000
                          metadata: {}
                          meta_data: []
                      artifact_provides:
                        artifact_name: test
                        rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                        rootfs-image.version: test
                      artifact_depends:
                        device_type:
                          - test
                      clears_artifact_provides:
                        - rootfs-image.*
                      size: 36891648
                      modified: '2016-03-11T13:03:17.063493443Z'
                - name: my-app-v2.0.0
                  artifacts:
                    - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                      name: Application 2.0.0
                      description: Johns Monday test build
                      device_types_compatible:
                        - Beagle Bone
                      info:
                        format: mender
                        version: 3
                      updates:
                        - type_info:
                            type: rootfs-image
                          files:
                            - name: rootfs-image-1
                              checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                              size: 123
                              date: 2016-03-11T13:03:17.063+0000
                          metadata: {}
                          meta_data: []
                      artifact_provides:
                        artifact_name: test
                        rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                        rootfs-image.version: test
                      artifact_depends:
                        device_type:
                          - test
                      clears_artifact_provides:
                        - rootfs-image.*
                      size: 36891648
                      modified: '2016-03-11T13:03:17.063493443Z'
              schema:
                $ref: '#/components/schemas/ReleasesV1'
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of releases matching query.
              schema:
                type: integer
            Link:
              description: Standard header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        List releases with pagination
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/artifacts:
    get:
      deprecated: true
      description: |
        Returns a collection of all artifacts.

        DEPRECATED: _since Oct 18 2021_ this end-point is deprecated because it doesn't support
        pagination and will be removed in the future, please use the
        /artifacts/list end-point instead.
      operationId: List Artifacts
      parameters:
        - description: Release name filter.
          in: query
          name: name
          schema:
            type: string
        - description: Release description filter.
          in: query
          name: description
          schema:
            type: string
        - description: Release device type filter.
          in: query
          name: device_type
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ArtifactV1'
                type: array
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        List all the artifacts
      tags:
        - Deployments_Management API
    post:
      description: |
        Upload mender artifact. Multipart request with meta and artifact.
        Supports artifact [versions v1, v2, v3](https://docs.mender.io/overview/artifact#versions).
      operationId: Upload Artifact
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadArtifactRequest'
        required: true
      responses:
        '201':
          content: {}
          description: Artifact uploaded.
          headers:
            Location:
              description: URL of the newly uploaded artifact.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          content:
            application/json:
              example:
                error: an artifact with the same name and depends already exists
                request_id: e4dde7e9-9424-4311-8648-86e24b542410
                metadata:
                  conflict:
                    want: cookies
              schema:
                $ref: '#/components/schemas/ErrorExt'
          description: |
            An artifact with the same name and matching dependency requirements already exists.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Upload mender artifact
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/artifacts/list:
    get:
      deprecated: true
      description: |
        Returns a collection of all artifacts.

        DEPRECATED: _since Tue Jul 22 2025_ we deprecated the endpoint due to performance issues.
        Please use the v2 /artifacts endpoint instead.
        In the new endpoint, we support exact and prefix matching for the various fields
      operationId: Deployments V1 List Artifacts with pagination
      parameters:
        - description: Artifact name filter.
          in: query
          name: name
          schema:
            type: string
        - description: Artifact description filter.
          in: query
          name: description
          schema:
            type: string
        - description: Artifact device type filter.
          in: query
          name: device_type
          schema:
            type: string
        - description: Starting page.
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Maximum number of results per page.
          in: query
          name: per_page
          schema:
            default: 20
            maximum: 500
            type: integer
        - description: |
            Sort the artifact list by the specified field and direction.
          in: query
          name: sort
          schema:
            default: name:asc
            enum:
              - name:asc
              - name:desc
              - modified:asc
              - modified:desc
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ArtifactV1'
                type: array
          description: OK
          headers:
            X-Total-Count:
              description: Total number of releases matching query.
              schema:
                type: integer
            Link:
              description: Standard header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        List known artifacts
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/artifacts/directupload:
    post:
      operationId: Request Direct Upload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactUploadLink'
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Request link for uploading artifact directly to the storage backend. This is an on-prem endpoint only, not available on Hosted Mender.
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/artifacts/directupload/{id}/complete:
    post:
      operationId: Complete Direct Upload
      parameters:
        - description: Artifact ID returned by "Request Direct Upload" API.
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectUploadMetadata'
        description: Metadata for contents of the artifact.
        required: false
      responses:
        '202':
          content: {}
          description: Accepted
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          content:
            application/json:
              example:
                error: not found
                request_id: b4965265-4475-4d00-8efc-840eaee5cf7b
              schema:
                $ref: '#/components/schemas/CompleteDirectUpload404Response'
          description: A pending direct upload with the given ID was not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Notify the server that the direct upload is completed to make it available in the artifacts API. Optionally you can provide files metadata which will be absent otherwise if skip-verify flag is present in the deployments service. This is an on-prem endpoint only, not available on Hosted Mender.
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/artifacts/generate:
    post:
      description: |
        Generate a new Mender artifact from raw data and meta data. Multipart request with meta and raw file.
        Supports generating single-file updates only, using the Single File Update Module (https://hub.mender.io/t/single-file).
      operationId: Generate Artifact
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/GenerateArtifactRequest'
        required: true
      responses:
        '201':
          content: {}
          description: Artifact generation request accepted and queued for processing.
          headers:
            Location:
              description: URL of the artifact going to be generated.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Upload raw data to generate a new artifact
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/artifacts/{id}:
    delete:
      description: |
        Deletes the artifact from file and artifacts storage.
        Artifacts used by deployments in progress can not be deleted
        until deployment finishes.
      operationId: Delete Artifact
      parameters:
        - description: Artifact identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          content: {}
          description: The artifact deleted successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Artifact used by active deployment.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Delete the artifact
      tags:
        - Deployments_Management API
    get:
      description: |
        Returns the details of a selected artifact.
      operationId: Show Artifact
      parameters:
        - description: Artifact identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                name: Application 1.0.0
                description: Johns Monday test build
                device_types_compatible:
                  - Beagle Bone
                info:
                  format: mender
                  version: 3
                updates:
                  - type_info:
                      type: rootfs-image
                    files:
                      - name: rootfs-image-1
                        checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                        size: 123
                        date: 2016-03-11T13:03:17.063+0000
                    metadata: {}
                    meta_data: []
                artifact_provides:
                  artifact_name: test
                  rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                  rootfs-image.version: test
                artifact_depends:
                  device_type:
                    - test
                clears_artifact_provides:
                  - rootfs-image.*
                size: 36891648
                modified: '2016-03-11T13:03:17.063493443Z'
              schema:
                $ref: '#/components/schemas/ArtifactV1'
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Get the details of a selected artifact
      tags:
        - Deployments_Management API
    put:
      description: |
        Edit description. Artifact is not allowed to be edited if it was used
        in any deployment.
      operationId: Update Artifact Info
      parameters:
        - description: Artifact identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtifactUpdateV1'
        required: false
      responses:
        '204':
          content: {}
          description: The artifact metadata updated successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unprocessable Entity.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Update description of a selected artifact
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/artifacts/{id}/download:
    get:
      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.
      operationId: Download Artifact
      parameters:
        - description: Artifact identifier.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactLink'
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Get the download link of a selected artifact
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/limits/storage:
    get:
      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.
      operationId: Deployments Get Storage Usage
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageLimit'
          description: Successful response.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Get storage limit and current storage usage
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/config:
    get:
      operationId: Get Configuration
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationTenant'
          description: Successful response.
          headers:
            ETag:
              description: |
                Contains the configuration object's current ETag.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Get the deployments service configuration
      tags:
        - Deployments_Management API
  /api/management/v1/deployments/config/binary_delta:
    put:
      operationId: Update Binary Delta configuration
      parameters:
        - description: Contains the config current ETag, and performs the update only if it matches the one stored in the database.
          in: header
          name: If-Match
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BinaryDeltaConfigurationUpdate'
        description: Binary Delta server-side generation configuration.
        required: true
      responses:
        '204':
          content: {}
          description: Configuration updated.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Delta generation is disabled.
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Document with a matching ETag does not exist.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Set the Binary Delta server-side generation configuration
      tags:
        - Deployments_Management API
  /api/management/v2/deployments/deployments:
    get:
      description: |
        Returns a filtered collection of deployments in the system. While you can provide multiple
        deployment identifiers, and multiple names to get the multiple deployments you cannot mix
        the ids and names in a one query expecting to get deployments that match both names or ids.
        The endpoint will return the deployments that match the ids and the name, if combined.
      operationId: Deployments V2 List Deployments
      parameters:
        - description: |
            Deployment identifier. You can provide it multiple times to query a set of deployments.
          in: query
          name: id
          schema:
            type: string
        - description: |
            Deployment name. You can provide it multiple times to query a set of deployments.
          in: query
          name: name
          schema:
            type: string
        - description: Deployment status filter.
          in: query
          name: status
          schema:
            enum:
              - inprogress
              - finished
              - pending
            type: string
        - description: |
            Deployment type filter.
          in: query
          name: type
          schema:
            enum:
              - software
              - configuration
            type: string
        - description: Results page number
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Maximum number of results per page.
          in: query
          name: per_page
          schema:
            default: 20
            maximum: 500
            type: integer
        - description: List only deployments created before and equal to Unix timestamp (UTC)
          in: query
          name: created_before
          schema:
            type: integer
        - description: List only deployments created after and equal to Unix timestamp (UTC)
          in: query
          name: created_after
          schema:
            type: integer
        - description: |
            Supports sorting the deployments list by creation date.
          in: query
          name: sort
          schema:
            enum:
              - asc
              - desc
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeploymentV2'
                type: array
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of deployments matching query.
              schema:
                type: integer
            Link:
              description: Standard header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: List all the deployments matching the specified filter parameters
      tags:
        - Deployments_v2_Management API
    post:
      description: |
        Deploy software to devices matching the given filter.
        The 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 the status of `noartifact`.
        If there are no artifacts for the deployment, the deployment will not be created and the 422 Unprocessable Entity status code will be returned.
        Dynamic deployments feature is available only to Enterprise users.
      operationId: Create Deployment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewDeploymentV2'
        description: New deployment that needs to be created.
        required: true
      responses:
        '201':
          content: {}
          description: New deployment created.
          headers:
            Location:
              description: URL of the newly created deployment.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: An active deployment with the same parameters already exists.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unprocessable Entity.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Create a deployment
      tags:
        - Deployments_v2_Management API
      x-mender-plan:
        - enterprise
  /api/management/v2/deployments/deployments/releases:
    delete:
      description: |
        Deletes releases with names provided in the message body.
        Releases used by deployments in progress can not be deleted
        until deployment finishes.
      operationId: Delete Releases
      parameters:
        - description: Name of the release to be deleted
          in: query
          name: name
          required: true
          schema:
            type: string
      responses:
        '204':
          content: {}
          description: Releases deleted successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleasesDeleteError'
          description: Conflict.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: Delete the releases with given names
      tags:
        - Deployments_v2_Management API
    get:
      description: |
        Returns a collection of releases, allows filtering by release name and sorting
        by name or last modification date.
      operationId: Deployments V2 List Releases with pagination
      parameters:
        - description: Release name filter.
          in: query
          name: name
          schema:
            type: string
        - description: Tag filter.
          in: query
          name: tag
          schema:
            items:
              type: string
            type: array
          style: form
        - description: Update type filter.
          in: query
          name: update_type
          schema:
            type: string
        - description: Starting page.
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Maximum number of results per page.
          in: query
          name: per_page
          schema:
            default: 20
            maximum: 500
            type: integer
        - description: |
            Sort the release list by the specified field and direction.
          in: query
          name: sort
          schema:
            default: name:asc
            enum:
              - artifacts_count:asc
              - artifacts_count:desc
              - modified:asc
              - modified:desc
              - name:asc
              - name:desc
              - tags:asc
              - tags:desc
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                - name: my-app-v1.0.1
                  artifacts:
                    - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                      name: Application 1.0.0
                      description: Johns Monday test build
                      device_types_compatible:
                        - Beagle Bone
                      info:
                        format: mender
                        version: 3
                      updates:
                        - type_info:
                            type: rootfs-image
                          files:
                            - name: rootfs-image-1
                              checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                              size: 123
                              date: 2016-03-11T13:03:17.063+0000
                          metadata: {}
                          meta_data: []
                      artifact_provides:
                        artifact_name: test
                        rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                        rootfs-image.version: test
                      artifact_depends:
                        device_type:
                          - test
                      clears_artifact_provides:
                        - rootfs-image.*
                      size: 36891648
                      modified: '2016-03-11T13:03:17.063493443Z'
                    - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                      name: Application 1.0.0
                      description: Johns Monday test build
                      device_types_compatible:
                        - Raspberry Pi
                      info:
                        format: mender
                        version: 3
                      updates:
                        - type_info:
                            type: rootfs-image
                          files:
                            - name: rootfs-image-1
                              checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                              size: 123
                              date: 2016-03-11T13:03:17.063+0000
                          metadata: {}
                          meta_data: []
                      artifact_provides:
                        artifact_name: test
                        rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                        rootfs-image.version: test
                      artifact_depends:
                        device_type:
                          - test
                      clears_artifact_provides:
                        - rootfs-image.*
                      size: 36891648
                      modified: '2016-03-11T13:03:17.063493443Z'
                - name: my-app-v2.0.0
                  artifacts:
                    - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
                      name: Application 2.0.0
                      description: Johns Monday test build
                      device_types_compatible:
                        - Beagle Bone
                      info:
                        format: mender
                        version: 3
                      updates:
                        - type_info:
                            type: rootfs-image
                          files:
                            - name: rootfs-image-1
                              checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                              size: 123
                              date: 2016-03-11T13:03:17.063+0000
                          metadata: {}
                          meta_data: []
                      artifact_provides:
                        artifact_name: test
                        rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                        rootfs-image.version: test
                      artifact_depends:
                        device_type:
                          - test
                      clears_artifact_provides:
                        - rootfs-image.*
                      size: 36891648
                      modified: '2016-03-11T13:03:17.063493443Z'
              schema:
                $ref: '#/components/schemas/ReleasesV2'
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of releases matching query.
              schema:
                type: integer
            Link:
              description: Standard header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        List releases
      tags:
        - Deployments_v2_Management API
  /api/management/v2/deployments/deployments/releases/{release_name}:
    get:
      description: |
        Returns the release with given name.
      operationId: Get Release with given name
      parameters:
        - description: Name of the release
          in: path
          name: release_name
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseV2'
          description: Successful response.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        Get release
      tags:
        - Deployments_v2_Management API
    patch:
      description: |
        Updates the Release object.
      operationId: Update Release information
      parameters:
        - description: Name of the release
          in: path
          name: release_name
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReleaseUpdate'
        required: false
      responses:
        '204':
          content: {}
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        Update selected fields of the Release object.
      tags:
        - Deployments_v2_Management API
  /api/management/v2/deployments/deployments/releases/{release_name}/tags:
    put:
      description: |
        Assigns tags to a release. The tags associated with the release will be
        replaced with the ones defined in the request body.

        LIMITATIONS:
          * Max 20 tags can be assigned to a single release.
          * There can be no more than 100 unique tag keys in total.
      operationId: Assign Release Tags
      parameters:
        - description: Name of the release
          in: path
          name: release_name
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tags'
        required: false
      responses:
        '204':
          content: {}
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          content:
            application/json:
              example:
                error: the total number of unique tags has been exceeded
                request_id: f7881e82-0492-49fb-b459-795654e7188a
              schema:
                $ref: '#/components/schemas/Error'
          description: Too many unique tag keys in use.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        Update and replace the tags of a release.
      tags:
        - Deployments_v2_Management API
  /api/management/v2/deployments/releases/all/tags:
    get:
      operationId: List Release Tags
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tags'
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          content:
            application/json:
              example:
                error: the total number of unique tags has been exceeded
                request_id: f7881e82-0492-49fb-b459-795654e7188a
              schema:
                $ref: '#/components/schemas/Error'
          description: Too many unique tag keys in use.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        Lists all available tags for releases.
      tags:
        - Deployments_v2_Management API
  /api/management/v2/deployments/releases/all/types:
    get:
      operationId: List Release Types
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTypes'
          description: Successful response.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        Lists all release update types.
      tags:
        - Deployments_v2_Management API
  /api/management/v2/deployments/artifacts:
    get:
      description: |
        Returns a collection of all artifacts sorted by name.
      operationId: Deployments V2 List Artifacts with pagination
      parameters:
        - description: |
            Artifact(s) name(s) filter.
            Multiple names can be provided (e.g., `?name=foo&name=bar`).
            Supports exact matching or prefix matching by adding `*` to the end (e.g., `foo*`).
            Note: when using prefix matching you may pass only a single value and you cannot combine
            prefix matching and exact matching in the same request.
          in: query
          name: name
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          examples:
            single:
              summary: Get artifact with the given name.
              value:
                - foo
            multi:
              summary: Get artifact matching multiple names by repeating the query parameter.
              value:
                - foo
                - bar
            prefix:
              summary: Get artifact with the specified prefix
              value:
                - foo*
        - description: |
            Artifact description filter.
            Supports exact matching or prefix matching by adding `*` to the end (e.g., `foo*`).
          in: query
          name: description
          schema:
            type: string
        - description: |
            Artifact device type filter.
            Supports exact matching or prefix matching by adding `*` to the end (e.g., `foo*`).
          in: query
          name: device_type
          schema:
            type: string
        - description: Starting page.
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Maximum number of results per page.
          in: query
          name: per_page
          schema:
            default: 20
            maximum: 500
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ArtifactV2'
                type: array
          description: OK
          headers:
            Link:
              description: Standard header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      summary: |
        Lists known artifacts.
      tags:
        - Deployments_v2_Management API
  /api/management/v2/deployments/releases/delta/jobs:
    get:
      operationId: List server side binary delta generation jobs
      tags:
        - Deployments_v2_Management API
      security:
        - ManagementJWT: []
      summary: |
        Lists all jobs originating from the generation of binary deltas on the server side.
      parameters:
        - name: page
          in: query
          description: Starting page.
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          required: false
          schema:
            type: integer
            default: 20
            maximum: 500
        - name: sort
          in: query
          description: |
            Sort the job list by the specified field and direction.
          required: false
          schema:
            type: string
            enum:
              - status:asc
              - status:desc
              - started:asc
              - started:desc
              - to_version:asc
              - to_version:desc
              - from_version:asc
              - from_version:desc
            default: status:asc
      responses:
        '200':
          description: Succesful query
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeltaJobsListItem'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v2/deployments/releases/delta/jobs/{id}:
    get:
      operationId: Get server side binary delta generation job details
      tags:
        - Deployments_v2_Management API
      security:
        - ManagementJWT: []
      summary: |
        Returns the details of a generation of binary deltas on the server side by delta generation job id.
      parameters:
        - name: id
          in: path
          description: |
            Delta generation job id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeltaJobDetailsItem'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/devices/v1/authentication/auth_requests:
    post:
      summary: Submit an authentication request
      description: |
        The device presents its unique identity data and public key, and signs the request with its private key.
        If the request is valid and the device is known to the system, a valid JWT authentication token is issued.

        Unless the device is pre-authorized, the very first authentication request from a device will
        always result in a 'HTTP 401 Unauthorized' response. At the same time, the identity data is recorded for
        later inspection by the user, who can then explicitly accept or reject the device via the web GUI.
        A subsequent authentication request will reflect this decision.

        Note that when the JWT expires, the device must renew the JWT by sending a new authentication request.
      operationId: DeviceAuth Authenticate Device
      tags:
        - Device_Authentication_Device API
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequest'
      parameters:
        - name: X-MEN-Signature
          in: header
          required: true
          description: |
            Request signature.
            The request signature depends on the public key submitted in the AuthRequest.
            A summary of signature algorithms and format follows:
            | Type       | Digest              | Format                   | Algorithm    |
            |------------|---------------------|--------------------------|--------------|
            | RSA        | SHA256(AuthRequest) | Base64(Signature)        | [RFC2313]    |
            | ECDSA      | SHA256(AuthRequest) | Base64(ASN.1(SEQ{R, S})) | [ANSI x9.62] |
            | Ed25519    | AuthRequest         | Base64(Signature)        | [RFC8032]    |
            *Remark:*
            For ECDSA, the signature constitutes two integers (R and S)
            in which case the binary signature is taken as the ASN.1 sequence of
            the two numbers in the given order.
          schema:
            type: string
      responses:
        '200':
          description: Authentication successful - a new JWT is issued and returned.
          content:
            application/json:
              schema:
                type: string
                example: |
                  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzYxMTkxMzYsImp0aSI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2MWNlN2E4NCIsImlzcyI6Ik1lbmRlciIsInN1YiI6IjlmNzM2YmNiMjhiZmFhOTg5YjVmNWUxNDA5ZGJmMGVhYzdhNjYxMjZiNjMyZDAzYWYwZmUzNGFjMjhiZjRhNzIifQ.PArg_WuoQkOiJ4kDoHYbQRjnxykeF1lIlsgJfUryhivnip2AHz5bkxxaxF20XTq9mIzSDonTSukfOtkaxJTZXjCMHjgh50iwa6_pUivIYWsIJW2O9t_M9T_SC-7Xu7IhE_iKQFb2NXxVfAG4nZKrheUM4MJBt8SxCawT2EOPopiLeIC6MOFBu_sPa9RsagKSZCRaLTBWVhmEGbfn19tLOX3Z06DZql61G-VY-YuyOlBjpEsCc4HiA1cXIdncCZKugrONOa44_m4yx0VsgRg4jCd2VO-Is-A96Jw3zkZshoD2cPXVSKAhFdhHja447ftuYYRq9kIQghKi3hfsPgyFZQ
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: The device authentication is forbidden. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: device unauthorized
                request_id: f7881e82-0492-49fb-b459-795654e7188a
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
      security:
        - DeviceJWT: []
  /api/internal/v1/devauth/alive:
    get:
      operationId: DeviceAuth Internal Check Liveliness
      tags:
        - Device_Authentication_Internal API
      summary: Trivial endpoint that unconditionally returns an empty 204 response whenever the API handler is running correctly.
      responses:
        '204':
          description: Service is up and running
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/health:
    get:
      operationId: DeviceAuth Internal Check Health
      tags:
        - Device_Authentication_Internal API
      summary: Check the health of the service
      responses:
        '204':
          description: Service is healthy and all dependencies are up and running.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: Service unhealthy / not ready to accept traffic. At least one dependency is not running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example2:
                  value:
                    error: 'error reaching MongoDB: context deadline exceeded'
                    request_id: ffd712be-d697-4cb7-814b-88ff1e2eb5f6
  /api/internal/v1/devauth/tokens/verify:
    post:
      operationId: DeviceAuth Internal Verify JWT
      tags:
        - Device_Authentication_Internal API
      summary: Check the validity of a token
      description: Besides the basic validity check, checks the token expiration time and user-initiated token revocation. Services which intend to use it should be correctly set up in the gateway's configuration.
      parameters:
        - name: Authorization
          in: header
          description: The token in base64-encoded form.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The token is valid.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/internal/v1/devauth/tokens:
    delete:
      operationId: DeviceAuth Internal Revoke Device Tokens
      tags:
        - Device_Authentication_Internal API
      summary: Delete device tokens
      description: This endpoint is designed to be used for device decommissioning and tenant account suspension purpose. For device decommissioning purpose both tenant_id and device_id parameters must be set. When both tenant_id and device_id parameters are set, all tokens will be deleted for device with given device_id. For tenant account suspension purpose only tenant_id parameter must be set. When device_id parameter is not set (only tenant_id parameter is set) all tokens for all tenant devices will be deleted.
      parameters:
        - name: tenant_id
          in: query
          required: true
          schema:
            type: string
        - name: device_id
          in: query
          required: false
          schema:
            type: string
      responses:
        '204':
          description: Tokens deleted.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/internal/v1/devauth/tenant/limits/{name}:
    get:
      operationId: Get Device Limits
      tags:
        - Device_Authentication_Internal API
      summary: Max device count limits for a list of tenants
      parameters:
        - name: name
          in: path
          description: Limit identifier.
          required: true
          schema:
            type: string
            enum:
              - max_devices
              - max_micro_devices
              - max_system_devices
        - name: tenant_id
          in: query
          description: Tenant ID.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TenantLimit'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/tenant/limits:
    get:
      operationId: Get All Device Limits
      tags:
        - Device_Authentication_Internal API
      summary: Get all limits for a list of tenants.
      parameters:
        - name: tenant_id
          in: query
          description: Tenant ID.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeviceLimitTenant'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/tenant/{tenant_id}/limits/{name}:
    get:
      operationId: DeviceAuth Internal Get Device Limit
      tags:
        - Device_Authentication_Internal API
      summary: Max device count limit
      parameters:
        - name: tenant_id
          description: Tenant ID.
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: Limit identifier.
          required: true
          schema:
            type: string
            enum:
              - max_devices
              - max_micro_devices
              - max_system_devices
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceLimit'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: DeviceAuth Internal Update Device Limit
      tags:
        - Device_Authentication_Internal API
      summary: Update max device count limit
      parameters:
        - name: tenant_id
          description: Tenant ID.
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: Limit identifier.
          required: true
          schema:
            type: string
            enum:
              - max_devices
              - max_micro_devices
              - max_system_devices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceLimit'
      responses:
        '204':
          description: Limit information updated.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: DeviceAuth Internal Clear Device Limit
      tags:
        - Device_Authentication_Internal API
      summary: Remove max device count limit
      parameters:
        - name: tenant_id
          description: Tenant ID.
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: Limit identifier.
          required: true
          schema:
            type: string
            enum:
              - max_devices
              - max_micro_devices
              - max_system_devices
      responses:
        '204':
          description: Limit information deleted.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/tenants:
    post:
      operationId: DeviceAuth Internal Create Tenant
      tags:
        - Device_Authentication_Internal API
      summary: Provision a new tenant
      description: Sets up all tenant-related infrastructure, e.g. a migrated tenant's database.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantNew'
      responses:
        '201':
          description: Tenant was successfully provisioned.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/tenants/{tid}/devices/{did}:
    delete:
      operationId: DeviceAuth Internal Delete Device
      tags:
        - Device_Authentication_Internal API
      summary: Delete a device from deviceauth service.
      parameters:
        - name: tid
          in: path
          required: true
          schema:
            type: string
        - name: did
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Authentication'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '201':
          description: Device deleted successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/internal/v1/devauth/tenants/{tid}/devices/{did}/external:
    put:
      operationId: DeviceAuth Internal Set external identity
      tags:
        - Device_Authentication_Internal API
      summary: Replace the external identity of a device.
      parameters:
        - name: tid
          in: path
          description: Tenant identifier.
          required: true
          schema:
            type: string
        - name: did
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalDevice'
      responses:
        '204':
          description: Device identity updated successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/tenants/{tid}:
    delete:
      operationId: Delete Tenant
      tags:
        - Device_Authentication_Internal API
      summary: Delete all the data for given tenant.
      parameters:
        - name: tid
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: All the tenant data have been successfully deleted.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/tenants/{tid}/devices/{did}/status:
    get:
      operationId: DeviceAuth Internal Device Status
      tags:
        - Device_Authentication_Internal API
      summary: Get the status of a tenant's device
      description: Returns the overall status of the device, computed over the statuses of its various authsets.
      parameters:
        - name: tid
          in: path
          description: Tenant identifier.
          required: true
          schema:
            type: string
        - name: did
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/tenants/{tid}/devices:
    get:
      operationId: DeviceAuth Internal List Devices
      tags:
        - Device_Authentication_Internal API
      summary: Get a list of tenant's devices.
      description: Provides a list of tenant's devices, sorted by creation date, with optional device status filter.
      parameters:
        - name: tid
          in: path
          description: Tenant identifier.
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: Device status filter. If not specified, all devices are listed.
          required: false
          schema:
            type: string
            enum:
              - pending
              - accepted
              - rejected
              - preauthorized
              - noauth
        - name: id
          in: query
          description: Device ID filter. Can be repeated to query a set of devices.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: page
          in: query
          description: Results page number.
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          required: false
          schema:
            type: integer
            default: 20
            maximum: 500
      responses:
        '200':
          description: An array of devices.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
          headers:
            Link:
              description: Standard header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/tenants/{tid}/devices/count:
    get:
      operationId: DeviceAuth Internal Count Devices
      summary: Count number of devices, optionally filtered by status.
      tags:
        - Device_Authentication_Internal API
      parameters:
        - name: tid
          in: path
          description: Tenant identifier.
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: Device status filter, one of 'pending', 'accepted', 'rejected', 'noauth'. Default is 'all devices'.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Device count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devauth/tenant/{tid}/limits:
    put:
      operationId: DeviceAuth Internal Put All Limits
      summary: Set all the limits for given tenant.
      tags:
        - Device_Authentication_Internal API
      parameters:
        - name: tid
          in: path
          description: Tenant identifier.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DeviceLimitTenantPut'
      responses:
        '204':
          description: Device limits updated.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: DeviceAuth Internal Get All Limits
      summary: Get all the limits for given tenant.
      tags:
        - Device_Authentication_Internal API
      parameters:
        - name: tid
          in: path
          description: Tenant identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Device limits.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeviceLimitTenant'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: DeviceAuth Internal Delete All Limits
      summary: Delete all the limits for all the tiers for given tenant ID.
      tags:
        - Device_Authentication_Internal API
      parameters:
        - name: tid
          in: path
          description: Tenant identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Device limits.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v2/devauth/devices:
    get:
      operationId: DeviceAuth Management List Devices
      security:
        - ManagementJWT: []
      summary: List devices sorted by age and optionally filter on device status.
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: authorization
          in: header
          description: The token in base64-encoded form.
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Device status filter. If not specified, all devices are listed.
          required: false
          schema:
            type: string
            enum:
              - pending
              - accepted
              - rejected
              - preauthorized
              - noauth
        - name: id
          in: query
          description: Device ID filter. Can be repeated to query a set of devices.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: page
          in: query
          description: Results page number
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          required: false
          schema:
            type: integer
            default: 20
            maximum: 500
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: An array of devices.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
          headers:
            Link:
              description: Standard header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: DeviceAuth Management Preauthorize
      security:
        - ManagementJWT: []
      summary: Submit a preauthorized device.
      description: Authorize a device identity with the server backend. On success the device identity is marked as 'preauthorized', and once the device connects and sends it's first authentication request the device automatically become 'accepted' without explicit user intervention.
      tags:
        - Device_Authentication_Management API
      parameters:
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreAuthSet'
      responses:
        '201':
          description: Device submitted.
          headers:
            Location:
              description: URL of the newly created device.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          description: Device already exists. Response contains conflicting device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v2/devauth/devices/search:
    post:
      operationId: DeviceAuth Management Search Devices
      security:
        - ManagementJWT: []
      summary: Query for devices. Returns a list of matching devices with AuthSets sorted by age.
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: page
          in: query
          description: Results page number
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          required: false
          schema:
            type: integer
            default: 20
            maximum: 500
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        description: Device status filter. All properties can be either a single string or an array of strings.
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: array
                  description: Device status filter. Can be an array for querying devices from multiple device statuses.
                  items:
                    type: string
                    enum:
                      - pending
                      - accepted
                      - rejected
                      - preauthorized
                      - noauth
                id:
                  type: array
                  description: Device ID filter. Can be a string for querying for a single device.
                  items:
                    type: string
                    description: Device ID
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                description: Array of devices
                items:
                  $ref: '#/components/schemas/Device'
          headers:
            Link:
              description: Pagination link header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v2/devauth/devices/{id}:
    get:
      operationId: DeviceAuth Management Get Device
      security:
        - ManagementJWT: []
      summary: Get a particular device.
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Authentication'
      responses:
        '200':
          description: Device found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: DeviceAuth Management Decommission device
      security:
        - ManagementJWT: []
      summary: Remove device and associated authentication set
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: Authorization
          in: header
          description: The token in base64-encoded form.
          required: false
          schema:
            type: string
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: Device decommissioned.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/management/v2/devauth/devices/{id}/auth/{aid}:
    delete:
      operationId: DeviceAuth Management Remove authentication
      security:
        - ManagementJWT: []
      summary: Remove (dismiss) the device authentication set
      description: Removes the device authentication set. Removing 'accepted' authentication set is equivalent to rejecting device and removing authentication set. If there is only one authentication set for the device and the device is 'preauthorized' then the device will also be deleted.
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
        - name: aid
          in: path
          description: Authentication data set identifier.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Authentication'
      responses:
        '204':
          description: Device authentication set deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/management/v2/devauth/devices/{id}/auth/{aid}/status:
    put:
      operationId: DeviceAuth Management Set Authentication Status
      security:
        - ManagementJWT: []
      summary: Update the device authentication set status
      description: 'Sets the status of an authentication data set of selected value. Valid state transitions: - ''pending'' -> ''accepted'' - ''pending'' -> ''rejected'' - ''rejected'' -> ''accepted'' - ''accepted'' -> ''rejected'''
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: authorization
          in: header
          description: The token in base64-encoded form.
          required: false
          schema:
            type: string
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
        - name: aid
          in: path
          description: Authentication data set identifier.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Status'
      responses:
        '204':
          description: The device authentication data set status was successfully updated.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Request cannot be fulfilled e.g. due to exceeded limit on maximum accepted devices (see error message).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
    get:
      operationId: DeviceAuth Management Get Authentication Status
      security:
        - ManagementJWT: []
      summary: Get the device authentication set status
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
        - name: aid
          in: path
          description: Authentication data set identifier.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Successful response - the device's authentication set status is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v2/devauth/devices/count:
    get:
      operationId: DeviceAuth Management Count Devices
      security:
        - ManagementJWT: []
      summary: Count number of devices, optionally filtered by status.
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: status
          in: query
          description: Device status filter, one of 'pending', 'accepted', 'rejected', 'noauth', 'preauthorized'. Default is 'all devices', meaning devices with any of these statuses will be counted.
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Device count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v2/devauth/tokens/{id}:
    delete:
      operationId: DeviceAuth Management Revoke API Token
      security:
        - ManagementJWT: []
      summary: Revoke JWT with given id
      description: Deletes the token, effectively revoking it. The device must apply for a new one with a new authentication request. The token 'id' corresponds to the standard 'jti' claim.
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: id
          in: path
          description: Unique token identifier('jti').
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: The token was successfully deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/management/v2/devauth/limits/{name}:
    get:
      deprecated: true
      description: |
        DEPRECATED: _since Tue Oct 21 2025_ we deprecated the endpoint due to a change in device limits. Please use the v2 /devauth/limits/devices endpoint instead.
      operationId: DeviceAuth Management Get Device Limit
      security:
        - ManagementJWT: []
      summary: Obtain limit of accepted devices.
      tags:
        - Device_Authentication_Management API
      parameters:
        - name: name
          in: path
          description: Limit identifier.
          required: true
          schema:
            type: string
            enum:
              - max_devices
              - max_micro_devices
              - max_system_devices
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Usage statistics and limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceLimit'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v2/devauth/limits/devices:
    get:
      operationId: Get Device Limits Per Tier
      security:
        - ManagementJWT: []
      summary: Obtain limit of accepted devices per tier
      tags:
        - Device_Authentication_Management API
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Usage statistics and limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceTierLimits'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/management/v2/devauth/license:
    get:
      operationId: Get Device License
      security:
        - ManagementJWT: []
      summary: Obtain license information for devices.
      tags:
        - Device_Authentication_Management API
      parameters:
        - $ref: '#/components/parameters/Authentication'
      responses:
        '200':
          description: Usage statistics and limits.
          content:
            text/csv:
              schema:
                title: UsageStatistics
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
  /api/management/v2/devauth/auto-auth:
    post:
      operationId: Automatically Authenticate Device
      security:
        - ManagementJWT: []
      tags:
        - Device_Authentication_Management API
      summary: Automatically accept a device
      description: |
        The caller presents device identity data and public key, and signs the request with a private key.
        If the request is valid the device is accepted, and a valid JWT authentication token is issued.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoAuthRequest'
      parameters:
        - name: X-MEN-Signature
          in: header
          description: |
            Request signature.

            The request signature depends on the public key submitted in the
            AuthRequest. A summary of signature algorithms and format follows:

            | Type       | Digest              | Format                   | Algorithm    |
            |------------|---------------------|--------------------------|--------------|
            | RSA        | SHA256(AuthRequest) | Base64(Signature)        | [RFC2313]    |
            | ECDSA      | SHA256(AuthRequest) | Base64(ASN.1(SEQ{R, S})) | [ANSI x9.62] |
            | ED25519    | AuthRequest         | Base64(Signature)        | [RFC8032]    |
            *Remark:*
            For ECDSA, the signature constitutes two integers (R and S)
            in which case the binary signature is taken as the ASN.1 sequence of
            the two numbers in the given order.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Authentication successful - a new JWT is issued and returned.
          content:
            application/json:
              schema:
                type: string
                example: |
                  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzYxMTkxMzYsImp0aSI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2MWNlN2E4NCIsImlzcyI6Ik1lbmRlciIsInN1YiI6IjlmNzM2YmNiMjhiZmFhOTg5YjVmNWUxNDA5ZGJmMGVhYzdhNjYxMjZiNjMyZDAzYWYwZmUzNGFjMjhiZjRhNzIifQ.PArg_WuoQkOiJ4kDoHYbQRjnxykeF1lIlsgJfUryhivnip2AHz5bkxxaxF20XTq9mIzSDonTSukfOtkaxJTZXjCMHjgh50iwa6_pUivIYWsIJW2O9t_M9T_SC-7Xu7IhE_iKQFb2NXxVfAG4nZKrheUM4MJBt8SxCawT2EOPopiLeIC6MOFBu_sPa9RsagKSZCRaLTBWVhmEGbfn19tLOX3Z06DZql61G-VY-YuyOlBjpEsCc4HiA1cXIdncCZKugrONOa44_m4yx0VsgRg4jCd2VO-Is-A96Jw3zkZshoD2cPXVSKAhFdhHja447ftuYYRq9kIQghKi3hfsPgyFZQ
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/devices/v1/deviceconfig/configuration:
    get:
      operationId: DeviceConfig Get Device Configuration
      tags:
        - Device_configure_Device API
      summary: Query the configuration store; retrieve all key-value pairs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAPIConfiguration'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
    put:
      operationId: DeviceConfig Report Device Configuration
      tags:
        - Device_configure_Device API
      summary: Set a key-value pair store, updating if existing, removing if empty
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceAPIConfiguration'
      responses:
        '204':
          description: Created
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
  /api/internal/v1/deviceconfig/health:
    get:
      tags:
        - Device_configure_Internal API
      summary: Get health status of service
      operationId: DeviceConfig Internal Check Health
      responses:
        '204':
          description: Service is healthy.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconfig/alive:
    get:
      tags:
        - Device_configure_Internal API
      summary: Get service liveliness status.
      operationId: DeviceConfig Internal Check Liveliness
      responses:
        '204':
          description: Service is up and serving requests.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconfig/tenants:
    post:
      tags:
        - Device_configure_Internal API
      operationId: DeviceConfig Internal Provision tenant
      summary: Initialize internal state for a new tenant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantNew'
      responses:
        '201':
          description: Tenant initialized successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconfig/tenants/{tenantId}:
    delete:
      operationId: DeviceConfig Internal Delete Tenant
      tags:
        - Device_configure_Internal API
      summary: Delete all the data for given tenant.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant.
      responses:
        '204':
          description: All the tenant data have been successfully deleted.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconfig/tenants/{tenantId}/devices:
    post:
      tags:
        - Device_configure_Internal API
      operationId: DeviceConfig Internal Provision device
      summary: Register a new device with the deviceconfig service.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant the device belongs to.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionDevice'
      responses:
        '201':
          description: Device was provisioned successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconfig/tenants/{tenantId}/devices/{deviceId}:
    delete:
      tags:
        - Device_configure_Internal API
      operationId: DeviceConfig Internal Decommission device
      summary: Remove a device from the deviceconfig service.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant the device belongs to.
        - in: path
          name: deviceId
          schema:
            type: string
          required: true
          description: ID of the target device.
      responses:
        '204':
          description: Device was deleted successfully
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconfig/tenants/{tenantId}/configurations/device/{deviceId}/deploy:
    post:
      operationId: DeviceConfig Internal Deploy Device Configuration
      tags:
        - Device_configure_Internal API
      summary: Deploy the device's configuration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewConfigurationDeployment'
      parameters:
        - in: path
          name: deviceId
          schema:
            type: string
          required: true
          description: ID of the device.
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of the tenant.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewConfigurationDeploymentResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/deviceconfig/configurations/device/{deviceId}:
    get:
      operationId: DeviceConfig Management Get Device Configuration
      tags:
        - Device_configure_Management API
      summary: Get the device's configuration
      parameters:
        - in: path
          name: deviceId
          schema:
            type: string
            format: uuid
          required: true
          description: ID of the device to query.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceConfiguration'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    put:
      operationId: DeviceConfig Management Set Device Configuration
      tags:
        - Device_configure_Management API
      summary: Set the device's configuration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagementAPIConfiguration'
      parameters:
        - in: path
          name: deviceId
          schema:
            type: string
          required: true
          description: ID of the device to query.
      responses:
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/deviceconfig/configurations/device/{deviceId}/deploy:
    post:
      operationId: DeviceConfig Management Deploy Device Configuration
      tags:
        - Device_configure_Management API
      summary: Deploy the device's configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewConfigurationDeployment'
      parameters:
        - in: path
          name: deviceId
          schema:
            type: string
          required: true
          description: ID of the device.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewConfigurationDeploymentResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/devices/v1/deviceconnect/connect:
    get:
      tags:
        - Device_connect_Device API
      operationId: DeviceConnect Connect
      summary: Connect the device and make it available to the server.
      description: Calling /connect will upgrade the connection to a persistent websocket connection and make the device available to the management API. The device must provide DeviceJWT identity either as Authorization (Bearer) header or as a cookie named 'JWT'.
      parameters:
        - in: header
          name: Connection
          schema:
            type: string
            enum:
              - Upgrade
          description: Standard websocket request header.
        - in: header
          name: Upgrade
          schema:
            type: string
            format: base64
            enum:
              - websocket
          description: Standard websocket request header.
        - in: header
          name: Sec-Websocket-Key
          schema:
            type: string
            format: base64
          description: Standard websocket request header.
        - in: header
          name: Sec-Websocket-Version
          schema:
            type: integer
            enum:
              - 13
          description: Standard websocket request header.
      responses:
        '101':
          description: |
            Successful response - change to websocket protocol.
          headers:
            Sec-Websocket-Accept:
              schema:
                type: string
                format: base64
              description: Standard websocket upgrade response header.
            Upgrade:
              schema:
                type: string
                enum:
                  - websocket
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
  /api/internal/v1/deviceconnect/health:
    get:
      tags:
        - Device_connect_Internal API
      summary: Get health status of service
      operationId: DeviceConnect Internal Check Health
      responses:
        '204':
          description: Service is healthy.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconnect/alive:
    get:
      tags:
        - Device_connect_Internal API
      summary: Get service liveliness status.
      operationId: DeviceConnect Internal Check Liveliness
      responses:
        '204':
          description: Service is up and serving requests.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconnect/shutdown:
    get:
      tags:
        - Device_connect_Internal API
      summary: Shutdown the service.
      operationId: DeviceConnect Internal Shutdown
      responses:
        '202':
          description: The service started the graceful shutdown procedure.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconnect/tenants/{tenantId}:
    delete:
      operationId: Delete Tenant Data
      tags:
        - Device_connect_Internal API
      summary: Delete all the data for given tenant.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant.
      responses:
        '204':
          description: All the tenant data have been successfully deleted.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconnect/tenants/{tenantId}/devices:
    post:
      tags:
        - Device_connect_Internal API
      operationId: DeviceConnect Internal Provision device
      summary: Register a new device with the deviceconnect service.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant the device belongs to.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionDevice'
      responses:
        '201':
          description: Device was provisioned successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconnect/tenants/{tenantId}/devices/{deviceId}:
    delete:
      tags:
        - Device_connect_Internal API
      operationId: DeviceConnect Internal Decomission device
      summary: Remove a device from the deviceconnect service.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant the device belongs to.
        - in: path
          name: deviceId
          schema:
            type: string
          required: true
          description: ID of the target device.
      responses:
        '202':
          description: Device was deleted successfully
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconnect/tenants/{tenantId}/devices/{deviceId}/check-update:
    post:
      tags:
        - Device_connect_Internal API
      operationId: DeviceConnect Internal Check Update
      summary: Trigger check-update for the Mender client running on the device
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant the device belongs to.
        - in: path
          name: deviceId
          required: true
          schema:
            type: string
          description: ID for the target device.
      responses:
        '202':
          description: Accepted
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/deviceconnect/tenants/{tenantId}/devices/{deviceId}/send-inventory:
    post:
      tags:
        - Device_connect_Internal API
      operationId: DeviceConnect Internal Send Inventory
      summary: Trigger send-inventory for the Mender client running on the device
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant the device belongs to.
        - in: path
          name: deviceId
          required: true
          schema:
            type: string
          description: ID for the target device.
      responses:
        '202':
          description: Accepted
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/deviceconnect/devices/{id}:
    get:
      tags:
        - Device_connect_Management API
      operationId: DeviceConnect Management Get device
      summary: Fetch the state of a device.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the device.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionState'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/deviceconnect/devices/{id}/check-update:
    post:
      tags:
        - Device_connect_Management API
      operationId: DeviceConnect Management Check Update
      summary: Trigger check-update for the Mender client running on the device
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the device.
      responses:
        '202':
          description: Accepted
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/deviceconnect/devices/{id}/connect:
    get:
      tags:
        - Device_connect_Management API
      operationId: DeviceConnect Management Connect
      summary: Establish permanent connection with device
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the device.
        - in: header
          name: Connection
          schema:
            type: string
            enum:
              - Upgrade
          description: Standard websocket request header.
        - in: header
          name: Upgrade
          schema:
            type: string
            format: base64
            enum:
              - websocket
          description: Standard websocket request header.
        - in: header
          name: Sec-Websocket-Key
          schema:
            type: string
            format: base64
          description: Standard websocket request header.
        - in: header
          name: Sec-Websocket-Version
          schema:
            type: integer
            enum:
              - 13
          description: Standard websocket request header.
      responses:
        '101':
          description: |
            Successful response - change to websocket protocol.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/deviceconnect/devices/{id}/download:
    get:
      tags:
        - Device_connect_Management API
      operationId: DeviceConnect Management Download
      summary: Download a file from the device
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the device.
        - in: query
          name: path
          required: true
          schema:
            type: string
          description: Path of the file on the device.
      responses:
        '200':
          description: The content of the file will be returned in the response body
          headers:
            X-MEN-File-Path:
              schema:
                type: string
              description: The path of the file on the device
            X-MEN-File-UID:
              schema:
                type: integer
              description: The numerical UID of the file on the device
            X-MEN-File-GID:
              schema:
                type: integer
              description: The numerical GID of the file on the device
            X-MEN-File-Mode:
              schema:
                type: string
              description: The octal representation of the mode of the file on the device
            X-MEN-File-Size:
              schema:
                type: integer
              description: The size of the file on the device
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/deviceconnect/devices/{id}/send-inventory:
    post:
      tags:
        - Device_connect_Management API
      operationId: DeviceConnect Management Send Inventory
      summary: Trigger send-inventory for the Mender client running on the device
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the device.
      responses:
        '202':
          description: Accepted
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/deviceconnect/sessions/{session_id}/playback:
    get:
      tags:
        - Device_connect_Management API
      operationId: DeviceConnect Management Playback
      summary: Establish a connection for playing back a session
      parameters:
        - in: path
          name: session_id
          required: true
          schema:
            type: string
          description: ID for the session to play back.
        - in: query
          name: sleep_ms
          required: false
          schema:
            type: integer
          description: Time in millisconds to sleep between the subsequent playback data writes.
        - in: header
          name: Connection
          schema:
            type: string
            enum:
              - Upgrade
          description: Standard websocket request header.
        - in: header
          name: Upgrade
          schema:
            type: string
            format: base64
            enum:
              - websocket
          description: Standard websocket request header.
        - in: header
          name: Sec-Websocket-Key
          schema:
            type: string
            format: base64
          description: Standard websocket request header.
        - in: header
          name: Sec-Websocket-Version
          schema:
            type: integer
            enum:
              - 13
          description: Standard websocket request header.
      responses:
        '101':
          description: |
            Successful response - change to websocket protocol.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/deviceconnect/devices/{id}/upload:
    put:
      tags:
        - Device_connect_Management API
      operationId: DeviceConnect Management Upload
      summary: Upload a file to the device
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the device.
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FileUpload'
      responses:
        '201':
          description: The file was successfully uploaded
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/devices/v1/devicemonitor/alert:
    post:
      tags:
        - Device_monitor_Devices API
      operationId: DeviceAlertPost
      summary: Process alert messages from a device.
      description: HTTP POST to /alert endpoint originates from a device where a monitored entity reach a critical condition or switched from it to normal state. The JWT must be passed in the Authorization headers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Alert'
              minItems: 1
              maxItems: 128
      responses:
        '204':
          description: |
            The service processed the alert.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
  /api/devices/v1/devicemonitor/config:
    post:
      tags:
        - Device_monitor_Devices API
      operationId: Set Monitor Configuration
      summary: Store Monitor configuration from a device.
      description: Submit the current monitor configuration from the device. The JWT must be passed in the Authorization headers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DeviceMonitorConfiguration'
              minItems: 1
              maxItems: 128
      responses:
        '204':
          description: |
            The service saved given configuration data.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
  /api/internal/v1/devicemonitor/tenants/{tenantId}:
    delete:
      operationId: Device monitor Internal Delete Tenant
      tags:
        - Device_monitor_Internal API
      summary: Delete all the data for given tenant.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant.
      responses:
        '204':
          description: All the tenant data have been successfully deleted.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devicemonitor/tenants/{tenant_id}/devices:
    get:
      tags:
        - Device_monitor_Internal API
      operationId: List devices and their latest alerts
      summary: List the devices and their latest alerts.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
          description: Tenant ID.
        - name: id
          in: query
          description: Device ID filter. Can be repeated to query a set of devices.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: page
          in: query
          description: Results page number
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          required: false
          schema:
            type: integer
            default: 20
            maximum: 500
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonitorDevice'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devicemonitor/tenants/{tenant_id}/devices/{device_id}:
    delete:
      operationId: Delete Tenant Device
      tags:
        - Device_monitor_Internal API
      summary: Delete all data relating to the given device.
      parameters:
        - in: path
          name: tenant_id
          schema:
            type: string
          required: true
          description: ID of tenant.
        - in: path
          name: device_id
          schema:
            type: string
          required: true
          description: ID of device.
      responses:
        '204':
          description: All the device data has been successfully deleted.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/devicemonitor/tenants/{tenant_id}/devices/{device_id}/alerts/latest:
    get:
      tags:
        - Device_monitor_Internal API
      operationId: Device monitor Internal List latest alerts
      summary: List the latest alerts for the given device. An optional 'level_from' parameter filters the result by returning alerts with at least 'level_from' or higher severity level.
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID.
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
          description: Tenant ID.
        - name: level_from
          in: query
          required: false
          schema:
            type: string
            enum:
              - OK
              - CRITICAL
            default: CRITICAL
          description: Filter the result by having `level_from` or higher severity level.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alert'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/devicemonitor/devices/{id}/alerts:
    get:
      tags:
        - Device_monitor_Management API
      operationId: List Alerts
      summary: List the alerts for the given device.
      parameters:
        - name: id
          in: path
          required: true
          description: Device ID.
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: The requested page number.
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          description: The number of items per page.
          schema:
            type: integer
            default: 20
        - name: issued_before
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter alerts issued before timestamp.
        - name: issued_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter alerts issued after timestamp.
        - name: sort_ascending
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
          description: Filter by ascending timestamp (reverse).
      responses:
        '200':
          description: OK
          headers:
            X-Total-Count:
              schema:
                type: integer
              description: The total number of alerts matching the query
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alert'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/devicemonitor/devices/{id}/alerts/latest:
    get:
      tags:
        - Device_monitor_Management API
      operationId: List latest alerts
      summary: List the latest alerts for the given device. An optional 'level_from' parameter filters the result by returning alerts with at least 'level_from' or higher severity level.
      parameters:
        - name: id
          in: path
          required: true
          description: Device ID.
          schema:
            type: string
        - name: level_from
          in: query
          required: false
          schema:
            type: string
            enum:
              - OK
              - CRITICAL
            default: CRITICAL
          description: Filter the result by having `level_from` or higher severity level.
        - name: issued_before
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Only show alerts older than `issued_before`.
        - name: issued_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Only show alerts older than `issued_after`.
        - name: page
          in: query
          required: false
          description: The requested page number.
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          description: The number of items per page.
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: |
            OK.
            Lists latest alerts sorted by oldest alert first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alert'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/devicemonitor/devices/{id}/config:
    get:
      tags:
        - Device_monitor_Management API
      operationId: Monitor Checks Configuration
      summary: List the check configured on a device.
      parameters:
        - name: id
          in: path
          required: true
          description: Device ID.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonitorConfiguration'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/devicemonitor/settings/global/channel/alerts/{name}/status:
    put:
      tags:
        - Device_monitor_Management API
      operationId: Toggle Channel Mute
      summary: Enable or disable the named alert channel for all users.
      parameters:
        - name: name
          in: path
          required: true
          description: Channel name
          schema:
            type: string
            enum:
              - email
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                  description: Enable/disable channel
      responses:
        '204':
          description: Update successful (no content)
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/devices/v1/inventory/device/attributes:
    put:
      tags:
        - Device_inventory_Device API
      summary: Replace the set of attributes for a device
      description: |
        Replaces the attribute set for the authenticated device with the provided one.
        The device ID is retrieved from the authorization header.

        This method replaces all the attributes with the new set:

        * attributes not provided in the set are removed from the db

        * the values of existing attributes are overwritten

        * attributes assigned for the first time are automatically created
      operationId: Replace Attributes
      requestBody:
        description: A list of attribute descriptors.
        content:
          application/json:
            schema:
              title: ListOfAttributes
              type: array
              example:
                - name: ip_addr
                  value: 1.2.3.4
                  description: IP address
                - name: mac_addr
                  value: 00.01:02:03:04:05
                  description: MAC address
              items:
                $ref: '#/components/schemas/Attribute'
        required: true
      responses:
        '200':
          description: Attributes were uploaded successfully.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
    patch:
      tags:
        - Device_inventory_Device API
      summary: Assign a set of attributes for a device
      description: |
        Saves the provided attribute set for the authenticated device.
        The device ID is retrieved from the authorization header.

        This method has upsert semantics:

        * the values of existing attributes are overwritten

        * attributes assigned for the first time are automatically created
      operationId: Assign Attributes
      requestBody:
        description: A list of attribute descriptors.
        content:
          application/json:
            schema:
              title: ListOfAttributes
              type: array
              example:
                - name: ip_addr
                  value: 1.2.3.4
                  description: IP address
                - name: mac_addr
                  value: 00.01:02:03:04:05
                  description: MAC address
              items:
                $ref: '#/components/schemas/Attribute'
        required: true
      responses:
        '200':
          description: Attributes were uploaded successfully.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - DeviceJWT: []
  /api/internal/v1/inventory/health:
    get:
      tags:
        - Device_inventory_Internal API
      summary: Check the health of the service
      operationId: Inventory Internal Check Health
      responses:
        '204':
          description: |
            Service is healthy and all dependencies are up and running.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: |
            Service unhealthy / not ready to accept traffic. At least one dependency is not running.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              example:
                error: 'error reaching MongoDB: context deadline exceeded'
                request_id: ffd712be-d697-4cb7-814b-88ff1e2eb5f6
  /api/internal/v1/inventory/alive:
    get:
      tags:
        - Device_inventory_Internal API
      summary: |
        Trivial endpoint that unconditionally returns an empty 200 response whenever the API handler is running correctly.
      operationId: Inventory Internal Check Liveliness
      responses:
        '204':
          description: Service is up and running.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants:
    post:
      tags:
        - Device_inventory_Internal API
      summary: Create tenant
      description: |
        Create a tenant with provided configuration.
      operationId: Inventory Internal Create Tenant
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/TenantNew'
        required: true
      responses:
        '201':
          description: The tenant was created successfully.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants/{tenant_id}/devices:
    post:
      tags:
        - Device_inventory_Internal API
      summary: Create a device resource with the supplied set of attributes
      operationId: Initialize Device
      parameters:
        - name: tenant_id
          in: path
          description: ID of given tenant.
          required: true
          schema:
            type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/DeviceNew'
        required: true
      responses:
        '201':
          description: The device was successfully created.
          headers:
            Location:
              description: URI for the newly created 'Device' resource.
              schema:
                type: string
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants/{tenant_id}:
    delete:
      tags:
        - Device_inventory_Internal API
      summary: Removes all data belonging to a tenant
      operationId: Delete tenant specific data
      parameters:
        - name: tenant_id
          in: path
          description: ID of given tenant.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Tenant data was removed successfuly.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants/{tenant_id}/devices/{device_id}:
    delete:
      tags:
        - Device_inventory_Internal API
      summary: Remove a device from the inventory service
      operationId: Delete Device
      parameters:
        - name: tenant_id
          in: path
          description: ID of given tenant.
          required: true
          schema:
            type: string
        - name: device_id
          in: path
          description: ID of given device.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Device removed
          content: {}
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants/{tenant_id}/devices/status/{status}:
    post:
      tags:
        - Device_inventory_Internal API
      summary: Update the status of a list of devices
      description: |
        An API end-point that allows to bulk update the status of a list
        of devices.
      operationId: Update Status of Devices
      parameters:
        - name: tenant_id
          in: path
          description: ID of given tenant.
          required: true
          schema:
            type: string
        - name: status
          in: path
          description: New status to set for the specified devices.
          required: true
          schema:
            type: string
      requestBody:
        description: List of devices.
        content:
          '*/*':
            schema:
              type: array
              description: A list of devices to update.
              example:
                - id: ff8f7099-d842-42f2-9d5b-46a9ad13f90a
                  revision: 3
                - id: 80f3ad8f-40f2-429a-8931-b47cebbbe9b3
                  revision: 5
              items:
                $ref: '#/components/schemas/DeviceUpdate'
        required: true
      responses:
        '200':
          description: The operation completed successfully.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants/{tenant_id}/device/{device_id}/attribute/scope/{scope}:
    patch:
      tags:
        - Device_inventory_Internal API
      summary: Update multiple inventory attributes in a single scope for a device
      description: |
        An API end-point that allows to  update the inventory attributes in
        a single scope for a device.
      operationId: Update Inventory for a Device
      parameters:
        - name: If-Unmodified-Since
          in: header
          description: Skips updating the device if modified after the given RFC1123 timestamp.
          required: false
          schema:
            type: string
        - name: tenant_id
          in: path
          description: ID of given tenant.
          required: true
          schema:
            type: string
        - name: device_id
          in: path
          description: ID of given device.
          required: true
          schema:
            type: string
        - name: scope
          in: path
          description: Scope of the inventory attributes.
          required: true
          schema:
            type: string
      requestBody:
        description: List of inventory attributes to set.
        content:
          '*/*':
            schema:
              type: array
              description: A list of attribute descriptors.
              items:
                $ref: '#/components/schemas/Attribute'
        required: true
      responses:
        '200':
          description: Device inventory successfully updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '412':
          description: 'Precondition failed: If-Unmodified-Since condition not met'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants/{tenant_id}/device/{device_id}/attributes:
    patch:
      tags:
        - Device_inventory_Internal API
      summary: Update multiple inventory attributes for a device
      description: |
        An API end-point that allows to update the inventory attributes for a device.
        It is operating in the same way as the /attribute/scope/{scope} endpoint, but
        does not override the scope of the attributes that you provide.
      operationId: Update Inventory for a Device Scope Wise
      parameters:
        - name: If-Unmodified-Since
          in: header
          description: Skips updating the device if modified after the given RFC1123 timestamp.
          required: false
          schema:
            type: string
        - name: tenant_id
          in: path
          description: ID of given tenant.
          required: true
          schema:
            type: string
        - name: device_id
          in: path
          description: ID of given device.
          required: true
          schema:
            type: string
      requestBody:
        description: List of inventory attributes to set.
        content:
          '*/*':
            schema:
              type: array
              description: A list of attribute descriptors.
              items:
                $ref: '#/components/schemas/Attribute'
        required: true
      responses:
        '200':
          description: Device inventory successfully updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '412':
          description: 'Precondition failed: If-Unmodified-Since condition not met'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants/{tenant_id}/devices/{device_id}/groups:
    get:
      tags:
        - Device_inventory_Internal API
      summary: Get a list of groups the device belongs to
      operationId: Get Device Groups
      parameters:
        - name: tenant_id
          in: path
          description: ID of given tenant.
          required: true
          schema:
            type: string
        - name: device_id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Groups'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants/{tenant_id}/test/devices/groups:
    post:
      tags:
        - Device_inventory_Internal API
      summary: Check if devices belongs to given groups
      description: |
        An API end-point that allows to check if devices belongs to certain groups.
      operationId: Check if devices belongs to given groups
      parameters:
        - name: tenant_id
          in: path
          description: ID of given tenant.
          required: true
          schema:
            type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/DevicesInGroupsReq'
        required: true
      responses:
        '200':
          description: All the devices belong to given groups.
          content: {}
        '404':
          description: Not all the devices belong to given groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/inventory/tenants/{tenant_id}/devices/{device_id}/reindex:
    post:
      tags:
        - Device_inventory_Internal API
      summary: Start reindexing device attributes.
      operationId: Start Re-indexing
      parameters:
        - name: service
          in: query
          description: The name of the calling service.
          schema:
            type: string
        - name: device_id
          in: path
          description: ID of the device that needs reindexing.
          required: true
          schema:
            type: string
        - name: tenant_id
          in: path
          description: ID of tenant owning the device.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Attributes have been re-indexed.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v2/inventory/tenants/{tenant_id}/filters/search:
    post:
      tags:
        - Device_inventory_filters_and_search_Internal API
      summary: Search device inventories based on attributes
      description: |
        Returns a paged collection of devices and their attributes.

        It accepts optional filters and sort parameters as body parameters.
      operationId: Inventory Internal V2 Search Device Inventories
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        description: The search and sort parameters of the filter
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  description: Starting page.
                per_page:
                  type: integer
                  description: Number of results per page.
                device_ids:
                  type: array
                  description: List of device IDs
                  items:
                    type: string
                    description: Attribute filter predicate
                text:
                  type: string
                  description: Free-text search query
                filters:
                  type: array
                  description: List of filter predicates, chained with boolean AND operators to build the search condition definition.
                  items:
                    $ref: '#/components/schemas/FilterPredicate'
                sort:
                  type: array
                  description: List of ordered sort criterias
                  items:
                    $ref: '#/components/schemas/SortCriteria'
                attributes:
                  type: array
                  description: List of attributes to select and return
                  items:
                    $ref: '#/components/schemas/SelectAttribute'
        required: false
      responses:
        '200':
          description: Successful response.
          headers:
            X-Total-Count:
              description: Custom header indicating the total number of devices for the given query parameters
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfDevices
                type: array
                items:
                  $ref: '#/components/schemas/DeviceInventory'
              example:
                - id: 291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e
                  attributes:
                    - name: ip_addr
                      scope: inventory
                      value: 1.2.3.4
                      description: IP address
                    - name: mac_addr
                      scope: inventory
                      value: 00.01:02:03:04:05
                      description: MAC address
                  updated_ts: '2016-10-03T16:58:51.639Z'
                - id: 76f40e5956c699e327489213df4459d1923e1a806603def19d417d004a4a3ef
                  attributes:
                    - name: mac
                      scope: inventory
                      value: '00:01:02:03:04:05'
                      description: MAC address
                  updated_ts: '2016-10-04T18:24:21.432Z'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v2/tenants/{tenant_id}/filters/{id}:
    get:
      tags:
        - Device_inventory_filters_and_search_Internal API
      summary: Return the definition of a saved filter
      description: |
        Returns the definition of a saved filter from its unique identifier.
      operationId: Internal V2 Show Filter
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: Filter identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          description: The filter was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/inventory/devices:
    get:
      tags:
        - Device_inventory_Management API
      summary: List devices inventories
      description: |
        Returns a paged collection of devices and their attributes.
        Accepts optional search and sort parameters.

        **Searching**<br/>
        Searching by attributes values is accomplished by appending attribute
        filters in the form `{scope}/{name}={value}` to the query string.

        Supported values for scope are:
          * __inventory__: Attributes reported by the device.
          * __system__: Attributes populated by the mender-server.
          * __identity__: Device's identity attributes provided in the device's auth request.
          * __monitor__: Attributes populated by the monitoring add-on.
          * __tags__: User-defined attributes associated with the device.

        Using an unsupported value for __scope__ will produce no results from this API except
        when no scope is present, in which case scope defaults to inventory.

        Examples:
        ```
        # Search for devices with inventory attribute `attr_name_1` and tag attribute `attr_name_2`
        GET /devices?inventory/attr_name_1=foo&tags/attr_name_2=100

        # Search devices by attribute without scope (inventory scope is used)
        GET /devices?attr_name_1=foo
        ```
      operationId: List Device Inventories
      parameters:
        - name: page
          in: query
          description: Starting page.
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          description: |
            Sort devices by attribute.
            The parameter is formatted as a comma-separated list of attribute
            names and sort order.

            The order direction (`ord`) must be either `asc` or `desc` for
            ascending and descending respectively.
            Defaults to `desc` if not specified.

            For example: `?sort=attr1:asc,attr2:desc`
            will sort by 'attr1' ascending, and then by 'attr2' descending.
          schema:
            type: string
            format: attr[:ord][,attr[:ord]...]
        - name: has_group
          in: query
          description: Limit result to devices assigned to a group.
          schema:
            type: boolean
        - name: group
          in: query
          description: Limits result to devices in the given group.
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of devices found
              schema:
                type: string
            Link:
              description: |
                Standard page navigation header, supported relations: 'first', 'next', and 'prev'.
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfDevices
                type: array
                items:
                  $ref: '#/components/schemas/DeviceInventoryV1'
              example:
                - id: 291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e
                  attributes:
                    - name: ip_addr
                      scope: inventory
                      value: 1.2.3.4
                      description: IP address
                    - name: mac_addr
                      scope: inventory
                      value: 00.01:02:03:04:05
                      description: MAC address
                  updated_ts: '2016-10-03T16:58:51.639Z'
                - id: 76f40e5956c699e327489213df4459d1923e1a806603def19d417d004a4a3ef
                  attributes:
                    - name: mac
                      scope: inventory
                      value: '00:01:02:03:04:05'
                      description: MAC address
                  updated_ts: '2016-10-04T18:24:21.432Z'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/inventory/devices/{id}:
    get:
      tags:
        - Device_inventory_Management API
      summary: Get a selected device's inventory
      operationId: Get Device Inventory
      parameters:
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response - the device was found.
          headers:
            ETag:
              description: |
                Contains the device object's current ETag.
                Applicable only to attributes with 'tags' scope, changing other attributes doesn't affect the ETag.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceInventoryV1'
              example:
                id: 291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e
                attributes:
                  - name: ip_addr
                    scope: inventory
                    value: 1.2.3.4
                    description: IP address
                  - name: mac_addr
                    scope: inventory
                    value: 00.01:02:03:04:05
                    description: MAC address
                  - name: environment
                    scope: tags
                    value: test
                    description: Test environment
                    timestamp: '2016-10-19T17:23:01.639Z'
                updated_ts: '2016-10-03T16:58:51.639Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    delete:
      tags:
        - Device_inventory_Management API
      summary: Remove selected device's inventory
      operationId: Delete Device Inventory
      parameters:
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Device removed
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/inventory/devices/{id}/tags:
    put:
      tags:
        - Device_inventory_Management API
      summary: Replace the set of tags for a device
      description: |
        Replaces the tags associated to the device.

        This method replaces all the tags with the new set:
        * it removes from the db the attributes not provided
        * it overwrites the values of existing attributes
        * it creates attributes assigned for the first time
      operationId: Assign Tags
      parameters:
        - name: If-Match
          in: header
          description: Contains the device object's current ETag, and performs the update only if it matches the one stored in the database.
          schema:
            type: string
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
      requestBody:
        description: A list of tags descriptors.
        content:
          application/json:
            schema:
              title: ListOfTags
              type: array
              example:
                - name: location
                  value: germany
                  description: Germany region
                - name: environment
                  value: test
              items:
                $ref: '#/components/schemas/Tag'
        required: true
      responses:
        '200':
          description: Tags were updated successfully.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          description: ETag doesn't match.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    patch:
      tags:
        - Device_inventory_Management API
      summary: Adds a set of tags for a device
      description: |
        Saves the provided tags set for the authenticated device.

        This method has upsert semantic:
        * it overwrites the values of existing attributes
        * it creates attributes assigned for the first time
      operationId: Add Tags
      parameters:
        - name: If-Match
          in: header
          description: Contains the device object's current ETag, and performs the update only if it matches the one stored in the database.
          schema:
            type: string
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
      requestBody:
        description: A list of tag descriptors.
        content:
          application/json:
            schema:
              title: ListOfTags
              type: array
              example:
                - name: location
                  value: germany
                  description: Germany region
                - name: environment
                  value: test
              items:
                $ref: '#/components/schemas/Tag'
        required: true
      responses:
        '200':
          description: Tags were updated successfully.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          description: ETag doesn't match.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/inventory/devices/{id}/group:
    get:
      tags:
        - Device_inventory_Management API
      summary: Get a selected device's group
      operationId: Get Device Group
      parameters:
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful response. If the device is not assigned to any group, the 'group' field will be set to 'null'.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    put:
      tags:
        - Device_inventory_Management API
      summary: Add a device to a group
      description: |
        Adds a device to a group.

        Note that a given device can belong to at most one group.
        If a device already belongs to some group, it will be moved
        to the selected one.
      operationId: Assign Group
      parameters:
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
      requestBody:
        description: Group descriptor.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
        required: true
      responses:
        '204':
          description: Success - the device was added to the group.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/inventory/devices/{id}/group/{name}:
    delete:
      tags:
        - Device_inventory_Management API
      summary: Remove a device from a group
      description: |
        Removes the device with identifier 'id' from the group 'group'.
      operationId: Clear Group
      parameters:
        - name: id
          in: path
          description: Device identifier.
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: Group name.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The device was successfully removed from the group.
          content: {}
        '404':
          description: The device was not found or doesn't belong to the group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/inventory/groups:
    get:
      tags:
        - Device_inventory_Management API
      summary: List all groups existing device groups
      operationId: List Groups
      parameters:
        - name: status
          in: query
          description: Show groups for devices with the given auth set status.
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  title: ListOfGroupNames
                  type: string
                  description: Group name
              example:
                - staging
                - testing
                - production
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/inventory/groups/{name}:
    delete:
      tags:
        - Device_inventory_Management API
      summary: Remove a device group
      description: |
        Removes a device group. This API provides a bulk alternative to
        DELETE /devices/{id}/group/{name} for managing device groups.
      operationId: Remove a Group
      parameters:
        - name: name
          in: path
          description: Group name.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                required:
                  - updated_count
                type: object
                properties:
                  updated_count:
                    type: integer
                    description: |
                      Number of devices for which the group was cleared sucessfully.
                description: |
                  JSON object listing how many devices were updated.
              example:
                updated_count: 2
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/inventory/groups/{name}/devices:
    get:
      tags:
        - Device_inventory_Management API
      summary: List the devices belonging to a given group
      operationId: Get Devices in Group
      parameters:
        - name: page
          in: query
          description: Starting page.
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          schema:
            type: integer
            default: 10
        - name: name
          in: path
          description: Group name.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Total-Count:
              description: Custom header indicating the total number of devices in the given group
              schema:
                type: string
            Link:
              description: Standard header, we support 'first', 'next', and 'prev'.
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfIDs
                type: array
                items:
                  type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    delete:
      tags:
        - Device_inventory_Management API
      summary: Clear devices' group
      description: |
        Removes a list of devices from the specified group.
      operationId: Remove Devices from Group
      parameters:
        - name: name
          in: path
          description: Group name.
          required: true
          schema:
            type: string
      requestBody:
        description: JSON list of device IDs to remove from the group.
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                required:
                  - updated_count
                type: object
                properties:
                  updated_count:
                    type: integer
                    description: |
                      Number of devices for which the group was cleared sucessfully.
                description: |
                  JSON object listing how many devices were updated.
              example:
                updated_count: 2
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    patch:
      tags:
        - Device_inventory_Management API
      summary: Add devices to group
      description: |
        Appends the list of devices in the request body to the given group.
        For devices already present in the group the operation has no effect.
      operationId: Add Devices to Group
      parameters:
        - name: name
          in: path
          description: Group name.
          required: true
          schema:
            type: string
      requestBody:
        description: JSON list of device IDs to append to the group.
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                required:
                  - matched_count
                  - updated_count
                type: object
                properties:
                  updated_count:
                    type: integer
                    description: |
                      Number of devices listed that changed group.
                  matched_count:
                    type: integer
                    description: |
                      Number of devices listed that matched a valid device id internally.
                description: |
                  JSON object listing how many devices were updated.
              example:
                updated_count: 2
                matched_count: 3
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/inventory/filters/attributes:
    get:
      tags:
        - Device_inventory_filters_and_search_Management API
      summary: Get the list of filterable inventory attributes
      description: |
        Returns a list of filterable inventory attributes.

        The list is sorted in descending order by the count of occurrences of the
        attribute in the inventory database, then in ascending order by scope and name.

        Limitations:
         * The API considers up to a sample of 5,000 devices when aggregating the number of attributes.
         * The API returns up to 500 unique attributes.
      operationId: Get filterable attributes
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                title: List of filter attributes
                type: array
                items:
                  $ref: '#/components/schemas/FilterAttribute'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/inventory/filters/search:
    post:
      tags:
        - Device_inventory_filters_and_search_Management API
      summary: Search devices based on inventory attributes
      description: |
        Returns a paged collection of devices and their attributes.

        If multiple filter predicates are specified, the filters are
        combined using boolean `and` operator.
      operationId: Inventory V2 Search Device Inventories
      requestBody:
        description: The search and sort parameters of the filter
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  default: 1
                  description: Starting page.
                per_page:
                  type: integer
                  default: 20
                  maximum: 500
                  description: Maximum number of results per page.
                text:
                  type: string
                  description: Free-text search query
                filters:
                  type: array
                  description: List of filter predicates.
                  items:
                    $ref: '#/components/schemas/FilterPredicate'
                sort:
                  type: array
                  description: List of ordered sort criteria
                  items:
                    $ref: '#/components/schemas/SortCriteria'
                attributes:
                  type: array
                  description: List of attributes to select and return
                  items:
                    $ref: '#/components/schemas/SelectAttribute'
        required: false
      responses:
        '200':
          description: Successful response.
          headers:
            X-Total-Count:
              description: Custom header indicating the total number of devices for the given query parameters
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfDevices
                type: array
                items:
                  $ref: '#/components/schemas/DeviceInventory'
              example:
                - id: 291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e
                  attributes:
                    - name: ip_addr
                      scope: inventory
                      value: 1.2.3.4
                      description: IP address
                    - name: mac_addr
                      scope: inventory
                      value: 00.01:02:03:04:05
                      description: MAC address
                  updated_ts: '2016-10-03T16:58:51.639Z'
                - id: 76f40e5956c699e327489213df4459d1923e1a806603def19d417d004a4a3ef
                  attributes:
                    - name: mac
                      scope: identity
                      value: '00:01:02:03:04:05'
                      description: MAC address
                  updated_ts: '2016-10-04T18:24:21.432Z'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/inventory/filters:
    get:
      tags:
        - Device_inventory_filters_and_search_Management API
      summary: List all the saved filters
      operationId: List Filters
      parameters:
        - name: page
          in: query
          description: Starting page.
          schema:
            type: number
            format: integer
            default: 1
        - name: per_page
          in: query
          description: Number of results per page.
          schema:
            type: number
            format: integer
            default: 20
      responses:
        '200':
          description: Successful response.
          headers:
            X-Total-Count:
              description: Custom header indicating the total number of saved filters for the given query parameters
              schema:
                type: string
            Link:
              description: |
                Standard header, used for page navigation.

                Supported relation types are 'first', 'next' and 'prev'.
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfFilters
                type: array
                items:
                  $ref: '#/components/schemas/Filter'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    post:
      tags:
        - Device_inventory_filters_and_search_Management API
      summary: Create a new saved filter from a filter definition
      operationId: Create Filter
      requestBody:
        description: The definition of the filter
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterDefinition'
        required: false
      responses:
        '201':
          description: The filter was successfully created.
          headers:
            Location:
              description: URL of the newly created filter.
              schema:
                type: string
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          description: A filter with the same name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v2/inventory/filters/{id}:
    get:
      tags:
        - Device_inventory_filters_and_search_Management API
      summary: Get the definition of a saved filter
      operationId: Show Filter
      parameters:
        - name: id
          in: path
          description: Filter identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    put:
      tags:
        - Device_inventory_filters_and_search_Management API
      summary: Update a saved filter
      operationId: Update Filter
      parameters:
        - name: id
          in: path
          description: Filter identifier.
          required: true
          schema:
            type: string
      requestBody:
        description: The definition of the filter
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterDefinition'
        required: false
      responses:
        '204':
          description: The filter was successfully updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    delete:
      tags:
        - Device_inventory_filters_and_search_Management API
      summary: Delete a saved filter
      operationId: Delete Filter
      parameters:
        - name: id
          in: path
          description: Filter identifier.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The filter was successfully deleted.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v2/inventory/filters/{id}/search:
    get:
      tags:
        - Device_inventory_filters_and_search_Management API
      summary: Search devices using saved filter
      operationId: Execute Filter
      parameters:
        - name: id
          in: path
          description: Filter identifier.
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: Starting page.
          schema:
            type: number
            format: integer
            default: 1
        - name: per_page
          in: query
          description: Number of results per page.
          schema:
            type: number
            format: integer
            default: 20
      responses:
        '200':
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of devices matched query.
              schema:
                type: string
            Link:
              description: |
                Standard header used for page navigation, page relations: 'first', 'next' and 'prev'.
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfDevices
                type: array
                items:
                  $ref: '#/components/schemas/DeviceInventory'
              example:
                - id: 291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e
                  attributes:
                    - name: ip_addr
                      scope: inventory
                      value: 1.2.3.4
                      description: IP address
                    - name: mac_addr
                      scope: inventory
                      value: 00.01:02:03:04:05
                      description: MAC address
                  updated_ts: '2016-10-03T16:58:51.639Z'
                - id: 76f40e5956c699e327489213df4459d1923e1a806603def19d417d004a4a3ef
                  attributes:
                    - name: mac
                      scope: inventory
                      value: '00:01:02:03:04:05'
                      description: MAC address
                  updated_ts: '2016-10-04T18:24:21.432Z'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v2/inventory/statistics:
    get:
      tags:
        - Device_inventory_filters_and_search_Management API
      summary: Get inventory statistics
      description: |
        The following statistics are currently supported:
        * Number of accepted and pending devices in each device tier
      operationId: Get Statistics
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                required:
                  - devices_by_status
                properties:
                  devices_by_status:
                    $ref: '#/components/schemas/DeviceStatusStatistics'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/internal/v1/iot-manager/health:
    get:
      tags:
        - IoT_Manager_Internal API
      summary: Get health status of service
      operationId: IoTManager Internal Check Health
      responses:
        '204':
          description: Service is healthy.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/iot-manager/alive:
    get:
      tags:
        - IoT_Manager_Internal API
      summary: Get service liveliness status.
      operationId: IoTManager Internal Check Liveliness
      responses:
        '204':
          description: Service is up and serving requests.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/iot-manager/tenants/{tenantId}/devices:
    post:
      tags:
        - IoT_Manager_Internal API
      operationId: IoTManager Internal Provision device
      summary: Register a new device with the deviceconfig service.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant the device belongs to.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewDevice'
        required: true
      responses:
        '202':
          description: The device provisioning event was accepted and will be processed asynchronously.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          description: A device with the same ID already exists in Iot Hub.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/iot-manager/tenants/{tenantId}:
    delete:
      tags:
        - IoT_Manager_Internal API
      operationId: IoTManager Internal Delete tenant
      summary: Delete all data belonging to a given tenant.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant to remove.
      responses:
        '204':
          description: The removal of tenant data was successful.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/iot-manager/tenants/{tenantId}/devices/{deviceId}:
    delete:
      tags:
        - IoT_Manager_Internal API
      operationId: IoTManager Internal Decommission device
      summary: Remove a device from Iot Hub.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant the device belongs to.
        - in: path
          name: deviceId
          schema:
            type: string
          required: true
          description: ID of the target device.
      responses:
        '202':
          description: The device decomissioning event was accepted and will be processed asynchronously.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/iot-manager/tenants/{tenantId}/bulk/devices/status/{status}:
    put:
      operationId: IoTManager Internal Update device statuses
      tags:
        - IoT_Manager_Internal API
      summary: Update device statuses in bulk.
      parameters:
        - in: path
          name: tenantId
          schema:
            type: string
          required: true
          description: ID of tenant the device belongs to.
        - in: path
          name: status
          schema:
            type: string
            enum:
              - accepted
              - noauth
              - pending
              - preauthorized
              - rejected
          required: true
          description: The status of the device
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: List of devices to update. Up to 100 devices can be processed per request.
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Device ID.
                required:
                  - id
        required: true
      responses:
        '202':
          description: The device status update bulk event was accepted and will be processed asynchronously.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/iot-manager/integrations:
    get:
      operationId: IoTManager Management List integrations
      summary: List all configured integrations
      tags:
        - IoT_Manager_Management API
      parameters:
        - name: page
          in: query
          description: Page number.
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Number of results per page.
          required: false
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: OK. Returns list of integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Integration'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    post:
      operationId: IoTManager Management Register integration
      summary: Register a new cloud integration
      tags:
        - IoT_Manager_Management API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Integration'
        required: true
      responses:
        '201':
          description: URL of the newly registered integration. Please note that the inventory webhook scope is supported in plans equal or above professional.
          headers:
            Location:
              description: URL of the newly registered integration.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/iot-manager/integrations/{id}:
    delete:
      operationId: IoTManager Management Remove integration
      summary: Remove a cloud integration
      tags:
        - IoT_Manager_Management API
      parameters:
        - name: id
          in: path
          description: Integration identifier.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Integration unregistered successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/iot-manager/integrations/{id}/credentials:
    put:
      operationId: IoTManager Management Set integration credentials
      summary: Replace the credentials associated with the integration.
      tags:
        - IoT_Manager_Management API
      parameters:
        - name: id
          in: path
          description: Integration identifier.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Credentials'
        required: true
      responses:
        '204':
          description: Credentials updated successfully.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/iot-manager/devices/{deviceId}:
    delete:
      operationId: IoTManager Management Unregister device integrations
      summary: Removes all associated cloud integrations for the device.
      description: Removes all associated cloud integrations for the device, but does not clean up any external state.
      tags:
        - IoT_Manager_Management API
      parameters:
        - name: deviceId
          in: path
          schema:
            type: string
          required: true
          description: The unique ID of the device.
      responses:
        '204':
          description: OK. Device successfully unregistered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceState'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/iot-manager/devices/{deviceId}/state:
    get:
      operationId: IoTManager Management Get Device States
      summary: Gets the desired and reported state of a device
      tags:
        - IoT_Manager_Management API
      parameters:
        - name: deviceId
          in: path
          schema:
            type: string
          required: true
          description: The unique ID of the device.
      responses:
        '200':
          description: OK. Returns device reported and desired states for all integrations.
          content:
            application/json:
              schema:
                type: object
                description: Mapping from integration ID to DeviceState objects for all applicable integrations.
                additionalProperties:
                  $ref: '#/components/schemas/DeviceState'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/iot-manager/devices/{deviceId}/state/{integrationId}:
    put:
      operationId: IoTManager Management Replace State
      summary: Replaces the (desired) cloud state of the device for the given integration
      tags:
        - IoT_Manager_Management API
      parameters:
        - name: deviceId
          in: path
          schema:
            type: string
          required: true
          description: The unique ID of the device.
        - name: integrationId
          in: path
          schema:
            type: string
          required: true
          description: The unique ID of the integration.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceState'
        required: true
      responses:
        '200':
          description: OK. Returns the updated device state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceState'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    get:
      operationId: IoTManager Management Get Device State
      summary: Gets the desired and reported state of a device from an integration
      tags:
        - IoT_Manager_Management API
      parameters:
        - name: deviceId
          in: path
          schema:
            type: string
          required: true
          description: The unique ID of the device.
        - name: integrationId
          in: path
          schema:
            type: string
          required: true
          description: The unique ID of the integration.
      responses:
        '200':
          description: OK. Returns device reported and desired state for the integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceState'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/iot-manager/events:
    get:
      operationId: IoTManager Management List events
      summary: List all stored events
      tags:
        - IoT_Manager_Management API
      parameters:
        - name: page
          in: query
          description: Page number.
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Number of results per page.
          required: false
          schema:
            type: integer
            default: 20
        - name: integration_id
          in: query
          schema:
            type: string
            format: uuid
          required: false
          description: The unique ID of the integration to get the events from.
      responses:
        '200':
          description: OK. Returns list of events.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/internal/v1/tenantadm/alive:
    get:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: |
        Trivial endpoint that unconditionally returns an empty 200 response whenever the API handler is running correctly.
      operationId: Check Liveliness
      responses:
        '204':
          description: |
            Service is up and running
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/tenantadm/health:
    get:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: Check the health of the service
      operationId: Tenantadm Internal Check Health
      responses:
        '204':
          description: |
            Service is healthy and all dependencies are up and running.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: |
            Service unhealthy / not ready to accept traffic. At least one dependency is not running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/internal/v1/tenantadm/tenants:
    get:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: List known tenants
      description: |
        Returns a paged collection of existing tenants.
      operationId: List Tenants
      parameters:
        - name: id
          in: query
          description: |
            Tenant ID filter. Matches if the tenant ID is equal to this string.
          schema:
            type: string
        - name: plan
          in: query
          description: |
            Tenant plan. Matches if the tenant plan is equal to this string.
          required: false
          schema:
            type: string
        - name: trial
          in: query
          description: |
            Matches if the tenant account is a trial account.
          required: false
          schema:
            type: boolean
        - name: q
          in: query
          description: |
            Tenant filter. Matches if the tenant ID is equal to this string, or tenant's name or tenant's admin username contain this string.
          schema:
            type: string
        - name: parent_tenant_id
          in: query
          description: |
            List children tenants belonging to the given tenant ID.
          schema:
            type: string
        - name: field
          in: query
          description: |
            If specified, the response will include tenant objects with field matching this string.
            You can specify multiple fields by setting field parameter multiple times in one query.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: page
          in: query
          description: Starting page.
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Successful response.
          headers:
            X-Total-Count:
              description: Total number of tenants matched query.
              schema:
                type: string
            Link:
              description: |
                Standard header, used for page navigation.

                Supported relation types are 'first', 'next' and 'prev'.
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfTenants
                type: array
                items:
                  $ref: '#/components/schemas/Tenant'
              example:
                - id: 507f191e810c19729de860ea
                  name: Acme
                  plan: os
                  tenant_token: jp+/TvhmkU60qifhk+cOAjBSFBjWy5rk
                - id: 507f1f77bcf86cd799439011
                  name: Foo Inc.
                  plan: professional
                  tenant_token: GowGfbYCV80qioiHA5CkqqQt8nVNJ21P
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/tenantadm/tenants/verify:
    post:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: Check the validity of a tenant token
      description: |
        Verifies the Tenant Token and returns the associated Tenant.
      operationId: Verify Tenant Token
      parameters:
        - name: Authorization
          in: header
          description: The tenant token in base64-encoded form.
          required: true
          schema:
            type: string
            format: Bearer [token]
      responses:
        '200':
          description: The token is valid. A tenant descriptor is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
              example:
                id: 507f191e810c19729de860ea
                name: Acme
                tenant_token: wGypZL/J5mDakDq1CjL2hCfNcF8zEYcz
        '401':
          description: Verification failed.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/tenantadm/tenants/{id}/status:
    put:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: Suspend/unsuspend tenant's account.
      description: |
        Changes the given tenant's suspension status. Valid statuses are:
        - 'suspended'
        - 'active'
      operationId: Set Account Status
      parameters:
        - name: id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        description: Target suspension status
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantStatus'
        required: true
      responses:
        '200':
          description: |
            The tenant was successfully (un)suspended.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/tenantadm/tenants/{tenant_id}:
    get:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: Obtain information about selected tenant
      operationId: Show Tenant
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
        - name: include_children
          in: query
          description: Boolean flag to include children tenants, if included will result in another db call quering all the tenants with parent tenant id set to the tenant in question.
          schema:
            type: boolean
      responses:
        '200':
          description: A tenant descriptor is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: Update tenant information
      description: |
        Update tenant information.
      operationId: Update Tenant
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        description: Updated tenant data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantUpdateInternal'
        required: true
      responses:
        '202':
          description: Tenant information updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: |
            The tenant cannot be updated becaues of a conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: Delete all the information belonging to a tenant
      operationId: Tenantadm Internal Delete Tenant
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: All the tenant data removed.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/tenantadm/tenants/{tenant_id}/children:
    post:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: Assign existing tenants as children to a service provider tenant
      operationId: Assign Tenants to Service Provider
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        description: The unique identifiers of the tenants to be assigned.
        content:
          application/json:
            schema:
              type: object
              properties:
                tenant_ids:
                  type: array
                  items:
                    type: string
        required: true
      responses:
        '204':
          description: Tenant successfully assigned to service provider.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: |
            The specified tenant is not a Service Provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: Delete all the information belonging to the children tenants of a Service Provider tenant
      operationId: Delete Tenant Children
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: All the tenant data removed.
          content: {}
        '409':
          description: |
            The specified tenant is not a Service Provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/tenantadm/tenants/{tenant_id}/children/{child_id}:
    delete:
      tags:
        - Tenants_APIs_Tenantadm Internal
      summary: Removing the parent reference in the child tenant.
      description: |
        Making the child tenant a standalone tenant by removing the parent reference.
      operationId: Delete Parent Reference
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
        - name: child_id
          in: path
          description: Child ID.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The parent reference is removed.
          content: {}
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/tenantadm/user/tenant:
    get:
      tags:
        - Tenants_APIs_Tenantadm Management
      summary: Obtain information about current tenant
      description: |
        The returned tenant resolves to the owner of the subject claim (user unique ID) in the JWT token.
      operationId: Tenant Info
      responses:
        '200':
          description: A tenant descriptor is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '401':
          description: Verification failed.
          content: {}
        '404':
          description: User is not a part of any tenant organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/billing:
    get:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Get billing information, such as the card stored as default payment method in stripe
      operationId: Get billing information
      responses:
        '200':
          description: Stripe stored card data is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInfo'
              example:
                card:
                  brand: Visa
                  checks:
                    address_line1_check: pass
                    address_postal_code_check: pass
                    cvc_check: pass
                  country: 'no'
                  description: ''
                  exp_month: 2
                  exp_year: 2020
                  fingerprint: fingerprint
                  funding: all
                  iin: ''
                  issuer: ''
                  last4: '1234'
                  three_d_secure_usage:
                    supported: true
                  wallet:
                    dynamic_last4: '6789'
                    type: visa_checkout
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/billing/card:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Generate a Stripe setup intent for collecting updated CC details via the UI.
      operationId: Init Card Update
      responses:
        '200':
          description: Stripe setup intent id and secret is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardSetupData'
              example:
                intent_id: seti_1HXHVn2eZvKYlo2CT3XEEjKB
                secret: TYooMQauvdEDq54NiTphI7jx
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Tenant is in invalid state; see error for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/billing/card/{id}/confirm:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Save the credit card collected using the given intent as the default card.
      operationId: Confirm Card Update
      parameters:
        - name: id
          in: path
          description: Setup intent ID obtained from POST /card.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: New credit card is saved as the default one.
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Setup intent is in invalid state; see error for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/billing/profile:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Register billing information.
      operationId: Register billing profile
      requestBody:
        description: The billing profile.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingProfile'
        required: true
      responses:
        '200':
          description: Billing profile registered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProfile'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    get:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Retrieve the billing information.
      operationId: Get billing profile
      responses:
        '200':
          description: The billing information for the account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProfile'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    patch:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Update billing information.
      operationId: Update billing profile
      requestBody:
        description: The updated billing information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingProfileUpdate'
        required: true
      responses:
        '200':
          description: The updated billing information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProfile'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/billing/subscription:
    post:
      x-mender-private: true
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Request changes to your subscription
      operationId: Change subscription
      requestBody:
        description: Subscription change request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
        required: true
      responses:
        '202':
          description: Request accepted and scheduled for processing
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Forbidden
          content: {}
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: 'billing for your account is not self-managed: please contact support'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    get:
      x-mender-private: true
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Get the current subscription details.
      operationId: Show subscription
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/billing/subscription/invoices/preview:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Preview an upcomming invoice
      description: |
        Requests a preview to view an upcomming invoice with an optional subscription change request.
        The SubscriptionRequest is optional.
      operationId: Preview invoice
      requestBody:
        description: Subscription preview request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewRequest'
        required: true
      responses:
        '200':
          description: Successfully rendered the preview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: No invoice could be generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/billing/secret:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Get stripe client secret, create if not exist.
      operationId: Get stripe secret
      responses:
        '200':
          description: Stripe client secret is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutData'
              example:
                secret: TYooMQauvdEDq54NiTphI7jx
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/contact/support:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Send message to Mender support
      description: |
        The message is free form; internally it will be auto-decorated with important metadata
        (organization id/name, user id/name, etc.).
      operationId: Contact Support
      requestBody:
        description: Support request data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupportRequest'
        required: true
      responses:
        '202':
          description: Message accepted.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/tenants:
    get:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: List the children Tenants associated with a Service Provider Tenant
      operationId: List Tenants v2
      parameters:
        - name: tiers
          in: query
          description: Flag to include tiers in the response.
          schema:
            type: string
            default: 'false'
        - name: page
          in: query
          description: Starting page.
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: List of tenants is returned
          headers:
            X-Total-Count:
              description: Total number of devices matched query.
              schema:
                type: string
            Link:
              description: |
                Standard header, used for page navigation.

                Supported relation types are 'first', 'next' and 'prev'.
              schema:
                type: string
          content:
            application/json:
              schema:
                title: ListOfTenants
                type: array
                items:
                  $ref: '#/components/schemas/Tenant'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Create a new Tenant associated with a Service Provider Tenant
      operationId: Create new Tenant
      requestBody:
        description: New Tenant
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTenant'
        required: true
      responses:
        '202':
          description: Request to create tenant was accepted
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '403':
          description: |
            Forbidden because the current tenant is not a service provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: |
            Tenant or admin user is duplicated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |
            Tenant limit for max child tenants exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/tenants/signup:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Create a new Account
      operationId: Sign up
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - email
                - g-recaptcha-response
                - organization
                - password
              type: object
              properties:
                organization:
                  type: string
                  description: Organization name (ASCII characters only, max 100 characters)
                email:
                  type: string
                  description: Email address (ASCII characters only)
                  format: email
                password:
                  type: string
                  description: Password
                g-recaptcha-response:
                  type: string
                  description: reCAPTCHA response
                name:
                  type: string
                  description: customer name
                subscription_type:
                  type: string
                  default: trial
                  enum:
                    - trial
                    - azure
                subscription_token:
                  type: string
                  description: |-
                    Subscription token is used to resolve the externally managed
                    subscription. The token is required if subscription_type is "azure".
                campaign:
                  type: string
                  description: Campaign
                ts:
                  type: integer
                  description: captcha timestamp
                  format: int32
        required: true
      responses:
        '202':
          description: Request to create organization was accepted
          headers:
            Location:
              description: URL to log in to the newly created organization.
              schema:
                type: string
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          description: |
            Recaptcha verififaction failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: |
            Endpoint disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: |
            Email is duplicated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v2/tenantadm/tenants/trial:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Create a trial organization
      operationId: Create Trial Account
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - email
                - g-recaptcha-response
                - organization
                - password
              type: object
              properties:
                organization:
                  type: string
                  description: Organization name (ASCII characters only, max 100 characters)
                email:
                  type: string
                  description: Email address (ASCII characters only)
                  format: email
                password:
                  type: string
                  description: Password
                g-recaptcha-response:
                  type: string
                  description: reCAPTCHA response
                name:
                  type: string
                  description: customer name
                plan:
                  type: string
                  description: customer plan
                  default: enterprise
                  enum:
                    - os
                    - professional
                    - enterprise
                campaign:
                  type: string
                  description: Campaign
                ts:
                  type: integer
                  description: captcha timestamp
                  format: int32
          application/json:
            schema:
              required:
                - email
                - g-recaptcha-response
                - organization
                - password
              type: object
              properties:
                organization:
                  type: string
                  description: Organization name (ASCII characters only, max 100 characters)
                email:
                  type: string
                  description: Email address (ASCII characters only)
                  format: email
                password:
                  type: string
                  description: Password
                g-recaptcha-response:
                  type: string
                  description: reCAPTCHA response
                name:
                  type: string
                  description: customer name
                plan:
                  type: string
                  description: customer plan
                  default: enterprise
                  enum:
                    - os
                    - professional
                    - enterprise
                campaign:
                  type: string
                  description: Campaign
                ts:
                  type: integer
                  description: captcha timestamp
                  format: int32
        required: true
      responses:
        '202':
          description: Request to create organization was accepted
          headers:
            Location:
              description: URL to log in to the newly created organization.
              schema:
                type: string
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          description: |
            Recaptcha verififaction failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: |
            Endpoint disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: |
            Email is duplicated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v2/tenantadm/tenants/{id}:
    delete:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Remove inactive tenant from the system.
      description: |
        Remove inactive tenant information from the system.
      operationId: Delete Inactive Account
      parameters:
        - name: id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Tenant removed.
          content: {}
        '403':
          description: |
            User token does not provide access to tenant with given Id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: |
            The tenant cannot be removed.
            Only inactive tenant can be removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/tenants/{id}/cancel:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Request the cancellation of a tenant
      description: |
        Requests the cancellation of a tenant.
      operationId: Cancel Account
      parameters:
        - name: id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        description: Cancellation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelRequest'
        required: true
      responses:
        '202':
          description: |
            Request has been successfully recorded.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '403':
          description: |
            User token does not provide access to tenant with given Id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The tenant is not active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/tenants/{id}/child:
    put:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Update a Tenant associated with a Service Provider Tenant
      operationId: Update Child Tenant
      parameters:
        - name: id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        description: Updated Tenant
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChildTenant'
        required: true
      responses:
        '204':
          description: Tenant updated.
          content: {}
        '403':
          description: |
            User token does not provide access to tenant with given Id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |
            Device limit for children tenants exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/tenants/{id}/plan:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Request the subscription plan/add-ons change
      description: |
        Request the subscription plan/add-ons change.
      operationId: Update Plan
      parameters:
        - name: id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        description: Plan change request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanChangeRequest'
        required: true
      responses:
        '202':
          description: |
            Request has been successfully recorded.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '403':
          description: |
            User token does not provide access to tenant with given Id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The tenant is not active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/tenants/{id}/remove/start:
    post:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Initialize the process of tenant removal.
      description: |
        Start the asynchronous process of removing tenant from the system.
      operationId: Init Tenant Removal
      parameters:
        - name: id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Request to cancel the tenant upgrade was accepted
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '403':
          description: |
            User token does not provide access to tenant with given Id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v2/tenantadm/tenants/{id}/status:
    put:
      tags:
        - Tenants_APIs_v2_Tenantadm Management v2
      summary: Activate tenant's account.
      description: |
        Changes the given tenant's suspension status to active.
        The only valid statuses is 'active'.
      operationId: Activate Account
      parameters:
        - name: id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        description: Target suspension status
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantStatus'
        required: true
      responses:
        '202':
          description: |
            Request to activate tenant was accepted.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '403':
          description: |
            User token does not provide access to tenant with given Id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The tenant was suspended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/internal/v1/useradm/health:
    get:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Check the health of the service
      operationId: Useradm Check Health
      responses:
        '204':
          description: |
            Service is healthy and all dependencies are up and running.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: |
            Service unhealthy / not ready to accept traffic. At least one dependency is not running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'error reaching MongoDB: context deadline exceeded'
                request_id: ffd712be-d697-4cb7-814b-88ff1e2eb5f6
  /api/internal/v1/useradm/alive:
    get:
      tags:
        - User_administration_and_authentication_Internal API
      summary: |
        Trivial endpoint that unconditionally returns an empty 200 response whenever the API handler is running correctly.
      operationId: Useradm Check Liveliness
      responses:
        '204':
          description: Service is up and running.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/auth/verify:
    post:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Check the validity of a token
      description: |
        Besides the basic validity check, checks the token expiration time and user-initiated token revocation.
        Services which intend to use it should be correctly set up in the gateway's configuration.
      operationId: Verify JWT
      parameters:
        - name: Authorization
          in: header
          description: The token in base64-encoded form.
          required: true
          schema:
            type: string
            format: Bearer [token]
        - name: X-Forwarded-Uri
          in: header
          description: |
            URI the original request was sent to, the URI is expected to have
            at least 4 components, eg. /api/management/1.0/foo/bar
          required: true
          schema:
            type: string
            format: HTTP path
        - name: X-Forwarded-Method
          in: header
          description: HTTP method used when accessing the original URI
          required: true
          schema:
            type: string
            enum:
              - GET
              - PUT
              - POST
              - DELETE
      responses:
        '200':
          description: The token is valid.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          description: Verification failed, authentication should not be granted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Token has expired - apply for a new one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/users:
    get:
      tags:
        - User_administration_and_authentication_Internal API
      summary: |
        List users matching the filtering conditions.
      operationId: List All Users
      parameters:
        - name: page
          in: query
          description: Results page number
          schema:
            type: number
            format: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          schema:
            maximum: 500
            type: number
            format: integer
            default: 20
        - name: id
          in: query
          description: |
            Limit result by user ID, can be repeated to include multiple users in the query.
          schema:
            type: string
        - name: tenant_id
          in: query
          description: |
            Limit result by tenant ID.
          schema:
            type: string
        - name: email
          in: query
          description: |
            Limit result by user email, can be repeated to include multiple users in the query.
          schema:
            type: string
        - name: sso_provider_id
          in: query
          description: |
            Filter by SSO provider ID. Must be a UUID or on the form oauth2/<provider>.
          schema:
            type: string
        - name: sso_subject
          in: query
          description: |
            Filter by SSO subject ID.
          schema:
            type: string
        - name: created_after
          in: query
          description: |
            Filter users created after timestamp (UNIX timestamp).
          schema:
            type: integer
        - name: created_before
          in: query
          description: |
            Filter users created before timestamp (UNIX timestamp).
          schema:
            type: integer
        - name: updated_after
          in: query
          description: |
            Filter users updated after timestamp (UNIX timestamp).
          schema:
            type: integer
        - name: updated_before
          in: query
          description: |
            Filter users updated before timestamp (UNIX timestamp).
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                title: ListOfUsers
                type: array
                items:
                  $ref: '#/components/schemas/UserWithTenantInfo'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/tenants:
    post:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Create a tenant with provided configuration.
      operationId: Useradm Create Tenant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantNew'
        required: true
      responses:
        '201':
          description: The tenant was created successfully.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/tenants/{tenant_id}/sso/assign:
    put:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Assigns the SSO to the tenant
      operationId: Assign tenant SSO
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID to asign the SSO to.
          required: true
          schema:
            type: string
      requestBody:
        description: Existing tenant ID to get the SSO configuration from.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantNew'
        required: true
      responses:
        '200':
          description: The SSO data was successfuly assigned, however there is additional message returned (for instance in case of replacement of existing configuration).
          content: {}
        '201':
          description: The SSO data was successfuly assigned.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/tenants/{tenant_id}:
    delete:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Deletes all the tenant data
      operationId: Useradm Internal Delete tenant data
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID to delete.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The tenant data was successfully deleted.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/tenants/{tenant_id}/users:
    get:
      tags:
        - User_administration_and_authentication_Internal API
      summary: |
        List all users registered under the tenant owning the JWT.
      operationId: List Users Internal
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
        - name: id
          in: query
          description: |
            Limit result by user ID, can be repeated to include multiple users in the query.
          schema:
            type: string
        - name: email
          in: query
          description: |
            Limit result by user email, can be repeated to include multiple users in the query.
          schema:
            type: string
        - name: created_after
          in: query
          description: |
            Filter users created after timestamp (UNIX timestamp).
          schema:
            type: integer
        - name: created_before
          in: query
          description: |
            Filter users created before timestamp (UNIX timestamp).
          schema:
            type: integer
        - name: updated_after
          in: query
          description: |
            Filter users updated after timestamp (UNIX timestamp).
          schema:
            type: integer
        - name: updated_before
          in: query
          description: |
            Filter users updated before timestamp (UNIX timestamp).
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                title: ListOfUsers
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Create user
      operationId: Create User Internal
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        description: New user data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserNewInternal'
        required: true
      responses:
        '201':
          description: The user was successfully created.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: |
            User name or ID is duplicated, or limit on maximum number of users has been exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/tenants/{tenant_id}/devices/{device_id}/users:
    get:
      tags:
        - User_administration_and_authentication_Internal API
      summary: |
        List users' email addresses of users with access to a given device.
      operationId: List Users' email addresses
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
        - name: device_id
          in: path
          description: Device ID.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Emails'
        '400':
          description: |
            Device id not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/tenants/{tenant_id}/users/{user_id}:
    delete:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Delete a user
      description: |
        Remove a user from the tenant.
      operationId: Delete User Internal
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
        - name: user_id
          in: path
          description: User ID.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User deleted.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/tokens:
    delete:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Delete all user tokens
      description: |
        This endpoint is designed to be used for tenant account suspension purpose.
        When only tenant_id parameter is set, tokens for all tenant users will be removed.
        It is also possible to remove tokens for user with given user_id by setting
        optional user_id parameter.
      operationId: Revoke User Tokens
      parameters:
        - name: tenant_id
          in: query
          description: Tenant ID.
          required: true
          schema:
            type: string
        - name: user_id
          in: query
          description: User ID.
          schema:
            type: string
      responses:
        '204':
          description: Tokens deleted.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/internal/v1/useradm/tenants/{tenant_id}/limits:
    get:
      tags:
        - User_administration_and_authentication_Internal API
      operationId: Get Tenant Limits Internal
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Limits'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Update information about tenant limits
      operationId: Update Tenant Limits
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Limits'
        required: true
      responses:
        '204':
          description: Limit information updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Remove limits from tenant
      operationId: Clear Tenant Limits
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Limits information deleted.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/tenants/{tenant_id}/plan_binding:
    get:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Get plan and limits information for given tenant
      operationId: Show Tenant Plan And Limits
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response - a plan information is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanBindingDetails'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Update information about tenant plan and limits
      operationId: Update Tenant Plan And Limits
      parameters:
        - name: tenant_id
          in: path
          description: Tenant ID.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanBinding'
        required: true
      responses:
        '204':
          description: Plan and limits information updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/internal/v1/useradm/users/{id}/assign:
    post:
      tags:
        - User_administration_and_authentication_Internal API
      summary: Assign tenants to a given user
      operationId: Assign Tenants Internal
      parameters:
        - name: id
          in: path
          description: User id or email to assign.
          required: true
          schema:
            type: string
      requestBody:
        description: tenantIdsData.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantIdsData'
        required: true
      responses:
        '200':
          description: User assigned.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/useradm/auth/login:
    post:
      tags:
        - User_Administration_Management API
      summary: Log in to Mender
      description: |
        Accepts user credentials via standard Basic Auth, and returns a
        JWT token to be used for authentication in subsequent requests.
      operationId: Login
      requestBody:
        description: Log in options
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginOptions'
        required: false
      responses:
        '200':
          description: |
            Authentication successful - a new JWT is issued and returned with content type application/jwt.
            The JWT is signed with the API's private key ('RS256' signing algorithm), and contains the following standard claims:
            * 'iss' - issuer
            * 'exp' - expiry date
            * 'sub' - unique, autogenerated user ID
            * 'scp' - 'mender.*', allows access to all APIs/methods.

            If the login process requires SSO, the content type will be application/json and the body will contain a JSON document containing the following properties:
            * 'id' - the SSO integration ID
            * 'kind' - the SSO kind, e.g., 'sso/saml' or 'sso/oidc'

            Example response: {"id": "1a97b53f-9b84-5048-8874-df01f4f58f78", "kind": "sso/saml"}
          content:
            application/jwt:
              schema:
                type: string
                example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzYxMTkxMzYsImlzcyI6Ik1lbmRlciIsInN1YiI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2MWNlN2E4NCIsInNjcCI6WyJtZW5kZXIuKiJdfQ.X7Ief4PhPLlR6mA2wh3G3K0Z2tud0rK1QJesxu52NfICSeARmlujczs-_1YZxMwI0s-HgpXHbXIjaSVK80BjxjAM1rqpRGvgqSqG-dU5KmglDpAaTr4VaJci3VFPlVUVTRpI7bfqNMnKZtjmOUAGwjvroDUwX1RwayEmms-efGI
            application/json:
              schema:
                type: string
                example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzYxMTkxMzYsImlzcyI6Ik1lbmRlciIsInN1YiI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2MWNlN2E4NCIsInNjcCI6WyJtZW5kZXIuKiJdfQ.X7Ief4PhPLlR6mA2wh3G3K0Z2tud0rK1QJesxu52NfICSeARmlujczs-_1YZxMwI0s-HgpXHbXIjaSVK80BjxjAM1rqpRGvgqSqG-dU5KmglDpAaTr4VaJci3VFPlVUVTRpI7bfqNMnKZtjmOUAGwjvroDUwX1RwayEmms-efGI
        '400':
          description: Bad request, see error message for details.
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: |
            The user is not authorized. There are two possible scenarios for that:
            * username/password do not match
            * token for two factor authentication (if enabled) was not correct
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Feature not available in your Plan.
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/UnavailableError'
      security:
        - Login: []
  /api/management/v1/useradm/auth/magic/{id}:
    get:
      tags:
        - User_Administration_Management API
      summary: Parses uuid referencing a one-time use, short lived magic token and logs a user in automatically
      operationId: Login using a magic link
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '307':
          description: |
            Authentication successful - a new JWT is issued and set as a cookie and
            a user redirect to the UI is returned.
          content: {}
        '401':
          description: |
            The user is not authorized. There are two possible scenarios for that:
            * the user may not have been initialized successfully
            * the tenant may not have been initialized successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/management/v1/useradm/auth/sso/{id}/acs:
    post:
      tags:
        - User_Administration_Management API
      summary: Parses signed and encrypted SAML SSO assertion data
      operationId: Submit assertion data
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - SAMLResponse
              type: object
              properties:
                SAMLResponse:
                  type: string
                  description: |
                    Base64 encoded XML assertion data.
        required: true
      responses:
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '403':
          description: |
            Request forbidden, possibly due to the feature not being available in the current Mender plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          description: |
            Endpoint does not support the provided Content-Type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |
            The metadata has not been uploaded yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
  /api/management/v1/useradm/auth/sso/{id}/login:
    get:
      tags:
        - User_Administration_Management API
      summary: Sets cookies and redirects to the Identity Provider for login
      operationId: Login via given Identity Provider
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '302':
          description: |
            The request body is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: |
            The metadata has not been uploaded yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/management/v1/useradm/auth/logout:
    post:
      tags:
        - User_Administration_Management API
      summary: Log out from Mender
      description: |
        Invalidates the JWT token of the current user.
      operationId: Logout
      responses:
        '202':
          description: |
            Request has been accepted and the JWT token has been invalidated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/auth/password-reset/start:
    post:
      tags:
        - User_Administration_Management API
      summary: Initiate a Password Reset request based on the provided email address
      description: |
        Starts a Password Reset request, sending an email to the user containing a unique, time-based hash which can be used to reset the password of the user.
      operationId: Initiate Password Reset Request
      requestBody:
        description: |
          Password Reset request, it includes the email address of the user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetRequest'
        required: false
      responses:
        '202':
          description: The request has been accepted.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '429':
          description: |
            Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/useradm/auth/password-reset/complete:
    post:
      tags:
        - User_Administration_Management API
      summary: Complete a Password Reset request
      description: |
        Complete a Password Reset request initiated by the `/auth/password-reset/start` end-point.
        Caller provides the secret hash received by email, and the new password of the user.
      operationId: Complete Password Reset Request
      requestBody:
        description: |
          Password Reset request, it includes the secret hash received by email, as well as the new password of the user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetCompletion'
        required: false
      responses:
        '202':
          description: The request has been accepted.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/useradm/auth/verify-email/start:
    post:
      tags:
        - User_Administration_Management API
      summary: Initiate an Email Verification request based on the provided email address
      description: |
        Starts an Email Verification request, sending an email to the user containing a unique, time-based hash which can be used to verify the email address of the user.
      operationId: Initiate Email Verification Request
      requestBody:
        description: |
          Email Verification request, it includes the email address of the user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailVerificationRequest'
        required: false
      responses:
        '202':
          description: The request has been accepted.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/useradm/auth/verify-email/complete:
    post:
      tags:
        - User_Administration_Management API
      summary: Complete an Email Verification procedure
      description: |
        Complete an Email Verification procedure initiated by the `/auth/verify-email/start` end-point.
        Caller provides the secret hash received by email.
      operationId: Complete Email Verification
      requestBody:
        description: |
          Email Verification request, it includes the secret hash received by email.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailVerificationCompletion'
        required: false
      responses:
        '204':
          description: The email address has been verified.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/useradm/auth/plan-verify:
    post:
      tags:
        - User_Administration_Management API
      summary: Check if the user has given or superior pricing plan associated
      description: |
        Checks if user is in the given plan, or a superior one
      operationId: Verify Plan
      parameters:
        - name: X-Mender-Required-Minimal-Plan
          in: header
          description: |
            Required minimal plan to complete the request
          required: true
          schema:
            type: string
        - name: X-Mender-Required-Addon
          in: header
          description: |
            Required add-on to complete the request
          required: true
          schema:
            type: string
      responses:
        '202':
          description: The required minimal plan matches the user plan
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: The required minimal plan doesn't match the user plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - Login: []
  /api/management/v1/useradm/oauth2/{provider}:
    get:
      tags:
        - User_Administration_Management API
      summary: Sign in using OAuth2.0
      operationId: Login OAuth2.0
      parameters:
        - name: provider
          in: path
          description: Provider ID
          required: true
          schema:
            type: string
            enum:
              - github
              - google
              - microsoft
      responses:
        '302':
          description: Redirection to the OAuth 2.0 provider's login page
          content: {}
        '404':
          description: The required OAuth 2.0 provider is not available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-mender-plan: []
  /api/management/v1/useradm/users:
    get:
      tags:
        - User_Administration_Management API
      summary: |
        List all users registered under the tenant owning the JWT.
      operationId: List Users Management
      parameters:
        - name: id
          in: query
          description: |
            Limit result by user ID, can be repeated to include multiple users in the query.
          schema:
            type: string
        - name: email
          in: query
          description: |
            Limit result by user email, can be repeated to include multiple users in the query.
          schema:
            type: string
        - name: created_after
          in: query
          description: |
            Filter users created after timestamp (UNIX timestamp).
          schema:
            type: integer
        - name: created_before
          in: query
          description: |
            Filter users created before timestamp (UNIX timestamp).
          schema:
            type: integer
        - name: updated_after
          in: query
          description: |
            Filter users updated after timestamp (UNIX timestamp).
          schema:
            type: integer
        - name: updated_before
          in: query
          description: |
            Filter users updated before timestamp (UNIX timestamp).
          schema:
            type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                title: ListOfUsers
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    post:
      tags:
        - User_Administration_Management API
      summary: |
        Create a new user under the tenant owning the JWT.
      operationId: Create User Management
      requestBody:
        description: New user data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserNew'
        required: true
      responses:
        '201':
          description: The user was successfully created.
          headers:
            Location:
              description: URI for the newly created 'User' resource.
              schema:
                type: string
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: |
            The email address is duplicated, password is too short, current password doesn't match or limit on maximum number of users has been exceeded.
            It is possible that the user with the given email address exists
            in a different organization. In this case Mender server will
            also produce an error because the email address has to be unique
            across all organizations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/users/exists:
    get:
      tags:
        - User_Administration_Management API
      summary: |
        Verify if a user with a given email address exists.
        This endpoint requires the ManageTenants RBAC permission set.
      operationId: Check User Existence
      parameters:
        - name: email
          in: query
          description: Email address to check.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response - returns a JSON containing a boolean 'exists'.
          content:
            application/json:
              schema:
                type: object
                properties:
                  exists:
                    type: boolean
                    description: True if the user exists.
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/users/{id}:
    get:
      tags:
        - User_Administration_Management API
      summary: Get user information
      operationId: Show User
      parameters:
        - name: id
          in: path
          description: User id.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response - a user information is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    put:
      tags:
        - User_Administration_Management API
      summary: Update user information
      operationId: Update User
      parameters:
        - name: id
          in: path
          description: User id.
          required: true
          schema:
            type: string
      requestBody:
        description: Updated user data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
        required: true
      responses:
        '204':
          description: User information updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: |
            The email address is duplicated, the password is too short
            or the user is trying to modify another user's password.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    delete:
      tags:
        - User_Administration_Management API
      summary: Remove user from the system
      operationId: Remove User
      parameters:
        - name: id
          in: path
          description: User id.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User removed.
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/users/me:
    get:
      tags:
        - User_Administration_Management API
      summary: Get user information
      operationId: Show Own User Data
      responses:
        '200':
          description: Successful response - a user information is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserWithTenantInfo'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    put:
      tags:
        - User_Administration_Management API
      summary: Update own user information
      operationId: Update Own User Data
      requestBody:
        description: Updated user data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OwnUserUpdate'
        required: true
      responses:
        '204':
          description: User information updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: |
            The email address is duplicated or the password is too short.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/users/{id}/2fa/enable:
    post:
      tags:
        - User_Administration_Management API
      summary: Enable 2FA authentication
      operationId: Enable 2FA
      parameters:
        - name: id
          in: path
          description: User id (use 'me' for authenticated user).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 2FA is enabled.
          content: {}
        '400':
          description: |
            Operation is invalid, see error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The user was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v1/useradm/users/{id}/2fa/disable:
    post:
      tags:
        - User_Administration_Management API
      summary: Disable 2FA authentication
      operationId: Disable 2FA
      parameters:
        - name: id
          in: path
          description: User id (use 'me' for authenticated user).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 2FA is disabled.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The user was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v1/useradm/users/{id}/assign:
    post:
      tags:
        - User_Administration_Management API
      summary: Assign tenants to a given user
      operationId: Assign Tenants
      parameters:
        - name: id
          in: path
          description: User id or email to assign.
          required: true
          schema:
            type: string
      requestBody:
        description: tenantIdsData.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantIdsData'
        required: true
      responses:
        '200':
          description: User assigned.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The user was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v1/useradm/roles:
    get:
      tags:
        - User_Administration_Management API
      summary: List existing roles
      description: |
        This endpoint is deprecated. Please use /api/management/v2/useradm/roles
        togheter with /api/management/v2/useradm/permission_sets instead.
      operationId: List Roles v1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                title: ListOfRoles
                type: array
                items:
                  $ref: '#/components/schemas/RoleV1'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: true
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    post:
      tags:
        - User_Administration_Management API
      summary: Create role
      description: |
        This endpoint is deprecated. Please use /api/management/v2/useradm/roles
        togheter with /api/management/v2/useradm/permission_sets instead.
      operationId: Create Role v1
      requestBody:
        description: New role data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleV1'
        required: true
      responses:
        '201':
          description: The role was successfully created.
          headers:
            Location:
              description: URI for the newly created 'Role' resource.
              schema:
                type: string
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: true
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v1/useradm/roles/{id}:
    get:
      tags:
        - User_Administration_Management API
      summary: Get role information
      description: |
        Returns role information.
        This endpoint is deprecated. Please use /api/management/v2/useradm/roles/{id}
        togheter with /api/management/v2/useradm/permission_sets/{id} instead.
      operationId: Show Role v1
      parameters:
        - name: id
          in: path
          description: Role id.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response - a role information is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleV1'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: The role was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: true
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    put:
      tags:
        - User_Administration_Management API
      summary: Update role description and list of permissions.
      description: |
        This endpoint is deprecated. Please use /api/management/v2/useradm/roles/{id}
        togheter with /api/management/v2/useradm/permission_sets/{id} instead.
      operationId: Update Role v1
      parameters:
        - name: id
          in: path
          description: Role id.
          required: true
          schema:
            type: string
      requestBody:
        description: Updated role data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleV1'
        required: true
      responses:
        '202':
          description: Role information updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: |
            The role does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: true
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    delete:
      tags:
        - User_Administration_Management API
      summary: Remove role from the system
      description: |
        This endpoint is deprecated. Please use /api/management/v2/useradm/roles/{id}
        togheter with /api/management/v2/useradm/permission_sets/{id} instead.
      operationId: Delete Role v1
      parameters:
        - name: id
          in: path
          description: Role id.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Role removed.
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: true
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v1/useradm/settings:
    get:
      tags:
        - User_Administration_Management API
      summary: Get global user settings
      operationId: Show User Settings
      responses:
        '200':
          description: Successful response - a user information is returned.
          headers:
            ETag:
              description: |
                Contains the device object's current ETag.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Settings'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    post:
      tags:
        - User_Administration_Management API
      summary: Set global user settings
      description: |
        Create global user settings or replace existing settings with provided object.
      operationId: Update User Settings
      parameters:
        - name: If-Match
          in: header
          description: Contains the settings' current ETag, and performs the update only if it matches the one stored in the database.
          schema:
            type: string
      requestBody:
        description: New user settings.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Settings'
        required: true
      responses:
        '201':
          description: User settings set.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: |
            The user has no access to authentication settings because of unverified email address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '412':
          description: ETag doesn't match.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/settings/me:
    get:
      tags:
        - User_Administration_Management API
      summary: Get user settings for the current user
      operationId: Show My User Settings
      responses:
        '200':
          description: Successful response - a user information is returned.
          headers:
            ETag:
              description: |
                Contains the device object's current ETag.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Settings'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    post:
      tags:
        - User_Administration_Management API
      summary: Set user settings for the current user
      description: |
        Create current user settings or replace existing settings with provided object.
      operationId: Update My User Settings
      parameters:
        - name: If-Match
          in: header
          description: Contains the settings' current ETag, and performs the update only if it matches the one stored in the database.
          schema:
            type: string
      requestBody:
        description: New user settings.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Settings'
        required: true
      responses:
        '201':
          description: User settings set.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '412':
          description: ETag doesn't match.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/2faqr:
    get:
      tags:
        - User_Administration_Management API
      summary: Get 2FA QR code
      operationId: Get 2FA QR code
      security:
        - ManagementJWT: []
      responses:
        '200':
          description: Successful response - a user information is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  qr:
                    type: string
                    description: The content of the QR code.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/useradm/2faverify:
    put:
      tags:
        - User_Administration_Management API
      summary: Verify the 2FA token
      operationId: Verify the 2FA token
      security:
        - ManagementJWT: []
      requestBody:
        description: The token
        content:
          application/json:
            schema:
              type: object
              properties:
                token2fa:
                  type: string
                  description: The 2FA token to verify.
        required: true
      responses:
        '202':
          description: Successful response - the verification was successful.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          description: The verification failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/management/v1/useradm/settings/tokens:
    get:
      tags:
        - User_Administration_Management API
      summary: Get user Personal Access Tokens
      operationId: List User Personal Access Tokens
      responses:
        '200':
          description: Endpoint returns a list of tokens.
          content:
            application/json:
              schema:
                title: ListOfTokens
                type: array
                items:
                  $ref: '#/components/schemas/PersonalAccessToken'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    post:
      tags:
        - User_Administration_Management API
      summary: Create new Personal Access Token
      description: |
        Create new Personal Access Token with given name and expiration.
      operationId: Create Personal Access Token
      requestBody:
        description: The token object.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonalAccessTokenRequest'
        required: true
      responses:
        '200':
          description: Token has been created.
          content:
            application/json:
              schema:
                type: string
                example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzYxMTkxMzYsImlzcyI6Ik1lbmRlciIsInN1YiI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2MWNlN2E4NCIsInNjcCI6WyJtZW5kZXIuKiJdfQ.X7Ief4PhPLlR6mA2wh3G3K0Z2tud0rK1QJesxu52NfICSeARmlujczs-_1YZxMwI0s-HgpXHbXIjaSVK80BjxjAM1rqpRGvgqSqG-dU5KmglDpAaTr4VaJci3VFPlVUVTRpI7bfqNMnKZtjmOUAGwjvroDUwX1RwayEmms-efGI
        '400':
          description: |
            The request body is malformed or expiration time is too big.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: |
            Personal Access Token with the same name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |
            Maximum number of Personal Acess Tokens reached for this user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/settings/tokens/{id}:
    delete:
      tags:
        - User_Administration_Management API
      summary: Revoke Personal Access Token
      operationId: Revoke Personal Access Token
      parameters:
        - name: id
          in: path
          description: Token identifier.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Token removed.
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/sso/idp/metadata/{id}:
    get:
      tags:
        - User_Administration_Management API
      summary: Get Identity Provider Metadata for the given id
      operationId: Get IDP SAML or OpenID Connect Metadata for the tenant
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Identity Provider Metadata retrieved successfully.
          content:
            application/json:
              schema:
                title: IdentityProviderMetadata
                type: string
        '403':
          description: |
            Request forbidden, possibly due to feature not being available in current Mender plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: |
            There is nothing to return under the given id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    put:
      tags:
        - User_Administration_Management API
      summary: Update SAML Metadata
      operationId: Update SAML Metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/samlmetadata+xml:
            schema:
              type: string
        required: true
      responses:
        '204':
          description: SAML Metadata updated successfully.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '403':
          description: |
            Request forbidden, possibly due to feature not being available in current Mender plan or read-only permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: |
            Given id was not associated with any Metadata object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: |
            Endpoint does not support the Content-Type provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    delete:
      tags:
        - User_Administration_Management API
      summary: Delete SAML or OpenID Connect Metadata
      operationId: Delete SAML or OpenID Connect Metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Request to delete the metadata was accepted
          content: {}
        '403':
          description: |
            Request forbidden, possibly due to feature not being available in current Mender plan or read-only permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: |
            Metadata with the given id was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/sso/idp/metadata:
    get:
      tags:
        - User_Administration_Management API
      summary: Get an array of SAML or OpenID Connect Metadata for the tenant
      operationId: Get SAML or OpenID Connect Metadata for the tenant
      responses:
        '200':
          description: SAML or OpenID Connect Metadata retrieved successfully.
          content:
            application/json:
              schema:
                title: ListOfMetadata
                type: array
                items:
                  $ref: '#/components/schemas/SAMLMetadata'
        '403':
          description: |
            Request forbidden, possibly due to feature not being available in current Mender plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
    post:
      tags:
        - User_Administration_Management API
      summary: Store SAML or OpenID Connect Metadata.
      description: |
        In both cases (SAML and OpenID Connect) we support the passing of the metadata URL
        which we will automatically query (via GET) and parse the response.
        Please note that in the case of OpenID Connect you have to pass the url via
        "well-known" field in json request, and in case of SAML you need to use xml
        element: "IdentityProviderUrl", for instance:
        "<IdentityProviderUrl>https://samltest.id/saml/idp</IdentityProviderUrl>".
      operationId: Post SAML, OpenID Connect Metadata, or URL point to them
      requestBody:
        content:
          application/samlmetadata+xml:
            schema:
              type: string
          application/json:
            schema:
              type: string
        required: true
      responses:
        '201':
          description: SAML or OpenID Connect Metadata stored successfully.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '403':
          description: |
            Request forbidden, possibly due to feature not being available in current Mender plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: |
            The tenant is managed by a Service Provider and the configuration cannot be changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: |
            Entity was too large to process.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: |
            Endpoint does not support the Content-Type provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/sso/sp/metadata/{id}:
    get:
      tags:
        - User_Administration_Management API
      summary: Get Service Provider Metadata for the given id
      operationId: Get Service Provider Metadata by id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Service Provider Metadata retrieved successfully.
          content:
            application/json:
              schema:
                title: ServiceProviderMetadata
                type: string
        '204':
          description: SAML or OpenID Connect Metadata was empty.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '403':
          description: |
            Request forbidden, possibly due to feature not being available in current Mender plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/limits:
    get:
      tags:
        - User_Administration_Management API
      summary: Obtain information about limits.
      operationId: Get Tenant Limits
      responses:
        '200':
          description: Usage statistics and limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Limits'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/plans:
    get:
      tags:
        - User_Administration_Management API
      summary: Get list of available plans
      operationId: List Plans
      parameters:
        - name: page
          in: query
          description: Starting page.
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          schema:
            maximum: 500
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response - list of plans is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plan'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/plan_binding:
    get:
      tags:
        - User_Administration_Management API
      summary: Get plan and limits information for current tenant
      operationId: Show Plan And Limits
      responses:
        '200':
          description: Successful response - a plan information is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanBindingDetails'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /api/management/v1/useradm/users/tenants/{id}/token:
    get:
      tags:
        - User_Administration_Management API
      summary: Issue a new JWT Token for the given tenant
      description: |
        Issue new JWT Token for given name and expiration.
      operationId: Issue Token
      parameters:
        - name: id
          in: path
          description: Tenant identifier.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Token has been created and returned.
          content:
            application/json:
              schema:
                type: string
                example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzYxMTkxMzYsImlzcyI6Ik1lbmRlciIsInN1YiI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2MWNlN2E4NCIsInNjcCI6WyJtZW5kZXIuKiJdfQ.X7Ief4PhPLlR6mA2wh3G3K0Z2tud0rK1QJesxu52NfICSeARmlujczs-_1YZxMwI0s-HgpXHbXIjaSVK80BjxjAM1rqpRGvgqSqG-dU5KmglDpAaTr4VaJci3VFPlVUVTRpI7bfqNMnKZtjmOUAGwjvroAwX1RwayEmms-efGI
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/UnavailableError'
      security:
        - ManagementJWT: []
  /api/management/v2/useradm/roles:
    get:
      tags:
        - User_Administration_v2_Management API
      summary: List existing roles
      operationId: List Roles
      parameters:
        - name: page
          in: query
          description: Results page number
          schema:
            type: number
            format: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          schema:
            maximum: 500
            type: number
            format: integer
            default: 20
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                title: ListOfRoles
                type: array
                items:
                  $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    post:
      tags:
        - User_Administration_v2_Management API
      summary: Create role
      operationId: Create Role
      requestBody:
        description: New role data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
        required: true
      responses:
        '201':
          description: The role was successfully created.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: |
            The role with the same name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v2/useradm/roles/{id}:
    get:
      tags:
        - User_Administration_v2_Management API
      summary: Get role information
      description: |
        Returns role information.
      operationId: Show Role
      parameters:
        - name: id
          in: path
          description: Role id.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response - a role information is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    put:
      tags:
        - User_Administration_v2_Management API
      summary: Update role description and list of permissions.
      operationId: Update Role
      parameters:
        - name: id
          in: path
          description: Role id.
          required: true
          schema:
            type: string
      requestBody:
        description: Updated role data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
        required: true
      responses:
        '200':
          description: Role information updated.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: |
            The role does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    delete:
      tags:
        - User_Administration_v2_Management API
      summary: Remove role from the system
      operationId: Delete Role
      parameters:
        - name: id
          in: path
          description: Role id.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Role removed.
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v2/useradm/permission_sets:
    get:
      tags:
        - User_Administration_v2_Management API
      summary: List existing permission sets
      operationId: List Permission Sets
      parameters:
        - name: page
          in: query
          description: Results page number
          schema:
            type: number
            format: integer
            default: 1
        - name: per_page
          in: query
          description: Maximum number of results per page.
          schema:
            maximum: 500
            type: number
            format: integer
            default: 20
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                title: ListOfPermissionSets
                type: array
                items:
                  $ref: '#/components/schemas/PermissionSet'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    post:
      tags:
        - User_Administration_v2_Management API
      summary: Create permission set.
      operationId: Create Permission Set
      requestBody:
        description: New permission set data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionSet'
        required: true
      responses:
        '201':
          description: The permission set was successfully created.
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: The permission set with the same name already exists..
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v2/useradm/permission_sets/{id}:
    get:
      tags:
        - User_Administration_v2_Management API
      summary: Get permission set information
      description: |
        Returns permission set information.
      operationId: Get Permission Set
      parameters:
        - name: id
          in: path
          description: Permission set id.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response - a permission set information is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionSet'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    put:
      tags:
        - User_Administration_v2_Management API
      summary: Update permission set.
      operationId: Update Permission Set
      parameters:
        - name: id
          in: path
          description: Permission set id.
          required: true
          schema:
            type: string
      requestBody:
        description: Updated permission set data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionSet'
        required: true
      responses:
        '200':
          description: Permission Set information updated.
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: The permission set was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
    delete:
      tags:
        - User_Administration_v2_Management API
      summary: Remove permission set from the system
      operationId: Delete Permission Set
      parameters:
        - name: id
          in: path
          description: Permission set id.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Permission set removed.
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
      x-mender-plan:
        - enterprise
  /api/management/v2/useradm/support/feedback/{form_id}:
    post:
      tags:
        - User_Administration_v2_Management API
      summary: Submit user feedback form
      operationId: User feedback
      parameters:
        - name: form_id
          in: path
          description: The form identifier
          required: true
          schema:
            type: string
            enum:
              - product
              - feat.ai
      requestBody:
        description: |
          User feedback form.
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/FeedbackProduct'
                - $ref: '#/components/schemas/FeedbackAI'
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: '#/components/schemas/FeedbackProduct'
                - $ref: '#/components/schemas/FeedbackAI'
        required: true
      responses:
        '204':
          description: Response recorded
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Response already recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - ManagementJWT: []
  /status:
    get:
      summary: Check if service API is alive and serving requests
      operationId: Workflows Check Liveliness
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
              example:
                status: ok
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
        - Workflows_other
  /health:
    get:
      summary: Check if service and all operational dependencies are healthy.
      operationId: Workflows Check Health
      responses:
        '204':
          description: Service is healthy.
          content: {}
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          description: Service is temporarily unavailable (currently unhealthy).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Workflows_other
  /api/v1/tenants/{id}:
    delete:
      summary: Delete all the data belonging to a given tenant
      description: |
        Removes all the jobs that have the given tenant id in input parameters.
      operationId: Delete tenant data
      parameters:
        - name: id
          in: path
          description: Tenant id to remove.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Tenant data removed
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
        - Workflows_other
  /api/v1/workflow/{name}:
    post:
      summary: Start a new workflow
      description: |
        Starts a new workflow given by the name path-parameter.
      operationId: Start Workflow
      parameters:
        - name: name
          in: path
          description: Workflow identifier.
          required: true
          schema:
            type: string
      requestBody:
        description: Contains the definition of the job to be started.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/InputParameter'
        required: true
      responses:
        '201':
          description: Workflow created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Workflows_other
  /api/v1/workflow/{name}/batch:
    post:
      summary: Start a batch of workflows
      description: |
        Starts a new workflow given by the name path-parameter.
      operationId: Start Batch Workflows
      parameters:
        - name: name
          in: path
          description: Workflow identifier.
          required: true
          schema:
            type: string
      requestBody:
        description: Contains the definition of the job to be started.
        content:
          application/json:
            schema:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/InputParameter'
        required: true
      responses:
        '201':
          description: Workflows created successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    error:
                      type: string
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Workflows_other
  /api/v1/workflow/{name}/{id}:
    get:
      summary: Gets the workflow status for the given id.
      description: |
        Gets the workflow status for the given workflow name and id provided
        by the path parameters.
      operationId: Workflow Status
      parameters:
        - name: name
          in: path
          description: Workflow identifier.
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: Job identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Workflows_other
  /api/v1/metadata/workflows:
    get:
      summary: Get all workflow definitions
      operationId: List Workflows
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Workflow'
      tags:
        - Workflows_other
    post:
      summary: Register a new workflow
      operationId: Register Workflow
      requestBody:
        description: Workflow definition.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Workflow'
        required: true
      responses:
        '201':
          description: Successful response.
          content: {}
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          $ref: '#/components/responses/ConflictError'
      tags:
        - Workflows_other
  /api/v1/jobs/{id}:
    get:
      summary: Gets the job for the given id.
      description: |
        Gets the job object for the given job id.
      operationId: Job Structure
      parameters:
        - name: id
          in: path
          description: Job identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobObject'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Workflows_other
components:
  responses:
    InternalServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not Found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidRequestError:
      description: Invalid Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ConflictError:
      description: Conflict.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnauthorizedError:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ForbiddenError:
      description: The user is not permitted to access the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Forbidden
            request_id: eed14d55-d996-42cd-8248-e806663810a8
    UnavailableError:
      description: Service is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: service unavailable
            request_id: eed14d55-d996-42cd-8248-e806663810a8
  schemas:
    Error:
      description: Error descriptor.
      example:
        error: error message
        request_id: f7881e82-0492-49fb-b459-795654e7188a
      properties:
        error:
          description: Description of the error.
          type: string
        request_id:
          description: Request ID (same as in X-MEN-RequestID header).
          type: string
      required:
        - error
      type: object
    ArtifactLink:
      description: URL for artifact file download.
      example:
        uri: http://mender.io/artifact.tar.gz.mender
        expire: '2016-10-29T10:45:34Z'
      properties:
        uri:
          type: string
        expire:
          format: date-time
          type: string
      required:
        - expire
        - uri
      type: object
    JobStatus:
      example:
        workflowName: workflowName
        id: id
        inputParameters:
          - name: key
            value: parameter
          - name: key
            value: parameter
        results:
          - cli:
              output: output
              exitCode: 0
              error: error
              command:
                - command
                - command
            request:
              body: body
              statusCode: 6
            response:
              headers:
                - headers
                - headers
              method: method
              body: body
              uri: uri
          - cli:
              output: output
              exitCode: 0
              error: error
              command:
                - command
                - command
            request:
              body: body
              statusCode: 6
            response:
              headers:
                - headers
                - headers
              method: method
              body: body
              uri: uri
        status: status
      properties:
        id:
          type: string
        workflowName:
          type: string
        inputParameters:
          items:
            $ref: '#/components/schemas/InputParameter'
          type: array
        status:
          type: string
        results:
          items:
            $ref: '#/components/schemas/TaskResult'
          type: array
      type: object
    InputParameter:
      example:
        name: key
        value: parameter
      properties:
        name:
          type: string
        value:
          type: string
      required:
        - name
        - value
      type: object
    TaskResult:
      example:
        cli:
          output: output
          exitCode: 0
          error: error
          command:
            - command
            - command
        request:
          body: body
          statusCode: 6
        response:
          headers:
            - headers
            - headers
          method: method
          body: body
          uri: uri
      properties:
        success:
          type: boolean
        cli:
          $ref: '#/components/schemas/TaskResultCLI'
        request:
          $ref: '#/components/schemas/TaskResultHTTPRequest'
        response:
          $ref: '#/components/schemas/TaskResultHTTPResponse'
      type: object
    TaskResultCLI:
      example:
        output: output
        exitCode: 0
        error: error
        command:
          - command
          - command
      properties:
        command:
          items:
            type: string
          type: array
        output:
          type: string
        error:
          type: string
        exitCode:
          type: integer
      type: object
    TaskResultHTTPRequest:
      example:
        body: body
        statusCode: 6
      properties:
        statusCode:
          type: integer
        body:
          type: string
      type: object
    TaskResultHTTPResponse:
      example:
        headers:
          - headers
          - headers
        method: method
        body: body
        uri: uri
      properties:
        uri:
          type: string
        method:
          type: string
        headers:
          items:
            type: string
          type: array
        body:
          type: string
      type: object
    TenantNew:
      type: object
      properties:
        tenant_id:
          type: string
          description: ID of new tenant.
      required:
        - tenant_id
    IdentityData:
      description: Device identity attributes, in the form of a JSON structure. The attributes are completely vendor-specific, the provided ones are just an example. In reference implementation structure contains vendor-selected fields, such as MACs, serial numbers, etc.
      type: object
      properties:
        mac:
          description: MAC address.
          type: string
        sku:
          description: Stock keeping unit.
          type: string
        sn:
          description: Serial number.
          type: string
      example:
        mac: '00:01:02:03:04:05'
        sku: My Device 1
        sn: SN1234567890
    AuthSet:
      type: object
      description: AuthSet describes the identity a device uses to authenticate with the Mender server.
      properties:
        id:
          type: string
          description: The unique ID of the authentication set.
        device_id:
          type: string
          description: The unique ID of the device the authentication set belongs.
        identity_data:
          $ref: '#/components/schemas/IdentityData'
        pubkey:
          type: string
          description: 'The device''s public key (PEM encoding). generated by the device or pre-provisioned by the vendor. Currently supported public algorithms are: RSA, Ed25519 and ECDSA P-256.'
        tier:
          type: string
          description: A device tier.
          enum:
            - standard
            - micro
            - system
        status:
          type: string
          description: Authorization status of the set.
        ts:
          type: string
          format: date-time
          description: The creation timestamp of the authentication set.
    ProvisionDevice:
      type: object
      properties:
        device_id:
          type: string
          format: uuid
          description: ID of the new device.
      required:
        - device_id
    TenantLimit:
      description: Tenant account limit.
      type: object
      properties:
        tenant_id:
          type: string
        current_value:
          type: integer
        limit:
          type: integer
      required:
        - tenant_id
        - current_value
        - limit
      example:
        tenant_id: 58be8208dd77460001fe0d78
        current_value: 42
        limit: 123
    Scope:
      type: string
      description: |
        The scope of the attribute.

        Scope is a string and acts as namespace for the attribute name.

        * __inventory__: Attributes reported by the device.
        * __system__: Attributes populated by the mender-server.
        * __identity__: Device's identity attributes provided in the device's auth request.
        * __monitor__: Attributes populated by the monitoring add-on.
        * __tags__: User-defined attributes associated with the device.
      enum:
        - system
        - identity
        - inventory
        - monitor
        - tags
    DeviceLimitTenant:
      description: Tenant device limits per tier.
      type: object
      properties:
        name:
          type: string
        tenant_id:
          type: string
        current_value:
          type: integer
        value:
          type: integer
      required:
        - name
        - tenant_id
        - current_value
        - value
      example:
        name: max_micro_devices
        current_value: 255
        value: 1024
        tenant_id: 69072e3c0d4f7bebcd5470b3
    DeviceLimitTenantPut:
      description: Device limit.
      type: object
      properties:
        name:
          type: string
        value:
          type: integer
      required:
        - name
        - value
      example:
        name: max_micro_devices
        value: 1024
    Actor:
      required:
        - id
        - type
      type: object
      properties:
        id:
          type: string
          description: |
            A unique identifier of the actor.
        type:
          type: string
          description: |
            The type of the actor.
          enum:
            - user
            - device
        email:
          type: string
          description: |
            The email address of the user.
        identity_data:
          type: string
          description: |
            The identity data of the device.
      description: |
        The actor may be a user or device.
        Depending on the type of the actor different information will be available.
    AuditlogsTenant:
      required:
        - id
      type: object
      properties:
        id:
          type: string
          description: The id of a tenant.
        name:
          type: string
          description: The name of a tenant.
        parent:
          type: string
          description: The id of a parent tenant.
      description: The tenant descriptor.
      example:
        id: 66e456ef8437e701abc42a9c
        name: Devel Tenant
        parent: 66e457193c5f69b99d74d2cb
    AuditlogsUser:
      required:
        - email
      type: object
      properties:
        email:
          type: string
          description: Email address of the user.
      description: User descriptor.
      example:
        email: user@acme.com
    Deployment:
      required:
        - artifact_name
        - name
      type: object
      properties:
        name:
          type: string
        artifact_name:
          type: string
      description: The deployment descriptor.
      example:
        name: production
        artifact_name: Application 0.0.1
    AuditlogsArtifact:
      required:
        - name
      type: object
      properties:
        name:
          type: string
      description: The artifact descriptor.
      example:
        name: artifact_name_1
    AuditlogsDevice:
      required:
        - identity_data
      type: object
      properties:
        id:
          type: string
          description: Device ID.
        identity_data:
          type: string
          description: Vendor-specific JSON representation of the device identity data (MACs, serial numbers, etc.).
      description: Device descriptor.
      example:
        id: e1ba5bee-c45d-11eb-887d-3fd47bdc3990
        identity_data: '{"mac_address": "2C:54:91:88:C9:E3", "sn": "1229224105105176"}'
    Object:
      required:
        - id
        - type
      type: object
      properties:
        id:
          type: string
          description: |
            A unique identifier of the object.
        type:
          type: string
          description: |
            The type of the object.
          enum:
            - tenant
            - user
            - deployment
            - artifact
            - device
        tenant:
          $ref: '#/components/schemas/AuditlogsTenant'
        user:
          $ref: '#/components/schemas/AuditlogsUser'
        deployment:
          $ref: '#/components/schemas/Deployment'
        artifact:
          $ref: '#/components/schemas/AuditlogsArtifact'
        device:
          $ref: '#/components/schemas/AuditlogsDevice'
      description: |
        Various types of objects are supported.
        Depending on the type of object different information will be available.
    AuditLog:
      required:
        - action
        - actor
        - object
        - time
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/Actor'
        time:
          type: string
          format: date-time
        action:
          type: string
          enum:
            - create
            - update
            - delete
            - abort
            - reject
            - decommission
            - open_terminal
            - close_terminal
            - open_portforward
            - close_portforward
            - download_file
            - upload_file
            - set_configuration
            - deploy_configuration
            - upload
        object:
          $ref: '#/components/schemas/Object'
        change:
          type: string
      description: Audit log entry
    Artifact:
      description: Detailed artifact.
      example:
        id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
        name: Application 1.0.0
        description: Johns Monday test build
        device_types_compatible:
          - Beagle Bone
        info:
          format: mender
          version: 3
        updates:
          - type_info:
              type: rootfs-image
            files:
              - name: rootfs-image-1
                checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                size: 123
                date: 2016-03-11T13:03:17.063+0000
            meta_data: []
        artifact_provides:
          artifact_name: test
          rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
          rootfs-image.version: test
        artifact_depends:
          device_type:
            - test
        clears_artifact_provides:
          - rootfs-image.*
        size: 36891648
        modified: '2016-03-11T13:03:17.063493443Z'
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        device_types_compatible:
          description: An array of compatible device types.
          items:
            type: string
          type: array
        info:
          $ref: '#/components/schemas/ArtifactInfo'
        signed:
          description: Idicates if artifact is signed or not.
          type: boolean
        updates:
          items:
            $ref: '#/components/schemas/Update'
          type: array
        artifact_provides:
          additionalProperties:
            type: string
          description: |
            List of Artifact provides.

            Map of key/value pairs, where both keys and values are strings.
          type: object
        artifact_depends:
          additionalProperties:
            items:
              type: string
            type: array
          description: |
            List of Artifact depends.

            Map of key/value pairs, where keys are strings and values are lists of strings.
          type: object
        clears_artifact_provides:
          description: List of Clear Artifact provides.
          items:
            type: string
          type: array
        size:
          description: |
            Artifact total size in bytes - the size of the actual file that will be transferred to the device (compressed).
          format: integer
          type: number
        modified:
          description: |
            Represents creation / last edition of any of the artifact properties.
          format: date-time
          type: string
      required:
        - device_types_compatible
        - id
        - modified
        - name
      type: object
    DeploymentStatus:
      example:
        status: success
      properties:
        status:
          enum:
            - installing
            - pause_before_installing
            - downloading
            - pause_before_rebooting
            - rebooting
            - pause_before_committing
            - success
            - failure
            - already-installed
          type: string
        substate:
          description: Additional state information
          type: string
      required:
        - status
      type: object
    DeploymentInstructions:
      example:
        id: w81s4fae-7dec-11d0-a765-00a0c91e6bf6
        artifact:
          artifact_name: my-app-0.1
          source:
            uri: https://aws.myupdatebucket.com/image123
            expire: '2016-03-11T13:03:17.063493443Z'
          device_types_compatible:
            - rspi
            - rspi2
            - rspi0
      properties:
        id:
          description: Deployment ID
          type: string
        artifact:
          $ref: '#/components/schemas/DeploymentInstructionsArtifact'
      required:
        - artifact
        - id
      type: object
      nullable: true
    DeploymentLog:
      example:
        messages:
          - timestamp: '2016-03-11T13:03:17.063493443Z'
            level: INFO
            message: OK
          - timestamp: '2016-03-11T13:03:18.023765782Z'
            level: DEBUG
            message: successfully updated.
      properties:
        messages:
          description: Array of log entries of a deployment
          items:
            $ref: '#/components/schemas/DeploymentLogMessagesInner'
          type: array
      required:
        - messages
      type: object
    CheckUpdateDependsRequest:
      additionalProperties:
        type: string
        x-mender-plan:
          - enterprise
      example:
        device_type: rspi
        artifact_name: prototype-v1.0.0
        rootfs_image_checksum: 4d480539cdb23a4aee6330ff80673a5af92b7793eb1c57c4694532f96383b619
      properties:
        device_type:
          description: Device type of the device.
          type: string
        artifact_name:
          description: Name of the currently installed artifact.
          type: string
      required:
        - artifact_name
        - device_type
      type: object
    DeploymentInstructionsArtifactSource:
      properties:
        uri:
          description: URL to fetch the artifact from
          format: url
          type: string
        expire:
          description: URL expiration time
          format: date-time
          type: string
      type: object
    DeploymentInstructionsArtifact:
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/DeploymentInstructionsArtifactSource'
        device_types_compatible:
          description: Compatible device types
          items:
            type: string
          type: array
        artifact_name:
          type: string
      required:
        - artifact_name
        - device_types_compatible
        - source
      type: object
    DeploymentLogMessagesInner:
      properties:
        timestamp:
          format: date-time
          type: string
        level:
          type: string
        message:
          type: string
      required:
        - level
        - message
        - timestamp
      type: object
    ArtifactInfo:
      description: Information about artifact format and version.
      properties:
        format:
          type: string
        version:
          type: integer
      type: object
    ArtifactTypeInfo:
      description: |
        Information about update type.
      properties:
        type:
          description: Note that for emtpy Artifacts, the type is 'null'
          type: string
      type: object
    UpdateFile:
      description: |
        Information about particular update file.
      properties:
        name:
          type: string
        checksum:
          type: string
        size:
          type: integer
        date:
          format: date-time
          type: string
      type: object
    MetadataAny:
      description: metadata is an object of unknown structure as this is dependent of update type (also custom defined by user)
      additionalProperties:
        type: string
      type: object
    MetadataAnyDeprecated:
      deprecated: true
      description: |
        Deprecated: Please use `metadata` instead.
        A list of objects of unknown structure as this is dependent
        of update type (also custom defined by user)
      items:
        type: object
      type: array
    Update:
      description: |
        Single updated to be applied.
      example:
        type_info:
          type: type
        metadata: {}
        meta_data: []
        files:
          - date: '2000-01-23T04:56:07.000+00:00'
            size: 6
            name: name
            checksum: checksum
          - date: '2000-01-23T04:56:07.000+00:00'
            size: 6
            name: name
            checksum: checksum
      properties:
        type_info:
          $ref: '#/components/schemas/ArtifactTypeInfo'
        files:
          items:
            $ref: '#/components/schemas/UpdateFile'
          type: array
        metadata:
          $ref: '#/components/schemas/MetadataAny'
        meta_data:
          $ref: '#/components/schemas/MetadataAnyDeprecated'
      type: object
    DeploymentInstructionsArtifactSourceV2:
      properties:
        uri:
          description: URL to fetch the artifact from
          type: string
        expire:
          description: URL expiration time
          format: date-time
          type: string
      type: object
    DeploymentInstructionsArtifactV2:
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/DeploymentInstructionsArtifactSourceV2'
        device_types_compatible:
          description: Compatible device types
          items:
            type: string
          type: array
        artifact_name:
          type: string
      required:
        - artifact_name
        - device_types_compatible
        - source
      type: object
    DeploymentInstructionsV2:
      example:
        id: w81s4fae-7dec-11d0-a765-00a0c91e6bf6
        artifact:
          artifact_name: my-app-0.1
          source:
            uri: https://aws.my_update_bucket.com/image_123
            expire: '2016-03-11T13:03:17.063493443Z'
          device_types_compatible:
            - rspi
            - rspi2
            - rspi0
          update_control_map:
            id: e1ba5bee-c45d-11eb-887d-3fd47bdc3990
            priority: 1
            states:
              ArtifactInstall_Enter:
                action: pause
      properties:
        id:
          description: Deployment ID (device unique)
          type: string
        artifact:
          $ref: '#/components/schemas/DeploymentInstructionsArtifactV2'
        update_control_map:
          additionalProperties: true
          description: |
            A valid JSON object defining the update control map.
            The ID attribute is automatically set to the deployment's ID.
            *NOTE*: Available only in the Enterprise plan.
          example:
            update_control_map:
              id: e1ba5bee-c45d-11eb-887d-3fd47bdc3990
              priority: 1
              states:
                ArtifactInstall_Enter:
                  action: pause
          type: object
          x-mender-plan:
            - enterprise
      required:
        - artifact
        - id
      type: object
    UpdateControlMap:
      additionalProperties: true
      description: |
        A valid JSON object defining the update control map.
        The ID attribute is automatically set to the deployment's ID.
        *NOTE*: Available only in the Enterprise plan.
      example:
        update_control_map:
          id: e1ba5bee-c45d-11eb-887d-3fd47bdc3990
          priority: 1
          states:
            ArtifactInstall_Enter:
              action: pause
      type: object
      x-mender-plan:
        - enterprise
    CheckUpdateRequest:
      example:
        device_provides:
          device_type: rspi
          artifact_name: prototype-v1.0.0
          rootfs-image.checksum: 4d480539cdb23a4aee6330ff80673a5af92b7793eb1c57c4694532f96383b619
        update_control_map: true
      properties:
        device_provides:
          additionalProperties:
            type: string
            x-mender-plan:
              - enterprise
          description: |
            Key-value map of strings which describes the artifact(s) installed on the device and the
            device itself. It is used to determine the next deployment. The keys device_type and
            artifact_name are mandatory, additional free-form key-value pairs can be specified.
          type: object
        update_control_map:
          description: |
            True if the device supports Update Control Maps.
            *NOTE*: Available only in the Enterprise plan.
          type: boolean
          x-mender-plan:
            - enterprise
      required:
        - device_provides
      type: object
    StorageSettings:
      description: Per tenant storage settings.
      example:
        region: us-east-1
        bucket: mender-artifacts-unique-bucket-name
        uri: example.internal:9000
        external_uri: example.com
        key: <key>
        secret: <secret>
        token: <token>
        force_path_style: false
        use_accelerate: false
      properties:
        type:
          description: The storage provider type 'azure' Blob storage or AWS 's3' (defaults to s3).
          enum:
            - s3
            - azure
          type: string
        region:
          description: 'AWS region (S3 only: required).'
          type: string
        bucket:
          description: 'S3 Bucket (Azure: container) name.'
          type: string
        uri:
          description: Bucket/container endpoint URI.
          type: string
        external_uri:
          description: Public Endpoint URI for presigning URLs (S3 only).
          type: string
        key:
          description: 'Access key identifier (Azure: account name).'
          type: string
        secret:
          description: 'Secret access key (Azure: access key).'
          type: string
        token:
          description: AWS S3 session token (S3 only).
          type: string
        force_path_style:
          description: Force S3 path-style instead of virtual-hosted style (S3 only).
          type: boolean
        use_accelerate:
          description: Enable S3 Transfer acceleration (S3 only).
          type: boolean
        connection_string:
          description: Shared access key connection string (Azure only).
          type: string
        container_name:
          description: Alias for 'bucket' (Azure only).
          type: string
        account_name:
          description: Alias for 'key' (Azure only).
          type: string
        account_key:
          description: Alias for 'secret' (Azure only).
          type: string
      required:
        - bucket
        - key
        - secret
      type: object
    DeploymentV1Internal:
      example:
        created: '2016-02-11 13:03:17.063493+00:00'
        status: finished
        name: production
        artifact_name: Application 0.0.1
        id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
        finished: '2016-03-11 13:03:17.063493+00:00'
      properties:
        created:
          format: date-time
          type: string
        name:
          type: string
        artifact_name:
          type: string
        id:
          type: string
        finished:
          format: date-time
          type: string
        status:
          enum:
            - inprogress
            - pending
            - finished
          type: string
        device_count:
          type: integer
        artifacts:
          description: An array of artifact's identifiers.
          items:
            type: string
          type: array
        type:
          enum:
            - configuration
            - software
          type: string
      required:
        - artifact_name
        - created
        - id
        - name
        - status
      type: object
    ConfigurationDeploymentRequest:
      example:
        name: config-1.1
        configuration: '{"foo":"bar"}'
      properties:
        name:
          description: Name of the deployment
          type: string
        configuration:
          description: |
            A string containing a configuration object.
            The deployments service will use it to generate configuration
            artifact for the device.
            The artifact will be generated when the device will ask
            for an update.
          type: string
        retries:
          description: |
            The number of times a device can retry the deployment
            in case of failure, defaults to 0.
          type: integer
        update_control_map:
          description: |
            A valid JSON object defining the update control map.
            *NOTE*: Available only in the Enterprise plan.
          type: object
          x-mender-plan:
            - enterprise
      required:
        - configuration
        - name
      type: object
    GenerateDeltaJobStatus:
      description: Status of the generate delta job.
      example:
        status: success
      properties:
        status:
          type: string
      type: object
    DeviceDeployment:
      example:
        id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
        deployment:
          id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
          name: production
          artifact_name: Application 0.0.1
          status: inprogress
          created: '2016-02-11 13:03:17.063493+00:00'
          device_count: 100
        device:
          id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
          device_type: Raspberry Pi 3
          status: installing
          finished: '2016-03-11 13:03:17.063493+00:00'
          created: '2016-02-11 13:03:17.063493+00:00'
          state: installing
          substate: installing.enter;script:foo-bar
          log: false
          image:
            id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
            name: Application 1.0.0
            meta:
              description: Johns Monday test build
            meta_artifact:
              name: Application 1.0.0
              device_types_compatible:
                - Beagle Bone
              info:
                format: mender
                version: 3
              updates:
                - type_info:
                    type: rootfs-image
                  files:
                    - name: rootfs-image-1
                      checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                      size: 123
                      date: 2016-03-11T13:03:17.063+0000
                  metadata: {}
                  meta_data: []
              artifact_provides:
                artifact_name: test
                rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                rootfs-image.version: test
              artifact_depends:
                device_type:
                  - test
              clears_artifact_provides:
                - rootfs-image.*
            size: 36891648
            modified: '2016-03-11 13:03:17.063493+00:00'
      properties:
        id:
          type: string
        deployment:
          $ref: '#/components/schemas/DeploymentV1Internal'
        device:
          $ref: '#/components/schemas/DeviceWithImage'
      required:
        - deployment
        - device
      type: object
    LastDeviceDeploymentsStatuses:
      example:
        device_deployment_last_statuses:
          - device_id: b86dfe3d-a0a6-4838-b374-5fbcb7c956a1
            deployment_id: acaf62f0-6a6f-45e4-9c52-838ee593cb62
            device_deployment_id: b14a36d3-c1a9-408c-b128-bfb4808604f1
            device_deployment_status: success
          - device_id: b86dfe3d-a0a6-4838-b374-5fbcb7c956a1
            deployment_id: acaf62f0-6a6f-45e4-9c52-838ee593cb62
            device_deployment_id: b14a36d3-c1a9-408c-b128-bfb4808604f1
            device_deployment_status: success
      properties:
        device_deployment_last_statuses:
          items:
            $ref: '#/components/schemas/LastDeviceDeployment'
          type: array
      required:
        - device_deployment_last_statuses
      type: object
    LastDeviceDeployment:
      example:
        device_id: b86dfe3d-a0a6-4838-b374-5fbcb7c956a1
        deployment_id: acaf62f0-6a6f-45e4-9c52-838ee593cb62
        device_deployment_id: b14a36d3-c1a9-408c-b128-bfb4808604f1
        device_deployment_status: success
      properties:
        device_id:
          type: string
        deployment_id:
          type: string
        device_deployment_id:
          type: string
        device_deployment_status:
          type: string
      type: object
    LastDeviceDeploymentReq:
      example:
        device_ids:
          - device_id1
          - device_id2
      properties:
        device_ids:
          items:
            type: string
          type: array
      required:
        - device_ids
      type: object
    Get_Binary_Delta_Configurations_200_response_inner:
      example:
        tenant_id: tenant_id
      properties:
        tenant_id:
          description: Tenant ID
          type: string
        enabled:
          description: Flag indicating if binary delta generation is enabled
          type: boolean
      type: object
    Upload_artifact_request:
      x-go-name: InternalUploadArtifactRequest
      properties:
        artifact_id:
          description: Artifact ID, optional; the server generates a randome one if not provided.
          type: string
        size:
          description: Size of the artifact file in bytes.
          format: long
          type: integer
        description:
          type: string
        artifact:
          description: Artifact. It has to be the last part of request.
          format: binary
          type: string
      required:
        - artifact
      type: object
    DeviceGroups:
      description: Device's groups names.
      properties:
        groups:
          type: array
          items:
            type: string
          description: List of group names for the device.
      example:
        groups:
          - foo
          - bar
      type: object
    TenantLimitValue:
      description: Limit definition
      type: object
      properties:
        limit:
          type: integer
      required:
        - limit
      example:
        limit: 123
    DeviceStatus:
      x-go-name: DeploymentDeviceStatus
      enum:
        - failure
        - aborted
        - pause_before_installing
        - pause_before_committing
        - pause_before_rebooting
        - downloading
        - installing
        - rebooting
        - pending
        - success
        - noartifact
        - artifact_too_big
        - already-installed
        - decommissioned
      type: string
    DeviceWithImageImageMeta:
      properties:
        description:
          description: Image description
          type: string
      type: object
    DeviceWithImageImageMetaArtifact:
      properties:
        name:
          type: string
        device_types_compatible:
          description: An array of compatible device types.
          items:
            type: string
          type: array
        info:
          $ref: '#/components/schemas/ArtifactInfo'
        signed:
          description: Idicates if artifact is signed or not.
          type: boolean
        updates:
          items:
            $ref: '#/components/schemas/Update'
          type: array
        artifact_provides:
          additionalProperties:
            type: string
          description: |
            List of Artifact provides.

            Map of key/value pairs, where both keys and values are strings.
          type: object
        artifact_depends:
          additionalProperties:
            items:
              type: string
            type: array
          description: |
            List of Artifact depends.

            Map of key/value pairs, where keys are strings and values are lists of strings.
          type: object
        clears_artifact_provides:
          description: List of Clear Artifact provides.
          items:
            type: string
          type: array
      type: object
    DeviceWithImageImage:
      properties:
        id:
          description: Image ID
          type: string
        meta:
          $ref: '#/components/schemas/DeviceWithImageImageMeta'
        meta_artifact:
          $ref: '#/components/schemas/DeviceWithImageImageMetaArtifact'
        size:
          description: Image size in bytes
          type: integer
        modified:
          description: Creation / last edition of any of the artifact properties
          format: date-time
          type: string
      type: object
    DeviceWithImage:
      example:
        id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
        finished: '2016-03-11T13:03:17.063493443Z'
        status: installing
        created: '2016-02-11T13:03:17.063493443Z'
        started: '2016-02-12T13:03:17.063493443Z'
        device_type: Raspberry Pi 3
        log: false
        state: installing
        substate: installing.enter;script:foo-bar
        image:
          id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
          name: Application 1.0.0
          meta:
            description: Johns Monday test build
          meta_artifact:
            name: Application 1.0.0
            device_types_compatible:
              - Beagle Bone
            info:
              format: mender
              version: 3
            updates:
              - type_info:
                  type: rootfs-image
                files:
                  - name: rootfs-image-1
                    checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                    size: 123
                    date: 2016-03-11T13:03:17.063+0000
                metadata: {}
                meta_data: []
            artifact_provides:
              artifact_name: test
              rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
              rootfs-image.version: test
            artifact_depends:
              device_type:
                - test
            clears_artifact_provides:
              - rootfs-image.*
          size: 36891648
          modified: '2016-03-11T13:03:17.063493443Z'
      properties:
        id:
          description: Device identifier.
          type: string
        status:
          $ref: '#/components/schemas/DeviceStatus'
        created:
          format: date-time
          type: string
        started:
          format: date-time
          type: string
        finished:
          format: date-time
          type: string
        deleted:
          format: date-time
          type: string
        device_type:
          type: string
        log:
          description: Availability of the device's deployment log.
          type: boolean
        state:
          description: State reported by device
          type: string
        substate:
          description: Additional state information
          type: string
        attempts:
          description: Number of deployment attempts for this device
          type: integer
        phase_id:
          description: Deployment phase identifier
          type: string
        image:
          $ref: '#/components/schemas/DeviceWithImageImage'
      required:
        - id
        - log
        - status
      type: object
    XDeltaArgs:
      description: |
        xdelta3 arguments. Please refer to the xdelta3 documentation
        for a detailed description of the different options.
      example:
        compression_level: 1
        instruction_buffer_size: 1024
        input_window_size: 65536
        compression_duplicates_window: 1024
        source_window_size: 65536
      properties:
        disable_checksum:
          default: false
          description: |
            Disables checksum
          type: boolean
        disable_external_decompression:
          default: false
          description: |
            Disable external decompression
          type: boolean
        compression_level:
          description: |
            Compression level
          type: integer
        source_window_size:
          description: |
            Source window size
          type: integer
        input_window_size:
          description: |
            Input window size
          type: integer
        compression_duplicates_window:
          description: |
            Compression duplicates window
          type: integer
        instruction_buffer_size:
          description: |
            Instruction buffer size
          type: integer
      type: object
    BinaryDeltaConfiguration:
      description: The mender-binary-delta-generator configuration options.
      example:
        xdelta_args:
          compression_level: 1
          instruction_buffer_size: 1024
          input_window_size: 65536
          compression_duplicates_window: 1024
          source_window_size: 65536
        timeout: 200
      properties:
        xdelta_args:
          $ref: '#/components/schemas/XDeltaArgs'
        timeout:
          description: |
            Delta generation job timeout in seconds.
          type: integer
      type: object
    Limit:
      description: Limit descriptor.
      example:
        min: 5
        max: 100
        default: 10
      properties:
        min:
          description: Minimum value.
          type: integer
        max:
          description: Maximum value.
          type: integer
        default:
          description: Default value.
          type: integer
      type: object
    XDeltaArgsLimits:
      description: |
        Limits for arguments which will be passed to xdelta3.
        Please refer to the xdelta3 documentation
        for a detailed description of the different options.
      example:
        compression_level: {}
        instruction_buffer_size: {}
        input_window_size: {}
        compression_duplicates_window: {}
        source_window_size: {}
      properties:
        compression_level:
          allOf:
            - $ref: '#/components/schemas/Limit'
          description: Limit for compression level.
          type: object
        source_window_size:
          allOf:
            - $ref: '#/components/schemas/Limit'
          description: Limit for source window size.
          type: object
        input_window_size:
          allOf:
            - $ref: '#/components/schemas/Limit'
          description: Limit for input window size limit.
          type: object
        compression_duplicates_window:
          allOf:
            - $ref: '#/components/schemas/Limit'
          description: Limit for compression duplicates window.
          type: object
        instruction_buffer_size:
          allOf:
            - $ref: '#/components/schemas/Limit'
          description: Limit for instruction buffer size.
          type: object
      type: object
    BinaryDeltaLimits:
      description: The mender-binary-delta-generator configuration limits.
      example:
        queue_length: {}
        jobs_in_parallel: {}
        xdelta_args_limits:
          compression_level: {}
          instruction_buffer_size: {}
          input_window_size: {}
          compression_duplicates_window: {}
          source_window_size: {}
        timeout:
          min: 5
          max: 100
          default: 10
      properties:
        xdelta_args_limits:
          $ref: '#/components/schemas/XDeltaArgsLimits'
        timeout:
          $ref: '#/components/schemas/Limit'
        jobs_in_parallel:
          allOf:
            - $ref: '#/components/schemas/Limit'
          description: |
            Maximum number of delta generation jobs which can be run in parallel.
          type: object
        queue_length:
          allOf:
            - $ref: '#/components/schemas/Limit'
          description: |
            Maximum number of queued delta generation jobs.
          type: object
      type: object
    DeltaConfiguration:
      description: Delta configuration options.
      example:
        binary_delta_limits:
          queue_length: {}
          jobs_in_parallel: {}
          xdelta_args_limits:
            compression_level: {}
            instruction_buffer_size: {}
            input_window_size: {}
            compression_duplicates_window: {}
            source_window_size: {}
          timeout:
            min: 5
            max: 100
            default: 10
        binary_delta:
          xdelta_args:
            compression_level: 1
            instruction_buffer_size: 1024
            input_window_size: 65536
            compression_duplicates_window: 1024
            source_window_size: 65536
          timeout: 200
      properties:
        enabled:
          type: boolean
        binary_delta:
          $ref: '#/components/schemas/BinaryDeltaConfiguration'
        binary_delta_limits:
          $ref: '#/components/schemas/BinaryDeltaLimits'
      type: object
    ConfigurationTenant:
      description: Configuration.
      example:
        delta:
          binary_delta_limits:
            queue_length: {}
            jobs_in_parallel: {}
            xdelta_args_limits:
              compression_level: {}
              instruction_buffer_size: {}
              input_window_size: {}
              compression_duplicates_window: {}
              source_window_size: {}
            timeout:
              min: 5
              max: 100
              default: 10
          binary_delta:
            xdelta_args:
              compression_level: 1
              instruction_buffer_size: 1024
              input_window_size: 65536
              compression_duplicates_window: 1024
              source_window_size: 65536
            timeout: 200
      properties:
        delta:
          $ref: '#/components/schemas/DeltaConfiguration'
      type: object
    ErrorExt:
      description: Error descriptor with additional metadata.
      example:
        error: error description
        request_id: 11de4197-d8cf-4bd2-8a3a-29f88f238e7b
        metadata:
          additional: properties
      properties:
        error:
          description: Description of the error.
          type: string
        request_id:
          description: Request ID (same as in X-MEN-RequestID header).
          type: string
        metadata:
          additionalProperties: true
          type: object
      required:
        - error
      type: object
    NewDeployment:
      example:
        name: production
        artifact_name: Application 0.0.1
        devices:
          - 00a0c91e6-7dec-11d0-a765-f81d4faebf6
        phases:
          - batch_size: 5
            start_ts: '2020-07-06T15:04:49.114046203+02:00'
          - batch_size: 15
            start_ts: '2020-07-06T16:04:49.114046203+02:00'
          - start_ts: '2020-07-06T17:04:49.114046203+02:00'
        retries: 3
      properties:
        name:
          description: Name of the deployment
          type: string
        artifact_name:
          description: Name of the artifact to deploy
          type: string
        devices:
          description: An array of devices' identifiers.
          items:
            type: string
          type: array
        all_devices:
          description: |
            When set, the deployment will be created for all
            currently accepted devices.
          type: boolean
        force_installation:
          description: Force the installation of the Artifact disabling the `already-installed` check.
          type: boolean
        phases:
          items:
            $ref: '#/components/schemas/NewDeploymentPhase'
          type: array
          x-mender-plan:
            - professional
            - enterprise
        retries:
          description: The number of times a device can retry the deployment in case of failure, defaults to 0
          type: integer
        update_control_map:
          additionalProperties: true
          description: |
            A valid JSON object defining the update control map.
            *NOTE*: Available only in the Enterprise plan.
          type: object
          x-mender-plan:
            - enterprise
        autogenerate_delta:
          default: false
          description: |
            The flag idicating if the autogeneration of delta artifacts is enabled for a given deployment.
          type: boolean
      required:
        - artifact_name
        - name
      type: object
    NewDeploymentForGroup:
      example:
        name: production
        artifact_name: Application 0.0.1
        phases:
          - batch_size: 5
            start_ts: '2020-07-06T15:04:49.114046203+02:00'
          - batch_size: 15
            start_ts: '2020-07-06T16:04:49.114046203+02:00'
          - start_ts: '2020-07-06T17:04:49.114046203+02:00'
        retries: 3
      properties:
        name:
          description: Name of the deployment
          type: string
        artifact_name:
          description: Name of the artifact to deploy
          type: string
        force_installation:
          description: Force the installation of the Artifact disabling the `already-installed` check.
          type: boolean
        phases:
          items:
            $ref: '#/components/schemas/NewDeploymentPhase'
          type: array
          x-mender-plan:
            - professional
            - enterprise
        retries:
          description: The number of times a device can retry the deployment in case of failure, defaults to 0
          type: integer
        update_control_map:
          additionalProperties: true
          description: |
            A valid JSON object defining the update control map.
            *NOTE*: Available only in the Enterprise plan.
          type: object
          x-mender-plan:
            - enterprise
        autogenerate_delta:
          default: false
          description: |
            The flag idicating if the autogeneration of delta artifacts is enabled for a given deployment.
          type: boolean
      required:
        - artifact_name
        - name
      type: object
    DeploymentV1:
      example:
        created: '2016-02-11T13:03:17.063493443Z'
        status: finished
        name: production
        artifact_name: Application 0.0.1
        id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
        finished: '2016-03-11T13:03:17.063493443Z'
        phases:
          - batch_size: 5
          - start_ts: '2020-07-06T17:04:49.114046203+02:00'
            device_count: 25
          - batch_size: 15
          - start_ts: '2020-07-06T18:04:49.114046203+02:00'
            device_count: 10
          - start_ts: '2020-07-06T19:04:49.114046203+02:00'
            device_count: 0
        device_count: 100
        retries: 3
      properties:
        id:
          description: Deployment identifier
          type: string
        name:
          description: Name of the deployment
          type: string
        artifact_name:
          description: Name of the artifact to deploy
          type: string
        created:
          description: Deployment's creation date and time
          format: date-time
          type: string
        finished:
          description: Deployment's completion date and time
          format: date-time
          type: string
        status:
          description: Status of the deployment
          enum:
            - inprogress
            - scheduled
            - pending
            - finished
          type: string
        device_count:
          description: Number of devices the deployment acted upon
          type: integer
        artifacts:
          description: An array of artifact's identifiers.
          items:
            type: string
          type: array
        groups:
          description: |
            An array of groups the devices targeted by the deployment belong to.
            Available only if the user created the deployment for a group or a single device (if the device was in a static group).
          items:
            type: string
          type: array
        phases:
          description: An array of deployments phases (if any were defined for the deployment).
          items:
            $ref: '#/components/schemas/DeploymentPhase'
          type: array
        retries:
          description: The number of times a device can retry the deployment in case of failure, defaults to 0
          type: integer
        update_control_map:
          additionalProperties: true
          description: |
            A valid JSON object defining the update control map.
            *NOTE*: Available only in the Enterprise plan.
          type: object
        max_devices:
          description: |
            max_devices denotes a limit on a number of completed deployments (failed or successful) above which the dynamic deployment will be finished.
          type: integer
        initial_device_count:
          description: |
            In case of dynamic deployments this is a number of devices targeted initially (maching the filter at the moment of deployment creation).
          type: integer
        dynamic:
          description: |
            Flag indicating if the deployment is dynamic or not.
          type: boolean
        type:
          enum:
            - configuration
            - software
          type: string
        configuration:
          description: |
            A string containing a configuration object provided
            with the deployment constructor.
          type: string
        autogenerate_delta:
          description: |
            The flag idicating if the autogeneration of delta artifacts is enabled for a given deployment.
          type: boolean
        statistics:
          $ref: '#/components/schemas/DeploymentStatistics'
        filter:
          $ref: '#/components/schemas/FilterV1'
      required:
        - artifact_name
        - created
        - device_count
        - id
        - name
        - status
      type: object
    NewDeploymentPhase:
      description: |
        An array of deployments phases. Phases define a starting point and
        a relative batch size of devices to which the deployment applies.

        A single phase allows scheduling a deployment to start at a specific
        time.

        Multiple phases split the deployment into smaller batches of devices
        at the time giving a higher level of control of the rate devices are
        updated.

        *NOTE*: Professional plan is only allowed to specify a single phase to
        schedule deployments, this feature is not available for Starter plan.
      example:
        start_ts: '2099-07-07T21:10:17.063493443Z'
        batch_size: 5
      properties:
        batch_size:
          description: |
            Percentage of devices to update in the phase.
            This field is optional for the last phase.
            The last phase will contain the rest of the devices.
            Note that if the percentage of devices entered does not
            add up to a whole number of devices it is rounded down,
            and in the case it is rounded down to zero, a 400 error
            will be returned. This is mostly a concern when the deployment
            consists of a low number of devices, like say 5 percent of 11
            devices will round to zero, and an error is returned by the server.
          type: integer
        batch_size_devices:
          description: |
            Exact number of devices to update in this phase.
            This field is optional for the last phase, which will contain the remaining devices.
            Note that you can only specify either `batch_size` or `batch_size_devices`, not both for all phases in a deployment.
          type: integer
        start_ts:
          description: |
            Start date of a phase.
            Can be skipped for the first phase of a new deployment definition ('start immediately').
          format: date-time
          type: string
      type: object
    DeviceDeploymentV1:
      example:
        id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
        deployment:
          id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
          name: production
          artifact_name: Application 0.0.1
          status: inprogress
          created: '2016-02-11T13:03:17.063493443Z'
          device_count: 100
        device:
          id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
          device_type: Raspberry Pi 3
          status: installing
          finished: '2016-03-11T13:03:17.063493443Z'
          created: '2016-02-11T13:03:17.063493443Z'
          started: '2016-02-11T13:03:17.063493443Z'
          state: installing
          substate: installing.enter;script:foo-bar
          log: false
          image:
            id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
            name: Application 1.0.0
            meta:
              description: Johns Monday test build
            meta_artifact:
              name: Application 1.0.0
              device_types_compatible:
                - Beagle Bone
              info:
                format: mender
                version: 3
              updates:
                - type_info:
                    type: rootfs-image
                  files:
                    - name: rootfs-image-1
                      checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                      size: 123
                      date: 2016-03-11T13:03:17.063+0000
                  metadata: {}
                  meta_data: []
              artifact_provides:
                artifact_name: test
                rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
                rootfs-image.version: test
              artifact_depends:
                device_type:
                  - test
              clears_artifact_provides:
                - rootfs-image.*
            size: 36891648
            modified: '2016-03-11T13:03:17.063493443Z'
      properties:
        id:
          type: string
        deployment:
          $ref: '#/components/schemas/DeploymentV1'
        device:
          $ref: '#/components/schemas/DeviceWithImage'
      required:
        - deployment
        - device
      type: object
    ArtifactUpdateV1:
      description: Artifact information update.
      example:
        description: Some description
      properties:
        description:
          type: string
      type: object
    ArtifactV1:
      description: Detailed artifact.
      example:
        id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
        name: Application 1.0.0
        description: Johns Monday test build
        device_types_compatible:
          - Beagle Bone
        info:
          format: mender
          version: 3
        updates:
          - type_info:
              type: rootfs-image
            files:
              - name: rootfs-image-1
                checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                size: 123
                date: 2016-03-11T13:03:17.063+0000
            metadata: {}
            meta_data: []
        artifact_provides:
          artifact_name: test
          rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
          rootfs-image.version: test
        artifact_depends:
          device_type:
            - test
        clears_artifact_provides:
          - rootfs-image.*
        size: 36891648
        modified: '2016-03-11T13:03:17.063493443Z'
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        device_types_compatible:
          description: An array of compatible device types.
          items:
            type: string
          type: array
        info:
          $ref: '#/components/schemas/ArtifactInfo'
        signed:
          description: Idicates if artifact is signed or not.
          type: boolean
        updates:
          items:
            $ref: '#/components/schemas/Update'
          type: array
        artifact_provides:
          additionalProperties:
            type: string
          description: |
            List of Artifact provides.

            Map of key/value pairs, where both keys and values are strings.
          type: object
        artifact_depends:
          additionalProperties:
            items:
              type: string
            type: array
          description: |
            List of Artifact depends.

            Map of key/value pairs, where keys are strings and values are lists of strings.
          type: object
        clears_artifact_provides:
          description: List of Clear Artifact provides.
          items:
            type: string
          type: array
        size:
          description: |
            Artifact total size in bytes - the size of the actual file that will be transferred to the device (compressed).
          type: integer
        modified:
          description: |
            Represents creation / last edition of any of the artifact properties.
          format: date-time
          type: string
      required:
        - device_types_compatible
        - id
        - modified
        - name
      type: object
    ArtifactUploadLink:
      description: URL for artifact file upload.
      example:
        id: 07d2e773-a2a3-4f64-936a-4245e79194dd
        uri: https://hosted-mender-artifacts.s3.amazonaws.com/1234/40df67c4-e5e9-4042-981a-f43adebd5b88?X-Amz-Date=20230401T000000Z&X-Amz-Expires=900&X-Amz-Signature=6d656e646572
        expire: '2023-04-01T00:15:00Z'
      properties:
        id:
          description: The ID of the artifact upload intent.
          format: uuid
          type: string
        uri:
          type: string
        expire:
          format: date-time
          type: string
      required:
        - expire
        - id
        - uri
      type: object
    ReleasesV1:
      description: List of releases
      items:
        $ref: '#/components/schemas/ReleaseV1'
      type: array
    ReleaseV1:
      description: Groups artifacts with the same release name into a single resource.
      example:
        name: my-app-v1.0.1
        artifacts:
          - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
            name: Application 1.0.0
            description: Johns Monday test build
            device_types_compatible:
              - Beagle Bone
            info:
              format: mender
              version: 3
            updates:
              - type_info:
                  type: rootfs-image
                files:
                  - name: rootfs-image-1
                    checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                    size: 123
                    date: 2016-03-11T13:03:17.063+0000
                metadata: {}
                meta_data: []
            artifact_provides:
              artifact_name: test
              rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
              rootfs-image.version: test
            artifact_depends:
              device_type:
                - test
            clears_artifact_provides:
              - rootfs-image.*
            size: 36891648
            modified: '2016-03-11T13:03:17.063493443Z'
          - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
            name: Application 1.0.0
            description: Johns Monday test build
            device_types_compatible:
              - Raspberry Pi
            info:
              format: mender
              version: 3
            updates:
              - type_info:
                  type: rootfs-image
                files:
                  - name: rootfs-image-1
                    checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                    size: 123
                    date: 2016-03-11T13:03:17.063+0000
                metadata: {}
                meta_data: []
            artifact_provides:
              artifact_name: test
              rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
              rootfs-image.version: test
            artifact_depends:
              device_type:
                - test
            clears_artifact_provides:
              - rootfs-image.*
            size: 36891648
            modified: '2016-03-11T13:03:17.063493443Z'
      properties:
        Name:
          description: |
            release name.
          type: string
        modified:
          description: |
            Last modification time for the release.
          format: date-time
          type: string
        Artifacts:
          description: List of artifacts for this release.
          items:
            $ref: '#/components/schemas/ArtifactV1'
          type: array
        ArtifactsCount:
          description: Number of artifacts.
          type: integer
        tags:
          description: |-
            Tags assigned to the release used for filtering releases. Each tag
            must be valid a ASCII string and contain only lowercase and uppercase
            letters, digits, underscores, periods and hyphens.
          items:
            type: string
          type: array
        notes:
          description: |
            Additional information describing a Release limited to 1024 characters. Please use the v2 API to set this field.
          type: string
      type: object
    BinaryDeltaConfigurationUpdate:
      description: The mender-binary-delta-generator configuration options.
      example:
        xdelta_args:
          compression_level: 1
          instruction_buffer_size: 1024
          input_window_size: 65536
          compression_duplicates_window: 1024
          source_window_size: 65536
      properties:
        xdelta_args:
          $ref: '#/components/schemas/XDeltaArgs'
      type: object
    DirectUploadMetadata:
      description: Artifact metadata
      example:
        size: 0
        updates:
          - type_info:
              type: type
            metadata: {}
            meta_data: []
            files:
              - date: '2000-01-23T04:56:07.000+00:00'
                size: 6
                name: name
                checksum: checksum
              - date: '2000-01-23T04:56:07.000+00:00'
                size: 6
                name: name
                checksum: checksum
          - type_info:
              type: type
            metadata: {}
            meta_data: []
            files:
              - date: '2000-01-23T04:56:07.000+00:00'
                size: 6
                name: name
                checksum: checksum
              - date: '2000-01-23T04:56:07.000+00:00'
                size: 6
                name: name
                checksum: checksum
      properties:
        size:
          description: |
            wsize of the artifact file.
          type: integer
        updates:
          description: List of updates for this artifact.
          items:
            $ref: '#/components/schemas/Update'
          type: array
      type: object
    DeploymentIdentifier:
      description: Deployment identifier
      example:
        deployment_ids:
          - deployment_ids
          - deployment_ids
      properties:
        deployment_ids:
          items:
            description: The list of deployment IDs
            type: string
          type: array
      type: object
    FilterV1:
      description: |
        Filter built based on devices targeted by the deployment.
      example:
        id: myfilter
        name: My Filter
        terms:
          - scope: system
            attribute: group
            type: $eq
            value: groupName
      properties:
        id:
          description: |
            Unique identifier of the saved filter.
          type: string
        name:
          description: |
            Name of the saved filter.
          type: string
        terms:
          items:
            $ref: '#/components/schemas/AttributeFilterPredicate'
          type: array
      required:
        - terms
      type: object
    DeploymentStatusStatisticsList200ResponseInner:
      example:
        stats:
          success: 3
          pending: 1
          failure: 0
          downloading: 1
          installing: 2
          rebooting: 3
          noartifact: 0
          artifact_too_big: 0
          already-installed: 0
          aborted: 0
          pause_before_installing: 0
          pause_before_rebooting: 0
          pause_before_committing: 0
        id: id
      properties:
        id:
          description: The deployment ID
          type: string
        stats:
          $ref: '#/components/schemas/Statistics'
      type: object
    PatchDeploymentControlMapRequest:
      description: Update control map.
      properties:
        update_control_map:
          properties: {}
          type: object
      type: object
    AbortDeploymentRequest:
      properties:
        status:
          enum:
            - aborted
          type: string
      required:
        - status
      type: object
    UploadArtifactRequest:
      properties:
        size:
          description: |
            Size of the artifact file in bytes.
            DEPRECATED: _since Mon Apr 6 2020_ Size is determined from uploaded content.
          format: long
          type: integer
        description:
          type: string
        artifact:
          description: Artifact. It has to be the last part of request.
          format: binary
          type: string
      required:
        - artifact
      type: object
    CompleteDirectUpload404Response:
      example:
        error: error
        request_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
      properties:
        error:
          type: string
        request_id:
          description: 'Request identifier (Header: X-Men-Requestid)'
          format: uuid
          type: string
      type: object
    GenerateArtifactRequest:
      properties:
        name:
          description: Name of the artifact to generate.
          type: string
        description:
          description: Description of the artifact to generate.
          type: string
        device_types_compatible:
          description: An array of compatible device types.
          items:
            type: string
          type: array
        type:
          description: Update Module used to generate the artifact.
          enum:
            - single_file
          type: string
        args:
          description: |
            String that represents a JSON document defining the arguments used to generate the artifact.
            The service won't parse the content of this parameter and pass it as it is to the create artifact worker.
            The available arguments and options depend on the Update Module implementation and are, therefore, Type-specific.
          type: string
        file:
          description: Raw file to be used to generate the artifact. It has to be the last part of request.
          format: binary
          type: string
      required:
        - device_types_compatible
        - file
        - name
        - type
      type: object
    DeploymentPhase:
      example:
        application/json:
          id: foo
          start_ts: '2020-07-06T15:04:49.114046203+02:00'
          batch_size: 5
          device_count: 42
      properties:
        id:
          description: Phase identifier.
          type: string
        batch_size:
          description: |
            Percentage of devices to update in the phase.
          type: integer
        start_ts:
          description: |
            Start date of a phase.
            May be undefined for the first phase of a deployment.
          format: date-time
          type: string
        device_count:
          description: |
            Number of devices which already requested an update within this phase.
          type: integer
      type: object
    Statistics:
      example:
        success: 3
        pending: 1
        failure: 0
        downloading: 1
        installing: 2
        rebooting: 3
        noartifact: 0
        artifact_too_big: 0
        already-installed: 0
        aborted: 0
        pause_before_installing: 0
        pause_before_rebooting: 0
        pause_before_committing: 0
      properties:
        success:
          description: Number of successful deployments.
          type: integer
        pending:
          description: Number of pending deployments.
          type: integer
        downloading:
          description: Number of deployments being downloaded.
          type: integer
        rebooting:
          description: Number of deployments devices are rebooting into.
          type: integer
        installing:
          description: Number of deployments devices being installed.
          type: integer
        failure:
          description: Number of failed deployments.
          type: integer
        noartifact:
          description: Do not have appropriate artifact for device type.
          type: integer
        artifact_too_big:
          description: Artifact size exceeded limit for distribution to the device
          type: integer
        already-installed:
          description: Number of devices unaffected by upgrade, since they are already running the specified software version.
          type: integer
        aborted:
          description: Number of deployments aborted by user.
          type: integer
        pause_before_installing:
          description: Number of deployments paused before install state.
          type: integer
        pause_before_rebooting:
          description: Number of deployments paused before reboot phase.
          type: integer
        pause_before_committing:
          description: Number of deployments paused before commit phase.
          type: integer
      required:
        - aborted
        - already-installed
        - downloading
        - failure
        - installing
        - noartifact
        - artifact_too_big
        - pause_before_committing
        - pause_before_installing
        - pause_before_rebooting
        - pending
        - rebooting
        - success
      type: object
    DeploymentStatistics:
      properties:
        status:
          $ref: '#/components/schemas/Statistics'
        total_size:
          description: |
            Sum of sizes (in bytes) of all artifacts assigned to all device deployments,
            which are part of this deployment.
            If the same artifact is assigned to multiple device deployments,
            its size will be counted multiple times.
          type: integer
      type: object
    AttributeFilterPredicate:
      description: Attribute filter predicate
      example:
        type: $eq
        attribute: serial_no
        scope: inventory
        value: '123456789'
      properties:
        scope:
          $ref: '#/components/schemas/Scope'
        attribute:
          description: |
            Name of the attribute to be queried for filtering.
          type: string
        type:
          description: Type or operator of the filter predicate.
          enum:
            - $eq
            - $gt
            - $gte
            - $in
            - $lt
            - $lte
            - $ne
            - $nin
            - $exists
          type: string
        value:
          description: |
            The value of the attribute to be used in filtering.
            Attribute type is implicit, inferred from the JSON type.
            Supported types: number, string, array of numbers, array of strings.
            Mixed arrays are not allowed.
      required:
        - attribute
        - scope
        - type
        - value
      type: object
    StorageLimit:
      description: Tenant account storage limit and storage usage.
      example:
        limit: 1073741824
        usage: 536870912
      properties:
        limit:
          description: |
            Storage limit in bytes. If set to -1 - there is no limit for storage.
          type: integer
        usage:
          description: |
            Current storage usage in bytes.
          type: integer
      required:
        - limit
        - usage
      type: object
    ArtifactV2:
      description: Detailed artifact.
      example:
        id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
        name: Application 1.0.0
        description: Johns Monday test build
        device_types_compatible:
          - Beagle Bone
        info:
          format: mender
          version: 3
        updates:
          - type_info:
              type: rootfs-image
            files:
              - name: rootfs-image-1
                checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                size: 123
                date: 2016-03-11T13:03:17.063+0000
            metadata: {}
            meta_data: []
        artifact_provides:
          artifact_name: test
          rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
          rootfs-image.version: test
        artifact_depends:
          device_type:
            - test
        clears_artifact_provides:
          - rootfs-image.*
        size: 36891648
        modified: '2016-03-11T13:03:17.063493443Z'
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        device_types_compatible:
          description: An array of compatible device types.
          items:
            type: string
          type: array
        info:
          $ref: '#/components/schemas/ArtifactInfo'
        signed:
          description: Idicates if artifact is signed or not.
          type: boolean
        updates:
          items:
            $ref: '#/components/schemas/Update'
          type: array
        artifact_provides:
          additionalProperties:
            type: string
          description: |
            List of Artifact provides.

            Map of key/value pairs, where both keys and values are strings.
          type: object
        artifact_depends:
          additionalProperties:
            items:
              type: string
            type: array
          description: |
            List of Artifact depends.

            Map of key/value pairs, where keys are strings and values are lists of strings.
          type: object
        clears_artifact_provides:
          description: List of Clear Artifact provides.
          items:
            type: string
          type: array
        size:
          description: |
            Artifact total size in bytes - the size of the actual file that will be transferred to the device (compressed).
          type: integer
        modified:
          description: |
            Represents creation / last edition of any of the artifact properties.
          format: date-time
          type: string
      required:
        - description
        - device_types_compatible
        - id
        - modified
        - name
      type: object
    ReleasesV2:
      description: List of releases
      items:
        $ref: '#/components/schemas/ReleaseV2'
      type: array
    ReleaseV2:
      description: Groups artifacts with the same release name into a single resource.
      example:
        name: my-app-v1.0.1
        artifacts:
          - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
            name: Application 1.0.0
            description: Johns Monday test build
            device_types_compatible:
              - Beagle Bone
            info:
              format: mender
              version: 3
            updates:
              - type_info:
                  type: rootfs-image
                files:
                  - name: rootfs-image-1
                    checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                    size: 123
                    date: 2016-03-11T13:03:17.063+0000
                metadata: {}
                meta_data: []
            artifact_provides:
              artifact_name: test
              rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
              rootfs-image.version: test
            artifact_depends:
              device_type:
                - test
            clears_artifact_provides:
              - rootfs-image.*
            size: 36891648
            modified: '2016-03-11T13:03:17.063493443Z'
          - id: 0c13a0e6-6b63-475d-8260-ee42a590e8ff
            name: Application 1.0.0
            description: Johns Monday test build
            device_types_compatible:
              - Raspberry Pi
            info:
              format: mender
              version: 3
            updates:
              - type_info:
                  type: rootfs-image
                files:
                  - name: rootfs-image-1
                    checksum: cc436f982bc60a8255fe1926a450db5f195a19ad
                    size: 123
                    date: 2016-03-11T13:03:17.063+0000
                metadata: {}
                meta_data: []
            artifact_provides:
              artifact_name: test
              rootfs-image.checksum: 32714818ad6f98ee0185a52e23a475d89122e3efd2b2c26c733781c28e798c99
              rootfs-image.version: test
            artifact_depends:
              device_type:
                - test
            clears_artifact_provides:
              - rootfs-image.*
            size: 36891648
            modified: '2016-03-11T13:03:17.063493443Z'
      properties:
        name:
          description: |
            release name.
          type: string
        modified:
          description: |
            Last modification time for the release.
          format: date-time
          type: string
        artifacts:
          description: List of artifacts for this release.
          items:
            $ref: '#/components/schemas/ArtifactV2'
          type: array
        tags:
          description: |-
            Tags assigned to the release used for filtering releases. Each tag
            must be valid a ASCII string and contain only lowercase and uppercase
            letters, digits, underscores, periods and hyphens.
          items:
            type: string
          type: array
        notes:
          description: |
            Additional information describing a Release limited to 1024 characters. Please use the v2 API to set this field.
          type: string
      type: object
    ReleaseUpdate:
      description: Fields to be updated in the given Release.
      example:
        notes: New security fixes 2023
      properties:
        notes:
          description: Release notes, limited to maximum length.
          type: string
      type: object
    Tags:
      description: |-
        Tags assigned to the release used for filtering releases. Each tag
        must be valid a ASCII string and contain only lowercase and uppercase
        letters, digits, underscores, periods and hyphens.
      items:
        type: string
      type: array
    UpdateTypes:
      description: Update types as present in the images.
      items:
        type: string
      type: array
    FilterV2:
      description: Inventory filter assigned to the deployment
      example:
        id: myfilter
        name: My Filter
        terms:
          - scope: inventory
            attribute: serial_no
            type: $eq
            value: '123456789'
      properties:
        id:
          description: |
            Unique identifier of the saved filter.
          type: string
        name:
          description: |
            Name of the saved filter.
          type: string
        terms:
          items:
            $ref: '#/components/schemas/AttributeFilterPredicate'
          type: array
      required:
        - id
        - name
      type: object
    DeploymentV2:
      example:
        created: '2016-02-11T13:03:17.063493443Z'
        status: finished
        name: production
        artifact_name: Application 0.0.1
        id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
        finished: '2016-03-11T13:03:17.063493443Z'
        phases:
          - batch_size: 5
          - start_ts: '2020-07-06T17:04:49.114046203+02:00'
            device_count: 25
          - batch_size: 15
          - start_ts: '2020-07-06T18:04:49.114046203+02:00'
            device_count: 10
          - start_ts: '2020-07-06T19:04:49.114046203+02:00'
            device_count: 0
        device_count: 500
        retries: 3
      properties:
        id:
          description: Deployment identifier
          type: string
        name:
          description: Name of the deployment
          type: string
        artifact_name:
          description: Name of the artifact to deploy
          type: string
        created:
          description: Deployment's creation date and time
          format: date-time
          type: string
        finished:
          description: Deployment's completion date and time
          format: date-time
          type: string
        status:
          description: Status of the deployment
          enum:
            - scheduled
            - pending
            - inprogress
            - finished
          type: string
        device_count:
          description: Number of devices the deployment acted upon
          type: integer
        artifacts:
          description: An array of artifact's identifiers.
          items:
            type: string
          type: array
        groups:
          description: |
            An array of groups the devices targeted by the deployment belong to.
            Available only if the user created the deployment for a group or a single device (if the device was in a static group).
          items:
            type: string
          type: array
        phases:
          description: An array of deployments phases (if any were defined for the deployment).
          items:
            $ref: '#/components/schemas/DeploymentPhase'
          type: array
        retries:
          description: The number of times a device can retry the deployment in case of failure, defaults to 0
          type: integer
        update_control_map:
          additionalProperties: true
          description: |
            A valid JSON object defining the update control map.
            *NOTE*: Available only in the Enterprise plan.
          type: object
        max_devices:
          description: |
            max_devices denotes a limit on a number of completed deployments (failed or successful) above which the dynamic deployment will be finished.
          type: integer
        initial_device_count:
          description: |
            In case of dynamic deployments this is a number of devices targeted initially (maching the filter at the moment of deployment creation).
          type: integer
        dynamic:
          description: |
            Flag indicating if the deployment is dynamic or not.
          type: boolean
        filter:
          $ref: '#/components/schemas/FilterV2'
        type:
          enum:
            - configuration
            - software
          type: string
        configuration:
          description: |
            A string containing a configuration object provided
            with the deployment constructor.
          type: string
        autogenerate_delta:
          description: |
            The flag idicating if the autogeneration of delta artifacts is enabled for a given deployment.
          type: boolean
        statistics:
          $ref: '#/components/schemas/DeploymentStatistics'
      required:
        - artifact_name
        - created
        - device_count
        - id
        - name
        - status
      type: object
    NewDeploymentV2:
      example:
        name: production
        artifact_name: Application 0.0.1
        filter_id: 00a0c91e6-7dec-11d0-a765-f81d4faebf6
        phases:
          - batch_size: 5
            start_ts: '2020-07-06T17:04:49.114046203+02:00'
          - batch_size: 15
            start_ts: '2020-07-06T18:04:49.114046203+02:00'
          - start_ts: '2020-07-06T19:04:49.114046203+02:00'
        retries: 3
      properties:
        name:
          type: string
        artifact_name:
          type: string
        filter_id:
          description: ID of a filter from inventory service.
          type: string
        phases:
          description: |
            Phased rollout feature is available only to Enterprise users.
          items:
            $ref: '#/components/schemas/NewDeploymentPhase'
          type: array
        retries:
          description: The number of times a device can retry the deployment in case of failure, defaults to 0
          type: integer
        max_devices:
          description: |
            max_devices denotes a limit on a number of completed deployments (failed or successful) above which the dynamic deployment will be finished
          type: integer
        update_control_map:
          additionalProperties: true
          description: |
            A valid JSON object defining the update control map.
            *NOTE*: Available only in the Enterprise plan.
          type: object
          x-mender-plan:
            - enterprise
        autogenerate_delta:
          default: false
          description: |
            The flag idicating if the autogeneration of delta artifacts is enabled for a given deployment.
          type: boolean
      required:
        - artifact_name
        - filter_id
        - name
      type: object
    ReleasesDeleteError:
      description: Releases used by active deployment.
      example:
        error: active deployments are using some of the releases from the request
        request_id: f7881e82-0492-49fb-b459-795654e7188a
      properties:
        error:
          description: Description of the error.
          type: string
        active_deployments:
          description: List of IDs of active deployments which are using releases from the request.
          items:
            type: string
          type: array
        request_id:
          description: Request ID (same as in X-MEN-RequestID header).
          type: string
      type: object
    DeltaJobsListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: |
            Identifier of the job
        deployment_id:
          type: string
          format: uuid
          description: |
            Identifier of a deployment
        delta_job_id:
          type: string
          description: |
            Workflows id that corresponds to the job executed by the generator, it is an internal id important
            to include in case of support requests
        to_version:
          type: string
          description: |
            Release or artifact name of the second argument that we used to generate the delta
        from_version:
          type: string
          description: |
            Release or artifact name of the first argument that we used to generate the delta
        details:
          type: string
          description: |
            Details of the delta generation job
        devices_types_compatible:
          type: array
          items:
            type: string
          description: |
            Array of the devices types names compatible with this artifact
        started:
          type: string
          format: date-time
          description: |
            Date we started the generation
        finished:
          type: string
          format: date-time
          description: Time when the generation terminated.
        total_time:
          type: string
          description: The duration for the delta generation.
        status:
          type: string
          enum:
            - pending
            - queued
            - success
            - failed
          description: |
            Gneration status
      example:
        id: bb2a1d7f-a275-4045-be54-ec701f11659c
        delta_job_id: 67e4310d82ba0eead4e41cbf
        to_version: release-1024-rofs-no-deps-sum
        from_version: release-256-rofs-no-deps-sum
        devices_types_compatible:
          - raspberrypi4
          - raspberrypi3
        started: '2025-03-26T16:53:33.592Z'
        finished: '2025-03-26T16:59:15.713Z'
        total_time: 5m42s
        status: success
    DeltaJobDetailsItem:
      allOf:
        - $ref: '#/components/schemas/DeltaJobsListItem'
        - type: object
          properties:
            to_release:
              deprecated: true
              type: string
              description: |
                Target release name

                Deprecated: contains the same information as to_version.
            from_release:
              deprecated: true
              type: string
              description: |
                Source release name

                Deprecated: contains the same information as from_version.
            exit_code:
              type: number
              description: |
                Exit code of the delta generation job
            target_size:
              type: number
              description: |
                Size of the target artifact
            delta_artifact_size:
              type: number
              description: |
                Size of the resulting delta artifact
        - example:
            deployment_id: 455ac5e4-16ec-428e-9a2e-6bda6653a727
            device_types_compatible:
              - raspberrypi4
              - raspberrypi3
            from_release: my-release-1
            to_release: my-release-2
            status: success
            details: |
              2025-05-05T17:25:40Z generation job scheduled
              2025-05-05T17:27:10Z finished successfully"
            exit_code: 0
            target_size: 134217728
            delta_artifact_size: 12288
    AuthRequest:
      type: object
      required:
        - id_data
        - pubkey
      properties:
        id_data:
          type: string
          description: Vendor-specific JSON representation of the device identity data (MACs, serial numbers, etc.).
        pubkey:
          type: string
          description: |
            The device's public key (PEM encoding), generated by the device or pre-provisioned by the vendor. Currently supported public algorithms are: RSA, Ed25519 and ECDSA P-256.
        tenant_token:
          type: string
          description: Tenant token.
        tier:
          type: string
          description: A device tier.
          enum:
            - standard
            - micro
            - system
        external_id:
          type: string
          description: |
            External identity which can be used to verify devices managed by cloud providers.
            Currently, only Azure IoT Edge devices are supported.
      example:
        id_data: '{"mac":"00:01:02:03:04:05"}'
        pubkey: |
          -----BEGIN PUBLIC KEY-----
          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH
          VJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c
          yC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP
          okP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty
          1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0
          iyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG
          UwIDAQAB
          -----END PUBLIC KEY-----
    ExternalDevice:
      type: object
      description: External device descriptor
      properties:
        id:
          type: string
          description: ID assigned by external provider
        name:
          type: string
          description: Name of the device
        provider:
          type: string
          description: Name of the external provider
        id_data:
          type: string
          description: Optional custom ID data
      required:
        - id
        - name
        - provider
    DeviceLimit:
      description: Limit definition
      type: object
      properties:
        limit:
          type: integer
      required:
        - limit
      example:
        limit: 123
    Status:
      description: Admission status of the device.
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - accepted
            - rejected
            - preauthorized
      required:
        - status
      example:
        status: accepted
    ExternalIdentity:
      description: |
        Device external identity.
      type: object
      properties:
        data:
          description: External identity.
          type: string
        active:
          description: Status flag.
          type: boolean
      example:
        data: iot-hub device-id/module-id
    Device:
      type: object
      properties:
        id:
          type: string
          description: Mender assigned Device ID.
        identity_data:
          $ref: '#/components/schemas/IdentityData'
        status:
          type: string
          x-go-name: DeviceAuthStatus
          enum:
            - pending
            - accepted
            - rejected
            - preauthorized
            - noauth
        created_ts:
          type: string
          format: date-time
          description: Created timestamp
        updated_ts:
          type: string
          format: date-time
          description: Updated timestamp
        check_in_time:
          type: string
          format: date-time
          description: Time when accepted device contacted server for the last time.
        auth_sets:
          type: array
          items:
            $ref: '#/components/schemas/AuthSet'
        decommissioning:
          type: boolean
          description: Devices that are part of ongoing decomissioning process will return True
        external_id:
          $ref: '#/components/schemas/ExternalIdentity'
    Count:
      description: Counter type
      type: object
      properties:
        count:
          description: The count of requested items.
          type: integer
      example:
        count: 42
    DeviceTierLimits:
      description: Device limit per tier
      type: object
      properties:
        standard:
          type: integer
          description: |
            The number of standard tier devices that can be accepted by the tenant.
            A value of 0 or -1 means that an unlimited amount of standard tier devices can be accepted.
        micro:
          type: integer
          description: |
            The number of micro tier devices that can be accepted by the tenant.
            A value of -1 means that an unlimited amount of micro tier devices can be accepted.
        system:
          type: integer
          description: |
            The number of system tier devices that can be accepted by the tenant.
            A value of -1 means that an unlimited amount of system tier devices can be accepted.
      required:
        - standard
        - micro
        - system
      example:
        standard: 100
        micro: 1000
        system: 10
    PreAuthSet:
      type: object
      properties:
        force:
          type: boolean
          description: Indicates that despite the device having any authsets the preauthorization should proceed.
        identity_data:
          $ref: '#/components/schemas/IdentityData'
        pubkey:
          type: string
          description: 'The device''s public key (PEM encoding), generated by the device or pre-provisioned by the vendor. Currently supported public algorithms are: RSA, Ed25519 and ECDSA P-256.'
        tier:
          type: string
          description: A device tier.
          enum:
            - standard
            - micro
            - system
      required:
        - identity_data
        - pubkey
      example:
        identity_data:
          mac: '00:01:02:03:04:05'
          sku: My Device 1
          sn: SN1234567890
        pubkey: |
          -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH VJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c yC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP okP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty 1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0 iyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG UwIDAQAB -----END PUBLIC KEY-----
    AutoAuthRequest:
      type: object
      description: Authentication request.
      properties:
        id_data:
          type: string
          description: Vendor-specific JSON representation of the device identity data (MACs, serial numbers, etc.).
        pubkey:
          type: string
          description: |
            The device's public key (PEM encoding), generated by the device or pre-provisioned by the vendor. Currently supported public algorithms are: RSA, ED25519 and ECDSA.
        tenant_token:
          type: string
          description: Tenant token.
        external_id:
          type: string
          description: |
            External identity which can be used to verify devices managed by cloud providers.
            Currently, only Azure IoT Edge devices are supported.
      required:
        - id_data
        - pubkey
      example:
        id_data: '{"mac":"00:01:02:03:04:05"}'
        pubkey: |
          -----BEGIN PUBLIC KEY-----
          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH
          VJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c
          yC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP
          okP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty
          1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0
          iyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG
          UwIDAQAB
          -----END PUBLIC KEY-----
    DeviceAPIConfiguration:
      type: object
      additionalProperties:
        type: string
    NewConfigurationDeployment:
      type: object
      properties:
        retries:
          type: integer
          description: The number of times a device can retry the deployment in case of failure, defaults to 0
          default: 0
          x-mender-plan:
            - professional
            - enterprise
        update_control_map:
          x-mender-plan:
            - enterprise
          type: object
          additionalProperties: true
          description: |
            A valid JSON object defining the update control map.
            *NOTE*: Available only in the Enterprise plan.
    NewConfigurationDeploymentResponse:
      type: object
      properties:
        deployment_id:
          type: string
          description: Deployment ID
    ManagementAPIConfiguration:
      type: object
      additionalProperties:
        type: string
    DeviceConfiguration:
      type: object
      properties:
        id:
          type: string
          format: uuid
        configured:
          $ref: '#/components/schemas/ManagementAPIConfiguration'
        reported:
          $ref: '#/components/schemas/ManagementAPIConfiguration'
        deployment_id:
          description: ID of the latest configuration deployment
          type: string
          format: uuid
        reported_ts:
          type: string
          format: date-time
        updated_ts:
          type: string
          format: date-time
    ConnectionState:
      type: object
      properties:
        device_id:
          type: string
          format: uuid
          description: Device ID.
        status:
          type: string
          enum:
            - connected
            - disconnected
            - unknown
          description: Device status.
        updated_ts:
          description: Server-side timestamp of the last device information update.
          format: date-time
          type: string
        created_ts:
          description: Server-side timestamp of the device creation.
          format: date-time
          type: string
    FileUpload:
      type: object
      properties:
        path:
          type: string
          description: The destination path on the device
        uid:
          type: integer
          description: The numerical UID of the file on the device
        gid:
          type: integer
          description: The numerical GID of the file on the device
        mode:
          type: string
          description: The octal representation of the mode of the file on the device
        file:
          type: string
          format: binary
      required:
        - path
    Alert:
      description: Alert request
      type: object
      properties:
        name:
          description: |
            A descriptive name of the alert
          type: string
        level:
          description: |
            Alert severity level
          type: string
          enum:
            - OK
            - CRITICAL
        subject:
          $ref: '#/components/schemas/AlertSubject'
        timestamp:
          description: |
            Time and date when the alert occured
          type: string
          format: date-time
      required:
        - name
        - level
        - subject
        - timestamp
      example:
        name: mender-connect systemd service
        level: CRITICAL
        timestamp: '2019-07-21T17:32:28Z'
        subject:
          name: mender-connect
          status: not-running
          type: systemd.unit
          details:
            description: Description of an error.
            lines_before:
              - line_number: 1
                data: Line 1 from a log file
              - line_number: 2
                data: Line 2 from a log file
            line_matching:
              line_number: 3
              data: Line 3 from a log file
            lines_after:
              - line_number: 4
                data: Line 4 from a log file
              - line_number: 5
                data: Line 5 from a log file
    AlertSubject:
      description: |
        Alert subject: the description of the alert origin
      type: object
      properties:
        name:
          description: |
            Name of an entity that caused the alert
          type: string
        type:
          description: |
            The type of executable that triggered the alert.
          type: string
        status:
          description: |
            Status of an entity that caused the alert
          type: string
        details:
          $ref: '#/components/schemas/AlertDetails'
      required:
        - name
        - status
        - type
      example:
        name: mender-connect
        status: not-running
        type: systemd.unit
        details:
          description: Description of an error.
          lines_before:
            - line_number: 1
              data: Line 1 from a log file
            - line_number: 2
              data: Line 2 from a log file
          line_matching:
            line_number: 3
            data: Line 3 from a log file
          lines_after:
            - line_number: 4
              data: Line 4 from a log file
            - line_number: 5
              data: Line 5 from a log file
    AlertDetails:
      description: |
        Additional details on the alert.
      type: object
      properties:
        description:
          description: |
            Alert description.
          type: string
        lines_before:
          description: |
            Log lines before matched pattern.
          type: array
          items:
            $ref: '#/components/schemas/LineDescriptor'
          minItems: 1
          maxItems: 1024
        lines_after:
          description: |
            Log lines after matched pattern.
          type: array
          items:
            $ref: '#/components/schemas/LineDescriptor'
          minItems: 1
          maxItems: 1024
        line_matching:
          $ref: '#/components/schemas/LineDescriptor'
      example:
        description: Description of an error.
        lines_before:
          - line_number: 1
            data: Line 1 from a log file
          - line_number: 2
            data: Line 2 from a log file
        line_matching:
          line_number: 3
          data: Line 3 from a log file
        lines_after:
          - line_number: 4
            data: Line 4 from a log file
          - line_number: 5
            data: Line 5 from a log file
    LineDescriptor:
      description: |
        Describes the data and line of a pattern-matched log line.
      type: object
      properties:
        line_number:
          type: integer
          minimum: 1
        data:
          type: string
      required:
        - line_number
        - data
    DeviceMonitorConfiguration:
      description: |
        Monitor configuration data.
      allOf:
        - type: object
          properties:
            name:
              type: string
            status:
              type: string
            type:
              type: string
          required:
            - name
            - status
            - type
    MonitorDevice:
      type: object
      properties:
        id:
          type: string
        alerts_open_count:
          type: integer
        alerts_total_count:
          type: integer
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/Alert'
      required:
        - id
        - alerts_open_count
        - alerts_total_count
        - alerts
      example:
        id: eed14d55-d996-42cd-8248-e806663810a8
        alerts_open_count: 1
        alerts_total_count: 1
        alerts:
          - name: mender-connect systemd service
            level: CRITICAL
            device_id: 1298be14-b5ce-4c01-868a-acb93f35e255
            timestamp: '2019-07-21T17:32:28Z'
            type: systemd
            subject:
              name: mender-connect
              status: not-running
              type: systemd.unit
    MonitorConfiguration:
      description: |
        Monitor configuration data.
      allOf:
        - type: object
          properties:
            name:
              type: string
            status:
              type: string
            type:
              type: string
              enum:
                - log
                - service
                - dbus
          required:
            - name
            - status
            - type
        - oneOf:
            - $ref: '#/components/schemas/LogSubsystem'
            - $ref: '#/components/schemas/ServiceSubsystem'
            - $ref: '#/components/schemas/DBusSubsystem'
          discriminator:
            propertyName: type
    LogSubsystem:
      description: |
        log subsystem specific configuration
      type: object
      properties:
        log:
          type: object
          properties:
            pattern:
              description: |
                Log pattern
              type: string
            path:
              description: |
                Path to the log file or command to execute to get the logs (prefixed with '@').
              type: string
            expire_seconds:
              description: |
                Number of seconds after which the pattern is considered expired and an OK is sent
              type: integer
          required:
            - pattern
            - path
    ServiceSubsystem:
      description: |
        service subsystem specific configuration
      type: object
      properties:
        service:
          type: object
          properties:
            name:
              description: |
                Service name
              type: string
            type:
              description: |
                Service type
              type: string
          required:
            - name
            - type
    DBusSubsystem:
      description: |
        dbus subsystem specific configuration
      type: object
      properties:
        dbus:
          type: object
          properties:
            name:
              description: |
                Check name.
              type: string
            pattern:
              description: |
                DBus pattern to look for
              type: string
            watch:
              description: |
                DBus watch expression
              type: string
            alert_expiration:
              description: |
                Number of seconds after which the alert is considered expired and an OK is sent
              type: integer
          required:
            - name
            - watch
            - pattern
    Attribute:
      description: Attribute descriptor.
      example:
        name: ip_addr_eth
        description: Device IP address on ethernet interface
        value: 127.0.0.1
      required:
        - name
        - value
      type: object
      properties:
        name:
          type: string
          description: |
            A human readable, unique attribute ID, e.g. 'device_type', 'ip_addr', 'cpu_load', etc.
        description:
          type: string
          description: Attribute description.
        value:
          oneOf:
            - type: string
            - type: number
            - type: array
              items:
                type: string
            - type: array
              items:
                type: number
          description: |
            The current value of the attribute.

            Attribute type is implicit, inferred from the JSON type.

            Supported types: number, string, array of numbers, array of strings.
            Mixed type arrays are not allowed.
    DeviceNew:
      required:
        - id
      type: object
      properties:
        id:
          type: string
          description: Mender-assigned unique ID.
        updated_ts:
          type: string
          description: Timestamp of the most recent attribute update.
        attributes:
          type: array
          description: A list of attribute descriptors.
          items:
            $ref: '#/components/schemas/Attribute'
      example:
        id: 291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e
        attributes:
          - name: ip_addr
            value: 1.2.3.4
            description: IP address
          - name: mac_addr
            value: 00.01:02:03:04:05
            description: MAC address
    DeviceUpdate:
      required:
        - id
        - revision
      type: object
      properties:
        id:
          type: string
          description: Device identifier.
        revision:
          type: integer
          description: Device object revision.
      description: Object containing device id and device revision of the device to update.
    Groups:
      required:
        - groups
      type: object
      properties:
        groups:
          type: array
          description: List of device's groups.
          items:
            type: string
      example:
        groups:
          - test
          - production
    DevicesInGroupsReq:
      required:
        - devices
        - groups
      type: object
      properties:
        devices:
          type: array
          description: List of device IDs.
          items:
            type: string
        groups:
          type: array
          description: List of group names.
          items:
            type: string
      description: Object containing list of device IDs and list of groups.
    DeviceInventory:
      type: object
      properties:
        id:
          type: string
          description: Mender-assigned unique ID.
        updated_ts:
          type: string
          description: Timestamp of the most recent attribute update.
        attributes:
          type: array
          description: A list of attribute descriptors.
          items:
            $ref: '#/components/schemas/AttributeV2'
      example:
        id: 291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e
        attributes:
          - name: ip_addr
            scope: inventory
            value: 1.2.3.4
            description: IP address
          - name: mac_addr
            scope: inventory
            value: 00.01:02:03:04:05
            description: MAC address
        updated_ts: '2016-10-03T16:58:51.639Z'
    ErrorNotFound:
      type: object
      properties:
        error:
          type: string
          description: Description of the error.
        request_id:
          type: string
          description: Request ID (same as in X-MEN-RequestID header).
      description: Error descriptor.
      example:
        error: filter not found
        request_id: f7881e82-0492-49fb-b459-795654e7188a
    SelectAttribute:
      required:
        - attribute
        - scope
      type: object
      properties:
        attribute:
          type: string
          description: Attribute name.
        scope:
          $ref: '#/components/schemas/Scope'
      description: Inventory attribute
      example:
        attribute: serial_no
        scope: inventory
    FilterPredicate:
      required:
        - attribute
        - scope
        - type
        - value
      type: object
      properties:
        scope:
          $ref: '#/components/schemas/Scope'
        attribute:
          type: string
          description: Attribute name.
        type:
          type: string
          description: |
            Type or operator of the filter predicate.

            | *Operator* | *Name*                       | *Argument type* |
            |:----------:|:-----------------------------|:----------------|
            | $eq        | Equal (`==`)                 | any             |
            | $ne        | Not equal (`!=`)             | any             |
            | $gt        | Greater than (`>`)           | any             |
            | $gte       | Greater than or equal (`>=`) | any             |
            | $lt        | Less than (`<`)              | any             |
            | $lte       | Less than or equal (`<=`)    | any             |
            | $ltne      | Less than or does not exist  | any             |
            | $exists    | Attribute exists             | bool            |
            | $in        | Is an element of             | array           |
            | $nin       | Is not an element of         | array           |
            | $regex     | Regex filter                 | string          |
          enum:
            - $eq
            - $gt
            - $gte
            - $in
            - $lt
            - $lte
            - $ltne
            - $ne
            - $nin
            - $exists
            - $regex
        value:
          type: string
          description: |
            The value of the attribute to be used in filtering.
            Attribute type is implicit, inferred from the JSON type.

            The $exists operator expects a boolean value: true means the specified
            attribute exists, false means the specified attribute doesn't exist.

            The $regex operator expects a string as a Perl compatible regular expression
            (PCRE), automatically anchored by ^. If the regular expression is not valid,
            the filter will produce no results. If you need to specify options and flags,
            you can provide the full regex in the format of /regex/flags, for example
            `/[a-z]+/i`. 
      description: Attribute filter predicate
      example:
        attribute: serial_no
        scope: inventory
        type: $eq
        value: '123456789'
    SortCriteria:
      description: Sort criteria definition
      example:
        attribute: serial_no
        scope: inventory
        order: asc
      required:
        - attribute
        - order
        - scope
      type: object
      properties:
        attribute:
          type: string
          description: Attribute name.
        scope:
          $ref: '#/components/schemas/Scope'
        order:
          type: string
          description: Sort order.
          enum:
            - asc
            - desc
    AttributeV2:
      description: Attribute descriptor with scope (v2 APIs).
      example:
        name: serial_no
        scope: inventory
        description: Serial number
        value: '123456789'
      required:
        - name
        - scope
        - value
      type: object
      properties:
        name:
          type: string
          description: |
            A human readable, unique attribute ID, e.g. 'device_type', 'ip_addr', 'cpu_load', etc.
        scope:
          $ref: '#/components/schemas/Scope'
        description:
          type: string
          description: Attribute description.
        value:
          oneOf:
            - type: string
            - type: number
            - type: array
              items:
                type: string
            - type: array
              items:
                type: number
          description: |
            The current value of the attribute.

            Attribute type is implicit, inferred from the JSON type.

            Supported types: number, string, array of numbers, array of strings.
            Mixed arrays are not allowed.
    Filter:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: string
          description: |
            Unique identifier of the saved filter.
        name:
          type: string
          description: |
            Name of the saved filter.
        terms:
          type: array
          items:
            $ref: '#/components/schemas/FilterPredicate'
      description: Filter definition
      example:
        id: myfilter
        name: My Filter
        terms:
          - scope: inventory
            attribute: serial_no
            type: $eq
            value: '123456789'
    AttributeV1:
      required:
        - name
        - scope
        - value
      type: object
      properties:
        name:
          type: string
          description: |
            A human readable, unique attribute ID, e.g. 'device_type', 'ip_addr', 'cpu_load', etc.
        scope:
          type: string
          description: |
            The scope of the attribute.

            Scope is a string and acts as namespace for the attribute name.
        description:
          type: string
          description: Attribute description.
        value:
          oneOf:
            - type: string
            - type: number
            - type: array
              items:
                type: string
            - type: array
              items:
                type: number
          description: |
            The current value of the attribute.

            Attribute type is implicit, inferred from the JSON type.

            Supported types: number, string, array of numbers, array of strings.
            Mixed type arrays are not allowed.
        timestamp:
          type: string
          description: |
            The date and time of last tag update in RFC3339 format.
          format: date-time
      description: Attribute descriptor.
      example:
        name: ip_addr_eth
        description: Device IP address on ethernet interface
        value: 127.0.0.1
        timestamp: '2016-10-19T17:23:01.639Z'
        scope: inventory
    Tag:
      required:
        - name
        - value
      type: object
      properties:
        name:
          type: string
          description: |
            Tag is an attribute with 'tags' scope.

            A human readable, unique tag ID, e.g. 'location', 'environment', etc.
        description:
          type: string
          description: Tag description.
        value:
          type: string
          description: The current value of the tag.
        timestamp:
          type: string
          description: |
            The date and time of last tag update in RFC3339 format.
          format: date-time
      description: Tag descriptor.
      example:
        name: environment
        description: Test environment
        value: test
        timestamp: '2016-10-19T17:23:01.639Z'
    DeviceInventoryV1:
      type: object
      properties:
        id:
          type: string
          description: Mender-assigned unique device ID.
        updated_ts:
          type: string
          description: Timestamp of the most recent attribute update.
        attributes:
          type: array
          description: A list of attribute descriptors.
          items:
            $ref: '#/components/schemas/AttributeV1'
      example:
        id: 291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e
        attributes:
          - name: ip_addr
            value: 1.2.3.4
            description: IP address
            scope: inventory
          - name: mac_addr
            value: 00.01:02:03:04:05
            description: MAC address
            scope: inventory
        updated_ts: '2016-10-03T16:58:51.639Z'
    Group:
      required:
        - group
      type: object
      properties:
        group:
          type: string
          description: Device group.
      example:
        group: staging
    FilterAttribute:
      required:
        - count
        - name
        - scope
      type: object
      properties:
        name:
          type: string
          description: Name of the attribute.
        scope:
          $ref: '#/components/schemas/Scope'
        count:
          type: integer
          description: Number of occurrences of the attribute in the database.
      description: Filterable attribute
      example:
        name: serial_no
        scope: inventory
        count: 10
    FilterDefinition:
      type: object
      properties:
        name:
          type: string
          description: Name of the filter, must be unique.
          example: My filter
        terms:
          type: array
          description: List of filter predicates, chained with boolean AND operators to build the search condition definition.
          items:
            $ref: '#/components/schemas/FilterPredicate'
      description: Filter definition
    DeviceStatusStatistics:
      type: object
      description: Device statistics grouped by device status
      required:
        - accepted
        - pending
      properties:
        accepted:
          $ref: '#/components/schemas/DeviceCountByTier'
        pending:
          $ref: '#/components/schemas/DeviceCountByTier'
      example:
        accepted:
          standard: 975
          micro: 3546
          system: 0
        pending:
          standard: 2
          micro: 30
          system: 1
    DeviceCountByTier:
      description: Number of devices per tier
      type: object
      required:
        - standard
        - micro
        - system
      properties:
        standard:
          type: number
        micro:
          type: number
        system:
          type: number
    NewDevice:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the new device.
        status:
          type: string
          enum:
            - accepted
            - noauth
            - pending
            - preauthorized
            - rejected
          description: Authorization status for the device.
        auth_sets:
          type: array
          items:
            $ref: '#/components/schemas/AuthSet'
        created_ts:
          type: string
          format: date-time
          description: The creation timestamp of the device.
      required:
        - id
    Integration:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique integration identifier generated by the mender server
        provider:
          type: string
          enum:
            - iot-hub
            - iot-core
            - webhook
        credentials:
          $ref: '#/components/schemas/Credentials'
        description:
          type: string
          description: A short human readable description (max 1024 characters).
        scopes:
          type: array
          items:
            type: string
            enum:
              - deviceauth
              - inventory
          description: |
            An array of scopes for the integration. Currently we support deviceauth
            and inventory scopes. The former will match the events related to a device
            state (accepted, decomissioned), while the latter the inventory changed event.
      required:
        - provider
        - credentials
    Credentials:
      oneOf:
        - $ref: '#/components/schemas/AWSCredentials'
        - $ref: '#/components/schemas/AzureSharedAccessSecret'
        - $ref: '#/components/schemas/HTTP'
      discriminator:
        propertyName: type
        mapping:
          aws: '#/components/schemas/AWSCredentials'
          sas: '#/components/schemas/AzureSharedAccessSecret'
          http: '#/components/schemas/HTTP'
    AWSCredentials:
      type: object
      description: AWS credentials in the form of access key id and secret access key, a region and a device policy name.
      properties:
        type:
          description: The credential type
          type: string
          enum:
            - aws
        aws:
          type: object
          properties:
            access_key_id:
              type: string
            secret_access_key:
              type: string
            region:
              type: string
            device_policy_name:
              type: string
          required:
            - access_key_id
            - secret_access_key
            - region
            - device_policy_name
      required:
        - type
        - aws
    AzureSharedAccessSecret:
      type: object
      description: Shared Access Secret is an authentication mechanism in the form of a connection string for Azure IoT Hub.
      properties:
        type:
          description: The credential type
          type: string
          enum:
            - sas
        connection_string:
          type: string
      required:
        - type
        - connection_string
    DeviceState:
      type: object
      properties:
        desired:
          description: The desired state for the device, as reported by the cloud/user.
          additionalProperties: true
        reported:
          description: State reported by the device, this cannot be changed from the cloud.
          additionalProperties: true
    HTTP:
      type: object
      description: HTTP Webhook configuration.
      properties:
        type:
          description: The credential type
          type: string
          enum:
            - http
        http:
          type: object
          properties:
            url:
              type: string
              description: The destination URL for the webhook. The webhook will send POST requests with event details to this target URL.
            secret:
              type: string
              description: An optional secret used to verify the integrity of the payload. The string must be in hexadecimal format.
              pattern: '[0-9a-f]{1,64}'
          required:
            - url
      required:
        - type
        - http
    Event:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique event identifier generated by the Mender server
        type:
          type: string
          enum:
            - device-provisioned
            - device-decommissioned
            - device-status-changed
            - device-inventory-changed
          description: Type of the event
        delivery_statuses:
          type: array
          items:
            type: object
            properties:
              integration_id:
                type: string
                description: The ID of the integration the status belongs.
              success:
                type: boolean
                description: Whether the event hook was executed successfully.
              status_code:
                type: integer
                description: The (HTTP) status code of the hook.
              error:
                type: string
                description: An error message if the hook failed.
            required:
              - integration_id
              - success
        time:
          type: string
          format: date-time
          description: Creation timestamp
        data:
          oneOf:
            - $ref: '#/components/schemas/DeviceAuthEvent'
            - $ref: '#/components/schemas/DeviceInventoryEvent'
          discriminator:
            propertyName: type
            mapping:
              device-provisioned: '#/components/schemas/DeviceAuthEvent'
              device-decommissioned: '#/components/schemas/DeviceAuthEvent'
              device-status-changed: '#/components/schemas/DeviceAuthEvent'
              device-inventory-changed: '#/components/schemas/DeviceInventoryEvent'
    DeviceAuthEvent:
      type: object
      description: 'DeviceAuthEvent describes an event that relates to changes to a device''s authentication data. The properties included depends on the event type: device provisioning includes the entire device with the accepted authentication set, status change events only includes the device id and the new status, and device decommissioning will only include the device id.'
      properties:
        id:
          type: string
          description: Device unique ID.
        status:
          type: string
          description: The authentication status of the device.
        auth_sets:
          type: array
          items:
            $ref: '#/components/schemas/AuthSet'
        created_ts:
          type: string
          format: date-time
          description: The time the device was initialized in Mender.
      required:
        - id
    DeviceInventoryEvent:
      type: object
      description: DeviceInventoryEvent describes an event that relates to changes to a device's inventory data.
      properties:
        device_id:
          type: string
          description: Device unique ID.
        tenant_id:
          type: string
          description: Tenant ID.
        inventory:
          type: object
          description: Arbitrary key-value pairs of inventory attributes as device has sent them
      required:
        - device_id
        - tenant_id
        - inventory
    TenantUpdateInternal:
      type: object
      description: Update tenant information.
      properties:
        name:
          type: string
          description: Name of the tenant's organization.
        plan:
          type: string
          description: Plan assigned to the tenant account.
          enum:
            - os
            - enterprise
            - professional
        trial:
          type: boolean
          description: Whether this account is free trial.
        trial_expiration:
          type: string
          description: When trial evaluation expires.
          format: date-time
        addons:
          type: array
          description: Addons configuration.
          items:
            $ref: '#/components/schemas/Addon'
        api_limits:
          $ref: '#/components/schemas/TenantApiLimits'
        service_provider:
          type: boolean
          description: True if the tenant is a service provider tenant.
        max_child_tenants:
          type: string
          description: Maximum number of allowed child tenants
        suspend_at:
          type: string
          description: Planned suspention date and time, in ISO8601 format.
        customer_id:
          type: string
        subscription_id:
          type: string
        subscription_type:
          type: string
      example:
        name: Acme
        plan: os
        trial: true
        trial_expiration: '2021-01-01T00:00:00Z'
        suspend_at: '2021-01-01T00:00:00Z'
        api_limits:
          management:
            quota:
              max_calls: 100
              interval_sec: 60
          devices:
            quota:
              max_calls: 1000
              interval_sec: 60
            bursts:
              - action: PATCH
                uri: /api/devices/v1/inventory/device/attributes
                min_interval_sec: 10
              - action: POST
                uri: /api/devices/v1/deployments/device/deployments/next
                min_interval_sec: 60
    Addon:
      type: object
      properties:
        name:
          type: string
          description: Name of the addon (one of ['configure', 'troubleshoot']).
        enabled:
          type: boolean
          description: Enabled/disabled flag.
      description: Mender addon definition.
      example:
        name: troubleshoot
        enabled: true
    TenantAdditionalInfo:
      type: object
      properties:
        marketing:
          type: boolean
          description: Marketing
        campaign:
          type: string
          description: Campaign
      description: Additional information about a tenant.
      example:
        marketing: true
        campaign: Campaign
    ApiBurst:
      type: object
      properties:
        action:
          type: string
          description: HTTP verb.
        uri:
          type: string
          description: URI of the resource subject to the limit.
        min_interval_sec:
          type: integer
          description: Minimum allowed interval, in seconds, between subsequent calls to 'action' on 'uri' (10 = one call every 10 seconds, etc.)
      description: API burst limit definition.
      example:
        action: PATCH
        uri: /api/devices/v1/inventory/device/attributes
        min_interval_sec: 10
    ApiQuota:
      type: object
      properties:
        max_calls:
          type: integer
          description: |
            Maximum allowed number of calls within 'interval'.
            A value of 0 means 'no limit'.
        interval_sec:
          type: integer
          description: Interval definition, in seconds (60 = 1 minute, 3600 = 1 hour, etc.).
      description: API usage quota definition.
      example:
        max_calls: 100
        interval_sec: 3600
    ApiLimits:
      type: object
      properties:
        bursts:
          type: array
          description: Collection of api burst limit definitions over specified API resources.
          items:
            $ref: '#/components/schemas/ApiBurst'
        quota:
          $ref: '#/components/schemas/ApiQuota'
      description: Usage quota and burst limit definitions for an API type.
      example:
        bursts:
          - action: PATCH
            uri: /api/devices/v1/inventory/device/attributes
            min_interval_sec: 10
          - action: POST
            uri: /api/devices/v1/deployments/device/deployments/next
            min_interval_sec: 60
        quota:
          max_calls: 100
          interval_sec: 60
    TenantApiLimits:
      type: object
      properties:
        management:
          $ref: '#/components/schemas/ApiLimits'
        devices:
          $ref: '#/components/schemas/ApiLimits'
      description: API usage quota and burst limit definitions for a tenant - per API type.
      example:
        management:
          quota:
            max_calls: 100
            interval_sec: 60
        devices:
          quota:
            max_calls: 1000
            interval_sec: 60
          bursts:
            - action: PATCH
              uri: /api/devices/v1/inventory/device/attributes
              min_interval_sec: 10
            - action: POST
              uri: /api/devices/v1/deployments/device/deployments/next
              min_interval_sec: 60
    Tenant:
      description: Tenant descriptor.
      required:
        - id
        - name
        - tenant_token
      type: object
      properties:
        id:
          type: string
          description: Tenant ID.
        name:
          type: string
          description: Name of the tenant's organization.
        tenant_token:
          type: string
          description: Currently used tenant token.
        status:
          type: string
          description: Status of the tenant account.
          enum:
            - active
            - suspended
        plan:
          type: string
          description: Plan assigned to the tenant account.
          enum:
            - os
            - enterprise
            - professional
        trial:
          type: boolean
          description: Whether this account is free trial.
        trial_expiration:
          type: string
          description: When trial evaluation expires.
          format: date-time
        addons:
          type: array
          description: Addons configuration.
          items:
            $ref: '#/components/schemas/Addon'
        service_provider:
          type: boolean
          description: Whether this account is a service provider.
        parent_tenant_id:
          type: string
          description: The ID of the service provider tenant managing this tenant.
        additional_info:
          $ref: '#/components/schemas/TenantAdditionalInfo'
        api_limits:
          $ref: '#/components/schemas/TenantApiLimits'
        created_at:
          type: string
          description: Creation date and time, in ISO8601 format.
        updated_at:
          type: string
          description: Last update date and time, in ISO8601 format.
        device_count:
          type: integer
          description: Count of accepted devices for the tenant.
        device_limit:
          type: integer
          description: Device limit for the tenant.
        device_limits:
          type: object
          properties:
            max_devices:
              $ref: '#/components/schemas/DeviceLimitTenant'
            max_micro_devices:
              $ref: '#/components/schemas/DeviceLimitTenant'
            max_system_devices:
              $ref: '#/components/schemas/DeviceLimitTenant'
      example:
        id: 507f191e810c19729de860ea
        name: Acme
        tenant_token: RAA2O7A854tyU/AGM4gLN+vs+oFo7pNW
        status: active
        plan: os
        api_limits:
          management:
            quota:
              max_calls: 100
              interval_sec: 60
          devices:
            quota:
              max_calls: 1000
              interval_sec: 60
            bursts:
              - action: PATCH
                uri: /api/devices/v1/inventory/device/attributes
                min_interval_sec: 10
              - action: POST
                uri: /api/devices/v1/deployments/device/deployments/next
                min_interval_sec: 60
        created_at: '2019-12-12T12:00:00Z'
        updated_at: '2023-11-10T15:15:00Z'
    TenantStatus:
      required:
        - status
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - suspended
      description: Status of a tenant account.
      example:
        status: active
    CardData:
      type: object
      properties:
        brand:
          type: string
          description: Card brand. Can be `amex`, `diners`, `discover`, `jcb`, `mastercard`, `unionpay`, `visa`, or `unknown`.
        checks:
          type: object
          properties:
            address_line1_check:
              type: string
            address_postal_code_check:
              type: string
            cvc_check:
              type: string
          description: Checks on Card address and CVC if provided.
        country:
          type: string
          description: Two-letter ISO code representing the country of the card. You could use this attribute to get a sense of the international breakdown of cards you've collected.
        exp_month:
          type: integer
          description: Two-digit number representing the card's expiration month.
        exp_year:
          type: integer
          description: Four-digit number representing the card's expiration year.
        fingerprint:
          type: string
          description: Uniquely identifies this particular card number. You can use this attribute to check whether two customers who’ve signed up with you are using the same card number,for example. For payment methods that tokenize card information (Apple Pay, Google Pay), the tokenized number might be provided instead of the underlying card number.
        funding:
          type: string
          description: Card funding type. Can be `credit`, `debit`, `prepaid`, or `unknown`.
        last4:
          type: string
          description: The last four digits of the card.
        three_d_secure_usage:
          type: object
          properties:
            supported:
              type: boolean
          description: Contains details on how this Card maybe be used for 3D Secure authentication.
        wallet:
          type: object
          properties:
            dynamic_last4:
              type: string
            type:
              type: string
          description: If this Card is part of a card wallet, this contains the details of the card wallet.
      description: Card information stored in Stripe. The full type description is available at "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.yaml#/components/schemas/payment_method_card"
    SubscriptionData:
      type: object
      additionalProperties: true
      description: Subscription information stored in Stripe. The full type description is available at "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.yaml#/components/schemas/subscription"
      example:
        id: sub_36VrPHS2vVxJMq
        object: subscription
        billing_cycle_anchor: 1387222772
        cancel_at_period_end: false
        canceled_at: 1445989053
        collection_method: charge_automatically
        created: 1386790772
        current_period_end: 1447702772
        current_period_start: 1444678772
        customer: cus_36Akh5CetFGg9T
        default_tax_rates: []
        ended_at: 1445989053
        items:
          object: list
          data:
            - id: si_18SfBn2eZvKYlo2C1fwOImYF
              object: subscription_item
              created: 1386790772
              metadata: {}
              price:
                id: '40'
                object: price
                active: true
                billing_scheme: per_unit
                created: 1386694689
                currency: usd
                livemode: false
                metadata:
                  charset: utf-8
                  content: '40'
                product: prod_BTcfj5EqyqxDVn
                recurring:
                  interval: week
                  interval_count: 5
                  usage_type: licensed
                type: recurring
                unit_amount: 5465
                unit_amount_decimal: '5465'
              quantity: 1
              subscription: sub_36VrPHS2vVxJMq
              tax_rates: []
          has_more: false
          url: /v1/subscription_items?subscription=sub_36VrPHS2vVxJMq
        livemode: false
        metadata: {}
        start_date: 1386790772
        status: canceled
        trial_end: 1387222772
        trial_start: 1386790772
    BillingInfo:
      type: object
      properties:
        card:
          $ref: '#/components/schemas/CardData'
        subscription:
          $ref: '#/components/schemas/SubscriptionData'
      description: Billing related data, such as credit card information and next billing date
      example:
        card:
          brand: Visa
          checks:
            address_line1_check: pass
            address_postal_code_check: pass
            cvc_check: pass
          country: 'no'
          description: ''
          exp_month: 2
          exp_year: 2020
          fingerprint: fingerprint
          funding: all
          iin: ''
          issuer: ''
          last4: '1234'
          three_d_secure_usage:
            supported: true
          wallet:
            dynamic_last4: '6789'
            type: visa_checkout
        subscription:
          id: sub_36VrPHS2vVxJMq
          object: subscription
          billing_cycle_anchor: 1387222772
          cancel_at_period_end: false
          canceled_at: 1445989053
          collection_method: charge_automatically
          created: 1386790772
          current_period_end: 1447702772
          current_period_start: 1444678772
          customer: cus_36Akh5CetFGg9T
          default_tax_rates: []
          ended_at: 1445989053
          items:
            object: list
            data:
              - id: si_18SfBn2eZvKYlo2C1fwOImYF
                object: subscription_item
                created: 1386790772
                metadata: {}
                price:
                  id: '40'
                  object: price
                  active: true
                  billing_scheme: per_unit
                  created: 1386694689
                  currency: usd
                  livemode: false
                  metadata:
                    charset: utf-8
                    content: '40'
                  product: prod_BTcfj5EqyqxDVn
                  recurring:
                    interval: week
                    interval_count: 5
                    usage_type: licensed
                  type: recurring
                  unit_amount: 5465
                  unit_amount_decimal: '5465'
                quantity: 1
                subscription: sub_36VrPHS2vVxJMq
                tax_rates: []
            has_more: false
            url: /v1/subscription_items?subscription=sub_36VrPHS2vVxJMq
          livemode: false
          metadata: {}
          start_date: 1386790772
          status: canceled
          trial_end: 1387222772
          trial_start: 1386790772
    CardSetupData:
      required:
        - intent_id
        - secret
      type: object
      properties:
        intent_id:
          type: string
          description: Setup intent id.
        secret:
          type: string
          description: Setup intent secret.
      description: Stripe setup intent data.
      example:
        intent_id: seti_1HXHVn2eZvKYlo2CT3XEEjKB
        secret: TYooMQauvdEDq54NiTphI7jx
    AddressUpdate:
      type: object
      properties:
        country:
          type: string
        state:
          type: string
        city:
          type: string
        postal_code:
          type: string
        line1:
          type: string
        line2:
          type: string
    Address:
      allOf:
        - $ref: '#/components/schemas/AddressUpdate'
        - required:
            - country
            - city
            - postal_code
            - line1
    BillingProfile:
      required:
        - address
        - email
        - name
        - shipping
      type: object
      properties:
        email:
          type: string
          description: The customer's email address.
        name:
          type: string
          description: The customer's full name or business name.
        phone:
          type: string
          description: The customer's phone number.
        address:
          type: object
          allOf:
            - $ref: '#/components/schemas/Address'
            - description: The customer's address.
        shipping:
          type: object
          properties:
            name:
              type: string
              description: Name of the recipient.
            phone:
              type: string
              description: Phone number of the recipient (including extension).
            address:
              type: object
              allOf:
                - $ref: '#/components/schemas/Address'
                - description: Address of the recipient.
          description: |
            Mailing and shipping address for the customer. Appears on invoices.
      description: |
        Billing profile contains information about the customer.
    BillingProfileUpdate:
      type: object
      properties:
        email:
          type: string
          description: The customer's email address.
        name:
          type: string
          description: The customer's full name or business name.
        phone:
          type: string
          description: The customer's phone number.
        address:
          type: object
          allOf:
            - $ref: '#/components/schemas/AddressUpdate'
            - description: The customer's address.
        shipping:
          type: object
          properties:
            name:
              type: string
              description: Name of the recipient.
            phone:
              type: string
              description: Phone number of the recipient (including extension).
            address:
              type: object
              allOf:
                - $ref: '#/components/schemas/AddressUpdate'
                - description: Address of the recipient.
          description: |
            Mailing and shipping address for the customer. Appears on invoices.
      description: Billing profile contains partial billing information.
    Invoice:
      type: object
      properties:
        id:
          type: string
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        total:
          type: number
          description: |
            Total amount in the minimum transactable unit for the given currency (cents for USD).
        currency:
          type: string
          description: The currency of the amount
        lines:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLineItem'
    InvoiceLineItem:
      required:
        - amount
        - currency
        - description
        - quantity
      type: object
      properties:
        description:
          type: string
          description: A human readable description of the item.
        quantity:
          type: number
          description: The number of units for the given line item.
        amount:
          type: number
          description: The amount in the minimum transactable unit for the given currency (cents for USD).
        currency:
          type: string
          description: The currency of amount.
        product:
          type: string
          description: The name of the product for this item.
        addon:
          type: string
          description: The name of the addon for this item if this is an addon.
        proration:
          type: boolean
          description: Whether this item was generated to prorate changes to the subscription within the subscription period.
    PreviewRequest:
      allOf:
        - $ref: '#/components/schemas/SubscriptionRequest'
        - type: object
          properties:
            preview_mode:
              type: string
              enum:
                - next
                - recurring
      example:
        application/json:
          preview_mode: recurring
          products:
            - name: mender_standard
              quantity: 100
    Subscription:
      allOf:
        - $ref: '#/components/schemas/SubscriptionRequest'
        - type: object
          properties:
            id:
              type: string
              description: The unique subscription ID.
            status:
              type: string
              description: The subscription status.
              enum:
                - active
                - canceled
                - incomplete
                - past_due
                - unpaid
    SubscriptionRequest:
      type: object
      properties:
        plan:
          $ref: '#/components/schemas/TenantPlan'
        products:
          type: array
          description: The requested product and additional properties like quantity and addons
          items:
            $ref: '#/components/schemas/Product'
      example:
        plan: os
        products:
          - name: mender_standard
            plan: professional
            quantity: 500
            addons:
              - name: configure
              - name: troubleshoot
    Product:
      required:
        - quantity
      type: object
      properties:
        name:
          type: string
          enum:
            - mender_standard
        quantity:
          type: number
        addons:
          type: array
          items:
            $ref: '#/components/schemas/Addon'
    TenantPlan:
      type: string
      description: Plan assigned to the tenant account.
      default: os
      enum:
        - os
        - professional
        - enterprise
    CheckoutData:
      required:
        - secret
      type: object
      properties:
        secret:
          type: string
          description: Stripe client secret.
      description: Checkout data.
      example:
        secret: TYooMQauvdEDq54NiTphI7jx
    SupportRequest:
      required:
        - body
        - subject
      type: object
      properties:
        subject:
          type: string
          description: Message subject.
        body:
          type: string
          description: Message body.
      description: Contact support request.
      example:
        subject: Subscription change request
        body: 'Requested addons: Troubleshoot, Configure'
    NewTenant:
      type: object
      properties:
        name:
          type: string
          description: Name of the tenant.
        admin:
          type: object
          properties:
            email:
              type: string
              description: Email address of the admin user
            password:
              type: string
              description: Password of the admin user, must be provided if not using SSO
            login:
              type: object
              additionalProperties: true
              description: Alternative SSO login schemes, must be provided if password is empty
            send_reset_password:
              type: boolean
              description: Send reset password email to the admin user
        users:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
                description: Email address of an existing user to be added to the newly created tenant
              role:
                type: string
                description: Role of the user to be added
        device_limit:
          type: integer
          description: Device limit for the tenant.
        binary_delta:
          type: boolean
          description: Enable server side binary delta generation for the tenant.
        sso:
          type: boolean
          description: |
            Inherit single sign-on configuration from service provider.
            The new tenant will not be able to modify the SSO configuration.
      description: New Tenant
    CancelRequest:
      required:
        - reason
      type: object
      properties:
        reason:
          type: string
      description: Cancellation request of a tenant account.
      example:
        reason: Reason for cancelling the tenant
    UpdateChildTenant:
      type: object
      properties:
        name:
          type: string
          description: Name of the tenant.
        device_limit:
          type: integer
        device_limits:
          type: object
          properties:
            max_devices:
              $ref: '#/components/schemas/DeviceLimitPut'
            max_micro_devices:
              $ref: '#/components/schemas/DeviceLimitPut'
            max_system_devices:
              $ref: '#/components/schemas/DeviceLimitPut'
      description: Update Tenant
    DeviceLimitPut:
      description: Device limit.
      type: object
      properties:
        Name:
          type: string
        value:
          type: integer
      required:
        - Name
        - value
      example:
        Name: max_micro_devices
        value: 1024
    PlanChangeRequest:
      type: object
      properties:
        current_plan:
          type: string
        requested_plan:
          type: string
        current_addons:
          type: string
        requested_addons:
          type: string
        user_message:
          type: string
      description: Plan/add-on change request of a tenant account.
      example:
        current_plan: Professional
        requested_plan: Enterprise
        current_addons: troubleshoot
        requested_addons: troubleshoot, configure
        user_message: User message
    User:
      required:
        - email
        - id
      type: object
      properties:
        email:
          type: string
          description: A unique email address.
        id:
          type: string
          description: User Id.
        created_ts:
          type: string
          description: |
            Server-side timestamp of the user creation.
          format: date-time
        updated_ts:
          type: string
          description: |
            Server-side timestamp of the last user information update.
          format: date-time
        login_ts:
          type: string
          description: Timestamp the of last successful login.
          format: date-time
        verified:
          type: boolean
          description: |
            Indicates if the user's email address has been verified.
        tfa_status:
          type: string
          description: User Two Factor Authentication status.
        roles:
          type: array
          description: List of user roles.
          items:
            title: ListOfRoles
            type: string
            description: Role name
        send_reset_password:
          type: boolean
          description: Flag indicating wether to trigger password reset on user creation.
      description: User descriptor.
      example:
        email: user@acme.com
        id: 806603def19d417d004a4b67e
        created_ts: '2020-07-06T15:04:49.114046203+02:00'
        updated_ts: '2020-07-07T01:04:49.114046203+02:00'
    TenantInfo:
      type: object
      properties:
        tenant_id:
          type: string
          description: Tenant identifier of a tenant, user will log in to by default.
        tenant_ids:
          type: array
          description: List of tenant Ids user can login to.
          items:
            type: string
    TenantIdName:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: string
          description: Tenant identifier.
        name:
          type: string
          description: Tenant name.
    TenantsIdName:
      type: array
      items:
        $ref: '#/components/schemas/TenantIdName'
    UserWithTenantInfo:
      allOf:
        - $ref: '#/components/schemas/User'
        - $ref: '#/components/schemas/TenantInfo'
        - type: object
          properties:
            tenants:
              $ref: '#/components/schemas/TenantsIdName'
    UserNewInternal:
      required:
        - email
        - password
      type: object
      properties:
        email:
          type: string
          description: User's email.
          format: email
        password:
          type: string
          description: User's password.
        propagate:
          type: boolean
          description: |
            This paramter is deprecated _since Thu Jul 6 2023_, the propagation
            of user information to tenantadm is disabled permanently.
        magic_id:
          type: string
          description: Unique id to allow a user to log in using a magic link
          format: uuid
        send_reset_password:
          type: boolean
          description: Send reset password email to the user
      description: New user descriptor.
      example:
        email: user@acme.com
        password: secret
        propagate: false
        magic_id: a30a780b-b843-5344-80e3-0fd95a4f6fc3
    Emails:
      required:
        - emails
      type: object
      properties:
        emails:
          type: array
          description: List of users emails.
          items:
            type: string
      example:
        emails:
          - demo@example.com
          - admin@example.com
    UseradmLimit:
      required:
        - max
      type: object
      properties:
        count:
          type: integer
        max:
          type: integer
      description: Tenant account limits.
      example:
        count: 10
        max: 20
    Limits:
      required:
        - users
      type: object
      properties:
        users:
          $ref: '#/components/schemas/UseradmLimit'
      description: Tenant account limits.
      example:
        users:
          max: 10
          count: 2
        limit: 123
    Features:
      type: object
      properties:
        rbac:
          type: boolean
        audit_logs:
          type: boolean
        dynamic_groups:
          type: boolean
        terminal:
          type: boolean
        file_transfer:
          type: boolean
        configuration:
          type: boolean
        monitoring:
          type: boolean
        reporting:
          type: boolean
      description: Features descriptor.
      example:
        rbac: true
        audit_logs: false
        dynamic_groups: false
        terminal: true
        file_transfer: true
        configuration: true
        monitoring: true
        reporting: true
    Plan:
      required:
        - display_name
        - features
        - name
      type: object
      properties:
        name:
          type: string
          description: |
            Unique name of the plan.
        display_name:
          type: string
          description: |
            Short information about the plan.
        features:
          $ref: '#/components/schemas/Features'
      description: Plan descriptor.
      example:
        name: mender-enterprise
        display_name: Mender Enterprise
        features:
          rbac: true
          audit_logs: false
          dynamic_groups: false
          terminal: true
          file_transfer: true
          configuration: true
          monitoring: true
    PlanLimits:
      type: object
      properties:
        devices:
          type: integer
        users:
          type: integer
        audit_logs_days:
          type: integer
      description: Plan limits descriptor.
      example:
        devices: 10
        users: 2
        audit_logs_days: 2
    PlanBindingDetails:
      type: object
      properties:
        plan:
          $ref: '#/components/schemas/Plan'
        limits:
          $ref: '#/components/schemas/PlanLimits'
      description: Combination of plan and limits objects.
      example:
        plan:
          product: Mender
          name: mender-enterprise
          display_name: Mender Enterprise
          features:
            rbac: true
            audit_logs: true
        limits:
          devices: 10
          users: 2
          audit_logs_days: 2
    PlanBinding:
      type: object
      properties:
        plan_name:
          type: string
        limits:
          $ref: '#/components/schemas/PlanLimits'
      description: Combination of plan and limits objects.
      example:
        plan_name: mender-enterprise
        limits:
          devices: 10
          users: 2
          audit_logs_days: 2
    TenantIdsData:
      required:
        - tenant_ids
      type: object
      properties:
        tenant_ids:
          type: array
          items:
            title: ListOfIds
            type: string
            description: tenant ids
        role:
          type: string
          description: 'Optional RBAC role name to assign to the user. Defaults to: RBAC_ROLE_OBSERVER.'
      description: Tenant ids data.
      example:
        tenant_ids:
          - 65c76fd6e15517b2f0fbfdf1
          - 65c76fda5e6177ca400a9d4d
        role: RBAC_ROLE_OBSERVER
    LoginOptions:
      type: object
      properties:
        no_expiry:
          type: boolean
          description: Generate a JWT token with no expiration date.
        token2fa:
          type: string
          description: |
            Two factor authentication token, required if two factor authentication is
              enabled and tenant's plan is Professional or Enterprise.
      description: Log in options
      example:
        no_expiry: true
        token2fa: '012234'
    UserNew:
      required:
        - email
      type: object
      properties:
        email:
          type: string
          description: A unique email address. Non-ascii characters are invalid.
        password:
          type: string
          description: Password.
        login:
          type: object
          additionalProperties: true
          description: Alternative login schemes
        sso:
          type: array
          description: SSO login schemes
          items:
            $ref: '#/components/schemas/SsoObject'
      description: New user descriptor.
      example:
        email: user@acme.com
        password: mypass1234
        login:
          google: bob@gmail.com
    SsoObject:
      required:
        - id
        - kind
      type: object
      properties:
        id:
          type: string
          description: An id of the identity provider.
          format: uuid
        kind:
          type: string
          description: Single Sign On provider kind.
        subject:
          type: string
          description: Single Sign On subject.
      description: Single Sign On descriptor.
      example:
        id: 84430f18-d464-5194-b8ef-b1a15161bb4c
        kind: sso/saml
    UserUpdate:
      type: object
      properties:
        email:
          type: string
          description: A unique email address.
        password:
          type: string
          description: New password.
        current_password:
          type: string
          description: Current password.
        roles:
          type: array
          description: List of roles for the user. If not provided existing roles are kept.
          items:
            title: ListOfRoles
            type: string
            description: Role name
      description: Update user information.
      example:
        email: new_email@acme.com
        roles:
          - RBAC_ROLE_DEPLOY_GROUP_TESTING_DEVICES
          - RBAC_ROLE_READ_ONLY
        password: new password
        current_password: old password
    OwnUserUpdate:
      type: object
      properties:
        email:
          type: string
          description: A unique email address.
        password:
          type: string
          description: New password.
        current_password:
          type: string
          description: Current password.
      description: Update user information.
      example:
        email: new_email@acme.com
        password: new password
        current_password: old password
    PersonalAccessTokenRequest:
      required:
        - name
      type: object
      properties:
        name:
          type: string
          description: Name of a token.
        expires_in:
          type: integer
          description: |
            Expiration time in seconds (maximum one year - 31536000s).
            If you omit it or set it to zero, the Personal Access Token will never expire.
      description: Personal Access Token Request.
      example:
        name: my_personal_token
        expires_in: 28800
    PersonalAccessToken:
      required:
        - created_ts
        - expiration_date
        - id
        - name
      type: object
      properties:
        id:
          type: string
          description: Token identifier.
        name:
          type: string
          description: Name of a token.
        last_used:
          type: string
          description: |
            Date of last usage of a token. The accuracy is 5 minutes.
          format: date-time
        expiration_date:
          type: string
          description: Expiration date.
          format: date-time
        created_ts:
          type: string
          description: |
            Server-side timestamp of the token creation.
          format: date-time
      description: Personal Access Token Object.
      example:
        id: 806603def19d417d004a4b67e
        name: my_personal_token
        last_used: '2022-07-05T11:11:35.725Z'
        expiration_date: '2023-10-16T07:28:34.725Z'
        created_ts: '2022-07-05T11:03:27.725Z'
    Settings:
      type: object
      properties:
        2fa:
          type: string
          description: Enable/disable two-factor authentication for this user.
          enum:
            - enabled
            - disabled
          x-mender-plan:
            - professional
            - enterprise
      description: User settings.
    PasswordResetRequest:
      required:
        - email
      type: object
      properties:
        email:
          type: string
          description: User's email address
      description: Password reset request
      example:
        email: user@mender.io
    PasswordResetCompletion:
      required:
        - password
        - secret
      type: object
      properties:
        secret:
          type: string
          description: Secret hash received by email by the user
        password:
          type: string
          description: New password of the user
      description: Password reset completion
      example:
        secret: 16fd2706-8baf-433b-82eb-8c7fada847da
        password: new password
    EmailVerificationRequest:
      required:
        - email
      type: object
      properties:
        email:
          type: string
          description: User's email address
      description: Email Verification request
      example:
        email: user@mender.io
    EmailVerificationCompletion:
      required:
        - secret
      type: object
      properties:
        secret:
          type: string
          description: Secret hash received by email by the user
      description: Email Verification completion
      example:
        secret: 16fd2706-8baf-433b-82eb-8c7fada847da
    SAMLMetadata:
      required:
        - id
        - issuer
        - valid_until
      type: object
      properties:
        id:
          type: string
          description: Metadata Id.
          format: uuid
        issuer:
          type: string
          description: Metadata Issuer.
        valid_until:
          type: string
          description: Date after which the data is not valid.
          format: date-time
      description: Metadata structure.
      example:
        id: 84430f18-d464-5194-b8ef-b1a15161bb4c
        issuer: https://samltest.id/saml/idp
        valid_until: '2038-08-24T21:14:09Z'
    RoleV1:
      required:
        - name
      type: object
      properties:
        name:
          type: string
          description: A unique name.
        description:
          type: string
          description: Description of the role, as shown in the UI.
        permission_sets_with_scope:
          type: array
          items:
            $ref: '#/components/schemas/PermissionSetWithScope'
      description: Role descriptor.
      example:
        name: RBAC_ROLE_NAME
        description: Description of the role
        permission_sets_with_scope:
          - name: ReadReleases
          - name: ReadDevices
            scope:
              type: DeviceGroups
              value:
                - test
                - dev
    PermissionSetWithScope:
      required:
        - name
      type: object
      properties:
        name:
          type: string
          description: Unique permission set name.
        scope:
          $ref: '#/components/schemas/PermissionSetScope'
      description: Permission set with optional scope.
    PermissionSetScope:
      required:
        - type
        - value
      type: object
      properties:
        type:
          type: string
          description: Type of the scope.
          enum:
            - DeviceGroups
            - ReleaseTags
        value:
          type: array
          items:
            type: string
      example:
        type: DeviceGroups
        value:
          - test
          - development
    Role:
      required:
        - name
      type: object
      properties:
        name:
          type: string
          description: A unique name.
        description:
          type: string
          description: Description of the role, as shown in the UI.
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/RolePermission'
      description: Role descriptor.
      example:
        name: RBAC_ROLE_NAME
        description: Description of the role
        permissions:
          - action: http
            object:
              type: GET
              value: /api/v1/endpoint
          - action: http
            object:
              type: POST
              value: /api/v1/endpoint
    RolePermission:
      required:
        - action
        - object
      type: object
      properties:
        action:
          type: string
          description: Action
          enum:
            - any
            - http
            - CREATE_DEPLOYMENT
            - MANAGE_DEVICE
            - REMOTE_TERMINAL
            - VIEW_DEVICE
        object:
          $ref: '#/components/schemas/RolePermissionObject'
      description: Role permission
      example:
        action: http
        object:
          type: GET
          value: .*
    RolePermissionObject:
      required:
        - type
        - value
      type: object
      properties:
        type:
          type: string
          description: Type
        value:
          type: string
          description: Value
      description: Role permission object
      example:
        type: POST
        value: /api/v1/endpoint
    PermissionSet:
      required:
        - name
        - permissions
      type: object
      properties:
        name:
          type: string
          description: A unique name.
        action:
          type: string
        object:
          type: string
        description:
          type: string
          description: Description of the permission set.
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        supported_scope_types:
          type: array
          items:
            type: string
      description: Permission set descriptor.
    Permission:
      required:
        - action
        - object
      type: object
      properties:
        action:
          type: string
          description: Action
          enum:
            - any
            - http
        object:
          $ref: '#/components/schemas/PermissionObject'
      example:
        action: http
        object:
          type: GET
          value: .*
    PermissionObject:
      required:
        - type
        - value
      type: object
      properties:
        type:
          type: string
          description: Type
        value:
          type: string
          description: Value
      example:
        type: POST
        value: /api/v1/endpoint
    FeedbackProduct:
      type: object
      properties:
        score:
          type: integer
          description: User satisfaction
          minimum: 1
          maximum: 5
        message:
          type: string
          description: Optional feedback from the user.
          maxLength: 2000
      description: General product feedback
    FeedbackAI:
      required:
        - deployment_id
        - device_id
        - useful
      type: object
      properties:
        useful:
          type: boolean
          description: Was this feature useful?
        deployment_id:
          type: string
          description: The deployment ID where this feedback was triggered for context.
          format: uuid
        device_id:
          type: string
          description: The device ID where this feedback was triggered for context.
          format: uuid
      description: AI feedback form.
    CLIParams:
      type: object
      properties:
        command:
          type: array
          items:
            type: string
        executionTimeOut:
          type: integer
      description: CLI parameters
    HTTPParams:
      type: object
      properties:
        uri:
          type: string
        method:
          type: string
        contentType:
          type: string
        body:
          type: string
        json:
          type: object
          properties: {}
        headers:
          type: object
          properties: {}
        statusCodes:
          type: array
          items:
            type: integer
        connectionTimeOut:
          type: integer
        readTimeOut:
          type: integer
      description: HTTP parameters
    Task:
      required:
        - name
        - type
      type: object
      properties:
        name:
          type: string
        type:
          type: string
        retries:
          type: integer
        retryDelaySeconds:
          type: integer
        requires:
          type: array
          items:
            type: string
        cli:
          $ref: '#/components/schemas/CLIParams'
        http:
          $ref: '#/components/schemas/HTTPParams'
      description: Task definition
    Workflow:
      required:
        - name
        - tasks
        - version
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        version:
          type: integer
        schemaversion:
          type: integer
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        inputParameters:
          type: array
          items:
            type: string
    JobObject:
      type: object
      properties:
        id:
          type: string
        workflowName:
          type: string
        inputParameters:
          type: array
          items:
            $ref: '#/components/schemas/InputParameter'
        status:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/TaskResult'
        insert_time:
          type: string
          format: date-time
        version:
          type: string
  securitySchemes:
    ManagementJWT:
      type: http
      description: |
        API token issued by User Authentication service.
      scheme: bearer
      bearerFormat: JWT
    DeviceJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        API token issued by Device Authentication service.
        Format: 'Authorization: Bearer [JWT]'
    Login:
      type: http
      scheme: basic
  parameters:
    Authentication:
      name: authorization
      in: header
      description: The token in base64-encoded form.
      required: false
      schema:
        type: string
    RequestId:
      name: X-MEN-RequestID
      in: header
      required: false
      description: A request identification
      schema:
        type: string
x-tagGroups:
  - name: Mender API
    tags:
      - Mender_API_Mender API
  - name: Audit Logs
    tags:
      - Audit_Logs_Internal API
      - Audit_Logs_Auditlogs Internal
      - Audit_Logs_Management API
      - Audit_Logs_Auditlogs Management
  - name: Deployments
    tags:
      - Deployments_Device API
      - Deployments_Management API
  - name: Deployments v2
    tags:
      - Deployments_v2_Device API
      - Deployments_v2_Management API
  - name: Deployments Internal API
    tags:
      - Deployments_Internal_API_Internal API
  - name: Device Authentication
    tags:
      - Device_Authentication_Device API
      - Device_Authentication_Internal API
      - Device_Authentication_Management API
  - name: Device configure
    tags:
      - Device_configure_Device API
      - Device_configure_Internal API
      - Device_configure_Management API
  - name: Device connect
    tags:
      - Device_connect_Device API
      - Device_connect_Internal API
      - Device_connect_Management API
  - name: Device monitor
    tags:
      - Device_monitor_Devices API
      - Device_monitor_Internal API
      - Device_monitor_Management API
  - name: Device inventory
    tags:
      - Device_inventory_Device API
      - Device_inventory_Internal API
      - Device_inventory_Management API
  - name: Device inventory filters and search
    tags:
      - Device_inventory_filters_and_search_Internal API
      - Device_inventory_filters_and_search_Management API
  - name: IoT Manager
    tags:
      - IoT_Manager_Internal API
      - IoT_Manager_Management API
  - name: Tenants APIs
    tags:
      - Tenants_APIs_Internal API
      - Tenants_APIs_Tenantadm Internal
      - Tenants_APIs_Management API
      - Tenants_APIs_Tenantadm Management
  - name: Tenants APIs v2
    tags:
      - Tenants_APIs_v2_Management API
      - Tenants_APIs_v2_Tenantadm Management v2
  - name: User administration and authentication
    tags:
      - User_administration_and_authentication_Internal API
  - name: User Administration
    tags:
      - User_Administration_Management API
  - name: User Administration v2
    tags:
      - User_Administration_v2_Management API
  - name: Workflows
    tags:
      - Workflows_other
