Back to top

Dataiku API Node User API

  • All API calls will return the following two HTTP headers

    • DSS-API-Version: Version of the API handling the request
    • DSS-Version : Version of the DSS backend answering the request

Prediction endpoints

Perform a prediction

Perform a prediction
POST/public/api/v1/{serviceId}/{endpointId}/predict

Performs a prediction for a single record.

🔒 Authentication: HTTP Basic

Example URI

POST /public/api/v1/serviceId/endpointId/predict
URI Parameters
HideShow
serviceId
string (required) 
endpointId
string (required) 
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "features": {
    "customer_id": 2136,
    "transaction_amount": 233.33,
    "payment_type": "CB",
    "user-agent": "Mozilla/5.0 (Chrome)",
    "utm_medium": "campaign"
  },
  "explanations": {
    "enabled": true,
    "method": "ICE",
    "nExplanations": 4
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "features": {
      "type": "object",
      "properties": {}
    },
    "explanations": {
      "type": "object",
      "properties": {}
    },
    "context": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
/* An example for a classification response */
{
    "result" : {
        "prediction" : "FRAUDULENT",
        "probaPercentile" : 94,
        "probas" :{
            "FRAUDULENT" : 0.878,
            "NOT_FRAUDULENT" : 0.122
        },
        "explanations": {
            "transaction_amount" : 0.4849670612000565,
            "payment_type" : -0.30430010095526216,
            "user-agent" : -0.103871964479336,
            "utm_medium" : 0.02356044582554162
        }
    }
}

/* An example for a regression response */
{
    "result" : {
        "prediction" : 12356.23,
        "explanations": {
            "transaction_amount" : 0.4849670612000565,
            "payment_type" : -0.30430010095526216,
            "user-agent" : -0.103871964479336,
            "utm_medium" : 0.02356044582554162
        }
    }
}

/* An example for a multiclass classification response */
{
    "result" : {
        "prediction" : "setosa",
        "probas" :{
            "setosa" : 0.612,
            "versicolor" : 0.541,
            "virginca" : 0.212
        },
        "explanations": {
            "transaction_amount" : 0.4849670612000565,
            "payment_type" : -0.30430010095526216,
            "user-agent" : -0.103871964479336,
            "utm_medium" : 0.02356044582554162
        }
    }
}

/* An example for a failed prediction because an enrich step multi-matched */
{
    "result" : {
        "ignored" : true,
        "ignoreReason" : "MULTIPLE_LOOKUP_MATCHES"
    ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "object",
      "properties": {},
      "description": "Actual prediction result. Contains a \"prediction\""
    },
    "apiContext": {
      "type": "object",
      "properties": {},
      "description": "Various information about the API response"
    },
    "timing": {
      "type": "object",
      "properties": {},
      "description": "Response timing information"
    }
  }
}

Perform multiple predictions

Perform multiple predictions
POST/public/api/v1/{serviceId}/{endpointId}/predict-multi

Performs a prediction for several records.

🔒 Authentication: HTTP Basic

Example URI

POST /public/api/v1/serviceId/endpointId/predict-multi
URI Parameters
HideShow
serviceId
string (required) 
endpointId
string (required) 
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "features": {
        "customer_id": 2136,
        "transaction_amount": 233.33,
        "payment_type": "CB",
        "user-agent": "Mozilla/5.0 (Chrome)",
        "utm_medium": "campaign"
      },
      "context": {
        "frontend_id": 2
      }
    },
    {
      "features": {
        "customer_id": 1235,
        "transaction_amount": 2.17,
        "payment_type": "CB",
        "user-agent": "Mozilla/5.0 (Chrome)",
        "utm_medium": "mailing"
      },
      "context": {
        "frontend_id": 4
      }
    }
  ],
  "explanations": {
    "enabled": false,
    "method": "SHAPLEY",
    "nExplanations": 5,
    "nMonteCarloSteps": 150
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "items": {
      "type": "object",
      "properties": {}
    },
    "explanations": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
/* An example for a classification response */
[
    {
        "results" : [
            {
                "prediction" : "FRAUDULENT",
                "probaPercentile" : 94,
                "probas" :{
                    "FRAUDULENT" : 0.878,
                    "NOT_FRAUDULENT" : 0.122
                },
                "explanations": {
                    "customer_id" : -0.003854188999492303,
                    "transaction_amount" : 0.4849670612000565,
                    "payment_type" : -0.30430010095526216,
                    "user-agent" : -0.103871964479336,
                    "utm_medium" : 0.02356044582554162
                }
            },
            {
                "prediction" : "OK",
                "probaPercentile" : 2,
                "probas" :{
                    "FRAUDULENT" : 0.278,
                    "NOT_FRAUDULENT" : 0.722
                },
                "explanations": {
                    "customer_id" : 0.001639138912371,
                    "transaction_amount" : -0.13039482920565,
                    "payment_type" : -0.10398478902413,
                    "user-agent" : -0.9110034984,
                    "utm_medium" : 0.1348012494203595
                }
            }
        ]
    }
]

/* An example for a regression response */
[
    {
        "results" : [
            {
                "prediction" : 12356.23,
                "explanations": {
                    "customer_id" : 0.001639138912371,
                    "transaction_amount" : -0.13039482920565,
                    "payment_type" : -0.10398478902413,
                    "user-agent" : -0.9110034984,
                    "utm_medium" : 0.1348012494203595
                }
            },
            {
                "prediction" : 2231,
                "explanations": {
                    "customer_id" : -0.003854188999492303,
                    "transaction_amount" : 0.4849670612000565,
                    "payment_type" : -0.30430010095526216,
                    "user-agent" : -0.103871964479336,
                    "utm_medium" : 0.02356044582554162
                }
            }
        ]
    }
]

/* An example for a multiclass classification response */
[
    {
        "results" : [
            {
                "prediction" : "setosa",
                "probas" :{
                    "setosa" : 0.612,
                    "versicolor" : 0.541,
                    "virginca" : 0.212
                },
                "explanations": {
                    "customer_id" : 0.001639138912371,
                    "transaction_amount" : -0.13039482920565,
                    "payment_type" : -0.10398478902413,
                    "user-agent" : -0.9110034984,
                    "utm_medium" : 0.1348012494203595
                }
            },
            {
                "prediction" : "versicolor",
                "probas" :{
                    "setosa" : 0.232,
                    "versicolor" : 0.841,
                    "virginca" : 0.172
                },
                "explanations": {
                    "customer_id" : -0.003854188999492303,
                    "transaction_amount" : 0.4849670612000565,
                    "payment_type" : -0.30430010095526216,
                    "user-agent" : -0.103871964479336,
                    "utm_medium" : 0.02356044582554162
                }
            }
        ]
    }
]

/* An example for a partially failed prediction because an enrich step multi-matched */
[
    {
        "results" : [
            {
                "ignored" : true,
                "ignoreReason" : "MULTIPLE_LOOKUP_MATCHES"
            },
            {
                "prediction" : 21237
            }
        ]
    }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "results": {
      "description": "One entry for each record to predict"
    },
    "apiContext": {
      "type": "object",
      "properties": {},
      "description": "Various information about the API response"
    },
    "timing": {
      "type": "object",
      "properties": {},
      "description": "Response timing information"
    }
  }
}

Perform a prediction - debug

Perform a prediction - debug
GET/public/api/v1/{serviceId}/{endpointId}/predict-simple

Debug endpoint to make predictions about a single record.

Each query parameter will be used as a feature.

Answers are the same as the “/predict” call

🔒 Authentication: HTTP Basic

Example URI

GET /public/api/v1/serviceId/endpointId/predict-simple
URI Parameters
HideShow
serviceId
string (required) 
endpointId
string (required) 
Response  204

Custom function endpoints

Run a Python function

Run a Python function
GET/public/api/v1/{serviceId}/{endpointId}/run/{?param1}{?param2}

Note: equivalent results can be achieved by using the POST method.

Call a user-defined Python function and specify its arguments as the parameters of the API call. The endpoint will return the results of that function.

Example of exposed function:

def api_py_function(param1, param2):
    
    answer = param1 + param2
    return answer

Important:

  • This example is from a Python function that requires 2 arguments, but any number of argument can be passed.

  • The names of the parameters that are sent by the API call must strictly match the Python function signature.

🔒 Authentication: HTTP Basic

Example URI

GET /public/api/v1/python_svc/simple_sum/run/?param1=30?param2=12
URI Parameters
HideShow
serviceId
string (required) Example: python_svc
endpointId
string (required) Example: simple_sum
param1
string (required) Example: 30
param2
string (required) Example: 12
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "response": 42,
  "timing": {
    "preProcessing": 0,
    "wait": 198,
    "execution": 14858,
    "functionInternal": 185
  },
  "apiContext": {
    "serviceId": "python_svc",
    "endpointId": "simple_sum",
    "serviceGeneration": "v1"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {},
      "description": "Output of the function to be executed"
    },
    "apiContext": {
      "type": "object",
      "properties": {},
      "description": "Various information about the API response"
    },
    "timing": {
      "type": "object",
      "properties": {},
      "description": "Response timing information"
    }
  }
}

Run a Python function

Run a Python function
POST/public/api/v1/{serviceId}/{endpointId}/run

Note: equivalent results can be achieved by using the GET method.

Call a user-defined Python function and specify its arguments as the input payload of the API call. The endpoint will return the results of that function.

Example of exposed function:

def api_py_function(param1, param2):

    answer = param1 + param2
    return answer

Important:

  • This example is from a Python function that requires 2 arguments, but any number of argument can be passed.

  • The names of the parameters that are sent by the API call must strictly match the Python function signature.

🔒 Authentication: HTTP Basic

Example URI

POST /public/api/v1/python_svc/simple_sum/run
URI Parameters
HideShow
serviceId
string (required) Example: python_svc
endpointId
string (required) Example: simple_sum
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "param1": 30,
  "param2": 12
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "param1": {
      "type": "object",
      "properties": {}
    },
    "param2": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "response": 42,
  "timing": {
    "preProcessing": 0,
    "wait": 207,
    "execution": 2924,
    "functionInternal": 9
  },
  "apiContext": {
    "serviceId": "python_svc",
    "endpointId": "simple_sum",
    "serviceGeneration": "v1"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {},
      "description": "Output of the function to be executed"
    },
    "apiContext": {
      "type": "object",
      "properties": {},
      "description": "Various information about the API response"
    },
    "timing": {
      "type": "object",
      "properties": {},
      "description": "Response timing information"
    }
  }
}

Run a R function

Run a R function
GET/public/api/v1/{serviceId}/{endpointId}/run/{?param1}{?param2}{?param3}

Note: equivalent results can be achieved by using the POST method.

Call a user-defined R function and specify its arguments as the parameters of the API call. The endpoint will return the results of that function.

Example of exposed function:

api_r_function <- function(param1, param2, param3){
    mean(as.integer(param1), as.integer(param2), as.integer(param3))
}

Important:

  • This example is from an R function that requires 3 arguments, but any number of argument can be passed.

  • The names of the parameters that are sent by the API call must strictly match the R function signature.

🔒 Authentication: HTTP Basic

Example URI

GET /public/api/v1/rstats_svc/simple_avg/run/?param1=100?param2=20?param3=6
URI Parameters
HideShow
serviceId
string (required) Example: rstats_svc
endpointId
string (required) Example: simple_avg
param1
string (required) Example: 100
param2
string (required) Example: 20
param3
string (required) Example: 6
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "response": 42,
  "timing": {
    "preProcessing": 0,
    "wait": 422191,
    "execution": 38810,
    "functionInternal": 0
  },
  "apiContext": {
    "serviceId": "rstats_svc",
    "endpointId": "simple_avg",
    "serviceGeneration": "v1"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {},
      "description": "Output of the function to be executed"
    },
    "apiContext": {
      "type": "object",
      "properties": {},
      "description": "Various information about the API response"
    },
    "timing": {
      "type": "object",
      "properties": {},
      "description": "Response timing information"
    }
  }
}

Run a R function

Run a R function
POST/public/api/v1/{serviceId}/{endpointId}/run

Note: equivalent results can be achieved by using the GET method.

Call a user-defined R function and specify its arguments as the input payload of the API call. The endpoint will return the results of that function.

Example of exposed function:

api_r_function <- function(param1, param2, param3){
    mean(as.integer(param1), as.integer(param2), as.integer(param3))
}

Important:

  • This example is from an R function that requires 3 arguments, but any number of argument can be passed.

  • The names of the parameters that are sent by the API call must strictly match the R function signature.

🔒 Authentication: HTTP Basic

Example URI

POST /public/api/v1/rstats_svc/simple_avg/run
URI Parameters
HideShow
serviceId
string (required) Example: rstats_svc
endpointId
string (required) Example: simple_avg
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "param1": 100,
  "param2": 20,
  "param3": 6
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "param1": {
      "type": "object",
      "properties": {}
    },
    "param2": {
      "type": "object",
      "properties": {}
    },
    "param3": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "response": 42,
  "timing": {
    "preProcessing": 0,
    "wait": 207,
    "execution": 2924,
    "functionInternal": 9
  },
  "apiContext": {
    "serviceId": "python_svc",
    "endpointId": "simple_sum",
    "serviceGeneration": "v1"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {},
      "description": "Output of the function to be executed"
    },
    "apiContext": {
      "type": "object",
      "properties": {},
      "description": "Various information about the API response"
    },
    "timing": {
      "type": "object",
      "properties": {},
      "description": "Response timing information"
    }
  }
}

SQL endpoints

Perform a SQL query

Perform a SQL query
GET/public/api/v1/{serviceId}/{endpointId}/query/{?param1}{?param2}

Note: equivalent results can be achieved by using the POST method.

Execute a parametrized SQL query after specifying the parameters in the URI of the API call.

The endpoint will return the results of that query.

Important:

  • This example is from a SQL query that contains 2 parameters, but any number of parameters can be passed.

  • Please make sure that the connection linking the target database has been properly specified in your endpoint settings.

Example of exposed SQL query:

SELECT
  "PassengerId",
  "Name",
  "Age",
  "Survived"
FROM "DB_titanic_table" AS "t"
WHERE "t"."Age" > ? AND "t"."Sex" = ?

🔒 Authentication: HTTP Basic

Example URI

GET /public/api/v1/sql_svc/simple_filter/query/?param1=60?param2=female
URI Parameters
HideShow
serviceId
string (required) Example: sql_svc
endpointId
string (required) Example: simple_filter
param1
string (required) Example: 60
param2
string (required) Example: female
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "results": [
    {
      "columns": [
        {
          "name": "PassengerId",
          "type": "int8"
        },
        {
          "name": "Name",
          "type": "text"
        },
        {
          "name": "Age",
          "type": "float8"
        },
        {
          "name": "Survived",
          "type": "int8"
        }
      ],
      "rows": [
        [
          "276",
          "Andrews, Miss. Kornelia Theodosia",
          "63.0",
          "1"
        ],
        [
          "484",
          "Turkula, Mrs. (Hedwig)",
          "63.0",
          "1"
        ],
        [
          "830",
          "Stone, Mrs. George Nelson (Martha Evelyn)",
          "62.0",
          "1"
        ]
      ],
      "updatedRows": 0
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "results": {
      "type": "object",
      "properties": {},
      "description": "Query results"
    }
  }
}

Perform a SQL query

Perform a SQL query
POST/public/api/v1/{serviceId}/{endpointId}/query

Note: equivalent results can be achieved by using the GET method.

Execute a parametrized SQL query after specifying the parameters in the body of the API call.

The endpoint will return the results of that query.

Important:

  • This example is from a SQL query that contains 2 parameters, but any number of parameters can be passed.

  • Please make sure that the connection linking the target database has been properly specified in your endpoint settings.

Example of exposed SQL query:

SELECT
  "PassengerId",
  "Name",
  "Age",
  "Survived"
FROM "DB_titanic_table" AS "t"
WHERE "t"."Age" > ? AND "t"."Sex" = ?

🔒 Authentication: HTTP Basic

Example URI

POST /public/api/v1/sql_svc/simple_filter/query
URI Parameters
HideShow
serviceId
string (required) Example: sql_svc
endpointId
string (required) Example: simple_filter
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "param1": 60,
  "param2": "female"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "param1": {
      "type": "object",
      "properties": {}
    },
    "param2": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "results": [
    {
      "columns": [
        {
          "name": "PassengerId",
          "type": "int8"
        },
        {
          "name": "Name",
          "type": "text"
        },
        {
          "name": "Age",
          "type": "float8"
        },
        {
          "name": "Survived",
          "type": "int8"
        }
      ],
      "rows": [
        [
          "276",
          "Andrews, Miss. Kornelia Theodosia",
          "63.0",
          "1"
        ],
        [
          "484",
          "Turkula, Mrs. (Hedwig)",
          "63.0",
          "1"
        ],
        [
          "830",
          "Stone, Mrs. George Nelson (Martha Evelyn)",
          "62.0",
          "1"
        ]
      ],
      "updatedRows": 0
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "results": {
      "type": "object",
      "properties": {},
      "description": "Query results"
    }
  }
}

Dataset lookup endpoints

Perform a lookup

Perform a lookup
POST/public/api/v1/{serviceId}/{endpointId}/lookup

Search a record inside a managed dataset by looking it up using lookup keys.

The endpoint will return the values corresponding to the matching input lookup keys. The choice of values to return is defined by the user when setting up the endpoint.

Important: The API call cannot return more than one dataset line. In case of multiple matches, when setting up the endpoint the user can choose to either keep the first result, return an empty payload, or raise an error.

🔒 Authentication: HTTP Basic

Example URI

POST /public/api/v1/lookup_svc/passenger_info/lookup
URI Parameters
HideShow
serviceId
string (required) Example: lookup_svc
endpointId
string (required) Example: passenger_info
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "PassengerId": 42
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "results": [
    {
      "data": {
        "PassengerId": "42",
        "Name": "Turpin, Mrs. William John Robert (Dorothy Ann Wonnacott)",
        "Age": 27,
        "Fare": 21
      },
      "ignored": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "results": {
      "type": "object",
      "properties": {},
      "description": "Query results"
    }
  }
}

Perform multiple lookups

Perform multiple lookups
POST/public/api/v1/{serviceId}/{endpointId}/lookup-multi

Search multiple records inside a managed dataset by looking it up using lookup keys.

The endpoint will return a list of results corresponding to the matching input lookup keys. The choice of values to return is defined by the user when setting up the endpoint.

Important: For each input record, the API call cannot return more than one dataset line. In case of multiple matches, when setting up the endpoint the user can choose to either keep the first result, return an empty payload, or raise an error.

🔒 Authentication: HTTP Basic

Example URI

POST /public/api/v1/lookup_svc/passenger_info/lookup-multi
URI Parameters
HideShow
serviceId
string (required) Example: lookup_svc
endpointId
string (required) Example: passenger_info
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "data": {
        "id_key": 42
      }
    },
    {
      "data": {
        "id_key": 24
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "results": [
    {
      "data": {
        "id_key": "42",
        "Name": "Turpin, Mrs. William John Robert (Dorothy Ann Wonnacott)",
        "Age": 27,
        "Fare": 21
      },
      "ignored": false
    },
    {
      "data": {
        "id_key": "24",
        "Name": "Sloper, Mr. William Thompson",
        "Age": 28,
        "Fare": 35.5
      },
      "ignored": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "results": {
      "type": "object",
      "properties": {},
      "description": "Query results"
    }
  }
}

Perform a lookup - debug

Perform a lookup - debug
GET/public/api/v1/{serviceId}/{endpointId}/lookup-simple{?id_key}

Debug endpoint to perform dataset lookups on a single record.

Each query parameter will be used as an input lookup key.

Answers are the same as the “/lookup” call.

Important: the number of parameters must be equal to the number of keys required to perform the lookup (as defined when building the endpoint). In this example there is only one key (id_key).

🔒 Authentication: HTTP Basic

Example URI

GET /public/api/v1/lookup_svc/passenger_info/lookup-simple?id_key=42
URI Parameters
HideShow
serviceId
string (required) Example: lookup_svc
endpointId
string (required) Example: passenger_info
id_key
string (required) Example: 42
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "results": [
    {
      "data": {
        "PassengerId": "42",
        "Name": "Turpin, Mrs. William John Robert (Dorothy Ann Wonnacott)",
        "Age": 27,
        "Fare": 21
      },
      "ignored": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "results": {
      "type": "object",
      "properties": {},
      "description": "Query results"
    }
  }
}

Generated by aglio on 23 May 2023