PRTG Manual: Object Manipulation

You can use the following functions to manipulate objects (URLs are shown without user name or passhash to enhance readability).

In this section:

Changing Object Settings

i_round_redAuthentication with API key or user name and passhash (or user name and password) must always be included in each PRTG API request. See section HTTP API for more information.

i_speechExamples

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

i_round_redThis function can change most string and number properties of objects (names, numeric values, object identifiers (OID), etc.). Use it with caution. You can discern the property_name parameter 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 underscore _ and use tags as a value for the property_name parameter.

Supported Object Types for rename.htm

rename.htm supports the following object types:

  • group
  • device
  • sensor
  • map
  • report
  • library
  • notification template
  • schedule
  • user
  • user group

rename.htm does not support other object types.

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.

i_speechExample

Replace the parameter inheritType with the name of the inheritance type:

/api/setobjectproperty.htm?id=id_of_object&name=inheritType_&value=0_or_1

i_round_redThis 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).

i_round_redThis call does not work with the Schedules, Dependencies, and Maintenance Window settings.

Changing Properties of Channels

With this API call, you can change a sensor's channel settings. In general, this works like changing properties of any other object. To set channel properties via the PRTG API, you need to provide

  • the ID of a sensor (parameter id),
  • a subtype (channel for channels), and
  • a subid (ID of the channel that you want to edit).

i_speechExample: Enabling and Setting Limits for Channels

Set limits for channels:

/api/setobjectproperty.htm?id=sensorid&subtype=channel&subid=0&name=limitmaxerror&value=limitvalue

i_round_blueYou must 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

i_round_blueFor Toplists, you can use the subtype toplist to change the properties. When using this subtype, subid is the ID of a Toplist.

i_square_cyanFor a list of available channel parameters, see section Single Object Property.

Pausing/Resuming

i_speechExamples

Pause a sensor or object indefinitely:

/api/pause.htm?id=objectid&pausemsg=yourmessage&action=0

Pause a sensor or object for x minutes:

/api/pauseobjectfor.htm?id=objectid&pausemsg=yourmessage&duration=x

i_round_blueThe pause message is optional. You can leave out the parameter &pausemsg=yourmessage if you do not want to display a message.

Simulate an error for a sensor:

/api/simulate.htm?id=objectid&action=1

i_round_bluesimulate.htm only works for sensors in the Up, Warning, Unusual, or Unknown status.

Resume monitoring of a sensor or object:

/api/pause.htm?id=objectid&action=1

Supported Object Types for pause.htm

pause.htm supports the following object types:

  • probe
  • group
  • device
  • sensor
  • notification
  • user account

pause.htm does not support other object types.

Error Handling (Acknowledge Alarm)

i_speechExample

Acknowledge the Down status:

/api/acknowledgealarm.htm?id=objectid&ackmsg=yourmessage

Rescanning, Triggering Auto-Discovery

i_speechExamples

Scan a sensor now:

/api/scannow.htm?id=objectid

Run an auto-discovery for a group or device:

/api/discovernow.htm?id=objectid&template=filename

i_round_blueProviding a device 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 file name including file extension surrounded by double quotation marks (") and encode whitespaces, if necessary. Example: &template="Linux%20SNMP.odt"

i_round_bluediscovernow.htm overrides the Auto-Discovery setting of the target group or device. If it is set to No auto-discovery, it automatically changes to Standard auto-discovery (default).

Reordering Objects in the Sensor Tree

i_speechExample

Move an object in the sensor tree (x can be up, down, top, bottom):

/api/setposition.htm?id=objectid&newpos=x

Report-related

i_speechExample

Add a group, device, or sensor to a report:

/api/reportaddsensor.htm?id=reportid&addid=objectid

Notification-related

i_speechExample

Trigger a notification immediately for testing purposes:

/api/notificationtest.htm?id=objectid

/api/notificationtest.json?id=objectid

i_round_blueobjectid is the ID of the notification template.

Adding/Deleting Objects

Adding and deleting objects in your configuration is the most complex and potentially most critical process when using the PRTG API. Keep in mind that adding or deleting objects is much better guided in the normal PRTG web interface with more warnings and alerts.

i_round_redWe recommend that you use the PRTG web interface for adding and deleting objects, if possible.

Deleting Objects

i_round_redAPI 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.

i_speechExample

Delete an object:

/api/deleteobject.htm?id=objectid&approve=1

Adding Objects

Adding completely new objects from scratch is not supported via the PRTG API because of the complexity of object creation and its parameters. To add new objects to PRTG, create a "master" object that is cloned into new objects.

Supported Object Types for duplicateobject.htm

duplicateobject.htm supports the following object types:

  • group
  • device
  • sensor
  • report
  • library
  • map
  • notification template

duplicateobject.htm does not support other object types.

i_speechExamples

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

Duplicate a library:

/api/duplicateobject.htm?id=id_of_library_to_clone&name=new_name

Duplicate a notification template:

/api/duplicateobject.htm?id=id_of_notification_template_to_clone&name=new_name

i_round_blueIf duplicateobject succeeds, the PRTG core server replies 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.

i_round_redWhen a group, device, or sensor is cloned, it is initially set to Paused so you have the chance to edit parameters as desired. You must resume it with an API call afterward.

i_round_blueThe API calls for duplicating reports, maps, libraries, and notification templates do not require a targetid.

Duplicating Sensors and Changing Clone Settings

The following process duplicates a sensor, changes some settings, and then starts monitoring:

i_speechExample

Duplicate the sensor (the server replies with a redirect to the new object's web page, 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=newname

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 specified, the PRTG core server executes the geo location lookup (this can take up to three minutes). Provide the name of the location, for example, New York. It is shown in the Location settings, no matter the longitude or latitude.

If the longitude and latitude parameter is specified, the marker in the map is set to this position, no matter of the location parameter. Provide longitude and latitude separated by a comma, for example -73.998672,40.714728.

i_speechExample

Set the geo location of an object:

/api/setlonlat.htm?id=objectid&location=name_of_object_location&lonlat=longitude,latitude

More

i_square_blueKNOWLEDGE BASE

How can I use the PRTG Application Programming Interface (API)?