Introduction

Welcome to the UP2TOM API! The UP2TOM API functionality has been developed to support the integration between third party applications and TOM models.

The UP2TOM API is a REST API that provides programmatic access to TOM models. The UP2TOM API identifies users with authorization tokens. All endpoints are authenticated. All requests made to the UP2TOM API must be using SSL. All requests and responses use Content-Type: application/json.

There are language examples for curl, Python and jQuery. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, use this code:

# With curl, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Token <key>"

import requests

headers = { 'Authorization': 'Token <key>' }
r = requests.get('api_endpoint_here', headers=headers)

$.ajaxSetup({
  headers: { 'Authorization': 'Token <key>' }
});

Make sure to replace <key> with your API key.

UP2TOM uses API keys to provide authentication and identification. An API key is linked to a collection of models. Please contact our support team to obtain an API key.

UP2TOM expects the API key to be included in all requests using the header:

Authorization: Token <key>

For testing and experimentation, the API can be used with the demo key 9307bfd5fa011428ff198bb37547f979. In which case the following authorization header can be used:

Authorization: Token 9307bfd5fa011428ff198bb37547f979

You must replace <key> with your personal API key.

Models

Get all the Models linked to the API key.

curl "https://api.up2tom.com/v2/models"
  -H "Authorization: Token <key>"

import requests

headers = { 'Authorization': 'Token <key>' }
r = requests.get('https://api.up2tom.com/v2/models', headers=headers)

$.ajaxSetup({
  headers: { 'Authorization': 'Token <key>' }
});
$.get({
  url: 'https://api.up2tom.com/v2/models'
});

The above command returns JSON structured like this:

{
  "models": [
    {
      "id": "abcd1234abcd1234abcd1234",
      "name": "Demo",
      "description": "A demo model",
      "publish_date": "2017-01-12T01:25:22.335Z",
      "created_by": "User 1"
    },
    {
      "id": "5678abcd5678abcd5678abcd5678",
      "name": "Demo 2",
      "description": "Another demo model",
      "publish_date": "2017-01-18T09:15:22.000Z",
      "created_by": "User 2"
    },
    {
      "id": "9123abcd9123abcd9123abcd9123",
      "name": "Demo 3",
      "description": "The last demo model",
      "publish_date": "2017-01-18T13:55:11.000Z",
      "created_by": "User 3"
    }
  ]
}

This endpoint returns summarized information about all the models linked to the API key.

HTTP Request

GET https://api.up2tom.com/v2/models

HTTP Responses

Status Code	Description
200	Success
401	Missing or bad API key
403	API Key is not in use or has been disabled
405	Method not allowed (POST)
503	Service is currently unavailable

Get a Specific Model

curl "https://api.up2tom.com/v2/models/<ID>"
  -H "Authorization: Token <key>"

import requests

headers = { 'Authorization': 'Token <key>' }
r = requests.get('https://api.up2tom.com/v2/models/<ID>', headers=headers)

$.ajaxSetup({
  headers: { 'Authorization': 'Token <key>' }
});
$.get({
  url: 'https://api.up2tom.com/v2/models/<ID>'
});

The above command returns JSON structured like this:

[
  {
    "id": "abcd1234abcd1234abcd1234",
    "name": "Demo",
    "description": "A demo model",
    "measurements": {
      "levers": [{
          "index": 0,
          "drop": 0.25
      }, {
          "index": 1,
          "drop": 0.75
      }]
    },
    "metadata": {
      "prediction": {
        "_cls": "Nominal",
        "name": "outcome",
        "question": "Is the patient old?",
        "domain": {
          "_cls": "DomainC",
          "values": ["Yes", "No"]
        }
      },
      "attributes": [{
        "_cls": "Nominal",
        "name": "INPUTVAR1",
        "question": "Age?",
        "domain": {
          "_cls": "DomainR",
          "lower": 0,
          "upper": 80,
          "interval": 1
        }
      }, {
        "_cls": "Continous",
        "name": "INPUTVAR2",
        "question": "Gender?",
        "domain": {
          "_cls": "DomainC",
          "values": ["Male", "Female"]
        }
      }]
    },
    "exclusions": [{
      "_cls": "ValueEx",
      "antecedent": {
        "_cls": "LTEQ",
        "index": 0,
        "threshold": 20
      },
      "consequent": {
        "_cls": "EQ",
        "index": 1,
        "threshold": "Yes"
      }
    }, {
      "_cls": "BlatantEx",
      "antecedent": {
        "_cls": "LTEQ",
        "index": 0,
        "threshold": 10
      },
      "consequent": {
        "value": "No"
      }
    }]
  }
]

This endpoint retrieves a model specification based on the model ID.

HTTP Request

GET https://api.up2tom.com/v2/models/<ID>

URL Parameters

Parameter	Description
ID	The ID of the model specification to retrieve

HTTP Responses

Status Code	Description
200	Success
400	Bad model ID
401	Missing or bad API key
403	No access to model with the specified ID.
403	API Key is not in use or has been disabled
405	Method not allowed (POST)
503	Service is currently unavailable

Decision

Make a decision with a specific model.

curl -X POST -d "{ data }" "https://api.up2tom.com/v2/decision/<ID>"
  -H "Authorization: Token <key>"
  -H "Content-Type: application/json"

import requests

headers = { 'Authorization': 'Token <key>' }
r = requests.post('https://api.up2tom.com/v2/decision/<ID>', json=data, headers=headers)
r.json()
# { "decision": "Yes", "meets_confidence": false }

$.ajaxSetup({
  headers: { 'Authorization': 'Token <key>' }
});
$.post({
  url: 'https://api.up2tom.com/v2/decision/<ID>',
  data: JSON.stringify(data),
  contentType: 'application/json'
});

The above command receives JSON structured like this:

{
  "INPUTVAR1": 1.0,
  "INPUTVAR2": "Yes",
  "INPUTVAR3": "Green",
  "INPUTVAR4": 4.0
}

and returns JSON structured like this:

{
  "input": {
    "INPUTVAR1": 1.0,
    "INPUTVAR2": "Yes",
    "INPUTVAR3": "Green",
    "INPUTVAR4": 4.0
  },
  "decision": "Yes",
  "meets_confidence": false
}

This endpoint returns a decision using a specific model and an input scenario.

HTTP Request

POST https://api.up2tom.com/v2/decision/<ID>

URL Parameters

Parameter	Description
ID	The ID of the model

Body Parameters

See the code sample to the right.

HTTP Responses

Status Code	Description
200	Success
400	Bad model ID
401	Missing or bad API key
403	API Key is not in use or has been disabled
403	No access to model with the specified ID
422	Invalid input. See error detail
405	Method not allowed (GET)
503	Service is currently unavailable

Schema

The UP2TOM API exposes several different data structures that provide information about the model. In order to gain a better understanding, each component is described here from the top down.

Component	Description
Model	A container for all the properties of the model
Metadata	A description of the input variables and model outcomes
Attribute	A specification for an individual input variable or outcome
Domain	Range of possible values for an input variable or outcome
Exclusion Rules	Rules that reduce the possible set of input or rules that enforce an automatic outcome
Relation	A relationship restriction between two variables or between a variable and a value
Result	An outcome
Measurements	Technical information about the model

Model

Brief Model Description

{
  "title": "Brief Model Description",
  "type": "object",
  "properties": {
    "id": "string",
    "name": "string",
    "description": "string",
    "created_by": "string",
    "publish_date": "date"
  }
}

Full Model Description

{
  "title": "Full Model Description",
  "type": "object",
  "properties": {
    "id": "string",
    "name": "string",
    "description": "string",
    "created_by": "string",
    "publish_date": "date",
    "metadata": { "$ref": "#/definitions/Metadata" },
    "exclusions": { "$ref": "#/definitions/Exclusions" },
    "measurements": { "$ref": "#/definitions/Measurements" }
  }
}

The UP2TOM API uses two different model schemas; a brief description and a full description. When querying for a list of models, a brief description for each model is returned. The full description is returned when querying a specific model.

Brief Model Description

The brief model description contains the following properties:

Property	Description
id	A unique 24 character hex string
name	The name of the model
description	A description of the model
created_by	The username of the model creator
publish_date	The date the model was last updated

Full Model Description

The full model description contains the above properties as well as the following:

Property	Description
metadata	Metadata describing the input variables and outcomes
exclusions	Exclusions rules
measurements	Technical information about the model

Metadata

{
  "title": "Metadata",
  "type": "object",
  "properties": {
    "attributes": {
      "type": "array",
      "items": { "$ref": "#/definitions/Attribute" }
    },
    "prediction": { "$ref": "#/definitions/Attribute" }
  }
}

Metadata specifies the input variables and outcomes for the model. Each model has multiple input variables and a decision variable which contains several possible outcomes.

The Metadata object contains the following properties:

Property	Description
attributes	A list of `Attribute`s describing the input variables
prediction	A single `Attribute` describing the model outcomes

Attribute

{
  "title": "Attribute",
  "type": "object",
  "properties": {
    "type": "string",
    "name": "string",
    "question": "string",
    "domain": { "$ref": "#/definitions/Domain" }
  }
}

An attribute is a description of a single input or decision variable. Each attribute in a model has a unique name and a question. Additionally, each attribute is constrained by a domain.

The Attribute object contains the following properties:

Property	Description
type	The type of attribute, either `Nominal` or `Continuous`
name	The name of the attribute, e.g. `INPUTVAR1`
question	The question that is presented during simulation
domain	The domain of the attribute

Attributes belong to one of three different types, each describing the type of input variable.

Continuous

An attribute for a numeric input.

Nominal

An attribute for a collection of possible text values.

Ordinal

An attribute for a collection of possible text values where the order of the values is important, e.g. low, medium, high.

Domain

The Domain object is an important component that defines the types of the input and decision variables. The domain is used during the simulation process to ensure that only feasible scenarios are generated. Additionally, the domain is used during the decision process by validating each input scenario. E.g. the lower and upper bounds for each continuous variable are checked when making a decision.

Continuous Domain

Continuous Domain

{
  "title": "Continuous Domain",
  "type": "object",
  "properties": {
    "type": "string",
    "lower": "number",
    "upper": "number",
    "interval": "number",
    "discrete": "boolean"
  }
}

The Continuous Domain object describes a numeric variable and contains the following properties:

Property	Description
type	The type of domain, in this case `DomainR`
lower	The lower bound (inclusive) of the variable. An input must be greater than or equal to this
upper	The upper bound (inclusive) of the variable. An input must be less than or equal to this
interval	The step of the variable used in simulation. This value can be used to restrict possible inputs but is not validated during the decision process
discrete	Whether or not this variable describes a whole number

Categorical Domain

Categorical Domain

{
  "title": "Categorical Domain",
  "type": "object",
  "properties": {
    "type": "string",
    "values": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

The Categorical Domain object describes a variable with multiple text outcomes and contains the following properties:

Property	Description
type	The type of domain, in this case `DomainC`
values	A list of possible string values for this variable

Relation

{
  "title": "Relation",
  "type": "object",
  "properties": {
    "type": "string",
    "index": "integer",
    "threshold": "number"
  }
}

A relation describes a relationship between two variables or a relationship between a variable and a value. The different types of Relations correspond to different operators:

Type	Operator
LTEQ	≤
GT	>
EQ	=
NEQ	≠

The Relation object contains the following properties:

Property	Description
type	The type of `Relation`. Possible types of relations include `LTEQ`, `GT`, `EQ` and `NEQ`
index	An integer index of an `Attribute` in the `Metadata`
threshold	A value to be compared against, either a number or text depending on the relation type

Result

{
  "title": "Class Result",
  "type": "object",
  "properties": {
    "type": "string",
    "value": "string"
  }
}

UP2TOM uses results to store the outcome of a decision. Currently, only text outcomes are allowed. These results are termed Class Results.

The Result object contains the following properties:

Property	Description
type	The type of result, in this case `ClassRes`
value	A single text value representing a model outcome

Exclusion Rules

Exclusion rules are powerful components used to either restrict the feasibility of input scenarios or as a way to short-circuit the decision making process by immediately returning a user-defined outcome. Exclusion rules make use of Relations to describe the relationships between variables or between a variable and an outcome.

Value Exclusion

Value Exclusion

{
  "title": "Value Exclusion",
  "type": "object",
  "properties": {
    "type": "string",
    "antecedent": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Relation"
      }
    },
    "consequent": {
      "type": "array",
      "items": { "$ref": "#/definitions/Relation" }
    }
  }
}

A value exclusion describes an IF -> THEN rule. The Relations in the antecedent form a compound IF A AND B AND C statement. The Relations in the consequent form a compound THEN X AND Y AND Z statement. In other words, an input scenario is satisfied by a value exclusion if all of the relations in the antecedent and all of the relations in the consequent are satisfied.

The Value Exclusion object contains the following properties:

Property	Description
type	The type of exclusion rule, in this case `ValueEx`
antecedent	A list of `Relation`s that form the IF statement
consequent	A list of `Relation`s that form the THEN statement

Relationship Exclusion

Relationship Exclusion

{
  "title": "Relationship Exclusion",
  "type": "object",
  "properties": {
    "type": "string",
    "relation": { "$ref": "#/definitions/Relation" }
  }
}

A relationship exclusion describes a MUST BE rule. The type of the Relation specifies the operator of the rule, i.e. ≤ or>. The index of the Relation describes the Attribute on the left side of the operator. The threshold is used as an index to describe the Attribute on the right side of the operator. This builds a rule in the form A MUST BE ≤ or A MUST BE > B.

The Relationship Exclusion object contains the following properties:

Property	Description
type	The type of exclusion rule, in this case `RelationshipEx`
relation	A `Relation` between two variables

Blatant Exclusion

Blatant Exclusion

{
  "title": "Blatant Exclusion",
  "type": "object",
  "properties": {
    "type": "string",
    "antecedent": { "$ref": "#/definitions/Relation" },
    "consequent": { "$ref": "#/definitions/Result" }
  }
}

A blatant exclusion describes an IF A -> THEN RESULT IS B rule. It is used to produce an automatic decision before querying the model. The antecedent describes a single IF rule. If the antecedent is satisfied, the decision is set to the value stored in the result.

A Blatant Exclusion contains the following properties:

Property	Description
type	The type of exclusion rule, in this case `BlatantEx`
antecedent	A `Relation` for a single IF rule
consequent	A `Result` for the THEN rule

Measurements

{
  "title": "Measurements",
  "type": "object",
  "properties": {
    "levers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": "integer",
          "drop": "number"
        }
      }
    }
  }
}

The measurements object contains the levers (variable importance) for the model. Each lever is described using an index (of the variable in the Metadata), and a drop in percentage. The drop in percentage is an estimate of how important a variable is with higher values indicating more importance and lower values indicating less importance.

The Measurement object contains the following properties:

Property	Description
levers	A list of levers describing the importance of each input variable