API Overview


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

Gateway base URL

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


The general form of the base URL for Gateway endpoint with specifying 5480 as the port number. https://<GatewayIPAddress>:5480

For example, to generate a Gateway access token, use

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:


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.
429 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 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"

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

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 paratmers are seggregated by ":" and concatenated by "+"


OpsRamp API Pagination with Query Strings

The following table examples on pagination and preparing query strings

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