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 #

Simulations #

Accounts #

Utilities #

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 #

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

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 #

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

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 #

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

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 #

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

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 #

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

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 #

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

Query String Parameters #

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 #

  {
    "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 #

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

Query completed scenarios #

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

Query String Filter Parameters #

Query String Operation Parameters #

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) #

  {
    "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) #

  {
    "The query returned an empty collection"
  }

Response object (count) #

  {
    "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 #

  {
    "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 #

{
  "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 #

  {
    "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 #

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

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