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 #

curl {BASE URL}/v1/users/registration
    -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."
  }

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
  {
    "UserName": "sallydoe@company.com",
    "Role": "Your role name",
    "Status": "Active",
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxx",
    "ApiKeyExpiration": "date"
  } 

  //response if role is (customer 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 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",
    "LastName": "Doe",
    "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 #

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

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.

Query String Parameters #

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":[],
          }
        }'

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.

Request #

curl {BASE URL}/v1/simulations/{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
    },
    "ResourceRequirementsForecast": null,
    "Calendars" : null,
    "NoSolutionGraphs": null,
    "Errors": null,
    "ValidationPassed": null,
    "ValidationResults": null,
    "Settings": null
  }

Search scenarios #

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

Query String Filter Parameters #

Query String Operation Parameters #

Request #

curl {BASE URL}/v1/simulations/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 #

curl {BASE URL}/v1/simulations/{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"
  }

Calendarize completed scenarios #

Calendarization transforms one or more successfully completed simulations from a time-series based on event intervals into a time-series based on calendar months or quarters (e.g., used for financial planning and forecasting).

When a request is for multiple scenarios, each scenario is individually calendarized and summed per selected calendar period.

Zypr provides two methods for calendarization.

1. Retrieve successfully completed scenarios (i.e., must have final state StatusNbr 7) from your saved simulation history.
2. Provide scenarios object in request.

Both methods are validated to ensure calendarization completes without errors.

Request #

//request list of scenario ids to automatically retrieve
//scenario object(s) from Zypr simulation history 

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

//request with user-provided scenario(s) resources  

curl {BASE URL}/v1/simulations/calendarize
    -X POST
    -H "Content-Type: application/json" 
    -H "x-api-key: your_api_key"  
    -d '{
          "ReportDateStart": "2023-01-01",
          "ReportDateEnd": "2025-06-30",
          "CalendarPeriod": "Month",
          "ResourceType": "All",
          "Scenarios": [
            "HardwareInventory": [],
            "SoftwareInventory": [],
            "FacilityResources": []
          ]
    }

Response object #

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

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 #

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 #

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

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 #

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

//summary list

  curl {BASE URL}/v1/pool-models/search
      -X GET
      -H "Content-Type: application/json" 
      -H "x-api-key: your_api_key"  
    
//model by id 
//   all versions if more than one exists, otherwise single 

  curl {BASE URL}/v1/pool-models/search?id=D01

//model by id and version 
  curl {BASE URL}/v1/pool-models/search?id=D01&version=1.0

Response objects #

 //list 
[
  {
      "Id" : "A01",
      "Version" : "1.0",
      "Description" : "Modify server config & performance",
      "Created" : "2022-07-01 00:00:00+0",
      "Changed" : "20222-07-01 00:00:00+0"
  },
]

//item
{
  "Id" : "A01",
  "Version" : "1.0",
  "Description" : "Modify server config & performance",
  "PoolResourceModel" : {..},
  "Created" : "2022-07-01 00:00:00+0",
  "Changed" : "20222-07-01 00:00:00+0"
}