Company logoHelp Center
Visit www.threatlocker.com

/portalAPI/MaintenanceMode/*

14 min. readlast update: 11.26.2024

This article will encompass all portalAPI calls that are related to /portalAPI/MaintenanceMode/* endpoints

 

Be sure to input the instance your organization exists on for each call. This is indicated with the "INSTANCE" text in each endpoint. Linked here is a KB to find your instance: 

Locating Your Organization's Instance | ThreatLocker Help Center

 

MaintenanceModeGetByComputerId

https://portalapi.INSTANCE.threatlocker.com/portalapi/MaintenanceMode/MaintenanceModeGetByComputerId

  • Method: GET
  • Description: This API will return the Maintenance Mode history of a machine, passing in the computerId. This call can only be utilized with one machine at a time. This can be useful for evaluating the Maintenance Modes the computer has been in previously and determining if the machine is currently in a Maintenance mode(s). For evaluating machines that are in a child organization, utilize the “managedOrganizationId” header and input the organizationId as the value. Then pass in the computerId to this call and the Maintenance Mode history will be displayed for the machine. This can also be used to gather the maintenanceModeId from a Maintenance Mode the machine is currently in which can be useful if looking to use the MaintenanceModeEndById call to end a Maintenance Mode.
  • Required body/parameters
    • Requires valid APIKey/Authorization Token in header
    • ComputerId: Passed in as a query parameter in the below format:
      • GUID format: "00000000-0000-0000-0000-000000000000"
  • Optional body/parameters
    • In header: "managedOrganizationId": <GUID>
      • GUID format: "00000000-0000-0000-0000-000000000000"
  • Permissions
    • Edit Computers
    • Install Computers

 

MaintenanceModeInsert

https://portalapi.INSTANCE.threatlocker.com/portalapi/MaintenanceMode/MaintenanceModeInsert

  • Method: POST
  • Description: This API will allow you to add to the maintenance schedule of a computer. This API will allow you to add to an existing application using Installation and Learning Mode, create a new application using Installation and Learning Mode, utilize Automatic Learning with Learning Mode, and enable all other Maintenance Modes. This API can only be used with one computer at a time as it expects a computerId to be entered in the call. All times used expect a time entered in UTC in format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, leave the T, HH are the hours, the second MM are the minutes, and SS are the seconds. Listed below are what is expected in all the fields for this call.
    • allUsers
      • Determines whether all users on the selected computer will be affected by the Maintnance Mode that will be enabled. If you wish to have only select users affected by the Maintenance Mode, set AllUsers to false and utilize the userList field below to input the users the Maintenance Mode will apply to.
        • Expects true or false
    • automaticApplication
      • When using Learning Mode, this option is used to specify whether automatic Learning will be utilized. If set to true, automatic Learning will be enabled as per the automaticApplicationType set. Refer to the list below for valid automaticApplicationTypes.
        • Expects true or false
    • automaticApplicationType
      •  Automatic Computer will create new applications and policies as needed with the policies being created at the computer level. AutomaticGgroup will create new applications and policies as needed with the policies being created at the computer group level. Automatic System will only learn drivers and miscellaneous Windows files, this will apply to the individual system only.
        • empty = 0
        • Automatic Computer = 1
        • Automatic Group = 2
        • Automatic System = 3
    • comptuerId
      • Enter the computerId where you would like to enable the Maintenance Mode.
        • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • createNewApplication
      • Specifies when using Learning or Installation Mode whether a new application will be used when enabling the Maintenance Mode. If a new application is going to be used, be sure to refer to the newApplication list/description below. If wanting to create a new application, set this to true. If wanting to complete another action, leave this false.
        • Expects true or false
    • endDateTime
      • Specifies when the Maintenance Mode will end on a machine. This expects a time entered in UTC in format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, leave the T, HH are the hours, the second MM are the minutes, and SS are the seconds.
        • Expects end date and time in format: "YYYY-MM-DDTHH:MM:SSZ"
    • existingApplication
      • When not using a new application for Learning and Installation Mode and also not using automatic Learning with Learning Mode, an existing application needs to be supplied. existingApplication expects an applicationId in GUID format "00000000-0000-0000-0000-000000000000" and for the name of the application to be entered as it is assigned to the application already. If the name entered is not what is assigned in the portal, the name will not change to what was entered and the name associated with the applicationId is used. When enabling Learning or Installation Mode from a different organization than the currently logged in organization/where the authenticated user exists, be sure to pass in the organizationId where the application exists. Use the "managedOrganizationId" header to do so.
        • Expects an applicationId in GUID format: "00000000-0000-0000-0000-000000000000"
        • Expects the name in the "name" field
        • In header: "managedOrganizationId": <GUID>
          • GUID format: "00000000-0000-0000-0000-000000000000"
    • MaintenanceTypeId
      • Specifices the Maintenance Mode that will be enabled on the machine selected. Listed below are the types to utilize.

        • MaintenanceType ApplicationControlMonitorOnly = 1

        • MaintenanceType ApplicationControlInstallationMode= 2 

        • MaintenanceType Learning = 3 

        • MaintenanceType Elevation = 4 

        • MaintenanceType TamperProtectionDisabled = 6 

        • MaintenanceType Isolation = 14 

        • MaintenanceType Lockdown = 15 

        • MaintenanceType DisableOpsAlerts = 16 

        • MaintenanceType NetworkControlMonitorOnly = 17 

        • MaintenanceType StorageControlMonitorOnly = 18

    • newApplication
      • Used when creating a new application with Learning and Installation Mode. The applicationId will be assigned after this call is completed, it can stay in as "00000000-0000-0000-0000-000000000000". Enter an application name into the "applicationName" field. Determine whether you would like to create a policy with this new application or not. If you wish to only create a new application, set "createApplicationOnly" to true. If you want to create a new policy, set "createApplicationOnly" to false and enter the ID of where you would like to set the policy in the "appliesToId" field. This can be the computer (use computerId), a computer group (use computerGroupId), or it can be the entire organization (use organizationId). When enabling Learning or Installation Mode from a different organization than the currently logged in organization/where the authenticated user exists, be sure to pass in the organizationId where you would like the application to be created. Use the "managedOrganizationId" header to do so.
        • Expects applicationName
        • Expects true or false for createApplicationOnly
        • Expects an ID to apply a new policy to the selected ID
        • In header: "managedOrganizationId": <GUID>
          • GUID format: "00000000-0000-0000-0000-000000000000"
    • permitEnd
      • The permitEnd field is used to determine whether the end user has the option to end the Maintenance Mode from their machine. If “permitEnd”: true, the tray prompt will appear in the bottom right corner of their screen. If “permitEnd”: false, there will be nothing that appears for the end user.
        • Expects true or false
    • startDateTime
      • Specifies when the Maintenance Mode will start on a machine. This expects a time entered in UTC in format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, leave the T, HH are the hours, the second MM are the minutes, and SS are the seconds.
        • Expects end date and time in format: "YYYY-MM-DDTHH:MM:SSZ"
    • useExistingApplication
      • Specifies when using Learning or Installation Mode whether an existing application will be used when enabling the Maintenance Mode. If a new application is going to be used, be sure to refer to the existingApplication list/description above. If wanting to use an existing application, set this to true. If wanting to complete another action, leave this false.
        • Expects true or false
    • usersList
      • This will contain the list of users the Maintenance Mode will apply to. Enter the users you'd like to have the Maintenance Mode affect, separating each user with a " ", expected in this format: "DOMAIN\USERNAME".
        • Expects a list of users in the above format separated by commas
    • computerDateTime
      • This is used to determine the current time on the machine. As long as this field in not blank, processing will continue as normal as this call should pull the time information from the organization. Expects a time entered in UTC in format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, leave the T, HH are the hours, the second MM are the minutes, and SS are the seconds.
        • Expects date and time in format: "YYYY-MM-DDTHH:MM:SSZ"
  • Required body/parameters
    • Requires valid APIKey/Authorization Token in header
    • Sample body for enabling Automatic Computer Learning

{
  "allUsers": true,
  "automaticApplication": true,
  "automaticApplicationType": 1,
  "computerId": "00000000-0000-0000-0000-000000000000",
  "createNewApplication": false,
  "endDateTime": "YYYY-MM-DDTHH:MM:SSZ",
  "existingApplication": {
    "applicationId": "00000000-0000-0000-0000-000000000000",
    "name": ""
  },
  "maintenanceTypeId": 3,
  "newApplication": {
    "applicationId": "00000000-0000-0000-0000-000000000000",
    "applicationName": "",
    "createApplicationOnly": false,
    "appliesToId": "00000000-0000-0000-0000-000000000000"
  },
  "permitEnd": true,
  "startDateTime": "YYYY-MM-DDTHH:MM:SSZ",
  "useExistingApplication": false,
  "usersList": [
    "DOMAIN\USERNAME"
  ],
  "computerDateTime": "YYYY-MM-DDTHH:MM:SSZ"
}

 

    • Sample body for enabling Installation Mode with a new application

{
  "allUsers": true,
  "automaticApplication": false,
  "automaticApplicationType": 1,
  "computerId": "00000000-0000-0000-0000-000000000000",
  "createNewApplication": true,
  "endDateTime": "YYYY-MM-DDTHH:MM:SSZ",
  "existingApplication": {
    "applicationId": "00000000-0000-0000-0000-000000000000",
    "name": ""
  },
  "maintenanceTypeId": 2,
  "newApplication": {
    "applicationId": "00000000-0000-0000-0000-000000000000",
    "applicationName": "NewApplicationFromAPI",
    "createApplicationOnly": false,
    "appliesToId": "00000000-0000-0000-0000-000000000000"
  },
  "permitEnd": true,
  "startDateTime": "YYYY-MM-DDTHH:MM:SSZ",
  "useExistingApplication": false,
  "usersList": [
    "string"
  ],
  "computerDateTime": "YYYY-MM-DDTHH:MM:SSZ"
}

    • Sample body for enabling Learning Mode with an existing application (assuming a valid applicationId and name are entered into their fields.

{
  "allUsers": true,
  "automaticApplication": false,
  "automaticApplicationType": 1,
  "computerId": "00000000-0000-0000-0000-000000000000",
  "createNewApplication": false,
  "endDateTime": "YYYY-MM-DDTHH:MM:SSZ",
  "existingApplication": {
    "applicationId": "00000000-0000-0000-0000-000000000000",
    "name": ""
  },
  "maintenanceTypeId": 3,
  "newApplication": {
    "applicationId": "00000000-0000-0000-0000-000000000000",
    "applicationName": "",
    "createApplicationOnly": false,
    "appliesToId": "00000000-0000-0000-0000-000000000000"
  },
  "permitEnd": true,
  "startDateTime": "YYYY-MM-DDTHH:MM:SSZ",
  "useExistingApplication": true,
  "usersList": [
    "string"
  ],
  "computerDateTime": "YYYY-MM-DDTHH:MM:SSZ"
}

  • Permissions
    • Edit Computers
    • Edit Application Control Applications
    • Manage Application Control Installation Mode
    • Manage Application Control Learning Mode

 

MaintenanceModeEndById

https://portalapi.INSTANCE.threatlocker.com/portalapi/MaintenanceMode/MaintenanceModeEndById

  • Method: PATCH
  • Description: This API will allow you to end a Maintenance Mode by inserting the computerID in GUID format: "00000000-0000-0000-0000-000000000000" and the MaintenanceModeId in GUID format: "00000000-0000-0000-0000-000000000000" into the below body. This is useful for ending the current Maintenance Mode on a machine through API. The MaintenanceModeId will change with each MaintenanceMode, utilize API Call portalapi/MaintenanceMode/MaintenanceModeGetByComputerId, passing in ComputerID with valid managedOrganizationID and AuthorizationToken to get the current MainteanceModeId. Utilize the portalapi/MaintenanceMode/MaintenanceModeGetByComputerId, passing in ComputerID with valid managedOrganizationID and AuthorizationToken to also pull the current MaintenanceTypeId. This will be consistent with the types IDs shown below.
    • MaintenanceTypeIds

      • MaintenanceType ApplicationControlMonitorOnly = 1

      • MaintenanceType ApplicationControlInstallationMode= 2 

      • MaintenanceType Learning = 3 

      • MaintenanceType Elevation = 4 

      • MaintenanceType TamperProtectionDisabled = 6 

      • MaintenanceType Isolation = 14 

      • MaintenanceType Lockdown = 15 

      • MaintenanceType DisableOpsAlerts = 16 

      • MaintenanceType NetworkControlMonitorOnly = 17 

      • MaintenanceType StorageControlMonitorOnly = 18

  • Required paramerters/body
    • Requires valid APIKey/Authorization Token in header
    • Body

{ 
     "ComputerID" : "00000000-0000-0000-0000-000000000000", 
     "MaintenanceModeId" : "00000000-0000-0000-0000-000000000000", 
     "MaintenanceTypeId" : 1
}

  • Permissions
    • Edit Computers

 

MaintenanceModeUpdateEndDateTimeForSpecificDate

https://portalapi.INSTANCE.threatlocker.com/portalapi/MaintenanceMode/MaintenanceModeUpdateEndDateTimeForSpecificDate

  • Method: POST
  • Description: This API will allow you to change the end date/time of a maintenance mode. Important note that this will only extend the current active Maintenance Mode. If you input a different MaintenanceTypeId than the one currently active on the machine, the Maintenance Mode will not be modified based on the date supplied. Listed below are the Maintenance Modes and identifiers associated with each Maintenance Mode. ComputerID expects a GUID format: "00000000-0000-0000-0000-000000000000". MaintenanceEndDate expects a time entered in UTC in format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, leave the T, HH are the hours, the second MM are the minutes, and SS are the seconds. The maintenanceTypeId expects one of the integer values from below:
    • MaintenanceTypeIds 

      • MaintenanceType ApplicationControlMonitorOnly = 1  

      • MaintenanceType ApplicationControlInstallationMode= 2  

      • MaintenanceType Learning = 3  

      • MaintenanceType Elevation = 4 

      • MaintenanceType TamperProtectionDisabled = 6  

      • MaintenanceType Isolation = 14  

      • MaintenanceType Lockdown = 15  

      • MaintenanceType DisableOpsAlerts = 16  

      • MaintenanceType NetworkControlMonitorOnly = 17  

      • MaintenanceType StorageControlMonitorOnly = 18

  • Required body/parameters
    • Requires valid APIKey/Authorization Token in header
    • Body

      {

         "computerId": "00000000-0000-0000-0000-000000000000",

         "maintenanceEndDate": "YYYY-MM-DDTHH:MM:SSZ",

        "maintenanceTypeId": 1

}

  • Permissions
    • Edit Computers
    • Manage All Maintenance Modes
    • Super Admin
    • Super Admin Child
    • Manage ThreatLocker Detect Threats
    • Manage ThreatLocker Detect Remediations
Was this article helpful?