Dataiku API Node User API
-
All API calls will return the following two HTTP headers
DSS-API-Version
: Version of the API handling the requestDSS-Version
: Version of the DSS backend answering the request
Prediction endpoints ¶
Perform a prediction ¶
Perform a predictionPOST/public/api/v1/{serviceId}/{endpointId}/predict
Performs a prediction for a single record.
π Authentication: HTTP Basic
Example URI
- serviceId
string
(required)- endpointId
string
(required)
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": {}
}
}
}
200
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 predictionsPOST/public/api/v1/{serviceId}/{endpointId}/predict-multi
Performs a prediction for several records.
π Authentication: HTTP Basic
Example URI
- serviceId
string
(required)- endpointId
string
(required)
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": {}
}
}
}
200
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 - debugGET/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
- serviceId
string
(required)- endpointId
string
(required)
204
Custom function endpoints ¶
Run a Python function ¶
Run a Python functionGET/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
- serviceId
string
(required) Example: python_svc- endpointId
string
(required) Example: simple_sum- param1
string
(required) Example: 30- param2
string
(required) Example: 12
200
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 functionPOST/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
- serviceId
string
(required) Example: python_svc- endpointId
string
(required) Example: simple_sum
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": {}
}
}
}
200
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 functionGET/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
- 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
200
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 functionPOST/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
- serviceId
string
(required) Example: rstats_svc- endpointId
string
(required) Example: simple_avg
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": {}
}
}
}
200
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 queryGET/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
- serviceId
string
(required) Example: sql_svc- endpointId
string
(required) Example: simple_filter- param1
string
(required) Example: 60- param2
string
(required) Example: female
200
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 queryPOST/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
- serviceId
string
(required) Example: sql_svc- endpointId
string
(required) Example: simple_filter
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": {}
}
}
}
200
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 lookupPOST/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
- serviceId
string
(required) Example: lookup_svc- endpointId
string
(required) Example: passenger_info
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": {}
}
}
}
200
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 lookupsPOST/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
- serviceId
string
(required) Example: lookup_svc- endpointId
string
(required) Example: passenger_info
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": {}
}
}
}
200
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 - debugGET/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
- serviceId
string
(required) Example: lookup_svc- endpointId
string
(required) Example: passenger_info- id_key
string
(required) Example: 42
200
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"
}
}
}