Documentation
Discover the zero configuration mode
Not found

    ServicePilot API

    The ServicePilot REST API allows you to interact with the ServicePilot interface without any special technical skills. The ServicePilot REST API allows you to:

    • Add resources/view/graphical element
    • Send data
    • Make SQL requests
    • Remove resources

    External applications and agents can interact with ServicePilot data via the REST API.

    Provisioning API

    The ServicePilot Provisioning API allows you to quickly add views, resources and graphical elements to the ServicePilot monitoring, in bulk as required.

    ServicePilot Provisioning API can add one or more resources based on the same package per request as each request consists of a URL specifying the package type and a POST body with the associated resources to include.

    To add resources with the REST API, a web request using a WRITE capable API Key is required.

    Example: Provision resources using a cURL request

    1. Obtain a WRITE capable API Key following the instructions under API Authentication Keys

    2. Prepare a CSV file called "data-prov.csv" containing the definitions of the resources to add.

      name,ip_address_fqdn
Ping-1,10.0.0.1
Ping-2,10.0.0.2
Ping-3,10.0.0.3

      Note: Only the required fields for each resource need to be specified. See the Configuration > Advanced > Packages > Questions page in ServicePilot web interface for each package for the required fields.

    3. Edit the following commands as required and execute them in a CLI

      REM Select an API key with WRITE access
set APIKEY=10000000-0000-0000-0000-000000000000

curl -X POST "https://data.servicepilot.com/api/provisioning/network-ping" -H "Content-Type: text/csv" -H "x-api-key: %APIKEY%" --data-binary @data-prov.csv

    Example: Add a hierarchy of views using a PowerShell request

    1. Obtain a WRITE capable API Key following the instructions under API Authentication Keys

    2. Prepare a CSV file called "view-prov.csv" containing the definitions of the views to add.

      name,view,autoarrange
Sites,MAIN,none
Site-1,Sites,linear
Site-2,Sites,linear

      Note: Only the name and view fields for each view need to be specified.

    3. Edit the following commands as required and execute them in a PowerShell CLI

      # Uncomment line below if HTTPS with TLS>=1.2 only
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Tls12'

# Select an API key with write access
$APIKEY="10000000-0000-0000-0000-000000000000"

Invoke-WebRequest -UseBasicParsing -Uri "https://data.servicepilot.com/api/provisioning/view" -Method "POST" -Headers @{ 'x-api-key'=$APIKEY } -ContentType "text/csv" -InFile view-prov.csv

    ServicePilot Provisioning API Definitions

    See the Configuration > Advanced > Packages > API page in ServicePilot web interface for all package definitions including all optional fields.
    1. Using a user with administrative privileges, log in to ServicePilot
    2. Open SETTINGS > Provisioning
    3. Click on the Packages sub-menu
    4. Navigate to the API tab
    5. Follow the steps under Provisioning API

    Send data APIs

    There are a number of API that can be used to insert data into ServicePilot:

    1. ServicePilot Send Data API - Insert data into monitored resources in bulk.
    2. Old ServicePilot Send Data API - Insert data into one object at a time.
    3. Add a log-syslog-receiver resource - Capture Syslog data in the ServicePilot syslog collection. Capture filters and a script can be added to ServicePilot to limit Syslogs received.
    4. Add a log-trap-receiver resource - Capture SNMP Traps in the ServicePilot trap collection. Capture filters and a script can be added to ServicePilot to limit and categorize Traps received.

    Preferably use the new Send Data API unless only one object in ServicePilot is being sent data.

    Send data API

    ServicePilot Send Data API can insert indicator data, logs and views into one or more resources, independently of the package type, in the same request as each request consists of a URL specifying the API and a POST body with the associated resources and data to inject.

    Example: Insert data into resources

    1. Obtain a WRITE capable API Key following the instructions under API Authentication Keys

    2. Prepare a CSV file called "data-send.csv" containing the resources and associated data to be inserted.

      type,object,i1
data,Ping-1,333
data,Ping-2,555
data,Ping-3,777

      Note: Only a minimum of type, object, i1, where i1 is the monitor indicator number, need to be specified. See the Configuration > Advanced > Packages > Indicators page in ServicePilot web interface for each package for the list of indicators.

    3. Edit the following commands as required and execute them in a CLI

      REM Select an API key with WRITE access
set APIKEY=10000000-0000-0000-0000-WRITE0000001

curl -X POST "https://data.servicepilot.com/api/send" -H "Content-Type: text/csv" -H "x-api-key: %APIKEY%" --data-binary @data-send.csv

    To see the data sent by API and stored in ServicePilot, connect to the ServicePilot web interface. Open MONITOR > View > ResourceName and see the values that appear in the "last" column.

    Example: Create a sub-view inside a resource view and send indicator data and log data to a new object

    1. Obtain a WRITE capable API Key following the instructions under API Authentication Keys

    2. Prepare a CSV file called "data-send.csv" containing the resources and associated data to be inserted.

      type,resname,object,class,view,parentview,ip,host,object_1,object_2,object_3,object_4,object_5,log,i1,i2
createview,myresource,,view_class,view1,myresource
data,myresource,myobject1,object_class,view1,,1.2.3.4,hostname,object constant1,,,,,,333.33,string
log,myresource,myobject1,,,,,,,,,,,objectlog message

      Note: If a view does not exist then it can be created inside an existing resource by specifying the resource name, view class, view name and parent view name. If an object does not exist then it can be created inside an existing resource by specifying the resource name, object name, object class and view name. The number of monitor object indicators and the object log format is dependent on the class of the object to which data is sent. See the SETTINGS > Configuration > Advanced > Packages > Indicators page in ServicePilot web interface for each package for the list of indicators.

    3. Edit the following commands as required and execute them in a CLI

      REM Select an API key with WRITE access
set APIKEY=10000000-0000-0000-0000-WRITE0000001

curl -X POST "https://data.servicepilot.com/api/send" -H "Content-Type: text/csv" -H "x-api-key: %APIKEY%" --data-binary @data-send.csv

    ServicePilot Send Data API Definitions

    See the Configuration > Advanced > Packages > API page in ServicePilot web interface for all package definitions including all optional fields.
    1. Using a user with administrative privileges, log in to ServicePilot
    2. Open SETTINGS > Provisioning
    3. Click on the Packages sub-menu
    4. Navigate to the API tab
    5. Follow the steps under API for sending data

    Old Send data API

    The Old ServicePilot Send Data API can insert indicator data into one object, add an object log or create a view. This API should be used sparingly when only one object is to be sent data as it is not optimized for bulk data import.

    Example: Insert indicator data into an object

    1. Obtain a WRITE capable API Key following the instructions under API Authentication Keys

    2. Send data to ServicePilot using a GET API request. Note that the URL query parameters need to be URL encoded (+ or %20 for space, %2B for +, etc)

      curl https://data.servicepilot.com/d?apikey=10000000-0000-0000-0000-000000000000&resname=compdate&v=view1&c=class&o=compdate&i1=2024-05-22+13:57:00%2B01:00
      Query parameter key Query parameter value Notes
      apikey ServicePilot write capable API Key Required
      resname Resource name Required
      o Object name Required
      c Object class name Required if the object does not yet exist
      v Object view name Required if the object does not yet exist
      p Object parent view name Only required if the object does not exist and the object view does not exist but the parent of the object view must exist. A generic intermediate view will be created.
      ip IP address of source data for the object Specify for better data categorization
      h Host name of source data for the object Specify for better data categorization and host licensing
      o1 ... o5 Object constant 1 to 5 value Optional
      i1 ... i# Object indicator data Numeric or string data for the object monitor indicators depending on the class of object
      n yes Instead of indicator data, set this parameter to yes to indicate a no-response state for the object

      Note: Only a minimum of object and i1, where i1 is the monitor indicator number, need to be specified if the object already exists. See the SETTINGS > Configuration > Advanced > Packages > Indicators page in ServicePilot web interface for each package for the list of indicators.

    Example: Insert log data into an object

    1. Obtain a WRITE capable API Key following the instructions under API Authentication Keys

    2. Send data to ServicePilot using a GET API request. Note that the URL query parameters need to be URL encoded (+ or %20 for space, %2B for +, etc)

      curl https://data.servicepilot.com/l?apikey=10000000-0000-0000-0000-000000000000&resname=compdate&v=view1&c=class&o=compdate&l=log+text%09log+text2
      Query parameter key Query parameter value Notes
      apikey ServicePilot write capable API Key Required
      resname Resource name Required
      o Object name Required
      c Object class name Required if the object does not yet exist
      v Object view name Required if the object does not yet exist
      p Object parent view name Only required if the object does not exist and the object view does not exist but the parent of the object view must exist. A generic intermediate view will be created.
      ip IP address of source data for the object Specify for better data categorization
      h Host name of source data for the object Specify for better data categorization and host licensing
      o1 ... o5 Object constant 1 to 5 value Optional
      l Log data The formatted object log data

      Note: Only a minimum of object and l need to be specified if the object already exists. The object log format is dependent on the object class.

    Example: Create a view

    1. Obtain a WRITE capable API Key following the instructions under API Authentication Keys

    2. Create a view using a GET API request. Note that the URL query parameters need to be URL encoded (+ or + for space, %2B for +, etc)

      curl https://data.servicepilot.com/cv?apikey=10000000-0000-0000-0000-000000000000&resname=compdate&c=class&v=view1&p=resname&ar=linear
      Query parameter key Query parameter value Notes
      apikey ServicePilot write capable API Key Required
      resname Resource name Required
      c View class name Required
      v View name Required
      p Parent view name Required
      posx View X position in parent view from the top Value fully divisible by 10. Optional if parent view is auto-arranged.
      posy View Y position in parent view from the left Value fully divisible by 10. Optional if parent view is auto-arranged.
      width View icon size in parent view Optional. 30 by default.
      height View icon size in parent view Optional. 30 by default.
      bg View background picture name Optional
      ar linear Set this parameter to arrange icons in a linear fashion inside the view. No arrangement by default.

    SQL Request API

    The ServicePilot SQL Request API allows you to query and extract data directly from the ServicePilot database. The simplified SQL queries can be optimized with Lucene clauses and the output format can be set to CSV or JSON in the API request.

    The SQL Select request queries one database collection depending on the required information. Each collection stores a specific kind of data. Collections either contain current/real-time data or historical records. When querying a collection with historical records, either a time span or a number of most recent records must be specified. By default only the first 10 result rows are returned.

    Collection Description Historical
    events Object and resource alarms, acknowledgments and manage events, configuration changes and user logons X
    objectstatus Last minute informations about views, objects and resources (status, acknowledgments, managements, ...)
    objectdata Object and resource indicators statistics X
    objectml Object and resource indicators machine learning - anomalies, trend & prediction X
    objectlog Object's custom log messages X
    objectrca Root cause analysis records
    objectsl Service level statistics for views and resources X
    apptrace APM requests with client and server informations (HTTP status, errors, response times, ...) X
    nettrace Nettrace conversations with client and server statistics X
    inventory Inventory of servers and endpoints
    syslog Syslog records X
    trap SNMP trap records X
    voip VoIP call records X

    Query the ServicePilot DB using SQL Requests

    1. Obtain a READ capable API Key following the instructions under API Authentication Keys
    2. Build your SQL query specifying the necessary fields and collection and insert the query in the API request URL along with a READ capable API Key

    Example: Get a list of unavailable PING objects monitored by ServicePilot

    SQL Query:

    SELECT object,status FROM objectstatus WHERE status="-" AND class="ping" ORDER BY object ASC

    API Request URL:

    https://data.servicepilot.com/api/sql?q=SELECT object,status FROM objectstatus WHERE status="-" AND class="ping" ORDER BY object ASC&apikey=10000000-0000-0000-READ-000000000002

    Example: Get a JSON formatted list of the last 100 critical alarms on resources

    SQL Query:

    SELECT timestamp,resource,view,status,info FROM events WHERE source="resource" AND status="3" ORDER BY timestamp DESC

    API Request URL:

    https://data.servicepilot.com/api/sql?q=SELECT timestamp,resource,view,status,info FROM events WHERE source="resource" AND status="3" ORDER BY timestamp DESC&rows=100&wt=JSON&apikey=10000000-0000-0000-READ-000000000002

    Example: Get the average memory usage for servers during the last 30 mins

    SQL Query:

    SELECT object,MEAN(integer4) FROM objectdata WHERE class="server system" GROUP BY object ORDER BY timestamp DESC

    API Request URL:

    https://data.servicepilot.com/api/sql?q=SELECT object,MEAN(integer4) FROM objectdata WHERE class="server system" GROUP BY object ORDER BY timestamp DESC&rows=30&apikey=10000000-0000-0000-READ-000000000002

    ServicePilot SQL Request API Definitions

    ServicePilot also offers an assistant to help you build custom SQL queries as required. Visit the Query page in ServicePilot web interface to get started:
    1. Access the ServicePilot web interface
    2. Open TOOLS > Widget
    3. Click on the Query sub-menu
    4. Create your SQL request

    See the Configuration > API page in ServicePilot web interface for additional information and syntax on the SQL Request API.
    1. Using a user with administrative privileges, log in to ServicePilot
    2. Open SETTINGS > Configuration
    3. Navigate to API

    Resource removal API

    The ServicePilot Resource Removal API allows you to quickly remove views, resources and graphical elements from the ServicePilot monitoring, in bulk as required.

    ServicePilot Resource Removal API can remove one or more resources based on the same package per request as each request consists of a URL specifying the package type and a DELETE body with the associated resources to remove.

    To remove resources with the REST API, a web request using a DELETE capable API Key is used.

    Example: Remove resources using a cURL request

    1. Obtain a DELETE capable API Key following the instructions under API Authentication Keys

    2. Prepare a CSV file called "data-delete.csv" containing the definitions of the resources to remove.

      name,view
*,View_Test
Ping-3,

    3. Edit the following commands as required and execute them in a CLI

      REM Select an API key with DELETE access
set APIKEY=10000000-0000-0000-0000-DELETE000001

curl -X DELETE "https://data.servicepilot.com/api/provisioning/network-ping" -H "Content-Type: text/csv" -H "x-api-key: %APIKEY%" --data-binary @data-delete.csv

    ServicePilot Resource Removal API Definitions

    See the Packages > API page in ServicePilot web interface for additional information.
    1. Using a user with administrative privileges, log in to ServicePilot
    2. Open SETTINGS > Provisioning
    3. Click on the Packages sub-menu
    4. Navigate to the API tab
    5. Follow the steps under Resource removal API

    API Authentication Keys

    An API key is a secret pre-shared key associated with a ServicePilot customer and used by ServicePilot agents and API users to authorize access. Different API requests will require different API Key authorization levels.

    API Requests Minimum API Key Authorization
    Add resources Write
    Send data Write
    SQL Requests Read
    Remove resources Delete

    How to obtain a ServicePilot API Key?

    The "API Keys" page allows you to manage API Keys for ServicePilot agents and the REST API. It is suggested to use an API Key dedicated to the REST interface with Read, Read & Write or Read, Write & Delete privileges depending on what access is required. If this key is compromised, it can be removed without affecting ServicePilot agent data gathering.
    1. Using a user with administrative privileges, log in to ServicePilot
    2. Open SETTINGS > Configuration
    3. Navigate to API keys
    4. Create and note down an API Key with the required authorization