<%NUMBERING1%>.<%NUMBERING2%>.<%NUMBERING3%> PRTG Manual: Object Manipulation
You can use the following functions to manipulate existing objects (URLs are shown without username/passhash to improve readability).
Here are quick links for ease of use.
Changing Object Settings
Authentication with username and passhash (or username and password) must always be included in each PRTG API request. See section Authentication for more information.
Examples
Rename an object:
/api/rename.htm?id=objectid&value=newname
Set priority of an object (valid values for x are 1 to 5):
/api/setpriority.htm?id=objectid&prio=x
Change properties of objects:
/api/setobjectproperty.htm?id=id_of_object&name=property_name&value=new_value
This function can change most string and number properties of objects (names, numerical values, OIDs, etc.) and should be used with caution. The property_name parameter can be discerned by opening the Settings page of an object and looking at the HTML source of the INPUT fields. For example, the INPUT field for the tags of an object has the name tags_. Leave away the _ and use the rest (tags) as a value for the property_name parameter.
|
Switch Inheritance Off/On
This API call sets the "inherit" setting of objects (location, credentials, compatibility options, proxy settings, scanning interval, access rights, channel unit). In general, this works like changing properties for any other object.
Example
Replace the parameter inheritType with the name of the inheritance type:
/api/setobjectproperty.htm?id=id_of_object&name=inheritType_&value=0_or_1
This internal name must be followed by an underscore (_), in contrast to changing properties above. Use the value 0 for switching off inheritance, and 1 for switching on inheritance. For example, the inheritance type for the scanning interval setting has the name intervalgroup_; thus, this specific part in the URL is &name=intervalgroup_&value=0 (switches off inheritance for scanning interval).
This call does not work with the schedules, dependencies, and maintenance window.
|
Changing Properties of Channels
With this API call, you can change a sensor's channels settings. In general, this works like changing properties of any other object. To set channel properties via the API, you need to provide
- the ID of a sensor (parameter id)
- a subtype (channel for channels), and
- a subid (ID of the channel you want to edit).
Example: Enabling and Setting Limits for Channels
Set limits for channels:
/api/setobjectproperty.htm?id=sensorid&subtype=channel&subid=0&name=limitmaxerror&value=limitvalue
You have to set the limits for a channel before you can enable limits.
Enable limits for channels:
/api/setobjectproperty.htm?id=sensorid&subtype=channel&subid=0&name=limitmode&value=1
For example, the following API call sets the upper error limit of a channel with the ID 0 of a sensor with the ID 2970 to the value 25.
/api/setobjectproperty.htm?id=2970&subtype=channel&subid=0&name=limitmaxerror&value=25
For Toplists, you can use the subtype toplist to change the properties. When using this subtype, subid is the ID of a Toplist.
|
For a list of available channel parameters, see section Live Data.
Pausing/Resuming
Examples
Pause a sensor or object indefinitely:
/api/pause.htm?id=objectid&pausemsg=yourmessage&action=0-00
Pause a sensor or object for x minutes:
/api/pauseobjectfor.htm?id=objectid&pausemsg=yourmessage&duration=x
The pause message is optional. You can leave out the parameter &pausemsg=yourmessage if you do not want to display a message.
Pause and simulate a down status for a sensor:
/api/simulate.htm?id=objectid&action=1
Resume monitoring of a sensor or object:
/api/pause.htm?id=objectid&action=1
|
Error Handling (Acknowledge Alarm)
Example
Acknowledge a down status:
/api/acknowledgealarm.htm?id=objectid&ackmsg=yourmessage
|
Rescanning, Triggering Auto-Discovery
Examples
Scan a sensor now:
/api/scannow.htm?id=objectid
Run an auto-discovery for an object:
/api/discovernow.htm?id=objectid&template=filename
Template for auto-discovery is optional. You can leave out the parameter &template=filename to run the auto-discovery with the options defined in the object's settings.
If you use a template, provide the whole filename including file extension surrounded by double quotes and encode whitespaces, if necessary. Example: &template="Linux%20SNMP.odt"
|
Reordering Objects in the Sensor Tree
Example
Move an object in the sensor tree (x can be up, down, top, bottom):
/api/setposition.htm?id=objectid&newpos=x
|
Report-related
Example
Add a group, device, or sensor to a report:
/api/reportaddsensor.htm?id=reportid&addid=objectid
|
Notification-related
Example
Test a notification:
/api/notificationtest.htm?id=objectid
|
Adding/Deleting Objects
Adding and deleting objects in your PRTG configuration is the most complex and potentially most "dangerous" process when using the API. Keep in mind that add/delete activity is much better guided in the normal web interface with more warnings and alerts.
We recommended that you use the web interface for adding and deleting objects if possible.
Deleting Objects
API calls to the delete function immediately delete the referenced object including all subobjects, if there are any. For example, deleting a group deletes all its devices and sensors! There is no way to undo a deletion so use this function with care.
Example
Delete an object:
/api/deleteobject.htm?id=objectid&approve=1
|
Adding Objects
Adding completely new objects from scratch is not supported via the API due to the complexity of object creation and its parameters. To add new objects to PRTG, create a "master" object that will be cloned into new objects.
Examples
Duplicate a group:
/api/duplicateobject.htm?id=id_of_group_to_clone&name=new_name&targetid=id_of_target_group
Duplicate a device:
/api/duplicateobject.htm?id=id_of_device_to_clone&name=new_name&host=new_hostname_or_ip&targetid=id_of_target_group
Duplicate a sensor:
/api/duplicateobject.htm?id=id_of_sensor_to_clone&name=new_name&targetid=id_of_target_device
If the duplicateobject succeeds, the PRTG server will reply with a redirect to the URL of the new object (for example, /sensor.htm?id=1234), so your application should parse the new object ID from this URL.
When an object is cloned, it will initially be set to "paused" so you have the chance to edit parameters as desired. You must resume it with an API call afterwards.
|
Duplicating Sensors and Changing Clone Settings
The following process duplicates a sensor, changes some settings, and then starts monitoring:
Example
Duplicate the sensor (the server replies with a redirect to the new object's webpage, for example /sensor.htm?id=10214, parse id 10214 from the URL):
/api/duplicateobject.htm?id=2002&name=mynewsensor&targetid=2001
Rename the new sensor:
/api/setobjectproperty.htm?id=10214&name=name&value=anothernewname
Change the OID (in this example for an SNMP Custom sensor):
/api/setobjectproperty.htm?id=10214&name=oid&value=1.2.3.4.5.6.7
Resume monitoring for the new sensor:
/api/pause.htm?id=10214&action=1
|
Setting Geo Location
You can set the location of any object via an API call. Provide the object ID together with parameters for location and/or longitude and latitude.
If only the location parameter is given, the PRTG core server will execute the geo location lookup (this can take up to three minutes). Provide the name of the location, for example, New York. It will be shown in the Location settings, no matter the longitude/latitude.
If the longitude/latitude parameter is given, the marker in the map will be set to this position, no matter of the location parameter. Provide longitude and latitude separated by a comma, for example -73.998672,40.714728.
Example
Set the geo location of an object:
/api/setlonlat.htm?id=objectid&location=name_of_object_location&lonlat=longitude,latitude
|
More
Knowledge Base: How can I use the PRTG Application Programming Interface (API)?
Application Programming Interface (API) Definition—Topics