API Endpoints Reference

Overview

Endpoints are organized into four resources:

• Users
• Simulations
• Accounts
• Utilities

Endpoints for Users enable you to self-register with Zypr and manage your user account. The process will register you in the role of a 'trial user', which provides a time-limited period to use Zypr. If you need more time, you can reach by email to request more time. If your organization has an account with us, your Zypr account administrator can add you as an account user. This will change your role to 'user', with all the features available to organization's account.

Endpoints for Simulations let you create, retrieve, list, or delete finished simulations. Every request to run a simulation requires a pool resource model attached to the request body and receives a unique id generated by Zypr. This id identifies the scenario response object of a simulation. The scenario object reports any errors (e.g., validation of your model), simulation progress, and a resource forecast. Zypr doesn't provide a repository to store your pool model files. You, and your organization, maintain your own repository of pool models.

Endpoints for Accounts enable your organization's designated account administrator to oversee your organization's use of Zypr Your organization's account administer designates which users in your organization will have access to the set of features included in your organization's subscription.

Zypr provides two Utility endpoints. If you need to contact us, use the email endpoint to retrieve a list of our email addresses. The artifacts endpoint utility provides access to a repository that contains pre-defined pool resource models. These models are defined in the pool resource model repository and are intended to assist you with common use-cases. Each pre-defined model has a unique id. You can retrieve the complete model from the repository with this id.

Users

Verb	URL	Purpose
POST	/v1/users/registration	New user registration
POST	/v1/users/{activationCode}/registration?{query string}	Confirm new user registration
POST	/v1/users/new-api-key?{query string}	Request new API key
POST	/v1/users/{authorizationCode}/new-api-key?{query string}	Confirm request and receive new API key
GET	/v1/users/info	User record
DELETE	/v1/users/registration?{query string}	Delete trial user

 

Simulations

Verb	URL	Purpose
POST	/v1/simulations?{query string}	Create a scenario
GET	/v1/simulations/{scenarioId}?{query parameter}	Scenario record
GET	/v1/simulations/search?{query parameters}	Search scenarios
DELETE	/v1/simulations?{query string}	Delete one or more scenarios
POST	/v1/simulations/aggregate	Aggregate calendarized scenarios

 

Accounts

Verb	URL	Purpose
Get	/v1/accounts/{accountId}	Account record
POST	/v1/accounts/users/{emailAddress}/{action}	Add/Remove user membership of account
Get	/v1/accounts/users/{emailAddress}/info	Account member user record
DELETE	/v1/accounts/users?email{query string}	Delete member user account

 

Utilities

Verb	URL	Purpose
Post	/v1/utilities/sensitivity_analysis/matrix	Create a property combination matrix
Get	/v1/pool-models/search?{query string}	Search pre-define pool resource models
Get	/v1/contact-us	Get Ravello Analytics' customer service email addresses

 

New user registration

Registration is a two step process. The first step requires identifying yourself, your organization, and your organization provided email address. An email is sent to this address with an activation code. The activation code is used in the second step to verify your email address, complete your registration, and issue you an API Key.

If your organization does not already have an account to use Zypr, your user role will default to 'Trial User'.

If your organization does have an account to use Zypr, your role will default to 'User', but in an 'Inactive' status. Updating your user account to an 'Active' status is managed by your organization's 'Account Administrator'. After you successfully completed registration, your organization's account administrator is notified by email. Your organization's account administrator can now complete your user account setup and update your user account status to 'Active'.

Request

curl {BASE URL}/v1/users/registration
    -X POST
    -H "Content-Type: application/json"
    -d '{
        "FirstName": "Sally",
        "Email": "sallydoe@company.com",
        "Organization": "my company name"
       }'

Response object

  {
    "Message": "Email sent to sallydoe@company.com
                that contains your activation code."
  }

Activation Code

The activation code you receive is valid for 3 days.

 

Confirm new user registration

All users self-register. Upon verifying your email address with an activation code, a unique API key is issued. Please keep the API key private.

If your organization does not have an account setup to use Zypr, you will be setup as a trial user. If your organization has an account setup to use Zypr, the response object will include the contact information of the person your organization designated as the account administrator. The account administrator manages your user account permissions. Your API Key expiration date corresponds to your organization's subscription term. Check the status in the return object. If your status is 'Inactive', contact your account administrator. Your account administrator has not set you as a 'Named User' for your customer account.

Request

curl {BASE URL}/v1/users/{activationCode}/registration?email={emailAddress}
    -X POST
    -H "Content-Type: application/json"

Response object

  //response if role is Trial User
  {
    "Email": "sallydoe@company.com",
    "Role": "Your role name",
    "Status": "Active",
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxx",
    "ApiKeyExpiration": "date"
  } 

  //response if role is (customer account) User
  {
    "Email": "sallydoe@company.com",
    "Role": "Your role name",
    "Status" : "Inactive",
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxx",
    "ApiKeyExpiration": "date",
    "AccountAdminFirstName" : "first name",
    "AccountAdminEmail" : "xxxxxxxx"
  }

Trial User

Please note the expiration date of your API key. If you need additional time to evaluate Zypr, please reach out us. Use the Contacts Us endpoint to retrieve our contact email addresses.

 

Request new API key

If wish to change your existing API key, or forget your existing API key, you may create a new key to replace your existing key. Zypr will email you an authorization code to create a new API key using the request create

Request

curl {BASE URL}/v1/users/new-api-key?email={emailAddress}
    -X POST
    -H "Content-Type: application/json"

Response object

  {
    "An email was sent to xxxx@xxx.com that contains a single-use
     authorization code to create a new API key"
  }

 

Confirm new API key request

Use the authorization code you received by email from Zypr to receive a new Api key. If you are a trial user, the new API key will retain the same expiration date as the original key. If your organization has a Zypr account, your API key duration corresponds to your organization's subscription term.

Request

curl {BASE URL}/v1/users/{Authorization Code}/new-api-key?email={emailAddress}
    -X POST
    -H "Content-Type: application/json"

Response object

  {
    "FirstName": "Sally",
    "Role": "TrialUser",
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxx",
    "ApiKeyExpiration": "date"
  }

 

User record

Any user may retrieve their own user record.

Request

curl {BASE URL}/v1/users/info
    -X GET
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

Response object

  {
    "Email" : "sallydoe@company.com",
    "Status" : "Active", 
    "Role" : "Trial User", 
    "FirstName" : "Sally", 
    "Organization" : "your organization",
    "ApiExpirationDate" : "a date",
    "DaysRemaining" : 60
  }

Status

If your status is Inactive, the administrator for your organization's account has not registered you as a 'Named User'.

An Inactive user account has not been granted the permissions of the organization.

 

Delete trial user

If your role is 'Trial User', you may delete your own user account at any time, provided your Api Key has not expired.

If your role is 'User', that role is not authorized to delete its own user account. That permission is granted to your organization's Account Administrator.

Request

curl {BASE URL}/v1/users/registration?email={emailAddress}
    -X DELETE
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

Response object

  {
    "User sallydoe@company.com was successfully deleted"
  }

 

Create a scenario

To generate a scenario, add a PoolResourceModel object to the request body. This object is large, so the code block below contains an empty request object. Refer to the Pool Resources Model object reference for a complete description of a valid pool resource model object. Two query string parameters are available for setting simulation precision and maximum threads.

Simulations executed by a Trial User are restricted to the default parameter settings. Please reach out to us if your evaluation requirements necessitate higher simulation precision.

TIP

Because the PoolResourceModel object is large, you may find it helpful to use an online JSON tool to fully define your model and confirm it is valid JSON before attempting to run a simulation.

Query String Parameters

Operation	Purpose	Value	Default
precision	Sets precision for evaluating feasible unit volume per transaction event	normal, high	normal
threads	Sets maximum number of permitted threads	1 - 8	1
tag	Sets identifier for associating multiple scenarios to a collection	user-defined string	empty

Precision Parameter

Increasing the granularity of the solution space a simulation evaluates may produce lower total cost solutions when modeling pools prone to higher feasible unit volumes per transaction event, with respect to the selected lot unit.

For example, a pool with a 1000 servers, high service demand, a high K-ratio, with the lot unit property set to 'Server', will likely have transactions with higher feasible unit volumes to evaluate. A 'high' precision would likely identify more granularly precise unit volume per transaction event, which may result in lower total cost.

However, if the same pool had its lot unit property set to 'Rack', with a rack size of 42U, a 'normal' precision setting would likely yield the same result as a 'high' setting because the basis for determining feasible unit volumes per transaction event corresponds to 24 racks (i.e., 1000/42 = 23.8), not 1000 servers.

Request

curl {BASE URL}/v1/simulations
    -X POST
    -H "Content-Type: application/json" 
    -H "x-api-key: your_api_key"  
    -d '{                                         
          "PoolResourceModel": {                   
            "Settings": {},
            "SimulationRules": {},
            "EvolutionRules": {},
            "ValuationRules": {},
            "NewServerConfiguration": {},
            "PowerConsumptionTerms": {},
            "FacilityConsumptionTerms": {},
            "SoftwareResources":{
                "PoolSoftwareStack":[],
                "SoftwareInventoryTerms":[]
            },
            "ServerInventory":[],
            "JumpEvents":[],
            "Constraints":[]
          }
        }'

Response object

  {
    "Id":"abe.aurrovcocprbr25xg2zm4",
    "StatusNbr": 7,
    "StatusDescription": "Simulator completed",
    "Settings": {
      "ScenarioName": "My Scenario Name",
      "DataValidationCascadeMode": "Stop",
      "ModelEffectiveDate": "2023-01-01",
      "ModelStartDate": "2023-01-01",
      "ScenarioCreateDate": "2022-12-15",
      "EmailResults": true,
    },
    "SimulationStates": [..],
    "Progress": {},
    "ResourceRequirementsForecast": {..},
    "NoSolutionGraphs": null,
    "Errors": null
  }

The response is a Scenario object. The Settings object included in the submitted PoolResourceModel object has been modified by Zypr to include the highlighted properties in the code block above.

• ScenarioId property that uniquely represents each request to create a new scenario.
• ModelStartDate property that represents the starting date of the all time-series in the ResourceRequirementsForecast object.
• ScenarioRunDate property that represents the date when the scenario was created.

If a valid ModelEffectiveDate property was not included in the request Settings object, or it's left blank or null, then the ModelStartDate property will have the same date as the ScenarioRunDate property. If a valid date was included in the request Settings object for the ModelEffectiveDate property, then the ModelStartDate property will have the same date as the ModelEffectiveDate property. Zypr never modifies the ModelEffectiveDate property.

 

Scenario record

Use this endpoint to retrieve a single in-process or completed scenario. To return only the pool resource model that was used for this scenario, add the query string parameter 'prm=true' to the request url.

Request

curl {BASE URL}/v1/simulations/{Scenario Id}
    -X GET
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

Response object

  {
    "Id":"abe.aurrovcocprbr25xg2zm4",
    "StatusNbr": 6,
    "StatusDescription": "Simulator is executing",
    "SimulationStates": [],
    "Progress": {
       "Started" : true,
       "Completed" : false,
       "PercentComplete" : 78,
       "TransactionCount" : 17824,
       "SequenceCount" : 1286
    },
    "ResourceRequirementsForecast": null,
    "Calendars" : null,
    "NoSolutionGraphs": null,
    "Errors": null,
    "ValidationPassed": null,
    "ValidationResults": null,
    "Settings": null
  }

INFO

This Scenario response object shows a simulation that has proceeded to simulation state 6 and the Progress object is now reflects the most recently updated progress of the executing simulation.

The SimulationStates array contains status of states 1 to 6. On successful completion, StatusNbr property will be set to 7 and the remaining objects will be set.

If not successfully completed, the StatusNbr property value would correspond to a error code corresponding to the detail contained in the Errors object.

 

Search scenarios

Use this endpoint, along with query string filters and operations, to search scenarios.

Request

curl {BASE URL}/v1/simulations/search
    -X GET
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

Response object (success)

This the default response object, which contains a list of scenario summary records.

  {
    "Count" : 1,
    [
      {
        "Id" : "abe.aurrovcocprbr25xg2zm4",
        "CreatedDate" : "2023-01-15 10:16:36 +0",
        "ModelEffectiveDate": "2023-01-01 14:24:36 +0",
        "StatusNbr" : 7,
        "StatusDescription": "Simulation successfully completed",
        "ScenarioName": "My scenario name",
        "PoolName": "My resource pool name",
        "PoolId": "A02",
        "CreatedBy": "xxxxxxxxxxxxxx",
      }
    ]
  }

Response object (error)

Http status code 404 (not found) returned.

  {
    "The query returned an empty collection"
  }

Response object (count)

  {
    "Count" : 12,
  }

Search Query String Filter Parameters

Scenario Property	Notes	Filter Property
StatusNbr	Choose status nbr 7 to retrieve only successfully completed scenarios	status-nbr
ScenarioName		scenario-name
PoolName		pool-name
PoolId		pool-id
Tag	A successful search for a tag value requires having set the tag value, in the query string, on the simulation request endpoint	tag
CreatedDate	Matches only to date part of scenario created date. Filter property value must be in YYYY-MM-DD format only.	created-date

Examples

• Find all scenarios with status nbr 15. "{BASE URL}/v1/simulations/search?=status-nbr=15"

• Find all scenarios by pool id with status nbr 7. "{BASE URL}/v1/simulations/search?=pool-id=abc&status-nbr=7" (i.e., Both properties need to be true to return the record)

 

Search Query String Operation Parameters

Operation	Notes	Filter Value	Default Value
count	Response is only a Count. Omits lists for Scenario and Scenario Summary objects.	true	false
scenario-output	Response produces a list of Scenario objects. The default setting response produces a list of Scenario Summary objects.	true	false
next	Keyset form of pagination	datetime	NA

Search Pagination

A search query will limit the number of records returned in a single request due to a scenario's large payload size. Therefore the default search query returns a limit of 20 scenario summary records, not the entire scenario object. This provides a faster response time when attempting to narrow the scope of your search.

Selecting the query parameter "scenario-output=true" returns a limit of 5 records containing complete Scenario objects.

To ensure your search is complete, your query script will need to iteratively "page" for all of the records available per your query parameters.

Zypr uses keyset pagination. The keyset property is the requested date of a simulation that produced a scenario. The keyset sort order is descending. Therefore, iterative paging descends from the most recent simulation request date to the oldest.

Seed the initial next value to a future value (e.g., DateTime.Max constant). The next keyset value is found in returned records. Select the record with the oldest requested date and reset the keyset value to that date. Execute another search request with the new keyset value. Continue until the returned record count is less than 10 or matches the expected count of records.

If you have any questions, please contact us.

 

Delete one or more scenarios

Use this endpoint to delete a scenario, or delete a collection of scenarios using the Tag property. A tag value must have been defined when creating a simulation.

Request

//single scenario
curl {BASE URL}/v1/simulations?id={Scenario Id}
    -X DELETE
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

//multiple scenarios
curl {BASE URL}/v1/simulations?tag={Tag}
    -X DELETE
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

Response object

//single scenario
  {
    "Scenario Id fe.abcdef was successfully deleted"
  }

//multiple scenarios
  {
    "243 scenarios were successfully deleted";"
  }

Request

curl {BASE URL}/v1/simulations?tag={Tag}
    -X DELETE
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

Response object

  {
    "243 scenarios were successfully deleted";"
  }

 

Aggregate scenarios

Use this endpoint to aggregate multiple scenarios. All aggregate functions are performed on the CalendarizedForecast object. For each scenario included in the ScenarioIds array, the following are check:

1. The scenario exists and successfully completed with status number 7.
2. A valid CalendarizedForecast object exist for each scenario.
3. Each scenario's forecast period falls within the specified ReportDateStart and ReportDateEnd values.

Request

curl {BASE URL}/v1/simulations/aggregate
    -X POST
    -H "Content-Type: application/json" 
    -H "x-api-key: your_api_key"  
    -d '{
          "ReportDateStart": "2023-01-01",
          "ReportDateEnd": "2025-06-30",
          "ResourceType": "All",
          "AggregateFunction": "Sum",
          "ScenarioIds": []
        }'

Response object

{
    "ReportDateStart": "2023-01-01",
    "ReportDateEnd": "2025-06-30",
    "ResourceType": "All",
    "AggregateFunction": "Sum",
    "HardwareInventory": [
      {
        "IntervalNbr": 0,
        "ReportPeriod": "2023-01",
        "ServerQtyStart": 262,
        "ServerQtyEnd": 262,
        "ProcessorQtyStart": 262,
        "ProcessorQtyEnd": 262,
        "CoreQtyStart": 16768,
        "CoreQtyEnd": 16768
      },
    ],
    "SoftwareInventory": [..],
    "FacilityResources": [..],
    "ErrorMessage": ""
}

 

Create property combination matrix

Use this endpoint to generate a matrix representing the feasible property combinations to aide in performing sensitivity analyses. Please note, this endpoint does not execute the sensitivity analysis.

The request for this endpoint includes a SensitivityAnalysisModel object in the body of the request, which is composed of a 'baseline' PoolResourceModel object (i.e., the target model) and a SensitivityModel object (i.e., the target properties to test sensitivities). Please refer to the Sensitivity Analysis Model page for more details.

Request

curl {BASE URL}/v1/accounts/{id}
    -X POST
    -H "Content-Type: application/json" 
    -H "x-api-key: your_api_key"  
    -d '{                                         
          "PoolResourceModel": {},
          "SensitivityModel": []
        }'

Response object

[
  {
    "Key": "1.1,2.1",
    "Value": [
      {
        "FullPath": "JumpEvents[1].TriggerTime",
        "PropertyValue": 1.5
      },
      {
        "FullPath": "JumpEvents[0].TriggerTime", 
        "PropertyValue": 1.5
      },
      {
        "FullPath": "JumpEvents[1].PerformanceJumpPercent",
        "PropertyValue": 88.6
      }
    ]
  },
]

 

Add or remove user membership of customer account

Use this endpoint to add or remove a user as a member (i.e., named user) of an account. Adding sets the user status to 'Active' and grants the user priviledges of the account. Removing a user from an account suspends those priviledges and sets the member's user account to 'Inactive'.

Only a user with administrator priviledges can execute this endpoint.

Request

//add a user to an account
curl {BASE URL}/v1/accounts/{account id}/users/{user email address}/add
    -X GET
    -H "Content-Type: application/json" 
    -H "x-api-key: your_api_key"  

//remove a user from an account
curl {BASE URL}/v1/accounts/{account id}/users/{user email address}/remove
    -X GET
    -H "Content-Type: application/json" 
    -H "x-api-key: your_api_key"

Response object

  {
    "Mary was added to account xxxxx for ACME Inc."
  }

 

Account user record

Enables the designated account administrator for an organization to retrieve individual user records.

Request

curl {BASE URL}/v1/accounts/users/{emailAddress}/info
    -X GET
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

Response object

  {
    "Email" : "sallydoe@company.com",
    "Status" : "Active", 
    "Role" : "Trial User", 
    "FirstName" : "Sally", 
    "Organization" : "your organization",
    "ApiExpirationDate" : "a date",
    "DaysRemaining" : 60
  }

 

Delete account user

Deletes user's account and any saved scenarios.

Request

curl {BASE URL}/v1/accounts/users/?email={emailAddress}
    -X DELETE
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

Response object

  {
    "User sallydoe@company.com was successfully deleted"
  }

 

Get Ravello Analytics email addresses

Use the command below to find the right email address to connect with us.

Request

curl {BASE URL}/v1/email/contact-us
    -X GET
    -H "Content-Type: application/json" 
    -H "x-api-key: your_api_key"

Response object

The response object is a list of contact email addresses.

 

Sample models repository

To retrieve a summary list of sample pool models, use the following command.

Request

// returns list of all available starter models 

  curl {BASE URL}/v1/pool-models/search
      -X GET
      -H "Content-Type: application/json" 
      -H "x-api-key: your_api_key"  
    
// returns a specific starter pool resource model 
  
  curl {BASE URL}/v1/pool-models/search?code=D01&version=1.0

Response objects

 //list 
[
  {
      "Code" : "A01",
      "Version" : "1.0",
      "Description" : "Modify server config & performance",
  },
]

//a specific pool resource model
{
  "Settings": {},
  "SimulationRules": {},
  "EvolutionRules": {},
  "ValuationRules": {},
  "NewServerConfiguration": {},
  "PowerConsumptionTerms": {},
  "FacilityConsumptionTerms": {},
  "SoftwareResources":{
      "PoolSoftwareStack":[],
      "SoftwareInventoryTerms":[]
  },
  "ServerInventory":[],
  "JumpEvents":[],
  "Constraints":[]
}