Documentation forSolarWinds Service Desk

General Concepts

Service URL

https://api.samanage.com/

For European based customers, please use:

https://apieu.samanage.com

Formats:

You can use XML or JSON format for your request. For example:

XML

curl -H "X-Samanage-Authorization: Bearer TOKEN" -H 'Accept: application/vnd.samanage.v2.1+xml' -X GET https://api.samanage.com/incidents.xml

JSON

curl -H "X-Samanage-Authorization: Bearer TOKEN" -H 'Accept: application/vnd.samanage.v2.1+json' -H 'Content-Type: application/json' -X GET https://api.samanage.com/incidents.json

For create and update, the provided data needs to be in the correct format.

XML Example:

<incident>

<field_to_update>content</field_to_update>

</incident>

JSON Example:

{

"incident": {

"field_to_update": "content"

}

}

To clear fields, use the following format:

XML Example:

<incident>

<field_to_update></field_to_update>

</incident>

JSON Example:

{

"incident": {

"field_to_update": ""

}

}

Authentication

The API authentication is token-based. Admins can generate a token for their own user in the user setup page. That token can then be provided to the API developer in order for them to gain access to items in SolarWinds via the API. Admins can also re-generate their tokens from the user setup page, that will invalidate all previously generated tokens.

The tokens are relatively long strings that look like this: AAAZWV0YXkubmF0YW4rNUBzYW1hbmFnZS5jb20hbGciOiJIUzUxMiJ9.eyJ1c2VyX2ljIjoxMjU2OTQzLCJnZW5lcmF0ZWRfYXQiOiIyMDE3LTA2LTA3IDA5OjE3OjI5In0.j_H15qzJJr9vXGAHCThLEOQrE9GGbjMxZJOs5zAf_iqaGqxlIOAmvPpBx0td_C3r7dliAfXXIgdqhZHVoK1KTwAzd1

In order to supply the API token you should pass X-Samanage-Authorization header in the following format: “Bearer API_TOKEN_STRING”. Assuming that the token obtained in the user setup page is AAAZWV0YXkubmF0YW4rNUBzYW1hbmFnZS5jb20hbGciOiJIUzUxMiJ9.eyJ1c2VyX2ljIjoxMjU2OTQzLCJnZW5lcmF0ZWRfYXQiOiIyMDE3LTA2LTA3IDA5OjE3OjI5In0.j_H15qzJJr9vXGAHCThLEOQrE9GGbjMxZJOs5zAf_iqaGqxlIOAmvPpBx0td_C3r7dliAfXXIgdqhZHVoK1KTwAzd1 the API call looks like this:

Example:

curl -H "X-Samanage-Authorization: Bearer AAAZWV0YXkubmF0YW4rNUBzYW1hbmFnZS5jb20hbGciOiJIUzUxMiJ9.eyJ1c2VyX2ljIjoxMjU2OTQzLCJnZW5lcmF0ZWRfYXQiOiIyMDE3LTA2LTA3IDA5OjE3OjI5In0.j_H15qzJJr9vXGAHCThLEOQrE9GGbjMxZJOs5zAf_iqaGqxlIOAmvPpBx0td_C3r7dliAfXXIgdqhZHVoK1KTwAzd1" -H "Accept: application/vnd.samanage.v2.1+xml" https://api.samanage.com/hardwares.xml

If the authentication fails, a “401 Unauthorized” message will be returned.

Security

SWSD uses a secured API channel. To connect to the regional API server, use the account admin users’ token information and connect using Token-based authentication (Learn more: how to get your token) . Requests should never be transferred in plain text over the wire. Instead, use SSL version 1.2 or higher (which can be accessed using https://) to ensure that all communication with the server is encrypted and secured.

To ensure API performance and avoid denial of service, we employ API Call limits per minute that is set based on the plan of the endpoint user.

Professional package limits is set to a volume of 1000 calls per minutes while enterprise package user can reach a high volume of 1500 calls per minute.

Versioning

Clients must provide the version number they are ready to work with in the “Accept” HTTP header. A valid "Accept" header should specify current content type and version number.

For example, “application/vnd.samanage.v2.1+xml”.

When no “Accept” header is specified, the API will default to version 1.0.

If you request an API version that is no longer supported, the API will respond with an HTTP status code of “406 – Not Acceptable”.

Example:

curl -H "X-Samanage-Authorization: Bearer TOKEN" -H "Accept: application/vnd.samanage.v2.1+xml" https://api.samanage.com/hardwares.xml

Version History

  • 1.0: Deprecated

  • 1.1: Changed structure of custom_fields_values

  • 1.2: Changed name of “incident_type” to “category” in Catalog items and Incidents

  • 1.3: Updates to incidents or comments will not send an email or a notification to the users. To enable this feature you must add add_callbacks=true to the url.

  • 2.1: Token based authentication

Pagination

Every response with a large result set will be paginated. The response will include the pagination data as headers and links (formatted as <url>; rel=”relative”). For example:

X-Per-Page: 50

X-Total-Count: 3099

X-Total-Pages: 62

 

Link: <https://api.samanage.com/incidents.xml?page=1>; rel="first",

<https://api.samanage.com/incidents.xml?page=8>; rel="prev",

<https://api.samanage.com/incidents.xml?page=10>; rel="next",

<https://api.samanage.com/incidents.xml?page=62>; rel="last"

You can request a specific page by providing a “page” parameter. For example, to request the third page of the hardware list, you can use the following command:

curl -H "X-Samanage-Authorization: Bearer TOKEN" https://api.samanage.com/hardwares.xml?page=3

To control the number of rows returned, provide the per_page parameter. (You can request a maximum of 100 rows. When you make a request, the per page parameter you set will be saved until you make a new request). For example, to request 100 rows with each results page, use the following command:

curl -H "X-Samanage-Authorization: Bearer TOKEN" https://api.samanage.com/hardwares.xml?per_page=100

API Calls

Here are a few examples of supported API calls, and the corresponding responses. These examples are shown in the form of ‘curl’ commands. Curl (http://en.wikipedia.org/wiki/CURL) is a command line utility used to perform HTTP requests, and is available on most Unix systems. However, you can use any tool or language that can submit a corresponding HTTP request. Curl, in the form of libcurl, has bindings in more than 30 languages, which should provide a tool that can be used in whatever language you are working with.

Common Parameters

Every list will accept a page = parameter. The response will return those assets on the specified page.

API Entry Point

All communication with the API begins with a list of available services. Although it is possible to get to a specific service URL directly, we advise you to start with the api.xml entry point. This ensures your program will still work properly if we change the underlying URLs for services in future versions of the API.

Request

GET https://api.samanage.com/api.xml

curl -H "X-Samanage-Authorization: Bearer TOKEN" -H "Accept: application/vnd.samanage.v2.1+xml" -X GET https://api.samanage.com/api.xml

Response

<xml version="1.0" encoding="UTF-8">

<services>

<service>

<name>Computers List</name>

<href>https://api.samanage.com/hardwares.xml</href>

</service>

<service>

<name>Helpdesk Incidents List</name>

<href>https://api.samanage.com/incidents.xml</href>

</service>

<service>

<name>Risks List</name>

<href>https://api.samanage.com/risks.xml</href>

</service>

<service>

<name>Contracts List</name>

<href>https://api.samanage.com/contracts.xml</href>

</service>

<service>

<name>Software List</name>

<href>https://api.samanage.com/softwares.xml</href>

</service>

<service>

<name>Other Assets List</name>

<href>https://api.samanage.com/other_assets.xml</href>

</service>

<service>

<name>Vendors List</name>

<href>https://api.samanage.com/vendors.xml</href>

</service>

<service>

<name>Printers List</name>

<href>https://api.samanage.com/printers.xml</href>

</service>

<service>

<name>Audit Log List</name>

<href>https://api.samanage.com/audits.xml</href>

</service>

<service>

<name>Users List</name>

<href>https://api.samanage.com/users.xml</href>

</service>

<service>

<name>Problems List</name>

<href>https://api.samanage.com/problems.xml</href>

</service>

<service>

<name>Changes List</name>

<href>https://api.samanage.com/changes.xml</href>

</service>

<service>

<name>Releases List</name>

<href>https://api.samanage.com/releases.xml</href>

</service>

<service>

<name>Solutions List</name>

<href>https://api.samanage.com/solutions.xml</href>

</service>

<service>

<name>Catalog Items List</name>

<href>https://api.samanage.com/catalog_items.xml</href>

</service>

<service>

<name>Departments List</name>

<href>https://api.samanage.com/departments.xml</href>

</service>

<service>

<name>Sites List</name>

<href>https://api.samanage.com/sites.xml</href>

</service>

<service>

<name>Groups List</name>

<href>https://api.samanage.com/groups.xml</href>

</service>

<service>

<name>Mobile Devices List</name>

<href>https://api.samanage.com/mobiles.xml</href>

</service>

<service>

<name>Roles List</name>

<href>https://api.samanage.com/roles.xml</href>

</service>

<service>

<name>Categories List</name>

<href>https://api.samanage.com/categories.xml</href>

</service>

</services>

Short / long layout:

For all APIs, you can specify the layout (short / long). This affects the length of the returned records, and is relevant for changes, contracts, hardwares, incidents, other assets, problems, and solutions.

To use, add the parameter to the request: “?layout=short” or “?layout=long”. If not present, the default is “short”.

Searching:

You can search for records by using query parameters on top of the base URL. For example, when requesting a list of hardwares, you may want to limit them to only those with a specific IP address. This could be accomplished with a request like

GET https://api.samanage.com/hardwares.xml?ip_address=123.456*

Here, ip_address is a query parameter that implements a filter where the IP equals 123.456.xxx.xxx.

Other examples:

https://api.samanage.com/other_assets.xml?asset_id=XXXXXXXX

https://api.samanage.com/hardwares.xml?asset_tag=XXXXXXXX

Date formats:

The following date formats are allowed as input when updating date fields:

  • January 21, 2015

  • January 21 2015

  • Jan 21, 2015

  • Jan 21 2015

  • 21/1/2015

  • 2015/1/21

  • 21-1-2015

  • 2015-1-21

  • 21.1.2015

  • 2015.1.21

Custom fields:

To set custom fields, use the following data format:

XML Example:

<incident>

<custom_fields_values>

<custom_fields_value>

<name>field name</name>

<value>content</value>

</custom_fields_value>

<custom_fields_value>

<name>field name</name>

<value>content</value>

</custom_fields_value>

</custom_fields_values>

</incident>

JSON Example:

{

"incident": {

"custom_fields_values": {

"custom_fields_value": [{

"name": "field name",

"value": "content"

},

{

"name": "field name",

"value": "content"

}]

}

}

}