openapi: 3.0.3
info:
  title: WithSecure™ Elements API
  description: WithSecure™ Elements API
  version: ''
servers:
  - url: 'https://api.connect.withsecure.com'
    description: Production environment
  - url: 'https://api.connect-stg.fsapi.com'
    description: Staging environment
  - url: 'https://api.connect-ci.fsapi.com'
    description: CI environment
components:
  securitySchemes:
    basic:
      type: http
      scheme: basic
      description: Client credentials.
    oAuth2:
      type: http
      scheme: bearer
      description: API access token.
tags:
  - name: authentication
    description: Authenticate and obtain access tokens for Elements API.
  - name: API keys
    description: Manage API keys (credentials) for accessing the Elements API.
  - name: organizations
    description: Organizations information.
  - name: security events
    description: Security events information.
  - name: devices
    description: Devices information and actions.
  - name: Broad Context Detections (BCDs)
    description: 'Access and manage XDR Broad Context Detections (BCDs). In the Elements API, the BCD endpoint name is "incidents".'
  - name: Response actions
    description: Manage and monitor response actions execution.
  - name: Device response actions
    description: 'Execute response actions on devices (Windows, macOS, Linux).'
  - name: Identity response actions
    description: Execute response actions for Microsoft Entra ID identities.
  - name: invitations
    description: Manage invitations for devices.
  - name: software updates
    description: Manage software updates for devices.
  - name: databases
    description: Manage databases for devices.
  - name: whoami
    description: Get information about the currently authenticated user.
paths:
  /as/token.oauth2:
    post:
      tags:
        - authentication
      security:
        - basic: []
      operationId: oAuthToken
      summary: Authenticate
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
      description: |
        <p>
          Access to Elements API is granted using OAuth 2.0 authentication with the client credentials flow. The obtained token is used in subsequent requests.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -X POST -d "grant_type=client_credentials" -d "scope=connect.api.read connect.api.write" -u "{client_id}:{client_secret}" https://api.connect.withsecure.com/as/token.oauth2
          </code>
        </p> <p>
          The request will fail if parameters other than those allowed are sent in the payload.
        </p>
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                  example: client_credentials
                scope:
                  type: string
                  description: |
                    Used to determine access to the Elements API endpoints.  Must match the scope registered for the client during client credentials creation.  Multiple scopes should be separated by space.
                  example:
                    - connect.api.read
                    - connect.api.write
                    - connect.api.read connect.api.write
              required:
                - grant_type
      responses:
        '200':
          description: Bearer token and metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: Token value that can be used in subsequent requests to Elements API.
                  token_type:
                    type: string
                    description: The type of the token issued.
                  expires_in:
                    type: integer
                    description: |
                      The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
                example:
                  access_token: eHcMH7mMmrVK2vaTMnqwRk8ono4yVeBMO6/x2L887as
                  token_type: Bearer
                  expires_in: 1799
        '400':
          description: Bad request due to invalid parameters or data.
          headers:
            X-Transaction:
              description: Internal transaction ID to trace the request on demand.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                    description: 'Error code as described in [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-5.2)'
                  error_description:
                    type: string
                    description: |
                      Human-readable text providing additional information to assist the client developer in understanding the error that occurred.
              examples:
                Authorization header has wrong format:
                  description: |
                    Indicates that credentials can't be decoded from the Authorization HTTP header. The Authorization header must match the format `Basic base_64(${client_name}:${password})`.
                  value:
                    error: invalid_request
                    error_description: Authorization header has wrong format
                Request contains not allowed parameters:
                  description: |
                    Only parameters and values mentioned in the API specification are allowed.
                  value:
                    error: invalid_request
                    error_description: Request contains not allowed parameters
                Required grant is missing:
                  description: |
                    The `grant_type` parameter is missing or has an invalid value.
                  value:
                    error: unsupported_grant_type
                    error_description: Required grant is missing
                Scope parameter is invalid:
                  description: |
                    The provided `scope` parameter has a value that is not recognized by the Elements API.
                  value:
                    error: invalid_scope
                    error_description: Request contains invalid scope
                Scope parameter is not allowed for the client:
                  description: |
                    The provided `scope` parameter has a value that is not allowed for the client.  Read-write clients can access `connect.api.read` and `connect.api.write` scopes,  while read-only clients can access only the `connect.api.read` scope.
                  value:
                    error: invalid_scope
                    error_description: Scope not allowed for the client
        '401':
          description: Unauthorized.
          headers:
            X-Transaction:
              description: Internal transaction ID to trace the request on demand.
              schema:
                type: string
          content:
            application/json:
              examples:
                Invalid credentials:
                  description: |
                    The client name or password from the `Authorization` header is invalid.
                  value:
                    error: invalid_client
                    error_description: Invalid credentials
                Authorization header is missing:
                  description: |
                    The required `Authorization` HTTP header is missing from the request.
                  value:
                    error: invalid_client
                    error_description: Authorization header is missing
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                    description: 'Error code as described in [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-5.2)'
                  error_description:
                    type: string
                    description: |
                      Human-readable text providing additional information to assist the client developer in understanding the error that occurred.
  /api-keys/v1/create:
    post:
      tags:
        - API keys
      security:
        - oAuth2:
            - connect.api.write
      operationId: createApiKey
      summary: Create API key
      description: |
        <p>
          Creates a new API key (credentials) for accessing the Elements API.
        </p> <p>
          API keys can be created at the service organization partner (SOP) level or organization level.
          By default, the API key is created for the current organization of the authenticated client.
          Optionally, you can specify an organizationId to create keys for a specific organization 
          (when creating from SOP level).
        </p> <p>
          For security reasons, API keys are created as read-only by default (least privilege principle).
          You can optionally set <code>readOnly</code> to <code>false</code> to grant write access.
        </p> <p>
          <strong>Important:</strong> The <code>clientSecret</code> is only returned once during creation and 
          cannot be retrieved again. Store it securely.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" 
            https://api.connect.withsecure.com/api-keys/v1/create -d '{"description": "API key for automation", "readOnly": true}'
          </code>
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      requestBody:
        required: false
        content:
          application/json:
            examples:
              Create read-only API key for current organization:
                value:
                  description: API key for monitoring dashboard
              Create read-only API key for specific organization:
                value:
                  description: API key for partner integration
                  organizationId: 201efaa6-4fdc-4b31-8663-3b898a6364c2
              Create API key with write access:
                value:
                  description: API key for CI/CD pipeline
                  readOnly: false
              Create API key with write access for specific organization:
                value:
                  description: API key for automated deployments
                  organizationId: 201efaa6-4fdc-4b31-8663-3b898a6364c2
                  readOnly: false
            schema:
              type: object
              description: Request body for creating a new API key
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: |
                    Organization ID for which to create the API key. If not specified, defaults to the current organization  of the authenticated client. This allows creating service organization partner (SOP) level keys  from an SOP level, or organization level keys.
                  example: 201efaa6-4fdc-4b31-8663-3b898a6364c2
                description:
                  type: string
                  description: |
                    A human-readable description for the API key. This helps identify the purpose or owner of the key.
                  example: API key for CI/CD pipeline
                  minLength: 1
                  maxLength: 255
                readOnly:
                  type: boolean
                  description: |
                    Whether the API key should have read-only access. Defaults to true (least privilege principle).  Set to false to grant write access.
                  default: true
                  example: true
              required:
                - description
      responses:
        '201':
          description: API key created successfully. The clientSecret is only returned once and cannot be retrieved later.
          content:
            application/json:
              examples:
                API key created:
                  value:
                    clientId: fusion_01e88488b6554fadb659775a
                    organizationId: 201efaa6-4fdc-4b31-8663-3b898a6364c2
                    clientSecret: supersecret_value_that_is_only_shown_once
                    readOnly: true
                    description: API key for monitoring incidents
              schema:
                type: object
                description: API key created response object
                properties:
                  organizationId:
                    type: string
                    format: uuid
                    description: Organization ID to which the API key belongs
                    example: 201efaa6-4fdc-4b31-8663-3b898a6364c2
                  clientId:
                    type: string
                    description: Client ID for the API key
                    example: fusion_01e88488b6554fadb659775a
                  clientSecret:
                    type: string
                    description: Client secret for the API key. Only returned once during creation and never stored or displayed again.
                    example: secret_value_here
                  readOnly:
                    type: boolean
                    description: Whether the API key has read-only access
                    example: true
                  description:
                    type: string
                    description: Human-readable description for the API key
                    example: API key for monitoring incidents
                required:
                  - clientId
                  - organizationId
                  - clientSecret
                  - readOnly
        '400':
          description: The request failed because parameters have incorrect data.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400001 - request parameter has invalid format:
                  description: 'Indicates that the request parameters have the wrong format and can''t be converted to the target value. For example, a timestamp parameter that doesn''t match the date-time format. Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong format. Check details.
                    code: 400001
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: someTimestamp
                      invalidValue: '2022-10-6T12:1:14Z'
                400002 - request parameter has invalid type:
                  description: 'Indicates that the request parameters have a different type than expected. For example, a "string" value instead of an "integer". Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong type. Check details.
                    code: 400002
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: limit
                      invalidValue: some-string
        '401':
          description: |
            The user is not authorized to send the request. This endpoint requires the connect.api.write scope. Check if the request contains an Authentication header and a valid access token with the correct scope.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user does not have permission to create API keys for the specified organization.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403000 - forbidden:
                  value:
                    message: Forbidden. Insufficient permissions to create API key for this organization.
                    code: 403000
                    transactionId: 0000-someTransactionId
  /api-keys/v1/api-keys:
    get:
      tags:
        - API keys
      security:
        - oAuth2:
            - connect.api.write
      operationId: listApiKeys
      summary: List API keys
      description: |
        <p>
          Lists all API keys (credentials) for a given organization.
        </p> <p>
          By default, returns API keys for the current organization of the authenticated client.
          Optionally, you can specify an organizationId to list keys for a specific organization
          (when querying from SOP level).
        </p> <p>
          Note: This endpoint requires the <code>connect.api.write</code> scope.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/api-keys/v1/api-keys
          </code>
        </p>
      parameters:
        - name: organizationId
          in: query
          required: false
          description: |
            The UUID of an organization. If the organizationId is missing, the default organization of the authenticated client is used.
          schema:
            type: string
            format: uuid
            example: ec8a0100-d313-4896-b3cb-02188e060bf3
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
      responses:
        '200':
          description: List of API keys for the organization.
          content:
            application/json:
              examples:
                List of API keys:
                  value:
                    items:
                      - clientId: fusion_01e88488b6554fadb659775a
                        organizationId: 201efaa6-4fdc-4b31-8663-3b898a6364c2
                        description: API key for monitoring dashboard
                        readOnly: true
                        createdAt: '2023-03-22T13:34:51.097Z'
                      - clientId: fusion_2c902c73e2a640fd9532257e
                        organizationId: 201efaa6-4fdc-4b31-8663-3b898a6364c2
                        description: API key for CI/CD pipeline
                        readOnly: false
                        createdAt: '2023-08-09T12:10:43.537Z'
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      description: API key credentials object
                      properties:
                        clientId:
                          type: string
                          description: Client ID for the API key
                          example: fusion_01e88488b6554fadb659775a
                        organizationId:
                          type: string
                          format: uuid
                          description: Organization ID to which the API key belongs
                          example: 201efaa6-4fdc-4b31-8663-3b898a6364c2
                        description:
                          type: string
                          description: Human-readable description for the API key
                          example: API key for CI/CD pipeline
                        readOnly:
                          type: boolean
                          description: Whether the API key has read-only access
                          example: true
                        createdAt:
                          type: string
                          format: date-time
                          description: Timestamp when the API key was created
                          example: '2023-03-22T13:34:51.097Z'
                      required:
                        - clientId
                        - organizationId
                        - description
                        - readOnly
                        - createdAt
                required:
                  - items
        '400':
          description: The request failed because parameters have incorrect data.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400001 - request parameter has invalid format:
                  description: 'Indicates that the request parameters have the wrong format and can''t be converted to the target value. For example, a timestamp parameter that doesn''t match the date-time format. Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong format. Check details.
                    code: 400001
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: someTimestamp
                      invalidValue: '2022-10-6T12:1:14Z'
        '401':
          description: |
            The user is not authorized to send the request. This endpoint requires the connect.api.write scope. Check if the request contains an Authentication header and a valid access token with the correct scope.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user does not have permission to list API keys for the specified organization.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403000 - forbidden:
                  value:
                    message: Forbidden. Insufficient permissions to list API keys for this organization.
                    code: 403000
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            The organization is not found or out of scope.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - resource not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
  '/api-keys/v1/api-keys/{clientId}':
    delete:
      tags:
        - API keys
      security:
        - oAuth2:
            - connect.api.write
      operationId: deleteApiKey
      summary: Delete API key
      description: |
        <p>
          Deletes (removes) an API key by its credential ID.
        </p> <p>
          After deletion, the API key can no longer be used to authenticate with the Elements API.
          This operation is permanent and cannot be undone.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" 
            https://api.connect.withsecure.com/api-keys/v1/api-keys/fusion_01e88488b6554fadb659775a
          </code>
        </p>
      parameters:
        - name: clientId
          in: path
          required: true
          description: The UUID of the API key credential to delete.
          schema:
            type: string
            example: fusion_01e88488b6554fadb659775a
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
      responses:
        '204':
          description: API key deleted successfully. No content returned.
        '400':
          description: |
            The request failed due to incorrect parameter values.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400001 - request parameter has invalid format:
                  description: 'Indicates that the request parameters have the wrong format and can''t be converted to the target value. For example, a timestamp parameter that doesn''t match the date-time format. Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong format. Check details.
                    code: 400001
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: someTimestamp
                      invalidValue: '2022-10-6T12:1:14Z'
                400004 - invalid parameter value:
                  description: The request parameter has an incorrect value. The error response details include the name of the invalid parameter and the reason it was rejected.
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
        '401':
          description: |
            The user is not authorized to send the request. This endpoint requires the connect.api.write scope. Check if the request contains an Authentication header and a valid access token with the correct scope.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user does not have permission to delete this API key.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403000 - forbidden:
                  value:
                    message: Forbidden. Insufficient permissions to delete this API key.
                    code: 403000
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            The API key with the specified credential ID was not found.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - resource not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
  /whoami/v1/whoami:
    get:
      tags:
        - whoami
      security:
        - oAuth2:
            - connect.api.read
      operationId: whoami
      summary: Get current user information
      description: |
        <p>
          Shows information about the currently authenticated user.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/whoami/v1/whoami 
          </code>
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
      responses:
        '200':
          description: Whoami response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  clientId:
                    type: string
                    description: Client ID.
                  organizationId:
                    type: string
                    description: UUID of the current user's organization.
              examples:
                client:
                  value:
                    clientId: some-client-id
                    organizationId: 1a27fcc0-cb4c-337f-94a5-687dcbcb9fa7
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
  /incidents/v1/incidents:
    get:
      tags:
        - Broad Context Detections (BCDs)
      security:
        - oAuth2:
            - connect.api.read
      operationId: incidents
      summary: List BCDs (incidents)
      description: |
        <p>
          Lists Broad Context Detections (BCDs) for a given organization within a specified time frame.
        </p> <p>
          Broad Context Detections combine related malicious activities. Activities are combined into Broad Context Detections based on leads. Leads represent
          information that can be used to connect individual detections and other
          events together to formulate one combined higher-level representation of
          malicious or suspicious activity. Leads include host IDs and names,
          IPs, and global process IDs. For example, an incident could consist of
          multiple activities that all occur on the same host. In the case of lateral
          movement, a single incident may involve multiple hosts, so an
          individual incident is not tightly coupled to a single host.
        </p> <p>
          Please remember that an ongoing incident evolves over time, so one should keep 
          <a href="/getting-started/elements-cookbook#poll-detections">polling for new detections</a> 
          of that incident.
        </p> <p>
          It is strongly advised to add <code>archived=false</code> to every request if the client
          is only interested in non-archived Broad Context Detections. Adding this parameter and searching only for Broad Context Detections
          that are not archived might have a positive impact on the request's performance.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/incidents/v1/incidents?organizationId={org_id}&archived=false
          </code>
        </p>
      parameters:
        - name: anchor
          in: query
          required: false
          description: |
            Anchor pointing to the page that should be retrieved. If the parameter is missing or set to the default value, the endpoint returns the first page.
          schema:
            type: string
            default: no-value
        - name: organizationId
          in: query
          required: false
          description: |
            The UUID of an organization. If the organizationId is missing, the default organization of the authenticated client is used.
          schema:
            type: string
            format: uuid
            example: ec8a0100-d313-4896-b3cb-02188e060bf3
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - name: incidentId
          in: query
          required: false
          description: UUID of the incident.
          schema:
            type: string
            format: uuid
            example: 2c902c73-e2a6-40fd-9532-257ee102e1c1
        - name: createdTimestampStart
          in: query
          required: false
          description: |
            Lower inclusive bound for the createdTimestamp in the returned list. Cannot be used with updatedTimestamp filters.
          schema:
            type: string
            format: date-time
        - name: createdTimestampEnd
          in: query
          required: false
          description: |
            Upper exclusive bound for the createdTimestamp in the returned list. Cannot be used with updatedTimestamp filters.
          schema:
            type: string
            format: date-time
        - name: updatedTimestampStart
          in: query
          required: false
          description: |
            Lower inclusive bound for the updatedTimestamp in the returned list. Cannot be used with createdTimestamp filters.
          schema:
            type: string
            format: date-time
        - name: updatedTimestampEnd
          in: query
          required: false
          description: |
            Upper exclusive bound for the updatedTimestamp in the returned list. Cannot be used with createdTimestamp filters.
          schema:
            type: string
            format: date-time
        - name: exclusiveStart
          in: query
          required: false
          description: |
            If set to "true", createdTimestampStart and updatedTimestampStart are used as exclusive lower bounds. Otherwise, they are inclusive.
          schema:
            type: boolean
            default: false
        - name: status
          in: query
          required: false
          description: 'The status of the incidents to return. To filter by multiple statuses, add this parameter multiple times.'
          schema:
            type: string
            enum:
              - new
              - acknowledged
              - inProgress
              - monitoring
              - closed
              - waitingForCustomer
            description: Status of the incident
            example: new
        - name: resolution
          in: query
          required: false
          description: 'The resolution of the incident to return. To filter by multiple resolutions, add this parameter multiple times.'
          schema:
            type: string
            enum:
              - unconfirmed
              - confirmed
              - falsePositive
              - merged
              - autoUnconfirmed
              - autoFalsePositive
              - securityTest
              - acceptedRisk
              - acceptedBehavior
            description: Resolution of the incident (only present when status is closed)
            example: confirmed
        - name: riskLevel
          in: query
          required: false
          description: 'Filter by risk level. To filter by multiple risk levels, add this parameter multiple times.'
          schema:
            type: string
            enum:
              - info
              - low
              - medium
              - high
              - severe
        - name: archived
          in: query
          required: false
          description: |
            Specify whether archived Broad Context Detections should be included in the response. It is advised to query only non-archived Broad Context Detections as it might have a positive impact on query performance.
          schema:
            type: boolean
        - name: limit
          in: query
          required: false
          description: Maximum number of items in the response.
          schema:
            type: integer
            format: int32
            default: 20
            minimum: 1
            maximum: 50
        - name: order
          in: query
          required: false
          description: Specifies sorting order.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: source
          in: query
          required: false
          description: |
            <p> Filters by the source of the incident. Can be one or more, passed as a comma-separated list. </p> <p> <ul>
              <li>endpoint - The incident contains detections raised by endpoint events</li>
              <li>cloud (deprecated) - The incident contains detections raised by cloud events</li>
              <li>customer - The incident is a support request originated from the customer</li>
              <li>endpointExpert - The incident was raised manually by the MDR service team</li>
              <li>identityAzure - The incident contains Azure identity and access management related detections</li>
              <li>workloadAzure - The incident contains detections from Azure workloads</li>
              <li>workloadAws - The incident contains detections from AWS workloads</li>
            </ul> </p>
          schema:
            type: string
            enum:
              - endpoint
              - cloud
              - customer
              - endpointExpert
              - identityAzure
              - workloadAzure
              - workloadAws
      responses:
        '200':
          description: Incidents page response.
          content:
            application/json:
              examples:
                List of detections:
                  value:
                    items:
                      - organizationId: ec8a0100-d313-4896-b3cb-02188e060bf3
                        severity: medium
                        riskLevel: medium
                        riskScore: 74.86341234
                        incidentPublicId: 3599-4F9929A4
                        createdTimestamp: '2023-03-22T13:34:51.097Z'
                        name: Incident in DESKTOP-1
                        incidentId: 2c902c73-e2a6-40fd-9532-257ee102e1c1
                        initialReceivedTimestamp: '2023-03-22T13:34:51.097Z'
                        resolution: confirmed
                        updatedTimestamp: '2023-03-23T12:10:43.537Z'
                        status: closed
                        categories:
                          - CREDENTIAL_THEFT
                        sources:
                          - endpoint
                      - organizationId: 201efaa6-4fdc-4b31-8663-3b898a6364c2
                        severity: high
                        riskLevel: medium
                        riskScore: 74.863643223
                        incidentPublicId: 7662182-36
                        createdTimestamp: '2023-08-09T12:10:43.537Z'
                        name: Incident in DESKTOP-2
                        incidentId: 195abb06-c3a7-44a1-a0eb-1f8d5d222deb
                        initialReceivedTimestamp: '2022-06-21T13:12:45.858Z'
                        resolution: unconfirmed
                        updatedTimestamp: '2023-08-09T12:10:43.537Z'
                        status: new
                        categories:
                          - MALWARE
                        sources:
                          - endpoint
                    nextAnchor: next-page-ref
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      properties:
                        incidentId:
                          type: string
                          description: |
                            Unique identifier of incident in UUID format. Client should use that value as incident identifier in any request to other <code>/incidents/v1</code> endpoints
                        incidentPublicId:
                          type: string
                          description: ID of the incident visible in the portal
                        organizationId:
                          type: string
                          description: UUID of the organization
                        name:
                          type: string
                          description: Name related to the incident.
                        status:
                          type: string
                          enum:
                            - new
                            - acknowledged
                            - inProgress
                            - monitoring
                            - closed
                            - waitingForCustomer
                          description: Status of the incident
                          example: new
                        severity:
                          type: string
                          description: |
                            Details about level of severity
                          enum:
                            - info
                            - low
                            - medium
                            - high
                            - critical
                        riskLevel:
                          type: string
                          description: |
                            Details about risk
                          enum:
                            - info
                            - low
                            - medium
                            - high
                            - severe
                        riskScore:
                          type: number
                          description: Risk number evaluation directly bound with `riskLevel`
                          format: double
                        resolution:
                          type: string
                          enum:
                            - unconfirmed
                            - confirmed
                            - falsePositive
                            - merged
                            - autoUnconfirmed
                            - autoFalsePositive
                            - securityTest
                            - acceptedRisk
                            - acceptedBehavior
                          description: Resolution of the incident (only present when status is closed)
                          example: confirmed
                        createdTimestamp:
                          type: string
                          description: |
                            The incident creation timestamp. Time when the incident was created. This timestamp matches value in column 'Detected' in EDR portal.
                          format: date-time
                        updatedTimestamp:
                          type: string
                          description: |
                            The incident updated timestamp. Time when incident was updated or modified, for example with new detection. This timestamp matches  value in column 'Modified' in EDR portal.
                          format: date-time
                        initialReceivedTimestamp:
                          type: string
                          description: |
                            Time when the first action related to the incident was received by the backend processing pipeline. This can be used to measure the delays in submitting data from the sensor in case of remarkable delays in detections.
                          format: date-time
                        categories:
                          type: array
                          description: Contains list of incident (BCD) categories
                          items:
                            type: string
                            enum:
                              - ABNORMAL_EXECUTABLE_MODIFICATION
                              - ABNORMAL_FILE_ACCESSES
                              - ABNORMAL_FILE_MODIFICATION
                              - ABNORMAL_LIBRARY_OR_MODULE
                              - ABNORMAL_NETWORK_CONNECTION
                              - ABNORMAL_PROCESS
                              - ABNORMAL_PROCESS_EXECUTION
                              - ABNORMAL_PROCESSES_RELATION
                              - ABNORMAL_USER_ACTIVITY
                              - ANOMALY
                              - BACKDOORED_FILE
                              - CC_NETWORK_CONNECTION
                              - CHANGING_FILE_VISIBILITY
                              - CHANGING_SECURITY_SETTINGS
                              - CHANGING_USER_INFORMATION
                              - COMPROMISED_CLEAN_PROCESS
                              - CREATING_ATTACK_TOOLS
                              - CREDENTIAL_THEFT
                              - DIRECTED_ATTACK
                              - INJECTION
                              - INJECTION_TARGET
                              - LATERAL_MOVEMENT
                              - LATERAL_MOVEMENT_INITIATOR
                              - LATERAL_MOVEMENT_TARGET
                              - LOG_ANOMALIES
                              - MALICIOUS_PROCESS
                              - MALWARE
                              - PERSISTENCE
                              - PHISHING
                              - PRIVILEGE_ESCALATION
                              - PUP
                              - RECON_ACTIVITIES
                              - SCRIPTING_ABUSE
                              - SENSITIVE_FILE_MODIFICATION
                              - SENSOR_TAMPER
                              - SPOOFING_FILES
                              - SPOOFING_INPUTS
                              - SPOOFING_MEMORY
                              - SPOOFING_NETWORK
                              - SPOOFING_SECURITY_SETTINGS
                              - SPOOFING_USER_INFORMATION
                              - SPOOFING_VULNERABILITIES
                              - SYSTEM_OR_TOOL_MISUSE
                        sources:
                          type: array
                          description: Contains list of incident (BCD) sources
                          items:
                            type: string
                            enum:
                              - endpoint
                              - cloud
                              - customer
                              - endpointExpert
                              - identityAzure
                              - workloadAzure
                              - workloadAws
                        description:
                          type: string
                          description: |
                            Description of the BCD. User can change it in EDR portal.
                  nextAnchor:
                    type: string
                    description: Anchor to be used to retrieve the next page. Not to be returned on the last page.
                required:
                  - items
        '400':
          description: The request failed because parameters have incorrect data that does not pass validation.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            The organization is not found (or out of scope), or the customer is not found (or out of scope).
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - resource not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
    patch:
      tags:
        - Broad Context Detections (BCDs)
      security:
        - oAuth2:
            - connect.api.write
      operationId: updateIncident
      summary: Update status of BCDs
      description: |
        <p>
          Updates the status of given Broad Context Detections.
        </p> <p>
          The specified status is assigned to every incident (BCD) in the <code>targets</code> list in the request body.
          An incident (BCD) is identified with <code>incidentId</code>, which the client can read
          from the <a href="/api-reference/elements#get-/incidents/v1/incidents">BCDs list</a>.
        </p> <p>
          In every request, the client must specify at least one incident to update and the new status. Additionally,
          the client must specify <code>resolution</code> if the new status is <code>closed</code>.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/incidents/v1/incidents -d '{"targets": ["{incident_id}"], "status": "closed", "resolution":"confirmed"}'
          </code>
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      requestBody:
        required: true
        content:
          application/json:
            examples:
              Update incident status:
                value:
                  targets:
                    - 2c902c73-e2a6-40fd-9532-257ee102e1c1
                  status: monitoring
              Close incident:
                value:
                  targets:
                    - 2c902c73-e2a6-40fd-9532-257ee102e1c1
                  status: closed
                  resolution: confirmed
            schema:
              type: object
              properties:
                targets:
                  type: array
                  description: List of incident (BCD) IDs to update.
                  items:
                    type: string
                    format: uuid
                    example: 2c902c73-e2a6-40fd-9532-257ee102e1c1
                  maxItems: 1
                  minItems: 1
                status:
                  type: string
                  enum:
                    - new
                    - acknowledged
                    - inProgress
                    - monitoring
                    - closed
                    - waitingForCustomer
                  description: Status of the incident
                  example: new
                resolution:
                  type: string
                  enum:
                    - unconfirmed
                    - confirmed
                    - falsePositive
                    - merged
                    - autoUnconfirmed
                    - autoFalsePositive
                    - securityTest
                    - acceptedRisk
                    - acceptedBehavior
                  description: Resolution of the incident (only present when status is closed)
                  example: confirmed
              required:
                - targets
                - status
      responses:
        '207':
          description: The request payload was valid and it was processed in the internal backend.
          content:
            application/json:
              examples:
                Update completed successfully:
                  value:
                    multistatus:
                      - target: 2c902c73-e2a6-40fd-9532-257ee102e1c1
                        status: 204
                    transactionId: 0000-d1467e4907a54c87
                Update failed:
                  value:
                    multistatus:
                      - target: 2c902c73-e2a6-40fd-9532-257ee102e1c1
                        status: 404
                        details: Incident ID not found
                    transactionId: 0000-d1467e4907a54c90
              schema:
                type: object
                properties:
                  multistatus:
                    description: Contains information about updating the target incident.
                    type: array
                    items:
                      type: object
                      properties:
                        target:
                          type: string
                          format: uuid
                          description: 'Incident ID, corresponds to an element from the request `targets` array. Use this value to [query](/api-reference/elements#get-/incidents/v1/incidents) for further information about the incident.'
                        status:
                          type: integer
                          description: HTTP status of the update for the particular incident. A response with status code 204 means that the incident exists within the scope of the client's organization and the update was successfully processed.
                        details:
                          type: string
                          description: Details about the update. It might contain information about the reason for failure.
                      required:
                        - target
                        - status
                  transactionId:
                    type: string
                    description: Transaction ID for the request to the Elements API.
                required:
                  - multistatus
        '400':
          description: The request failed because parameters have incorrect data that does not pass validation.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user has insufficient privileges to send the request. Check if the token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
  /incidents/v1/comments:
    post:
      tags:
        - Broad Context Detections (BCDs)
      security:
        - oAuth2:
            - connect.api.write
      operationId: addCommentToIncident
      summary: Add comment to BCDs
      description: |
        <p>
          Adds comment to Broad Context Detections (BCDs).
        </p> <p>
          Specified comment is added to every incident in <code>targets</code> list in request body.
          Incident is identified with <code>incidentId</code> that client can read
          from <a href="/api-reference/elements#get-/incidents/v1/incidents">BCDs list</a>
        </p> <p>
          In every request client must specify at least one BCD to update and a comment to add.
        </p> <p>
          This endpoint works with "all or nothing" approach, meaning it will fail if any of given target BCDs have
          invalid UUID format or cannot be found, etc.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/incidents/v1/comments -d '{"targets": ["{incident_id}"], "comment": "example comment"}'
          </code>
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      requestBody:
        required: true
        content:
          application/json:
            examples:
              Add comment to incident:
                value:
                  targets:
                    - 2c902c73-e2a6-40fd-9532-257ee102e1c1
                  comment: TICKET-1234
              Add comment to multiple incidents:
                value:
                  targets:
                    - 2c902c73-e2a6-40fd-9532-257ee102e1c1
                    - cc8b996f-1d50-40cc-a942-686f82fcd3fc
                  comment: TICKET-1234
            schema:
              type: object
              properties:
                targets:
                  type: array
                  description: List of incident (BCD) IDs to comment.
                  items:
                    type: string
                    format: uuid
                    example: 2c902c73-e2a6-40fd-9532-257ee102e1c1
                  minItems: 1
                  maxItems: 10
                comment:
                  type: string
                  description: Comment to add to the target incidents (BCDs)
              required:
                - targets
                - comment
      responses:
        '200':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              examples:
                Comments added successfully:
                  value:
                    items:
                      - incidentId: 2c902c73-e2a6-40fd-9532-257ee102e1c1
                        comment: example comment
                      - incidentId: cc8b996f-1d50-40cc-a942-686f82fcd3fc
                        comment: example comment
              schema:
                type: object
                properties:
                  items:
                    description: Contains information about comment in target incidents
                    type: array
                    items:
                      type: object
                      properties:
                        incidentId:
                          type: string
                          format: uuid
                          description: 'Incident ID (BCD ID), corresponds to an element from the request `targets` array. Use this value to [query](/api-reference/elements#get-/incidents/v1/incidents) for further information about the incident (BCD).'
                        comment:
                          type: string
                          description: Comment added to the incident.
                      required:
                        - incidentId
                        - comment
                required:
                  - items
        '400':
          description: The request failed because parameters have incorrect data that does not pass validation.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user has insufficient privileges to send the request. Check if the token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            At least one of the targets doesn't exist. Check if the target incidents are correct.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
  /incidents/v1/detections:
    get:
      tags:
        - Broad Context Detections (BCDs)
      security:
        - oAuth2:
            - connect.api.read
      operationId: detections
      summary: List detections for given BCD in organization scope
      description: |
        <p>
          Lists detections for a given organization and incident (BCD) ID within a specified time frame in descending order.
          This endpoint is intended to be used together with the Security Events that inform that a BCD (identified by incident ID) was created, merged, or closed.
          The goal is to analyze and triage BCDs from a third-party system to bring them to a resolution, at which point they must be closed in Elements Security Center either manually or through the API (PATCH /incidents/v1/incidents).
          The goal is not to ingest as many detections as possible into a third-party system.
        </p> <p>
          The value of the <code>incidentId</code> parameter, used to query detections, can be read from the <code>incidentId</code> property in
          the details of the <a href="/api-reference/security-events#get-EDR-incident-created">EDR Security Event</a>.
        </p> <p>
          The <a href="/getting-started/elements-cookbook#poll-detections">Elements API Cookbook</a> 
          contains an example implementation of EDR detections polling.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/incidents/v1/detections?organizationId={org_id}&incidentId={incident_id} 
          </code>
        </p>
      parameters:
        - name: organizationId
          in: query
          required: false
          description: |
            The UUID of an organization. If the organizationId is missing, the default organization of the authenticated client is used.
          schema:
            type: string
            format: uuid
            example: ec8a0100-d313-4896-b3cb-02188e060bf3
        - name: incidentId
          in: query
          required: true
          description: |
            The ID of an incident. The client can find this value in the details of the <a href="/api-reference/security-events#get-EDR-incident-created">EDR Security Event</a>. The incident ID must match the UUID format.
          example: ec8a0100-d313-4896-b3cb-02188e060bf3
          schema:
            type: string
        - name: anchor
          in: query
          required: false
          description: |
            Anchor pointing to the page that should be retrieved. If the parameter is missing or set to the default value, the endpoint returns the first page.
          schema:
            type: string
            default: no-value
        - name: createdTimestampStart
          in: query
          required: false
          description: |
            Lower inclusive bound for the createdTimestamp in the returned list. Cannot be used with updatedTimestamp filters.
          schema:
            type: string
            format: date-time
        - name: createdTimestampEnd
          in: query
          required: false
          description: |
            Upper exclusive bound for the createdTimestamp in the returned list. Cannot be used with updatedTimestamp filters.
          schema:
            type: string
            format: date-time
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - name: limit
          in: query
          required: false
          description: Maximum number of items in the response.
          schema:
            type: integer
            format: int32
            default: 100
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Detections events page response.
          content:
            application/json:
              examples:
                List of detections:
                  value:
                    items:
                      - detectionId: cc04e914-dbea-4785-83cc-60492f03b97d
                        incidentId: 2c902c73-e2a6-40fd-9532-257ee102e1c1
                        deviceId: 3a8f06e1-c3e8-4933-b617-e23597111644
                        name: suspiciousPowershellCommand
                        detectionClass: PROCESS
                        severity: medium
                        riskLevel: medium
                        exePath: 'C:\Windows\Explorer.EXE'
                        exeName: '%systemroot%'
                        exeHash: c8f21ef51fa2f2033a9ca7c0cc0412c25065e2ba
                        cmdl: /usr/bin/whoami --version
                        pid: 1234
                        createdTimestamp: '2023-03-22T13:34:51.097Z'
                        initialReceivedTimestamp: '2023-03-22T13:34:51.097Z'
                        username: "DESKTOP-EXAMPLE\admin"
                        privileges: NormalPrivileges
                        activityContext:
                          - type: elevation
                            description: Elevation of privileges
                          - type: histogram
                            detectionAvgCount: 1
                            detectionMaxCount: 1
                            detectionAvgSensors: 1
                            detectionCountHistogram:
                              - 1
                            detectionHits24h: 1
                            detectionMaxSensors: 1
                            detectionSensors24h: 1
                            detectionSensorsHistogram:
                              - 1
                    nextAnchor: next-page-ref
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      properties:
                        detectionId:
                          type: string
                          description: ID of the detection.
                        incidentId:
                          type: string
                          description: ID of the incident to which the detection belongs.
                        deviceId:
                          type: string
                          description: ID of the device on which the incident was detected.
                        name:
                          type: string
                          description: Name related to the detection.
                        detectionClass:
                          type: string
                          description: 'Type of detection, e.g. PROCESS'
                        severity:
                          type: string
                          description: |
                            Details about the level of severity.
                          enum:
                            - info
                            - low
                            - medium
                            - high
                            - critical
                        riskLevel:
                          type: string
                          description: |
                            Details about risk
                          enum:
                            - info
                            - low
                            - medium
                            - high
                            - severe
                        exePath:
                          type: string
                          description: Process executable path.
                        exeName:
                          type: string
                          description: Process executable name.
                        exeHash:
                          type: string
                          description: Details on the executable hash.
                        cmdl:
                          type: string
                          description: Details on the command line.
                        pid:
                          type: integer
                          description: Process PID.
                        createdTimestamp:
                          type: string
                          description: |
                            The incident or activity creation timestamp. This is the time when the first action related to the activity occurred on the host.
                          format: date-time
                        initialReceivedTimestamp:
                          type: string
                          description: |
                            Source clock - Detection engine. The time when the first action related to the activity was received by the backend processing pipeline. This can be used to measure delays in submitting data from the sensor in case of significant detection delays.
                          format: date-time
                        username:
                          type: string
                          description: Details of the username related to the detection.
                        privileges:
                          type: string
                        description:
                          type: string
                          description: Description of a single detection.
                        activityContext:
                          type: array
                          description: |
                            Context information fields that provide specific details about an action reported in the incident. Each item may contain additional attributes with type-specific information. Attributes are defined as key/value pairs, where the value may be a primitive (integer, string), array, or complex object.
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                description: |
                                  Type of context information. This identifies the type of field data and the expected data attributes.
                              description:
                                type: string
                                description: |
                                  Description explaining why this field is shown.
                            additionalProperties: true
                      required:
                        - detectionId
                        - incidentId
                        - detectionClass
                        - severity
                        - riskLevel
                        - createdTimestamp
                        - initialReceivedTimestamp
                  nextAnchor:
                    type: string
                    description: Anchor to be used to retrieve the next page. Not to be returned on the last page.
                required:
                  - items
        '400':
          description: The request failed because parameters have incorrect data that does not pass validation.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            The organization is not found (or out of scope), or the customer is not found (or out of scope).
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - resource not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
  /incidents/v1/updates:
    get:
      tags:
        - Broad Context Detections (BCDs)
      security:
        - oAuth2:
            - connect.api.read
      operationId: getIncidentUpdates
      summary: Get BCD update history
      description: |
        Retrieves a list of updates for a specific BCD. Updates represent changes made to a BCD over time, including status changes, assignments, detections, and other modifications.
      parameters:
        - name: incidentId
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: The unique identifier of the incident
          example: 67c07b9f-16a5-45a4-860b-d306a8dc339b
        - name: organizationId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: 'Organization ID. If not provided, defaults to the organization the client is authenticated to'
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - capabilityNeeds
              - categories
              - closeElevationMessage
              - comment
              - detection
              - elevateIncidentMessage
              - elevationMessage
              - merge
              - patch
              - responseAction
              - risk
              - threatInvestigationResult
              - threatValidationResult
            description: Type of the incident update
            example: patch
          description: Filter updates by type
          example: patch
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: Maximum number of updates to return
          example: 20
        - name: anchor
          in: query
          required: false
          schema:
            type: string
          description: Pagination anchor for retrieving the next set of results
          example: eyJjcmVhdGVkVGltZXN0YW1wIjoiMjAyNS0xMC0wMlQwNTo1NTozMi4zNzZaIn0=
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the incident update
                          example: f859836d-04ba-41c9-9377-691e3c3393c3
                        incidentId:
                          type: string
                          description: Unique identifier of the incident this update belongs to
                          example: 67c07b9f-16a5-45a4-860b-d306a8dc339b
                        createdTimestamp:
                          type: string
                          format: date-time
                          description: Timestamp when the update was created
                          example: '2025-10-02T05:55:32.376Z'
                        type:
                          type: string
                          enum:
                            - capabilityNeeds
                            - categories
                            - closeElevationMessage
                            - comment
                            - detection
                            - elevateIncidentMessage
                            - elevationMessage
                            - merge
                            - patch
                            - responseAction
                            - risk
                            - threatInvestigationResult
                            - threatValidationResult
                          description: Type of the incident update
                          example: patch
                        origin:
                          type: object
                          description: Source information that triggered this update
                          properties:
                            type:
                              type: string
                              enum:
                                - engine
                                - responseAction
                                - unknown
                                - user
                              description: Type of origin that triggered the update
                            username:
                              type: string
                              description: Username (only for type "user")
                        detections:
                          type: object
                          description: Detection update fields (only present for type "detection")
                          properties:
                            added:
                              type: array
                              items:
                                type: string
                              description: Detection IDs added to the incident
                            removed:
                              type: array
                              items:
                                type: string
                              description: Detection IDs removed from the incident
                            modified:
                              type: array
                              items:
                                type: string
                              description: Detection IDs modified in the incident
                        stateBefore:
                          type: object
                          description: Incident state before the update
                          properties:
                            status:
                              type: string
                              enum:
                                - new
                                - acknowledged
                                - inProgress
                                - monitoring
                                - closed
                                - waitingForCustomer
                              description: Status of the incident
                              example: new
                            riskLevel:
                              type: string
                              description: |
                                Details about risk
                              enum:
                                - info
                                - low
                                - medium
                                - high
                                - severe
                            resolution:
                              type: string
                              enum:
                                - unconfirmed
                                - confirmed
                                - falsePositive
                                - merged
                                - autoUnconfirmed
                                - autoFalsePositive
                                - securityTest
                                - acceptedRisk
                                - acceptedBehavior
                              description: Resolution of the incident (only present when status is closed)
                              example: confirmed
                            categories:
                              type: array
                              description: Contains list of incident (BCD) categories
                              items:
                                type: string
                                enum:
                                  - ABNORMAL_EXECUTABLE_MODIFICATION
                                  - ABNORMAL_FILE_ACCESSES
                                  - ABNORMAL_FILE_MODIFICATION
                                  - ABNORMAL_LIBRARY_OR_MODULE
                                  - ABNORMAL_NETWORK_CONNECTION
                                  - ABNORMAL_PROCESS
                                  - ABNORMAL_PROCESS_EXECUTION
                                  - ABNORMAL_PROCESSES_RELATION
                                  - ABNORMAL_USER_ACTIVITY
                                  - ANOMALY
                                  - BACKDOORED_FILE
                                  - CC_NETWORK_CONNECTION
                                  - CHANGING_FILE_VISIBILITY
                                  - CHANGING_SECURITY_SETTINGS
                                  - CHANGING_USER_INFORMATION
                                  - COMPROMISED_CLEAN_PROCESS
                                  - CREATING_ATTACK_TOOLS
                                  - CREDENTIAL_THEFT
                                  - DIRECTED_ATTACK
                                  - INJECTION
                                  - INJECTION_TARGET
                                  - LATERAL_MOVEMENT
                                  - LATERAL_MOVEMENT_INITIATOR
                                  - LATERAL_MOVEMENT_TARGET
                                  - LOG_ANOMALIES
                                  - MALICIOUS_PROCESS
                                  - MALWARE
                                  - PERSISTENCE
                                  - PHISHING
                                  - PRIVILEGE_ESCALATION
                                  - PUP
                                  - RECON_ACTIVITIES
                                  - SCRIPTING_ABUSE
                                  - SENSITIVE_FILE_MODIFICATION
                                  - SENSOR_TAMPER
                                  - SPOOFING_FILES
                                  - SPOOFING_INPUTS
                                  - SPOOFING_MEMORY
                                  - SPOOFING_NETWORK
                                  - SPOOFING_SECURITY_SETTINGS
                                  - SPOOFING_USER_INFORMATION
                                  - SPOOFING_VULNERABILITIES
                                  - SYSTEM_OR_TOOL_MISUSE
                          additionalProperties: true
                        stateAfter:
                          type: object
                          description: Incident state before the update
                          properties:
                            status:
                              type: string
                              enum:
                                - new
                                - acknowledged
                                - inProgress
                                - monitoring
                                - closed
                                - waitingForCustomer
                              description: Status of the incident
                              example: new
                            riskLevel:
                              type: string
                              description: |
                                Details about risk
                              enum:
                                - info
                                - low
                                - medium
                                - high
                                - severe
                            resolution:
                              type: string
                              enum:
                                - unconfirmed
                                - confirmed
                                - falsePositive
                                - merged
                                - autoUnconfirmed
                                - autoFalsePositive
                                - securityTest
                                - acceptedRisk
                                - acceptedBehavior
                              description: Resolution of the incident (only present when status is closed)
                              example: confirmed
                            categories:
                              type: array
                              description: Contains list of incident (BCD) categories
                              items:
                                type: string
                                enum:
                                  - ABNORMAL_EXECUTABLE_MODIFICATION
                                  - ABNORMAL_FILE_ACCESSES
                                  - ABNORMAL_FILE_MODIFICATION
                                  - ABNORMAL_LIBRARY_OR_MODULE
                                  - ABNORMAL_NETWORK_CONNECTION
                                  - ABNORMAL_PROCESS
                                  - ABNORMAL_PROCESS_EXECUTION
                                  - ABNORMAL_PROCESSES_RELATION
                                  - ABNORMAL_USER_ACTIVITY
                                  - ANOMALY
                                  - BACKDOORED_FILE
                                  - CC_NETWORK_CONNECTION
                                  - CHANGING_FILE_VISIBILITY
                                  - CHANGING_SECURITY_SETTINGS
                                  - CHANGING_USER_INFORMATION
                                  - COMPROMISED_CLEAN_PROCESS
                                  - CREATING_ATTACK_TOOLS
                                  - CREDENTIAL_THEFT
                                  - DIRECTED_ATTACK
                                  - INJECTION
                                  - INJECTION_TARGET
                                  - LATERAL_MOVEMENT
                                  - LATERAL_MOVEMENT_INITIATOR
                                  - LATERAL_MOVEMENT_TARGET
                                  - LOG_ANOMALIES
                                  - MALICIOUS_PROCESS
                                  - MALWARE
                                  - PERSISTENCE
                                  - PHISHING
                                  - PRIVILEGE_ESCALATION
                                  - PUP
                                  - RECON_ACTIVITIES
                                  - SCRIPTING_ABUSE
                                  - SENSITIVE_FILE_MODIFICATION
                                  - SENSOR_TAMPER
                                  - SPOOFING_FILES
                                  - SPOOFING_INPUTS
                                  - SPOOFING_MEMORY
                                  - SPOOFING_NETWORK
                                  - SPOOFING_SECURITY_SETTINGS
                                  - SPOOFING_USER_INFORMATION
                                  - SPOOFING_VULNERABILITIES
                                  - SYSTEM_OR_TOOL_MISUSE
                          additionalProperties: true
                        comment:
                          type: string
                          description: Comment of the incident (present for type "comment" and elevation-related types)
                        deleted:
                          type: boolean
                          description: Whether the comment is deleted (only present for type "comment")
                        responseAction:
                          type: string
                          description: Response action taken (only present for type "responseAction")
                        parameters:
                          type: object
                          description: 'Additional parameters related to the response action ("hostIds", "emailAddresses" etc.) (only present for type "responseAction")'
                          additionalProperties: true
                        toIncidentId:
                          type: string
                          description: Target incident ID for merge (only present for type "merge")
                        fromDetections:
                          type: array
                          items:
                            type: string
                          description: Detection IDs being merged from (only present for type "merge")
                        fromIncidentId:
                          type: string
                          description: Source incident ID for merge (only present for type "merge")
                        elevationId:
                          type: string
                          description: Identifier for the elevation action (only present for elevation-related types)
                      required:
                        - id
                        - incidentId
                        - createdTimestamp
                  nextAnchor:
                    type: string
                    description: Anchor for pagination to get the next set of results
                    example: eyJjcmVhdGVkVGltZXN0YW1wIjoiMjAyNS0xMC0wMlQwNjo1NTozMi4zNzZaIn0=
                required:
                  - items
              example:
                items:
                  - id: f859836d-04ba-41c9-9377-691e3c3393c3
                    incidentId: 67c07b9f-16a5-45a4-860b-d306a8dc339b
                    createdTimestamp: '2025-10-02T05:55:32.376Z'
                    type: patch
                    stateBefore:
                      status: new
                      resolution: unconfirmed
                    stateAfter:
                      status: inProgress
                      resolution: unconfirmed
                    origin:
                      type: user
                nextAnchor: eyJjcmVhdGVkVGltZXN0YW1wIjoiMjAyNS0xMC0wMlQwNjo1NTozMi4zNzZaIn0=
        '400':
          description: The request failed because parameters have incorrect data that does not pass validation.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            The organization is not found (or out of scope), or the customer is not found (or out of scope).
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - resource not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
  /organizations/v1/organizations:
    get:
      tags:
        - organizations
      security:
        - oAuth2:
            - connect.api.read
      operationId: organizations
      summary: List organizations
      description: |
        <p>
          Lists organizations that belong to the given organization (including itself, if the type matches).
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/organizations/v1/organizations?organizationId={organizationId}
          </code>
        </p>
      parameters:
        - name: organizationId
          in: query
          required: false
          description: |
            The UUID of an organization. If the organizationId is missing, the default organization of the authenticated client is used.
          schema:
            type: string
            format: uuid
            example: ec8a0100-d313-4896-b3cb-02188e060bf3
        - name: anchor
          in: query
          required: false
          description: |
            Anchor pointing to the page that should be retrieved. If the parameter is missing or set to the default value, the endpoint returns the first page.
          schema:
            type: string
            default: no-value
        - name: type
          in: query
          required: false
          description: |
            Filter by organization type. Returns all organizations of the specified type.
          schema:
            type: string
            enum:
              - company
              - partner
            default: company
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - name: limit
          in: query
          required: false
          description: |
            The size of the single batch. This value defines the upper bound for the number of items that are sent in a single response. However, it doesn't guarantee that the response will contain the exact number of items if the next page exists. Clients that read all items matching the query parameters should depend only on the <code>nextAnchor</code> property, which contains a link to the next result. Clients can stop iteration when the <code>nextAnchor</code> is missing in the response.
          schema:
            type: integer
            format: int32
            default: 200
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: |
            Flat list of organizations of the given type that are under the organization of the authenticated client.
          content:
            application/json:
              schema:
                title: Organizations response
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Organization UUID.
                        name:
                          type: string
                          description: Organization name.
                        type:
                          type: string
                          enum:
                            - company
                            - sop
                            - sep
                          description: |
                            Organization type:
                              * company,
                              * sop - solution provider,
                              * sep - service partner.
                      required:
                        - id
                        - name
                    description: List of organizations.
                  nextAnchor:
                    type: string
                    description: Anchor to be used to retrieve the next page. Not to be returned on the last page.
                required:
                  - items
              examples:
                companies for SOP/SEP:
                  value:
                    items:
                      - id: 66787bfd-3fec-4355-955b-790b53ee0199
                        name: Example company 1
                        type: company
                      - id: 6827ac27-67b3-45c5-bdd3-69660e8272a8
                        name: Example company 2
                        type: company
                      - id: 30ec2ab5-7d4b-458c-bd66-ed099fe42398
                        name: Example company 3
                        type: company
                      - id: a03f227a-bbeb-4116-8d46-4dd006fcce63
                        name: Example company 4
                        type: company
                      - id: 4fb689b9-4b97-4693-9487-731c8799fc65
                        name: Example company 5
                        type: company
                    anchor: 1a27fcc0-cb4c-337f-94a5-687dcbcb9fa7
                companies for company:
                  value:
                    items:
                      - id: 66787bfd-3fec-4355-955b-790b53ee0199
                        name: Example company
                        type: company
                partners for SOP:
                  value:
                    items:
                      - id: 66787bfd-3fec-4355-955b-790b53ee0199
                        name: Example SOP 1
                        type: sop
                      - id: 66787bfd-3fec-4355-955b-790b53ee0111
                        name: Example SEP 1
                        type: sep
                      - id: 6827ac27-67b3-45c5-bdd3-69660e8272a8
                        name: Example SEP 2
                        type: sep
                      - id: 30ec2ab5-7d4b-458c-bd66-ed099fe42398
                        name: Example SEP 3
                        type: sep
                      - id: a03f227a-bbeb-4116-8d46-4dd006fcce63
                        name: Example SEP 4
                        type: sep
                      - id: 4fb689b9-4b97-4693-9487-731c8799fc65
                        name: Example SEP 5
                        type: sep
                    anchor: 1a27fcc0-cb4c-337f-94a5-687dcbcb9fa7
                partners for SEP:
                  value:
                    items:
                      - id: 66787bfd-3fec-4355-955b-790b53ee0111
                        name: Example SEP 1
                        type: sep
                    anchor: 1a27fcc0-cb4c-337f-94a5-687dcbcb9fa7
        '400':
          description: The request failed because parameters have incorrect data.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400001 - request parameter has invalid format:
                  description: 'Indicates that the request parameters have the wrong format and can''t be converted to the target value. For example, a timestamp parameter that doesn''t match the date-time format. Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong format. Check details.
                    code: 400001
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: someTimestamp
                      invalidValue: '2022-10-6T12:1:14Z'
                400002 - request parameter has invalid type:
                  description: 'Indicates that the request parameters have a different type than expected. For example, a "string" value instead of an "integer". Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong type. Check details.
                    code: 400002
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: limit
                      invalidValue: some-string
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
  /security-events/v1/security-events:
    post:
      tags:
        - security events
      security:
        - oAuth2:
            - connect.api.read
      operationId: queryEvents
      summary: Query security events
      description: |
        <p>
          Executes a search query against EPP, EDR, Exposure Management and Collaboration Protection Security Events and
          returns results in JSON format. For partner organizations, the query checks events in all child companies. The endpoint
          supports the following response formats:
            <ul>
              <li>items page (default) - the endpoint returns Security Events matching filter parameters as a page of items where
              each item represents a Security Event object. The client iterates over search results using the page anchor and can
              decide about page size and items ordering.</li>
              <li>aggregation - the endpoint groups and counts Security Events matching filter parameters by a property selected
              by the client. To select this mode, the client must add the HTTP header <code>Accept: application/vnd.withsecure.aggr+json</code>
              to the request. Additionally, it has to add the parameter <code>count={property name}</code> to the request.</li>
            </ul>
        </p> <p>
          The client can use the parameters <code>persistenceTimestampStart (inclusive)</code> and
          <code>persistenceTimestampEnd (exclusive)</code> to specify the search time range. A valid request must contain
          at least one of these two. Additionally, the client can use the parameter <code>exclusiveStart</code> if
          <code>persistenceTimestampStart</code> should be interpreted as the exclusive start of the time range.
        </p> <p>
          In every request, the client must specify an engine or engines group that will be used to select security events.
          The parameter <code>engine</code> allows selecting events from a particular engine, such as Deep Guard, Application Control,
          and others. <code>engineGroup</code> allows selecting events with engines that belong to a particular group. For
          example, to get all Collaboration Protection events, the client might send the query <code>engineGroup=ecp</code>.<br>
          <code>engine</code> and <code>engineGroup</code> are mutually exclusive - the client must send one or the other but
          never both.
        </p> <p>
          <code>engine</code>, <code>engineGroup</code>, and <code>severity</code> can be repeated in the query multiple times to fetch all events
          matching one of the provided values. For example, a query like <code>engine=emailScan&engine=deepGuard</code> will
          return all events from Collaboration Protection scan or EPP Deep Guard.
        </p> <p> Examples: <ul> <li>
            <p>Get a list of EPP Security Events from the Deep Guard engine:</p>
            <p><code>
            curl -v -X POST -H "Authorization: Bearer YOUR_TOKEN"
            -H "Accept: application/json" -d "engine=deepGuard" -d "persistenceTimestampStart=2023-05-01T00:00:00Z" "https://api.connect.withsecure.com/security-events/v1/security-events"
            </code></p>
        </li> <li>
            <p>Get a list of Collaboration Protection events from the Email Scan engine:</p>
            <p><code>
            curl -v -X POST -H "Authorization: Bearer YOUR_TOKEN"
            -H "Accept: application/json" -d "engine=emailScan" -d "persistenceTimestampStart=2023-05-01T00:00:00Z" "https://api.connect.withsecure.com/security-events/v1/security-events"
            </code></p>
        </li> <li>
            <p>Get all EPP and EDR events:</p>
            <p><code>
            curl -v -X POST -H "Authorization: Bearer YOUR_TOKEN"
            -H "Accept: application/json" -d "engineGroup=epp" -d "engineGroup=edr" -d "persistenceTimestampStart=2023-05-01T00:00:00Z" "https://api.connect.withsecure.com/security-events/v1/security-events"
            </code></p>
        </li> <li>
            <p>Aggregate Collaboration Protection events by engine:</p>
            <p><code>
            curl -v -X POST -H "Authorization: Bearer YOUR_TOKEN"
            -H "Accept: application/vnd.withsecure.aggr+json" -d "count=engine" -d "engineGroup=ecp" -d "persistenceTimestampStart=2023-05-01T00:00:00Z" "https://api.connect.withsecure.com/security-events/v1/security-events"
            </code></p>
        </li> </ul> </p>
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: |
                    ID of an organization. If organizationId is missing, default organization of authenticated client is used.
                persistenceTimestampStart:
                  type: string
                  format: date-time
                  description: |
                    Lower bound for persistence timestamp in the returned security events. Minimum allowed value is <code>2022-08-01T00:00:01Z</code>
                persistenceTimestampEnd:
                  type: string
                  format: date-time
                  description: |
                    Upper exclusive bound for persistence timestamp in the returned security events.
                engine:
                  type: array
                  items:
                    type: string
                    enum:
                      - AMSI
                      - activityMonitor
                      - activityMonitorClientProtection
                      - applicationControl
                      - browsingProtection
                      - cloudIdentityAzure
                      - cloudWorkloadAzure
                      - connectionControl
                      - connector
                      - dataGuard
                      - deepGuard
                      - deviceControl
                      - edr
                      - emailBreach
                      - emailScan
                      - fileScanning
                      - firewall
                      - inboxRuleScan
                      - integrityChecker
                      - oneDriveScan
                      - product
                      - realtimeScanning
                      - reputationBasedBrowsing
                      - setting
                      - sharePointScan
                      - systemEventsLog
                      - tamperProtection
                      - teamsScan
                      - webContentControl
                      - webTrafficScanning
                      - xFence
                      - xmRecommendation
                  description: Engine that triggered event.
                engineGroup:
                  type: array
                  items:
                    type: string
                    enum:
                      - epp
                      - edr
                      - ecp
                      - xm
                  description: |
                    Single parameter to select events from all engines that belong to particular engines group. Following groups are supported:
                      <ul>
                       <li>epp - Endpoint Protection
                       <li>edr - Detection and Response
                       <li>ecp - Collaboration Protection
                       <li>xm - Exposure Management
                      </ul>
                severity:
                  type: array
                  items:
                    type: string
                    enum:
                      - critical
                      - warning
                      - info
                  description: Event's severity
                targetId:
                  type: string
                  description: |
                    ID of the event's target - either the ID of the device or the email address. When this parameter is present, the response contains all events related to the EPP device or Office 365 entity.
                acknowledged:
                  type: boolean
                  description: |
                    Filter security events by acknowledgement status. If parameter is missing then response contains all events.
                count:
                  type: string
                  enum:
                    - engine
                    - url
                    - alertType
                    - deviceId
                    - infectionName
                    - categories
                    - appliedRule
                    - filePath
                    - description
                  description: |
                    Name of property to use in aggregation. All Security Events matching filter parameters are grouped and counted by selected property. This parameter is required when client sends request with HTTP header <code>Accept: application/vnd.withsecure.aggr+json</code>.
                anchor:
                  type: string
                  default: no-value
                  description: |
                    Anchor pointing to the page that should be retrieved. If the parameter is missing or equal to default value then endpoint returns first page.
                order:
                  type: string
                  enum:
                    - asc
                    - desc
                  default: desc
                  description: Sorting order
                exclusiveStart:
                  type: boolean
                  description: |
                    If equals <code>true</code>, then persistenceTimestampStart is used as exclusive lower bound. Otherwise, persistenceTimestampStart is inclusive.
                limit:
                  type: integer
                  format: int32
                  minimum: 1
                  maximum: 200
                  description: |
                    The size of the single batch. This value defines the upper bound for the number of items that are sent in a single response. However, it doesn't guarantee that the response will contain the exact number of items if the next page exists. Clients that read all items matching the query parameters should depend only on the <code>nextAnchor</code> property, which contains a link to the next result. Clients can stop iteration when the <code>nextAnchor</code> is missing in the response.
                language:
                  type: string
                  enum:
                    - en
                    - de
                    - es-MX
                    - fi
                    - fr
                    - it
                    - ja
                    - pl
                    - pt-BR
                    - sv
                    - zh-TW
                  description: |
                    Language of **message** and **description** field values. If not specified, the default language is used. The default language is English (en).
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            enum:
              - application/x-www-form-urlencoded
          description: |
            HTTP header that defines format of request body
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            enum:
              - application/json
              - application/vnd.withsecure.aggr+json
          description: |
            HTTP header defines expected format of response body. Client should use header <code>application/vnd.withsecure.aggr+json</code> to receive aggregated results - security events grouped and counted by selected property.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                List of EPP Security Events:
                  value:
                    items:
                      - id: 07a286cc-99ba-3538-8997-557076ff95ab_0
                        action: reported
                        engine: setting
                        severity: info
                        serverTimestamp: '2023-08-31T09:31:01.092Z'
                        persistenceTimestamp: '2023-08-31T09:31:03.292Z'
                        eventTransactionId: 0000-187cf62797634fef
                        clientTimestamp: '2023-08-31T07:31:03.292Z'
                        acknowledged: false
                        message: Firewall was turned on
                        description: Setting event
                        organization:
                          id: 222298dc-3785-4d2d-a957-f7399c2cd084
                          name: my-org
                        target:
                          name: 'Doe,John DESKTOP'
                          id: 71cceb9f-2728-4ac4-8e63-402cbbf76e18
                        device:
                          id: 71cceb9f-2728-4ac4-8e63-402cbbf76e18
                          name: 'Doe,John DESKTOP'
                        userName: John Doe
                        details:
                          profileName: My Company Profile
                          path: 'C:\Program Files\WithSecure\PSB\diagnostics\fsdiag.exe'
                          alertType: product.path.excluded
                          throttledCount: '0'
                          profileId: '12444818'
                          profileVersion: '34313431491'
                          hostIpAddress: 8.8.8.8/8
                          userName: John Doe
                          clientTimestamp: '1695889223479'
                    nextAnchor: link-to-next-page
                List of Collaboration Protection Security Events:
                  description: |
                    List contains one event generated by engine <code>emailScan</code> and one event generated by engine <code>teamsScan</code>. Because the latter affects multiple targets value  event doesn't contain property <code>target</code>.
                  value:
                    items:
                      - id: d522c33f-104b-33f6-b744-8b283e57111f_0
                        action: quarantined
                        severity: warning
                        organization:
                          id: 222298dc-3785-4d2d-a957-f7399c2cd084
                          name: my-org
                        engine: teamsScan
                        serverTimestamp: '2023-08-30T09:31:01.092Z'
                        persistenceTimestamp: '2023-08-30T09:31:03.292Z'
                        eventTransactionId: 0000-187cf62797634fef
                        details:
                          quarantineId: 7c8bf2ab-cdd8-4ef9-9e83-dbf13ecbd070
                          serviceType: o365-teams
                          severity: medium
                          eventId: 30ff8adf-3190-4bab-8923-2caaf954836a
                          itemType: TeamsChannelItem
                          created: '1693474260000'
                          category: harmfulContent
                          serviceId: c2a12a65-bd79-4f08-b83e-621ff907a245
                          reputation: unknown
                          detonation: false
                          reputationScore: '150'
                          prevalence: rare
                          fileName: my-file.txt
                          size: '184'
                          verdict: Unsafe
                          location: 'https://org1.sharepoint.com/sites/demo/Shared%20Documents/my-file.txt'
                      - id: dc8eddc5-2067-35b4-911f-a61b5e432d63_0
                        action: quarantined
                        severity: warning
                        acknowledged: true
                        acknowledgedBy: company-admin
                        ackTimestamp: '2023-09-01T09:31:01.092Z'
                        message: 'An MS Teams file ''file.txt'' was detected as ''harmful''. Action taken: ''Reported'''
                        description: Microsoft Teams scanning event
                        organization:
                          id: 222298dc-3785-4d2d-a957-f7399c2cd084
                          name: my-org
                        target:
                          name: jonis@abcdef.onmicrosoft.com
                          id: jonis@abcdef.onmicrosoft.com
                        engine: emailScan
                        serverTimestamp: '2023-08-31T09:31:01.092Z'
                        persistenceTimestamp: '2023-08-31T09:31:03.292Z'
                        eventTransactionId: 0000-187cf62797634fef
                        details:
                          quarantineId: 7c8bf2ab-cdd8-4ef9-9e83-dbf13ecbd070
                          serviceType: o365-exchange
                          severity: medium
                          unsafeAttachmentCount: '0'
                          eventId: 30ff8adf-3190-4bab-8923-2caaf954836a
                          itemType: EmailMessage
                          itemDateTimeReceived: '1693474255000'
                          created: '1693474260000'
                          itemSender: JoniS@abcdef.onmicrosoft.com
                          itemSubject: 123456 This is a Test Include Malicious attachments/url
                          internetMessageId: <E5A@DB9P1987.EURP193.PROD.OUTLOOK.COM>
                          urls: '[{"sha1":"29ef524c16cae0119e692998cb16d","verdict":"HarmfulUrl","reputation":"unsafe_url","reputationScore":"0","url":"http://mindinfected.domain.com"}]'
                          itemParentFolderName: Sent Items
                          itemSize: '10732'
                          category: harmfulContent
                          serviceId: c2a12a65-bd79-4f08-b83e-621ff907a245
                          unsafeUrlCount: '1'
                          userPrincipalName: jonis@abcdef.onmicrosoft.com
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        serverTimestamp:
                          type: string
                          format: date-time
                          description: 'Date and time of event being received by backend server. UTC+00:00'
                        clientTimestamp:
                          type: string
                          format: date-time
                          description: 'Date and time of event occurrence in client. UTC+00:00'
                        persistenceTimestamp:
                          type: string
                          format: date-time
                          description: 'Date and time of the event''s processing finish and its write to the database. UTC+00:00'
                        engine:
                          type: string
                          description: |
                            Name of an engine which raised the event.  For example: [
                              applicationControl,
                              browsingProtection,
                              dataGuard,
                              deviceControl,
                              connectionControl,
                              AMSI,
                              firewall,
                              integrityChecker,
                              fileScanning,
                              manualScanning,
                              reputationBasedBrowsing,
                              webContentControl,
                              tamperProtection,
                              webTrafficScanning,
                              edr,
                              emailScan,
                              emailBreach
                              teamsScan,
                              oneDriveScan,
                              sharePointScan
                            ]
                        severity:
                          type: string
                          enum:
                            - critical
                            - warning
                            - info
                          description: Severity of events
                        action:
                          type: string
                          description: |
                            Action performed to remove or mitigate the threat.  For example: [
                              none, 
                              allow, 
                              blocked, 
                              disinfected, 
                              quarantined, 
                              renamed, 
                              deleted, 
                              trashed, 
                              reported, 
                              reportedToUser, 
                              unspecified, 
                              merged, 
                              closed, 
                              created
                            ]
                        details:
                          type: object
                          description: |
                            Object containing a number of properties of an event. Actual set of properties depends on the engine. This property is optional.
                          additionalProperties: true
                        organization:
                          type: object
                          description: Organization to which belongs event's target
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: Id of organization
                            name:
                              type: string
                              description: name of organization
                          required:
                            - id
                            - name
                        device:
                          type: object
                          description: |
                            Optional details of device that reported event from EPP engine. This information is persisted only once, when security event occurs, and thus details might differ from /devices endpoint's response. 
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: Id of device
                            name:
                              type: string
                              description: Device name as visible in EPP portal
                            winsAddress:
                              type: string
                              description: WINS address
                            labels:
                              type: array
                              items:
                                type: string
                              description: List of labels of EPP device
                        target:
                          type: object
                          description: |
                            Optional details of affected entity. In events from EPP and EDR engines it is representation of device. In events from Collaboration Protection target represents Office 365 user id. Value is missing when event affects multiple targets.
                          properties:
                            id:
                              type: string
                              description: |
                                Id of affected entity (target). It might be UUID of EPP device in events from EPP and EDR engines or e-mail address in events from Collaboration Protection engines.
                            name:
                              type: string
                              description: |
                                Id of affected entity (target). It might be name EPP device in events from EPP and EDR engines or e-mail address in events from Collaboration Protection engines.
                        eventTransactionId:
                          type: string
                          description: |
                            id of the distributed transaction under which the event was created
                        userName:
                          type: string
                          description: |
                            Name of user that is related to this particular event. Property is present only in events from EPP and EDR engines
                        acknowledged:
                          type: boolean
                          description: |
                            acknowledgement status. Value is true if event was acknowledged
                        acknowledgedBy:
                          type: string
                          description: |
                            user that has acknowledged the event. This property is only present in the acknowledged events
                        ackTimestamp:
                          type: string
                          format: date-time
                          description: |
                            date and time of the event acknowledgement. This property is only present in the acknowledged events
                        message:
                          type: string
                          description: |
                            Human-readable text that describes this concrete event.
                        description:
                          type: string
                          description: |
                            Human-readable text that describes the event type.
                      required:
                        - id
                        - serverTimestamp
                        - persistenceTimestamp
                        - engine
                        - severity
                        - action
                        - message
                        - description
                  nextAnchor:
                    type: string
                    description: Anchor to be used to retrieve the next page. Not to be returned on the last page.
            application/vnd.withsecure.aggr+json:
              schema:
                type: object
                description: |
                  Response with aggregation results. It contains a summary of Security Events matching the request filters and the given time range. Security Events are grouped by the property specified in the request parameter <code>count</code>. For example, the response <code>{"items": [{"engine": "deepGuard", "count": 6}, {"engine": "edr", "count": 25}]}</code> means that the query found 6 Security Events from the <code>deepGuard</code> engine and 25 events from the <code>edr</code> engine.
                properties:
                  items:
                    type: array
                    description: |
                      List of aggregation rows. Each row contains common value of property used for aggregation and number of Security Events having that value.
                    items:
                      oneOf:
                        - type: object
                          properties:
                            count:
                              description: |
                                Number of Security Events having common value of property <code>alertType</code>.
                              type: number
                            alertType:
                              description: Common value of property used in aggregation
                              type: string
                        - type: object
                          properties:
                            count:
                              description: |
                                Number of Security Events having common value of property <code>infectionName</code>.
                              type: number
                            infectionName:
                              description: Common value of property used in aggregation
                              type: string
                        - type: object
                          properties:
                            count:
                              description: |
                                Number of Security Events having common value of property <code>description</code>.
                              type: number
                            description:
                              description: Common value of property used in aggregation
                              type: string
                        - type: object
                          properties:
                            count:
                              description: |
                                Number of Security Events having common value of property <code>deviceId</code>.
                              type: number
                            deviceId:
                              description: Common value of property used in aggregation.
                              type: string
                        - type: object
                          properties:
                            count:
                              description: |
                                Number of Security Events having common value of property <code>filePath</code>.
                              type: number
                            filePath:
                              description: Common value of property used in aggregation.
                              type: string
                        - type: object
                          properties:
                            count:
                              description: |
                                Number of Security Events having common value of property <code>appliedRule</code>.
                              type: number
                            appliedRule:
                              description: Common value of property used in aggregation.
                              type: string
                        - type: object
                          properties:
                            count:
                              description: |
                                Number of Security Events having common value of property <code>url</code>.
                              type: number
                            url:
                              description: Common value of property used in aggregation.
                              type: string
                        - type: object
                          properties:
                            count:
                              description: |
                                Number of Security Events having common value of property <code>engine</code>.
                              type: number
                            engine:
                              description: Common value of property used in aggregation
                              type: string
              examples:
                ECP Security Events aggregated by property engine:
                  value:
                    items:
                      - count: 4
                        engine: teamsScan
                      - count: 2
                        engine: inboxScan
                      - count: 18
                        engine: oneDriveScan
                EPP Security Events aggregated by url:
                  value:
                    items:
                      - count: 11
                        url: 'hxxp://unrated.testdomain.com'
                      - count: 43
                        url: 'hxxps://illegal.testdomain.com'
                      - count: 142
                        url: harmful.com
        '400':
          description: |
            The request failed because of missing required parameters  or incorrect parameters value.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400001 - request parameter has invalid format:
                  description: 'Indicates that the request parameters have the wrong format and can''t be converted to the target value. For example, a timestamp parameter that doesn''t match the date-time format. Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong format. Check details.
                    code: 400001
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: someTimestamp
                      invalidValue: '2022-10-6T12:1:14Z'
                400002 - request parameter has invalid type:
                  description: 'Indicates that the request parameters have a different type than expected. For example, a "string" value instead of an "integer". Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong type. Check details.
                    code: 400002
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: limit
                      invalidValue: some-string
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '404':
          description: The requested organization is not found.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
    get:
      tags:
        - security events
      security:
        - oAuth2:
            - connect.api.read
      operationId: events
      summary: Read list of security events (deprecated)
      deprecated: true
      description: |
        <p style="color: red"><strong>
          This endpoint is kept in maintenance mode which means it will receive only bugfixes and any new feature
          won't be added in the future. New integrations should use endpoint <a href="/api-reference/elements#post-/security-events/v1/security-events">POST /security-events/v1/security-events</a>.
        </strong></p> <p>
          List security events within specified time frame for given organization in specified order.
          Request with partner organizationId will return events for all companies in its hierarchy. </p>
        <p>To get valid response <code>persistenceTimestampStart</code> or <code>persistenceTimestampEnd</code> or <code>serverTimestampStart</code>
          or <code>serverTimestampEnd</code> must be used in query parameters. If query contains <code>persistenceTimestampStart</code> or
          <code>persistenceTimestampEnd</code> parameters then serverTimestamp parameters are ignored. It is recommended to use <code>persistenceTimestamp</code>
          for polling security events, because that attribute indicates time when processing of event ends. If events processing is delayed,
          query by <code>serverTimestamp</code> might return unstable results. It means, that two requests for same time range in the past, might
          return different list of events.
        </p> <p>By default <code>persistenceTimestampStart</code> and <code>serverTimestampStart</code> are used as <b>inclusive</b> range
           start. Default behavior can be changed with <code>exclusiveStart</code> parameter. If it equals <code>true</code>,
           then range start is exclusive. <a href="/getting-started/elements-cookbook#poll-security-events">Elements API Cookbook</a> 
           contains example implementation of Security Events polling. 
        </p> <p>
          When passing multiple values to <i>array</i> type parameters, values should be added to request query as multiple 
          parameters with the same name. For example: <code>...&engine={engine1}&engine={engine2}</code>
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/security-events/v1/security-events?organizationId={organizationId}&engine={engine}&persistenceTimestampStart={timestampStart}
          </code>
        </p>
      parameters:
        - name: organizationId
          in: query
          required: false
          description: |
            The UUID of an organization. If the organizationId is missing, the default organization of the authenticated client is used.
          schema:
            type: string
            format: uuid
            example: ec8a0100-d313-4896-b3cb-02188e060bf3
        - name: persistenceTimestampStart
          in: query
          required: false
          description: 'Lower bound for the persistence timestamp in the returned security events. The minimum allowed value is 2022-08-01T00:00:01Z.'
          schema:
            type: string
            format: date-time
        - name: persistenceTimestampEnd
          in: query
          required: false
          description: Upper exclusive bound for the persistence timestamp in the returned security events.
          schema:
            type: string
            format: date-time
        - name: serverTimestampStart
          in: query
          required: false
          description: Lower bound for the server timestamp in the returned security events.
          schema:
            type: string
            format: date-time
        - name: serverTimestampEnd
          in: query
          required: false
          description: Upper exclusive bound for the server timestamp in the returned security events.
          schema:
            type: string
            format: date-time
        - name: engine
          in: query
          required: false
          description: Filter by engines that triggered event.
          schema:
            type: array
            items:
              type: string
        - name: severity
          in: query
          required: false
          description: Filter by the severity of events.
          schema:
            type: array
            items:
              type: string
              enum:
                - critical
                - warning
                - info
        - name: anchor
          in: query
          required: false
          description: |
            Anchor pointing to the page that should be retrieved. If the parameter is missing or set to the default value, the endpoint returns the first page.
          schema:
            type: string
            default: no-value
        - name: order
          in: query
          required: false
          description: Specifies the sorting order.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: exclusiveStart
          in: query
          required: false
          description: |
            If set to "true", persistenceTimestampStart and serverTimestampStart are used as exclusive lower bounds. Otherwise, they are inclusive.
          schema:
            type: boolean
            default: false
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - name: limit
          in: query
          required: false
          description: |
            The size of the single batch. Value defines upper bound for number of items, that are sent in single response. However it doesn't guarantee, that response will contain exact number of items if next page exist. Client that reads all items matching query parameters should depend only on <code>nextAnchor</code> property, which contain link to next result. Client can stop iteration when <code>nextAnchor</code> is missing in response.
          schema:
            type: integer
            format: int32
            default: 200
            minimum: 1
            maximum: 200
      responses:
        '200':
          description: Security events page response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        serverTimestamp:
                          type: string
                          format: date-time
                          description: 'Date and time of event being received by backend server. UTC+00:00.'
                        clientTimestamp:
                          type: string
                          format: date-time
                          description: 'Date and time when the event occurred on the client. UTC+00:00.'
                        persistenceTimestamp:
                          type: string
                          format: date-time
                          description: 'Date and time when the event''s processing finished and it was written to the database. UTC+00:00.'
                        engine:
                          type: string
                          description: |
                            Name of the engine that raised the event.  For example: [
                              applicationControl,
                              browsingProtection,
                              dataGuard,
                              deepGuard,
                              deviceControl,
                              connectionControl,
                              AMSI,
                              firewall,
                              integrityChecker,
                              fileScanning,
                              manualScanning,
                              reputationBasedBrowsing,
                              webContentControl,
                              tamperProtection,
                              webTrafficScanning,
                              edr
                            ]
                        severity:
                          type: string
                          enum:
                            - critical
                            - warning
                            - info
                          description: Severity of the event.
                        action:
                          type: string
                          description: |
                            Action performed to remove or mitigate the threat.  For example: [
                              none, 
                              allow, 
                              blocked, 
                              disinfected, 
                              quarantined, 
                              renamed, 
                              deleted, 
                              trashed, 
                              reported, 
                              reportedToUser, 
                              unspecified, 
                              merged, 
                              closed, 
                              created
                            ]
                        details:
                          type: object
                          description: |
                            Object containing various properties of the event. The actual set of properties depends on the engine. This property is optional.
                        organization:
                          type: object
                          description: Organization to which the device reporting the event belongs.
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                          required:
                            - id
                            - name
                        device:
                          type: object
                          description: |
                            Device reporting the event. This information is persisted only once, when the security event occurs, and thus details might differ from the /devices endpoint's response.
                          properties:
                            id:
                              type: string
                              description: Device ID (UUID format).
                            name:
                              type: string
                              description: Device name as visible in the EPP portal.
                            winsAddress:
                              type: string
                              description: WINS address.
                          required:
                            - id
                        eventTransactionId:
                          type: string
                          description: |
                            ID of the distributed transaction under which the event was created.
                        userName:
                          type: string
                          description: |
                            Name of the user related to this particular event.
                      required:
                        - id
                        - serverTimestamp
                        - persistenceTimestamp
                        - engine
                        - severity
                        - action
                        - organization
                        - device
                  nextAnchor:
                    type: string
                    description: Anchor to be used to retrieve the next page. Not to be returned on the last page.
        '400':
          description: |
            Request failed because of missing required parameters  or incorrect parameters value.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400001 - request parameter has invalid format:
                  description: 'Indicates that the request parameters have the wrong format and can''t be converted to the target value. For example, a timestamp parameter that doesn''t match the date-time format. Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong format. Check details.
                    code: 400001
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: someTimestamp
                      invalidValue: '2022-10-6T12:1:14Z'
                400002 - request parameter has invalid type:
                  description: 'Indicates that the request parameters have a different type than expected. For example, a "string" value instead of an "integer". Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong type. Check details.
                    code: 400002
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: limit
                      invalidValue: some-string
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '404':
          description: Requested organization is not found.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
  /devices/v1/devices:
    get:
      tags:
        - devices
      security:
        - oAuth2:
            - connect.api.read
      operationId: devices
      summary: Query devices
      description: |
        <p>
           Execute queries related to an organization's devices. This endpoint can be used to:
          <ul>
            <li>List devices</li>
            <li>Get statistics about devices</li>
            <li>Get a histogram with device statistics for the last 30 days</li>
          </ul>
        </p> <p>
          The first use case is supported when the <code>Accept</code> header is set to <b>application/json</b>.
          The second use case requires the <code>Accept</code> header to be set to <b>application/vnd.withsecure.aggr+json</b> and 
          the <code>count</code> parameter to be set.
          The third use case requires the <code>Accept</code> header to be set to <b>application/vnd.withsecure.aggr+json</b> and 
          the <code>histogram</code> parameter to be set.
        </p> <p>
          With the <b>application/json</b> <code>Accept</code> header, the endpoint returns a list of devices.
          For a given organization, it retrieves devices matching all filters used in the query. 
          When the query contains the "deviceId" parameter, other filters are ignored.
        </p> <p>
          With the <b>application/vnd.withsecure.aggr+json</b> <code>Accept</code> header, the endpoint returns aggregations.
          Aggregations provide a useful statistical overview for the broader picture of an organization's assets.
          Devices are first filtered according to the provided query parameters and then grouped and counted.
          Use the <code>count</code> query parameter to select the property by which devices will be counted.
          The <code>histogram</code> query parameter works exactly the same as <code>count</code>, with the only difference being that 
          <code>histogram</code> will return aggregation data for the last 30 days.
          The <code>count</code> and <code>histogram</code> parameters cannot be used together in a single query.
          Filters supported with the <code>count</code> and <code>histogram</code> parameters include: organizationId, type, name, 
          online, label, clientVersion, and protectionStatusOverview.
        </p> <p>
            Examples:
            <ul>
              <li>
                <p>List devices for a given organization:</p>
                <p>
                  <code part="curl">
                  curl -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/json" https://api.connect.withsecure.com/devices/v1/devices?organizationId={organizationId}
                  </code>
                </p>
              </li>
              <li>
                <p>Count devices of type computer by protectionStatus for a given organization:</p>
                <p>
                  <code part="curl">
                    curl -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/vnd.withsecure.aggr+json" 
                    https://api.connect.withsecure.com/devices/v1/devices?organizationId={organizationId}&type=computer&count=protectionStatus
                  </code>
                </p>
              </li>
              <li>
                <p>Get protectionStatus histogram data from the last 30 days for devices of type computer:</p>
                <p>
                  <code part="curl">
                    curl -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/vnd.withsecure.aggr+json" 
                    https://api.connect.withsecure.com/devices/v1/devices?organizationId={organizationId}&type=computer&histogram=protectionStatus
                  </code>
                </p>
              </li>
            </ul>
        </p>
      parameters:
        - name: anchor
          in: query
          required: false
          description: |
            Anchor pointing to the page that should be retrieved. If the parameter is missing or set to the default value, the endpoint returns the first page.
          schema:
            type: string
            default: no-value
        - name: organizationId
          in: query
          required: false
          description: |
            The UUID of an organization. If the organizationId is missing, the default organization of the authenticated client is used.
          schema:
            type: string
            format: uuid
            example: ec8a0100-d313-4896-b3cb-02188e060bf3
        - name: deviceId
          in: query
          required: false
          description: UUID of a device.
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: |
            Filter by device type. Matches all devices of the specified type. If the type is not provided, all device types are included in the response.
          schema:
            type: string
            enum:
              - computer
              - connector
              - mobile
        - name: state
          in: query
          required: false
          description: |
            Filter devices by their state. Matches all devices with the specified state. If the state is not provided, only active devices will be included in the response.
          schema:
            type: string
            enum:
              - active
              - blocked
              - inactive
        - name: name
          in: query
          required: false
          description: Filter devices by device name (exact match).
          schema:
            type: string
        - name: serialNumber
          in: query
          required: false
          description: Filter devices by their exact serial number.
          schema:
            type: string
        - name: online
          in: query
          required: false
          description: Filter devices by online state.
          schema:
            type: boolean
        - name: label
          in: query
          required: false
          description: Filter by single label. Matches all devices that contain at least this label.
          schema:
            type: string
        - name: clientVersion
          in: query
          required: false
          description: Filters devices by client version (exact match).
          schema:
            type: string
        - name: protectionStatusOverview
          in: query
          required: false
          description: Filter devices by protection status overview.
          schema:
            type: string
            enum:
              - isolated
              - inactive
              - critical
              - warning
              - allOk
        - name: patchOverallState
          in: query
          required: false
          description: Filter devices by the state of software updates.
          schema:
            type: string
            enum:
              - missingCriticalUpdates
              - missingImportantUpdates
              - importantUpdatesInstalled
              - disabled
              - outdatedScanResults
              - notScannedYet
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - name: Accept
          in: header
          schema:
            type: string
            default: application/json
            enum:
              - application/json
              - application/vnd.withsecure.aggr+json
            description: |
              HTTP header that defines the expected format of the response body. Clients should use the header <code>application/vnd.withsecure.aggr+json</code> to receive aggregated results, where devices are grouped and counted by the selected property.
        - name: publicIpAddress
          in: query
          required: false
          description: The public IP address of the device.
          schema:
            type: string
        - name: organizationName
          in: query
          required: false
          description: The name of the organization (company or partner).
          schema:
            type: string
        - name: osName
          in: query
          required: false
          description: The name of the operating system installed on the device.
          schema:
            type: string
        - name: activeDirectoryGroup
          in: query
          required: false
          description: The name of the Active Directory group.
          schema:
            type: string
        - name: subscriptionKey
          in: query
          required: false
          description: |
            Filter by the subscription key with which the device registered. Only devices with the specified subscription key are returned. The required format is XXXX-XXXX-XXXX-XXXX-XXXX, where X is either a digit or an uppercase letter.
          schema:
            type: string
        - name: count
          in: query
          required: false
          schema:
            type: string
            enum:
              - protectionStatus
              - patchOverallState
              - firewallState
              - malwareState
          description: |
            Name of the property to use in aggregation. When the count parameter is provided and the <code>Accept</code> header is set to  <code>application/vnd.withsecure.aggr+json</code>, the response contains aggregation data.  Devices matching the query parameters are grouped and counted by the selected property values.  The <code>count</code> and <code>histogram</code> parameters cannot be used together in a single query.
        - name: histogram
          in: query
          required: false
          schema:
            type: string
            enum:
              - protectionStatus
          description: |
            Name of the property to use in histogram-type aggregation. When the histogram parameter is provided  and the <code>Accept</code> header is set to <code>application/vnd.withsecure.aggr+json</code>, the response contains aggregation data in histogram form. Aggregation data is returned for every date from the last 30 days.  Devices matching the query parameters are grouped and counted by the selected property values. The <code>count</code> and <code>histogram</code> parameters cannot be used together in a single query.
        - name: limit
          in: query
          required: false
          description: |
            Maximum number of devices to return in the response.
          schema:
            type: integer
            format: int32
            default: 200
            minimum: 1
            maximum: 200
      responses:
        '200':
          description: |
            List or aggregation of devices under given organization.  Includes mobile devices, servers and computers.
          content:
            application/json:
              schema:
                title: List devices response
                type: object
                properties:
                  items:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          description: Computer or server
                          properties:
                            activeDirectoryGroup:
                              type: string
                              description: Active directory group.
                            alias:
                              type: string
                              description: A custom alias name for the device.
                            applicationControlState:
                              type: string
                              description: Application Control overview state.
                              enum:
                                - enabled
                                - disabled
                            biosVersion:
                              type: string
                              description: version of bios.
                            browsingProtectionExtensionChrome:
                              type: string
                              description: Status of browsing protection extension in Chrome browser.
                              enum:
                                - enabled
                                - disabled
                                - unknown
                                - failed
                                - noBrowser
                            browsingProtectionExtensionEdge:
                              type: string
                              description: Status of browsing protection extension in Edge browser.
                              enum:
                                - enabled
                                - disabled
                                - unknown
                                - failed
                                - noBrowser
                            browsingProtectionExtensionFirefox:
                              type: string
                              description: Status of browsing protection extension in Firefox browser.
                              enum:
                                - enabled
                                - disabled
                                - unknown
                                - failed
                                - noBrowser
                            browsingProtectionExtensionSafari:
                              type: string
                              description: Status of browsing protection extension in Safari browser.
                              enum:
                                - enabled
                                - disabled
                                - unknown
                                - failed
                                - noBrowser
                            businessContext:
                              type: string
                              description: Business context information for the device.
                            clientVersion:
                              type: string
                              description: Client version.
                            company:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: Organization UUID.
                                name:
                                  type: string
                                  description: Organization name.
                                type:
                                  type: string
                                  enum:
                                    - company
                                    - sop
                                    - sep
                                  description: |
                                    Organization type:
                                      * company,
                                      * sop - solution provider,
                                      * sep - service partner.
                              required:
                                - id
                                - name
                            computerModel:
                              type: string
                              description: Computer model.
                            connectivityStatus:
                              type: string
                              description: Device connectivity status.
                              enum:
                                - connected
                                - always
                                - sometimes
                            currentUserAdmin:
                              type: boolean
                              description: Indicates if any of logged in users has administrator privileges.
                            dataguardState:
                              type: string
                              description: Dataguard overview state.
                              enum:
                                - enabled
                                - disabled
                            defaultBrowser:
                              type: string
                              description: Default browser set on the device.
                            defaultBrowserStatus:
                              type: string
                              description: Status of the default browser.
                            deviceControlState:
                              type: string
                              description: Device Control overview state.
                              enum:
                                - enabled
                                - disabled
                            discEncryptionEnabled:
                              type: boolean
                              description: Indicates if disc encryption is enabled.
                            dnsAddress:
                              type: string
                              description: DNS address.
                            edrIncidents:
                              type: object
                              description: information collected by EDR module.
                              properties:
                                riskHigh:
                                  type: integer
                                  description: number of incidents with high risk level.
                                riskLow:
                                  type: integer
                                  description: number of incidents with low risk level.
                                riskMedium:
                                  type: integer
                                  description: number of incidents with medium risk level.
                                riskSevere:
                                  type: integer
                                  description: number of incidents with severe risk level.
                            firewallState:
                              type: string
                              description: Firewall overview state.
                              enum:
                                - enabled
                                - disabled
                                - disabledByGpo
                                - disabledByGpoOk
                                - disabledOk
                                - disabledWs
                                - disabledMacOs
                            fullDiskAccessGranted:
                              type: boolean
                              description: Indicates if full disk access is granted on the Mac.
                            guestAccount:
                              type: boolean
                              description: Indicates if guest account is enabled.
                            id:
                              type: string
                              description: Device ID.
                            importance:
                              type: string
                              description: The importance level of the device.
                              enum:
                                - critical
                                - normal
                                - minor
                            installationTags:
                              type: string
                              description: Installation specific tags.
                            ipAddresses:
                              type: string
                              description: List of coma separated IP addresses.
                            ipv6Addresses:
                              type: string
                              description: List of coma separated IPv6 addresses.
                            labels:
                              type: array
                              items:
                                type: string
                              description: Device labels.
                            lastUser:
                              type: string
                              description: Last user of a device.
                            macAddresses:
                              type: string
                              description: List of coma separated MAC addresses.
                            malwareDbUpdateTimestamp:
                              type: string
                              format: date-time
                              description: Date and time of last update of malware database.
                            malwareDbVersion:
                              type: string
                              description: Version of malware database
                            malwareState:
                              type: string
                              description: Malware overview state.
                              enum:
                                - enabled
                                - disabled
                                - expired
                                - dangerousExclusions
                                - oldDefinitions
                                - malfunction
                                - notApplicable
                            name:
                              type: string
                              description: Device name as visible inside portal.
                            networkExtensionContentFilterServiceEnabled:
                              type: boolean
                              description: Indicates if network extension content filter service is enabled on the Mac.
                            online:
                              type: boolean
                              description: True if device has been communicating with backend during last 12 hours.
                            os:
                              type: object
                              properties:
                                name:
                                  type: string
                                  description: Operating System name
                                version:
                                  type: string
                                  description: Operating System version
                                endOfLife:
                                  type: boolean
                                  description: True if Operating System is no longer supported.
                            patchLastInstallTimestamp:
                              type: string
                              format: date-time
                              description: Last software update install time.
                            patchLastScanTimestamp:
                              type: string
                              format: date-time
                              description: Last software update scan time.
                            patchOverallState:
                              type: string
                              description: Patch management overview state.
                              enum:
                                - missingCriticalUpdates
                                - missingImportantUpdates
                                - importantUpdatesInstalled
                                - disabled
                                - outdatedScanResults
                                - notScannedYet
                            physicalMemoryFree:
                              type: integer
                              format: int64
                              description: Free physical memory (RAM) in bytes.
                            physicalMemoryTotalSize:
                              type: integer
                              format: int64
                              description: Total size of physical memory (RAM) in bytes.
                            profileName:
                              type: string
                              description: Current profile name.
                            profileState:
                              type: string
                              description: Profile assignment overview state.
                              enum:
                                - assignInProgress
                                - updateInProgress
                                - upToDate
                            protectionStatus:
                              type: string
                              description: 'Protection status, indicating if device is protected or showing the most severe issue.'
                              enum:
                                - activated
                                - notConnected
                                - protected
                                - subscriptionExpired
                                - firewallIssue
                                - malwareIssue
                                - isolated
                            protectionStatusOverview:
                              type: string
                              description: Protection status overview. See protectionStatus for details.
                              enum:
                                - isolated
                                - inactive
                                - critical
                                - warning
                                - allOk
                            publicInternet:
                              type: boolean
                              description: |
                                indicates if any of the <code>ipAddresses</code> is not in a private network. 
                            publicIpAddress:
                              type: string
                              description: Public IP address.
                            registrationTimestamp:
                              type: string
                              format: date-time
                              description: Registration timestamp.
                            serialNumber:
                              type: string
                              description: Device serial number.
                            state:
                              type: string
                              description: Device state.
                              enum:
                                - active
                                - blocked
                                - inactive
                            statusUpdateTimestamp:
                              type: string
                              format: date-time
                              description: Status update timestamp.
                            subscription:
                              type: object
                              properties:
                                key:
                                  type: string
                                  description: Key.
                                name:
                                  type: string
                                  description: Full product name.
                                productVariant:
                                  type: string
                                  enum:
                                    - mobileprotection
                                    - mobileprotection_vpn
                                    - computerprotection
                                    - computerprotection_premium
                                    - computerprotection_edr
                                    - computerprotection_premium_edr
                                    - edr
                                    - radar
                                    - serversecurity
                                    - serverprotection_premium
                                    - serverprotection_premium_rdr
                                    - rdr_server
                                    - elements_connector
                                  description: Product variant
                            systemDriveFreeSpace:
                              type: integer
                              format: int64
                              description: Free space on system hard drive in bytes.
                            systemDriveTotalSize:
                              type: integer
                              format: int64
                              description: Total size of system hard drive in bytes.
                            systemExtensionEnabled:
                              type: boolean
                              description: Indicates if system extension is enabled on the Mac.
                            systemIntegrityProtectionEnabled:
                              type: boolean
                              description: Indicates if system integrity protection is enabled on the Mac.
                            type:
                              type: string
                              description: Device type specifier.
                              enum:
                                - computer
                            unreachableConnectionAddresses:
                              type: array
                              items:
                                type: string
                              description: List of always failing connection addresses.
                            unstableConnectionAddresses:
                              type: array
                              items:
                                type: string
                              description: List of sometimes failing connection addresses.
                            userPrincipalName:
                              type: string
                              description: User principal name (UPN).
                            vmRiskScore:
                              type: integer
                              description: |
                                Vulnerability Management risk score. Calculated only for devices with active VM module
                            winsAddress:
                              type: string
                              description: WINS address.
                          required:
                            - id
                        - type: object
                          description: Elements Connector
                          properties:
                            alias:
                              type: string
                              description: A custom alias name for the device.
                            businessContext:
                              type: string
                              description: Business context information for the device.
                            clientVersion:
                              type: string
                              description: Client version.
                            company:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: Organization UUID.
                                name:
                                  type: string
                                  description: Organization name.
                                type:
                                  type: string
                                  enum:
                                    - company
                                    - sop
                                    - sep
                                  description: |
                                    Organization type:
                                      * company,
                                      * sop - solution provider,
                                      * sep - service partner.
                              required:
                                - id
                                - name
                            id:
                              type: string
                              description: Device ID.
                            importance:
                              type: string
                              description: The importance level of the device.
                              enum:
                                - critical
                                - normal
                                - minor
                            labels:
                              type: array
                              items:
                                type: string
                              description: Device labels.
                            name:
                              type: string
                              description: User-friendly device name.
                            online:
                              type: boolean
                              description: True if the device has been communicating with the backend during the last 12 hours.
                            os:
                              type: object
                              properties:
                                name:
                                  type: string
                                  description: Operating System name.
                                version:
                                  type: string
                                  description: Operating System version.
                            profileName:
                              type: string
                              description: Current profile name.
                            profileState:
                              type: string
                              description: Profile assignment overview state.
                              enum:
                                - assignInProgress
                                - updateInProgress
                                - upToDate
                            protectionStatus:
                              type: string
                              description: 'Protection status, indicating if the device is protected or showing the most severe issue.'
                              enum:
                                - activated
                                - notConnected
                                - protected
                                - subscriptionExpired
                                - firewallIssue
                                - malwareIssue
                                - isolated
                            protectionStatusOverview:
                              type: string
                              description: Protection status overview. See protectionStatus for details.
                              enum:
                                - isolated
                                - inactive
                                - critical
                                - warning
                                - allOk
                            registrationTimestamp:
                              type: string
                              format: date-time
                              description: Registration timestamp.
                            state:
                              type: string
                              description: Device state.
                              enum:
                                - active
                                - blocked
                                - inactive
                            statusUpdateTimestamp:
                              type: string
                              format: date-time
                              description: Status update timestamp.
                            subscription:
                              type: object
                              properties:
                                key:
                                  type: string
                                  description: Key.
                                name:
                                  type: string
                                  description: Full product name.
                                productVariant:
                                  type: string
                                  enum:
                                    - mobileprotection
                                    - mobileprotection_vpn
                                    - computerprotection
                                    - computerprotection_premium
                                    - computerprotection_edr
                                    - computerprotection_premium_edr
                                    - edr
                                    - radar
                                    - serversecurity
                                    - serverprotection_premium
                                    - serverprotection_premium_rdr
                                    - rdr_server
                                    - elements_connector
                                  description: Product variant
                            type:
                              type: string
                              description: Device type specifier.
                              enum:
                                - connector
                          required:
                            - id
                        - type: object
                          description: Mobile device
                          properties:
                            alias:
                              type: string
                              description: Device alias.
                            businessContext:
                              type: string
                              description: Business context information for the device.
                            clientVersion:
                              type: string
                              description: Client version.
                            company:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: Organization UUID.
                                name:
                                  type: string
                                  description: Organization name.
                                type:
                                  type: string
                                  enum:
                                    - company
                                    - sop
                                    - sep
                                  description: |
                                    Organization type:
                                      * company,
                                      * sop - solution provider,
                                      * sep - service partner.
                              required:
                                - id
                                - name
                            email:
                              type: string
                              description: User email.
                            firstName:
                              type: string
                              description: User first name.
                            id:
                              type: string
                              description: Device ID.
                            importance:
                              type: string
                              description: The importance level of the device.
                              enum:
                                - critical
                                - normal
                                - minor
                            labels:
                              type: array
                              items:
                                type: string
                              description: Device labels.
                            lastName:
                              type: string
                              description: User last name.
                            os:
                              type: object
                              properties:
                                name:
                                  type: string
                                  description: Operating System name.
                                version:
                                  type: string
                                  description: Operating System version.
                                securityPatch:
                                  type: string
                                  description: Operating System security patch identifier.
                            profileName:
                              type: string
                              description: Current profile name.
                            profileState:
                              type: string
                              description: Profile assignment overview state.
                              enum:
                                - assignInProgress
                                - updateInProgress
                                - upToDate
                            protectionStatus:
                              type: string
                              description: 'Protection status, indicating if the device is protected or showing the most severe issue.'
                              enum:
                                - activated
                                - notConnected
                                - protected
                                - subscriptionExpired
                                - firewallIssue
                                - malwareIssue
                                - isolated
                            protectionStatusOverview:
                              type: string
                              description: Protection status overview. See protectionStatus for details.
                              enum:
                                - isolated
                                - inactive
                                - critical
                                - warning
                                - allOk
                            registrationTimestamp:
                              type: string
                              format: date-time
                              description: Registration timestamp.
                            state:
                              type: string
                              description: Device state.
                              enum:
                                - active
                                - blocked
                                - inactive
                            statusUpdateTimestamp:
                              type: string
                              format: date-time
                              description: Status update timestamp.
                            subscription:
                              type: object
                              properties:
                                key:
                                  type: string
                                  description: Key.
                                name:
                                  type: string
                                  description: Full product name.
                                productVariant:
                                  type: string
                                  enum:
                                    - mobileprotection
                                    - mobileprotection_vpn
                                    - computerprotection
                                    - computerprotection_premium
                                    - computerprotection_edr
                                    - computerprotection_premium_edr
                                    - edr
                                    - radar
                                    - serversecurity
                                    - serverprotection_premium
                                    - serverprotection_premium_rdr
                                    - rdr_server
                                    - elements_connector
                                  description: Product variant
                            type:
                              type: string
                              description: Device type specifier.
                              enum:
                                - mobile
                          required:
                            - id
                    description: List of devices.
                  nextAnchor:
                    type: string
                    description: Anchor to be used to retrieve the next page. Not to be returned on the last page.
                required:
                  - items
            application/vnd.withsecure.aggr+json:
              schema:
                title: Aggregate devices response
                type: object
                properties:
                  items:
                    type: array
                    description: List of aggregations ordered by date in descending order
                    items:
                      oneOf:
                        - type: object
                          description: protectionStatus aggregation
                          properties:
                            date:
                              type: string
                              format: date
                              description: Date of entry - field is returned only when histogram is requested
                            protectionStatus:
                              type: string
                              enum:
                                - activated
                                - notConnected
                                - protected
                                - subscriptionExpired
                                - firewallIssue
                                - malwareIssue
                                - isolated
                              description: One of possible protectionStatus values. Only entries with non-zero counts are returned.
                            count:
                              type: number
                              description: Number of devices with given protectionStatus
                        - type: object
                          description: patchOverallState aggregation
                          properties:
                            patchOverallState:
                              type: string
                              enum:
                                - missingCriticalUpdates
                                - missingImportantUpdates
                                - importantUpdatesInstalled
                                - disabled
                                - outdatedScanResults
                                - notScannedYet
                              description: One of the possible patchOverallState values. Only entries with non-zero counts are returned.
                            count:
                              type: number
                              description: Number of devices with the given patchOverallState.
                        - type: object
                          description: firewallState aggregation
                          properties:
                            firewallState:
                              type: string
                              enum:
                                - enabled
                                - disabled
                                - disabledByGpo
                                - disabledByGpoOk
                                - disabledOk
                                - disabledWs
                                - disabledMacOs
                              description: One of possible firewallState values. Only entries with non-zero counts are returned.
                            count:
                              type: number
                              description: Number of devices with given firewallState
                        - type: object
                          description: malwareState aggregation
                          properties:
                            malwareState:
                              type: string
                              enum:
                                - enabled
                                - disabled
                                - expired
                                - dangerousExclusions
                                - oldDefinitions
                                - malfunction
                                - notApplicable
                              description: One of possible malwareState values. Only entries with non-zero counts are returned.
                            count:
                              type: number
                              description: Number of devices with given malwareState
                required:
                  - items
              examples:
                protectionStatus count:
                  value:
                    items:
                      - protectionStatus: protected
                        count: 10
                      - protectionStatus: notConnected
                        count: 2
                protectionStatus histogram:
                  value:
                    items:
                      - date: '2024-01-23'
                        protectionStatus: protected
                        count: 10
                      - date: '2024-01-23'
                        protectionStatus: notConnected
                        count: 2
                      - date: '2024-01-22'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-22'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-21'
                        protectionStatus: protected
                        count: 9
                      - date: '2024-01-21'
                        protectionStatus: notConnected
                        count: 3
                      - date: '2024-01-20'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-20'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-19'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-19'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-18'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-18'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-17'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-17'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-16'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-16'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-15'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-15'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-14'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-14'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-13'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-13'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-12'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-12'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-11'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-11'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-10'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-10'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-09'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-09'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-08'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-08'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-07'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-07'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-06'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-06'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-05'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-05'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-04'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-04'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-03'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-03'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-02'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-02'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2024-01-01'
                        protectionStatus: protected
                        count: 11
                      - date: '2024-01-01'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2023-12-31'
                        protectionStatus: protected
                        count: 11
                      - date: '2023-12-31'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2023-12-30'
                        protectionStatus: protected
                        count: 11
                      - date: '2023-12-30'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2023-12-29'
                        protectionStatus: protected
                        count: 11
                      - date: '2023-12-29'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2023-12-28'
                        protectionStatus: protected
                        count: 11
                      - date: '2023-12-28'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2023-12-27'
                        protectionStatus: protected
                        count: 11
                      - date: '2023-12-27'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2023-12-26'
                        protectionStatus: protected
                        count: 11
                      - date: '2023-12-26'
                        protectionStatus: notConnected
                        count: 1
                      - date: '2023-12-25'
                        protectionStatus: protected
                        count: 12
        '400':
          description: |
            The request failed due to missing required parameters  or incorrect parameter values.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400001 - request parameter has invalid format:
                  description: 'Indicates that the request parameters have the wrong format and can''t be converted to the target value. For example, a timestamp parameter that doesn''t match the date-time format. Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong format. Check details.
                    code: 400001
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: someTimestamp
                      invalidValue: '2022-10-6T12:1:14Z'
                400002 - request parameter has invalid type:
                  description: 'Indicates that the request parameters have a different type than expected. For example, a "string" value instead of an "integer". Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong type. Check details.
                    code: 400002
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: limit
                      invalidValue: some-string
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send the request. Ensure that the request  contains an Authentication header with a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
    patch:
      tags:
        - devices
      security:
        - oAuth2:
            - connect.api.write
      operationId: updateDevices
      summary: Update devices
      description: |
        <p>
          This endpoint can be used to:
          <ul>
            <li><a href="#state-update">Change device state</a></li>
            <li><a href="#subscription-update">Change device subscription</a></li>
            <li><a href="#alias-update">Update device alias</a></li>
            <li><a href="#importance-update">Update device importance</a></li>
            <li><a href="#business-context-update">Update device business context</a></li>
            <li><a href="#labels-update">Update device labels</a></li>
          </ul>
        </p> <a id="state-update"></a> <h3>Change device state</h3> <p>
          The following table presents possible state updates with the allowed device type and state for each transition. Use the <a href="/api-reference/elements#get-/devices/v1/devices">device query</a> to filter devices by type and state. If a device is already in the desired state, it will have a status of 200 in the response.
        </p> <table>
          <tr><th>State Update</th><th><code>state</code> Parameter</th><th>Allowed Device Type</th><th>Allowed Device State</th><th>Description</th></tr>
          <tr>
            <td>Block Devices</td>
            <td>blocked</td>
            <td>computer</td>
            <td>active</td>
            <td>After the operation, devices stop sending information to WithSecure services. Blocked devices don't occupy subscription seats and are not visible on the portal devices list. 
                <b>Devices can be restored from this state - use inactivate devices for this.</b></td>
          </tr>
          <tr>
            <td>Inactivate Devices</td>
            <td>inactive</td>
            <td>computer, mobile, connector</td>
            <td>active, blocked</td>
            <td>When a device is inactive, it doesn't occupy a subscription seat and is not visible on the portal devices list. If the inactive device is turned on, it will try to connect to the WithSecure services and will become active automatically upon succeeding. Subscription seats are checked during connection: if there is a free seat, the device will be activated; otherwise, it will stay inactive.</td>
          </tr>
        </table> <p>
          Request example: </br>
        </p> <p>
          <code part="curl">
            curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/devices/v1/devices -d '{"state": "blocked", "targets": ["ec8a0100-d313-4896-b3cb-02188e060bf3"]}'
          </code>
        </p> <a id="subscription-update"></a> <h3>Change device subscription</h3> <p>
          Solution providers can move devices to company-level subscriptions. 
          Subscriptions can belong to the same company, two different companies, or be moved from partner level to company level. 
          Moving devices from company-level subscriptions to partner-level subscriptions is not allowed. 
          Not all transitions are possible based on subscription types; for example, changing from an EPP+EDR subscription to an EDR-only subscription will fail. 
          If a device is already in the subscription specified in the request, it will have a status of 200 in the response.
        </p> <p>
          Request example: </br>
        </p> <p>
          <code part="curl">
            curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/devices/v1/devices -d '{"subscriptionKey": "XXXX-XXXX-XXXX-XXXX-XXXX", "targets": ["ec8a0100-d313-4896-b3cb-02188e060bf3"]}'
          </code>
        </p> <a id="alias-update"></a> <h3>Update device alias</h3> <p>
          Set a custom alias name for a device. This allows you to assign a human-readable name to a device for easier identification.
          The alias can be any string value. Only one device can be updated at a time when setting an alias.
        </p> <p>
          Request example: </br>
        </p> <p>
          <code part="curl">
            curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/devices/v1/devices -d '{"alias": "CEO Laptop", "targets": ["ec8a0100-d313-4896-b3cb-02188e060bf3"]}'
          </code>
        </p> <a id="importance-update"></a> <h3>Update device importance</h3> <p>
          Set the importance level of devices. This helps prioritize devices based on their criticality to your organization.
          Available importance levels are: <code>critical</code>, <code>normal</code>, and <code>minor</code>.
        </p> <p>
          Request example: </br>
        </p> <p>
          <code part="curl">
            curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/devices/v1/devices -d '{"importance": "critical", "targets": ["ec8a0100-d313-4896-b3cb-02188e060bf3"]}'
          </code>
        </p> <a id="business-context-update"></a> <h3>Update device business context</h3> <p>
          Set business context information for a device. This allows you to associate devices with specific business units, departments, 
          or purposes to help with organization and reporting.
        </p> <p>
          Request example: </br>
        </p> <p>
          <code part="curl">
            curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/devices/v1/devices -d '{"businessContext": "Finance Department - Payment Processing", "targets": ["ec8a0100-d313-4896-b3cb-02188e060bf3"]}'
          </code>
        </p> <a id="labels-update"></a> <h3>Update device labels</h3> <p>
          Replace the labels assigned to devices. This operation replaces all existing labels on the specified devices with the new set of labels provided.
          Labels help categorize and organize devices for easier management and filtering.
        </p> <p>
          Request example: </br>
        </p> <p>
          <code part="curl">
            curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/devices/v1/devices -d '{"labels": ["production", "finance", "critical-asset"], "targets": ["ec8a0100-d313-4896-b3cb-02188e060bf3"]}'
          </code>
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      requestBody:
        content:
          application/json:
            examples:
              Block devices:
                value:
                  state: blocked
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Inactivate devices:
                value:
                  state: inactive
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Change subscription key:
                value:
                  subscriptionKey: E43V-DE4H-U2X8-87L2-438V
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Update device alias:
                value:
                  alias: CEO Laptop
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
              Update device importance:
                value:
                  importance: critical
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
              Update device business context:
                value:
                  businessContext: Finance Department - Payment Processing
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
              Update device labels:
                value:
                  labels:
                    - production
                    - finance
                    - critical-asset
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
            schema:
              type: object
              oneOf:
                - type: object
                  properties:
                    state:
                      type: string
                      description: The state to which the device will be changed.
                      enum:
                        - blocked
                        - inactive
                    targets:
                      type: array
                      description: A list of targets (device identifiers) whose state will be changed.
                      items:
                        type: string
                      maxItems: 5
                      minItems: 1
                  required:
                    - state
                    - targets
                - type: object
                  properties:
                    subscriptionKey:
                      type: string
                      description: The key of the subscription to which the devices will be moved.
                    targets:
                      type: array
                      description: A list of targets (device identifiers) whose subscription will be changed.
                      items:
                        type: string
                      maxItems: 5
                      minItems: 1
                  required:
                    - subscriptionKey
                    - targets
                - type: object
                  properties:
                    alias:
                      type: string
                      description: A custom alias name for the device.
                    targets:
                      type: array
                      description: A single target (device identifier) to update the alias for.
                      items:
                        type: string
                      maxItems: 1
                      minItems: 1
                  required:
                    - alias
                    - targets
                - type: object
                  properties:
                    importance:
                      type: string
                      description: The importance level of the device.
                      enum:
                        - critical
                        - normal
                        - minor
                    targets:
                      type: array
                      description: A list of targets (device identifiers) whose importance will be changed.
                      items:
                        type: string
                      maxItems: 5
                      minItems: 1
                  required:
                    - importance
                    - targets
                - type: object
                  properties:
                    businessContext:
                      type: string
                      description: Business context information for the device.
                    targets:
                      type: array
                      description: A list of targets (device identifiers) whose business context will be changed.
                      items:
                        type: string
                      maxItems: 5
                      minItems: 1
                  required:
                    - businessContext
                    - targets
                - type: object
                  properties:
                    labels:
                      type: array
                      description: A list of labels to assign to the devices. This replaces all existing labels.
                      items:
                        type: string
                      minItems: 1
                      maxItems: 64
                    targets:
                      type: array
                      description: A list of targets (device identifiers) whose labels will be replaced.
                      items:
                        type: string
                      maxItems: 5
                      minItems: 1
                  required:
                    - labels
                    - targets
      responses:
        '207':
          description: The request payload was valid and processed in the internal backend.
          content:
            application/json:
              examples:
                All operations triggered successfully:
                  value:
                    multistatus:
                      - target: ec8a0100-d313-4896-b3cb-02188e060bf3
                        status: 200
                      - target: 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                        status: 200
                      - target: 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                        status: 200
                      - target: 181fd624-1db0-49b8-b1b9-b88d6336bd75
                        status: 200
                      - target: 21ccd888-01cc-459d-9341-2001508a83fc
                        status: 200
                    transactionId: 0000-abcdef-1234
                Some change device state operations couldn't be triggered:
                  value:
                    multistatus:
                      - target: ec8a0100-d313-4896-b3cb-02188e060bf3
                        status: 404
                        details: Not found
                      - target: 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                        status: 400
                        details: 'Requested device is in invalid state. State: inactive'
                      - target: 181fd624-1db0-49b8-b1b9-b88d6336bd75
                        status: 200
                      - target: 21ccd888-01cc-459d-9341-2001508a83fc
                        status: 200
                    transactionId: 0000-abcdef-1234
                Some change device subscription operations couldn't be triggered:
                  value:
                    multistatus:
                      - target: ec8a0100-d313-4896-b3cb-02188e060bf3
                        status: 404
                        details: Not found
                      - target: 00914ad6-1585-4560-99c8-34f806b6a096
                        status: 400
                        details: Product transition is not allowed.
                      - target: 1c49df1a-02d9-4bc4-91db-5609b80ad709
                        status: 400
                        details: Subscription not found.
                      - target: 169d6bb6-064c-4549-9f26-1bca8dd164ca
                        status: 400
                        details: New subscription can't be a partner level subscription.
                      - target: 2accab2b-8604-45d5-9d0f-144ed185b3dc
                        status: 400
                        details: New subscription doesn't have free seats.
                    transactionId: 0000-abcdef-1234
              schema:
                type: object
                properties:
                  multistatus:
                    description: |
                      Contains information about triggering operation.
                    type: array
                    items:
                      type: object
                      properties:
                        target:
                          type: string
                          description: 'Device identifier, corresponds to elements from request `targets` array.'
                        status:
                          type: integer
                          description: |
                            HTTP status of the triggering operation for a particular device. A response with status code 200 means that the device exists within the scope of the client's organization and the operation was successful in the internal backend.
                        details:
                          type: string
                          description: |
                            Details about the triggering operation. It might include information about the reason for failure.
                      required:
                        - target
                        - status
                  transactionId:
                    type: string
                    description: The transaction ID for the request to the Elements API.
                required:
                  - transactionId
                  - multistatus
        '400':
          description: |
            The request failed because required properties are missing in the request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - invalid format of target id:
                  description: |
                    The error indicates that at least one of the elements in the targets property has an incorrect format.
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      targets: All targets must be in UUID format.
        '401':
          description: |
            The user is not authorized to send the request. Ensure that the request  contains an Authentication header with a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user has insufficient privileges to send the request.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - insufficient scope:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
                403002 - wrong organization type:
                  value:
                    message: Operation allowed only for SOP.
                    code: 403002
                    transactionId: 0000-someTransactionId
    delete:
      tags:
        - devices
      security:
        - oAuth2:
            - connect.api.write
      operationId: removeDevices
      summary: Delete devices
      description: |
        <p>
          Delete devices. After the operation, subscription seats are freed and devices are no longer visible on the devices list. To start using the WithSecure product again, reinstall it on the machine. 
          After deletion and reinstallation, the device is assigned a new UUID. The query accepts a limited number of device IDs. Before processing the request, duplicates are removed from the list.
        </p> <p>
          Request example: </br>
          <code part="curl">
           curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/devices/v1/devices?deviceId=ec8a0100-d313-4896-b3cb-02188e060bf3&deviceId=01898f1e-d32d-40fe-b3c5-9f039c1eac04
          </code>
        </p>
      parameters:
        - name: deviceId
          in: query
          required: true
          description: A list of device IDs to be deleted. Up to 20 items are allowed.
          schema:
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 20
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
      responses:
        '200':
          description: Devices are deleted.
          content:
            application/json:
              examples:
                All devices deleted successfully:
                  value:
                    devices:
                      - ec8a0100-d313-4896-b3cb-02188e060bf3
                      - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                Some devices failed to delete:
                  value:
                    devices:
                      - ec8a0100-d313-4896-b3cb-02188e060bf3
              schema:
                type: object
                properties:
                  devices:
                    type: array
                    description: A list of deleted devices (duplicates removed).
                    items:
                      type: string
        '400':
          description: |
            The request failed due to missing required parameters  or incorrect parameter values.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - too many device ids provided:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - invalid parameter value:
                  description: The request parameter has an incorrect value. The error response details include the name of the invalid parameter and the reason it was rejected.
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      deviceId: All deviceId must match UUID format
                400005 - missing required request query parameter:
                  description: A required query parameter was not provided in the request.
                  value:
                    message: Required request query parameter is missing.
                    code: 400005
                    transactionId: 0000-someTransactionId
                    details:
                      missingParam: deviceId
        '401':
          description: |
            The user is not authorized to send the request. Ensure that the request  contains an Authentication header with a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user has insufficient privileges to send the request. Ensure that the token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
  /devices/v1/operations:
    post:
      tags:
        - devices
      security:
        - oAuth2:
            - connect.api.write
      operationId: triggerDeviceOperation
      summary: Trigger remote operations on devices
      description: |
        <p>
          Triggers a new operation on devices whose UUIDs are provided in the request body. Devices must belong to the client's organization and be in an active state.
         </p>
         <p>
           Triggering has two stages:
           <ul>
             <li>The operation is created in the internal backend</li>
             <li>The operation is triggered on the remote host</li>
           </ul>
         </p>
         <p>
           A successful response only means that the operation was created in the internal backend (first stage). 
           The client can <a href="/api-reference/elements#get-/devices/v1/devices/operations">query operations for the device</a> to check the status from the remote host (second stage).
           Depending on the operation type, additional arguments might be required - they should be sent
           in the body as a <code>parameters</code> map-like object. Operation-specific information in the response may be returned in the <code>metadataParameters</code> map-like object.
           Check the list of supported operations for more details.
         </p>
          <h2>Supported operations</h2>
         <table>
         <tr>
           <th>Operation type</th>
           <th>Allowed for device type</th>
           <th>Parameters</th>
           <th>Metadata parameters</th></tr>
         <tr>
           <td>assignProfile — assign a profile to a device</td>
           <td>computer, mobile, connector</td>
           <td>
             <ul>
               <li>profileId <b>(mandatory)</b> - id of the profile to assign. It can be found in the profile settings view, 
         which is available when selecting a profile under the Endpoint Protection/Profiles tab in the Elements Portal.</li>
             </ul>
           </td>
           <td></td>
         </tr>
         <tr>
           <td>collectDiagnosticFile — collect a diagnostic file from a device</td>
           <td>computer, mobile</td>
           <td>
             <ul>
               <li>consentMessage - message to show to the user of the device. The user may allow diagnostic data to be uploaded to the WithSecure™ or deny it. Maximum length of the message is 512 characters.</li>
             </ul>
           </td>
           <td>
             <ul>
               <li>fileId - reference number of the diagnostic file (also referred to as fsdiag or wsdiag) that will be generated</li>
             </ul>
           </td>
         </tr>
         <tr>
           <td>installSoftwareUpdates — install software updates on a device</td>
           <td>computer</td>
           <td>
             <p>Pass either bulletinIds or severity. Not both.</p>
             <ul>
               <li>bulletinIds - bulletin IDs of the software updates that should be installed. These can be retrieved from the /v1/missing-updates endpoint</a>.</li>
               <li>forceClose - enforce closing the applications that are upgraded.</li>
               <li>severity - severity of the software updates that should be installed.</li>
             </ul>
           </td>
           <td>
           </td>
         </tr>
         <tr>
           <td>isolateFromNetwork — isolate a device from network</td>
           <td>computer</td>
           <td>
             <ul>
               <li>message - message that is displayed on isolated host before the device is isolated from network.</li>
             </ul>
           </td>
           <td></td>
         </tr>
         <tr>
           <td>releaseFromNetworkIsolation — release a device from network isolation</td>
           <td>computer</td>
           <td></td>
           <td></td>
         </tr>
         <tr>
           <td>scanForMalware — scan for malware on a device</td>
           <td>computer, mobile</td>
           <td></td>
           <td></td>
         </tr>
         <tr>
           <td>scanForUpdates — scan for software updates on a device</td>
           <td>computer</td>
           <td></td>
           <td></td>
         </tr>
         <tr>
           <td>sendFullStatus — request a full status update from a device</td>
           <td>computer, mobile</td>
           <td></td>
           <td></td>
         </tr>
         <tr>
           <td>showMessage — show a message on a device</td>
           <td>computer, mobile</td>
           <td>
             <ul>
               <li>message <b>(mandatory)</b> - text to show on the remote host.</li>
             </ul>
           </td>
           <td></td>
         </tr>
         <tr>
           <td>turnOnFeature — turn on a feature on a device</td>
           <td>computer</td>
           <td>
             <ul>
               <li>feature <b>(mandatory)</b> - feature to turn on. Allowed values: debugLogging.</li>
               <li>turnOnTimeout <b>(mandatory)</b> - number of minutes after which debug logging will be turned off automatically. Must be between 5 and 1440.
         Debug logging also turns off automatically with the device restart.</li>
             </ul>
           </td>
           <td></td>
         </tr>
         <tr>
           <td>restartProduct — restart WithSecure agent software on a device</td>
           <td>computer (Windows only)</td>
           <td></td>
           <td></td>
         </tr>
         <tr>
           <td>restartSystem — restart a device</td>
           <td>computer (Windows only)</td>
           <td>
             <ul>
               <li>message - text to show on the remote host before the device is restarted.</li>
             </ul>
           </td>
           <td></td>
         </tr>
         </table>
         
         <p>
           Request example: </br>
           <code part="curl">
            curl -X POST -d '{"operation":"isolateFromNetwork","parameters":{"message":"Your device will be isolated"},"targets":["ec8a0100-d313-4896-b3cb-02188e060bf3", "01898f1e-d32d-40fe-b3c5-9f039c1eac04", "1226e0a9-653a-4682-b4ad-6a2fd54218b9", "181fd624-1db0-49b8-b1b9-b88d6336bd75", "21ccd888-01cc-459d-9341-2001508a83fc"]}' -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/devices/v1/operations
           </code>
         </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      requestBody:
        content:
          application/json:
            examples:
              Install all software updates:
                value:
                  operation: installSoftwareUpdates
                  parameters:
                    severity: everything
                    forceClose: true
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
              Install (selected) software updates:
                value:
                  operation: installSoftwareUpdates
                  parameters:
                    bulletinIds:
                      - '1234567890'
                    forceClose: true
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
              Isolate from network:
                value:
                  operation: isolateFromNetwork
                  parameters:
                    message: Your computer has been isolated
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Release from network isolation:
                value:
                  operation: releaseFromNetworkIsolation
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Assign profile:
                value:
                  operation: assignProfile
                  parameters:
                    profileId: 901566
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Scan for malware:
                value:
                  operation: scanForMalware
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Scan for updates:
                value:
                  operation: scanForUpdates
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
              Send full status:
                value:
                  operation: sendFullStatus
                  targets:
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Show message:
                value:
                  operation: showMessage
                  parameters:
                    message: Message from your administrator
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Turn on debug logging:
                value:
                  operation: turnOnFeature
                  parameters:
                    feature: debugLogging
                    turnOnTimeout: 1440
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Collect diagnostic file:
                value:
                  operation: collectDiagnosticFile
                  parameters:
                    consentMessage: Do you allow diagnostic data to be sent from this device?
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
                    - 21ccd888-01cc-459d-9341-2001508a83fc
              Restart WithSecure agent software:
                value:
                  operation: restartProduct
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
              Restart system:
                value:
                  operation: restartSystem
                  parameters:
                    message: The system will be restarted soon
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
            schema:
              type: object
              properties:
                operation:
                  type: string
                  description: Type of operation to execute.
                  enum:
                    - assignProfile
                    - collectDiagnosticFile
                    - installSoftwareUpdates
                    - isolateFromNetwork
                    - releaseFromNetworkIsolation
                    - scanForMalware
                    - scanForUpdates
                    - sendFullStatus
                    - showMessage
                    - turnOnFeature
                    - restartProduct
                    - restartSystem
                targets:
                  type: array
                  description: List of targets (device identifiers) on which the operation will be executed.
                  items:
                    type: string
                  maxItems: 5
                  minItems: 1
                parameters:
                  type: object
                  description: Additional arguments required by a specific type of operation.
                  properties:
                    bulletinIds:
                      type: array
                      description: Selected software updates to install. Bulletin IDs can be retrieved from the /v1/missing-updates endpoint. For installSoftwareUpdates operation.
                      items:
                        type: string
                      minItems: 1
                      maxItems: 200
                    consentMessage:
                      type: string
                      description: For collectDiagnosticFile operation.
                      maxLength: 512
                    feature:
                      type: string
                      description: For turnOnFeature operation.
                      enum:
                        - debugLogging
                    forceClose:
                      type: boolean
                      default: false
                      description: Whether to force close the applications that are upgraded. For installSoftwareUpdates operation.
                    message:
                      type: string
                      description: For isolateFromNetwork and showMessage operations.
                      maxLength: 512
                    profileId:
                      type: number
                      description: For assignProfile operation.
                    severity:
                      type: string
                      description: Severity of the software updates to install. For installSoftwareUpdates operation.
                      enum:
                        - critical
                        - everything
                        - important
                    turnOnTimeout:
                      type: number
                      description: For turnOnFeature operation.
                      minimum: 5
                      maximum: 1440
                  additionalProperties: true
              required:
                - operation
                - targets
      responses:
        '207':
          description: The request payload was valid and it was processed in the internal backend.
          content:
            application/json:
              examples:
                Some operations couldn't be triggered:
                  value:
                    multistatus:
                      - target: ec8a0100-d313-4896-b3cb-02188e060bf3
                        status: 404
                        details: Not found
                      - target: 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                        status: 400
                        details: 'Requested device has invalid type. Expected: computer, actual: mobile'
                      - target: 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                        status: 202
                        operationId: 14341413413490180
                      - target: 181fd624-1db0-49b8-b1b9-b88d6336bd75
                        status: 400
                        details: 'Requested device is in invalid state. State: inactive'
                    transactionId: 0000-abcdef-1234
                All operations triggered successfully:
                  value:
                    multistatus:
                      - target: ec8a0100-d313-4896-b3cb-02188e060bf3
                        status: 202
                        operationId: 7243413413490181
                      - target: 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                        status: 202
                        operationId: 7243413413490182
                      - target: 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                        status: 202
                        operationId: 14341413413490180
                    transactionId: 0000-abcdef-1234
              schema:
                type: object
                properties:
                  multistatus:
                    description: |
                      Contains information about the triggering operation.
                    type: array
                    items:
                      type: object
                      properties:
                        target:
                          type: string
                          description: 'Device identifier, corresponds to elements from the request `targets` array. Use this value to query for further information about the operation status.'
                        status:
                          type: integer
                          description: |
                            HTTP status of the triggering operation for the particular device. A response with status code 202 means that the device exists within the scope of the client's organization, and the operation was created in the internal backend service and will eventually be executed on the remote host.
                        details:
                          type: string
                          description: |
                            Details about the triggering operation. It might include information  about the reason for failure.
                        operationId:
                          type: string
                          description: |
                            ID of the operation if the trigger was successful. Use this identifier to correlate with the status from the [operations list](/api-reference/elements#get-/devices/v1/devices/operations).
                        metadataParameters:
                          type: object
                          description: Additional parameters returned by a specific type of operation.
                          properties:
                            fileId:
                              type: string
                              description: For the collectDiagnosticFile operation. Reference number of the diagnostic file (also referred to as fsdiag or wsdiag) that will be generated.
                          additionalProperties: true
                      required:
                        - status
                  transactionId:
                    type: string
                    description: Transaction ID for the request to the Elements API.
                required:
                  - transactionId
                  - multistatus
        '400':
          description: |
            The request failed because required properties are missing in the request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - invalid format of target id:
                  description: |
                    Error indicates that at least one of the elements of the targets property has the wrong format.
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      targets: All targets must match UUID format
                400004 - missing mandatory parameter for the operation:
                  description: |
                    At least one of the mandatory parameters for the operation is not present.
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      profileId: parameter is missing
                400004 - message parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded.
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Message too long. Max length is 512 characters.
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user has insufficient privileges to send the request. Check if the token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
    get:
      tags:
        - devices
      security:
        - oAuth2:
            - connect.api.read
      operationId: getDeviceOperations
      summary: List device operations
      description: |
        List of operations that were triggered on a particular device. If the device is not in an active state, an empty list is returned.     <p>
          Request example: </br>
          <code part="curl">
           curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/devices/v1/operations?deviceId={deviceId}
          </code>
        </p>
      parameters:
        - name: deviceId
          in: query
          required: true
          description: UUID of a device.
          schema:
            type: string
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
      responses:
        '200':
          description: |
            List of operations on the selected device.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: 'Operation ID. Use it to correlate with `operationId` from the [triggering operation](/api-reference/elements#post-/devices/v1/devices/operations) response.'
                        status:
                          description: Operation status from the remote host.
                          enum:
                            - pending
                            - finished
                            - ongoing
                            - failed
                            - internalError
                            - unknownError
                          type: string
                        operationName:
                          type: string
                          description: Operation name.
                        startedTimestamp:
                          type: string
                          format: date-time
                          description: |
                            Date and time when the operation was created in the internal backend.
                        lastUpdatedTimestamp:
                          type: string
                          format: date-time
                          description: Date and time of the last update of the operation's status.
                        expirationTimestamp:
                          type: string
                          format: date-time
                          description: |
                            Date and time of the operation's expiration. After this time, the pending operation is removed.
                        metadata:
                          type: object
                          description: 'Additional properties related to the specific type of operation. For possible values, see below.'
                          properties:
                            profileId:
                              type: string
                              description: ID of the assigned profile (for assignProfile operation).
                            feature:
                              type: string
                              description: Feature to turn on (for turnOnFeature).
                            fileId:
                              type: string
                              description: Reference number of the diagnostic file (also referred to as fsdiag or wsdiag) (for collectDiagnosticFile).
                          additionalProperties: true
              examples:
                List of operations triggered on the device:
                  value:
                    items:
                      - id: '7243413413490181'
                        status: pending
                        operationName: isolateFromNetwork
                        startedTimestamp: '2023-04-01T15:08:17Z'
                        lastUpdatedTimestamp: '2023-04-01T15:08:17Z'
                        expirationTimestamp: '2023-04-15T15:08:17Z'
                        metadata: {}
                      - id: '7243413413490193'
                        status: pending
                        operationName: assignProfile
                        startedTimestamp: '2023-04-01T15:08:17Z'
                        lastUpdatedTimestamp: '2023-04-01T15:08:17Z'
                        expirationTimestamp: '2023-04-15T15:08:17Z'
                        metadata:
                          profileId: '901566'
        '400':
          description: |
            The request failed because of missing required parameters  or incorrect parameter values.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            The device with the given ID is not found within the scope of the client's organization.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
  /response-actions/v1/responses:
    get:
      tags:
        - Response actions
      security:
        - oAuth2:
            - connect.api.read
      operationId: list-created-response-actions
      summary: Get status of response actions
      description: |
        <p> Get status of response actions for a given organization. After executing a response action, you can use this endpoint to get the status of the action. </p> <p>
          Request example: </br>
          <code part="curl">
           curl -X GET -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/response-actions/v1/responses?organizationId={organizationId}&order=asc
          </code>
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - name: organizationId
          in: query
          required: true
          description: |
            The UUID of an organization.
          schema:
            type: string
            format: uuid
            example: ec8a0100-d313-4896-b3cb-02188e060bf3
        - name: order
          in: query
          required: false
          description: Specifies the sorting order.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: anchor
          in: query
          required: false
          description: |
            Anchor pointing to the page that should be retrieved. If the parameter is missing or set to the default value, the endpoint returns the first page.
          schema:
            type: string
            default: no-value
        - name: type
          in: query
          required: false
          description: |
            Filter by the type of the response action.
          schema:
            type: string
            description: Type of response action
            enum:
              - blockUserAccess
              - deleteRegistry
              - deleteScheduledTasks
              - deleteServices
              - deleteWmiPersistence
              - endCurrentSession
              - enumerateProcesses
              - enumerateScheduledTasks
              - enumerateWmiPersistence
              - fullMemoryDump
              - mapFileSystem
              - mapRegistry
              - netstat
              - processMemoryDump
              - resetPassword
              - retrieveAmcache
              - retrieveAntivirusLogs
              - retrieveBrowserArtefacts
              - retrieveEventLogFiles
              - retrieveEventLogTracing
              - retrieveFiles
              - retrieveJumpList
              - retrieveLogEntries
              - retrieveMbr
              - retrieveMft
              - retrievePrefetch
              - retrieveRdpCache
              - retrieveRecentlyAccessed
              - retrieveRegistryHives
              - retrieveSrumdb
              - terminateProcess
              - terminateThread
        - name: actionId
          in: query
          required: false
          description: |
            Filter by the response action ID.
          schema:
            type: string
            format: uuid
        - name: state
          in: query
          required: false
          description: |
            Filter by the state of the response action.
          schema:
            type: string
            enum:
              - created
              - initializing
              - sending
              - running
              - canceling
              - finished
        - name: comment
          in: query
          required: false
          description: |
            Filter by comment. Matches any part of the comment text.
          schema:
            type: string
        - name: author
          in: query
          required: false
          description: |
            Filter by the author's username.
          schema:
            type: string
        - name: result
          in: query
          required: false
          description: |
            Filter by the result of the response action.
          schema:
            type: string
            enum:
              - succeeded
              - failed
              - timeout
              - cancelled
        - name: deviceId
          in: query
          required: false
          description: UUID of a device.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: |
            The size of a single batch. The value defines the upper bound for the number of items sent in a single response. However, it does not guarantee that the response will contain the exact number of items if the next page exists. Clients that read all items matching the query parameters should depend only on the <code>nextAnchor</code> property, which contains a link to the next result. Clients can stop iteration when the <code>nextAnchor</code> is missing in the response.
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: |
            List of created response actions for organization with paging and sorting
          content:
            application/json:
              schema:
                title: List created response actions
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      description: Response action
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: Response action ID.
                        type:
                          description: Response action type specifier.
                          allOf:
                            - type: string
                              description: Type of response action
                              enum:
                                - blockUserAccess
                                - deleteRegistry
                                - deleteScheduledTasks
                                - deleteServices
                                - deleteWmiPersistence
                                - endCurrentSession
                                - enumerateProcesses
                                - enumerateScheduledTasks
                                - enumerateWmiPersistence
                                - fullMemoryDump
                                - mapFileSystem
                                - mapRegistry
                                - netstat
                                - processMemoryDump
                                - resetPassword
                                - retrieveAmcache
                                - retrieveAntivirusLogs
                                - retrieveBrowserArtefacts
                                - retrieveEventLogFiles
                                - retrieveEventLogTracing
                                - retrieveFiles
                                - retrieveJumpList
                                - retrieveLogEntries
                                - retrieveMbr
                                - retrieveMft
                                - retrievePrefetch
                                - retrieveRdpCache
                                - retrieveRecentlyAccessed
                                - retrieveRegistryHives
                                - retrieveSrumdb
                                - terminateProcess
                                - terminateThread
                        state:
                          type: string
                          description: Response action state.
                          enum:
                            - created
                            - initializing
                            - sending
                            - running
                            - canceling
                            - finished
                        progress:
                          type: object
                          description: Response action progress.
                          properties:
                            devicesCount:
                              type: integer
                              description: Indicates how many devices are affected by the action
                            pendingTasksCount:
                              type: integer
                              description: Pending tasks count.
                            errorTasksCount:
                              type: integer
                              description: Number of tasks that failed to be processed at any point along the way.
                            activeTasksCount:
                              type: integer
                              description: Number of tasks that have not yet received any response from the sensor.
                            completedTasksCount:
                              type: integer
                              description: Number of tasks in the finished state.
                            successfullyCompletedTasksCount:
                              type: integer
                              description: Number of tasks in the finished state with the succeeded result.
                        createdTimestamp:
                          type: string
                          format: date-time
                          description: The ISO-formatted creation date and time.
                        updatedTimestamp:
                          type: string
                          format: date-time
                          description: The ISO-formatted date and time of the last update.
                        devices:
                          type: array
                          items:
                            type: object
                            properties:
                              deviceId:
                                type: string
                                format: uuid
                                description: ID of a device affected by the remote action
                          description: List of devices affected by the remote action.
                        author:
                          type: object
                          description: Response action author information
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: user ID of the author
                            source:
                              type: string
                              description: The system from where the user come
                              enum:
                                - oneId
                                - clientCredentials
                                - sso
                            username:
                              type: string
                              description: Author's username
                        comment:
                          type: string
                          description: Comment
                        result:
                          type: string
                          description: Response action result.
                          enum:
                            - succeeded
                            - failed
                            - timeout
                            - cancelled
                      required:
                        - id
                    description: List of created response actions.
                  nextAnchor:
                    type: string
                    description: Anchor to be used to retrieve the next page. Not to be returned on the last page.
                required:
                  - items
        '400':
          description: |
            Request failed because of missing required parameters or incorrect parameters value.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400006 - invalid organization type:
                  value:
                    message: Invalid organization type.
                    code: 400006
                    transactionId: 0000-someTransactionId
                    details:
                      organizationId: someUuid
                      expected: company
                      actual: sop
        '401':
          description: |
            User is not authorized to send request. Check if request contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company not found:
                  description: |
                    Company specified with <code>organizationId</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
  /response-actions/v1/response-actions:
    post:
      deprecated: true
      tags:
        - Response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: create-response-action
      summary: Execute response action (deprecated)
      description: |
        <p><strong>⚠️ DEPRECATED:</strong> This endpoint is deprecated. Please use the individual action-specific endpoints instead: <code>POST /response-actions/v1/execute/{action_name}</code></p> <p> This legacy endpoint supports only a limited subset of response actions for backward compatibility.  For full functionality and better documentation, use the individual execute endpoints. </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p> <h3>Supported Device Response Actions</h3> <p>This endpoint supports the following device action types:</p> <table> <tr><th>Type</th><th>Description</th><th>Parameters</th><th>Supported Devices</th></tr> <tr>
          <td>enumerateProcesses</td>
          <td>Enumerates running processes</td>
          <td>
          </td>
          <td>macOS, Linux, Windows</td>
        </tr> <tr>
          <td>fullMemoryDump</td>
          <td>Uploads a full memory dump. Warning: this job uploads large files and will thus block
                subsequent jobs. Consider running this job last
          </td>
          <td>
            Required:
            <ul>
              <li>winpmemVersion<sup>1</sup></li>
              <li>collectProfile<sup>2</sup></li>
              <li>captureMemory<sup>2</sup></li>
            </ul>
            1 - only Windows<br>2 - only Linux
          </td>
          <td>Linux, Windows</td>
        </tr> <tr>
          <td>killProcess</td>
          <td>Kills processes matching patterns</td>
          <td>
            Required:
            <ul>
              <li>match</li>
              <li>processMatchValues</li>
              <li>processMemoryDump<sup>1</sup></li>
              <li>memoryDumpFlag<sup>1</sup></li>
            </ul>
            1 - only Windows
          </td>
          <td>macOS, Linux, Windows</td>
        </tr> <tr>
          <td>killThread</td>
          <td>Kills a thread</td>
          <td>
            Required:
            <ul>
              <li>threadId</li>
            </ul>
          </td>
          <td>macOS, Linux, Windows</td>
        </tr> <tr>
          <td>netstat</td>
          <td>Retrieves network connections, routing tables, interface statistics, masquerade connections,
              multicast memberships, and associated process information for each entry from the selected endpoints
          </td>
          <td>
            Required:
            <ul>
              <li>maxFileHash</li>
            </ul>
          </td>
          <td>macOS, Linux, Windows</td>
        </tr> </table> <p>
          Request example: </br>
          <code part="curl">
            curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/response-actions/v1/response-actions -d '{"organizationId": "{organizationId}", "type": "netstat", "comment": "test", "targets": ["{deviceId}"], "parameters": {"maxFileHash": 10}}'
          </code>
        </p> <h3>Supported Identity Response Actions</h3> <p>This endpoint supports the following identity response actions for Microsoft Entra ID:</p> <table> <tr><th>Type</th><th>Description</th><th>Parameters</th></tr>
         <tr>
          <td>endCurrentSession</td>
          <td>Ends the Microsoft Entra session of a user</td>
          <td>
            Required:
            <ul>
              <li>userPrincipal</li>
            </ul>
          </td>
        </tr> <tr>
          <td>resetPassword</td>
          <td>Resets the Microsoft Entra password of a user</td>
          <td>
            Required:
            <ul>
              <li>userPrincipal</li>
            </ul>
          </td>
        </tr> <tr>
          <td>blockUserAccess</td>
          <td>Blocks access for a user to all resources inside the Microsoft Entra ecosystem</td>
          <td>
            Required:
            <ul>
              <li>userPrincipal</li>
            </ul>
          </td>
        </tr> </table> <p>
          Request example: </br>
          <code part="curl">
            curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" https://api.connect.withsecure.com/response-actions/v1/response-actions -d '{"organizationId": "{organizationId}", "type": "blockUserAccess", "comment": "test", "targets": ["{tenantId}"], "parameters": {"userPrincipal": "example@example.com"}}'
          </code>
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      userPrincipal: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Dump memory on Windows with winpmem 1.6:
                value:
                  type: fullMemoryDump
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    winpmemVersion: v1_6
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Full memory dump on Windows
              Dump memory on Linux:
                value:
                  type: fullMemoryDump
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    captureMemory: true
                    collectProfile: false
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Full memory dump on Linux
              Enumerate processes:
                value:
                  type: enumerateProcesses
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Enumerate processes
              Netstat with maximal 10 MB file hash:
                value:
                  type: netstat
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    maxFileHash: 10
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve network details
              Kill the thread:
                value:
                  type: killThread
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    threadId: 94343
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Killing thread 94343
              Kill the process with memory dump:
                value:
                  type: killProcess
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: processId
                    processMatchValues:
                      - '48573'
                      - '1343'
                    processMemoryDump: true
                    memoryDumpFlag: full
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Select process by id and kill it
              Kill the processes matching regular expression:
                value:
                  type: killProcess
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: processNameRegex
                    processMatchValues:
                      - '[A-Z]+'
                    processMemoryDump: false
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Select process with regular expression and kill it
              End current session:
                value:
                  type: endCurrentSession
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    userPrincipal: example@example.com
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: End session of a user
              Reset password:
                value:
                  type: resetPassword
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    userPrincipal: example@example.com
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Reset password of a user
              Block user access:
                value:
                  type: blockUserAccess
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    userPrincipal: example@example.com
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Block access of a user
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                type:
                  description: Type of action
                  type: string
                  enum:
                    - blockUserAccess
                    - endCurrentSession
                    - enumerateProcesses
                    - fullMemoryDump
                    - killProcess
                    - killThread
                    - netstat
                    - resetPassword
                targets:
                  type: array
                  description: List of targets (device identifiers or Microsoft Entra tenant identifiers) on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: |
                    Additional arguments required by particular type of action. See the tables above and open the <code>Examples</code> tab for parameter usage
                  properties:
                    captureMemory:
                      type: boolean
                      description: |
                        Take capture of system's memory. Required in <code>fullMemoryDump</code> when Linux devices are selected as targets
                    collectProfile:
                      type: boolean
                      description: |
                        Collect files required to build a kernel profile. Required in <code>fullMemoryDump</code> when Linux devices are selected as targets
                    match:
                      type: string
                      description: Strategy used to match processes (required in <code>killProcess</code>)
                      enum:
                        - processId
                        - processName
                        - processNameRegex
                        - processPath
                        - processPathRegex
                    maxFileHash:
                      type: number
                      description: |
                        Maximum file size to hash, in MB. Prevents excessive delays when hashing large files (required in <code>netstat</code>)
                    memoryDumpFlag:
                      type: string
                      description: |
                        Flag that will be used when dumping the process memory. Required in <code>killProcess</code> when processMemoryDump is true (Windows only). <ul> <li>full - memory dump includes all accessible memory of process</li> <li>pmem - only information necessary to capture process' stack traces</li> </ul>
                      enum:
                        - full
                        - pmem
                    processMatchValues:
                      type: array
                      description: |
                        List of values that are used to match process to kill (required in <code>killProcess</code>).  Depending on selected strategy it might be list of identifiers, names or regular expressions
                      items:
                        type: string
                      minItems: 1
                      maxItems: 6
                    processMemoryDump:
                      type: boolean
                      default: false
                      description: |
                        Run memory dump on process before killing it. Required in <code>killProcess</code>. Memory dump can be run only if <code>processName</code> or <code>processId</code> strategy is used (Windows only)
                    threadId:
                      type: number
                      description: Thread Id (required in <code>killThread</code>)
                    userPrincipal:
                      type: string
                      description: |
                        User principal (email) of the user. Required with the identity response actions <code>endCurrentSession</code>, <code>resetPassword</code> and <code>blockUserAccess</code>
                    winpmemVersion:
                      type: string
                      description: |
                        Version of <code>winpmem</code> to use. Required in <code>fullMemoryDump</code> when Windows devices are selected as targets
                      enum:
                        - v1_6
                        - v2_1
              required:
                - type
                - targets
                - organizationId
  /response-actions/v1/responses/tasks:
    get:
      tags:
        - Response actions
      security:
        - oAuth2:
            - connect.api.read
      operationId: get-response-action-tasks
      summary: Get response action tasks
      description: |
        <p>
        Retrieves a paginated list of tasks for a specific response action.
        </p>
        <p>
        Tasks represent the execution of a response action on individual devices.
        Each task tracks the state, result, and any attachments (output files) generated
        during execution.
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - name: organizationId
          in: query
          required: true
          description: |
            The UUID of an organization.
          schema:
            type: string
            format: uuid
            example: ec8a0100-d313-4896-b3cb-02188e060bf3
        - name: actionId
          in: query
          required: true
          description: |
            The UUID of the response action.
          schema:
            type: string
            format: uuid
          example: e3f22f33-4031-4540-a7db-a899c29f649a
        - name: anchor
          in: query
          required: false
          description: |
            Anchor pointing to the page that should be retrieved. If the parameter is missing or set to the default value, the endpoint returns the first page.
          schema:
            type: string
            default: no-value
        - name: order
          in: query
          required: false
          description: |
            Sort order for results.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: state
          in: query
          required: false
          description: |
            Filter tasks by their execution state.
          schema:
            type: string
            enum:
              - pending
              - sent
              - cancellationSent
              - cancellationAcknowledged
              - received
              - acknowledged
              - running
              - stopped
              - finished
              - canceling
        - name: result
          in: query
          required: false
          description: |
            Filter tasks by their execution result.
          schema:
            type: string
            enum:
              - succeeded
              - failed
              - timeout
              - canceled
        - name: deviceId
          in: query
          required: false
          description: UUID of a device.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: |
            Maximum number of items to return per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Successfully retrieved action tasks.
          content:
            application/json:
              schema:
                title: List response action tasks
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      description: |
                        Represents the execution of a response action on a specific device.
                        Tracks the state, result, and any output attachments.
                      properties:
                        device:
                          description: Information about the device.
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: Unique identifier of the device.
                              example: 185c4867-2e95-4167-8a78-f11c5967c986
                            name:
                              type: string
                              description: Human-readable name of the device.
                              example: DESKTOP-3D64DAK
                          required:
                            - id
                            - name
                        state:
                          type: string
                          description: Task execution state.
                          allOf:
                            - type: string
                              description: Current execution state of a response action task.
                              enum:
                                - pending
                                - sent
                                - cancellationSent
                                - cancellationAcknowledged
                                - received
                                - acknowledged
                                - running
                                - stopped
                                - finished
                                - canceling
                              example: finished
                          example: finished
                        result:
                          type: string
                          nullable: true
                          description: Task execution result.
                          allOf:
                            - type: string
                              description: |
                                Final result of a task execution. Only present when state is 'finished' or 'stopped'.
                              enum:
                                - succeeded
                                - failed
                                - timeout
                                - canceled
                              example: succeeded
                          example: succeeded
                        createdTimestamp:
                          type: string
                          format: date-time
                          description: The ISO-formatted creation date and time.
                          example: '2023-11-10T11:54:40.123Z'
                        updatedTimestamp:
                          type: string
                          format: date-time
                          description: The ISO-formatted date and time of the last update.
                          example: '2023-11-10T11:55:15.456Z'
                        disruptor:
                          type: boolean
                          description: Whether the task is marked as potentially disruptive to system operations.
                          example: false
                        error:
                          nullable: true
                          allOf:
                            - type: object
                              description: Error details when a task fails.
                              properties:
                                message:
                                  type: string
                                  description: Human-readable error message.
                                  example: Connection timeout
                              required:
                                - message
                          description: Error information if the task failed.
                        attachments:
                          type: array
                          nullable: true
                          description: |
                            List of output files/attachments generated by the task.
                            Common for actions like enumerateProcesses, netstat, fullMemoryDump.
                          items:
                            type: object
                            description: |
                              Output file/attachment generated by a response action task.
                              Contains a pre-signed URL for downloading the file.
                            properties:
                              url:
                                type: string
                                format: uri
                                description: Pre-signed S3 URL for downloading the attachment (expires after a period).
                                example: 'https://s3.amazonaws.com/bucket/path/to/attachment.zip'
                              size:
                                type: integer
                                format: int64
                                description: Size of the attachment in bytes.
                                example: 1048576
                              name:
                                type: string
                                description: Original filename of the attachment.
                                example: netstat_output.txt
                              state:
                                type: string
                                description: |
                                  State of the attachment processing.
                                  - pending: Being generated
                                  - ready: Available for download
                                  - expired: Download URL has expired
                                enum:
                                  - pending
                                  - ready
                                  - expired
                                example: ready
                              type:
                                type: string
                                description: MIME type of the attachment.
                                example: application/zip
                              reportedType:
                                type: string
                                description: Type of data contained in the attachment (action-specific).
                                example: netstat_result
                              receivedTimestamp:
                                type: string
                                format: date-time
                                description: The ISO-formatted date and time when the attachment was received.
                                example: '2023-11-10T11:55:15.456Z'
                            required:
                              - url
                              - size
                              - name
                              - state
                      required:
                        - device
                        - state
                        - createdTimestamp
                        - updatedTimestamp
                        - disruptor
                    description: Array of response action tasks.
                  nextAnchor:
                    type: string
                    description: Anchor to be used to retrieve the next page. Not to be returned on the last page.
                required:
                  - items
              examples:
                successfulTasks:
                  summary: Tasks with different states
                  value:
                    items:
                      - device:
                          id: 185c4867-2e95-4167-8a78-f11c5967c986
                          name: DESKTOP-3D64DAK
                        state: finished
                        result: succeeded
                        createdTimestamp: '2023-11-10T11:54:40.123Z'
                        updatedTimestamp: '2023-11-10T11:55:15.456Z'
                        disruptor: false
                        attachments:
                          - url: 'https://s3.amazonaws.com/bucket/path/to/attachment.zip'
                            size: 1048576
                            name: netstat_output.txt
                            state: ready
                            reportedType: netstat_result
                            type: application/zip
                            receivedTimestamp: '2023-11-10T11:55:15.456Z'
                      - device:
                          id: cc73c5d8-226c-4d0e-a4b4-c1a16c0b9b49
                          name: LAPTOP-ABC123
                        state: finished
                        result: failed
                        createdTimestamp: '2023-11-10T11:54:40.123Z'
                        updatedTimestamp: '2023-11-10T11:55:00.789Z'
                        disruptor: false
                        error:
                          message: Connection timeout
                    nextAnchor: eyJpZCI6ImU...
                emptyList:
                  summary: No tasks found
                  value:
                    items: []
        '400':
          description: |
            Request failed because of missing required parameters or incorrect parameters value.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
        '401':
          description: |
            User is not authorized to send request. Check if request contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Response action from request is not found in scope of organization.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - action not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
  /response-actions/v1/execute/blockUserAccess:
    post:
      tags:
        - Identity response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-blockUserAccess
      summary: Block user access in Microsoft Entra
      description: |
        <p> Blocks access for a user to all resources inside the Microsoft Entra ecosystem. </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      userPrincipal: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or tenant from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or tenant not found:
                  description: |
                    Company specified with <code>organizationId</code> or tenant specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Block user access:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    userPrincipal: example@example.com
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Block access of a user
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target tenants belong
                targets:
                  type: array
                  description: List of Microsoft Entra tenant identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the blockUserAccess action
                  required:
                    - userPrincipal
                  properties:
                    userPrincipal:
                      type: string
                      description: User principal (email) of the user
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/deleteRegistry:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-deleteRegistry
      summary: Delete registry key or value
      description: |
        <p> Deletes a specified Windows registry key or value to remove malicious entries or persistence mechanisms. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      registryPath: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Delete registry key recursively:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    registryPath: HKLM\Software\MaliciousKey
                    recursive: true
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Delete malicious registry key
              Delete specific registry value:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    registryPath: HKLM\Software\Microsoft\Windows\CurrentVersion\Run
                    registryValue: MaliciousStartup
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Remove malicious autorun entry
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the deleteRegistry action
                  required:
                    - registryPath
                  properties:
                    registryPath:
                      type: string
                      description: Path to registry key; case-insensitive
                    registryValue:
                      type: string
                      description: Registry value name; case-insensitive (optional)
                    recursive:
                      type: boolean
                      description: Delete sub-keys along with this key (optional)
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/deleteScheduledTasks:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-deleteScheduledTasks
      summary: Delete scheduled task
      description: |
        <p> Deletes a specified Windows scheduled task to remove persistence mechanisms. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      taskName: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Delete scheduled task:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    taskName: SuspiciousTask
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Delete suspicious scheduled task
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the deleteScheduledTasks action
                  required:
                    - taskName
                  properties:
                    taskName:
                      type: string
                      description: Task name; case-insensitive
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/deleteServices:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-deleteServices
      summary: Delete Windows service
      description: |
        <p> Deletes a specified Windows service to remove malicious or unwanted services. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      match: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Delete service by name:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: serviceName
                    serviceName: MaliciousService
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Delete malicious service
              Delete service by display name:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: displayName
                    displayName: Malicious Service Display Name
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Delete malicious service by display name
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the deleteServices action
                  required:
                    - match
                  properties:
                    match:
                      type: string
                      description: Strategy to match services
                      enum:
                        - serviceName
                        - displayName
                    serviceName:
                      type: string
                      description: Service name; case-insensitive (required when match is serviceName)
                    displayName:
                      type: string
                      description: Service display name; case-insensitive (required when match is displayName)
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/deleteWmiPersistence:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-deleteWmiPersistence
      summary: Delete WMI persistence objects
      description: |
        <p> Deletes Windows Management Instrumentation (WMI) persistence objects. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Delete WMI persistence with backup:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    namespace: root\subscription
                    eventConsumerName: MaliciousConsumer
                    doBackup: true
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Delete WMI persistence
              Delete WMI filter:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    eventFilterName: MaliciousFilter
                    delay: 15
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Remove malicious WMI filter
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the deleteWmiPersistence action (all optional)
                  properties:
                    namespace:
                      type: string
                      description: WMI namespace (default is root\subscription)
                    doBackup:
                      type: boolean
                      description: Create and upload a copy of WMI repository before changes
                    eventConsumerName:
                      type: string
                      description: Event consumer instance name
                    eventFilterName:
                      type: string
                      description: Event filter instance name
                    eventBindingPath:
                      type: string
                      description: Filter to consumer binding instance path
                    delay:
                      type: integer
                      description: Seconds to wait after removal before validation (default is 10)
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/endCurrentSession:
    post:
      tags:
        - Identity response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-endCurrentSession
      summary: End Microsoft Entra session
      description: |
        <p> Ends the Microsoft Entra session of a user. </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      userPrincipal: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or tenant from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or tenant not found:
                  description: |
                    Company specified with <code>organizationId</code> or tenant specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              End current session:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    userPrincipal: example@example.com
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: End session of a user
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target tenants belong
                targets:
                  type: array
                  description: List of Microsoft Entra tenant identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the endCurrentSession action
                  required:
                    - userPrincipal
                  properties:
                    userPrincipal:
                      type: string
                      description: User principal (email) of the user
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/enumerateProcesses:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-enumerateProcesses
      summary: Enumerate running processes
      description: |
        <p>
          Enumerates running processes on the target device.
        </p> <p> Supported operating systems: <strong>macOS, Linux, Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Enumerate processes:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                  comment: Enumerate processes
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/enumerateScheduledTasks:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-enumerateScheduledTasks
      summary: List scheduled tasks
      description: |
        <p> Lists all Windows scheduled tasks on the device. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Enumerate scheduled tasks:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: List all scheduled tasks
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/enumerateWmiPersistence:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-enumerateWmiPersistence
      summary: Enumerate WMI persistence mechanisms
      description: |
        <p> Enumerates WMI (Windows Management Instrumentation) persistence mechanisms including event consumers, filters, and bindings that may be used by malware. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Enumerate WMI persistence:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    namespace: root\subscription
                    limit: 100
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Enumerate WMI persistence
              Enumerate with custom queries:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    queryArray:
                      - SELECT * FROM __EventConsumer
                      - SELECT * FROM __EventFilter
                    prettyJson: true
                    showQualifiers: true
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Enumerate WMI with custom queries
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the enumerateWmiPersistence action (all optional)
                  properties:
                    namespace:
                      type: string
                      description: WMI namespace (default is root\subscription)
                    queryArray:
                      type: array
                      description: WQL queries for enumerating instances
                      items:
                        type: string
                    limit:
                      type: integer
                      description: Maximum number of instances returned (default is 100)
                    prettyJson:
                      type: boolean
                      description: Indent results for readability
                    showQualifiers:
                      type: boolean
                      description: Include WMI qualifiers
                    showExtendedInfo:
                      type: boolean
                      description: Include extended type information
                    includeSystemProperties:
                      type: boolean
                      description: Include system properties
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/fullMemoryDump:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-fullMemoryDump
      summary: Create full memory dump
      description: |
        <p> Uploads a full memory dump. Warning: this job uploads large files and will thus block subsequent jobs. Consider running this job last. </p> <p> Supported operating systems: <strong>Linux, Windows</strong> </p> <p> <strong>Note:</strong> Parameters differ by operating system: <ul>
          <li><strong>Windows:</strong> Requires <code>winpmemVersion</code> parameter to specify the winpmem tool version</li>
          <li><strong>Linux:</strong> Requires <code>captureMemory</code> and <code>collectProfile</code> parameters to control what data to collect</li>
        </ul> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      winpmemVersion: parameter is missing for Windows devices
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Windows - Full memory dump with winpmem 1.6:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    winpmemVersion: v1_6
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: 'Windows: Full memory dump using winpmem version 1.6'
              Windows - Full memory dump with winpmem 2.1:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    winpmemVersion: v2_1
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: 'Windows: Full memory dump using winpmem version 2.1'
              Linux - Full memory dump with kernel profile:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    captureMemory: true
                    collectProfile: true
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: 'Linux: Capture memory and collect kernel profile'
              Linux - Memory dump only (no profile):
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    captureMemory: true
                    collectProfile: false
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: 'Linux: Capture memory without kernel profile'
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  description: Parameters for the fullMemoryDump action. Requirements differ by target OS.
                  oneOf:
                    - type: object
                      title: Windows Parameters
                      description: Parameters for Windows devices
                      required:
                        - winpmemVersion
                      properties:
                        winpmemVersion:
                          type: string
                          description: |
                            Version of winpmem tool to use for memory capture. Winpmem is a physical memory acquisition tool.
                          enum:
                            - v1_6
                            - v2_1
                    - type: object
                      title: Linux Parameters
                      description: Parameters for Linux devices
                      required:
                        - captureMemory
                        - collectProfile
                      properties:
                        captureMemory:
                          type: boolean
                          description: |
                            Take a capture of the system's physical memory. When false, only kernel profile files are collected without the memory dump itself.
                          default: true
                        collectProfile:
                          type: boolean
                          description: |
                            Collect files required to build a kernel profile for memory analysis. When true, collects kernel debug symbols and system map files needed for memory forensics tools.
                          default: true
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/terminateProcess:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-terminateProcess
      summary: Terminate process
      description: |
        <p> Terminates processes matching patterns. </p> <p> Supported operating systems: <strong>macOS, Linux, Windows</strong> </p> <p> <strong>Note:</strong> Memory dump functionality is only available on Windows.  Process matching behavior differs by OS: <ul>
          <li><strong>Windows:</strong> Process names/paths are case-insensitive and exclude file extension</li>
          <li><strong>macOS/Linux:</strong> Process names/paths are case-sensitive and include file extension</li>
        </ul> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      match: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Windows - Terminate by process ID with memory dump:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    os: windows
                    match: processIds
                    processIds:
                      - 48573
                      - 1343
                    processMemoryDump: true
                    memoryDumpFlag: full
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: 'Windows: Terminate processes by ID with full memory dump'
              Windows - Terminate by process name:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    os: windows
                    match: processNames
                    processNames:
                      - notepad
                      - calc
                    processMemoryDump: false
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: 'Windows: Terminate by name (case-insensitive, no .exe extension)'
              Linux - Terminate by process name:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    os: linux
                    match: processNames
                    processNames:
                      - firefox
                      - chrome
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: 'Linux: Terminate by name (case-sensitive, with extension)'
              Windows - Terminate by name regex:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    os: windows
                    match: processNameRegexes
                    processNameRegexes:
                      - ^malware.*
                      - .*suspicious.*
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: 'Windows: Terminate processes matching regex patterns'
              Linux - Terminate by process path:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    os: linux
                    match: processPaths
                    processPaths:
                      - /usr/bin/firefox
                      - /opt/app/malicious
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: 'Linux: Terminate by full executable path'
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the terminateProcess action
                  required:
                    - os
                    - match
                  properties:
                    os:
                      description: Operating system of the target device
                      type: string
                      enum:
                        - windows
                        - mac
                        - linux
                        - mac_or_linux
                    match:
                      type: string
                      description: |
                        Strategy used to match processes. The value corresponds to the field name to use.
                        <ul>
                          <li><strong>processIds</strong>: Match by process IDs</li>
                          <li><strong>processNames</strong>: Match by process names</li>
                          <li><strong>processNameRegexes</strong>: Match by process name regex patterns</li>
                          <li><strong>processPaths</strong>: Match by process paths</li>
                          <li><strong>processPathRegexes</strong>: Match by process path regex patterns</li>
                        </ul>
                      enum:
                        - processIds
                        - processNames
                        - processNameRegexes
                        - processPaths
                        - processPathRegexes
                    processIds:
                      type: array
                      description: |
                        List of process IDs (PIDs) to terminate. 
                        <strong>Required when match=processIds.</strong>
                      items:
                        type: integer
                      minItems: 1
                      maxItems: 6
                    processNames:
                      type: array
                      description: |
                        List of process names to terminate. 
                        <strong>Required when match=processNames.</strong>
                        <br><strong>Windows:</strong> case-insensitive, exclude .exe extension (e.g., "notepad", "chrome").
                        <br><strong>Linux/macOS:</strong> case-sensitive, include extension (e.g., "firefox", "bash").
                      items:
                        type: string
                      minItems: 1
                      maxItems: 6
                    processNameRegexes:
                      type: array
                      description: |
                        List of regular expressions to match process names. 
                        <strong>Required when match=processNameRegexes.</strong>
                        <br><strong>Windows:</strong> case-insensitive matching.
                        <br><strong>Linux/macOS:</strong> case-sensitive matching.
                      items:
                        type: string
                      minItems: 1
                      maxItems: 6
                    processPaths:
                      type: array
                      description: |
                        List of full process paths to terminate. 
                        <strong>Required when match=processPaths.</strong>
                        <br><strong>Windows:</strong> case-insensitive (e.g., "C:\Windows\System32\notepad.exe").
                        <br><strong>Linux/macOS:</strong> case-sensitive (e.g., "/usr/bin/firefox").
                      items:
                        type: string
                      minItems: 1
                      maxItems: 6
                    processPathRegexes:
                      type: array
                      description: |
                        List of regular expressions to match process paths. 
                        <strong>Required when match=processPathRegexes.</strong>
                        <br><strong>Windows:</strong> case-insensitive matching.
                        <br><strong>Linux/macOS:</strong> case-sensitive matching.
                      items:
                        type: string
                      minItems: 1
                      maxItems: 6
                    processMemoryDump:
                      type: boolean
                      description: |
                        Run memory dump on process before terminating it. 
                        <strong>Windows only.</strong> Must be false or omitted for Linux/macOS.
                        Compatible only with processIds or processNames match strategies.
                      default: false
                    memoryDumpFlag:
                      type: string
                      description: |
                        Flag for process memory dump. <strong>Windows only.</strong>
                        <ul>
                          <li><strong>full</strong>: Includes all accessible memory in the process (may result in very large files)</li>
                          <li><strong>pmem</strong>: Only includes information necessary to capture stack traces for all existing threads</li>
                        </ul>
                      enum:
                        - full
                        - pmem
                      default: pmem
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/terminateThread:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-terminateThread
      summary: Terminate thread
      description: |
        <p> Terminates a thread. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      threadId: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Terminate the thread:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    threadId: 94343
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Terminating thread 94343
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the terminateThread action
                  required:
                    - threadId
                  properties:
                    threadId:
                      type: integer
                      description: Thread Id
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/mapFileSystem:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-mapFileSystem
      summary: List file system structure
      description: |
        <p> Lists the file system structure based on path matching patterns. </p> <p> Supported operating systems: <strong>macOS, Linux, Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      match: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Map file system:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: pathBasic
                    pathBasic: 'C:\Users'
                    depth: 2
                    maxFileSizeToHashMB: 10
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Map user directories
              Map with regex:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: pathRegex
                    pathRegex: 'C:\\Program Files\\.*\\.exe'
                    depth: 5
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Find executable files
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the mapFileSystem action
                  required:
                    - match
                  properties:
                    match:
                      type: string
                      description: Format for file path matching
                      enum:
                        - pathBasic
                        - pathRegex
                    pathBasic:
                      type: string
                      description: Path to file or directory; case-insensitive (required when match is pathBasic)
                    pathRegex:
                      type: string
                      description: Regex matching files or directories; case-insensitive (required when match is pathRegex)
                    depth:
                      type: integer
                      description: 'Maximum search depth in subdirectories (optional, default is 3)'
                    maxFileSizeToHashMB:
                      type: number
                      description: 'Maximum file size to hash, in MB. Prevents excessive delays when hashing large files (optional)'
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/mapRegistry:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-mapRegistry
      summary: List registry keys and values
      description: |
        <p> Lists the Windows registry keys and values based on path matching patterns. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      match: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Map registry autorun keys:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: pathBasic
                    pathBasic: HKLM\Software\Microsoft\Windows\CurrentVersion\Run
                    depth: 3
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Map registry autorun keys
              Map with regex and value filter:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: pathRegex
                    pathRegex: HKLM\\Software\\.*
                    values: .*malicious.*
                    depth: 2
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Find suspicious registry entries
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the mapRegistry action
                  required:
                    - match
                  properties:
                    match:
                      type: string
                      description: Format for registry path matching
                      enum:
                        - pathBasic
                        - pathRegex
                    pathBasic:
                      type: string
                      description: Path to registry key; case-insensitive (required when match is pathBasic)
                    pathRegex:
                      type: string
                      description: Regex matching registry keys; case-insensitive (required when match is pathRegex)
                    depth:
                      type: integer
                      description: 'Maximum search depth in subkeys (optional, default is 3)'
                    values:
                      type: string
                      description: 'Regex matching registry values; case-insensitive (optional, default is .*)'
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/netstat:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-netstat
      summary: Retrieve network connections
      description: |
        <p> Retrieves network connections, routing tables, interface statistics, masquerade connections, multicast memberships, and associated process information for each entry from the selected endpoints. </p> <p> Supported operating systems: <strong>macOS, Linux, Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      maxFileSizeToHashMB: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Netstat with maximal 10 MB file hash:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    maxFileSizeToHashMB: 10
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve network details
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the netstat action
                  required:
                    - maxFileSizeToHashMB
                  properties:
                    maxFileSizeToHashMB:
                      type: number
                      description: 'Maximum file size to hash, in MB. Prevents excessive delays when hashing large files'
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/processMemoryDump:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-processMemoryDump
      summary: Retrieve process memory dump
      description: |
        <p> Retrieves a memory dump of a specific process. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      match: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Process memory dump by ID:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: processId
                    processId: 1234
                    flags: full
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Dump memory of process 1234
              Process memory dump by name:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: processName
                    processName: chrome
                    flags: pmem
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Dump memory of Chrome process
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the processMemoryDump action
                  required:
                    - match
                    - flags
                  properties:
                    match:
                      type: string
                      description: Strategy to match the process
                      enum:
                        - processId
                        - processName
                    processId:
                      type: integer
                      description: Process identifier (PID) (required when match is processId)
                    processName:
                      type: string
                      description: 'Process name, excluding file extension; case-insensitive (required when match is processName)'
                    flags:
                      type: string
                      description: |
                        Memory dump flags. <ul>
                          <li>full: Includes all accessible memory</li>
                          <li>pmem: Includes only stack trace information</li>
                        </ul>
                      enum:
                        - full
                        - pmem
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/resetPassword:
    post:
      tags:
        - Identity response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-resetPassword
      summary: Reset Microsoft Entra password
      description: |
        <p> Resets the Microsoft Entra password of a user. </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      userPrincipal: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or tenant from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or tenant not found:
                  description: |
                    Company specified with <code>organizationId</code> or tenant specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Reset password:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    userPrincipal: example@example.com
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Reset password of a user
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target tenants belong
                targets:
                  type: array
                  description: List of Microsoft Entra tenant identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the resetPassword action
                  required:
                    - userPrincipal
                  properties:
                    userPrincipal:
                      type: string
                      description: User principal (email) of the user
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/retrieveAmcache:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveAmcache
      summary: Retrieve amcache files
      description: |
        <p> Retrieves the Application Compatibility Cache file from the device. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve Amcache:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve Amcache files
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveAntivirusLogs:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveAntivirusLogs
      summary: Retrieve antivirus logs
      description: |
        <p> Retrieves anti-virus software log files for security analysis. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve antivirus logs:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve antivirus log files
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveBrowserArtefacts:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveBrowserArtefacts
      summary: Retrieve browser artifacts
      description: |
        <p> Retrieves the browser history from the device. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve browser artefacts:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    chrome: true
                    edge: true
                    firefox: true
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve browser artifacts
              Retrieve for specific user:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    user: jdoe
                    chrome: true
                    iexplorer: true
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve browser artifacts for user jdoe
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the retrieveBrowserArtefacts action (all optional)
                  properties:
                    user:
                      type: string
                      description: Windows username to filter artifacts. All accounts selected when empty
                    chrome:
                      type: boolean
                      description: Collect artifacts from Chrome browser
                    edge:
                      type: boolean
                      description: Collect artifacts from Microsoft Edge browser
                    iexplorer:
                      type: boolean
                      description: Collect artifacts from Internet Explorer browser
                    firefox:
                      type: boolean
                      description: Collect artifacts from Mozilla Firefox browser
                    opera:
                      type: boolean
                      description: Collect artifacts from Opera browser
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveEventLogFiles:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveEventLogFiles
      summary: Retrieve Windows event log files
      description: |
        <p> Retrieves Windows Event Log files. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve event log files:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve Windows event log files
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveEventLogTracing:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveEventLogTracing
      summary: Retrieve event log tracing files
      description: |
        <p> Retrieves the .etl event log tracing files that contain records of system activities. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve event log tracing:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    guid: .*
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve event log tracing entries
              Retrieve specific GUID:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    guid: '{12345678-1234-1234-1234-123456789012}'
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve specific event log tracing provider
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the retrieveEventLogTracing action (all optional)
                  properties:
                    guid:
                      type: string
                      description: GUID for event log tracing providers. Regex supported (default is .*)
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveFiles:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveFiles
      summary: Retrieve files from device
      description: |
        <p> Retrieves files from the device based on path matching patterns. </p> <p> Supported operating systems: <strong>macOS, Linux, Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      match: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve files with basic path:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: pathBasic
                    pathBasic: 'C:\Windows\System32\drivers\etc\hosts'
                    pathStructure: all
                    maxFiles: 100
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve hosts file
              Retrieve with regex:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    match: pathRegex
                    pathRegex: 'C:\\Users\\.*\\.exe'
                    pathStructure: sub
                    maxFiles: 50
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve executable files from user directories
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the retrieveFiles action
                  required:
                    - match
                    - pathStructure
                    - maxFiles
                  properties:
                    match:
                      type: string
                      description: Format for file path matching
                      enum:
                        - pathBasic
                        - pathRegex
                    pathBasic:
                      type: string
                      description: Path to file or directory; case-insensitive (required when match is pathBasic)
                    pathRegex:
                      type: string
                      description: Regex matching files or directories; case-insensitive (required when match is pathRegex)
                    pathStructure:
                      type: string
                      description: |
                        Folder structure preservation method. <ul> <li>all: Maintains folder structure from the drive letter</li> <li>sub: Maintains folder structure from the deepest common folder</li> <li>none: Disregards folder structure</li> </ul>
                      enum:
                        - all
                        - sub
                        - none
                    maxFiles:
                      type: integer
                      description: Maximum number of files to upload
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/retrieveJumpList:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveJumpList
      summary: Retrieve jump list files
      description: |
        <p> Retrieves Jump Lists that are stored in the AutomaticDestinations and CustomDestinations subfolders of the user's \AppData\Roaming\Microsoft\Windows\Recent folder. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve jumplist files:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve jumplist files
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveLogEntries:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveLogEntries
      summary: Retrieve Windows event log entries
      description: |
        <p> Retrieves Windows Event Log entries based on specified filters. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve log entries:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    eventIds:
                      - '4624'
                      - '4625'
                    logNames:
                      - Security
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve security log entries
              Retrieve with time range:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    providers:
                      - Microsoft-Windows-Security-Auditing
                    startTimestamp: '2024-01-01T00:00:00Z'
                    endTimestamp: '2024-01-31T23:59:59Z'
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve security audit logs for January 2024
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the retrieveLogEntries action (all optional)
                  properties:
                    eventIds:
                      type: array
                      description: List of event IDs to retrieve
                      items:
                        type: string
                    providers:
                      type: array
                      description: List of log provider names; case-sensitive
                      items:
                        type: string
                    logNames:
                      type: array
                      description: List of log names (channels); case-sensitive
                      items:
                        type: string
                    startTimestamp:
                      type: string
                      format: date-time
                      description: Start of the period for log entries
                    endTimestamp:
                      type: string
                      format: date-time
                      description: End of the period for log entries
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveMbr:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveMbr
      summary: Retrieve master boot record
      description: |
        <p> Retrieves the Master Boot Record (MBR) from a specified drive, which contains boot loader code and partition table information. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      drive: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve MBR:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    drive: 'C:'
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve Master Boot Record
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the retrieveMbr action
                  required:
                    - drive
                  properties:
                    drive:
                      type: string
                      description: Drive letter
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/retrieveMft:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveMft
      summary: Retrieve master file table
      description: |
        <p> Retrieves the Master File Table (MFT) from a specified drive, which contains metadata about all files and directories on an NTFS volume. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - missing mandatory parameter for the action:
                  description: |
                    At least one of the mandatory parameters for the action is not present
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      drive: parameter is missing
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve MFT:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    drive: 'C:'
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve Master File Table
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the retrieveMft action
                  required:
                    - drive
                  properties:
                    drive:
                      type: string
                      description: Drive letter
              required:
                - targets
                - organizationId
                - parameters
  /response-actions/v1/execute/retrievePrefetch:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrievePrefetch
      summary: Retrieve prefetch files
      description: |
        <p> Retrieves Windows Prefetch files that contain evidence of program execution, including execution count, timestamps, and files/directories accessed by applications. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve prefetch files:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve prefetch files
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveRdpCache:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveRdpCache
      summary: Retrieve RDP cache files
      description: |
        <p> Retrieves Remote Desktop Protocol (RDP) bitmap cache files that contain fragments of remote desktop sessions. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve RDP cache:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve RDP cache files
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveRecentlyAccessed:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveRecentlyAccessed
      summary: Retrieve recently accessed files
      description: |
        <p> Retrieves information about recently accessed files and folders from user activity artifacts. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve recently accessed files:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve recently accessed files
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveRegistryHives:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveRegistryHives
      summary: Retrieve registry hive files
      description: |
        <p> Retrieves Windows registry hive files. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve registry hives:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    includeUserHives: true
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve registry hives
              Retrieve system hives only:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  parameters:
                    includeUserHives: false
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve system registry hives only
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
                parameters:
                  type: object
                  description: Parameters for the retrieveRegistryHives action (all optional)
                  properties:
                    includeUserHives:
                      type: boolean
                      description: Include user registry hives (default is true)
              required:
                - targets
                - organizationId
  /response-actions/v1/execute/retrieveSrumdb:
    post:
      tags:
        - Device response actions
      security:
        - oAuth2:
            - connect.api.write
      operationId: execute-retrieveSrumdb
      summary: Retrieve SRUM database
      description: |
        <p> Retrieves the System Resource Usage Monitor (SRUM) database, which contains historical application resource usage, network connectivity, and energy consumption data. </p> <p> Supported operating systems: <strong>Windows</strong> </p> <p> Clients can check the status of created actions using the endpoint `GET /response-actions/v1/responses`. </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      responses:
        '201':
          description: Request payload was valid and it was processed in the internal backend
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identifier of action
        '400':
          description: |
            Request failed because required properties are missing in request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of targets array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - comment parameter is too long:
                  description: |
                    Maximum length for the parameter value is exceeded
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      message: Comment too long. Max length is 1000 characters.
        '401':
          description: |
            User is not authorized to send request. Check if request  contains Authentication header and valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            User has insufficient privileges to send request. Check if token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            Company or device from request is not found in scope of partner
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company or device not found:
                  description: |
                    Company specified with <code>organizationId</code> or device specified in <code>targets</code> is not found in the scope of client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
                404001 - sensor not found:
                  description: |
                    Sensor does not exist in the sensor database or is not online.
                  value:
                    message: Device is not able to execute response actions.
                    code: 404001
                    transactionId: 0000-someTransactionId
      requestBody:
        content:
          application/json:
            examples:
              Retrieve Srumdb:
                value:
                  organizationId: 2fd54218-1db0-49b8-b4ad-6a2fd54218b9
                  targets:
                    - ec8a0100-d313-4896-b3cb-02188e060bf3
                  comment: Retrieve System Resource Usage Monitor database
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  description: Id of organization to which target devices belong
                targets:
                  type: array
                  description: List of device identifiers on which action is created
                  items:
                    type: string
                  maxItems: 10
                  minItems: 1
                comment:
                  type: string
                  description: Additional comment for action
              required:
                - targets
                - organizationId
  /invitations/v1/invitations:
    post:
      tags:
        - invitations
      security:
        - oAuth2:
            - connect.api.write
      operationId: createInvitation
      summary: Send new device invitations
      description: |
        <p>
          Create a new invitation within the scope of a company. The invitation is sent to
          the specified email and is valid for 30 days.
        </p> <p>
          When a new invitation is created and the target company is specified with <code>organizationId</code>,
          the company must be within the scope of the client's organization. Otherwise, the request will be rejected.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -X POST -d '{"invitations": [{"email":"test@withsecure.com","alias":"My new device","firstName":"John","lastName":"Doe","subscriptionKey":"AAAA-BBBB-CCCC-DDDD-EEEE"}], "organizationId": "181fd624-1db0-49b8-b1b9-b88d6336bd75"}' -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/invitations/v1/invitations
          </code>
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      requestBody:
        content:
          application/json:
            examples:
              Create new invitation with company client credentials:
                description: |
                  The invitation will be sent to the email in English, and the expiration date will be calculated for the 'UTC' timezone. <code>organizationId</code> is not required because the client is authenticated with company credentials.
                value:
                  invitations:
                    email: device-owner@company.com
                    subscriptionKey: AAAA-BBBB-CCCC-DDDD-EEEE
              Create new invitation with partner client credentials:
                description: |
                  The invitation will be sent to the email in English, and the expiration date will be calculated for the 'UTC' timezone. <code>organizationId</code> is required because the client is authenticated with partner credentials.
                value:
                  organizationId: 181fd624-1db0-49b8-b1b9-b88d6336bd75
                  invitations:
                    email: device-owner@company.com
                    subscriptionKey: AAAA-BBBB-CCCC-DDDD-EEEE
              Create new invitation with all parameters:
                description: |
                  User 'John Doe' will receive the invitation in German, and the expiration date will be calculated for the 'Europe/Berlin' timezone.
                value:
                  organizationId: 181fd624-1db0-49b8-b1b9-b88d6336bd75
                  invitations:
                    - email: john.doe@company.com
                      subscriptionKey: AAAA-BBBB-CCCC-DDDD-EEEE
                      alias: company-device
                      firstName: John
                      lastName: Doe
                      language: de_DE
                      timezone: Europe/Berlin
            schema:
              type: object
              properties:
                invitations:
                  type: array
                  minItems: 1
                  maxItems: 1
                  items:
                    type: object
                    properties:
                      email:
                        type: string
                        description: The end user's email address (the invitation will be sent to this address).
                      subscriptionKey:
                        type: string
                        description: The subscription under which the invited device will be registered.
                      alias:
                        type: string
                        description: |
                          A human-friendly name for the device that is displayed in the EPP management portal. If this property is defined for an invitation to a Mobile Protection subscription, the alias will be set as the name of the registered device.
                      firstName:
                        type: string
                        description: |
                          The end user's first name. If present, it will be used as the recipient's name in the invitation email.
                      lastName:
                        type: string
                        description: |
                          The end user's last name. If present, it will be used as the recipient's name in the invitation email.
                      language:
                        type: string
                        description: The language of the invitation in Locale format.
                        default: en_US
                        enum:
                          - cs_CZ
                          - da_DK
                          - de_DE
                          - en_US
                          - el_GR
                          - es_ES
                          - es_MX
                          - et_EE
                          - fi_FI
                          - fr_FR
                          - fr_CA
                          - hu_HU
                          - it_IT
                          - ja_JP
                          - lt_LT
                          - nl_NL
                          - no_NO
                          - pl_PL
                          - pt_PT
                          - pt_BR
                          - ro_RO
                          - ru_RU
                          - sl_SI
                          - sv_SE
                          - tr_TR
                          - vi_VN
                          - zh_HK
                          - zh_TW
                          - zh_CN
                      timezone:
                        type: string
                        description: |
                          The regional timezone identifier for the invitation. This affects how the expiration date is displayed in the invitation. Examples: UTC, Europe/Helsinki, America/Chicago.
                        default: UTC
                    required:
                      - email
                      - subscriptionKey
                organizationId:
                  type: string
                  description: |
                    The UUID of the target company under which the new invitation is created.
      responses:
        '200':
          description: Invitations are sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: ID of the invitation. It can be used for resend or renew operations.
                        expirationDate:
                          type: string
                          description: Invitation expiration date.
                        productVariant:
                          type: string
                          enum:
                            - mobileprotection
                            - mobileprotection_vpn
                            - computerprotection
                            - computerprotection_premium
                            - computerprotection_edr
                            - computerprotection_premium_edr
                            - edr
                            - radar
                            - serversecurity
                            - serverprotection_premium
                            - serverprotection_premium_rdr
                            - rdr_server
                            - elements_connector
                          description: Product variant
                        subscriptionKey:
                          type: string
                          description: |
                            Subscription under which the invited device will be registered.
                        installationCode:
                          type: string
                          description: |
                            One-time code used for device registration. In the legacy  <a href='/api-reference/psb#tag--provisioning-invitations'>Endpoint Protection API</a>,  this property was called <code>attributionId</code>.
                        recipient:
                          type: object
                          properties:
                            email:
                              type: string
                              description: End user's email address.
                            alias:
                              type: string
                              description: |
                                Human-friendly name of the device displayed in the EPP management portal.  If this property is defined for an invitation to a Mobile Protection subscription,  the alias will be set as the name of the registered device.
                            firstName:
                              type: string
                              description: End user's first name.
                            lastName:
                              type: string
                              description: End user's last name.
                          required:
                            - email
                        sentDate:
                          type: string
                          description: Invitation sent date.
                      required:
                        - id
                        - expirationDate
                        - productVariant
                        - subscriptionKey
                        - recipient
                        - installationCode
                required:
                  - invitations
        '400':
          description: |
            The request failed because required properties are missing in the request payload.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400003 - invalid size of invitations array:
                  description: |
                    Indicates that there are either too many or too few items in the provided array.
                  value:
                    message: Array should contain between N and M items.
                    code: 400003
                    transactionId: 0000-someTransactionId
                400004 - required parameter is missing in request body:
                  description: The partner client did not send the organizationId in the request body.
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      organizationId: Organization must be specified in request from partner external client
                400006 - invalid organization type:
                  value:
                    message: Invalid organization type.
                    code: 400006
                    transactionId: 0000-someTransactionId
                    details:
                      organizationId: someUuid
                      expected: company
                      actual: sop
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user has insufficient privileges to send the request. Check if the token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
        '404':
          description: |
            The company specified in the request is not found in the scope of the partner.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - company not found:
                  description: |
                    The company specified with <code>organizationId</code> is not found in the scope of the client's organization.
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
    get:
      tags:
        - invitations
      security:
        - oAuth2:
            - connect.api.read
      operationId: listInvitations
      summary: List invitations
      description: |
        <p>
         Lists invitations under a company. The response contains up to 200 invitations.
        </p> <p>
         Request example: </br>
         <code part="curl">
           curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/invitations/v1/invitations?organizationId={companyId}
         </code>
        </p>
      parameters:
        - name: organizationId
          in: query
          required: false
          description: |
            The UUID of a company. If the organizationId is missing, the default organization of the authenticated client is used.
          schema:
            type: string
          example:
            - ec8a0100-d313-4896-b3cb-02188e060bf3
        - name: state
          in: query
          required: false
          description: Filter by invitation state.
          schema:
            type: string
            enum:
              - expired
              - pending
            default: pending
        - name: anchor
          in: query
          required: false
          description: |
            Anchor pointing to the page that should be retrieved. If the parameter is missing or set to the default value, the endpoint returns the first page.
          schema:
            type: string
            default: no-value
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
      responses:
        '200':
          description: List of invitations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: ID of the invitation. It can be used for resend or renew operations.
                        expirationDate:
                          type: string
                          description: Invitation expiration date.
                        productVariant:
                          type: string
                          enum:
                            - mobileprotection
                            - mobileprotection_vpn
                            - computerprotection
                            - computerprotection_premium
                            - computerprotection_edr
                            - computerprotection_premium_edr
                            - edr
                            - radar
                            - serversecurity
                            - serverprotection_premium
                            - serverprotection_premium_rdr
                            - rdr_server
                            - elements_connector
                          description: Product variant
                        subscriptionKey:
                          type: string
                          description: |
                            Subscription under which the invited device will be registered.
                        installationCode:
                          type: string
                          description: |
                            One-time code used for device registration. In the legacy  <a href='/api-reference/psb#tag--provisioning-invitations'>Endpoint Protection API</a>,  this property was called <code>attributionId</code>.
                        recipient:
                          type: object
                          properties:
                            email:
                              type: string
                              description: End user's email address.
                            alias:
                              type: string
                              description: |
                                Human-friendly name of the device displayed in the EPP management portal.  If this property is defined for an invitation to a Mobile Protection subscription,  the alias will be set as the name of the registered device.
                            firstName:
                              type: string
                              description: End user's first name.
                            lastName:
                              type: string
                              description: End user's last name.
                          required:
                            - email
                        sentDate:
                          type: string
                          description: Invitation sent date.
                      required:
                        - id
                        - expirationDate
                        - productVariant
                        - subscriptionKey
                        - recipient
                        - installationCode
                  nextAnchor:
                    type: string
                    description: Anchor to be used to retrieve the next page. Not to be returned on the last page.
                required:
                  - items
        '400':
          description: |
            The request failed because of missing required parameters  or incorrect parameter values.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400006 - invalid organization type:
                  value:
                    message: Invalid organization type.
                    code: 400006
                    transactionId: 0000-someTransactionId
                    details:
                      organizationId: someUuid
                      expected: company
                      actual: sop
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
    delete:
      tags:
        - invitations
      security:
        - oAuth2:
            - connect.api.write
      operationId: deleteInvitations
      summary: Delete invitations
      description: |
        <p>
          Deletes invitations with the given IDs from the specified company. The query accepts a limited number of invitations.
          Before processing the request, duplicates are removed from the list.
        </p> <p>
          Request example: </br>
          <code part="curl">
            curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" "https://api.connect.withsecure.com/invitations/v1/invitations?organizationId={companyId}&invitationId={firstInvitationId}&invitationId={secondInvitationId}"
          </code>
        </p>
      parameters:
        - name: organizationId
          in: query
          required: false
          description: |
            The UUID of a company. If the organizationId is missing, the default organization of the authenticated client is used.
          example:
            - ec8a0100-d313-4896-b3cb-02188e060bf3
          schema:
            type: string
        - name: invitationId
          in: query
          required: true
          description: List of IDs of invitations to be deleted. Up to 20 items.
          schema:
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 20
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
      responses:
        '200':
          description: Invitations are deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitations:
                    type: array
                    description: List of removed invitations (without duplicates).
                    items:
                      type: string
        '400':
          description: |
            The request failed because of missing required parameters  or incorrect parameter values.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400006 - invalid organization type:
                  value:
                    message: Invalid organization type.
                    code: 400006
                    transactionId: 0000-someTransactionId
                    details:
                      organizationId: someUuid
                      expected: company
                      actual: sop
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user has insufficient privileges to send the request. Check if the token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
    put:
      tags:
        - invitations
      security:
        - oAuth2:
            - connect.api.write
      operationId: renewResendInvitations
      summary: Renew and resend invitations
      description: |
        <p>
          Allows renewing expired invitations or resending emails for pending invitations.
          <ol>
            <li>Renew - extends the expiration date of outdated invitations and sends new emails to the original recipients.
            This operation is only applied to expired invitations. Any pending invitations in the request
            body will be ignored.<br>
            <b>Request example:</b> </br>
          <code part="curl">
            curl -X PUT -d '{"operation": "renew", "organizationId": "{companyId}", "invitations":
              ["{invitationId}"]}' -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/invitations/v1/invitations
          </code></li>
            <li>Resend - resends emails to the original recipients for pending invitations.<br>
            <b>Request example:</b> </br>
          <code part="curl">
            curl -X PUT -d '{"operation": "resend", "organizationId": "{companyId}", "invitations":
              ["{invitationId}"]}' -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/invitations/v1/invitations
          </code></li>
          </ol>
        </p>
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the content type. Only <code>application/json</code> is supported.
      requestBody:
        content:
          application/json:
            examples:
              Resend pending invitations:
                value:
                  organizationId: ec8a0100-d313-4896-b3cb-02188e060bf3
                  operation: resend
                  invitations:
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
              Renew expired invitations:
                value:
                  organizationId: ec8a0100-d313-4896-b3cb-02188e060bf3
                  operation: renew
                  invitations:
                    - 01898f1e-d32d-40fe-b3c5-9f039c1eac04
                    - 1226e0a9-653a-4682-b4ad-6a2fd54218b9
                    - 181fd624-1db0-49b8-b1b9-b88d6336bd75
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  description: The UUID of a company.
                operation:
                  type: string
                  description: The name of the operation to trigger.
                  enum:
                    - resend
                    - renew
                invitations:
                  description: List of IDs of invitations - targets of the requested operation.
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
              required:
                - organizationId
                - invitations
                - operation
      responses:
        '204':
          description: The requested operation was successful.
        '400':
          description: |
            The request failed because of missing required parameters  or incorrect parameter values.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400006 - invalid organization type:
                  value:
                    message: Invalid organization type.
                    code: 400006
                    transactionId: 0000-someTransactionId
                    details:
                      organizationId: someUuid
                      expected: company
                      actual: sop
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '403':
          description: |
            The user has insufficient privileges to send the request. Check if the token has sufficient scopes.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                403001 - forbidden:
                  value:
                    message: Insufficient scope. The request requires higher privileges than provided by the access token.
                    code: 403001
                    transactionId: 0000-someTransactionId
  /software-updates/v1/missing-updates:
    post:
      tags:
        - software updates
      security:
        - oAuth2:
            - connect.api.read
      operationId: getMissingUpdates
      summary: Query missing software updates
      description: |
        <p>
          Queries a list of software updates that are ready to install. The list contains information
          collected by the EPP agent and sent with status updates, sorted by `category` in
          descending order. If this endpoint returns an empty list, it might indicate that the software
          installed on the device is up-to-date or the EPP agent has never sent a status update.
        </p> <p>
          It is possible to filter software updates by their category. Additionally, security
          patches can be filtered by their severity. Non-security patches have a severity of <code>unclassified</code>.
        </p> <p>
          It's recommended to use this endpoint together with the <a href="/api-reference/elements#get-/devices/v1/devices">
          Device listing endpoint</a> called with the query parameter <code>patchOverallState</code>.
        </p> <p>
          <b>Example</b>
          <ol>
            <li><code part="curl">
               curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/devices/v1/devices?patchOverallState=missingCriticalUpdates
              </code></li>
            <li><code part="curl">
               curl -X POST -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/software-updates/v1/missing-updates
               -d "deviceId={device_id}&category=critical"
              </code></li>
          </ol>
        </p> <p>
          Given the two example commands, the first one will find all devices that are missing critical updates. If the command returns any device
          that needs attention, then the second command will fetch a list of software that requires an upgrade on the device with the given <code>deviceId</code>.
        </p>
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                deviceId:
                  type: string
                  format: uuid
                  example: 30ff8adf-3190-4bab-8923-2caaf954836a
                  description: ID of the device in UUID format.
                severity:
                  description: Severity of software updates that should be included in the list.
                  type: string
                  enum:
                    - critical
                    - important
                    - moderate
                    - low
                    - unclassified
                category:
                  description: Category of software updates that should be included in the list.
                  type: string
                  enum:
                    - security
                    - nonSecurity
                    - servicePack
                    - securityTool
                    - none
                limit:
                  description: Maximum number of items in the response.
                  type: integer
                  format: int32
                  default: 100
                  minimum: 1
                  maximum: 200
                anchor:
                  type: string
                  default: no-value
                  description: |
                    Anchor pointing to the page that should be retrieved. If the parameter is missing or equal to the default value, the endpoint returns the first page.
              required:
                - deviceId
      responses:
        '200':
          description: List of software updates for the device.
          content:
            application/json:
              examples:
                List of non-security updates:
                  description: |
                    The response contains non-security updates. Each patch has a category of <code>unclassified</code>. Some items don't have the properties <code>installedVersion</code> and <code>targetVersion</code>.
                  value:
                    items:
                      - id: 85a283f8-0e2c-4a19-a5a3-7ec4a4d8dd95
                        name: Windows Malicious Software Removal Tool x64 - v4.116 (KB811130)
                        severity: unclassified
                        category: nonSecurity
                        description: Windows Malicious Software Removal Tool x64 - v4.116 (KB811130)
                        software:
                          vendor: Microsoft Corporation
                          name: Windows Update Agent
                        bulletinId: FSPM-1103-60302-222333/x64
                        cve: []
                      - id: eedff462-c951-4967-b766-72f75c1176b3
                        name: Microsoft Edge 115.0.1901.203
                        description: Microsoft Edge 115.0.1901.203
                        severity: unclassified
                        category: nonSecurity
                        cve: []
                        bulletinId: FSPM-3103-48305-183/x64
                        software:
                          name: Microsoft Edge
                          vendor: Microsoft Corporation
                        installedVersion: 115.0.1901.200
                        targetVersion: 115.0.1901.203
                List of security updates:
                  value:
                    items:
                      - id: c6217fea-9b7a-4459-8e34-0ebd9a3903d3
                        name: Mozilla Firefox 116.0.2
                        severity: important
                        category: security
                        description: Mozilla Firefox 116.0.2
                        software:
                          name: Mozilla Firefox (x86)
                          vendor: Mozilla Corporation
                        installedVersion: 57.0.2
                        targetVersion: 116.0.2
                        bulletinId: FSMP-46-47768-5/x86
                        cve:
                          - id: CVE-2018-5126
                            severity: IMPORTANT
                            severityIndex: 74
                            cvss3:
                              score: '9.8'
                          - id: CVE-2018-5092
                            severity: LOW
                            severityIndex: 35
                            cvss3:
                              score: '4.3'
                    nextAnchor: nex-page-ref
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Collection of missing software updates.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: ID of the software patch.
                        name:
                          type: string
                          description: Name of the software patch.
                        severity:
                          type: string
                          description: |
                            Severity of the patch. Equals <code>unclassified</code> when the patch <code>category</code> is different from <code>security</code>.
                          enum:
                            - low
                            - moderate
                            - important
                            - critical
                            - unclassified
                        category:
                          type: string
                          description: Category of the patch.
                          enum:
                            - security
                            - nonSecurity
                            - servicePack
                            - securityTool
                            - none
                        software:
                          type: object
                          description: |
                            Properties of the software that requires an update.
                          properties:
                            name:
                              type: string
                              description: |
                                Software that requires an update or reports it, for example, Windows Update Agent.
                            vendor:
                              type: string
                              description: Vendor of the software to update.
                        bulletinId:
                          type: string
                          description: Unique identifier of the patch.
                        installedVersion:
                          type: string
                          description: Version of the installed software. This property is optional.
                        targetVersion:
                          type: string
                          description: New version of the software to install. This property is optional.
                        cve:
                          description: |
                            List of CVE vulnerabilities that are supposed to be fixed with this software update. The list might be empty in non-security updates.
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: CVE ID.
                              severity:
                                type: string
                                description: Value representing the severity of the vulnerability.
                              severityIndex:
                                type: integer
                                description: Numeric value representing the severity of the vulnerability.
                              cvss3:
                                type: object
                                description: CVSS version 3.x
                                properties:
                                  score:
                                    type: string
                  nextAnchor:
                    type: string
                    description: |
                      Anchor to be used to retrieve the next page. Not to be returned on the last page.
        '400':
          description: |
            The request failed because of missing required parameters  or incorrect parameter values.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400001 - request parameter has invalid format:
                  description: 'Indicates that the request parameters have the wrong format and can''t be converted to the target value. For example, a timestamp parameter that doesn''t match the date-time format. Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong format. Check details.
                    code: 400001
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: someTimestamp
                      invalidValue: '2022-10-6T12:1:14Z'
                400002 - request parameter has invalid type:
                  description: 'Indicates that the request parameters have a different type than expected. For example, a "string" value instead of an "integer". Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong type. Check details.
                    code: 400002
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: limit
                      invalidValue: some-string
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send the request. Check if the request  contains an Authentication header and a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
        '404':
          description: Requested resource is not found.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                404000 - not found:
                  value:
                    message: Could not find the resource.
                    code: 404000
                    transactionId: 0000-someTransactionId
  /databases/v1/latest-versions:
    get:
      tags:
        - databases
      security:
        - oAuth2:
            - connect.api.read
      operationId: databases
      summary: Get the latest version information for databases
      description: |
        <p>
         Get the latest version information for databases. The table below provides a list of supported database identifiers that can be used in the query.
        </p> <p> <table> <tr><th>Product</th><th>Database Id</th></tr> <tr><td><u>EPP Win32</u></td><td>capricorn-win32</td></tr> <tr><td></td><td>deepguard-db</td></tr> <tr><td></td><td>hydra-win32</td></tr> <tr><td></td><td>lynx-win32</td></tr> <tr><td></td><td>nifcore-win32</td></tr> <tr><td></td><td>nifweb-win32</td></tr> <tr><td></td><td>oneclient-elements-win32</td></tr> <tr><td></td><td>pinned-certificates-win</td></tr> <tr><td></td><td>sccore-win32</td></tr> <tr><td></td><td>swup-win-db</td></tr> <tr><td></td><td>ulcore-win32</td></tr> <tr><td></td><td>ulupdater-win32</td></tr> <tr><td></td><td>uss-win32</td></tr> <tr><td></td><td>virgo-win32</td></tr>
        <tr><td><u>EPP Win64</u></td><td>capricorn-win64</td></tr> <tr><td></td><td>deepguard-db</td></tr> <tr><td></td><td>hydra-win64</td></tr> <tr><td></td><td>lynx-win64</td></tr> <tr><td></td><td>nifcore-win64</td></tr> <tr><td></td><td>nifweb-win64</td></tr> <tr><td></td><td>oneclient-elements-win32</td></tr> <tr><td></td><td>pinned-certificates-win</td></tr> <tr><td></td><td>sccore-win64</td></tr> <tr><td></td><td>swup-win-db</td></tr> <tr><td></td><td>ulcore-win64</td></tr> <tr><td></td><td>ulupdater-win64</td></tr> <tr><td></td><td>uss-win64</td></tr> <tr><td></td><td>virgo-win64</td></tr>
        <tr><td><u>EPP Win ARM64</u></td><td>capricorn-win-arm64</td></tr> <tr><td></td><td>deepguard-db</td></tr> <tr><td></td><td>hydra-win-arm64</td></tr> <tr><td></td><td>lynx-win-arm64</td></tr> <tr><td></td><td>nifcore-win-arm64</td></tr> <tr><td></td><td>nifweb-win-arm64</td></tr> <tr><td></td><td>oneclient-elements-win32</td></tr> <tr><td></td><td>pinned-certificates-win</td></tr> <tr><td></td><td>sccore-win-arm64</td></tr> <tr><td></td><td>swup-win-db</td></tr> <tr><td></td><td>ulcore-win-arm64</td></tr> <tr><td></td><td>ulupdater-win-arm64</td></tr> <tr><td></td><td>uss-win-arm64</td></tr> <tr><td></td><td>virgo-win-arm64</td></tr>
        <tr><td><u>EPP+EDR Win32</u></td><td>capricorn-win32</td></tr> <tr><td></td><td>deepguard-db</td></tr> <tr><td></td><td>hydra-win32</td></tr> <tr><td></td><td>cram-win32</td></tr> <tr><td></td><td>famp-client-win32</td></tr> <tr><td></td><td>sensor-win32</td></tr> <tr><td></td><td>sensor-win-db</td></tr> <tr><td></td><td>hydra-win32</td></tr> <tr><td></td><td>lynx-win32</td></tr> <tr><td></td><td>nifcore-win32</td></tr> <tr><td></td><td>nifweb-win32</td></tr> <tr><td></td><td>oneclient-elements-win32</td></tr> <tr><td></td><td>pinned-certificates-win</td></tr> <tr><td></td><td>sccore-win32</td></tr> <tr><td></td><td>swup-win-db</td></tr> <tr><td></td><td>ulcore-win32</td></tr> <tr><td></td><td>ulupdater-win32</td></tr> <tr><td></td><td>uss-win32</td></tr> <tr><td></td><td>virgo-win32</td></tr>
        <tr><td><u>EPP+EDR Win64</u></td><td>capricorn-win64</td></tr> <tr><td></td><td>deepguard-db</td></tr> <tr><td></td><td>hydra-win64</td></tr> <tr><td></td><td>cram-win64</td></tr> <tr><td></td><td>famp-client-win64</td></tr> <tr><td></td><td>sensor-win64</td></tr> <tr><td></td><td>sensor-win-db</td></tr> <tr><td></td><td>lynx-win64</td></tr> <tr><td></td><td>nifcore-win64</td></tr> <tr><td></td><td>nifweb-win64</td></tr> <tr><td></td><td>oneclient-elements-win32</td></tr> <tr><td></td><td>pinned-certificates-win</td></tr> <tr><td></td><td>sccore-win64</td></tr> <tr><td></td><td>swup-win-db</td></tr> <tr><td></td><td>ulcore-win64</td></tr> <tr><td></td><td>ulupdater-win64</td></tr> <tr><td></td><td>uss-win64</td></tr> <tr><td></td><td>virgo-win64</td></tr>
        <tr><td><u>Client Security Win32</u></td><td>capricorn-win32</td></tr> <tr><td></td><td>deepguard-db</td></tr> <tr><td></td><td>hydra-win32</td></tr> <tr><td></td><td>hydra-win32</td></tr> <tr><td></td><td>lynx-win32</td></tr> <tr><td></td><td>nifcore-win32</td></tr> <tr><td></td><td>nifweb-win32</td></tr> <tr><td></td><td>pinned-certificates-win</td></tr> <tr><td></td><td>sccore-win32</td></tr> <tr><td></td><td>swup-win-db</td></tr> <tr><td></td><td>ulcore-win32</td></tr> <tr><td></td><td>ulupdater-win32</td></tr> <tr><td></td><td>uss-win32</td></tr> <tr><td></td><td>virgo-win32</td></tr>
        <tr><td><u>Client Security Win64</u></td><td>capricorn-win64</td></tr> <tr><td></td><td>deepguard-db</td></tr> <tr><td></td><td>hydra-win64</td></tr> <tr><td></td><td>lynx-win64</td></tr> <tr><td></td><td>nifcore-win64</td></tr> <tr><td></td><td>nifweb-win64</td></tr> <tr><td></td><td>pinned-certificates-win</td></tr> <tr><td></td><td>sccore-win64</td></tr> <tr><td></td><td>swup-win-db</td></tr> <tr><td></td><td>ulcore-win64</td></tr> <tr><td></td><td>ulupdater-win64</td></tr> <tr><td></td><td>uss-win64</td></tr> <tr><td></td><td>virgo-win64</td></tr>
        <tr><td><u>EPP / EPP+EDR (Mac)</u></td><td>capricorn-macos-2</td></tr> <tr><td></td><td>elements-macos</td></tr>  <tr><td></td><td>fmlib-macos</td></tr> <tr><td></td><td>hydra-macos</td></tr> <tr><td></td><td>pinned-certificates-unix</td></tr> <tr><td></td><td>sensor-macos-db</td></tr> <tr><td></td><td>swup-macos-db</td></tr> <tr><td></td><td>xfence-rules</td></tr>
        <tr><td><u>Linux Security+EDR</u></td><td>capricorn-linux64</td></tr> <tr><td></td><td>fmlibunix64</td></tr> <tr><td></td><td>fsbg-100-linux-x86_64</td></tr> <tr><td></td><td>hydra-linux64</td></tr> <tr><td></td><td>pinned-certificates-unix</td></tr> <tr><td></td><td>linuxsecurity-1200-linux-x86_64</td></tr> <tr><td></td><td>sensor-linux-db</td></tr> <tr><td></td><td>sensor-linux64</td></tr> <tr><td></td><td>cram-linux64</td></tr> <tr><td></td><td>famp-client-linux64</td></tr>
        <tr><td><u>Linux Security</u></td><td>capricorn-linux64</td></tr> <tr><td></td><td>fmlibunix64</td></tr> <tr><td></td><td>fsbg-100-linux-x86_64</td></tr> <tr><td></td><td>hydra-linux64</td></tr> <tr><td></td><td>pinned-certificates-unix</td></tr> <tr><td></td><td>linuxsecurity-1200-linux-x86_64</td></tr>
        <tr><td><u>Atlant</u></td><td>capricorn-linux64</td></tr> <tr><td></td><td>fmlibunix64</td></tr> <tr><td></td><td>fsbg-100-linux-x86_64</td></tr> <tr><td></td><td>hydra-linux64</td></tr> <tr><td></td><td>fsbspamd-100-linux-x86_64</td></tr> <tr><td></td><td>atlant-100-linux-x86_64</td></tr>
        </table> </p> <p>
          Request example: </br>
          <code part="curl">
            curl -H "Authorization: Bearer YOUR_TOKEN" https://api.connect.withsecure.com/databases/v1/latest-versions?id={databaseId}
          </code>
        </p>
      parameters:
        - name: id
          in: query
          required: true
          description: |
            A list of database identifiers. If the list contains an identifier of an unsupported database, the request will fail with an error.
          schema:
            type: array
            items:
              type: string
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: |
            HTTP header that contains information about the software used to send the request. The request will be rejected if the <code>User-Agent</code> header is missing.
      responses:
        '200':
          description: |
            Latest versions of requested databases.
          content:
            application/json:
              schema:
                type: object
                description: |
                  A successful response from the service contains information about the latest versions of all selected databases.
                properties:
                  items:
                    type: array
                    description: Each item represents the latest version of a database that was selected in the request.
                    items:
                      type: object
                      properties:
                        id:
                          description: Database identifier.
                          type: string
                        title:
                          description: User-friendly title of the database version.
                          type: string
                        version:
                          description: Latest version of the update.
                          type: number
              examples:
                List of versions:
                  value:
                    items:
                      - id: hydra-linux64
                        title: WithSecure Hydra Update 2024-10-11_01
                        version: 1728613483
                      - id: sensor-win32
                        title: WithSecure Sensor (64-bit) 2024-10-09_01
                        version: 1728483927
        '400':
          description: Request failed because parameters have incorrect data.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                400000 - invalid parameters or data:
                  value:
                    message: Bad request because of invalid parameters or data.
                    code: 400000
                    transactionId: 0000-someTransactionId
                400001 - request parameter has invalid format:
                  description: 'Indicates that the request parameters have the wrong format and can''t be converted to the target value. For example, a timestamp parameter that doesn''t match the date-time format. Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong format. Check details.
                    code: 400001
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: someTimestamp
                      invalidValue: '2022-10-6T12:1:14Z'
                400002 - request parameter has invalid type:
                  description: 'Indicates that the request parameters have a different type than expected. For example, a "string" value instead of an "integer". Information about the invalid parameter is included in the error details.'
                  value:
                    message: Request parameter(s) have wrong type. Check details.
                    code: 400002
                    transactionId: 0000-someTransactionId
                    details:
                      invalidParam: limit
                      invalidValue: some-string
                400004 - wrong request parameter:
                  description: 'Indicates that a request parameter has an invalid value. For example, the value is out of range. The error response details include the name of the invalid parameter and the reason why it was rejected.'
                  value:
                    message: Invalid request parameter. Check details.
                    code: 400004
                    transactionId: 0000-someTransactionId
                    details:
                      limit: required value between 1 and 200
        '401':
          description: |
            The user is not authorized to send the request. Ensure that the request  contains an Authentication header with a valid access token.
          content:
            application/json:
              schema:
                title: Common error schema
                type: object
                properties:
                  message:
                    type: string
                    description: Error description.
                  code:
                    type: number
                    description: Elements API's error code.
                  transactionId:
                    type: string
                    description: Transaction ID used to trace the request.
                  documentation:
                    type: string
                    description: Optional link to error documentation.
                  details:
                    type: object
                    description: Object containing further error details.
                required:
                  - message
                  - code
              examples:
                401000 - unauthorized:
                  value:
                    message: Unauthorized.
                    code: 401000
                    transactionId: 0000-someTransactionId
