RESTful API Quick Start Guide

About

The RESTful API serves as a pivotal component within the integration framework for SevOne solutions. Representational State Transfer, or REST, is fundamentally an architectural style, characterized by a set of principles for the backend implementation of RESTful APIs. A key principle is statelessness, which means the system does not depend on a temporary state to ensure caching and routing of requests to less loaded appliances.

While the principles for RESTful API design from the user's perspective are not as rigidly defined, there are numerous approaches, guidelines, and best practices for designing such APIs. These are crucial for delivering a robust and user-friendly RESTful API across diverse teams and departments. Adherence to established standards and uniform design fosters better collaboration among development teams, expert labs, support, and customers.

SevOne's RESTful API adheres to the Swagger specification for API documentation. This allows users to access SevOne API Documentation and execute operations related to SevOne NMS data via the Swagger User Interface. This document aims to guide users on how to effectively utilize the Swagger User Interface in conjunction with SevOne APIs.

Administration
Alerts
AuthService
ClusterManager
ClusterOrchestrator
Data
DeviceGroups
Devices
DeviceTypes
Discovery
Docs
Flow
Health
Hotpatches
Icons
Indicators
MaintenanceWindows
Metadata
MetadataAdmin
ObjectGroups
Objects
Peers
Permissions
Plugins
Policies
Polling
Proxies
Roles
SDBConfigs
Solutions
Statistics
Support
TopNViews
Topology
Traps
Users
Utils
Webhooks
Workhours

Prerequisites

Edit online

A valid account in SevOne NMS is required.

Note: For information about RESTful API and SevOne NMS port requirements, please refer to SevOne Best Practices Guide - Cluster, Peer, and HSA guide for details.

To access API documents from SevOne NMS, launch the user interface by entering the URL from a browser of your choice.

Example: Launch SevOne NMS


http://<PAS hostname or IP address>

Click the Administration menu and select API Docs > Version 3.

Example: URL for Version 3


http://<PAS hostname or IP address>/api/v3/docs

If you are logged in, you are in the Swagger User Interface. The authentication token is not required as X-AUTH-TOKEN field is automatically filled with the token.

HTTP

Edit online

Contains the following topics.

Methods
Headers

HTTP methods, including GET, POST, PUT, PATCH, and DELETE, function to communicate the intended action to the server regarding a particular resource. In contrast, HTTP headers offer supplementary information pertaining to the request or response, incorporating elements such as content type or authentication specifics.

Methods

Edit online

The available HTTP methods are,

GET - retrieves data from the server.
POST - get / create a new resource on the server.
PUT - replace an existing resource with the provided data.
DELETE - removes a resource from the server.
PATCH - partially modifies an existing resource.

Headers

Edit online

HTTP provides a diverse array of headers, each with a specific purpose as outlined in the HTTP specification. These headers serve to convey metadata about the request itself and to clarify the communication between the API consumer and provider. They are not utilized to convey information about the content of the communication.

Common uses of HTTP headers include authorization of tokens or roles, specifying the format of the request or response, and more. For instance, the Content-Type header might be set to application/json to indicate that the request body is in JSON format, while the Accept header could be set to the same value to indicate that the client expects a JSON response.

In the context of RESTful APIs, all dates are expressed in UNIX timestamps in milliseconds, also known as Epoch Time multiplied by 1000. For example, the timestamp 1743119894000 corresponds to Thursday, March 27, 2025, 19:58:14 GMT-0400 (Eastern Daylight Time).

This convention applies universally across all RESTful API calls, regardless of whether the date is provided as a query parameter, a Data Transfer Protocol (DTP) property, or within a HTTP method or request/response body. There are no exceptions to this standard.

Endpoints

Edit online

An endpoint serves as a unique URL identifier for a singular instance or a collection of instances of the same category within a RESTful API. The type of instance, often denoted by an identifier like an ID, should be straightforward and unambiguous. Essentially, any abstract entity that can be conceptualized within the context of your domain can be considered a resource. The endpoint is established through a mutual comprehension of the domain between the API provider and consumer.

Examples of such instances include, but are not limited to, alerts, devices, objects, users, and more. Each of these represents a distinct resource that can be accessed, manipulated, or interacted with via the defined endpoint in the RESTful API. This mutual understanding ensures seamless communication and interaction between the API provider and consumer, facilitating efficient data exchange and system integration.

Example: Endpoints for single resources

/api/v3/alerts/{id} lists the alert with the given id.
/api/v3/devicegroups/{id} lists the device groups with the given id.
/api/v3/devices/{deviceId}/object/{objectId} lists the device with the given deviceId containing object with given objectId.

Example: Endpoints for a collection of resources

/api/v3/alerts lists all alerts.
/api/v3/devicegroups lists all device groups.
/api/devices/{deviceId}/objects lists a collection of all objects for the device with the given deviceId.
/api/v3/devicegroups/{id}/members/{deviceId} lists all members with the given deviceId in a device group with the given id.

Data Transfer Objects (DTOs)

Edit online

Data Transfer Objects, or DTOs, facilitates the transfer of structured data between the provider and consumer of a RESTful API. At present, the API is equipped to handle data exclusively in JSON format. This means that all data exchanged between the API provider and consumer must be formatted as JSON, ensuring a standardized and consistent method of data transmission. This approach simplifies data handling and interpretation, promoting seamless integration and communication between different systems.

Example# 1 - POST /api/v3/users/signin

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9eyJpc3MiOiJhZG1pbiJ9QEh4zafDHfd2XQLm5aEEhXqdh8rU0G0IW0E_ZsQ4Gt5mkQv-nZhEBX7UR0BT_akEPDAMzForLELRsX_ovpmerg" -d "{
  \"password\": \"<SevOne NMS appliance password>\",
  \"username\": \"<SevOne NMS username>\"
}" "http://9.42.110.16:15272/api/v3/users/signin"

Request URL

http://9.42.110.16:15272/api/v3/users/signin

Response Body


{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsic29hIl0sImV4cCI6MTc0MzEwNzUzNS45NzM2NjQsImp0aSI6ImZlNzkzOGRjLTgxYmYtNGFlNS05ZjU5LWE0ZDE5ODFmYzU2MSIsImlhdCI6MTc0MzEwNTczNS45NzM2NjQsImlzcyI6Im5tcyIsIm5iZiI6MTc0MzEwNTczNS45NzM2NjQsInN1YiI6IjEiLCJVc2VyIjp7ImFjdGl2ZSI6dHJ1ZSwiZGF0ZV9mb3JtYXQiOiIlZSAlYiAnJXkgJUg6JU06JVMiLCJmaXJzdF9uYW1lIjoiU2V2IiwiaWQiOjEsImxhc3RfbmFtZSI6Ik9uZSIsInJvbGVzIjpbMiwzXSwidGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwidXNlcm5hbWUiOiJhZG1pbiJ9LCJEZXB0aCI6MH0.wh00NSCUxa-UeDEZfEFUp_nlK1jppD0JQeDFP72Znho",
  "user": {
    "active": true,
    "dateFormat": "%e %b '%y %H:%M:%S",
    "email": "",
    "firstName": "Sev",
    "id": "1",
    "lastName": "One",
    "roles": [
      "2",
      "3"
    ],
    "timezone": "America/New_York",
    "username": "admin"
  }
}

Response Code 200 indicates success.

Example# 2 - POST /api/v3/alerts

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9eyJpc3MiOiJhZG1pbiJ9-vyyy5HzlY0spSzcOLaYsMxHazXKix_Gltn0n3l-9d7ZZDrDJyNuuvodSAVWg4MrafXSH7YaK_vQUzLOzEabBw" -d "{}" "http://9.42.110.16:15272/api/v3/alerts"

Request URL


http://9.42.110.16:15272/api/v3/alerts

Response Body


{
  "alerts": [
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "1",
      "messageText": "Trap received from 127.0.0.1: SNMPv2-MIB::coldStart -- Bindings: SNMPv2-MIB::snmpTrapEnterprise = 0 -- The device was powered up.",
      "occurrences": "3",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    },
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "2",
      "messageText": "Trap received from 127.0.0.1: IF-MIB::linkUp -- Bindings: RFC1213-MIB::ifIndex.2 = 2, RFC1213-MIB::ifAdminStatus.2 = 1, RFC1213-MIB::ifOperStatus.2 = 1, SNMPv2-MIB::snmpTrapEnterprise.0 = .1.3.6.1.4.1.8072.3.2.10, SNMPv2-MIB::snmpTrapEnterprise = 0 -- An interface has come back up.",
      "occurrences": "6",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    },
    ...
    ...
    ...
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": {
        "altName": "",
        "description": "DEFERRED Device",
        "displayName": "DEFERREDDevice 2",
        "id": "37",
        "ip": "127.0.0.1",
        "name": "DEFERREDDevice 2",
        "object": null
      },
      "endTime": "1743107009",
      "infoDevice": {
        "allowDelete": true,
        "altName": "",
        "dateAdded": "1712562042",
        "deleted": false,
        "description": "DEFERRED Device",
        "displayName": "DEFERREDDevice 2",
        "elements": "1",
        "id": "37",
        "ip": "127.0.0.1",
        "name": "DEFERREDDevice 2",
        "new": false,
        "lastDiscovery": "1712562169",
        "peerId": "1",
        "pollFrequency": "300",
        "timeZone": "America/New_York",
        "workHoursGroupId": "1"
      },
      "id": "54",
      "messageText": "Trap received from DEFERREDDevice 2: SNMPv2-MIB::authenticationFailure -- Bindings: SNMPv2-MIB::snmpTrapEnterprise = 0 -- An authentication failure has occurred.",
      "occurrences": "19948",
      "startTime": "1743044847",
      "severity": "WARNING",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    }
  ],
  "endTime": "1743107009",
  "startTime": "1691618263",
  "partialResults": null
}

Response Code 200 indicates success.

Example# 3 - GET /api/v3/devicegroups

Curl


curl -X GET --header "Accept: application/json" --header "X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9eyJpc3MiOiJhZG1pbiJ9E54Aa409QHqyWvkUSGxFl21bifSszSPyR9wLVKVz1ksxwJJOgaHbOqyiBMlg5O8R42E_kHHCiCu7uNDAqgka0Q" "http://9.42.110.16:15272/api/v3/devicegroups"

Request URL


http://9.42.110.16:15272/api/v3/devicegroups

Response Body


{
  "content": [
    {
      "name": "All Device Groups",
      "parentId": "1",
      "id": "2",
      "devices": []
    },
    {
      "name": "Location",
      "parentId": "2",
      "id": "3",
      "devices": []
    },
    {
      "name": "Type",
      "parentId": "2",
      "id": "4",
      "devices": []
    },
    {
      "name": "Router",
      "parentId": "4",
      "id": "6",
      "devices": []
    },
    {
      "name": "Switch",
      "parentId": "4",
      "id": "7",
      "devices": []
    },
    {
      "name": "Server",
      "parentId": "4",
      "id": "8",
      "devices": []
    },
    {
      "name": "SevOneNMS Appliance",
      "parentId": "4",
      "id": "9",
      "devices": []
    },
    {
      "name": "Unclassified",
      "parentId": "2",
      "id": "10",
      "devices": []
    },
    {
      "name": "Manufacturer",
      "parentId": "2",
      "id": "11",
      "devices": []
    },
    {
      "name": "SevOne",
      "parentId": "11",
      "id": "12",
      "devices": []
    },
    {
      "name": "Cisco",
      "parentId": "11",
      "id": "13",
      "devices": []
    },
    {
      "name": "Juniper",
      "parentId": "11",
      "id": "14",
      "devices": []
    },
    {
      "name": "Huawei",
      "parentId": "11",
      "id": "16",
      "devices": []
    },
    {
      "name": "Extreme",
      "parentId": "11",
      "id": "17",
      "devices": []
    },
    {
      "name": "F5",
      "parentId": "11",
      "id": "18",
      "devices": []
    },
    {
      "name": "HP",
      "parentId": "11",
      "id": "19",
      "devices": []
    },
    {
      "name": "Dell",
      "parentId": "11",
      "id": "20",
      "devices": []
    },
    {
      "name": "EMC",
      "parentId": "11",
      "id": "21",
      "devices": []
    },
    {
      "name": "NetApp",
      "parentId": "11",
      "id": "22",
      "devices": []
    },
    {
      "name": "Brocade",
      "parentId": "11",
      "id": "23",
      "devices": []
    }
  ],
  "pageNumber": 0,
  "pageSize": 20,
  "totalPages": "4",
  "totalElements": "61"
}

where,

totalElements is the count of the resources that is returned if there is no paging.

pageSize is the number of resources returned in the request. This is corresponding to the size query argument.

pageNumber is the current page number. This is corresponding to the page query argument. The returned elements start at element at index (pageNumber * pageSize).

Response Code 200 indicates success.

Note: In the context of RESTful APIs, a common convention is to associate one DTO with each unique resource type, identifiable by its URL. However, it is essential to recognize that this widely adopted pattern is not an inflexible, unyielding rule.

RESTful API services are engineered with composability as a core principle, allowing services to be combined in myriad ways to achieve intricate workflows and scenarios. This design philosophy necessitates that DTOs are crafted with a focus on generality and reusability. It is crucial to ensure that your DTOs are versatile, adaptable, and capable of being repurposed across various use cases. This approach not only promotes efficient data handling but also fosters seamless system integration, thereby enhancing overall functionality and flexibility.

Filtering, Sorting, & Rate Limits

Edit online

Contains the following topics.

Filtering
Sorting
Rate Limits

Filtering

Edit online

To retrieve filtered data, the endpoint incorporates the keyword filter at the conclusion of the request. These filter endpoints are exclusively utilized for reading resources and are not equipped to modify any data on the server. Given that a Data Transfer Object (DTO) must be transmitted, these operations are executed via the POST method. It is important to note that these requests do not induce any changes in the system's state, ensuring data integrity and consistency.

Example# 1: POST /api/v3/devicegroups/filter

In this example, let's filter by deviceId.

restApiFilter

Under Parameters, add {"deviceId": "1"} in body. This will return all device groups which contain deviceId = 1. Please see the Response Body below for the output.

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9eyJpc3MiOiJhZG1pbiJ9hruaPFtWySta7KKvraDfdgi8t-_VT4veH9xRfOS8P74koZqs3tODR95bVe3bMCEe_zBGWBK_tZwufG7Vg1uA_w" -d "{\"deviceId\": \"1\"}" "http://9.42.110.16:15272/api/v3/devicegroups/filter"

Request URL


http://9.42.110.16:15272/api/v3/devicegroups/filter

Response Body


{
  "content": [
    {
      "name": "All Device Groups",
      "parentId": "1",
      "id": "2"
    },
    {
      "name": "IP",
      "parentId": "2",
      "id": "24"
    },
    {
      "name": "IPv4",
      "parentId": "24",
      "id": "25"
    },
    {
      "name": "Class A",
      "parentId": "24",
      "id": "27"
    },
    {
      "name": "Special",
      "parentId": "2",
      "id": "40"
    },
    {
      "name": "All Devices",
      "parentId": "40",
      "id": "41"
    }
  ],
  "pageNumber": 0,
  "pageSize": 20,
  "totalPages": "0",
  "totalElements": "6"
}

This indicates that there are 6 total elements found which have deviceId = 1.

Response Code

200 indicates success.

Example# 2: POST /api/v3/plugins/filter

Choose queryType FULL from the drop-down and it returns the list of available plugins as shown in the table below.


Plugin ID	Plugin Name
1	SNMP Poller
2	ICMP Poller
3	Process Poller
4	HTTP Poller
5	Proxy Ping Poller
6	NBAR Poller
7	Portshaker Poller
8	DNS Poller
9	IP SLA Poller
10	Deferred Data
11	WMI Poller
15	VMware Poller
16	Web Status Poller
17	xStats
18	MySQL Database Poller
20	Calculation Poller
24	AWS
25	SDWAN
26	Azure
27	SDN
29	Wi-Fi
30	GCP

Curl


curl -X GET --header "Accept: application/json" --header "X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9eyJpc3MiOiJhZG1pbiJ9kqoCxkBpEZMePETB02qcm7aRc8w-CEdyv0KsjDyGs-rMQ8vy55MZohqpJzw3ikxeD0zotZA2iRwTBrPh0bVWPQ" "http://9.42.110.16:15272/api/v3/plugins/filter?queryType=FULL"

Request URL


http://9.42.110.16:15272/api/v3/plugins/filter?queryType=FULL

Response Body


{
  "workingPlugins": {
    "plugins": [
      {
        "pluginId": "1",
        "pluginName": "SNMP Poller",
        "deviceCount": "14"
      },
      {
        "pluginId": "2",
        "pluginName": "ICMP Poller",
        "deviceCount": "7"
      },
      {
        "pluginId": "3",
        "pluginName": "Process Poller",
        "deviceCount": "6"
      },
      {
        "pluginId": "4",
        "pluginName": "HTTP Poller",
        "deviceCount": "2"
      },
      {
        "pluginId": "5",
        "pluginName": "Proxy Ping Poller",
        "deviceCount": "2"
      },
      ...
      ...
      ...
      {
        "pluginId": "29",
        "pluginName": "Wi-Fi",
        "deviceCount": "0"
      },
      {
        "pluginId": "30",
        "pluginName": "GCP",
        "deviceCount": "0"
      }
    ],
    "pluginCount": "22"
  }

This indicates that there are 22 plugins available.

Response Code

200 indicates success.

Sorting

Edit online

Example: POST /api/v3/metadata/devices

In this example, the process of sorting the output is demonstrated. The sorting is based on two criteria: direction (ascending or descending) and field. The field options span a variety of attributes, such as alternate name, data added, description, display name, id, IP address, last discovery, name, number of objects, peer id, poll frequency, and timezone. This sorting mechanism enables a customized and tailored presentation of data, accommodating specific user requirements and preferences.

restApiSort

Under Parameters, add "sorts" variable in body as shown in the screenshot above. This will return all devices sorted in ascending order based on the device's display name. Please see the Response Body below for the output.

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9eyJpc3MiOiJhZG1pbiJ9hruaPFtWySta7KKvraDfdgi8t-_VT4veH9xRfOS8P74koZqs3tODR95bVe3bMCEe_zBGWBK_tZwufG7Vg1uA_w" -d "{
  \"sorts\": [
    {
      \"direction\": \"DIRECTION_ASCENDING\",
      \"field\": \"FIELD_DISPLAY_NAME\"
    }
  ]
}" "http://9.42.110.16:15272/api/v3/metadata/devices"

Request URL


http://9.42.110.16:15272/api/v3/metadata/devices

Response Body


{
  "devices": [
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562041",
      "deleted": false,
      "description": "BULKDATA Device",
      "displayName": "BULKDATADevice 1",
      "elements": "0",
      "id": "15",
      "ip": "127.0.0.1",
      "name": "BULKDATADevice 1",
      "new": false,
      "lastDiscovery": "1712562145",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562042",
      "deleted": false,
      "description": "BULKDATA Device",
      "displayName": "BULKDATADevice 2",
      "elements": "0",
      "id": "45",
      "ip": "::1",
      "name": "BULKDATADevice 2",
      "new": false,
      "lastDiscovery": "1712562155",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562041",
      "deleted": false,
      "description": "COC Device",
      "displayName": "COCDevice 1",
      "elements": "1",
      "id": "17",
      "ip": "127.0.0.1",
      "name": "COCDevice 1",
      "new": false,
      "lastDiscovery": "1712562163",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562042",
      "deleted": false,
      "description": "COC Device",
      "displayName": "COCDevice 2",
      "elements": "1",
      "id": "49",
      "ip": "::1",
      "name": "COCDevice 2",
      "new": false,
      "lastDiscovery": "1712562171",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562041",
      "deleted": false,
      "description": "DEFERRED Device",
      "displayName": "DEFERREDDevice 1",
      "elements": "1",
      "id": "11",
      "ip": "127.0.0.1",
      "name": "DEFERREDDevice 1",
      "new": false,
      "lastDiscovery": "1712562161",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    ...
    ...
    ...
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562042",
      "deleted": false,
      "description": "WMI Device",
      "displayName": "WMIDevice 2",
      "elements": "11",
      "id": "39",
      "ip": "10.129.20.1",
      "name": "WMIDevice 2",
      "new": false,
      "lastDiscovery": "1712562152",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    }
  ]
}

The Response Body yields a listing of devices, organized and presented by their Display Name. This output is arranged in an ascending order, facilitating a systematic and structured review of the data.

Rate Limits

Edit online

When dealing with extensive data outputs, the API provides a mechanism to cap the data volume according to the user's specified limit. This functionality empowers users to handle and interpret large datasets more effectively, ensuring they only access and review the data that is relevant to their requirements.

Example: POST /api/v3/alerts

restApiRateLimits

Under Parameters, add "pagination" variable with the amount of data you want to limit it to, in body as shown in the screenshot above. Since the limit is set to 3, it will return 3 alerts. Please see the Response Body below for the output.

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9eyJpc3MiOiJhZG1pbiJ9kqoCxkBpEZMePETB02qcm7aRc8w-CEdyv0KsjDyGs-rMQ8vy55MZohqpJzw3ikxeD0zotZA2iRwTBrPh0bVWPQ" -d "{
  \"pagination\": {
    \"limit\": \"3\"
  }
}" "http://9.42.110.16:15272/api/v3/alerts"

Request URL


http://9.42.110.16:15272/api/v3/alerts

Response Body


{
  "alerts": [
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "1",
      "messageText": "Trap received from 127.0.0.1: SNMPv2-MIB::coldStart -- Bindings: SNMPv2-MIB::snmpTrapEnterprise = 0 -- The device was powered up.",
      "occurrences": "3",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    },
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "2",
      "messageText": "Trap received from 127.0.0.1: IF-MIB::linkUp -- Bindings: RFC1213-MIB::ifIndex.2 = 2, RFC1213-MIB::ifAdminStatus.2 = 1, RFC1213-MIB::ifOperStatus.2 = 1, SNMPv2-MIB::snmpTrapEnterprise.0 = .1.3.6.1.4.1.8072.3.2.10, SNMPv2-MIB::snmpTrapEnterprise = 0 -- An interface has come back up.",
      "occurrences": "6",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    },
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "3",
      "messageText": "Trap received from 127.0.0.1: IF-MIB::linkDown -- Bindings: RFC1213-MIB::ifIndex.3 = 3, RFC1213-MIB::ifAdminStatus.3 = 1, RFC1213-MIB::ifOperStatus.3 = 2, SNMPv2-MIB::snmpTrapEnterprise.0 = .1.3.6.1.4.1.8072.3.2.10, SNMPv2-MIB::snmpTrapEnterprise = 0 -- An interface has gone down.",
      "occurrences": "3",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    }
  ],
  "endTime": "1708097859",
  "startTime": "1691618263",
  "partialResults": null
}

Upon examining the Response Body, it becomes evident that it encompasses three separate alerts. A key indicator of this is the presence of the variable messageText, which denotes the existence of three instances of this variable within the output. i.e.,

SNMPv2-MIB::coldStart
IF-MIB::linkUp
IF-MIB::linkDown

Response Code

200 indicates success.

Troubleshooting

Edit online

Contains the following topic.

HTTP Status Codes

Following the execution of an operation, the Response Code section will display an HTTP status code, serving as an indicator of the operation's status. For instance, a status code of 200 signifies a successful operation. In the event of an operation failure, the Response Body field may provide details about the encountered issue.

The subsequent screenshot exemplifies an error that arises when attempting to perform an operation without prior authentication. The pertinent HTTP status code in this scenario is 401, accompanied by the description "Unauthorized". In such cases, supplementary information regarding the error is provided following "detail":.

HTTP Status Codes

Edit online

The following table enumerates the HTTP status codes that are returned upon the execution of RESTful API requests.

Note: For the complete list of HTTP status codes, please refer to HTTP status codes.


HTTP Status Code	Description
200 (OK)	Request is executed successfully.
201 (Created)	Request is executed successfully and new resource is created in the system.
204 (No Content)	Request is executed successfully but no content is returned. It is used on all DELETE requests in RESTful API.
400 (Bad Request)	Server is unable to process the request due to something that is perceived to be a client error. For example, malformed request syntax, invalid request message framing, or deceptive request routing.
401 (Unauthorized)	Request is not executed because it lacks a valid authentication credentials for the target resource.
403 (Forbidden)	Request is executed with a valid credentials that are not significant to gain access to the resources.
404 (Not Found)	The resource requested is not found. For example, Wrong URI requested Request to add device in device group, but the device group is not found
409 (Conflict)	The resource could not be created/updated due to a conflict with the current state of the target resource. For example, request to create a new device, but device with that name already exists in the system
422 (Unprocessable Entity)	Missing required element in the request.
424 (Failed Dependency)	External system is not executed successfully. For example, RESTful API executes the NMS script which fails.
500 (Internal Server Error)	Server encounters an unexpected condition that prevents it from fulfilling the request.
503 (Service Unavailable)	Server is unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.