Create a reusable Shortcut 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 Shortcut template to manage desktop or internet shortcuts on Windows target endpoints. This policy supports both computer and user configurations.

Request URL

https://{serverurl}/dcapi/config-policies/v2/windows/shortcut 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

Shortcut supports both computer and user configurations.

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 shortcut to create or delete, applied in the order they appear, for either a computer or user target.

Show Sub-Attributes
JSON Object
Show Sub-Attributes
typestringMandatory

Type of shortcut.
Allowed Values:
generalShortcut = Creates a shortcut to an application, file, folder, or other local resource.,
internetShortcut = Creates a shortcut to an internet or web URL.
Example: type: "generalShortcut".

operationstringMandatory

Operation to perform.
Allowed values:
create = creates shortcut,
delete = deletes the shortcut matches with shortcutName
Example: operation: "create".

shortcutNamestringMandatory

Name of the shortcut. This field is required when creating a shortcut and is used to identify the shortcut when deleting it.
Example: shortcutName: "My Application".

targetAppstringOptional

Path of the target application for which the shortcut should be created. The application can be located on the local machine or a network location.
Example: targetApp: "C:\Applications\MyApplication\Application.exe".

targetUrlstringOptional

Web URL for which the shortcut should be created. This option is available only when Action = internetShortcut.
Example: targetUrl: "https://www.example.com".

targetAppArgumentstringOptional

If the application requires any arguments, specify the arguments. Leave it blank if it does not require any arguments.
Example: targetAppArgument: "--mode=production".

shortcutLocationstringOptional

Select the location to create the shortcut. Also this location is used to identify shortcut location while deleting it. The shortcut location can be any of the following:
Allowed values for computer:
allUsersDesktop = Creates the shortcut on the desktop for all users. , allUsersStartMenu = Creates the shortcut in the Start Menu for all users. , allUsersProgramsGroup = Creates the shortcut in the Programs group for all users. , allUsersStartupGroup = Creates the shortcut in the Startup group for all users., customLocation = Creates the shortcut at a custom location specified by the user.
Allowed values for User:
userDesktop = Creates the shortcut on the current user's desktop.
userFavorites = Creates the shortcut in the current user's Favorites folder.
userStartMenu = Creates the shortcut in the current user's Start Menu.
userProgramsGroup = Creates the shortcut in the current user's Programs group.
userStartupGroup = Creates the shortcut in the current user's Startup group.
userQuickLaunchBar = Creates the shortcut in the current user's Quick Launch bar.
allUsersDesktop = Creates the shortcut on the desktop for all users.
allUsersStartMenu = Creates the shortcut in the Start Menu for all users.
allUsersProgramsGroup = Creates the shortcut in the Programs group for all users.
allUsersStartupGroup = Creates the shortcut in the Startup group for all users.
customLocation = Creates the shortcut at the custom location specified by the user.
Example: shortcutLocation: "allUsersDesktop".

customLocationPathstringOptional

Custom location where the shortcut should be created when shortcutLocation is customLocation.
Example: customLocationPath: "C:\Applications\Shortcuts".

startInFolderstringOptional

Some applications may have some references to additional files during execution. In such cases, browse and select the location from where the application has to be started.
Example: startInFolder: "C:\Applications\MyApplication".

commentsstringOptional

Comments for this shortcut.
Example: comments: "Create application shortcut".

iconFileJSON ObjectOptional

Select and upload the icon file using POST /emsapi/files. The uploaded file is referenced here using its fileID and fileName.
fileID (Mandatory) : 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.
fileName : Name of the uploaded icon file.
Supported file format: .ico

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.

runWindowstringOptional

Select how the application has be started -
Allowed values:
normal = Starts the application in its default window state.,
maximized = Starts the application in a maximized window ,
minimized =Starts the application in a minimized window.
Example: runWindow: "normal".

overwritebooleanOptional

Whether to overwrite the shortcut if it already exists.
Allowed values:
true = Overwrites the existing shortcut.
false = Does not overwrite the existing shortcut.

runasAdminbooleanOptional

Whether the shortcut should run the application with administrator privileges. Allowed value:
true = Runs the application as an administrator.
false = Runs the application with standard user privileges.

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

Create Shortcut▼
Create Shortcut -- Create a Windows shortcut with icon, launch and placement options for a computer or user target.
Create Internet Shortcut -- Create a shortcut that opens a web URL from the user's Favorites folder.
Delete Shortcut -- Delete an existing Windows shortcut by its name and location for a computer or user target.

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/shortcut \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"shortcutName":"My Application","type":"generalShortcut","operation":"create"}],"label":"Shortcut Config","configType":"computer"}'

Sample Request Body - Create Shortcut

Create a computer-scoped shortcut entry with every documented field. Shortcut supports both computer and user configurations. targetUrl is empty here because the example creates a general shortcut rather than an internet shortcut.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Shortcut Config",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "shortcutLocation": "userDesktop",
        "comments": "Create application shortcut",
        "customLocationPath": "",
        "iconFile": {
          "fileName": "Custom-Icon.ico",
          "fileID": 302
        },
        "runasAdmin": false,
        "startInFolder": "C:\\Applications\\MyApplication",
        "type": "generalShortcut",
        "targetAppArgument": "--mode=production",
        "targetApp": "C:\\Applications\\MyApplication\\Application.exe",
        "shortcutName": "My Application",
        "runWindow": "normal",
        "operation": "create",
        "overwrite": false,
        "targetUrl": ""
      }
    ],
    "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/shortcut \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"shortcutName":"Support Portal","type":"internetShortcut","operation":"create"}],"label":"Internet Shortcut Config","configType":"user"}'

Sample Request Body - Create Internet Shortcut

Create an internet shortcut that opens a web URL.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Internet Shortcut Config",
    "configType": "user",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "shortcutLocation": "userFavorites",
        "comments": "Open the support portal",
        "customLocationPath": "",
        "iconFile": {
          "fileName": "SupportPortal.ico",
          "fileID": 305
        },
        "runasAdmin": false,
        "startInFolder": "",
        "type": "internetShortcut",
        "targetAppArgument": "",
        "targetApp": "",
        "shortcutName": "Support Portal",
        "runWindow": "normal",
        "operation": "create",
        "overwrite": true,
        "targetUrl": "https://support.example.com"
      }
    ],
    "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/shortcut \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"shortcutName":"My Application","type":"generalShortcut","operation":"delete"}],"label":"Delete Shortcut Config","configType":"user"}'

Sample Request Body - Delete Shortcut

Delete an existing shortcut by name and location.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Delete Shortcut Config",
    "configType": "user",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "shortcutLocation": "userDesktop",
        "shortcutName": "My Application",
        "type": "generalShortcut",
        "operation": "delete"
      }
    ],
    "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 - Create Shortcut

Success response for createShortcut

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

Sample Response: HTTP 400 - Create Shortcut

Error response for createShortcut

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

Sample Response: HTTP 200 - Create Internet Shortcut

Success response for createInternetShortcut

Copied!
  {
    "templateName": "createInternetShortcut",
    "templateId": 351,
    "configType": "user",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Create Internet Shortcut

Error response for createInternetShortcut

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

Sample Response: HTTP 200 - Delete Shortcut

Success response for deleteShortcut

Copied!
  {
    "templateName": "deleteShortcut",
    "templateId": 358,
    "configType": "user",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Delete Shortcut

Error response for deleteShortcut

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/shortcut",
    "errorMsg": "The URL /dcapi/config-policies/v2/windows/shortcut 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.