Create a reusable Registry template for Windows endpoints.

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

Creates a Registry template to manage Windows registry keys and values on target endpoints. The configuration is saved as a reusable template that can be deployed later. registryType manual defines each entry inline through headerKey, subKey, valueName and valueData; registryType import applies exported .reg files supplied through registryFiles or registryShareFilePaths. Use the returned templateId with the Deploy Configuration Template API to deploy it to targets.

Request URL

https://{serverurl}/dcapi/config-policies/v2/windows/registry Copied!

Scope

DesktopCentralCloud.Configurations.CREATECopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory
application/jsonapplication/jsonCopied!

Media type of the request body, as consumed by the endpoint.

AcceptstringMandatory
application/jsonapplication/jsonCopied!

Media type of the response body, as produced by the endpoint.

- Request Body

application/json
JSON Object
Hide Sub-Attributes
labelstringMandatory

Name of the configuration. Returned as templateName in the response.

descriptionstringOptional

Free-text description of the configuration. May be an empty string.

configTypestringMandatory

What the configuration is applied to. Allowed values:
computer = applied to the endpoint
user = applied to the logged-on user

applyAlwaysbooleanOptional

Reapply the configuration at every agent refresh, even when it has already been applied successfully.

applyAtStartupLogonbooleanOptional

Apply the configuration at endpoint startup when configType is computer, or at user logon when configType is user.

applyAtRefreshbooleanOptional

Apply the configuration at the scheduled agent refresh.

enableRetrybooleanOptional

Retry the configuration on the endpoint when it fails. noOfRetries sets how many attempts are made.

enableRefreshMinRetrybooleanOptional

Honour refreshMinRetry as the minimum gap between two retries at refresh.

enableLogonStartupMinRetrybooleanOptional

Honour logonStartupMinRetry as the minimum gap between two retries at startup or logon.

noOfRetriesintegerOptional

Number of retry attempts made after a failure. Read only when enableRetry is true.

refreshMinRetryintegerOptional

Minimum number of minutes between two retries at refresh. Read only when enableRefreshMinRetry is true.

logonStartupMinRetryintegerOptional

Minimum number of minutes between two retries at startup or logon. Read only when enableLogonStartupMinRetry is true.

configDetailsJSON ArrayMandatory

One entry per registry action, applied in the order they appear.

Show Sub-Attributes
JSON Object
Show Sub-Attributes
registryTypestringMandatory

How the entry is defined. Allowed values:
manual = describes the change inline through headerKey, subKey, valueName and valueData
import = applies an exported .reg file supplied through registryFiles or registryShareFilePaths

Mandatory.

actionstringOptional

Registry operation to perform. Allowed values:
writeValue = creates or updates the value named in valueName
deleteValue = removes that value
addKey = creates the key in subKey
deleteKey = removes that key and everything under it

Matched case-insensitively - createKey is not accepted.

headerKeystringOptional

Registry hive the change is made in. Allowed values:
HKLM = HKEY_LOCAL_MACHINE (machine-wide settings)
HKCU = HKEY_CURRENT_USER (preferences of the logged-on user)
HKCR = HKEY_CLASSES_ROOT (file associations, OLE information and shortcut data)
HKCC = HKEY_CURRENT_CONFIG (the hardware profile currently in use)
HKU = HKEY_USERS.Default (the default profile preferences). Which hives apply depends on configType: a computer configuration uses HKLM = HKEY_LOCAL_MACHINE and HKU = HKEY_USERS.Default, while a user configuration uses HKCR = HKEY_CLASSES_ROOT
HKCC = HKEY_CURRENT_CONFIG
HKCU = HKEY_CURRENT_USER and HKU = HKEY_USERS.Default.

subKeystringOptional

Path of the key under headerKey, without the hive prefix (e.g., "SOFTWARE\MyApp\Settings").

dataTypestringOptional

Type of the registry value being written. Allowed values:
regSZ = string
regExpandSZ = expandable string
regMultiSZ = multi-string written through multiValueData
regBinary = binary
regDword = 32-bit number
regQword = 64-bit number

Read only when action is writeValue. Matched case-insensitively, so regDword is accepted but regDWORD is not.

valueNamestringOptional

Name of the registry value to write or delete. Required when action is writeValue or deleteValue; ignored for addKey and deleteKey.

valueDatastringOptional

Data written into valueName, always sent as a string even for numeric types (e.g., regDword). Read only when action is writeValue and dataType is not regMultiSZ.

multiValueDatastringOptional

Data written into valueName when dataType is regMultiSZ, holding the individual strings of the multi-string value. Ignored for every other data type.

credentialDetailsJSON ObjectOptional

Saved credential used to reach the network share holding the .reg files, referenced by credentialID and credentialUUID from List Credentials. Always use an actual saved credential and avoid using credentialDetails: {credentialID: "-1", credentialName: "", credentialUUID: "--"}.

Show Sub-Attributes
credentialIDlongOptional

Identifier of a credential already saved under Admin - Credential Manager. Fetch it from List Credentials. Pass the credentialID together with its credentialUUID; the credential secret itself is never sent through this API.

credentialUUIDstringOptional

UUID of the saved credential, used to reference it without transmitting the secret. Fetch it from List Credentials. Must correspond to the credentialID supplied alongside it.

credentialNamestringOptional

Display name of the saved credential.

fileLocationTypestringOptional

Where the .reg files come from when registryType is import. Allowed values:
http = the files uploaded in registryFiles
networkShare = the UNC paths in registryShareFilePaths

Matched case-insensitively.

registryFilesJSON ArrayOptional

Exported .reg files to import, each already uploaded through POST /emsapi/files. Read only when registryType is import and fileLocationType is http.

Show Sub-Attributes
JSON Object
Show Sub-Attributes
fileIDlongMandatory

Identifier of a file already uploaded to the server. Upload the file first (POST /emsapi/files) and pass the fileID returned by that call. A fileID that has expired from the temporary upload folder is rejected.

fileNamestringOptional

Uploaded file name.

registryShareFilePathsarray[string]Optional

UNC paths of the .reg files to import from a network share. Read only when registryType is import and fileLocationType is networkShare; credentialDetails supplies the account used to reach the share.

enableEmailNotifybooleanOptional

Send an email to the addresses listed in email once the deployment finishes.

enableNotificationbooleanOptional

Notify the endpoint user about this deployment. notificationDuration and notificationEnabledDays are read only when this is true.

emailstringOptional

Comma-separated email addresses notified about the deployment. May be an empty string when enableEmailNotify is false.

notificationDurationintegerOptional

How long a deployment notification stays on screen for the endpoint user. Read only when enableNotification is true.

notificationEnabledDaysintegerOptional

Number of days for which deployment notifications stay enabled. Read only when enableNotification is true.

Examples

Write Registry String▼
Write Registry String -- Write a REG_SZ string value with action writeValue.
Delete Registry Value -- Delete a single registry value with action deleteValue.
Add Registry Key -- Create a registry key with action addKey.
Write DWORD Value -- Write a REG_DWORD value with dataType regDword.

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/registry \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"registryType":"manual"}],"label":"Sample CUSTOM_REGISTRY Config","configType":"computer"}'

Sample Request Body - Write Registry String

Write a string value under HKEY_LOCAL_MACHINE. headerKey accepts HKLM, HKCU, HKCR, HKCC and HKU, of which a computer configuration uses HKLM and HKU while a user configuration uses HKCR, HKCC, HKCU and HKU. dataType accepts regSZ, regExpandSZ, regMultiSZ, regBinary, regDword and regQword. credentialID -1 means no saved credential is used.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Sample CUSTOM_REGISTRY Config",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "registryType": "manual",
        "subKey": "SOFTWARE\\MyApp",
        "valueName": "Version",
        "credentialDetails": {
          "credentialUUID": "--",
          "credentialID": -1,
          "credentialName": ""
        },
        "dataType": "regSZ",
        "action": "writeValue",
        "headerKey": "HKLM",
        "valueData": "1.0"
      }
    ],
    "enableNotification": false,
    "enableEmailNotify": false,
    "notificationDuration": 6,
    "enableRetry": false,
    "enableRefreshMinRetry": false,
    "email": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/registry \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"registryType":"manual"}],"label":"Delete Registry Value","configType":"computer"}'

Sample Request Body - Delete Registry Value

Delete a single value from a key. action deleteValue needs headerKey, subKey and valueName; dataType and valueData are ignored. Use deleteKey to remove the key itself.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Delete Registry Value",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "registryType": "manual",
        "subKey": "SOFTWARE\\MyApp",
        "valueName": "OldSetting",
        "action": "deleteValue",
        "headerKey": "HKLM"
      }
    ],
    "enableNotification": false,
    "enableEmailNotify": false,
    "notificationDuration": 6,
    "enableRetry": false,
    "enableRefreshMinRetry": false,
    "email": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/registry \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"registryType":"manual"}],"label":"Create Registry Key","configType":"computer"}'

Sample Request Body - Add Registry Key

Create a registry key without writing a value into it. The accepted action is addKey - createKey is rejected with HTTP 400.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Create Registry Key",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "registryType": "manual",
        "subKey": "SOFTWARE\\MyCompany\\NewApp",
        "action": "addKey",
        "headerKey": "HKLM"
      }
    ],
    "enableNotification": false,
    "enableEmailNotify": false,
    "notificationDuration": 6,
    "enableRetry": false,
    "enableRefreshMinRetry": false,
    "email": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/registry \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"registryType":"manual"}],"label":"Set DWORD Registry Value","configType":"user"}'

Sample Request Body - Write DWORD Value

Write a DWORD value under HKEY_CURRENT_USER. HKCU is a user hive, so the configuration is sent as configType user. dataType must be regDword - regDWORD is rejected with HTTP 400 - and valueData carries the number as a string.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Set DWORD Registry Value",
    "configType": "user",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "registryType": "manual",
        "subKey": "SOFTWARE\\MyApp\\Settings",
        "valueName": "EnableFeature",
        "dataType": "regDword",
        "action": "writeValue",
        "headerKey": "HKCU",
        "valueData": "1"
      }
    ],
    "enableNotification": false,
    "enableEmailNotify": false,
    "notificationDuration": 6,
    "enableRetry": false,
    "enableRefreshMinRetry": false,
    "email": ""
  }
                
▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json
JSON Object

Success response returned when the configuration is saved as a reusable template.

Hide Sub-Attributes
templateIdlong

Unique identifier of the created template. Pass it to the Deploy Configuration Template API to deploy this template to targets.

templateNamestring

Name of the created template. It is the label sent in the request.

configTypestring

Type of configuration the template was created for. Allowed values:
computer
user

addedUserstring

Login name of the API user who created the template.

- HTTP code 400

Response Body - application/json
JSON Object

Error response when the request contains invalid or missing required fields.

Hide Sub-Attributes
errorCodelong

Product error code. 50003 = CONFIG_INVALID_INPUT_DATA: configDetails is missing or empty, or the configuration could not be resolved for this endpoint. 20003 = SERVICE_NOT_AVAILABLE: the configuration is deprecated for the requested configType.

errorMsgstring

Localised error message for the error code.

- HTTP code 401

Response Body - application/json
JSON Object
Hide Sub-Attributes
errorCodelong

Unauthorized error code returned when authentication credentials are missing, expired, or invalid (authentication=required)

errorMsgstring

Authentication failure reason

- HTTP code 413

Response Body - application/json
JSON Object

Error response returned when the server does not have enough free disk space to store the configuration files.

Hide Sub-Attributes
errorCodelong

Product error code. 170013 = INTERNAL_SERVER_ERROR: raised by the storage pre-check before the template is saved.

errorMsgstring

Localised error message for the error code.

- HTTP code 429

Response Body - application/json
JSON Object
Hide Sub-Attributes
errorCodelong

Rate limit error code returned when the API call threshold (configured via threshold/duration in security XML) is exceeded; client is locked out for lock-period minutes

errorMsgstring

Rate limit exceeded message with retry guidance

- HTTP code 500

Response Body - application/json
JSON Object

Error response returned when the template could not be saved because of an unexpected server error.

Hide Sub-Attributes
errorCodelong

Product error code. 1003 = INTERNAL_ERROR: the template could not be persisted. 50001 = CONFIG_INTERNAL_ERROR: an internal configuration error occurred while processing the request.

errorMsgstring

Localised error message for the error code.

Response Examples

Sample Response: HTTP 200 - Write Registry String

Success response for deployRegistry

Copied!
  {
    "templateName": "deployRegistry",
    "templateId": 316,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Write Registry String

Error response for deployRegistry

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 200 - Delete Registry Value

Success response for registryDeleteValue

Copied!
  {
    "templateName": "registryDeleteValue",
    "templateId": 317,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Delete Registry Value

Error response for registryDeleteValue

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 200 - Add Registry Key

Success response for registryCreateKey

Copied!
  {
    "templateName": "registryCreateKey",
    "templateId": 318,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Add Registry Key

Error response for registryCreateKey

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 200 - Write DWORD Value

Success response for registryDwordValue

Copied!
  {
    "templateName": "registryDwordValue",
    "templateId": 319,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Write DWORD Value

Error response for registryDwordValue

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 401

User is not authorized to create the configuration policy

Copied!
  {
    "errorCode": 1001,
    "errorMsg": "Access denied - You are not allowed to access the requested resource."
  }
                
▼ Show full

Sample Response: HTTP 413

Storage pre-check rejected the request before the template was saved

Copied!
  {
    "errorCode": 170013,
    "errorMsg": "The server machine does not have sufficient disk space. Please free up space and try again."
  }
                
▼ Show full

Sample Response: HTTP 429

Request rejected because the caller exceeded the configured rate limit

Copied!
  {
    "errorCode": "IAM0019",
    "url": "/dcapi/config-policies/v2/windows/registry",
    "errorMsg": "The URL /dcapi/config-policies/v2/windows/registry was called too many times. Please retry after a while."
  }
                
▼ Show full

Sample Response: HTTP 500

Unexpected server error while saving the configuration as a template

Copied!
  {
    "errorCode": 1003,
    "errorMsg": "An Internal Error occurred, try again later."
  }
                
▼ Show full

Duration: 1 minute | Threshold: 30 | Lock period: 5 minutes

Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.