API Overview

Describes all the essential properties which a user should know to optimal execution of API requests.

OpsRamp Public API's Base URL

The API fully supports domain-specific tenants (partner and client) URLs. The base URL for tenants who do not use custom branding is:

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

Custom or Privated branded URLs

Tenant with custom branding use a base URL that has the following format: https://{custom-branded-url}.api.opsramp.com/api

For example, custom-branded-url for the tenant with domain name, acme would be https://acme.api.opsramp.com/api

HTTP status codes

These status codes are returned by the APIs:

Status Message Description
200 Success Request succeeded
201 Success Resource successfully created
400 Bad Request Unable to authenticate.
401 Unauthorized System or user is not authorized to use the API.
404 Not found Resource was not found.
405 Method not allowed HTTP method is not allowed for the resource or not supported by any resource.
407 Proxy Authentication Required Token expired.
410 Gone Tenant is unavailable or deactivated.
429 Too Many Requests Request exceeds the rate limit.
500 Internal Server Error Unexpected condition preventing the server from completing the request.

Rate limits

API throttling limits the number of requests an API server accepts within a given time period. API requests are throttled to ensure a better quality of service(QoS).

OpsRamp APIs Rate limits

The following limits apply for each tenant (service provider, partner, and client) as requests per minute: The following table shows partner-level and client-level rate limits for the different resource categories:

API Category Scope GET (non-paginated) GET (paginated) POST / DELETE / PUT
Alerts Partners 1500 150 600
Alerts Client 500 50 200
Metric Partners 1500 150 15000
Metric Client 500 50 5000
Device Partners 1500 150 75
Device Client 500 50 25
Tickets Partners 1500 150 150
Tickets Client 500 50 50
Other APIs Partners 1500 150 150
Other APIs Client 500 50 50

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"
}

Once the rate limit is reached, any additional API requests will not be processed until the next reset time interval.

The API response header provides details about the API rate limit, including the current usage count, the remaining requests, and additional information such as:

  • x-ratelimit-bucket: "API_HITS:854521_28776146-alerts_write"
  • x-ratelimit-limit: "500"
  • x-ratelimit-remaining: "497"
  • x-ratelimit-reset: "1726568820"

alt text

Filtering and Pagination

Where applicable, you can use the following query string parameters to get filter results paginated on API execution.The query format and its parameters can be concatenated as exampled below.The "queryString" formulates all the input filtering parameters given by user. Multiple query parameters are seggregated by ":" and concatenated by "+"

Special Characters

There are special characters that can be used in a queryString:

  • (+) represents the next field and must be URL-encoded.
  • (:) represents equals. An example is key : value.
  • Space characters must be URL-encoded.
  • Date format must be yyyy-MM-ddTHH:mm:ssZ (GMT).
  • (,) indicates multiple values for a key. An example is alert states: CRITICAL,WARNING

Default Filtering

Based on the API endpoint functionality some of the query filters would be mandatory else by default, the query would give all the results. In case of incorrect query parameters,the endpoint results to default.

  • queryString is optional query parameter for search endpoints.
  • optional query parameters are never validated and ignored if incorrect.
  • recommended to use only correct and valid query parameters with queryString.
https://api.opsramp.com/api/v2/tenants/clientId/sites/search?pageNo=1&pageSize=10&isDescendingOrder=true&sortName=id&queryString=id:31+name:east-zone+parentId:30
https://api.opsramp.com/api/v2/tenants/clientId/sites/search?pageNo=1&pageSize=10&isDescendingOrder=true&sortName=id&queryString=states:CRITICAL,WARNING

OpsRamp API Pagination with Query Strings

BaseURL: https://api.opsramp.com/api/v2/tenants/clientId/resources

Parameter Description Default Example
pageNo (optional) The page to return in a multi-page document 1 BaseURL/search?pageNo=1
pageSize (optional) Enteries per page 10 BaseURL/search?pageSize=3
isDescendingOrder Page order listing true = descending false BaseURL/search?isDescendingOrder=true
sortName (optional) Page data sorting order by field Name Field Name BaseURL/search?sortName=id
queryString (optional) Resource-specific query string. n/a BaseURL/search?queryString=agentInstalled:true+state:inactive
2021-09-21T05:35:07.322Z