Create a new sensor with scripts, output variables, and execution metadata

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 new sensor with scripts, output variables, and execution metadata. Supports WINDOWS, LINUX, and MAC platforms.

Request URL

https://{serverurl}/intelligence/sensors/api/addSensor

Scope

DesktopCentralCloud.Platform.CREATECopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory
application/jsonapplication/jsonCopied!
AcceptstringMandatory
application/addSensor.v1+jsonapplication/addSensor.v1+jsonCopied!

- Request Body

application/json
JSON Object
Hide Sub-Attributes
sensorDetailsJSON ObjectOptional

Container object holding all sensor configuration details

Show Sub-Attributes
sensorNamestringOptional

Unique sensor name. Allowed characters: alphanumeric, underscore, space. Max 100 chars

descriptionstringOptional

Human-readable description of the sensor purpose. Max 500 chars

isCustomSensorbooleanOptional

true if this is a user-created custom sensor; false for built-in sensors

numberOfRunstringOptional

Number of execution runs to retain for this sensor

executionTypestringOptional

When to execute: 'ondemand' for manual trigger or 'nextSchedule' for scheduled execution

forceUpdatebooleanOptional

true to overwrite existing sensor version; false to skip if unchanged

sensorScriptDetailsJSON ArrayOptional

Array of platform-specific script definitions for the sensor

Show Sub-Attributes
JSON Object
Show Sub-Attributes
contentstringOptional

Script content or file path. Max 25000 chars

platformstringOptional

Target OS platform: WINDOWS, LINUX, or MAC (case-insensitive)

fileNamestringOptional

Script file name (e.g., collectDisk.ps1)

scriptArgsstringOptional

Command-line arguments passed to the script. Max 1000 chars

exitCodestringOptional

Comma-separated success exit codes (e.g., '0,3010'). Max 250 chars

outputVariablesJSON ArrayOptional

Array of output variable definitions (0-70 items) the sensor collects

Show Sub-Attributes
JSON Object
Show Sub-Attributes
variableNamestringOptional

Variable name (letters, numbers, and underscores only). Max 100 characters

displayNamestringOptional

User-friendly display name. Alphanumeric, underscore, space. Max 100 chars

dataTypestringOptional

Data type of the output: 1=String, 2=Integer, 3=Large Integer, 4=Decimal

defaultValuestringOptional

Default value when sensor returns no output. Max 250 chars

isPIIbooleanOptional

true if this variable contains Personally Identifiable Information

descriptionstringOptional

Purpose of this output variable. Max 500 chars

outputVariableIDlongOptional

Existing output variable ID (0 for new variables)

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/intelligence/sensors/api/addSensor \
  --header 'Accept: application/addSensor.v1+json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{}'

Sample Request Body

Create a custom disk health sensor for Windows with one output variable

Copied!
  {
    "sensorDetails": {
      "isCustomSensor": true,
      "sensorName": "Disk Health Sensor",
      "executionType": "ondemand",
      "description": "Collects disk metrics",
      "numberOfRun": 30,
      "outputVariables": [
        {
          "variableName": "diskUsage",
          "displayName": "Disk Usage",
          "defaultValue": "0",
          "dataType": 1,
          "description": "Usage percentage",
          "isPII": false,
          "outputVariableID": 0
        }
      ],
      "forceUpdate": false,
      "sensorScriptDetails": [
        {
          "scriptArgs": "--quick",
          "fileName": "collectDisk.ps1",
          "exitCode": "0,3010",
          "content": "Get-WmiObject Win32_DiskDrive | Select-Object Status",
          "platform": "WINDOWS"
        }
      ]
    }
  }
                
Show full

Response Parameters

- HTTP code 200

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

Result of the operation: 'success' on successful creation

messagestring

A confirmation message (e.g., 'Sensor Disk Health Sensor added successfully')

sensorIDstring

Unique ID of the newly created sensor

sensorVersionIDstring

Version ID of the created sensor

sensorNamestring

Name of the created sensor

- HTTP code 400

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

Error code indicating which validation failed

errorMessagestring

Details about which field failed and why

- HTTP code 401

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

Unauthorized error code: credentials missing, expired, or invalid

errorMsgstring

Authentication failure reason

- HTTP code 500

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

Error code for the server error

errorMessagestring

Details about the server error

Possible Response Codes

200HTTP code
400HTTP code
401HTTP code
500HTTP code

Sample Response: HTTP 200

Sensor created successfully

Copied!
  {
    "sensorVersionID": "67890",
    "sensorName": "Disk Health Sensor",
    "message": "Sensor Disk Health Sensor added successfully",
    "status": "success",
    "sensorID": "12345"
  }
                
Show full

Sample Response: HTTP 400

Sensor name contains invalid characters

Copied!
  {
    "errorMessage": "Sensor name contains invalid characters. Only alphanumeric, underscore and space are allowed.",
    "errorCode": "SENSOR_VALIDATION_ERROR"
  }
                
Show full

Sample Response: HTTP 401

Login credentials are missing or invalid

Copied!
  {
    "errorMessage": "Authentication required. Provide valid credentials.",
    "errorCode": "UNAUTHORIZED"
  }
                
Show full

Sample Response: HTTP 500

Server error while creating the sensor

Copied!
  {
    "errorMessage": "An internal error occurred while creating the sensor.",
    "errorCode": "INTERNAL_ERROR"
  }
                
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.