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 > View editor
3. Click on the Packages sub-menu
4. Navigate to the API tab
5. Follow the steps under Provisioning API

Send data API

The ServicePilot Send Data API allows you to insert data into monitored resources, in bulk as required.

ServicePilot Send Data API can insert data 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 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
   

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 > View editor
3. Click on the Packages sub-menu
4. Navigate to the API tab
5. Follow the steps under API for sending data

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.

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 > View editor
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.

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