The REST API provides create, update, get, and delete operations on platform management resources. The resources are grouped in the following categories:

  • Agents and Gateways
  • Alerts
  • Automation
  • Exports
  • Integrations
  • Knowledge Base
  • Metrics
  • Monitoring
  • Patching
  • Resource Management
  • Tenancy and Access Controls
  • Tickets

View a summary of resource endpoints and operations in the next section.

The following topics describe basic REST API capabilities.

Authentication

The API supports OAuth 2.0 authentication. All API requests require authentication.

To authenticate API requests you need to provide an ID and authentication token with the request. When you set up a custom integration, providing your credentials and specifying ‘OAUTH2’ authentication, you receive:

  • tenant ID
  • key
  • secret

Use the key and secret values in the /auth/oauth/token API request to get the authentication token for subsequent API requests. The response provides the authentication token in the access_token field and the time interval for which the token is valid, in seconds, in the expires-in field.

Use the authentication token and tenant ID to authenticate subsequent API requests, passing the authentication token in the request header:

"Authorization: Bearer {authenticationToken}"

Where required, pass the tenant ID as a path parameter.

Base URL

The API fully supports domain-specific partner and client URLs.

Gateway base URL

The following endpoints are provided to interface with the Gateway appliance:

apiTokenGen
applicationservice
download/gateway/{packagename}
externalproxy
generalinfo
getntpdetails
gettimezoneinfo
networksettings
nginx
ntpmanualconfig
ntpservice
ntpsyncips
ntpupdateips
proxy
registration
restartnetwork
settimezone
staticroute

The general form of the base URL for Gateway endpoints is:

https://<GatewayIPAddress>:5480

specifying 5480 as the port number.

For example, to generate a Gateway access token, use:

https://172.26.1.244:5480/api/v2/apiTokenGen

Partners

Custom brand partners use a base URL that has the following format:

https://{partnerName}.api.opsramp.com/api

The {partnerName} part of the URL is a path parameter, which is replaced by the partner domain name. For example, the base URL for partner Alpha is: https://alpha.api.opsramp.com/api.

All other partners use the following base URL:

https://api.opsramp.com/api

Clients

The base URL for a client who uses custom branding while the partner does not use custom branding is: https://api.opsramp.com/api.

Clients and partners who both use custom branding use the client URL, which has the following format:

https://{clientName}.api.opsramp.com/api

For example, if both partner Alpha and client Acme are private-labeled, the base URL is https://acme.api.opsramp.com/api.

URL path parameters

The API documentation indicates variable URL path parameters using brackets: {pathParameter}. This permits operations on specific resources. For example, a tenant ID path parameter is represented as {tenantID}. When making an API request that requires a tenant ID to be specified, replace {tenantID} with the actual tenant ID.

Versioning

API versioning ensures application and service compatibility. All API requests include an API version specification.

The API version identifier is appended to the base URL. For example, API version v2 has the following URL format:

https://api.opsramp.com/api/v2

HTTP request header

Use the following request header fields to provide data format and authentication information:

HeaderValue
Acceptapplication/json
Content-Typeapplication/json
AuthorizationBearer {accessToken} or Basic base64_encode(loginName:password)

HTTP response header

the HTTP response header includes rate limit information for adjusting the API request frequency to accommodate performance and service changes.

HTTP HeaderDescriptionExample
X-RateLimit-LimitMaximum number of requests per minute.X-RateLimit-Limit: 500
X-RateLimit-RemainingNumber of requests remaining in the current rate limit window.X-RateLimit-Remaining: 14
X-RateLimit-ResetThe time the current rate limit window resets, in UTC epoch seconds.X-RateLimit-Reset: 1491397260

HTTP methods

The API supports the following methods:

MethodDescription
DELETERemove a resource.
GETGet resource data.
POSTModify or update a resource.
PUTCreate or overwrite a resource.

Data encoding

The API supports JSON data encoding of request and response data.

Specify JSON encoding in the HTTP header Content-Type and Accept fields.

HTTP status codes

These status codes are returned by the APIs:

StatusMessageDescription
200SuccessRequest succeeded.
400Bad RequestUnable to authenticate.
401UnauthorizedSystem or user is not authorized to use the API.
404Not foundResource was not found.
405Method not allowedHTTP method is not allowed for the resource or not supported by any resource.
407Proxy Authentication RequiredToken expired.
410GoneTenant is unavailable or deactivated.
429Too Many RequestsRequest exceeds the rate limit.
500Internal Server ErrorUnexpected condition preventing the server from completing the request.

Filtering

Where applicable, you can use the following query string parameters to filter results returned by the server. The parameters can be concatenated, as in:

https://api.opsramp.com/api/v2/tenants/msp_6/sites/search?pageNo=1&pageSize=10&isDescendingOrder=true&sortName=id&queryString=id:31+name:east-zone+parentId:30
ParameterDescriptionDefaultExample
pageNo(optional) The page to return in a multi-page document.1https://api.opsramp.com/api/v2/tenants/msp_1/resources/search?pageNo=1
pageSize(optional) Number of entries to return per page.10https://api.opsramp.com/api/v2/tenants/msp_1/resources/search?pageSize=3
isDescendingOrder(optional) List order:
true = descending order
false = ascending order
falsehttps://api.opsramp.com/api/v2/tenants/msp_1/resources/search?isDescendingOrder=true
sortName(optional) Name of field on which to sort returned data.<name>https://api.opsramp.com/api/v2/tenants/msp_6/sites/search?sortName=id
queryString(optional) Resource-specific query string.n/ahttps://api.opsramp.com/api/v2/tenants/msp_1/resources/search?queryString=agentInstalled:true+state:inactive

Rate limit

The rate limit specifies the number of requests the server accepts within a one-minute time interval. Requests that exceed the rate limit are throttled.

The following table shows partner- and client-level rate limits for the different resource categories:

API CategoryScopeGET (non-paginated)GET (paginated)POST/DELETE/PUT
AlertsPartner1500150600
Client50050200
MetricPartner150015015000
Client500505000
DevicePartner150015075
Client5005025
TicketsPartner1500150150
Client5005050
Other APIsPartner1500150150
Client5005050

A request that is rejected because it exceeds the rate limit returns a HTTP 429 Too Many Requests status code with the following error information in the response body:

{
    "error" : "throttled",
    "error_description" : "Too Many Requests"
}

Additional rate limit errors received within one minute of the first error are not processed.