The instructions below target software developers familiar with API interfaces.
Introduction
The API allows Plutocalc Designer to be connected with other tools like spreadsheets, optimization models or databases.
Plutocalc Designer backend uses an HTTP interface that outputs data to users based on GET and POST commands.
The input/output data format follows JSON standard for data collections and UTF-8 text for errors, notes and warnings.
OpenAPI
Plutocalc Designer API is compatible with OpenAPI 3.0.3 standard. The descriptor can be found in the address below.
https://www.plutocalc.com/designer/server/openapi.json
Request format
Only two parameters are required to exchange data with the server, the model and the command.
Server URL format:
https://www.plutocalc.com/designer/server/[MODEL]/[COMMAND]
Where:
[BASE_URL]:
https://www.plutocalc.com/designer/server/
[MODEL]: Plutocalc Designer computation model internal name/id. The complete list can be extracted using the command
listmodels. Examples:
- cmasbod
- cmasbodnh4
- cmasbodno3
- mbrbodnh4
- mbrbodno3
- stripping
- rocip
[COMMAND]: Command used to request a response from the server.
Mandatory POST headers:
Content-type: application/json
Response headers can be either
Content-type: application/json
for data packages or
Content-type: text/html
for errors, warnings and information.
Command reference
| Command | Type | Input | Output | Description |
|---|
BASE_URL/ | GET | - | application/json | Server name and version |
BASE_URL/status | GET | - | text/html | Server operational status (normal is "Online") |
BASE_URL/license/status | POST | {"license_key": "YOUR_KEY"} | application/json | Outputs the credits balance. It will return zero if the license key is invalid. |
BASE_URL/listmodels | GET | - | application/json | List the available models using internal names (also referred as "id"). |
BASE_URL/listmodelsinfo | GET | - | application/json | List the all the available models with the respective detailed information sheet: id, name, short name, version, description and links to the manuals. This is the best starting point for MCP or automated systems. |
BASE_URL/MODEL | GET | - | text/html | Model name and version. "MODEL" is the "id" from listmodels or listmodelsinfo |
BASE_URL/MODEL/information | GET | - | application/json | Model detailed information. Same as listmodelsinfo, but for a specific model. |
BASE_URL/MODEL/template | GET | - | application/json | Model template. Use this exact JSON structure as the body input for the compute command. User is allowed to modify "val" and "unit" fields. |
BASE_URL/MODEL/jsontomarkdown | POST | JSON template for the specific model | application/json | Converts the machine readable template (JSON object) to a human readable text with Markdown markup. The API cannot accept text format for the calculations, therefore, after any change, it must be converted back with markdowntojson before using the compute command. This command can also be used to validate the JSON object format. |
BASE_URL/MODEL/markdowntojson | POST | {"text": "stringified_markdown_template"} | application/json | Converts the human readable template from text / markdown format to the JSON object template required for the compute action. |
BASE_URL/MODEL/referencedb | GET | - | application/json | List reference databases (example: chemical compounds). Databases are used to fill "type":"index" fields. For every database record, there is an associated index. The name of the database the field is referring to is in the "db" key. |
BASE_URL/MODEL/unitslist | GET | - | application/json | Supported units for conversions. If the unit is not listed here, it can't be used in the templates. |
BASE_URL/MODEL/compute | POST | JSON template for the specific model | application/json | Performs the calculation, outputs a JSON with the inputs, results and status messages |
Typical use sequence
- Get BASEURL/listmodelsinfo. Look for the desired calculation model, read the manual using the provided URL, take a note of the model "id".
- Get BASEURL/MODEL/unitslist (MODEL is replaced by the "id" from step 1). This will return the units supported by the model. Units are identified with the key "unit" in the templates. User is allowed to change units if the destination unit is supported.
- Get BASEURL/MODEL/referencedb (MODEL is replaced by the "id" from step 1). This will output reference databases used by the model. Every database entry has an index that is used to fill "index" type fields in the template.
- Get BASEURL/MODEL/template (MODEL is replaced by the "id" from step 1). This returns the template that should be filled by the user. Every model requires a different template, templates can change when the model is updated to a newer version.
- Fill the template. Fields with mode "input" are considered inputs and should be filled by the user, mode "output" are for computation results. Mode "context" fields can be either inputs or outputs, depending on their initial values or other field values.
"index" type fields need to be filled with a database index. The database to be used can be found in the key "db".
The template defaults tend to be the most common constants, parameters or settings for that specific model. If you don't know where to get the values, consider using the defaults.
"unit" type fields can also be changed by the user to the preferred unit from the units list. If the user alters the unit of an output field, the computation result will be automatically converted to the unit previously set.
- Post the filled template at BASEURL/MODEL/compute (MODEL is replaced by the "id" from step 1). This should return the processed template filled with the calculation results or errors. A list of errors will be at the end of the returned template.
- Repeat steps 5 and 6 until the desired final design.
Template validation
Supported field types and required keys for each type
- header: id, key, label
- section: id, key, label
- label: id, key, label
- footer: id, key, label
- scalar: id, key, mode, label, val (number), unit (no spaces)
- index: id, key, mode, label, db (string), val (positive integer, 0, or -1)
- number: id, key, mode, label, val (number)
- list: id, key, mode, label, val (array)
- boolean: id, key, mode, label, val (0 or 1)
- string: id, key, mode, label, val (string)
Validation rules applied to all types of fields
- 'id', 'key', and 'label' are required for all types
- 'key' must contain only letters, numbers, dashes, and underscores
- 'key' property value MUST match the object property name (case-sensitive)
- 'unit' field (when required) cannot contain spaces
- 'val' field type must match the specified variable type restrictions
- 'db' field (for index type) must be a non-empty string
- 'mode' value must be one of: "context", "input", "output"
License keys
If required, a license key must be included in the appropriate field of the input JSON structure. Credits will be used as they would in a normal calculation from the user interface. We recommend using HTTPS request to prevent key leak. For input/output testing purposes use any text string as key, the backend will answer with the properly formatted response, except of the calculation results.
Abuse prevention
The backend server has embed algorithms that detect abuses in several levels and block the API usage. The threshold limits depend on the IP origin, license key, external abuse prevention lists and other factors. If you believe your requests were blocked by mistake please
contact us.