API

Integrate Apidae into your code and products

Apidae provides a web-based API for accessing our tools programatically. To get started, contact us at support@buildlab.net.

Introduction


Getting started

Apidae provides a RESTful API to use our tools programatically and integrate them into your projects and products. To get started using the API, create an user account and contact us at support@buildlab.net to obtain an API token.


HTTP endpoints

The API consists of a series of HTTP endpoints, following most RESTful conventions, and returning JSON-based responses. Endpoints dealing with reading and retrieving information accept the GET request method. Endpoints dealing with creating or mutating resources accept the POST request method. The API does not currently support PUT or DELETE requests.

Most POST endpoints accept JSON-based request bodies. However, some endpoints deal with uploading file data and require request bodies consisting of multi-part form data.

HTTP API endpoints are accessible from https://apidaelabs.com.


Websocket events

Since some API endpoints trigger long-running processes (i.e. running EnergyPlus simulations), the API includes a websocket interface, where the results of long-running tasks are emitted to listening websocket connections.

Since the websocket protocol upgrades the standard HTTP connection, websockets allow for socket connections without dealing with firewall restrictions and port forwarding, as might be expected with TCP socket connections. In addition, the event-based design pattern eliminates the need for long HTTP requests, saving client and server-side resources.

Websocket events emit stringified UTF-8 encoded JSON to clients. Clients are responsible for parsing message payloads.

Apidae provides a separate websocket server dedicated to API usage at wss://apidaelabs.com:8484. Please note that this server is using a separate dedicated port number which must be included in connection urls.


Creating websocket session

In order to connect HTTP requests to the resulting websocket events they trigger, the Apidae API uses the concept of websocket sessions. After connecting to the websocket server, a websocket client creates a websocket session and receives a unique token used to identify the websocket connection. By including this session token in any HTTP requests, websocket events will be sent to the clients connection.

After connecting to wss://apidaelabs.com:8484, send the following message as stringified JSON:

{
  "event": "/uuid"
}

Any time that a websocket client sends this type of message, a new unique session token is generated and any previous session token will no longer be valid

Once this message is received on the server, the websocket connection will be provided a new unique session token. The client will receive a websocket message including its session token in the following format:

{
  "uuid": "session token"
}

Accelerator


Running model simulation

Running a model simulation using Accelerator involves uploading an IDF and EPW file and listening for websocket events indicating that the model simulation has completed.

Start by making a POST request to /accelerator/model/run.json. Since this endpoint involves uploading files, requests must be multipart/form-data, including the following:

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="email"

[email address of API user]
--AaB03x
Content-Disposition: form-data; name="token"

[API token of API user]
--AaB03x
Content-Disposition: form-data; name="websocket"

[websocket session token (websocket events for this simulation will be sent to this socket) ]
--AaB03x
Content-Disposition: form-data; name="idf"; filename="[idf_file_name.idf]"
Content-Type: text/plain

[contents of IDF file (UTF-8 encoded) ]
--AaB03x--
Content-Disposition: form-data; name="epw"; filename="[epw_file_name.epw]"
Content-Type: text/plain

[contents of EPW file (UTF-8 encoded) ]
--AaB03x--
Content-Disposition: form-data; name="run_standard"

[true or false (run standard simulation through EnergyPlus - optional - default: true) ]
--AaB03x--
Content-Disposition: form-data; name="run_fast"

[true or false (run fast simulation through Apidae EnergyPlus - optional - default: true) ]
--AaB03x--

By default, each Accelerator simulation runs model files through a standard version of EnergyPlus and a faster simulation through Apidae EnergyPlus. Note that the optional run_standard and run_fast parameters can be included in the HTTP request, with value false, to skip running the standard or fast simulation.

The HTTP endpoint will return with a JSON response:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "model_uuid": "unique identifier assigned to this model"
  }
}

If the request was successful, the model simulation(s) will be queued and executed in the order received. Note that simulations are queued based on user rate limits and resource availability.

When a simulation completes, a message of stringified JSON will be sent to the websocket client identified by the token supplied in the websocket parameter of the request:

{
  "event": "/accelerator/study/complete"
, "model_space_uuid": "unique identifier of model (compare to UUID received from HTTP response)"
, "type": "type of simulation (standard or fast)"
, "status": {
    "state": "valid or failed (was simulation completed successfully)"
  }
, "message": "if simulation failed, more information is included in this message"
, "results_url": "URL where result file can be accessed (if simulation was valid)"
}

By default, each Accelerator run includes two simulations (standard and fast), and two websocket messages will be sent when each simulation completes. If only one simulation speed is specified, only one websocket message will be sent when this simulation completes.


Getting model results

To retrieve the status and any result file URLs for an Accelerator model, send a GET request to /accelerator/model/[unique model identifier]/read.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "result_files": [
      "URLs for any result files from completed simulations for this model"
      ...
    ]
  , "status": {
      "state": "valid or failed (was simulation completed successfully)"
    , "message": "if simulation failed, more information is included in this message"
    }
  }
}

Listing model statuses

To retrieve the results and statuses for all Accelerator models for an user's account, send a GET request to /accelerator/model/list.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "each model will be listed, by identifier, as a key in this object": {
      "result_files": [
        "URLs for any result files from completed simulations for this model"
        ...
      ]
    , "status": {
        "state": "valid or failed (was simulation completed successfully)"
      , "message": "if simulation failed, more information is included in this message"
      }
    }
    ...
  }
}

Influence


Importing model

Importing a model for use with Influence involves uploading an IDF and EPW file and listening for websocket events indicating that the model import has completed. The import process involves surveying all possible inputs and outputs to use in configuring Influence simulations.

Start by making a POST request to /influence/model/create.json. Since this endpoint involves uploading files, requests must be multipart/form-data, including the following:

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="email"

[email address of API user]
--AaB03x
Content-Disposition: form-data; name="token"

[API token of API user]
--AaB03x
Content-Disposition: form-data; name="websocket"

[websocket session token (websocket events for this import will be sent to this socket) ]
--AaB03x
Content-Disposition: form-data; name="idf"; filename="[idf_file_name.idf]"
Content-Type: text/plain

[contents of IDF file (UTF-8 encoded) ]
--AaB03x--
Content-Disposition: form-data; name="epw"; filename="[epw_file_name.epw]"
Content-Type: text/plain

[contents of EPW file (UTF-8 encoded) ]
--AaB03x--

The HTTP endpoint will return with a JSON response:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "model_uuid": "unique identifier assigned to this model"
  }
}

If the request was successful, the model import will be queued and executed in the order received. Note that simulations are queued based on user rate limits and resource availability.

When the import completes, a message of stringified JSON will be sent to the websocket client identified by the token supplied in the websocket parameter of the request:

{
  "event": "/influence/model/create/complete"
, "model_space_uuid": "unique identifier of model (compare to UUID received from HTTP response)"
, "status": {
    "state": "valid or failed (was import completed successfully)"
  }
, "message": "if import failed, more information is included in this message"
}

Getting model inputs

After importing model files into Influence, your IDF is converted to JSON and valid inputs are identified. These inputs can be used as parameters for your Influence simulations of this model. Each input is assigned a unique identifier and includes information needed to use it as a parameter.

To retrieve the JSON of your model's IDF, make a GET request to /influence/model/[unique model identifier]/inputs/read.json

{
  "error": "error message (blank if request was successful)"
, "data": {
    //array of IDF objects
    "idf": [
      {
        //array of properties (fields) for IDF object
        "properties": [
          {
            "uuid": "unique identifier for input (needed to use as parameter)"
          , "label": "..."
          , "value": "..."
            ...
          }
          ...
        ]
      }
    ]
    //hash of IDD entries that apply to IDF objects
  , "idd": {
      "IDD object" {
         //array of properties for IDD object
        "properties": [
          {
            "datatype": "..."
          , "default": "..."
          , "label": "..."
          , "units": "..."
            ...
          }
          ...
        ]
      }
    }
  }
}

Getting model outputs

After importing model files into Influence, valid EnergyPlus outputs are surveyed and identified. These outputs can be used as parameters for your Influence simulations of this model. Each output is assigned a unique identifier and includes information needed to use it as a parameter.

To retrieve the JSON of your model's outputs, make a GET request to /influence/model/[unique model identifier]/outputs/read.json

{
  "error": "error message (blank if request was successful)"
, "data": [
    //array of output objects
    {
      "uuid": "unique identifier for output (needed to use as parameter)"
    , "label": "..."
    , "data_source": "..."
    , "data_type": "..."
    , "object": "..."
    , "units": "..."
    , "variable_name": "..."
      ...
    }
    ...
  ]
}

Getting model settings

Influence models store their settings in a JSON document which can be read and modified using the API. The model settings include input and output parameters, and other information used in running simulations with Influence.

To retrieve the model's settings, make a GET request to /influence/model/[unique model identifier]/settings/read.json

{
  "error": "error message (blank if request was successful)"
, "data": [
    //JSON document of model settings
    {
      ...
      //array of objects representing input parameters
      "parameters": [
        {
          "dynamic_argument": {
            "min": minimum value to simulate
          , "max": maximum value to simulate
          , "count": number of steps to simulate between min and max
          , "type": "linear"
          }
        , "dynamic_argument_default": default value of input
        , "label": "human-readable label for this parameter"
        , "script_name": "idf_modify_field_on_uuid_target_list"
        , "static_arguments": {
            "targets": [
              "unique identifier for input (refer to inputs endpoint for this value)"
            ]
          }
        , "units": "units type for this input"
        , "uuid": "a unique identifier for this input parameter"
        }
        ...
      ]
      //array of objects representing output parameters - most values are derived from the output specified (refer to outputs endpoint)
    , "report_dictionary": [
        {
          "data_source": "data_source of output"
        , "data_type": "data_type of output"
        , "label": "label of this output"
        , "object": "object of output"
        , "units": "units type for this output"
        , "variable_name": "variable_name for this output"
        , "uuid": "a unique identifier for this output parameter"
        }
        ...
      ]
      //array of objects representing the analysis functions to be performed on output parameters (entries in the report_dictionary) during simulations
    , "fitness_functions": [
        {
          "fitness_function_type": "type of fitness function to be used (Sum, Maximum, Average, or Minimum)"
        , "label": "human-readable label for this fitness function"
        , "simulated_report_dictionary_uuid": "unique identifier from the report_dictionary array of the output parameter used with this fitness function"
        , "uuid": "a unique identifier for this fitness function"
        }
        ...
      ]
      ...
    }
    ...
  ]
}

Updating model settings

To modify the settings of an Influence model, new JSON is sent through a POST request to

To retrieve the model's settings, make a GET request to /influence/model/[unique model identifier]/settings/update.json. parameters, report_dictionary, and fitness_functions arrays can be updated using this endpoint:

{
  "email": "API user email"
, "token": "API access token"
, "parameters": [] //refer to parameters array from settings read endpoint
, "report_dictionary": [] //refer to report_dictionary array from settings read endpoint
, "fitness_functions": [] //refer to fitness_functions array from settings read endpoint
}

Note that any existing model settings will be overwritten, not updated.


Validating model settings

Influence models can be validated for errors in their settings by making a GET request to /influence/model/[unique model identifier]/calculate.json:

{
  "email": "API user email"
, "token": "API access token"
}

This endpoint will return an error if there is a problem with the model's current settings. If the model's settings are valid, this endpoint will return information on the number of simulations to be run, and user limits for usage with Influence:

{
  "error": "error message if validation error occurred"
, "data": {
    "simulations": total number of simulations that will be run for this model
  , "concurrency": concurrency rate that this model will be simulated at
  , "rate_limit": number of models that can be simulated by this user at once
  , "max_simulations": maximum number of model simulations that can be run by this user (-1 means unlimited)
  , "max_study_simulations": maximum number of simulations this user can run for any model
  }
}

Running model simulation

Once a model has been configured, its simulation can be run by making a POST request to /influence/model/[unique model identifer]/run.json. Since this endpoint involves websocket events, it requires passing a websocket session token along with email and API token for authentication:

{
  "email": "API user email"
, "token": "API access token"
, "websocket": "websocket session token"
}

The HTTP endpoint will return with a JSON response:

{
  "error": "error message (blank if request was successful)"
}

Before queuing the simulation, the model settings will be validated, and if invalid, an error will be returned and the simulation will not be run. If the request was successful, the model simulation(s) will be queued and executed in the order received. Note that simulations are queued based on user rate limits and resource availability.

When a simulation completes, a message of stringified JSON will be sent to the websocket client identified by the token supplied in the websocket parameter of the request:

{
  "event": "/influence/study/complete"
, "model_space_uuid": "unique identifier of model (compare to UUID received from HTTP response)"
, "status": {
    "state": "valid or failed (was simulation completed successfully)"
  }
, "message": "if simulation failed, more information is included in this message"
, "results_url": "URL where result file can be accessed (if simulation was valid)"
}

Getting model results

To retrieve the status and any result file URLs for an Influence model, send a GET request to /influence/model/[unique model identifier]/read.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "result_files": [
      "URLs for any result files from completed simulations for this model"
      ...
    ]
  , "status": {
      "state": "valid or failed (was simulation completed successfully)"
    , "message": "if simulation failed, more information is included in this message"
    }
  }
}

Listing model statuses

To retrieve the results and statuses for all Influence models for an user's account, send a GET request to /influence/model/list.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "each model will be listed, by identifier, as a key in this object": {
      "result_files": [
        "URLs for any result files from completed simulations for this model"
        ...
      ]
    , "status": {
        "state": "valid or failed (was simulation completed successfully)"
      , "message": "if simulation failed, more information is included in this message"
      }
    }
    ...
  }
}

Factors


Importing model

Importing a model for use with Factors involves uploading an IDF and EPW file and listening for websocket events indicating that the model import has completed. The import process involves surveying all possible inputs and outputs to use in configuring Factors simulations.

Start by making a POST request to /factors/model/create.json. Since this endpoint involves uploading files, requests must be multipart/form-data, including the following:

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="email"

[email address of API user]
--AaB03x
Content-Disposition: form-data; name="token"

[API token of API user]
--AaB03x
Content-Disposition: form-data; name="websocket"

[websocket session token (websocket events for this import will be sent to this socket) ]
--AaB03x
Content-Disposition: form-data; name="idf"; filename="[idf_file_name.idf]"
Content-Type: text/plain

[contents of IDF file (UTF-8 encoded) ]
--AaB03x--
Content-Disposition: form-data; name="epw"; filename="[epw_file_name.epw]"
Content-Type: text/plain

[contents of EPW file (UTF-8 encoded) ]
--AaB03x--

The HTTP endpoint will return with a JSON response:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "model_uuid": "unique identifier assigned to this model"
  }
}

If the request was successful, the model import will be queued and executed in the order received. Note that simulations are queued based on user rate limits and resource availability.

When the import completes, a message of stringified JSON will be sent to the websocket client identified by the token supplied in the websocket parameter of the request:

{
  "event": "/factors/model/create/complete"
, "model_space_uuid": "unique identifier of model (compare to UUID received from HTTP response)"
, "status": {
    "state": "valid or failed (was import completed successfully)"
  }
, "message": "if import failed, more information is included in this message"
}

Getting model inputs

After importing model files into Factors, your IDF is converted to JSON and valid inputs are identified. These inputs can be used as parameters for your Factors simulations of this model. Each input is assigned a unique identifier and includes information needed to use it as a parameter.

To retrieve the JSON of your model's IDF, make a GET request to /factors/model/[unique model identifier]/inputs/read.json

{
  "error": "error message (blank if request was successful)"
, "data": {
    //array of IDF objects
    "idf": [
      {
        //array of properties (fields) for IDF object
        "properties": [
          {
            "uuid": "unique identifier for input (needed to use as parameter)"
          , "label": "..."
          , "value": "..."
            ...
          }
          ...
        ]
      }
    ]
    //hash of IDD entries that apply to IDF objects
  , "idd": {
      "IDD object" {
         //array of properties for IDD object
        "properties": [
          {
            "datatype": "..."
          , "default": "..."
          , "label": "..."
          , "units": "..."
            ...
          }
          ...
        ]
      }
    }
  }
}

Getting model outputs

After importing model files into Factors, valid EnergyPlus outputs are surveyed and identified. These outputs can be used as parameters for your Factors simulations of this model. Each output is assigned a unique identifier and includes information needed to use it as a parameter.

To retrieve the JSON of your model's outputs, make a GET request to /factors/model/[unique model identifier]/outputs/read.json

{
  "error": "error message (blank if request was successful)"
, "data": [
    //array of output objects
    {
      "uuid": "unique identifier for output (needed to use as parameter)"
    , "label": "..."
    , "data_source": "..."
    , "data_type": "..."
    , "object": "..."
    , "units": "..."
    , "variable_name": "..."
      ...
    }
    ...
  ]
}

Getting model settings

Factors models store their settings in a JSON document which can be read and modified using the API. The model settings include input and output parameters, and other information used in running simulations with Factors.

To retrieve the model's settings, make a GET request to /factors/model/[unique model identifier]/settings/read.json

{
  "error": "error message (blank if request was successful)"
, "data": [
    //JSON document of model settings
    {
      ...
      //array of objects representing input parameters
      "parameters": [
        {
          "dynamic_argument": {
            "min": minimum value to simulate
          , "max": maximum value to simulate
          , "count": number of steps to simulate between min and max
          , "type": "linear"
          }
        , "dynamic_argument_default": default value of input
        , "label": "human-readable label for this parameter"
        , "script_name": "idf_modify_field_on_uuid_target_list"
        , "static_arguments": {
            "targets": [
              "unique identifier for input (refer to inputs endpoint for this value)"
            ]
          }
        , "units": "units type for this input"
        , "uuid": "a unique identifier for this input parameter"
        }
        ...
      ]
      //array of objects representing output parameters - most values are derived from the output specified (refer to outputs endpoint)
    , "report_dictionary": [
        {
          "data_source": "data_source of output"
        , "data_type": "data_type of output"
        , "label": "label of this output"
        , "object": "object of output"
        , "units": "units type for this output"
        , "variable_name": "variable_name for this output"
        , "uuid": "a unique identifier for this output parameter"
        }
        ...
      ]
      //array of objects representing the analysis functions to be performed on output parameters (entries in the report_dictionary) during simulations
    , "fitness_functions": [
        {
          "fitness_function_type": "type of fitness function to be used (Sum, Maximum, Average, or Minimum)"
        , "label": "human-readable label for this fitness function"
        , "simulated_report_dictionary_uuid": "unique identifier from the report_dictionary array of the output parameter used with this fitness function"
        , "uuid": "a unique identifier for this fitness function"
        }
        ...
      ]
      ...
    }
    ...
  ]
}

Updating model settings

To modify the settings of an Factors model, new JSON is sent through a POST request to

To retrieve the model's settings, make a GET request to /factors/model/[unique model identifier]/settings/update.json. parameters, report_dictionary, and fitness_functions arrays can be updated using this endpoint:

{
  "email": "API user email"
, "token": "API access token"
, "parameters": [] //refer to parameters array from settings read endpoint
, "report_dictionary": [] //refer to report_dictionary array from settings read endpoint
, "fitness_functions": [] //refer to fitness_functions array from settings read endpoint
}

Note that any existing model settings will be overwritten, not updated.


Validating model settings

Factors models can be validated for errors in their settings by making a GET request to /factors/model/[unique model identifier]/calculate.json:

{
  "email": "API user email"
, "token": "API access token"
}

This endpoint will return an error if there is a problem with the model's current settings. If the model's settings are valid, this endpoint will return information on the number of simulations to be run, and user limits for usage with Factors:

{
  "error": "error message if validation error occurred"
, "data": {
    "simulations": total number of simulations that will be run for this model
  , "concurrency": concurrency rate that this model will be simulated at
  , "rate_limit": number of models that can be simulated by this user at once
  , "max_simulations": maximum number of model simulations that can be run by this user (-1 means unlimited)
  , "max_study_simulations": maximum number of simulations this user can run for any model
  }
}

Running model simulation

Once a model has been configured, its simulation can be run by making a POST request to /factors/model/[unique model identifer]/run.json. Since this endpoint involves websocket events, it requires passing a websocket session token along with email and API token for authentication:

{
  "email": "API user email"
, "token": "API access token"
, "websocket": "websocket session token"
}

The HTTP endpoint will return with a JSON response:

{
  "error": "error message (blank if request was successful)"
}

Before queuing the simulation, the model settings will be validated, and if invalid, an error will be return and the simulation will not be run. If the request was successful, the model simulation(s) will be queued and executed in the order received. Note that simulations are queued based on user rate limits and resource availability.

When a simulation completes, a message of stringified JSON will be sent to the websocket client identified by the token supplied in the websocket parameter of the request:

{
  "event": "/factors/study/complete"
, "model_space_uuid": "unique identifier of model (compare to UUID received from HTTP response)"
, "status": {
    "state": "valid or failed (was simulation completed successfully)"
  }
, "message": "if simulation failed, more information is included in this message"
, "results_url": "URL where result file can be accessed (if simulation was valid)"
}

Getting model results

To retrieve the status and any result file URLs for an Factors model, send a GET request to /factors/model/[unique model identifier]/read.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "result_files": [
      "URLs for any result files from completed simulations for this model"
      ...
    ]
  , "status": {
      "state": "valid or failed (was simulation completed successfully)"
    , "message": "if simulation failed, more information is included in this message"
    }
  }
}

Listing model statuses

To retrieve the results and statuses for all Factors models for an user's account, send a GET request to /factors/model/list.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "each model will be listed, by identifier, as a key in this object": {
      "result_files": [
        "URLs for any result files from completed simulations for this model"
        ...
      ]
    , "status": {
        "state": "valid or failed (was simulation completed successfully)"
      , "message": "if simulation failed, more information is included in this message"
      }
    }
    ...
  }
}

Calibrator


Importing model

Importing a model for use with Calibrator involves uploading an IDF and EPW file and listening for websocket events indicating that the model import has completed. The import process involves surveying all possible inputs and outputs to use in configuring Calibrator simulations.

Start by making a POST request to /calibrator/model/create.json. Since this endpoint involves uploading files, requests must be multipart/form-data, including the following:

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="email"

[email address of API user]
--AaB03x
Content-Disposition: form-data; name="token"

[API token of API user]
--AaB03x
Content-Disposition: form-data; name="websocket"

[websocket session token (websocket events for this import will be sent to this socket) ]
--AaB03x
Content-Disposition: form-data; name="idf"; filename="[idf_file_name.idf]"
Content-Type: text/plain

[contents of IDF file (UTF-8 encoded) ]
--AaB03x--
Content-Disposition: form-data; name="epw"; filename="[epw_file_name.epw]"
Content-Type: text/plain

[contents of EPW file (UTF-8 encoded) ]
--AaB03x--

The HTTP endpoint will return with a JSON response:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "model_uuid": "unique identifier assigned to this model"
  }
}

If the request was successful, the model import will be queued and executed in the order received. Note that simulations are queued based on user rate limits and resource availability.

When the import completes, a message of stringified JSON will be sent to the websocket client identified by the token supplied in the websocket parameter of the request:

{
  "event": "/calibrator/model/create/complete"
, "model_space_uuid": "unique identifier of model (compare to UUID received from HTTP response)"
, "status": {
    "state": "valid or failed (was import completed successfully)"
  }
, "message": "if import failed, more information is included in this message"
}

Getting model inputs

After importing model files into Calibrator, your IDF is converted to JSON and valid inputs are identified. These inputs can be used as parameters for your Calibrator simulations of this model. Each input is assigned a unique identifier and includes information needed to use it as a parameter.

To retrieve the JSON of your model's IDF, make a GET request to /calibrator/model/[unique model identifier]/inputs/read.json

{
  "error": "error message (blank if request was successful)"
, "data": {
    //array of IDF objects
    "idf": [
      {
        //array of properties (fields) for IDF object
        "properties": [
          {
            "uuid": "unique identifier for input (needed to use as parameter)"
          , "label": "..."
          , "value": "..."
            ...
          }
          ...
        ]
      }
    ]
    //hash of IDD entries that apply to IDF objects
  , "idd": {
      "IDD object" {
         //array of properties for IDD object
        "properties": [
          {
            "datatype": "..."
          , "default": "..."
          , "label": "..."
          , "units": "..."
            ...
          }
          ...
        ]
      }
    }
  }
}

Getting model outputs

After importing model files into Calibrator, valid EnergyPlus outputs are surveyed and identified. These outputs can be used as parameters for your Calibrator simulations of this model. Each output is assigned a unique identifier and includes information needed to use it as a parameter.

To retrieve the JSON of your model's outputs, make a GET request to /calibrator/model/[unique model identifier]/outputs/read.json

{
  "error": "error message (blank if request was successful)"
, "data": [
    //array of output objects
    {
      "uuid": "unique identifier for output (needed to use as parameter)"
    , "label": "..."
    , "data_source": "..."
    , "data_type": "..."
    , "object": "..."
    , "units": "..."
    , "variable_name": "..."
      ...
    }
    ...
  ]
}

Uploading model measured data

Importing measured data for use with a Calibrator model involves uploading a CSV file.

Make a POST request to /calibrator/model/[identifier of model]/data/upload.json. Since this endpoint involves uploading files, requests must be multipart/form-data, including the following:

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="email"

[email address of API user]
--AaB03x
Content-Disposition: form-data; name="token"

[API token of API user]
--AaB03x
Content-Disposition: form-data; name="websocket"

[measured data file]
--AaB03x
Content-Disposition: form-data; name="data"; filename="[data_file_name.csv]"
Content-Type: text/plain

[contents of measured data file (UTF-8 encoded) ]
--AaB03x--

The HTTP endpoint will return with a JSON response:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "model": "unique identifier of this model"
  , "file": "unique file name assigned to this data file"
  , "path": "full path where file is stored on AWS S3"
  }
}

Getting model measured data

To retrieve the contents of an existing measured data file, make a GET request to /calibrator/model/[unique model identifier]/data/[name of file]/read.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "model": "unique identifier of this model"
  , "file": "unique file name assigned to this data file"
  , "data": "UTF-8 encoded string of file's contents"
  }
}

Listing model measured data files

To retrieve a list of all measured data files associated with a Calibrator model, make a GET request to /calibrator/model/[unique model identifier]/data/list.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "files": [
      "list of all S3 file paths for measured data files"
      ...
    ]
  }
}

Getting model settings

Calibrator models store their settings in a JSON document which can be read and modified using the API. The model settings include input and output parameters, and other information used in running simulations with Calibrator.

To retrieve the model's settings, make a GET request to /calibrator/model/[unique model identifier]/settings/read.json

{
  "error": "error message (blank if request was successful)"
, "data": [
    //JSON document of model settings
    {
      ...
      //array of objects representing input parameters
      "parameters": [
        {
          "dynamic_argument": {
            "min": minimum value to simulate
          , "max": maximum value to simulate
          , "count": number of steps to simulate between min and max
          , "type": "linear"
          }
        , "dynamic_argument_default": default value of input
        , "label": "human-readable label for this parameter"
        , "script_name": "idf_modify_field_on_uuid_target_list"
        , "static_arguments": {
            "targets": [
              "unique identifier for input (refer to inputs endpoint for this value)"
            ]
          }
        , "units": "units type for this input"
        , "uuid": "a unique identifier for this input parameter"
        }
        ...
      ]
      //array of objects representing output parameters and measured data columns - most values are derived from the output specified (refer to outputs endpoint)
    , "report_dictionary": [
        //example of output parameter
        {
          "data_source": "data_source of output"
        , "data_type": "data_type of output"
        , "label": "label of this output"
        , "object": "object of output"
        , "units": "units type for this output"
        , "variable_name": "variable_name for this output"
        , "uuid": "a unique identifier for this output parameter"
        }
        //example of measured data column
      , {
          "data_source": "Sensor"
        , "data_type": "data_type of output"
        , "input_arguments": {
            "data_timestep": "timestep for measured data column"
          }
        , "units": "units type for this output"
        , "uuid": "a unique identifier for this measured data column parameter"
        }
        ...
      ]
      //array of objects representing the analysis functions to be performed on output parameters (entries in the report_dictionary) during simulations
    , "fitness_functions": [
        {
          "fitness_function_type": "type of fitness function to be used (CV-RMSE or MBE)"
        , "label": "human-readable label for this fitness function"
        , "measured_report_dictionary_uuid": "unique identifier from the report_dictionary array of the measured data source used with this fitness function"
        , "simulated_report_dictionary_uuid": "unique identifier from the report_dictionary array of the output parameter used with this fitness function"
        , "uuid": "a unique identifier for this fitness function"
        }
        ...
      ]
    , "measured_data_sources": [
        {
          "first_timestamp": "timestamp for start date of measured data source (YYYY-MM-DD HH:MM - 24-hour time)"
        , "s3_key": "S3 path for measured data file"
        , "timestep": "timestep for measured data source"
        , "data": [
            //array of columns used with this data source
            {
              "data_column": "index of data column (1-based)"
            , "report_dictionary_uuid": "unique identifier of data column from report_dictionary array"
            }
            ...
          ]
        }
        ...
      ]
      ...
    }
    ...
  ]
}

Updating model settings

To modify the settings of an Calibrator model, new JSON is sent through a POST request to

To retrieve the model's settings, make a GET request to /calibrator/model/[unique model identifier]/settings/update.json. parameters, report_dictionary, and fitness_functions arrays can be updated using this endpoint:

{
  "email": "API user email"
, "token": "API access token"
, "parameters": [] //refer to parameters array from settings read endpoint
, "report_dictionary": [] //refer to report_dictionary array from settings read endpoint
, "fitness_functions": [] //refer to fitness_functions array from settings read endpoint
, "measured_data_sources": [] //refer to measured_data_sources array from settings read endpoint
}

Note that any existing model settings will be overwritten, not updated.


Validating model settings

Calibrator models can be validated for errors in their settings by making a GET request to /calibrator/model/[unique model identifier]/calculate.json:

{
  "email": "API user email"
, "token": "API access token"
}

This endpoint will return an error if there is a problem with the model's current settings. If the model's settings are valid, this endpoint will return information on the number of simulations to be run, and user limits for usage with Calibrator:

{
  "error": "error message if validation error occurred"
, "data": {
    "simulations": total number of simulations that will be run for this model
  , "concurrency": concurrency rate that this model will be simulated at
  , "rate_limit": number of models that can be simulated by this user at once
  , "max_simulations": maximum number of model simulations that can be run by this user (-1 means unlimited)
  , "max_study_simulations": maximum number of simulations this user can run for any model
  }
}

Running model simulation

Once a model has been configured, its simulation can be run by making a POST request to /calibrator/model/[unique model identifer]/run.json. Since this endpoint involves websocket events, it requires passing a websocket session token along with email and API token for authentication:

{
  "email": "API user email"
, "token": "API access token"
, "websocket": "websocket session token"
}

The HTTP endpoint will return with a JSON response:

{
  "error": "error message (blank if request was successful)"
}

Before queuing the simulation, the model settings will be validated, and if invalid, an error will be return and the simulation will not be run. If the request was successful, the model simulation(s) will be queued and executed in the order received. Note that simulations are queued based on user rate limits and resource availability.

When a simulation completes, a message of stringified JSON will be sent to the websocket client identified by the token supplied in the websocket parameter of the request:

{
  "event": "/calibrator/study/complete"
, "model_space_uuid": "unique identifier of model (compare to UUID received from HTTP response)"
, "status": {
    "state": "valid or failed (was simulation completed successfully)"
  }
, "message": "if simulation failed, more information is included in this message"
, "results_url": "URL where result file can be accessed (if simulation was valid)"
}

Getting model results

To retrieve the status and any result file URLs for an Calibrator model, send a GET request to /calibrator/model/[unique model identifier]/read.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "result_files": [
      "URLs for any result files from completed simulations for this model"
      ...
    ]
  , "status": {
      "state": "valid or failed (was simulation completed successfully)"
    , "message": "if simulation failed, more information is included in this message"
    }
  }
}

Listing model statuses

To retrieve the results and statuses for all Calibrator models for an user's account, send a GET request to /calibrator/model/list.json. As with all API HTTP requests, email and API token are required for authentication:

{
  "email": "API user email"
, "token": "API access token"
}

JSON response will include:

{
  "error": "error message (blank if request was successful)"
, "data": {
    "each model will be listed, by identifier, as a key in this object": {
      "result_files": [
        "URLs for any result files from completed simulations for this model"
        ...
      ]
    , "status": {
        "state": "valid or failed (was simulation completed successfully)"
      , "message": "if simulation failed, more information is included in this message"
      }
    }
    ...
  }
}