Skip to content
On this page

API Reference Overview


The Zypr API is organized around HTTP REST using JSON as the wire format for requests and responses. It uses standard HTTP response codes, authentication, and verbs.

The base URL for Zypr is:


The Zypr API uses an API key in the request header to authenticate requests. You do not need to provide a password. Authentication failure will return 401 response code. All API requests must be made over HTTPS. Calls made over plain HTTP will return 403 response code.

A unique API key is issued per named user within an organization. Your API key permits certain permissions within your organization. Please keep your key secure. Do not share your API key in publicly accessible areas.

Rate limiting

To promote stability of Zypr, the endpoint for executing a simulation is rate limited. Sending too many requests to the endpoint will result in a 429 response code.

Job status reporting

Executing a simulation is a long-running job. The precise length of time to complete a simulation is influenced by many factors and is not easily determined in advance. A request to execute a simulation involves a series of steps which Zypr reports.

The state of each step is reported in the JobStates array object of the Scenario response object. The most recent step is reported on the StatusNbr and StatusDescription properties of the Scenario response object.


Zypr uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Zypr's servers. A 400 Bad Request error indicates a data input error, which also includes validation of the PoolResourceModel object.

The Errors object of the Scenario response object provides information about the nature of the error.


HTTP response codes
200OKEverything worked as expected.
400Bad RequestRequest failed input validation.
401UnauthorizedAPI Key not provided or API Key provided is not valid.
403ForbiddenRequest failed to use HTTPS.
429Too Many RequestsRate limit has been exceeded.


Executing simulations may involve large, complex models to describe a target environment. Such models are prone to validation errors. When attempting to execute a simulation, Zypr will attempt to validate the entire model before initiating the simulation engine. The Scenario response object includes an Errors object that provides further details about the nature of the error.

Additionally, models that include constraints may cause no feasible solution. The NoSolutionGraphs object in the Scenario response object identifies when that outcome occurs with feedback as to root cause.


Correlation Id

Every API request is issued a correlation identifier. You can find this value in the response headers under x-correlation-id. If you have a problem, referring to this value will be helpful in resolving your issue.

Scenario Id

A scenario identifier is created when the POST request of the Simulation Management endpoint is invoked. This Id is found in the Scenario response object. You use the scenario id to query the status of a running simulation and retrieve its results.

Define a model

A simulation uses the JSON object, PoolResourcesModel, to define the characteristics of pool along with rules, events, and constraints that govern how resource consumption evolves on a forward-looking basis. The PoolResourcesModel object is composed of eleven objects to define a pool:

Run a simulation

To run a simulation, add the PoolResourcesModel object to the request body as indicated in the code block below. Because a simulation may take several seconds to minutes to complete, all simulation requests are managed as an "on-demand job" and executed by a background service.

The Scenario response object includes a Zypr generated scenario id that is used to further query the job state.

curl {BASE URL}/scenarios
    -X POST
    -H "X-ApiKey: f9d75247-5098-4319-b8fa-685e1e2b9992"
    -H "Content-Type: application/json"
    -d '{ PoolResourcesModel: {..} }'

Check simulation status

The Scenario response object returns the current state of a simulation. pr generated scenario id. The scenario id is used to further query the status of the job, such as:

curl {BASE URL}/scenarios/{Scenario Id}/scenario
    -X GET 
    -H "X-ApiKey: f9d75247-5098-4319-b8fa-685e1e2b9992"
    -H "Content-Type: application/json"

Alternatively, the completed job can be delivered by email by setting the EmailResult property to true in the Settings object in the PoolResourcesModel object.

Receive a completed scenario

After a successful completion of the job, the Scenario response object will include the ResourcesForecast object, comprising:

Ravello Analytics, LLC