Skip to content
On this page

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

VerbURLPurpose
POST/v1/usersNew user registration
POST/v1/users/{activationCode}/registrationVerify email address and receive API key
POST/v1/users/new-api-keyRequest new API key
POST/v1/users/{authorizationCode}/new-api-keyConfirm new API key request and receive new key
GET/v1/users/info/{emailAddress}User record
DELETE/v1/users/{emailAddress}Delete trial user

 

Simulations

VerbURLPurpose
POST/v1/simulations{query string}Create a scenario
GET/v1/simulations/{scenarioId}Scenario record
GET/v1/simulations/search?{query parameters}Search scenarios
DELETE/v1/simulations/{scenarioId}Delete a scenario

 

Accounts

VerbURLPurpose
Get/v1/accounts/{accountId}Account record
POST/v1/accounts/users/{emailAddress}/{action} Add/Remove user membership of account
Get/v1/accounts/users/{emailAddress}/infoAccount member user record
DELETE/v1/accounts/users/{emailAddress}Delete account member user

 

Utilities

VerbURLPurpose
Get/v1/contact-usGet Ravello Analytics' customer service email addresses
Get/v1/pool-models/search?{query parameters}Search pre-define pool resource models

 

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 object

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

Response object

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

Activation Code

The activation code you receive is valid for 5 days.

 

Verify email address

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

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 URL

curl {BASE URL}/v1/users/{activationCode}/registration
    -X PUT
    -H "Content-Type: application/json"
   

Response object

json
  //response if trial user
  {
    "UserName": "sallydoe@company.com",
    "Role": "Your role name",
    "Status": "Active"
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxx",
    "ApiKeyExpiration": "date"
  } 

  //response if account user
  {
    "UserName": "sallydoe@company.com",
    "Role": "Your role name",
    "Status" : "Inactive",
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxx",
    "ApiKeyExpiration": "date",
    "AccountAdminName" : "full 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 you forget your existing API key, or wish to change your existing key, you may create a new key to replace your existing key. This request does not require entering your existing API key in the request header and requires two steps to complete.

First, submit a request that contains the email address you used to register with Zypr. A change authorization code will be sent to this email address. Use the authorization code to create a new API key.

Request URL

curl {BASE URL}/v1/users/new-api-key
    -X PUT
    -H "Content-Type: application/json"
    

Response object

json
  Valid request
  {
    "An email was sent to xxxxx that contains a single-use authorization
     code to verify your request and receive a new Api Key"
  }

INFO

The change authorization code is valid for 10 minutes.

 

Confirm new API key request and receive new key

Request URL

curl {BASE URL}/v1/users/{Authorization Code}/new-api-key
    -X PUT
    -H "Content-Type: application/json"
    

Response object

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

Api Key Expiration

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.

 

User record

Any user may retrieve their own user record.

A user, with the role of 'Account Administrator', may fetch the user record of any user who is a member of the customer account.

Request URL

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

Response object

json
  {
    "UserName" : "sallydoe@company.com",
    "Status" : "Active", 
    "Role" : "Trial User", 
    "FirstName" : "Sally", 
    "LastName" : "Doe",
    "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 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 URL

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

Response object

json
  {
    "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, tool to fully define your model object and confirm it is valid JSON before attempting to run a simulation.

Query String Parameters

OperationFilter ValueDefault Value
sim-precisionnormal, highnormal
max-threads1 - 41

Simulation Precision

The parameter 'sim-precision' sets the precision level for how Zypr approximates minimum feasible future inventory transactions. Increasing the granularity of feasible transactions doesn't necessarily produce lower costs. However, for very large pools, as measured by the LotUnit property setting, it may be advantageous to increase Zypr's precision level.

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 higher server turnover rates. A 'high' precision would likely identify more granular transactions (e.g., instead remove 20 existing servers, instead identify 22 for removal), 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 feasible maximum transaction event for inventory removal would be approximately 23 rack units (i.e., 1000/42 = 22).

Maximum Threads

The parameter 'max-threads' sets the maximum number of threads Zypr is permitted to consume in parallelized execution. The higher the thread number, the faster the simulation executes. The need to run a simulation with more than one thread usually corresponds with the need for higher simulation precision.

Unless your organization has a dedicated run-time environment setup for executing simulations, maximum thread count is subject to thread availability at simulation run-time.

Request object

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

Response object

json
  {
    "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": {},
    "ResourcesForecast": {..},
    "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 ResourcesForecast 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 an in-process or completed scenario.

Request URL

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

Response object

json
  {
    "Id":"abe.aurrovcocprbr25xg2zm4",
    "StatusNbr": 6,
    "StatusDescription": "Simulator is executing",
    "SimulationStates": [],
    "Progress": {
       "Started" : true,
       "Completed" : false,
       "PercentComplete" : 78,
       "TransactionCount" : 17824,
       "SequenceCount" : 1286
    },
    "ResourcesForecast": 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.

 

Query completed scenarios

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

Query String Filter Parameters

Scenario PropertyFilter Property
StatusNbrstatus-nbr
ScenarioNamescenario-name
PoolNamepool-name
PoolIdpool-id
CreatedDatecreated-date     Matched to date part of DateTime.

Examples

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

  • Sorted oldest to newest. "{BASE URL}/v1/scenarios/list?=status-nbr=15 & sort=asc"

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

 

Query String Operation Parameters

OperationFilter ValueDefault Value
sortasc, descdesc
propa filter propertycreated-date
skipan integer >= 0
Operation invoked after filter applied.
0
takean integer >= 1
Operation invoked after filter applied.
10
counttrue
Response excludes Scenarios list
false

Examples

  • Sorted newest to oldest. "{BASE URL}/v1/scenarios/list?=status-nbr=15
  • Skip and take records. "{BASE URL}/v1/scenarios/list?=skip=8 & take=30"
  • Count records. "{BASE URL}/v1/scenarios/list?=pool-id=abc & count=true"

Request URL

curl {BASE URL}/v1/scenarios/list{query string}
    -X GET
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"

Response object (success)

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

Response object (error)

json
  {
    "The query returned an empty collection"
  }

Response object (count)

json
  {
    "Count" : 12,
  }

 

Delete a scenario

Request URL

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

Response object

json
  {
    "Scenario Id abcdef was successfully deleted"
  }

 

Customer account record

Use this endpoint to receive your organization's account information. Access to this endpoint is restricted to users with account administration priviledges.

Request object

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

Response object

json
{
  "AccountId" : "9999999",
  "Name" : "ABC Bank",
  "AccountAdministrator" : "Roberta Doe",
  "EnableAutoActiveStatus" : false,
  "SubscriptionStartDate" : "2023-04-01 00:00:00+0",
  "SubscriptionEndDate" : "2026-03-31 00:00:00+0",
  "DaysRemaining": 1095,
  "Users": [
    {
      "FirstName" : "", 
      "LastName" : "",
      "Email" : "",
      "RoleName" : "",
      "Status": "", 
    },
  ],
  "Entitlements" : [..]
}

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 object

//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

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

 

Get Ravello Analytics email addresses

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

Request object

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 objects

//summary list
curl {BASE URL}/v1/pool-models
    -X GET
    -H "Content-Type: application/json" 
    -H "x-api-key: your_api_key"  
    
//model by id - all versions 
curl {BASE URL}/v1/pool-models/{id}

//model by id by version 
curl {BASE URL}/v1/pool-models/{id}/{version}

Response objects

json
 //summary 
[
  {
      "Id" : "A01",
      "Version" : "1.0",
      "Description" : "Modify server config & performance",
  },
]

//detail
{
  "Id" : "A01",
  "Version" : "1.0",
  "Description" : "Modify server config & performance",
  "PoolResourceModel" : {..}
}

Ravello Analytics, LLC